fearovex/project-audit

project-audit

Triggers: /project-audit, audit project, review claude config, sdd diagnostic, project health check

---

<!-- Structural floor ~440 lines. Add new content to sibling files, not here. -->

Read-only diagnostic of Claude/SDD config. Flow: /project-audit → audit-report.md → /project-fix → /project-audit (verify). The report IS the spec /project-fix implements. Kernel: discovery → evaluation → report (stable; rules evolve). Save report at [project_root]/.claude/audit-report.md.

Sibling reference files — REPORT_TEMPLATE.md (output format), SCORING.md (100-point distribution + interpretation), PHASE_A_SCRIPT.md (discovery script + schema).

Dimension classes

| Class | Dimensions | Score impact | |---------------|-----------------------------|--------------| | Scored | D1, D2, D3, D4, D6, D7, D8 | 100-pt score | | Informational | D9, D10, D11, D12, D13, D14 | None |

D5 was removed. Informational dimensions never affect score unless stated.

Compatibility policy — global-config exemptions

IS_GLOBAL_CONFIG=1 → the methodology repo is not a consumer of its own deployment. Skip table:

| Dim. | Check | Skip when global-config | |------|-------------------------------|-------------------------| | D1 | Stack / package.json | Skip | | D1 | ## Architecture section | Skip (in README) | | D1 | Skills registry | Skip ALWAYS (Principle 2 — harness auto-discovers) | | D1 | ai-context/ path refs | Skip | | D2 | Memory (ai-context/) | Skip dim; N/A in score | | D4a | Registry vs disk | Skip |

Rationale: ai-context/ is deployed BY this repo INTO consumer projects via /project-setup — auditing the methodology repo for it is a category error. Scoring: D2 → N/A; denominator becomes 75. Final = round(actual/75*100).

---

Process

Read real files. Never assume. Run dimensions systematically.

Phase A — Discovery

Run PHASE_A_SCRIPT.md once; capture key=value outputs; run the post-script "Legacy commands/ detection". Max 3 Bash calls total per audit run.

Phase B — Per-dimension evaluation

Apply each dimension. Findings carry severity (CRITICAL/HIGH/MEDIUM/LOW/INFO) and optional FIX_MANIFEST entries.

Dimension 1 — CLAUDE.md

Project type detection: IS_GLOBAL_CONFIG=1 → global-config. Accept root CLAUDE.md as equivalent to .claude/CLAUDE.md. Note Project Type in report.

