feat(skills): add sw-audit for periodic codebase health checks

CLAUDE.md

@@ -19,6 +19,7 @@ Spec-driven app development with quality gates. Ensures the user gets what they
 | `sw-guard` | Detect stack and interactively configure guardrails (hooks, CI, settings). |
 | `sw-status` | Current state and progress. |
 | `sw-learn` | Post-ship capture of patterns and learnings. |
+| `sw-audit` | Periodic codebase health check. Finds systemic tech debt. |
 
 ## Anchor Documents
 
@@ -52,6 +53,7 @@ Skills reference shared protocols in `protocols/` for fragile operations:
 - `insights.md` -- External Claude Code insights data access
 - `learning-lifecycle.md` -- Compaction triggers and tiered memory
 - `landscape.md` -- Codebase reference document format and freshness rules
+- `audit.md` -- Codebase health findings format, IDs, and lifecycle
 
 ## Key Rules
 

DESIGN.md

@@ -39,9 +39,12 @@ What is this repo? What are we building? Who are the consumers? Architectural in
 **LANDSCAPE.md** -- Codebase Knowledge (optional)
 Persistent cache of codebase structure: architecture, modules, conventions, integration points, gotchas. Not an anchor document — it accelerates design research but never blocks workflow. Created by sw-init (survey phase), read by sw-design (with inline refresh when stale), incrementally updated by sw-learn after shipping. Format and freshness rules in `protocols/landscape.md`.
 
-## Skills (14)
+**AUDIT.md** -- Codebase Health Findings (optional)
+Persistent record of systemic issues that per-change gates miss: architecture debt, complexity growth, convention drift, accumulated workarounds. Created by sw-audit, surfaced by sw-design during research, resolved by sw-learn after shipping. Findings have stable IDs across re-runs. Resolved findings purge after 90 days. Format, matching, and freshness rules in `protocols/audit.md`.
 
-### User-Facing (9)
+## Skills (15)
+
+### User-Facing (10)
 
 | Skill | Purpose | Key Innovation |
 |-------|---------|----------------|
@@ -54,6 +57,7 @@ Persistent cache of codebase structure: architecture, modules, conventions, inte
 | `sw-status` | Where am I, what's done, what's next | Supports --reset to abandon work |
 | `sw-guard` | Detect stack, configure guardrails interactively | Layer-by-layer approval (session, commit, push, CI/CD) |
 | `sw-learn` | Post-ship capture. What worked, what to remember | Promotes patterns to constitution |
+| `sw-audit` | Periodic codebase health check | Finds systemic debt gates miss. Feeds findings into design + learn |
 
 ### Internal Gate Skills (5)
 
@@ -111,8 +115,9 @@ Extracted once in `protocols/`, referenced by skills. Loaded on demand.
 | `insights.md` | External CC insights data access | ~150 |
 | `learning-lifecycle.md` | Compaction triggers, tier structure, theme format | ~150 |
 | `landscape.md` | Codebase reference doc format, freshness, updates | ~180 |
+| `audit.md` | Codebase health findings format, IDs, matching, lifecycle | ~180 |
 
-Total: ~2030 tokens (loaded on demand, not all at once).
+Total: ~2210 tokens (loaded on demand, not all at once).
 
 ## Skill Anatomy
 
@@ -156,7 +161,7 @@ Target: 600 tokens per SKILL.md (40% of the 1,500 token ceiling).
 
 ```
 specwright/
-├── skills/           # SKILL.md files (14 skills)
+├── skills/           # SKILL.md files (15 skills)
 │   ├── sw-init/      # User-facing
 │   ├── sw-design/
 │   ├── sw-plan/
@@ -166,6 +171,7 @@ specwright/
 │   ├── sw-guard/
 │   ├── sw-status/
 │   ├── sw-learn/
+│   ├── sw-audit/
 │   ├── gate-build/   # Internal (invoked by verify)
 │   ├── gate-tests/
 │   ├── gate-security/
@@ -187,6 +193,7 @@ Runtime state (created by init):
 ├── CONSTITUTION.md   # Development practices
 ├── CHARTER.md        # Technology vision
 ├── LANDSCAPE.md      # Codebase knowledge (optional)
+├── AUDIT.md          # Codebase health findings (optional)
 ├── state/
 │   └── workflow.json # Current state
 └── work/             # Work unit artifacts (specs, evidence, plans)

README.md

@@ -167,6 +167,7 @@ Two persistent documents drive all decisions and survive context compaction:
 | `/sw-guard` | Configure guardrails (hooks, CI) |
 | `/sw-status` | Progress and state |
 | `/sw-learn` | Pattern capture |
+| `/sw-audit` | Codebase health check |
 
 </td></tr>
 </table>
@@ -195,8 +196,8 @@ See `DESIGN.md` for the complete architecture document.
 
 ```
 specwright/
