Cathedral Audit

A structured process for measuring and closing spec-code drift in the Cathedral C# codebase.

When to Run

• - After a build wave (multiple features/refactors landed)
• Before starting a new major feature (establish baseline)
• When spec-code drift is suspected
• Periodically as a health check (not on a calendar — trigger on events)

Process Overview

CODEBLOCK0

Step 1: Forward Audit (Specs → Code)

For each spec in kitty-specs/, compare what the spec says against what the code does.

Output per spec: One of:

• - ✅ Conformant — code matches spec
• ⚠️ Divergent — code exists but differs from spec
• ❌ Missing — spec describes something not built

Deliverable: INLINECODE1

Use parallel CC agents (one per spec batch) for speed if memory allows. On memory-constrained hosts (e.g., WSL2), run sequentially — two concurrent CC sessions will OOM. Provide each agent read-only access.

Step 2: Reverse Audit (Code → Specs)

Scan all .cs files in src/Cathedral.Core/ and src/Cathedral.TestHarness/. For each file/subsystem, determine:

• - Is it covered by a spec?
• Does it match what the spec says?
• Is it dead/orphaned code?

Output sections:

1. 1. Executive Summary — counts with delta from previous audit
2. Unspecced Code — files/subsystems with no spec coverage
3. Architectural Divergences — code takes a fundamentally different path than spec
4. Code Exceeding Spec — code has features the spec doesn't document
5. Dead/Orphaned Code — files with no callers or references
6. Bugs Discovered — runtime, data, or logic bugs found during review
7. Comparison with Previous Audit — what improved, what remains

Deliverable: INLINECODE5

Use parallel CC agents (group files by directory/subsystem) for speed if memory allows. Run sequentially on memory-constrained hosts.

Step 3: Consolidation & Prioritization

Merge findings from both audits into a prioritized action plan:

Rules:

• - Bugs always get their own section with severity ratings
• "Code exceeding spec" = spec update, not code change
• Architectural divergences that are intentionally deferred (V2 work) go to P6 and are documented but not actioned
• Each priority level should be achievable in a single CC session

Deliverable: Recommendations section in the reverse audit report.

Step 4: Execution

Execute fixes by priority tier (P0 first, P6 last or deferred).

Per priority tier:

1. 1. Log intent to memory/YYYY-MM-DD.md — tier name, CC session name, what's being attempted
2. Write a task briefing for CC (see references/cc-task-template.md)
3. Launch CC session: INLINECODE8
4. Set up monitoring cron (every 5 min)
5. When CC completes: log results to daily memory — files changed, what was done, any issues
6. Verify build before committing — dotnet build must pass
7. If CC gets killed (OOM): check git diff --stat, verify build manually, fix any issues, log the incident
8. Commit with descriptive message referencing the priority tier
9. Log commit hash to daily memory

Hard rules:

• - ⚠️ ALWAYS verify dotnet build passes before committing. No exceptions. CC may get OOM-killed mid-build-check.
• ⚠️ ALWAYS log to daily memory file at every step. Log intent before launch, results after completion, commit hash after commit. If the session dies, the log survives for recovery.
• One commit per priority tier (or logical grouping)

Logging template for daily memory:
CODEBLOCK1

Step 5: Verification

After all tiers are complete, optionally run a quick re-audit to measure improvement:

• - Compare counts: unspecced, divergent, dead code, bugs
• Verify delta matches expectations
• Document remaining gaps and whether they're P6/deferred or newly discovered

Deliverable: Updated audit files with comparison section.

Logging

Every audit produces a complete trail in memory/YYYY-MM-DD.md:

• - Audit launch — which audits are being run, baseline reference
• Audit results — summary counts, key findings
• Each priority tier — intent, CC session, results, issues, commit hash
• Final summary — total commits, total lines changed, what's resolved vs deferred

This is non-negotiable. The Feb 17-18 amnesia incident proved that unlogged work is lost work. Log-then-act: write what you're about to do BEFORE doing it, then update with results.

Baseline Tracking

Always compare against the previous audit. Store audits as:
CODEBLOCK2

The executive summary table with deltas is the key metric:

CODEBLOCK3

CC Task Briefing Template

See references/cc-task-template.md for the standard format for CC task briefings.