claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/core/commands/review.md

@@ -0,0 +1,195 @@
+---
+description: Unified review orchestrator — detect changes, dispatch reviewers, validate findings, optionally post GitHub inline comments
+argument-hint: "[base-branch | PR#number | --full] [--comment] (default: HEAD~1)"
+allowed-tools: Bash, Read, Grep, Glob, Agent
+---
+
+# Unified Orchestrated Code Review
+
+Detect changed files, dispatch specialized reviewer agents in parallel with injected git context, independently validate every finding, and produce a deduplicated report. Optionally post the results to a GitHub PR.
+
+## Target
+
+$ARGUMENTS
+
+## Hard Rules
+
+1. Review ONLY the diff scope — changed lines plus their surrounding context. Pre-existing issues outside the diff are out of scope (exception: `--full` reviews all tracked files).
+2. Dispatch each agent **at most once**, and only agents that exist in `.claude/agents/`.
+3. Every HIGH/MEDIUM-confidence finding passes independent validation (Step 5) before reaching the report. LOW-confidence (<60) items skip validation and go to **Open Questions** — never silently dropped.
+4. **goal-verifier** produces a verdict report (PASS / NEEDS-ATTENTION / NEEDS-REMEDIATION), not severity findings — its output bypasses Steps 4–6 validation and lands in its own report section.
+5. Zero confirmed findings is a valid outcome — report "clean" honestly, do not pad.
+
+## Step 1 — Parse Arguments and Detect Changes
+
+**Flags:** `--comment` → post GitHub PR comments (default: terminal only). Remaining argument → diff target.
+
+**Diff base:**
+- `PR#NNN` or a number → `gh pr diff $TARGET --name-only`
+- branch name → `git diff --name-only $TARGET...HEAD`
+- `--full` → all tracked files (`git ls-files`)
+- empty → `git diff --name-only HEAD~1`
+
+**Gather context** (run in parallel):
+```bash
+git diff --stat ${BASE}...HEAD        # changed files + line counts
+git diff ${BASE}...HEAD               # full hunks for agent injection
+git log --oneline -5                  # intent
+gh pr view $PR_NUMBER --json title,body 2>/dev/null   # PR mode only
+```
+
+Build a `REVIEW_CONTEXT` block:
+```
+=== REVIEW CONTEXT ===
+## PR Info (if available)
+Title / Description (first 500 chars)
+## Changed Files (N files, +X/-Y)
+<git diff --stat>
+## Recent Commits (intent)
+<git log --oneline -5>
+## Diff Hunks
+<diff, truncated to 8000 chars per agent if needed>
+=== END CONTEXT ===
+```
+
+## Step 2 — Map Files to Agents
+
+| File pattern | Agents |
+|---|---|
+| `*.go` (excluding `*_test.go`, migrations) | **go-reviewer**, **security-scanner** |
+| `migrations/*.sql` or `db/migrate/*.sql` | **migration-reviewer**, **database-reviewer** |
+| Data-access files (`*_repo.go`, repositories) | **database-reviewer** |
+| `*.tsx` | **ts-reviewer**, **design-system-reviewer** |
+| `*.ts` | **ts-reviewer** |
+| `*.py` | **py-reviewer**, **security-scanner** |
+| `*.rs` | **rs-reviewer** |
+| `**/bot*/**/*.go` or `**/bot*/**/*.py` | **bot-reviewer** |
+| `*.yaml` / `*.yml` (OpenAPI/GraphQL) | **api-contract-sync** |
+| Any changed code files | **silent-failure-hunter**, **comment-rot-analyzer** |
+| Any changed code files, IF an implementation plan exists in `docs/superpowers/plans/` | **goal-verifier** (verdict track — Hard Rule 4) |
+
+Rules: skip agents missing from `.claude/agents/`; if no files match any pattern, report "No reviewable changes detected" and stop; print the dispatch plan (agent + matched file count) before executing.
+
+## Step 3 — Dispatch All Agents in Parallel
+
+All triggered agents are independent — dispatch ALL of them simultaneously in one message. For each, inject the `REVIEW_CONTEXT` block filtered to its files:
+
+- **go-reviewer** → `*.go` hunks (minus tests/migrations) · **ts-reviewer** → `*.ts`/`*.tsx` · **py-reviewer** → `*.py` · **rs-reviewer** → `*.rs` · **migration-reviewer**/**database-reviewer** → SQL + data-access hunks · **bot-reviewer** → bot hunks · **design-system-reviewer** → `*.tsx`/`*.vue`/`*.svelte` UI hunks · **api-contract-sync** → spec hunks
+- Cross-cutting, receive ALL hunks: **security-scanner**, **silent-failure-hunter**, **comment-rot-analyzer**, **goal-verifier**
+
+Prompt template for each reviewer:
+```
+Start with Phase 0 — read project docs (CLAUDE.md/AGENTS.md + relevant docs/architecture/) before reviewing.
+
+{REVIEW_CONTEXT — filtered to your files}
+
+## Your Task
+Review the diff hunks against your checklist. Recent commits show intent — judge whether changes are complete and consistent with it. Focus on: contradictions with commit intent, missing pieces (e.g. "add endpoint" but no route registration), regressions in existing patterns.
+Report in your standard output format. Every finding MUST include: file, line, severity, confidence, description, evidence, fix.
+```
+
+Exception — **goal-verifier** (verdict track, Hard Rule 4): instead of the checklist task above, give it ALL hunks plus the implementation plan path from `docs/superpowers/plans/` and request its verdict report.
+
+## Step 4 — Collect and Triage Findings
+
+Merge all findings (excluding goal-verifier — verdict track). Each must carry: `file`, `line`, `severity` (CRITICAL/WARNING/SUGGESTION), `confidence` (HIGH ≥80 / MEDIUM 60–79 / LOW <60), `agent`, `description`, `evidence`, `fix`.
+
+Triage — route, don't drop:
+- LOW confidence → **Open Questions** bucket (appears in the final report; skips validation).
+- SUGGESTION from a non-primary reviewer for that file type → validate last; if you skip its validation, route it to Open Questions — never to the confirmed sections (Hard Rule 3).
+- Everything else → validation queue.
+
+## Step 5 — Validate Findings (Double Verification)
+
+Launch one validation agent PER FINDING, all in parallel:
+
+```
+You are a code review validator. Independently verify whether a reported issue is real.
+
+## Reported Issue
+Agent: {agent} · File: {file}:{line} · Severity: {severity}
+Description: {description}
+Evidence: {evidence}
+
+## Your Task
+1. Read the file at the reported location (the actual file, not the diff).
+2. Read ±20 lines of surrounding context.
+3. Decide: is the problem real? Could it be a false positive (pre-existing, intentional, linter-covered)? Is the severity right?
+
+## Verdict — reply with exactly one of:
+CONFIRMED — real and correctly described
+DOWNGRADE — real but severity should be lower (say which and why)
+REJECTED — false positive (say why)
+
+Be strict. When in doubt, REJECT — false positives waste more time than missed issues.
+```
+
+Apply verdicts: REJECTED → dropped (counted in validation stats); DOWNGRADE → severity adjusted; CONFIRMED → kept. Validators reading the real file also catch stale/wrong line references.
+
+## Step 6 — Deduplicate and Report
+
+1. Deduplicate: same file:line flagged twice → keep the higher-severity confirmed finding.
+2. Group and print:
+
+```
+### Blocking (CRITICAL confirmed)
+- [agent] file:line — description
+### Important (WARNING confirmed)
+- [agent] file:line — description
+### Nit (SUGGESTION confirmed)
+- [agent] file:line — description
+### Open Questions (LOW confidence — surfaced, not dropped)
+- [agent] file:line — suspicion + what would confirm it
+### Goal Verification (only if goal-verifier ran)
+Verdict: PASS / NEEDS-ATTENTION / NEEDS-REMEDIATION + its gap list verbatim
+```
+
+3. Summary table:
+
+| Agent | Blocking | Important | Nit | Raw | Confirmed | Status |
+|-------|----------|-----------|-----|-----|-----------|--------|
+| go-reviewer | 0 | 2 | 1 | 5 | 3 | PASS |
+
+Status per agent: **FAIL** if any Blocking, **WARN** if Important only, **PASS** otherwise.
+
+4. Validation stats: "X findings reported → Y confirmed (Z% hit rate), R rejected".
+
+5. Confidence distribution:
+
+| Band | Count | Route |
+|------|-------|-------|
+| HIGH (80–100) | N | validated (Step 5) |
+| MEDIUM (60–79) | N | validated (Step 5) |
+| LOW (<60) | N | Open Questions — surfaced, not dropped |
+
+### Overall Verdict
+**PASS / WARN / FAIL** — FAIL if any Blocking confirmed; WARN if Important only; PASS otherwise. One line naming the most critical confirmed finding (or "clean").
+
+## Step 7 — Post GitHub Comments (only if --comment)
+
+No `--comment` → stop here (terminal output only).
+
+With `--comment`, post ONE summary comment via `gh pr comment $PR_NUMBER --body "..."` containing: confirmed-issue count (raw → confirmed), the Blocking/Important lists with GitHub permalinks, the summary table, and the validation hit rate. If zero confirmed issues, post the clean-review variant ("No issues found. Agents dispatched: […]. Findings: 0 confirmed of X raw.").
+
+Permalink format (exact, or GitHub won't render):
+```
+https://github.com/OWNER/REPO/blob/FULL_SHA/path/to/file.ext#LSTART-LEND
+```
+`FULL_SHA` = full 40-char `git rev-parse HEAD`; include ≥1 context line on each side in the range.
+
+## Done ONLY when
+
+- [ ] Every agent in the printed dispatch plan returned (or is named as skipped/failed — never silently absent).
+- [ ] Every HIGH/MEDIUM finding carries an applied validation verdict (CONFIRMED / DOWNGRADE / REJECTED).
+- [ ] Dedup ran and the full report printed: severity groups + summary table + validation stats + confidence distribution + Overall Verdict.
+- [ ] If `--comment` was given: the PR comment was actually posted (show the `gh` output).
+
+Not all boxes checked → say what is missing; do not claim the review is complete.
+
+## Recap — non-negotiables
+
+- Diff scope only (unless `--full`); pre-existing issues are not findings.
+- Every reported finding survived independent validation; LOW confidence → Open Questions, never dropped silently.
+- goal-verifier is a verdict, not findings — separate report section.
+- Clean review is a valid review.
+- `--comment` requires an authenticated `gh` CLI.

package/packages/core/commands/security-scan.md

@@ -0,0 +1,142 @@
+---
+description: Run AgentShield security scan on .claude/ configurations — detect secrets, permission issues, hook injection, MCP vulnerabilities
+argument-hint: "[--fix] [--opus] [--format json|markdown]"
+allowed-tools: Bash, Read
+---
+
+# Security Scan
+
+Run AgentShield to audit `.claude/` configurations for vulnerabilities (102 rules, 5 categories), then report the score and findings.
+
+## Target
+
+$ARGUMENTS
+
+## Hard Rules
+
+- Report ONLY what the scanner actually output — never invent a score, grade, or finding. If the scan cannot run or exits with an error, report that error and stop.
+- AgentShield grades on its own scale `critical / high / medium / low`. Relay it verbatim; do NOT remap it to the kit's CRITICAL / WARNING / SUGGESTION.
+- Run the scan at most once, using the single Step 2 command that matches the flags in Target.
+- `--opus` needs `ANTHROPIC_API_KEY` set in the environment; if it is unset, run without `--opus` and say so.
+- Emit the report only after the scan command has actually returned.
+
+## Step 1 — Check AgentShield availability
+
+```bash
+npx ecc-agentshield --version
+```
+
+Branch on the result:
+- **Prints a version** → installed; go to Step 2.
+- **Errors because the package is not cached yet** → `npx` will download `ecc-agentshield` on first run in Step 2; go to Step 2.
+- **`npx` unavailable, no network, or download fails** → report `AgentShield unavailable: <error>` and stop. Do not fabricate results.
+
+Done when: you know whether the scan can run.
+
+## Step 2 — Run the scan
+
+Select ONE command by the flags in Target (flags are independent; if Target names more than one, append each form to the single `scan` command):
+
+| Flag in Target | Command |
+|----------------|---------|
+| (none) | `npx ecc-agentshield scan` |
+| `--fix` | `npx ecc-agentshield scan --fix` — auto-remediate safe issues |
+| `--opus` | `npx ecc-agentshield scan --opus --stream` — AI deep analysis (needs `ANTHROPIC_API_KEY`) |
+| `--format json` | `npx ecc-agentshield scan --format json` — for CI integration |
+| `--format markdown` | `npx ecc-agentshield scan --format markdown` — for reports |
+
+If the command exits non-zero for a reason other than findings-present (e.g. a crash), report the exit code and stderr; do not invent a score.
+
+Done when: the scan command has returned output, or its failure has been captured.
+
+## Step 3 — Report results
+
+Extract from the scanner output and fill the Output Contract:
+- Security score (0–100) and grade (A–F)
+- Findings grouped by AgentShield severity: `critical → high → medium → low`
+- Category breakdown (secrets, permissions, hooks, MCP, agents)
+
+Threshold rules:
+- Score < 70 → recommend re-running with `--fix`.
+- Any `critical` findings → list the specific files and remediation steps.
+
+Done when: score, grade, findings-by-severity, category breakdown, and the recommendation line are all present in the report.
+
+## What it checks (102 rules)
+
+| Category | Rules | Examples |
+|----------|:-----:|---------|
+| Secrets | 10 | API keys, tokens, passwords in config files |
+| Permissions | 10 | Wildcard Bash(*), missing deny lists |
+| Hooks | 34 | Command injection, data exfiltration, silent error suppression |
+| MCP Servers | 23 | Supply chain (npx -y), shell metacharacters, network exposure |
+| Agent Configs | 25 | Prompt injection, hidden instructions, auto-run directives |
+
+## Output Contract
+
+```
+## Security Scan — AgentShield
+
+Score: <0-100>   Grade: <A-F>
+Command run: <exact command from Step 2>
+
+### Findings by severity (AgentShield scale, not the kit's)
+| Severity | Count |
+|----------|:-----:|
+| critical | <N> |
+| high     | <N> |
+| medium   | <N> |
+| low      | <N> |
+
+### Category breakdown
+| Category      | Findings |
+|---------------|:--------:|
+| Secrets       | <N> |
+| Permissions   | <N> |
+| Hooks         | <N> |
+| MCP Servers   | <N> |
+| Agent Configs | <N> |
+
+### Critical findings   (only if any)
+- <file> — <issue> → <remediation>
+
+Recommendation: <e.g. "Score 62 < 70 — re-run with --fix" | "No critical findings; score 88 (B)">
+```
+
+Mini example:
+
+```
+## Security Scan — AgentShield
+
+Score: 62   Grade: D
+Command run: npx ecc-agentshield scan
+
+### Findings by severity (AgentShield scale, not the kit's)
+| Severity | Count |
+|----------|:-----:|
+| critical | 1 |
+| high     | 3 |
+| medium   | 5 |
+| low      | 2 |
+
+### Category breakdown
+| Category      | Findings |
+|---------------|:--------:|
+| Secrets       | 1 |
+| Permissions   | 4 |
+| Hooks         | 3 |
+| MCP Servers   | 2 |
+| Agent Configs | 1 |
+
+### Critical findings
+- .claude/settings.json — hardcoded API key in env block → move to a secret manager / .env not committed
+
+Recommendation: Score 62 < 70 — re-run with --fix.
+```
+
+## Recap — non-negotiables
+
+- Never fabricate a score or finding; the scan must actually run first, and a failed scan is reported as an error.
+- AgentShield's `critical/high/medium/low` is the tool's own scale — relay it verbatim, do not remap.
+- Run the scan at most once, matching the Target flags.
+- Score < 70 → recommend `--fix`; any `critical` finding → list the files and their remediation.

package/packages/core/commands/superkit-evolve.md

@@ -0,0 +1,231 @@
+---
+description: Incremental documentation update — detect drift, fix stale docs, add missing coverage
+argument-hint: "[--fix-all]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent
+---
+
+# Superkit Evolve — Incremental Documentation Update
+
+Detect what is outdated or missing in the documentation of a project already using superkit, then fix it. Six drift checks → report → confirmed fixes → verified commit.
+
+## Mode
+
+$ARGUMENTS
+
+| Arguments | Mode | Behavior |
+|-----------|------|----------|
+| (empty) | interactive | Report issues in Step 7, ask before fixing |
+| `--fix-all` | automatic | Print the Step 7 scan block, skip the prompt, fix everything except [UNKNOWN] |
+
+## Hard Rules
+
+1. Run ALL six checks (Steps 1–6) before reporting. A check whose command fails or whose value cannot be parsed records an **[UNKNOWN]** issue with the reason — never guess a value, never claim drift from an unparsed value.
+2. Interactive mode: fix NOTHING until the user confirms in Step 7.
+3. Touch only documentation and config: `docs/`, `CLAUDE.md`, `.claude/rules/`, `.claude/scripts/hooks/`. Never edit application source code.
+4. Canonical architecture doc names are the shipped template names (Step 2 table): `api-reference.md`, `frontend-state.md`, etc. Do not check for or generate other spellings.
+5. A fix counts as FIXED only after re-running the check that produced the issue and seeing it pass.
+6. Use the portable commands below as written — they run on both macOS and Linux. Do not substitute `grep -P` or `stat -f` variants.
+7. Zero issues is a valid result — emit the final report saying so; do not manufacture drift.
+
+## Step 1 — Migration Counter Drift
+
+```bash
+# Count actual migrations
+ACTUAL=$(find . -path "*/migrations/*" -name "*.up.sql" -not -path "*/node_modules/*" 2>/dev/null | wc -l | tr -d ' ')
+# Extract claimed upper counter from CLAUDE.md: last NNN..NNN range on the first matching line, zero-padding stripped
+CLAIMED=$(grep -E '[0-9]{3,}\.\.[0-9]{3,}' CLAUDE.md 2>/dev/null | head -1 | sed -n 's/.*\.\.0*\([1-9][0-9]*\).*/\1/p')
+```
+
+Branches (exactly one applies):
+- `ACTUAL` is 0 but a `migrations/` directory exists → recount with `-name "*.sql"` (project without `.up/.down` split), then continue below.
+- No migrations in the project at all → no issue, done.
+- `CLAIMED` empty while `ACTUAL > 0` → issue `[UNKNOWN] Migration counter not parseable from CLAUDE.md (actual: $ACTUAL)`.
+- `CLAIMED != ACTUAL` → issue `[DRIFT] Migration counter (CLAUDE.md: $CLAIMED, actual: $ACTUAL)`.
+- `CLAIMED == ACTUAL` → no issue.
+
+Done when: one branch recorded.
+
+## Step 2 — Missing Architecture Docs
+
+For each detected component, run the check:
+
+| Component present | Expected doc | Check |
+|-------------------|-------------|-------|
+| `go.mod` or backend code | `backend-layers.md` | `test -f docs/architecture/backend-layers.md` |
+| API route files | `api-reference.md` | `test -f docs/architecture/api-reference.md` |
+| `migrations/` dir | `database-schema.md` | `test -f docs/architecture/database-schema.md` |
+| Auth code | `auth-and-sessions.md` | `test -f docs/architecture/auth-and-sessions.md` |
+| Frontend code | `frontend-state.md` | `test -f docs/architecture/frontend-state.md` |
+| Docker/CI files | `deployment.md` | `test -f docs/architecture/deployment.md` |
+
+Component present + check fails → issue `[MISSING] docs/architecture/<doc>`.
+
+Done when: every row with a present component was tested.
+
+## Step 3 — Tree Freshness
+
+```bash
+NEWEST_TREE=$(ls -t docs/trees 2>/dev/null | grep '^tree-.*\.md$' | head -1)
+if [ -n "$NEWEST_TREE" ]; then
+  NEWEST_TREE="docs/trees/$NEWEST_TREE"
+  # Parentheses group the -name alternatives so -newer applies to ALL of them
+  NEW_FILES=$(find . -newer "$NEWEST_TREE" \
+    \( -name "*.go" -o -name "*.ts" -o -name "*.tsx" -o -name "*.py" \) \
+    -not -path "*/node_modules/*" -not -path "*/.git/*" | wc -l | tr -d ' ')
+fi
+```
+
+Branches:
+- `NEWEST_TREE` empty → issue `[MISSING] No tree files in docs/trees/`.
+- `NEW_FILES > 10` → issue `[STALE] Tree outdated — $NEW_FILES new source files since last generation`.
+- Otherwise → no issue.
+
+Done when: one branch recorded.
+
+## Step 4 — Rule Path Validity
+
+Verify every path referenced in `.claude/rules/documentation.md` still exists:
+
+```bash
+grep -o '`[^`]*`' .claude/rules/documentation.md 2>/dev/null | tr -d '`' | while read -r pattern; do
+  case "$pattern" in
+    */*) sh -c "ls -- $pattern" >/dev/null 2>&1 || echo "BROKEN PATH: $pattern" ;;  # sh -c expands globs in any parent shell
+  esac
+done
+```
+
+Only strings containing `/` are treated as paths; other backticked spans (commands, names) are skipped.
+
+- Rule file absent → issue `[MISSING] .claude/rules/documentation.md not installed`.
+- Each `BROKEN PATH` line → issue `[BROKEN] Rule path: <pattern>`.
+
+Done when: rule file checked and every path-like span tested.
+
+## Step 5 — New Components Without Docs
+
+```bash
+for dir in */ ; do
+  d=${dir%/}
+  case "$d" in node_modules|vendor|dist|build|docs|test|tests) continue ;; esac
+  SRC=$(find "$d" \( -name "*.go" -o -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.rs" \) \
+    -not -path "*/node_modules/*" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$SRC" -ge 5 ] && ! ls docs/architecture 2>/dev/null | grep -Fq -- "$d"; then
+    echo "UNDOCUMENTED: $d ($SRC source files)"
+  fi
+done
+```
+
+Then filter: drop any `UNDOCUMENTED` line whose directory is a conventional source root (`src`, `app`, `cmd`, `internal`, `pkg`, `lib`) already covered by an existing Step 2 doc (`backend-layers.md` for backend roots, `frontend-state.md` for frontend roots). Each remaining line → issue `[MISSING] No docs for <dir>/ component`.
+
+Done when: every top-level code directory flagged or explicitly covered.
+
+## Step 6 — CLAUDE.md Staleness
+
+Read `CLAUDE.md` and run three sub-checks:
+- **Versions** — compare each version in the tech-stack table against actual `go.mod` / `package.json`. Mismatch → issue `[DRIFT] CLAUDE.md stack table: <component> says X, actual Y`.
+- **Coverage** — list `docs/architecture/` (Glob or `ls`); a doc on disk missing from the Architecture Reference table → issue `[DRIFT] Architecture table missing <doc>`.
+- **Dead links** — a doc path referenced in CLAUDE.md that fails `test -f` → issue `[BROKEN] Dead reference: <path>`.
+
+Done when: all three sub-checks ran.
+
+## Step 7 — Report and Confirm
+
+Print the scan block (both modes):
+
+```
+📊 superkit-evolve scan complete — 6/6 checks run
+
+Found N issues:
+
+  1. [DRIFT]   Migration counter: CLAUDE.md says 48, actual is 50
+  2. [MISSING] No docs for workers/ component
+  3. [STALE]   Tree outdated — 22 new files since last generation
+  4. [BROKEN]  Rule path: services/feed/*.go → should be services/feed_engine/*.go
+  5. [UNKNOWN] Migration counter not parseable from CLAUDE.md
+
+Fix? [yes / issue numbers / no]
+```
+
+If `N == 0`: skip Steps 8–9, go straight to Output.
+
+**Interactive mode** — handle the reply:
+
+| Reply | Action |
+|-------|--------|
+| `yes` | fix every issue |
+| issue numbers (e.g. `1 3`) | fix only those; mark the rest `SKIPPED (user)` |
+| `no` / `skip` | fix nothing; mark all `SKIPPED (user)`; still emit the Output report |
+| anything else | ask once more; still unclear → treat as `no` |
+
+**--fix-all mode**: print the scan block without the final `Fix?` line; fix every issue without waiting. In BOTH modes, `[UNKNOWN]` issues are never fixed automatically — mark them `SKIPPED (needs human)`.
+
+Done when: every issue has a decision (fix or skip).
+
+## Step 8 — Fix
+
+For each issue selected for fixing:
+
+| Issue | Fix |
+|-------|-----|
+| Migration counter drift | Update the migration range in CLAUDE.md to the actual count |
+| Missing architecture doc | Generate from code following the /superkit-init doc-generation procedure; use the canonical name from the Step 2 table |
+| Stale tree | Regenerate `docs/trees/` using tree/find |
+| Broken rule path | Grep for where the files moved, update the rule with the correct path |
+| CLAUDE.md staleness | Re-read go.mod/package.json, update versions; sync the Architecture Reference table |
+| New component without docs | Generate an architecture doc named `<component>-<topic>.md` |
+| Dead architecture reference | Doc should exist → regenerate it; obsolete → remove the reference |
+
+After each fix, re-run the Step 1–6 check that produced the issue: pass → `FIXED`; fail → retry the fix once; still failing → `SKIPPED (fix failed: <error>)`.
+
+Done when: every selected issue is FIXED or SKIPPED (fix failed).
+
+## Step 9 — Commit
+
+Only when at least one issue is FIXED:
+
+```bash
+git add docs/ CLAUDE.md .claude/rules/ .claude/scripts/hooks/
+git commit -m "docs: superkit-evolve — fix N documentation issues
+
+Fixed:
+- [list of fixes]
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+git rev-parse --short HEAD
+```
+
+Done when: commit created and sha captured, or no fixes were applied.
+
+## Output
+
+End with exactly this report:
+
+```
+✅ superkit-evolve complete
+
+| # | Issue | Result |
+|---|-------|--------|
+| 1 | [DRIFT] Migration counter 48 → 50 | FIXED |
+| 2 | [MISSING] No docs for workers/ | SKIPPED (user) |
+
+Checks run: 6/6 · Found: 2 · Fixed: 1 · Skipped: 1
+Commit: a1b2c3d
+```
+
+- `Found: 0` → table replaced by the line `No documentation drift detected.`
+- No fixes applied → `Commit: none`.
+
+## Done ONLY when
+
+- [ ] All six checks (Steps 1–6) ran; command failures recorded as [UNKNOWN], not guessed.
+- [ ] Every issue in the final table is FIXED (its check re-run and passing) or SKIPPED with a reason.
+- [ ] Commit created if at least one fix was applied, and its sha is in the report.
+- [ ] Final report emitted in the exact Output format.
+
+## Recap
+
+- All six checks run before any report; unparseable values become [UNKNOWN], never claimed drift.
+- Interactive mode fixes nothing without confirmation; `--fix-all` fixes everything except [UNKNOWN].
+- Docs and config only — never application source code.
+- FIXED means the originating check was re-run and passes; then commit, sha in the report.
+- Canonical doc names come from the Step 2 table (`api-reference.md`, `frontend-state.md`).