-├── skills/       # 14 SKILL.md files (9 user + 5 gates)
-├── protocols/    # 11 shared protocols (loaded on demand)
+├── skills/       # 15 SKILL.md files (10 user + 5 gates)
+├── protocols/    # 12 shared protocols (loaded on demand)
 ├── agents/       # 6 custom subagent definitions
 ├── hooks/        # Session lifecycle hooks
 ├── DESIGN.md     # Full architecture

protocols/audit.md

@@ -0,0 +1,25 @@
+# Audit Protocol
+
+## Format
+
+`.specwright/AUDIT.md` — optional reference document. Never blocks workflow.
+
+Header: `Snapshot:` (ISO 8601), `Scope:` (full | focused: {path}), `Dimensions:` (list), `Findings:` (count, B/W/I).
+
+Sections: Summary, Findings (`[SEVERITY] F{n}: {title}` — Dimension, Location, Description, Impact, Recommendation, Status), Resolved (resolver ID + date).
+
+## Finding IDs
+
+Format: `F{n}`, never reused. On re-run: match by dimension + location. Matched → reuse ID. Unmatched new → next ID. Unmatched existing → `stale`.
+
+## Lifecycle
+
+Open → Stale (unmatched on re-run) → Resolved (`## Resolved`, with work unit ID + date) → Purged (resolved >90 days, removed on re-run).
+
+## Size
+
+Target 1000-2000 words, cap 3000. Overflow: keep highest-severity, truncate INFO.
+
+## Freshness
+
+`Snapshot:` timestamp. Stale after 30 days (configurable: `config.audit.stalenessThresholdDays`). Missing: proceed without.

protocols/context.md

@@ -18,6 +18,7 @@ Load when needed for alignment/verification:
 Load on demand when codebase structure knowledge is needed:
 
 - `.specwright/LANDSCAPE.md` — Codebase architecture and module knowledge (optional)
+- `.specwright/AUDIT.md` — Codebase health findings and tech debt tracking (optional)
 
 ## Initialization Checks
 

skills/sw-audit/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: sw-audit
+description: >-
+  Periodic codebase health check. Analyzes architecture, complexity,
+  consistency, and debt across the full codebase. Produces persistent
+  findings in AUDIT.md.
+argument-hint: "[path | --full]"
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+# Specwright Audit
+
+## Goal
+
+Find systemic codebase issues that per-change quality gates miss.
+Architecture debt, complexity growth, convention drift, and accumulated
+workarounds compound silently. Surface them, let the user prioritize,
+and persist findings for future design cycles.
+
+## Inputs
+
+- The codebase itself
+- `.specwright/CONSTITUTION.md` -- practices to check against
+- `.specwright/AUDIT.md` -- prior findings (if exists, for ID matching)
+- `.specwright/LANDSCAPE.md` -- module structure (if exists, for triage)
+- `.specwright/config.json` -- audit config (optional `audit` section)
+
+## Outputs
+
+- `.specwright/AUDIT.md` -- findings per `protocols/audit.md` format
+- Findings presented to user grouped by dimension before saving
+
+## Constraints
+
+**Scope (LOW freedom):**
+- This skill reads and analyzes. It NEVER modifies source code, creates branches, runs builds, or starts work units.
+- Does NOT create `currentWork` in workflow.json. Does NOT require a lock. Can run while a work unit is in progress.
+- On compaction: re-run from scratch (no state to recover).
+
+**Triage (MEDIUM freedom):**
+- Determine intensity from argument and codebase size:
+  - Path argument → **Focused**: analyze specified directory/module only
+  - `--full` argument → **Full**: parallel agents, all dimensions
+  - No argument → auto-triage: Standard (<50 files) or Full (50+ files)
+- If LANDSCAPE.md exists, use module count to inform triage.
+
+**Analysis (HIGH freedom):**
+- Four dimensions: architecture, complexity, consistency, debt.
+- Delegate per `protocols/delegation.md`:
+  - `specwright-architect`: architecture + complexity (structural analysis)
+  - `specwright-reviewer`: consistency + debt (convention and quality analysis)
+- Standard intensity: 2 agent calls (sequential or parallel).
+- Full intensity: up to 4 parallel calls (one per dimension).
+- Include constitution practices as the baseline for consistency checks.
+
+**Synthesis (LOW freedom):**
+- Agents return raw findings. The skill itself aggregates results.
+- If prior AUDIT.md exists: match findings per `protocols/audit.md` (dimension + location). Reuse matched IDs, assign new IDs for unmatched. Mark unmatched prior findings as stale.
+- Purge resolved findings older than 90 days.
+- Enforce size cap per protocol. Write AUDIT.md.
+
+**Presentation (MEDIUM freedom):**
+- Show findings grouped by dimension. For each: severity, location, description, impact, recommendation.
+- Use AskUserQuestion to let user adjust severity or dismiss findings before saving.
+- Maximum 20 findings per run. If more, keep highest-severity.
+
+## Protocol References
+
+- `protocols/audit.md` -- finding format, IDs, matching, lifecycle
+- `protocols/delegation.md` -- agent delegation
+- `protocols/context.md` -- config and anchor doc loading
+
+## Failure Modes
+
+| Condition | Action |
+|-----------|--------|
+| No codebase files found | STOP: "No source files to audit." |
+| Agents unavailable | Fall back to inline analysis (less thorough) |
+| Prior AUDIT.md parse error | WARN, start fresh (no ID continuity) |
+| Compaction during audit | Re-run from scratch |

