claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/codex/skills/writing-commands/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: writing-commands
+description: Use when creating or revising a Codex user-invocable workflow skill, including its inputs, phases, delegation, verification, or completion contract.
+user-invocable: false
+tokens: 2280
+---
+
+# Writing Codex User-Invocable Skills
+
+A command-like Codex workflow is a skill in
+`.codex/skills/<skill-name>/SKILL.md` with `user-invocable: true`, rather than a
+Claude slash-command file. Author one defined outcome with explicit inputs,
+authority, verification, and a stopping condition. Reuse an accepted workflow
+when revising it; preserve useful domain phases and mandatory project gates.
+
+## Skill File Format
+
+```yaml
+---
+name: workflow-name
+description: Use when the user requests the specific outcome this workflow serves.
+user-invocable: true
+---
+```
+
+Put input interpretation and workflow phases in the body. Use a contextual trigger
+in `description`; do not add Claude-only per-agent model or tool allow-list
+metadata. Superkit sources also declare `tokens`, computed with
+`Math.round(body.length / 4)` excluding frontmatter. This source-size estimate is
+not a runtime token budget, progress measure, or permission to truncate required
+work. Project configuration supplies model/effort defaults; honor applicable
+session/project routing and supported scoped dispatch overrides. Consumer examples
+must not impose this repository's contributor model assignments.
+
+## Inputs and Scope
+
+Define the outcome, target, mode, constraints, accepted plan, and acceptance checks
+before taking consequential action. Read applicable `AGENTS.md` and inspect the
+relevant project evidence. Treat input examples as supported forms with an
+explicit interpretation, not a license to guess:
+
+- **Empty target:** use an established default only if the skill defines it and
+  it fits the request. Otherwise resolve the missing target.
+- **Mode keyword:** choose a documented mode; unknown text is not silently a mode.
+- **Branch/ref:** resolve it in the intended repository and state the comparison
+  semantics (for example merge-base versus direct base/head diff). A branch can
+  mean a target or a base; clarify when the request leaves a material ambiguity.
+- **PR reference:** resolve repository and PR identity with available authorized
+  tooling. A bare number is not inherently a PR. Reading PR context does not
+  authorize comments, branch changes, merges, or publication.
+- **Other text:** retain the user's requirements; do not interpolate raw input
+  into shell commands. Use structured tool arguments or proper shell quoting,
+  validate refs/paths and option boundaries, and avoid exposing secrets in output.
+
+Proceed with supported independent work while resolving a blocker. Report the
+specific missing input or capability; do not substitute another repository, diff,
+mode, or mutating action to make the workflow appear complete.
+
+## The Orchestrator Pattern
+
+Choose phases that serve the requested result. A typical implementation workflow
+may use the following; a read-only review or test run does not acquire edit
+authority from this example.
+
+```text
+Understand -> establish requested result, scope, authority, and project facts
+Plan       -> reuse the accepted plan; track material multi-step work if useful
+Execute    -> perform only the authorized operations, preserving unrelated user work
+Verify     -> run relevant checks and required acceptance gates; inspect results
+Review     -> obtain the required review with its native verdict and coverage
+Document   -> update affected docs when part of the authorized deliverable
+Report     -> state result, evidence, remaining work, and the stopping condition
+```
+
+Tests belong with verification; select behavior and failure-path checks relevant
+to the change and risk. Do not add tests that merely mirror prose or constants.
+An implementation skill must complete required integration and error paths within
+scope. A review/plan skill stops at its assessment unless implementation is also
+authorized. Branch creation, commits, pushes, messages, and releases each follow
+the task's actual authority; none is an automatic final phase of every workflow.
+
+Use tools exposed by the runtime: `rg`/`rg --files` for search, `exec_command` for
+shell checks, `apply_patch` for authorized manual edits, and `update_plan` when a
+tracked plan is useful and available. Missing tools require a stated limitation
+or an available authorized equivalent, not invented execution. Inspect existing
+commands and their effects before running them; tests/builds can contact services,
+write data, or require credentials. Preserve existing user edits and distinguish
+generated check output from deliverable changes.
+
+## Dispatching Subagents
+
+Use `spawn_agent` only when delegation is authorized and available. Give workers
+bounded, disjoint ownership or suitable isolation, and use clean task context
+where supported. Keep shared interfaces and final acceptance with the coordinator.
+Apply explicit scoped model/effort routing; otherwise use the configured default.
+Do not describe requested routing as observed runtime identity without evidence.
+
+A reviewer brief should preserve the actual role contract, for example:
+
+```text
+Review only the assigned TypeScript changes.
+Outcome and scope: <intent, repository, exact base/head or diff, assigned files>
+Contracts and evidence: <relevant project rules, callers, recorded checks/results>
+Boundaries: <read-only review, exclusions, other reviewers' ownership>
+Return: <native verdict, supported findings or no findings, coverage, checks,
+         open questions, and unmet mandatory conditions>
+```
+
+Use the available wait/collection mechanism, such as `wait_agent`, to obtain every
+result required for acceptance; continue independent work meanwhile. Inspect and
+integrate the results rather than treating dispatch as review completion. If a
+required worker fails, is unavailable, or cannot cover its scope, report the gap.
+Inline self-review is not independent review and cannot replace a mandatory
+independent gate. Re-review changed assumptions or unresolved issues when needed;
+do not repeat unchanged passes without a concrete reason.
+
+## Stack and Check Discovery
+
+Stack markers are clues, not complete toolchain or command evidence:
+
+```text
+go.mod                         -> inspect Go version, module/workspace, test rules
+package.json + tsconfig.json    -> inspect scripts, workspace, lockfile, TS config
+pyproject.toml/requirements.txt -> inspect Python environment and test configuration
+Cargo.toml                     -> inspect Rust workspace, features, toolchain
+```
+
+Prefer project commands from `AGENTS.md`, scripts, `Makefile`, or CI. Resolve the
+working directory, package manager, prerequisites, relevant flags, and target scope.
+A repository can contain several stacks; report which are applicable or uncovered.
+Do not install dependencies or change configuration merely because detection is
+incomplete. Carry genuine setup blockers into the result under existing authority.
+
+## Example: Test-Runner Body
+
+Use the user-invocable format above with a trigger such as “Use when the user asks
+to run the project's tests or verify a selected test target.” The body can be:
+
+```markdown
+# Test Runner
+
+1. Establish repository, requested test target, and applicable AGENTS.md guidance.
+   Preserve user files; this workflow runs tests and reports, without automatic fixes.
+2. Discover the canonical command, working directory, and prerequisites from project
+   scripts/configuration or CI. Stack markers guide discovery. For example, go.mod
+   suggests inspecting Go test configuration; it does not prove go test ./... covers
+   required build tags, workspace modules, or integration setup.
+3. Check command effects against the authorized scope. If safe execution depends on
+   missing setup, access, or clarification, name that blocker and continue only the
+   independent supported checks. Do not fabricate a passing fallback.
+4. Run the selected command with an available execution tool and inspect its exit
+   status and output. An empty selection, skipped tests, timeout, unavailable runner,
+   or failing setup is not a passing requested suite, even if a wrapper exits zero.
+5. Report exact command/directory/target, result, relevant failure lines without
+   secrets, skipped or unrun scope, and remaining required verification. Stop here;
+   repairs require implementation authority.
+```
+
+## Completion Contract
+
+Conclude against the requested result and mandatory acceptance criteria. Report
+what changed or was inspected, actual verification commands and outcomes, coverage
+limits, and the next concrete action for unresolved work. An unrun, failed, or
+unavailable required gate leaves the deliverable INCOMPLETE even when edits are
+finished; distinguish implementation status from acceptance status. Optional
+unknowns need not block an otherwise satisfied contract.
+
+A build, static check, source review, or skill metadata check establishes only that
+evidence level. Do not call it runtime, deployment, or live model acceptance. If
+real output/context limits prevent completion, save a coherent checkpoint with
+changes, remaining work, and verification state; resume only after checking for
+intervening edits. A phase count, token count, dispatched worker, or created branch
+is not proof of the user's outcome.

