From 3715622192bb8404f8af3c4a8b272858f477d272 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 19:32:41 +1100 Subject: [PATCH 1/7] feat(protocols): add audit protocol for codebase health check findings Defines AUDIT.md format, finding ID scheme with dimension+location matching, lifecycle (open/stale/resolved/purged), size caps, and freshness rules. Consumer-agnostic per P4. Co-Authored-By: Claude Opus 4.6 --- protocols/audit.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 protocols/audit.md diff --git a/protocols/audit.md b/protocols/audit.md new file mode 100644 index 0000000..278102d --- /dev/null +++ b/protocols/audit.md @@ -0,0 +1,40 @@ +# Audit Protocol + +## Format + +`.specwright/AUDIT.md` is a reference document (not an anchor document). Optional. Never blocks workflow. + +Required metadata header: +``` +Snapshot: {ISO 8601 timestamp} +Scope: {full | focused: {path}} +Dimensions: {list} +Findings: {count} (B:{n} W:{n} I:{n}) +``` + +Required sections: Summary, Findings (per-finding: `[SEVERITY] F{n}: {title}` with Dimension, Location, Description, Impact, Recommendation, Status), Resolved (resolved findings with resolver ID and date). + +## Finding IDs + +Format: `F{n}`. IDs are never reused. Resolved findings keep their ID in the `## Resolved` section. + +**Matching on re-run:** Match existing open findings by dimension + location (file path or module name). Matched: reuse ID, update description. Unmatched new: assign next available ID. Unmatched existing: mark `stale`. + +## Lifecycle + +- **Open:** active finding, not yet addressed +- **Stale:** open finding not matched on last re-run (may be resolved or moved) +- **Resolved:** moved to `## Resolved` section with resolver work unit ID and date +- **Purged:** resolved findings older than 90 days are removed on re-run + +## Size + +Target: 1000-2000 words. Hard cap: 3000 words. On overflow: keep highest-severity, truncate INFO findings, note truncation. + +## Freshness + +Parse `Snapshot:` timestamp. Default staleness threshold: 30 days. Configurable via `config.audit.stalenessThresholdDays` (optional field, default 30). + +- Fresh: use as-is +- Stale: consumer may re-run or proceed without +- Missing: no warning, proceed without From bf5f650336f50673e7ed24a5d32c9abc1e5d4267 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 19:33:09 +1100 Subject: [PATCH 2/7] feat(protocols): add AUDIT.md to context protocol reference documents Co-Authored-By: Claude Opus 4.6 --- protocols/context.md | 1 + 1 file changed, 1 insertion(+) diff --git a/protocols/context.md b/protocols/context.md index d6c2fac..62a3048 100644 --- a/protocols/context.md +++ b/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 From a2fd7721dc82a91a33e651102b771ee2c5cb8e39 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 19:33:57 +1100 Subject: [PATCH 3/7] feat(skills): add sw-audit skill for periodic codebase health checks Analyzes architecture, complexity, consistency, and debt dimensions. Delegates to architect and reviewer agents, synthesizes findings into persistent AUDIT.md. Adaptive intensity (focused/standard/full). Co-Authored-By: Claude Opus 4.6 --- skills/sw-audit/SKILL.md | 86 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 skills/sw-audit/SKILL.md diff --git a/skills/sw-audit/SKILL.md b/skills/sw-audit/SKILL.md new file mode 100644 index 0000000..6cd4fb6 --- /dev/null +++ b/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 | From 25bee3ab75b94cc7547d13ee53551148beb1e376 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 19:34:35 +1100 Subject: [PATCH 4/7] feat(skills): add audit-aware research to sw-design Load AUDIT.md during research phase to surface known tech debt in the area being designed. Tightened User checkpoints to compensate (P2). Co-Authored-By: Claude Opus 4.6 --- skills/sw-design/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/skills/sw-design/SKILL.md b/skills/sw-design/SKILL.md index b552b41..6cf16f3 100644 --- a/skills/sw-design/SKILL.md +++ b/skills/sw-design/SKILL.md @@ -57,6 +57,7 @@ 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. - Produce `context.md` summarizing findings for downstream agents. @@ -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 From 97971e22e20ebe986ec7bdadf6ab0785d4d12035 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 19:35:15 +1100 Subject: [PATCH 5/7] feat(skills): add audit resolution phase to sw-learn After landscape update, checks if work unit resolved any open audit findings. Tightened Presentation and Retrospective to compensate (P2). Co-Authored-By: Claude Opus 4.6 --- skills/sw-learn/SKILL.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/skills/sw-learn/SKILL.md b/skills/sw-learn/SKILL.md index 6a19a2d..0859f97 100644 --- a/skills/sw-learn/SKILL.md +++ b/skills/sw-learn/SKILL.md @@ -58,8 +58,7 @@ work benefits. **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. @@ -67,8 +66,7 @@ work benefits. - User must approve 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 `.specwright/learnings/` has 2+ prior files, surface recurring patterns across units. If <2 files: skip. **Persistence (LOW freedom):** - Write `.specwright/learnings/{work-id}.json` only when at least one finding is promoted. @@ -78,6 +76,10 @@ work benefits. - 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 +94,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 From 9a1a92f97ec9906c92d8f5cddbb9ab5c2e5aa81f Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 19:38:49 +1100 Subject: [PATCH 6/7] docs: add sw-audit to DESIGN.md, CLAUDE.md, and README.md [codebase-audit/docs-audit] Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 ++ DESIGN.md | 15 +++++++++++---- README.md | 5 +++-- 3 files changed, 16 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8d149af..e46d782 100644 --- a/CLAUDE.md +++ b/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 diff --git a/DESIGN.md b/DESIGN.md index 43eb6d4..d9178e0 100644 --- a/DESIGN.md +++ b/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) diff --git a/README.md b/README.md index f7c43d5..25befba 100644 --- a/README.md +++ b/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 | @@ -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 From c45d86f705e07dce9c1336e163c9c741fa7dde52 Mon Sep 17 00:00:00 2001 From: MacAttak Date: Sun, 15 Feb 2026 22:45:43 +1100 Subject: [PATCH 7/7] fix(specs): compress audit protocol and tighten skill word budgets Resolves AC-1.7 (protocol over token budget), AC-4.4 (sw-design +14 words, limit 10), and AC-5.5 (sw-learn +36 words, limit 15). [codebase-audit/verify-fixes] Co-Authored-By: Claude Opus 4.6 --- protocols/audit.md | 29 +++++++---------------------- skills/sw-design/SKILL.md | 2 +- skills/sw-learn/SKILL.md | 11 +++++------ 3 files changed, 13 insertions(+), 29 deletions(-) diff --git a/protocols/audit.md b/protocols/audit.md index 278102d..99e08b3 100644 --- a/protocols/audit.md +++ b/protocols/audit.md @@ -2,39 +2,24 @@ ## Format -`.specwright/AUDIT.md` is a reference document (not an anchor document). Optional. Never blocks workflow. +`.specwright/AUDIT.md` — optional reference document. Never blocks workflow. -Required metadata header: -``` -Snapshot: {ISO 8601 timestamp} -Scope: {full | focused: {path}} -Dimensions: {list} -Findings: {count} (B:{n} W:{n} I:{n}) -``` +Header: `Snapshot:` (ISO 8601), `Scope:` (full | focused: {path}), `Dimensions:` (list), `Findings:` (count, B/W/I). -Required sections: Summary, Findings (per-finding: `[SEVERITY] F{n}: {title}` with Dimension, Location, Description, Impact, Recommendation, Status), Resolved (resolved findings with resolver ID and date). +Sections: Summary, Findings (`[SEVERITY] F{n}: {title}` — Dimension, Location, Description, Impact, Recommendation, Status), Resolved (resolver ID + date). ## Finding IDs -Format: `F{n}`. IDs are never reused. Resolved findings keep their ID in the `## Resolved` section. - -**Matching on re-run:** Match existing open findings by dimension + location (file path or module name). Matched: reuse ID, update description. Unmatched new: assign next available ID. Unmatched existing: mark `stale`. +Format: `F{n}`, never reused. On re-run: match by dimension + location. Matched → reuse ID. Unmatched new → next ID. Unmatched existing → `stale`. ## Lifecycle -- **Open:** active finding, not yet addressed -- **Stale:** open finding not matched on last re-run (may be resolved or moved) -- **Resolved:** moved to `## Resolved` section with resolver work unit ID and date -- **Purged:** resolved findings older than 90 days are removed on re-run +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. Hard cap: 3000 words. On overflow: keep highest-severity, truncate INFO findings, note truncation. +Target 1000-2000 words, cap 3000. Overflow: keep highest-severity, truncate INFO. ## Freshness -Parse `Snapshot:` timestamp. Default staleness threshold: 30 days. Configurable via `config.audit.stalenessThresholdDays` (optional field, default 30). - -- Fresh: use as-is -- Stale: consumer may re-run or proceed without -- Missing: no warning, proceed without +`Snapshot:` timestamp. Stale after 30 days (configurable: `config.audit.stalenessThresholdDays`). Missing: proceed without. diff --git a/skills/sw-design/SKILL.md b/skills/sw-design/SKILL.md index 6cf16f3..6270c4b 100644 --- a/skills/sw-design/SKILL.md +++ b/skills/sw-design/SKILL.md @@ -59,7 +59,7 @@ When warranted: `decisions.md`, `data-model.md`, `contracts.md`, `testing-strate - 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):** diff --git a/skills/sw-learn/SKILL.md b/skills/sw-learn/SKILL.md index 0859f97..58b8b8a 100644 --- a/skills/sw-learn/SKILL.md +++ b/skills/sw-learn/SKILL.md @@ -54,22 +54,21 @@ 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, 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. If <2 files: 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):**