superkit-evolve

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

# 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.