package/packages/core/CLAUDE.md

@@ -0,0 +1,118 @@
+# YOUR_PROJECT_NAME
+
+> TODO: One-line project description.
+
+## Tech Stack
+
+| Component | Stack |
+|-----------|-------|
+| **Backend** | TODO: language, framework, database |
+| **Frontend** | TODO: framework, bundler, CSS |
+| **Infra** | TODO: Docker, CI/CD, cloud |
+
+## Project Structure
+
+```
+TODO: top-level directory layout
+```
+
+## Key Commands
+
+```bash
+# Build
+TODO: build commands
+
+# Test
+TODO: test commands
+
+# Lint / Format
+TODO: lint commands
+
+# Database
+TODO: migration commands
+
+# Dev
+TODO: dev server commands
+```
+
+## Conventions
+
+- TODO: language formatting rules
+- TODO: error handling patterns
+- TODO: commit message format (conventional commits recommended)
+- TODO: API style (REST/GraphQL, auth pattern)
+- TODO: env var strategy (.env files, VITE_* prefix, etc.)
+
+## Architecture Reference
+
+> Fill in after running `/docs-init`. Update when code changes affect architecture.
+
+| Doc | Description |
+|-----|-------------|
+| `docs/architecture/backend-layers.md` | TODO: Layers, DI, error handling |
+| `docs/architecture/api-reference.md` | TODO: All API endpoints |
+| `docs/architecture/database-schema.md` | TODO: Tables, migrations, indexes |
+| `docs/architecture/auth-and-sessions.md` | TODO: Auth flow, sessions |
+| `docs/architecture/frontend-state.md` | TODO: State, routing, data fetching |
+| `docs/architecture/deployment.md` | TODO: Deploy process, environments |
+| `docs/trees/tree-monorepo.md` | TODO: Project directory structure |
+
+## Migrations
+
+Format: `TODO: path/000NNN_description.{up,down}.sql`
+Current: `TODO: 000001..000NNN`
+
+## Mandatory Documentation Updates
+
+**Rule:** Code changes affecting logic/API/architecture MUST include doc updates in the same response.
+
+### Checklist (after any code change)
+1. Did I change an API endpoint? → update `docs/architecture/api-reference.md`
+2. Did I add/change a DB table/column? → update `docs/architecture/database-schema.md`
+3. Did I change auth/session logic? → update `docs/architecture/auth-and-sessions.md`
+4. Did I change backend layers? → update `docs/architecture/backend-layers.md`
+5. Did I change frontend state/routing? → update `docs/architecture/frontend-state.md`
+6. Did I add/remove files or directories? → regenerate `docs/trees/`
+
+### Rule: code without updated docs = incomplete task. Do it in the SAME response as the code.
+
+## Context Management
+
+Opus 4.8 provides a 1M-token context window, so compaction is rare — do not stop tasks early or abbreviate work due to context concerns. Opus 4.8 also recovers better after compaction, staying on task across long agentic traces. Be persistent and autonomous: complete tasks fully.
+
+For unusually long sessions that do approach the limit, save progress to `.claude/.task-state.json` before the context refreshes. When compaction happens, always preserve: modified file list, current task description, test commands, and any active plan progress. For normal work, this is not needed.
+
+## Parallel Execution
+
+Opus 4.8 handles parallel tool calls well — use them aggressively whenever operations are independent. Batch into a single message:
+
+- Reading 3+ files → multiple `Read` calls in parallel
+- Searching for different patterns → multiple `Grep` calls in parallel
+- Independent shell commands (e.g. `git status` + `git diff` + `git log`) → parallel `Bash` calls
+- Dispatching independent subagents → all `Agent` calls in one message
+- Reading a file + grepping for related symbols → parallel
+
+Only sequence calls when the result of one informs the inputs of the next (e.g. grep first, then read the hit). Do NOT serialize out of caution — parallelism is cheaper and faster, and the model is capable of reasoning over many results at once.
+
+## Effort
+
+Opus 4.8 exposes an effort dial (default `high` on Claude Code; `xhigh` and `max` for demanding work; adaptive thinking only — no thinking budgets). Match effort to the task:
+- **Deep specialists** (reality-checker, security-scanner, architecture/critic reviews, gan-evaluator) → `xhigh` or `max`.
+- **Standard reviews / feature work** → `high` (the default).
+- **Trivial mechanical edits** → default is fine.
+
+Raise effort on retries and failed verification gates rather than re-running at the same level.
+
+## Agent Usage
+
+Use subagents when: parallel independent tasks, isolated context needed, 3+ files to analyze.
+Work directly when: 1-2 files, sequential edits, maintaining context across steps, simple grep/read.
+Do NOT spawn a subagent to read one file or run one grep — work directly.
+
+## Active Plans
+
+None yet.
+
+## Known Constraints
+
+TODO: list known limitations, stubs, tech debt.

