Cathedral Audit

intent

cathedral-audit measures and closes spec-code drift in the Cathedral C# codebase through a two-pass audit system. forward audit (specs→code) checks whether code implements what specs say. reverse audit (code→specs) finds unspecced code, orphaned files, and bugs. output is a prioritized fix plan executed via CC sessions with continuous logging. run this after build waves, major refactors, when drift is suspected, or as a periodic health check triggered by events (not a calendar).

inputs

codebase locations:

• specs: kitty-specs/ directory (all .md spec files)
• code: src/Cathedral.Core/ and src/Cathedral.TestHarness/ (all .cs files)
• previous audits: kitty-specs/000-project-context/spec-audit-*.md and reverse-audit-*.md (for delta comparison)

execution environment:

• dotnet SDK 6+ installed and dotnet build functional
• claude CLI installed with -p (piped input) flag and access to Edit, Write, Read, Bash tools
• bash shell for cron/monitoring and git operations
• memory file location: memory/YYYY-MM-DD.md (create if missing)
• task briefing template: references/cc-task-template.md

cc agent access:

• read-only access to kitty-specs/ and src/ directories
• write access to assigned files only (CC will edit .cs and .md as instructed)
• no access to credentials or external services

system constraints:

• memory-constrained hosts (wsl2, etc.): sequential cc execution only. two concurrent sessions cause oom.
• memory-capable hosts: parallel cc agents allowed (one per spec batch or directory subsystem), but monitor memory actively.

external dependencies:

• git (commit and diff operations)
• cron or timer for 5-min monitoring intervals during cc execution

procedure

step 1: forward audit (specs→code)

1a. input: read all .md files in kitty-specs/. 1b. for each spec, assign to a cc agent (batch by directory if running parallel, or queue sequentially on constrained hosts). 1c. cc agent compares spec text against code implementation in src/Cathedral.Core/ and src/Cathedral.TestHarness/. 1d. output per spec: one status line:

• ✅ conformant (code matches spec)
• ⚠️ divergent (code exists but differs from spec)
• ❌ missing (spec describes something not built) 1e. cc writes findings to kitty-specs/000-project-context/spec-audit-YYYY-MM-DD.md with brief evidence per spec. 1f. input to next step: completed forward audit file.

step 2: reverse audit (code→specs)

2a. input: all .cs files from src/Cathedral.Core/ and src/Cathedral.TestHarness/. group by directory/subsystem for parallel batching. 2b. for each code file/subsystem, cc scans for:

• is there a spec that covers this code?
• does the code match the spec (if one exists)?
• is this dead/orphaned code (no callers)? 2c. cc produces structured report with sections:
• executive summary: count table with deltas (unspecced, divergent, dead, bugs, conformant). compare against previous audit by reading last reverse-audit-*.md.
• unspecced code: list of files/subsystems with no spec coverage.
• architectural divergences: code takes fundamentally different path than spec.
• code exceeding spec: code has features spec doesn't document.
• dead/orphaned code: files with zero callers or references.
• bugs discovered: runtime, data, or logic bugs found during review. include severity.
• comparison with previous audit: what improved, what remains. cite previous file by date. 2d. output: write to kitty-specs/000-project-context/reverse-audit-YYYY-MM-DD.md. 2e. input to next step: completed reverse audit file.

step 3: consolidation and prioritization

3a. input: spec-audit-YYYY-MM-DD.md, reverse-audit-YYYY-MM-DD.md, and the bugs/findings section. 3b. merge all findings into a single action plan. categorize by priority tier (see decision points). 3c. output: write recommendations section into the reverse audit report (append to file created in step 2). 3d. rules:

• each priority tier should fit in one cc session (scope for success).
• bugs always get their own section and are ranked by severity.
• code exceeding spec = write spec update, not code change.
• architectural divergences deferred to v2 = p6 tier, documented but not actioned. 3e. input to next step: prioritized list of fixes (one per tier).

step 4a: execution setup (per priority tier)

4a-i. before launching cc: write intent log to memory/YYYY-MM-DD.md. format:

## [Priority Tier Name]
- CC session: [name] (launched ~HH:MM CST)
- Task: [brief description]
- Status: RUNNING
- Files changed: [pending]
- Key actions: [pending]
- Issues: [none yet]
- Committed as: [pending]

4a-ii. read references/cc-task-template.md and write task briefing to /tmp/task.md. include priority tier, files to change, acceptance criteria. 4a-iii. input to next step: task briefing and memory log created.

step 4b: execution launch

4b-i. launch cc: cat /tmp/task.md | claude -p --allowedTools 'Edit,Write,Read,Bash' 4b-ii. set up monitoring: run cron or loop to check process every 5 min. watch for oom, timeout, or completion. 4b-iii. input: cc session running. output: cc produces edited files and status.

step 4c: execution completion

4c-i. when cc reports done: run dotnet build in the repo root. output: build log. 4c-ii. check build result. if build fails:

• cc may have been oom-killed mid-check. run git diff --stat to see what changed.
• fix compilation errors manually or reset with git checkout and re-run cc.
• log incident to memory file: "Build failed at HH:MM, [reason], fixed by [action]".
• do not commit until build passes. 4c-iii. if build passes: run git diff --stat to confirm file count matches intent. output: stat report. 4c-iv. update memory log with results:

## [Priority Tier Name]
- CC session: [name] (launched ~HH:MM, completed ~HH:MM CST)
- Task: [description]
- Status: ✅ COMPLETE
- Files changed: [count from diff --stat]
- Key actions: [what cc actually did]
- Issues: [any problems]
- Committed as: [pending]

4c-v. input to next step: passing build and git diff report.

step 4d: execution commit

