project-audit

What this skill does

# 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