skills/sw-design/SKILL.md

@@ -57,8 +57,9 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 
 **Research (HIGH freedom):**
 - If `.specwright/LANDSCAPE.md` exists, load it first. If stale per `protocols/landscape.md`, refresh inline and update `Snapshot:` timestamp. If missing, proceed without. Use as baseline for research.
+- If `.specwright/AUDIT.md` exists and fresh per `protocols/audit.md`, surface relevant findings for the area being designed.
 - Scan code, dependencies, APIs, existing patterns. Check `.specwright/patterns.md` and `.specwright/learnings/INDEX.md` if they exist.
-- Delegate to `specwright-researcher` (external docs) and `specwright-architect` (deep analysis) as needed.
+- Delegate to `specwright-researcher` and `specwright-architect` as needed.
 - Produce `context.md` summarizing findings for downstream agents.
 
 **Design (HIGH freedom):**
@@ -73,8 +74,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - `design.md` exists + argument: change request, re-run critic. No argument: ask — redesign, continue, or changes.
 
 **User checkpoints:**
-- Ask for hard constraints before research (record in design.md). Share findings after research, alternatives after design, resolutions after critic.
-- The user must approve the design before it is saved.
+- Ask for hard constraints before research. Share findings after research, alternatives after design, resolutions after critic. User approves design before saving.
 
 **State mutations (LOW freedom):**
 - Follow `protocols/state.md` for all workflow.json updates.
@@ -89,6 +89,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate
 - `protocols/delegation.md` -- agent delegation for research and critic
 - `protocols/recovery.md` -- compaction recovery
 - `protocols/landscape.md` -- codebase reference document format
+- `protocols/audit.md` -- codebase health findings format
 
 ## Failure Modes
 

skills/sw-learn/SKILL.md

@@ -54,30 +54,31 @@ work benefits.
 
 **Discovery (HIGH freedom):**
 - Scan evidence files, git log, and plan.md for patterns worth remembering.
-- Look for: things that broke, things surprisingly hard, things that worked well.
+- Look for: what broke, what was hard, what worked well.
 
 **Presentation (MEDIUM freedom):**
 - Group by category (build, security, testing, architecture). Show: what happened, why it matters, proposed rule.
-- Use AskUserQuestion for curation: promote to constitution, promote to patterns, or dismiss.
-- Maximum 5-7 learnings per session.
+- Use AskUserQuestion for curation: promote to constitution, patterns, or dismiss. Maximum 5-7 learnings.
 
 **Promotion (LOW freedom):**
-- If promoting to constitution: add a new practice with ID (e.g., S6, Q5) and clear wording.
-- If promoting to patterns: append to `.specwright/patterns.md` (create if doesn't exist).
-- User must approve exact wording before saving.
+- Constitution: add practice with ID (e.g., S6, Q5). Patterns: append to `.specwright/patterns.md` (create if missing).
+- User approves exact wording before saving.
 
 **Retrospective (MEDIUM freedom):**
-- When `.specwright/learnings/` has 2+ prior files, surface recurring patterns across units citing work IDs.
-- If directory empty, missing, or <2 files: silently skip.
+- When 2+ prior learning files exist, surface recurring patterns across units.
 
 **Persistence (LOW freedom):**
-- Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted.
+- Write `.specwright/learnings/{work-id}.json` when any finding is promoted.
 - Schema: `{ workId, timestamp, findings: [{ category, source, description, proposedRule, disposition }] }`
 
 **Landscape update (MEDIUM freedom):**
 - After persistence, if `.specwright/LANDSCAPE.md` exists: identify affected modules from evidence and plan artifacts, re-scan those modules, merge updates. Show diff, user approves. Update `Snapshot:` timestamp.
 - If LANDSCAPE.md doesn't exist: silently skip.
 
+**Audit resolution (MEDIUM freedom):**
+- After landscape update, if `.specwright/AUDIT.md` exists: check if work unit's changed files overlap with open finding locations. If finding is addressed, move to `## Resolved` with work unit ID. User approves.
+- If AUDIT.md doesn't exist: silently skip.
+
 **Enrichment (MEDIUM freedom):**
 - Optional per `protocols/insights.md`. Silently skip if unavailable or stale.
 
@@ -92,6 +93,7 @@ work benefits.
 - `protocols/insights.md` -- session pattern enrichment
 - `protocols/learning-lifecycle.md` -- compaction triggers and lifecycle
 - `protocols/landscape.md` -- codebase reference document format
+- `protocols/audit.md` -- codebase health findings format
 
 ## Failure Modes