Skip to content

Standard 106: Capability Architecture & MRI Pipeline

Status: Active (Jan 2026) Owner: Architecture Guild Tooling: inject_dye.ts, perform_mri.ts

1. The Core Principle: "Code-First Authority"

We do not write documentation to describe what we intend to build. We write code with Capability Tags (@cap), and we let the MRI Pipeline generate the documentation of what actually exists.

Rule 106.1: If a capability is not tagged in the code with @cap, it does not exist in the official architecture.

2. The Golden Data Hierarchy

A. The Data Layer (The Storage)

These JSON files are the authoritative records of the system.

  • As-Built Storage: generated/capabilities.json
  • Role: The computed state of the codebase.
  • Origin: Auto-generated by perform_mri.ts (The Scanner).
  • To-Be Storage: generated/future_capabilities.json
  • Role: The planned state of the codebase.
  • Origin: Manual entry (The Backlog).

B. The Presentation Layer (The View)

  • Capability Matrix: documentation/06_CAPABILITY_MATRIX.md
  • Role: A human-readable report rendered from the Data Layer.
  • Logic: Uses rendering logic ported from scripts/architect/index-capabilities.ts.
  • Status: ReadOnly (Overwritten by perform_mri.ts).

3. The Workflow

Phase A: Planning (The Future)

  1. Check generated/future_capabilities.json.
  2. If your feature is missing, add it to the JSON with a priority.
  3. Include this Capability ID in your Blueprint or Spec (e.g., [GOV-ELECTION-CONFIG]).

Phase B: Implementation (The Code)

  1. Write your Service Method or API Route.
  2. IMMEDIATELY add the JSDoc tag.
/**
 * @cap GOV-ELECTION-CONFIG
 * @desc Configuration interface for election rules.
 * @access Admin only
 */
async function setElectionConfig(config: Config) { ... }

Phase C: Verification (The MRI)

  1. Run the scanner: pnpm diagnose:mri.
  2. Verify your new capability appears in generated/capabilities.json.
  3. Check documentation/06_DOMAIN_ARCHITECTURE.md for the updated report.

4. Maintenance

  • Renaming: If you rename a function, the @cap tag preserves the identity.
  • Refactoring: If you move a file, the MRI scanner finds it in the new location automatically.
  • Deletion: If you delete the code, the Capability disappears from the Matrix (preventing Zombie Documentation).

5. Tooling

  • pnpm diagnose:mri: Runs scripts/diagnostics/perform_mri.ts. Crawls packages/modules, extracts tags, updates JSON and Markdown.
  • pnpm diagnose:dye --apply: Runs scripts/diagnostics/inject_dye.ts. Auto-injects placeholder tags into untagged services (The "Contrast Agent").
  • pnpm diagnose:audit: Runs scripts/diagnostics/audit_tags.ts. Fails the build if untagged code is found (The "Gatekeeper").

6. Enforcement Policy

To ensure high fidelity of the MRI scans, tagging is enforced at the time of code creation.

  • CI Protocol: The diagnose:audit script runs during the CI pipeline.
  • Zero Tolerance: Any commit introducing untagged Capabilities or Entities will fail the build.
  • Enforcement: Zero tolerance for untagged code in CI.

7. Troubleshooting & Recovery

Issue: "Audit Failed" (Untagged Code)

  • Symptom: commit blocked or CI fails with "Found X untagged capabilities".
  • Cause: You wrote new Services or Schemas but didn't add JSDoc tags.
  • Recovery:
  • Run the Auto-Healer: pnpm diagnose:dye --apply
  • Review the injected tags (fill in descriptions).
  • Retry commit.

Issue: "Capability Not in Matrix"

  • Symptom: You tagged the code, but it doesn't show up in 06_CAPABILITY_MATRIX.md.
  • Cause: The MRI scan hasn't run, or the code syntax is unsupported.
  • Recovery:
  • Run the Scanner manually: pnpm diagnose:mri.
  • Check for syntax errors (e.g., missing async keyword pattern).
  • Check generated/capabilities.json directly to see if it was indexed.

Issue: "Drift Detected" (Git Status dirty after MRI)

  • Symptom: After running mri, 06_CAPABILITY_MATRIX.md shows as modified.
  • Cause: The documentation was out of sync with the code.
  • Recovery: Commit the updated Matrix. It is the View Layer and should always reflect the Code.

Version History

Version Date Author Change
0.1.0 2026-01-26 Antigravity Initial Audit & Metadata Injection