| Check | Severity | |--------------------------------------------------------|----------| | Exists .claude/CLAUDE.md (or root for global-config) | CRITICAL | | Not empty (>50 lines) | CRITICAL | | Has Stack section (## Tech Stack or ## Stack) | CRITICAL | | Stack has ≥ 3 technologies with explicit versions | CRITICAL | | Stack matches package.json / pyproject.toml | HIGH | | Has ## Architecture section | HIGH | | Has Skills registry | HIGH | | Has Unbreakable Rules section | MEDIUM | | Has Plan Mode section | LOW | | Mentions SDD (/sdd-*) | HIGH | | References to ai-context/ paths are correct | MEDIUM |

Stack severity is CRITICAL per ADR-004 (every tech-reference skill routes on it). Exemptions under IS_GLOBAL_CONFIG=1: see "Compatibility policy".

Stack comparison: extract top 5–10 deps from package.json/equivalent, compare with CLAUDE.md. Report discrepancies as declared X.Y, actual A.B.

Template path verification: locate ## Documentation Conventions section, extract paths matching docs/templates/*.md, verify each exists. Each missing → MEDIUM + required_actions.medium type: create_file. Skip entirely if no such pattern found.

---

Dimension 2 — Memory (ai-context/)

Skip entirely when IS_GLOBAL_CONFIG=1 — emit INFO "D2 skipped — global-config repos do not use ai-context/". D2 → N/A (25 pts excluded from denominator). See Compatibility policy.

For standard projects:

| File | Min lines | Note | |-------------------------------|-----------|---------------------------------| | ai-context/stack.md | > 30 | | | ai-context/architecture.md | > 40 | | | ai-context/conventions.md | > 30 | | | ai-context/known-issues.md | > 10 | may be brief for new projects | | ai-context/changelog-ai.md | > 5 | at least one entry |

Location may be ai-context/ or docs/ai-context/. Check both.

Content checks (per existing file):

• stack.md: top-5 dependency versions match package.json.
• architecture.md: directories named exist on disk.
• conventions.md: documented conventions appear in 2–3 sample real files.
• known-issues.md: real content vs. [To confirm]/[Empty] stubs.
• changelog-ai.md: at least one ## YYYY-MM-DD entry.

Placeholder phrase detection — scan content for (case-insensitive in brackets, case-sensitive for plain TODO): [To be filled], [empty], [TBD], [placeholder], [To confirm], [Empty], plain uppercase TODO. Each match → HIGH "[filename] appears to contain unfilled placeholder content". Treat the file as functionally empty even if line count passes. Add to required_actions.high with type: update_file.

stack.md version count — count lines matching x.y, x.y.z, or vX. < 3 → MEDIUM "stack.md lists fewer than 3 technologies with concrete versions — minimum is 3". Skip when stack.md absent or already placeholder.

User documentation freshness (for ai-context/scenarios.md and ai-context/quick-reference.md):

• Absent → LOW "[filename] missing — create via /project-onboard or manually".
• Present → search first 10 lines for ^> Last verified: (\d{4}-\d{2}-\d{2})$. Missing/malformed → LOW. > 90 days old → LOW with age. All findings LOW, no D2 score deduction.

---

Dimension 3 — SDD Orchestrator

3a. Global SDD skills — 8 phase skills must exist in ~/.claude/skills/: sdd-explore, sdd-propose, sdd-spec, sdd-design, sdd-tasks, sdd-apply, sdd-verify, sdd-archive. Any missing → CRITICAL.

3b. Engram availability — call mem_context. Reachable → INFO log. Unreachable → HIGH "Engram not reachable — SDD artifacts will not persist".

3c. CLAUDE.md mentions SDD — contains any /sdd-* → HIGH if absent; section explaining SDD flow → LOW if absent.

3d. Orphaned changes — mem_search(query: "sdd/", project: "{project}"), filter for state artifacts with last_updated > 14 days ago and no archive-report. List them.

3e. Hook script existence — for each settings file present (settings.json, .claude/settings.json, settings.local.json), locate hooks key and extract script paths. Each missing on disk → HIGH + required_actions.high type: create_file. Skip when no hooks key.

3f. Active changes conflict detection:

1. Search engram for active changes (no archive-report). Retrieve each design.md.
2. Locate ## File Change Matrix table. Extract File column. Normalize: lowercase + strip leading ./.
3. Skip if fewer than 2 active changes have a design.md.
4. Intersect path sets. Each overlap → MEDIUM "Concurrent file modification conflict: [path] is targeted by both [change-A] and [change-B]". Add to violations[], rule: "D3-active-changes-conflict".

Normalization only handles lowercase + leading ./. Other format inconsistencies are not caught.

---

Dimension 4 — Skills quality

4a. Registry vs disk (bidirectional): each skill in CLAUDE.md exists on disk; each skill on disk appears in CLAUDE.md. Report mismatches both ways.

Skip 4a when IS_GLOBAL_CONFIG=1 (no manual registry exists; Principle 2). Emit INFO "D4a skipped — harness auto-discovery, not a manual registry". 4b and 4c still apply.

4b. Minimum content — for each skill file:

• < 30 lines → probable stub.
• Format-aware structural check (see docs/format-types.md):
  1. Parse YAML frontmatter, extract format:. Absent → treat as procedural.
  2. Unknown value → INFO, treat as procedural.

| Resolved format | Required sections | Finding if absent (MEDIUM) | |-----------------|------------------------------------------------------------------------------------------------|----------------------------| | procedural | ## Process | "procedural skill [name] missing ## Process section" | | reference | At least one of ## Patterns/## Critical Patterns AND one of ## Examples/## Code Examples | "reference skill [name] missing (## Patterns or ## Critical Patterns) or (## Examples or ## Code Examples)" | | anti-pattern | ## Anti-patterns OR ## Critical Patterns | "anti-pattern skill [name] missing ## Anti-patterns or ## Critical Patterns section" |

Missing **Triggers** or ## Rules → MEDIUM for all formats. Missing ## Process is NOT a finding for reference/anti-pattern.

Each finding → required_actions.medium, type: skill_quality_action, action_type: add_missing_section, target: [skill path], missing_sections: ["[heading]"].

4c. Relevant tech skills coverage (scored 0–10 pts):

Stack → skill mapping: React 18+ → react-19, Next.js 14+ → nextjs-15, TypeScript → typescript, Zustand → zustand-5, Tailwind → tailwind-4, Zod → zod-4, Playwright → playwright, Prisma → prisma, React Native / Expo → react-native, Go → go-testing.

Coverage rule (tech-skill locality policy): a skill counts as "covered" if it exists EITHER in the project's local .claude/skills/<name>/ OR in the global ~/.claude/skills/<name>/. Tech skills are expected to live locally; only meta/orchestrator skills are expected globally. Penalizing a project for not having zod-4 globally when it has it locally is a category error.

| Coverage of applicable skills | Points | |--------------------------------|--------| | 100% covered OR no applicable | 10 | | ≥ 75% | 8 | | 50–74% | 5 | | 25–49% | 2 | | < 25% | 0 |

"Applicable" = project uses the tech AND a matching skill exists locally or globally. D4 max: 20 pts (4a+4b = 10; 4c = 10).

---

Dimension 6 — Cross-reference integrity

Everything referenced in the Claude configuration must exist on disk.

| Source | Target | |-----------------------------------|-----------------------------------------------------| | ## Documentation in CLAUDE.md | .claude/docs/ | | Templates section in CLAUDE.md | .claude/templates/ | | Paths inside skills | /lib/, /domain/, pages/api/, etc. | | ai-context/architecture.md dirs | Project filesystem | | Skills referenced in commands | The skill file |

Each broken reference: source file, approximate line, missing path.

---

Dimension 7 — Architecture compliance

Input: analysis-report.md at project root (produced by /project-analyze).

| Condition | Score | Severity | Message | |--------------------------------------------|-------|----------|-----------------------------------------------------------| | analysis-report.md absent | 0/5 | CRITICAL | "Run /project-analyze first, then re-run /project-audit" | | Present + architecture.md absent | 2/5 | HIGH | "No architecture baseline to compare against" | | Drift = none | 5/5 | OK | | | Drift = minor | 3/5 | MEDIUM | List drift entries | | Drift = significant | 0/5 | HIGH | List drift entries |

Staleness penalty (when ANALYSIS_REPORT_EXISTS=1):

| Age | Deduction | |--------------|-------------------| | ≤ 30 days | none | | 31–60 days | −1 pt (floor: 0) | | > 60 days | −2 pts (floor: 0) |

Emit "analysis-report.md is [N] days old — staleness penalty applied". Stacks with drift; combined floor 0.

When drift is minor/significant, read ## Architecture Drift from the report and list entries.

D7 violations go in violations[] only — NOT required_actions. /project-fix does not auto-fix architecture drift.

---

Dimension 8 — Testing & verification

8a. Test runner configured or detectable → HIGH if missing. Documented testing strategy in ai-context/ → MEDIUM if missing.

8b. For each archive-report in engram, verify a verify-report exists and references tool execution results. Missing → HIGH.

8c. For each active change with tasks, verify the task plan includes verification criteria. For each with design, verify the design defines test approach.

---

Dimension 9 — Project skills quality (informational)

Skip when $LOCAL_SKILLS_DIR does not exist — emit "No [value] directory found — Dimension 9 skipped". No deduction.

Global-config circular detection: when auditing the global-config repo, every subdir under skills/ has a matching counterpart in ~/.claude/skills/ (same files via install.sh). Disposition keep for all — expected.

D9-2 Duplicate — for each subdir under $LOCAL_SKILLS_DIR: ~/.claude/skills/<name>/ exists → disposition move-to-global (if differs) or delete (if identical). Global catalog unreadable → INFO, disposition keep.

D9-3 Structural completeness — apply D4b format-aware check. Missing required section OR missing SKILL.md → disposition update, action add_missing_section.

D9-4 Language compliance — D4e heuristic on body text outside fenced code. Non-English prose → disposition update, action flag_language_violation, severity INFO (no deduction).

D9-5 Stack relevance — technology references in trigger line and title. If absent from both ai-context/stack.md AND package.json/pyproject.toml → disposition update, action flag_irrelevant, severity INFO. No stack source → emit "Stack relevance check skipped — no stack source found".

---

Dimension 10 — Feature docs coverage (informational)

Skip when no features detected.

Config-driven — if project config.yaml has feature_docs: key, read convention (skill|markdown|mixed), paths, and feature_detection.

Heuristic fallback — sources, in order:

1. Non-SDD skills in $LOCAL_SKILLS_DIR (names not starting with sdd-, project-, memory-, skill-).
2. *.md files in docs/features/ or docs/modules/.
3. Subdirs of src/features/, src/modules/, app/ with a README.md.

Exclude always: shared, utils, common, lib, types, hooks, components. Empty after exclusions → emit "No feature directories detected — Dimension 10 skipped".

Per-feature checks:

• D10-a Coverage: PASS if doc exists per convention; FAIL otherwise.
• D10-b Structure: SKILL.md → PASS if frontmatter + **Triggers** + ## Process + ## Rules. Other .md → PASS if H1 + ≥1 H2.
• D10-c Freshness: extract paths /src/[^\s]+, /lib/[^\s]+, /app/[^\s]+. Each missing → flag stale.
• D10-d Registry alignment: SKILL.md in .claude/skills/ not in CLAUDE.md registry → INFO (not a warning).

D10 findings MUST NOT appear in required_actions or skill_quality_actions.

---

Dimension 11 — Internal coherence (informational)

Read/Glob/Grep only — no Bash. Skip when neither $LOCAL_SKILLS_DIR nor root CLAUDE.md exists.

D11-a Count consistency — extract claims via CLAIM_PATTERN = /(\d+)\s+(Dimensions?|Steps?|Rules?|Phases?|Checks?|Sub-checks?)/i from headings and blockquote lines. Count matching body sections. Mismatch → INFO. Do NOT match inside code blocks.

D11-b Numbering continuity — patterns: /^#{2,3}\s+.*Step\s+(\d+)/im, Dimension\s+(\d+), Phase\s+(\d+), /^#{2,4}\s+.*D(\d+)/m. Sort numbers, detect gaps and duplicates. ≥ 2 members required. Severity INFO.

D11-c Frontmatter-body alignment — if description has a numeric claim, verify via D11-a logic. Mismatch → INFO.

All D11 findings → violations[], severity info, rule names D11-count-consistency, D11-numbering-continuity, D11-frontmatter-body. Never in required_actions.

---

Dimension 12 — ADR coverage (informational)

Activation: CLAUDE.md contains string docs/adr/. If absent → emit INFO, skip.

D12-1: ADR_README_EXISTS=0 → HIGH "CLAUDE.md references docs/adr/ but docs/adr/README.md is missing" + required_actions.high type: create_file.

D12-2: Glob docs/adr/NNN-*.md. No matches → INFO "docs/adr/ contains no ADR files yet". Each ADR: search ## Status heading or frontmatter status: field. Neither → MEDIUM "ADR file [filename] is missing a valid status field" + required_actions.medium type: update_file. Valid: accepted, deprecated, superseded; custom allowed, do not validate value.

---

Dimension 13 — Spec coverage (informational)

Activation: Engram reachable AND mem_search(query: "sdd/") returns spec artifacts.

D13-1: For each spec.md, extract path-like references (contain /, no spaces, not in URLs or fenced code). Check existence at [project_root]/[path]. Missing → INFO "Spec artifact references a path that no longer exists: [path]". Add to violations[], rule: "D13-stale-path-reference", severity: "info", file: "engram spec artifact". INFO findings NOT in required_actions.

---

Dimension 14 — Budget compliance (informational)

Runs on every audit.

1. Read CLAUDE.md at project root; count characters.
2. Global-config (install.sh + sync.sh exist) → 20,000 char budget; otherwise → 5,000.
3. Over budget → INFO "CLAUDE.md is [N] chars ([N-budget] over [budget] budget). Consider extracting content to skills (ADR-041)".
4. Within → INFO "CLAUDE.md budget OK: [N]/[budget] chars".

Findings go in ## Budget Compliance section. No score impact.

---

Report

Save at [project_root]/.claude/audit-report.md using the exact structure in REPORT_TEMPLATE.md. Scoring distribution and interpretation live in SCORING.md.

---

Rules

1. Always read real files. Never assume content.
2. Run in a subagent with read tools. Never in main context.
3. Always save the report at .claude/audit-report.md before presenting.
4. The FIX_MANIFEST is valid YAML. Verify the block parses.
5. Never modify anything. 100% read-only.
6. If a file cannot be read, report ❌ with the exact error. Do not assume absence.
7. When finished: "Report saved in .claude/audit-report.md. To implement: /project-fix".
8. All shell discovery in Phase A. Max 3 Bash calls per run. No per-dimension ls/grep/wc -l/find.
9. Compatibility behavior is explicit, not implicit in a dimension.