Cathedral Audit

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

1. Forward Audit (specs → code)
2. Reverse Audit (code → specs)
3. Consolidation & Prioritization
4. Execution
5. Verification

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: kitty-specs/000-project-context/spec-audit-YYYY-MM-DD.md

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. 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: kitty-specs/000-project-context/reverse-audit-YYYY-MM-DD.md

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. 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: cat /tmp/task.md | claude -p --allowedTools 'Edit,Write,Read,Bash'
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:

## [Priority Tier Name]
- CC session: [name] (launched ~HH:MM CST)
- Task: [brief description]
- Status: [RUNNING | ✅ COMPLETE | ❌ FAILED | ⚠️ KILLED]
- Files changed: [count]
- Key actions: [what was done]
- Issues: [any problems encountered]
- Committed as [hash]

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:

kitty-specs/000-project-context/
  spec-audit-YYYY-MM-DD.md      (forward)
  reverse-audit-YYYY-MM-DD.md   (reverse)

The executive summary table with deltas is the key metric:

| Category | Previous | Current | Delta |
|----------|----------|---------|-------|
| Unspecced Code | 38 | 24 | -14 |
| Divergences | 12 | 7 | -5 |
| Dead Code | 14 | 8 | -6 |
| Bugs | 0 | 8 | +8 |
| Conformant | ~60 | ~120 | +60 |

CC Task Briefing Template

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