4d-i. compose commit message referencing priority tier: [P<N>] [tier name]: [brief description]. example: [P0] Bug fixes: fix double-logging in AuthService, resolve OOM in CacheManager. 4d-ii. run: git add -A && git commit -m "[P<N>] [message]". output: commit hash. 4d-iii. log commit hash to memory file: update "Committed as [hash]" line. 4d-iv. input to next step: committed tier.

step 5: verification (optional, after all tiers complete)

5a. input: all tier commits and previous audit for comparison. 5b. optionally re-audit selected categories to measure improvement (not required if audits are recent). 5c. compare counts: unspecced, divergent, dead code, bugs. 5d. verify delta matches expectations from consolidation plan. 5e. output: updated audit comparison section documenting improvement and any remaining gaps. 5f. log summary to memory file:

## Final Summary
- Total commits: [count]
- Total lines changed: [from git log]
- P0-P5 resolved: [count]
- P6 deferred: [count]
- New gaps discovered: [list or none]

decision points

if host is memory-constrained (wsl2, < 8gb ram):

• run all cc agents sequentially. do not spawn parallel sessions. queue specs and code subsystems in order.
• else (memory-capable): batch agents by directory or spec file group for speed. monitor memory during execution.

if previous audit exists in kitty-specs/000-project-context/:

• read the executive summary table and use it as baseline. include delta column in new audit.
• else (first audit): create baseline counts without comparison. future audits will compare against this.

if build fails after cc execution:

• check if cc was oom-killed. run git diff --name-only to see what changed.
• if oom suspected: reset with git checkout -- . and re-run cc with smaller file batches.
• if compilation errors: cc may have introduced syntax issues. either fix manually or ask cc to retry.
• do not commit until dotnet build passes.

if cc session gets killed (oom, timeout, or crash):

• log the incident to memory file with timestamp and cause.
• run git diff --stat to confirm what was written.
• check dotnet build to see if partial changes broke the build.
• if build is broken: reset with git checkout -- . and assess whether to retry or skip this tier.
• if build passes: optionally commit the partial work and log it as incomplete. resume with next tier.
• never commit without a passing build.

if a bug is discovered during reverse audit but has low severity (e.g., cosmetic):

• assign to p2 (data quality) or p4 (spec accuracy). do not defer to p6 unless architectural.
• else (high severity or runtime impact): assign to p0. action in first execution round.

if code exceeds spec (features not documented in spec):

• create a spec update task (p4 priority). do not change code.
• else (spec is accurate): mark as conformant.

if architectural divergence exists but is intentional (deferred to v2):

• document in "architectural gaps" section of recommendations.
• assign to p6 tier. note in task briefing: "defer to v2, document only, no code changes".
• else (unintentional divergence): assign to p1-p3 tier and fix in execution phase.

output contract

forward audit file (spec-audit-YYYY-MM-DD.md):

• format: markdown with one row per spec file.
• columns: spec file path, status (✅/⚠️/❌), brief evidence (one sentence per status).
• location: kitty-specs/000-project-context/spec-audit-YYYY-MM-DD.md.
• required: present at end of step 1.

reverse audit file (reverse-audit-YYYY-MM-DD.md):

• format: markdown with structured sections (executive summary, unspecced, divergences, exceeding spec, dead code, bugs, comparison).
• executive summary: table with columns [Category, Previous, Current, Delta]. categories: unspecced code, divergences, dead code, bugs, conformant specs.
• bugs section: formatted as list with severity tags (critical/high/medium/low).
• comparison section: cites previous audit by date and explains improvements.
• location: kitty-specs/000-project-context/reverse-audit-YYYY-MM-DD.md.
• required: present at end of step 2.

recommendations section (appended to reverse audit):

• format: priority table with columns [Priority, Category, Criteria, Count, Files/Notes].
• priority levels: p0-p6 with clear scope.
• deferred p6 items: explicitly noted as "deferred to v2" in notes column.
• location: appended to reverse-audit-YYYY-MM-DD.md at end of step 3.
• required: present at end of step 3.

memory file (memory/YYYY-MM-DD.md):

• format: markdown with per-tier sections (see logging template in procedure).
• sections: audit launch, audit results summary, per-tier logs (intent, session, results, commit), final summary.
• location: memory/YYYY-MM-DD.md (create if missing).
• required: continuously updated from step 1 through step 5. this is the execution trail.

git commits:

• message format: [P<N>] [tier name]: [description]. example: [P0] Bug fixes: AuthService double-logging, CacheManager OOM.
• one commit per priority tier (or logical grouping within tier).
• all commits must follow a passing dotnet build.
• hash logged to memory file.

build state:

• dotnet build must return exit code 0 before any commit.
• non-negotiable. if build is broken, audit is incomplete.

outcome signal

audit is successful when:

• forward and reverse audit files are written to kitty-specs/000-project-context/ with today's date.
• executive summary table shows delta (improvement) vs. previous audit or is baseline if first run.
• memory file in memory/YYYY-MM-DD.md contains complete execution trail from launch through final summary.

execution (step 4) is successful when:

• all priority tiers p0-p5 are committed to git (p6 is documented but not actioned).
• dotnet build passes after each commit.
• each tier's memory log shows status ✅ complete with commit hash.
• no p0 or p1 bugs remain (they are all fixed and committed).

you know it worked because:

• git log shows new commits with [P0]...[P5] tags.
• git diff <last-main-commit>..HEAD --stat shows files changed per tier.
• memory file is complete and traceable (read it back to understand what happened).
• build is green and no regressions appear in test runs.
• unspecced code count decreased (from executive summary delta).
• bugs discovered in reverse audit are now closed (status changed from open to fixed).