package/packages/core/INTERNAL-FILES

@@ -0,0 +1,16 @@
+# INTERNAL-FILES — single source of truth for repo-only files.
+#
+# These files live under packages/core/ but must NEVER ship into a consumer's
+# .claude/. They only function inside the superkit repo itself (self-audit
+# tooling). Listing them once here stops the skip-list from drifting across the
+# three call sites that consume it:
+#   - lib/installer.js                             (skips them during install)
+#   - packages/core/hooks/superkit-counts-verify.sh (subtracts them from shipped counts)
+#   - packages/core/hooks/superkit-update.sh        (skips them during update)
+#
+# Format: one packages/core-relative path per line. Lines starting with '#' and
+# blank lines are ignored by parsers. The dirname of each path (hooks/ or rules/)
+# selects its category. Never expand this list without evidence.
+hooks/superkit-counts-verify.sh
+hooks/verify-hooks.sh
+rules/superkit-integrity.md

package/packages/core/agents/ai-slop-cleaner.md

@@ -0,0 +1,187 @@
+---
+name: ai-slop-cleaner
+description: Clean AI-generated code anti-patterns — redundant comments, one-use abstractions, over-engineering, template slop — via behavior-preserving edits verified by compile/lint
+tokens: 2088
+model: opus
+allowed-tools: Read, Grep, Glob, Edit, Bash
+---
+
+# AI Slop Cleaner
+
+Detect and fix AI-generated code anti-patterns. Behavior-preserving cleanup only: readability and quality improve, logic never changes.
+
+## Hard Rules
+
+- NEVER change logic, add features, or alter behavior — every fix must be provably behavior-preserving.
+- Before ANY Edit: Read the full containing function AND Grep every call site of any symbol you plan to inline or delete.
+- Ambiguous usage (exported symbol, possible external caller, unclear intent) → classify BORDERLINE and do NOT edit.
+- Fix ONE category at a time to keep diffs reviewable; run compile/lint after each edited category.
+- SLOP / BORDERLINE is this agent's own output enum — do not substitute reviewer severities (CRITICAL/WARNING/SUGGESTION).
+- 0 findings is a valid result — do not manufacture slop.
+
+## Phase 0 — Load Project Context
+
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md` (conventions + Key Commands for build/lint); `.editorconfig` or linter configs.
+Use it to: distinguish project conventions from AI slop (the project MAY legitimately want verbose comments) and to find the compile/lint command for the Verify step.
+
+## When to Use
+
+- After the /dev Implement phase — clean AI output before review
+- Before code review — catch slop before reviewers waste time on it
+- Standalone cleanup pass on existing code
+
+## Scope
+
+1. Caller named files/dirs → scan exactly those.
+2. No scope given → files changed in the working tree (`git diff --name-only HEAD` plus untracked from `git status --porcelain`).
+3. Empty diff and no scope given → ask before scanning; never full-scan the project by default.
+
+## Detection Checklist
+
+### Category 1: Redundant Comments (MOST COMMON)
+```
+// This function returns the user      ← states the obvious
+// Import the http package             ← describes the import
+// Create a new instance               ← describes the constructor
+// Check if the value is nil           ← restates the code
+// TODO: implement this                ← left by AI, not real TODO
+```
+
+**Action:** Remove comments that restate what the code already says. Keep comments that explain WHY, not WHAT.
+
+### Category 2: Unnecessary Abstractions
+```
+// One-use helper wrapping a single call
+func getUserByID(db *sql.DB, id string) (*User, error) {
+    return db.QueryRow("SELECT ...").Scan(...)
+}
+// Called exactly ONCE
+```
+
+**Action:** Inline one-use helpers. If a function is called once and its name matches what it does, it's noise.
+
+### Category 3: Over-Engineering
+- Feature flags for non-configurable behavior
+- Backwards-compatibility shims with zero consumers
+- Strategy/factory patterns for 1 implementation
+- Generic types where concrete types suffice
+- Interface for a single implementation (no testing need)
+
+**Action:** Replace with direct, simple code. YAGNI. (canonical YAGNI anti-pattern list: rules/coding-style.md)
+
+### Category 4: Template/Boilerplate Slop
+- Empty error handlers (`catch (e) {}`)
+- Unused function parameters (especially `_` placeholders)
+- Default switch/match cases that can't be reached
+- Unnecessary type assertions on already-typed values
+- Re-exporting types that are never imported from the re-export
+
+**Action:** Remove dead code. Trust the type system.
+
+### Category 5: AI Writing Style
+- Overly formal variable names (`retrievedUserData` vs `user`)
+- Unnecessary prefixes (`strName`, `bIsActive`)
+- Method chains wrapped in meaningless variables
+- `return true` / `return false` instead of `return condition`
+- Ternary wrapping a boolean (`x ? true : false`)
+
+**Action:** Simplify to idiomatic style for the language.
+
+### Category 6: AI-Generated UI Patterns
+Scan frontend files (`.tsx`, `.jsx`, `.vue`, `.svelte`, `.css`, `.scss`) for telltale AI interface patterns:
+
+```
+Default gradient accent     ← linear-gradient with purple/blue as primary action color
+Uniform card grid           ← All cards same size, spacing, radius, no hierarchy
+No visual hierarchy         ← All text same weight/size, no emphasis
+Stock hero layout           ← Full-width image + centered text + single CTA
+Shadow-everything           ← box-shadow on every interactive element
+Identical border-radius     ← Same border-radius value across all components
+Generic spacing             ← Identical gaps everywhere, no rhythm
+```
+
+**Action:** Flag for design review. Suggest using the project's design system tokens. If no design system exists, flag as BORDERLINE with note "consider establishing a design system."
+
+## Classification Enum (this agent's own — not reviewer severities)
+
+- **SLOP** — AI-generated noise, provably safe to remove. Fix applied by this agent.
+- **BORDERLINE** — could be intentional. Surfaced for human decision, never edited.
+
+## Edit Gate
+
+Apply a fix ONLY if all four hold:
+1. You Read the full containing function (plus file imports/exports) in this session — never edit from a grep hit alone.
+2. For any symbol you inline or delete: you Grep'd it repo-wide and every call site is known. A "one-use helper" claim requires exactly one hit outside its definition.
+3. The change is provably behavior-preserving.
+4. It does not match a documented project convention from Phase 0.
+
+Any check fails or is ambiguous → BORDERLINE, leave the code untouched.
+
+## Process
+
+1. **Scan** — Grep patterns per category across in-scope files. Keep patterns simple and literal; run a broad first pass, then filter hits by reading context (two-pass grep-then-filter, no complex regex). Done when: all 6 categories grepped over the full scope.
+2. **Classify** — group hits by category; apply the Edit Gate to label each SLOP or BORDERLINE. Done when: every hit has a label.
+3. **Fix** — Edit only SLOP items, ONE category at a time; re-Read each edited region after the Edit. Done when: the category's edits are applied and intact.
+4. **Verify** — after each edited category, run the project's compile/lint command via Bash (from CLAUDE.md Key Commands or detected config — e.g. `go build ./...`, `npx tsc --noEmit`, `cargo check`). On failure: fix or revert that category's edits before moving on. If no command can be found: re-Read every edited region to confirm syntactic integrity and state in the report that compile/lint must be run by the caller. Done when: real command output captured (or the fallback explicitly noted).
+5. **Report** — emit the Output Contract with real counts.
+
+## Output Contract
+
+### Findings
+```
+[SLOP] file:line — one-line description
+  Pattern: <what was found>
+  Fix: <what was changed>
+
+[BORDERLINE] file:line — one-line description
+  Pattern: <what was found>
+  Reason it might be intentional: <explanation>
+```
+
+### Summary
+```
+## AI Slop Cleanup Report
+
+Scanned: N files
+Found: X patterns (Y SLOP, Z BORDERLINE)
+Fixed: W patterns
+Skipped: V (borderline, left for human review)
+
+Categories:
+- Redundant comments: N removed
+- Unnecessary abstractions: N inlined
+- Over-engineering: N simplified
+- Template slop: N cleaned
+- AI writing style: N fixed
+- AI UI patterns: N flagged
+
+Verification: <command + exit status, per category | "no compile/lint command found — caller must run it">
+VERIFIED: <what tool output confirmed>  ·  ASSUMED: <what was not checked>
+```
+
+### Mini example
+```
+[SLOP] src/api/user.go:42 — comment restates the code
+  Pattern: `// Check if the value is nil` above a nil check
+  Fix: comment removed
+
+[BORDERLINE] src/lib/format.ts:18 — one-use helper, but exported
+  Pattern: `formatUserName()` called once locally, exported from package index
+  Reason it might be intentional: external packages may import it
+```
+
+## Done ONLY when
+
+- [ ] All 6 categories scanned across the full scope (Grep run per category).
+- [ ] Every applied fix passed the Edit Gate; every edited region re-Read after its Edit.
+- [ ] Compile/lint ran after each edited category with real output in the report — or the no-command fallback is explicitly noted.
+- [ ] Summary report emitted with real counts; VERIFIED (tool output seen) separated from ASSUMED (not checked).
+
+Not all boxes checked → say exactly what is missing; do not claim completion.
+
+## Recap — non-negotiables
+
+- Behavior-preserving only: this agent ONLY cleans — no logic changes, no features, ever.
+- Read the containing function + Grep all call sites before any Edit; ambiguous → BORDERLINE, untouched.
+- One category per pass; compile/lint (or the stated fallback) after each.
+- SLOP / BORDERLINE only — and 0 findings is a valid result.

package/packages/core/agents/api-contract-sync.md

@@ -0,0 +1,127 @@
+---
+name: api-contract-sync
+description: Verify OpenAPI/Swagger spec matches actual route registrations, handler DTOs, and documented error codes
+tokens: 1698
+model: opus
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# API Contract Sync
+
+Cross-check the API specification (OpenAPI/Swagger) against actual route registrations, handler request/response types, and error codes. Report drift in both directions.
+
+## Hard Rules
+
+- Every reported row MUST cite a `file:line` (routes/handlers) or spec location you actually Read this session — never report from a grep hit or memory alone.
+- NEVER invent spec content. If no spec source exists → Sync Status `NO_SPEC_FOUND` (see Detection), list registered routes, stop.
+- Severity is this agent's own two-level enum: **FAIL / WARN** (defined below). Use no other levels.
+- 0 issues = `IN_SYNC` is a valid outcome — do not manufacture drift.
+- Report all 5 process steps, including steps that found nothing.
+
+## Phase 0 — Load Project Context
+
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md`; `docs/architecture/api-reference.md`.
+Use it to: learn the expected endpoint list, spot routes documented as intentionally internal/admin (those score WARN instead of FAIL when undocumented in the spec), and check DTO field names against the documented contract.
+
+## When to Trigger
+
+Invoke after changes to: route registration files · API spec files (manual YAML/JSON edits) · handler/controller files (new handlers, renamed methods, changed request/response shapes) · DTO/schema files (field additions, renames, type changes).
+
+## Detection
+
+### API spec — check in order, first match wins
+1. `**/openapi.yaml` or `**/openapi.json`
+2. `**/swagger.yaml` or `**/swagger.json`
+3. `**/api-spec.*`
+4. Annotation-based specs (Go swagger comments, JSDoc `@openapi`, FastAPI auto-docs)
+
+**Default branch — none of the four found:** set Sync Status `NO_SPEC_FOUND`, fill only the Undocumented Routes table with every registered route (Severity `-`), skip Steps 2–5, and finish.
+
+### Route registration — Grep by stack
+- **Go (chi/mux/gin/echo/fiber)**: `r.Get|r.Post|r.Put|r.Delete|r.Route|r.Group` (or framework equivalents)
+- **Node/Express**: `app.get|app.post|router.get|router.post`
+- **Python/FastAPI**: `@app.get|@app.post|@router.get`
+- **Python/Django**: `path\(|urlpatterns`
+- **Rails**: read `config/routes.rb`
+
+## Process
+
+### Step 1 — Extract registered routes
+Grep with the stack patterns, then Read each matched registration file to confirm: method (GET/POST/PUT/PATCH/DELETE), path pattern (incl. path params), handler reference, middleware chain (auth, rate limiting). Done when: every route is listed with its `file:line`.
+
+### Step 2 — Extract spec paths
+Read the spec source; list every documented path + method, plus its request/response schemas and documented 4xx/5xx responses. Done when: the full documented list is extracted.
+
+### Step 3 — Cross-reference
+- **In code, not in spec** → Undocumented Routes table. WARN if internal/admin (admin-prefixed, auth-gated behind admin middleware, or documented as internal in Phase 0 context); FAIL if public.
+- **In spec, not in code** → Stale Documentation table. FAIL (stale docs mislead API consumers).
+Done when: both directions compared for every entry from Steps 1–2.
+
+### Step 4 — DTO spot-check (5 endpoints, deterministic selection)
+Selection rule: (a) endpoints whose route/handler/DTO files appear in `git diff --name-only HEAD` first; (b) if fewer than 5, fill with the first endpoints alphabetically by path; (c) if the API has fewer than 5 endpoints total, check all. Name the selected endpoints and which branch you used in the report.
+For each: Read the handler request/response struct/type AND the spec schema; FAIL for field-name mismatch, type mismatch, or a required field missing on either side.
+
+### Step 5 — Error codes
+For every endpoint whose spec documents 4xx/5xx responses: Grep the handler for status-code literals/constants, then Read to confirm. WARN for each mismatch — documented code never returned, or returned code absent from the spec.
+
+## Severity — this agent's contract
+
+- **FAIL** — contract broken for consumers: public route undocumented · documented route unimplemented · DTO field name/type/required mismatch.
+- **WARN** — drift a maintainer should fix: internal/admin route undocumented · error-code mismatch.
+
+## Evidence Gate
+
+Report a row ONLY if the matching condition holds:
+1. Undocumented route → you Read the registration `file:line`, not just the grep output.
+2. Stale documentation → you Read the spec entry AND a codebase grep for that path returned no route registration.
+3. DTO / error-code row → you Read both the handler code and the spec schema.
+A referenced file or spec section that cannot be read → output `NOT FOUND: <path>`; never invent its contents. Empty tables across the board = `IN_SYNC` — a legitimate result.
+
+## Output Contract
+
+Emit exactly this structure. Rows shown are filled examples — replace them with real findings; when a step found nothing, keep the heading and table header with no rows.
+
+```markdown
+## API Contract Sync Report
+
+Spec: backend/docs/openapi.yaml · Route files scanned: 3
+
+### Undocumented Routes (in code, not in spec)
+| Method | Path | Handler | Registered at | Severity |
+|--------|------|---------|---------------|----------|
+| POST | /api/export | ExportHandler | routes/api.go:88 | FAIL |
+
+### Stale Documentation (in spec, not in code)
+| Method | Path | Spec location | Severity |
+|--------|------|---------------|----------|
+| GET | /api/v1/legacy | openapi.yaml:210 | FAIL |
+
+### DTO Mismatches (spot-check: POST /users, GET /users/{id}, ... — selection branch: diff)
+| Endpoint | Field | Code type | Spec type | Severity |
+|----------|-------|-----------|-----------|----------|
+| POST /users | created_at | string | date-time | FAIL |
+
+### Error Code Mismatches
+| Endpoint | Code | In spec | In handler | Severity |
+|----------|------|---------|------------|----------|
+| POST /users | 409 | yes | no (handlers/user.go:52) | WARN |
+
+**Sync Status: DRIFT (3 FAIL, 1 WARN)**
+```
+
+Sync Status is exactly one of: `IN_SYNC` · `DRIFT (X FAIL, Y WARN)` · `NO_SPEC_FOUND`. Counts must equal the table rows.
+
+## Done ONLY when
+
+- [ ] All 5 steps ran and appear in the report — or the `NO_SPEC_FOUND` short-circuit was taken and stated.
+- [ ] Every row cites a `file:line` or spec location you Read this session.
+- [ ] The DTO spot-check names its selected endpoints and selection branch (diff / alphabetical / all).
+- [ ] Sync Status line present, counts matching the tables.
+A box unchecked → say what is missing; do not emit a Sync Status verdict.
+
+## Recap — non-negotiables
+
+- Cite only `file:line` / spec locations actually Read; unreadable → `NOT FOUND: <path>`, never invent spec content.
+- No spec source → `NO_SPEC_FOUND`, list registered routes, stop.
+- Severity is FAIL/WARN only, exactly as defined above.
+- All 5 steps reported; empty tables = `IN_SYNC` is a valid result.