C3 Audit

Overview

Verify C3 documentation from two angles:

Methodology Compliance - Do docs follow C3 layer rules?
Implementation Conformance - Do docs match code reality?

Announce: "I'm using the c3-audit skill to audit documentation."

Audit Modes

| Mode | Purpose | When | |------|---------|------| | Methodology | Verify layer rules | After doc changes | | Full | All docs vs code | Periodic health check | | ADR | Verify ADR implemented | After ADR work | | ADR-Plan | ADR ↔ Plan coherence | Before handoff | | Container | Single container audit | After container changes | | Quick | Inventory check only | Fast sanity check |

Mode 0: Methodology Audit

Phase 1: Load Layer Rules

Load rules from references/layer-audit-rules.md (or layer skill defaults).

Phase 2: Structure Check

Verify IDs, paths, frontmatter per references/v3-structure.md.

Phase 3: Layer Content Audit

For each doc, verify content matches layer rules:

Context: Has container inventory, protocols. NO component lists.
Container: Has component inventory, tech stack. NO step-by-step algorithms.
Component: Has flow, dependencies. NO sibling relationships.

Phase 4: Diagram Audit

Verify diagram types appropriate per layer (see references/layer-audit-rules.md).

Phase 5: Contract Chain

Check for orphans (undocumented) and phantoms (documented but missing).

Phase 6: Load Layer Skills

Load c3-context-design, c3-container-design, c3-component-design for suggestion generation.

Phase 7: Generate Report

Use template from references/audit-report-templates.md.

Mode 1: Full Audit

Load all C3 docs (inventory)
Explore codebase (Task tool, Explore agent)
Compare: inventory drift, technology drift, structure drift, protocol drift
Generate drift report

Mode 2: ADR Audit

Load ADR, extract Changes Across Layers + Verification Checklist
Verify each doc change was made
Verify code matches (use verification items)
Update Audit Record in ADR file:
- Append row to "Audit Runs" table:
```
| YYYY-MM-DD | [layers checked] | PASS/FAIL | [drift found or "None"] |
```
- If PASS: Update "Lifecycle" table row for Implemented
If all pass: transition status to implemented, rebuild TOC

📋 ADR STATUS ENFORCEMENT (MANDATORY)

This applies to Mode 2 (ADR Audit) and any audit that touches ADRs.

Status Workflow

proposed → accepted → implemented
                   ↘ superseded
                   ↘ deprecated

Status Transition Rules

| Transition | Requirement | Who | |------------|-------------|-----| | proposed → accepted | Design reviewed, approach approved | Human decision | | accepted → implemented | All doc changes made, code matches, verification passes | Audit verifies | | Any → superseded | New ADR replaces this one (link required) | Human decision | | Any → deprecated | Decision no longer relevant | Human decision |

Audit Verification for `implemented` Status

BEFORE transitioning to implemented, verify ALL:

| Check | How to Verify | |-------|---------------| | All "Changes Across Layers" made | Each doc modified as specified | | Verification checklist passes | Each item checked and passes | | Code matches docs | Implementation conforms to documented changes | | Implementation Plan complete | All Code Changes done, Acceptance Criteria met |

TOC Filtering

Only status: implemented ADRs appear in TOC.

After transitioning to implemented:

# Rebuild TOC using build-toc.sh from plugin
./build-toc.sh

Red Flags - STOP and Fix

🚩 ADR with implemented status but verification items unchecked 🚩 ADR in TOC but status is proposed or accepted 🚩 superseded ADR without link to replacement 🚩 Missing status field in frontmatter 🚩 Skipping accepted (going straight from proposed to implemented)

Audit Checklist for ADR Status

[ ] ADR has status field in frontmatter
[ ] Status is valid (proposed, accepted, implemented, superseded, deprecated)
[ ] If implemented: all verifications pass
[ ] If superseded: links to replacement ADR
[ ] TOC only includes implemented ADRs

Mode 3: ADR-Plan Coherence

Extract ADR sections + Implementation Plan
Verify: Layer Changes → Code Changes (all mapped)
Verify: Verifications → Acceptance Criteria (all mapped)
Check for orphans, vague locations, untestable criteria

Mode 4: Container Audit

Focus on single container: technology match, component coverage, pattern compliance.

Mode 5: Quick Audit

# Inventory counts only
grep -c "| c3-[0-9]" .c3/README.md
ls -d .c3/c3-[0-9]-*/ 2>/dev/null | wc -l

Checklist

See references/audit-report-templates.md for full checklists per mode.

references/layer-audit-rules.md - Layer compliance rules
references/audit-report-templates.md - Report formats
references/v3-structure.md - ID/path patterns