worclaude 2.7.1 → 2.9.0

package/templates/commands/review-plan.md

@@ -1,17 +1,90 @@
 ---
-description: "Send implementation plan to plan-reviewer agent for staff-level review"
+description: "Auto-detect plans from .claude/plans/ and send to plan-reviewer with project context"
 ---
 
-Send the current implementation plan to the plan-reviewer agent.
-The plan-reviewer will act as a staff engineer and critically
-review the plan for:
-- Ambiguity
-- Missing verification steps
-- Unrealistic scope
-- Edge cases
-- SPEC.md alignment
+Send an implementation plan to the `plan-reviewer` agent for staff-level
+review. The plan-reviewer acts as a staff engineer and critically
+reviews the plan for ambiguity, missing verification steps, unrealistic
+scope, edge cases, and SPEC.md alignment.
 
-Wait for the review and address all feedback before proceeding.
+## 1. Auto-detect the plan
+
+Read `.claude/plans/` and list every file inside (excluding `.gitkeep`
+and `README.md`). Behavior depends on what's present:
+
+- **Zero plan files:** **Refuse to dispatch.** Report:
+  "No plan files found in `.claude/plans/`. Drop your plan there
+  (any filename) and re-run `/review-plan`."
+  Do not invoke the agent.
+
+- **Exactly one plan file:** Use it directly without asking.
+
+- **Multiple plan files:** Use **`AskUserQuestion`** (2-4 options) to
+  let the user pick which one to review. For >4 candidates, present a
+  numbered list and ask for a number reply.
+
+Do NOT match filename patterns. The folder convention is the discovery
+mechanism — anything in `.claude/plans/` is a candidate.
+
+## 2. Auto-load project context
+
+Before dispatching, read these files and pass their contents to the
+agent so it can check SPEC alignment without a second turn:
+
+- `CLAUDE.md` — project conventions and critical rules
+- `docs/spec/SPEC.md` — the source of truth for what should ship
+
+Include both in the agent's prompt under clearly-labeled sections.
+
+## 3. Dispatch to `plan-reviewer`
+
+```
+Agent({
+  subagent_type: "plan-reviewer",
+  description: "Staff-level review of <plan-file>",
+  prompt: "Review the implementation plan below as a senior staff engineer.
+
+PLAN (from .claude/plans/<filename>):
+<plan content>
+
+PROJECT CONVENTIONS (from CLAUDE.md):
+<CLAUDE.md content>
+
+SPECIFICATION (from docs/spec/SPEC.md):
+<SPEC.md content>
+
+Check for: ambiguity, missing verification steps, unrealistic scope,
+edge cases, SPEC alignment. Report findings in priority order with
+specific file/line references where possible."
+})
+```
+
+## 4. Persist the review output
+
+When the agent returns, **write its findings to
+`.claude/scratch/last-plan-review.md`** with SHA frontmatter so the
+next session can surface the review via `/start`:
+
+```markdown
+---
+created: <YYYY-MM-DDTHH:MM:SSZ>
+sha: <git rev-parse HEAD>
+command: /review-plan
+plan: .claude/plans/<filename>
+---
+
+# Plan Review
+
+<agent output verbatim>
+```
+
+If `last-plan-review.md` already exists, **overwrite it** — only the
+most recent review is consumed.
+
+## 5. Report
+
+Surface the review's priority findings to the user inline. Wait for
+them to address feedback before proceeding to implementation.
 
 ## Trigger Phrases
 - "review this plan"

package/templates/commands/start.md

@@ -1,5 +1,5 @@
 ---
-description: "Load session context, check for handoff files, detect drift since last session"
+description: "Load session context, check for handoffs, detect drift, surface scratch + plans"
 ---
 
 The SessionStart hook has already loaded CLAUDE.md, PROGRESS.md,
@@ -9,33 +9,30 @@ When invoked with arguments, use them as the task focus. Example: `/start implem
 
 Arguments: $ARGUMENTS
 
-Your job is to supplement that with drift detection and additional context.
+Your job is to supplement that with drift detection, handoff loading,
+scratch artifact surfacing, and plan discovery.
 
-## 1. Drift Detection
+## 1. Drift Detection (SHA-based)
 
 Show what changed since the last session so there are no surprises.
 Present raw signals only — do NOT interpret or warn.
 
-Run these commands and report the output:
+Prefer **SHA-based drift** when the most recent session summary records
+a HEAD SHA in its frontmatter. Otherwise fall back to date-based drift.
+
+Run the helper script as a single command — do not unpack the script body.
+Bundling avoids per-line permission prompts on multi-line bash with
+`X=$(...)` assignments and `if`/`elif` blocks.
 
 ```bash
-# How many commits since last session file?
-LAST_SESSION=$(ls -t .claude/sessions/*.md 2>/dev/null | head -1)
-if [ -n "$LAST_SESSION" ]; then
-  SESSION_DATE=$(echo "$LAST_SESSION" | grep -oP '\d{4}-\d{2}-\d{2}')
-  echo "Commits since last session ($SESSION_DATE):"
-  git log --oneline --since="$SESSION_DATE" 2>/dev/null | head -15
-else
-  echo "No previous session found. Recent commits:"
-  git log --oneline -10 2>/dev/null
-fi
+bash .claude/scripts/start-drift.sh
 ```
 
-Report as:
+The script outputs the drift list and the current branch name. Report as:
 
 ```
 ## Drift Since Last Session
-- **X commits** since {date}
+- **X commits** since {SHA or date}
 - {one-liner per commit, max 15}
 
 Current branch: {branch name}
@@ -45,36 +42,67 @@ If there are 0 commits since the last session, just say:
 
 ```
 ## Drift Since Last Session
-No new commits since last session ({date}). Branch: {branch name}
+No new commits since last session ({SHA or date}). Branch: {branch name}
 ```
 
 Do NOT add commentary like "you should review these" or "there may be
 conflicts." Just the facts.
 
-## 2. Check for Handoff Files
+## 2. Read handoff and session summary as distinct artifacts
+
+`/end` writes two files with disjoint content:
+
+- **Handoff** at `docs/handoffs/HANDOFF-{branch}-{date}.md` — forward-
+  looking only (what's left, decisions pending, where to pick up)
+- **Session summary** at `.claude/sessions/{YYYY-MM-DD-HHMM}-{branch}.md` —
+  backward-looking only (what got done, observability)
+
+Read both, keeping their roles distinct. Do not merge their content into
+a single "last session" blob:
+
+- Look in `docs/handoffs/` for any `HANDOFF*.md` matching the current
+  branch first, then any other recent handoff. Read the most relevant.
+- The session summary is already loaded by the SessionStart hook — re-
+  reference it for "what got done" but don't re-read it.
+
+## 3. Surface pending scratch artifacts (SHA-matched)
+
+Read `.claude/scratch/` and list every file inside. For each artifact
+with a `sha:` frontmatter field, compare against `git rev-parse HEAD`:
+
+- **SHA matches HEAD:** the artifact is fresh. Surface it prominently
+  with its purpose (e.g., "/review-changes left findings — run
+  /refactor-clean to apply them").
+- **SHA does not match HEAD:** the artifact is stale. Mention it with a
+  "(stale, ignore)" tag. Do not delete — the user may want to inspect it.
+- **No SHA in frontmatter:** report as "(unknown freshness)".
 
-Look in docs/handoffs/ for any HANDOFF*.md files:
+This surfacing is **generic** — list whatever is in the folder. New
+scratch types added later don't require spec changes here.
 
-- Both HANDOFF-{branch}-{date}.md and legacy HANDOFF_{date}.md
-- Prioritize files matching the current branch name
-- If found, read them for context and report what was handed off
+## 4. Discover active plans (folder, not filename pattern)
 
-## 3. Load Agent Routing
+Read `.claude/plans/` and list every file inside (excluding `.gitkeep`
+and `README.md`). These are the project's active plans. Surface each
+with its first H1 heading or filename for quick scanning.
 
-Read .claude/skills/agent-routing/SKILL.md for agent usage guidance.
+Do NOT match filename patterns like `PHASE-*-PROMPT.md` or
+`IMPLEMENTATION-*.md` — the folder convention replaces pattern detection.
+Anything in `.claude/plans/` is treated as active work guidance.
 
-## 4. Check for Active Prompt Files
+## 5. Load Agent Routing
 
-If any PHASE-*-PROMPT.md or implementation prompt file exists in the
-project root, read it and note it.
+Read `.claude/skills/agent-routing/SKILL.md` for agent usage guidance.
 
-## 5. Report
+## 6. Report
 
 Summarize:
 
 - Drift status (from step 1)
-- Any handoffs found (from step 2)
-- What was last completed (from session summary loaded by hook)
+- Handoff content (forward-looking, from step 2)
+- Session summary highlights (backward-looking, already loaded)
+- Pending scratch artifacts (from step 3)
+- Active plans (from step 4)
 - What's next (from PROGRESS.md loaded by hook)
 - Any blockers or notes
 
@@ -83,3 +111,6 @@ Summarize:
 - "begin working"
 - "load context"
 - "what changed since last time"
+- "what's the status"
+- "where am I"
+- "what am I working on"

package/templates/commands/sync.md

@@ -10,6 +10,10 @@ ONLY update shared-state files — do not resolve conflicts. That is
 /conflict-resolver's job. If you detect unresolved conflicts, stop
 and tell the user to run /conflict-resolver first.
 
+## Invocation Contract
+
+Run this command only when the human explicitly invokes it (typed `/sync` or one of the Trigger Phrases at the bottom of this file). Do not auto-launch after detecting that PRs were merged. The "ship/wait" prompt at step 9 is non-skippable. See CLAUDE.md Critical Rule 13.
+
 ## Pre-check
 
 1. Confirm you are on the develop branch. If not, stop and warn.
@@ -19,6 +23,26 @@ and tell the user to run /conflict-resolver first.
    or version tag. If nothing was merged, report "Nothing to sync"
    and stop.
 
+## Drift preflight
+
+3a. Run `worclaude doctor` to surface CLAUDE.md ↔ package.json drift
+    before any shared-state file writes:
+
+    ```bash
+    worclaude doctor
+    ```
+
+    The `## Documentation` section reports any tech-stack claims in
+    CLAUDE.md (e.g., `857 tests, 62 files`) that no longer match the
+    current test count. If a `CLAUDE.md test-file count drift` warning
+    appears, step 10c will fix the line when it refreshes tech-stack
+    metrics — note the actual count from the warning and proceed.
+
+    If the warning is surprising (claim doesn't exist, or the delta is
+    large enough to suggest a deleted/renamed suite), pause and inspect
+    before continuing. Other doctor warnings are advisory; only the
+    drift warning is load-bearing for this sync.
+
 ## Update PROGRESS.md
 
 4. Update docs/spec/PROGRESS.md:
@@ -37,13 +61,18 @@ and tell the user to run /conflict-resolver first.
 
 ## Bootstrap: ensure a version tag exists
 
-6. Check for a version tag:
+6. Check for a version tag and capture its commit date. Run the helper as
+   a single command — do not unpack the script body.
 
    ```bash
-   LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+   bash .claude/scripts/sync-release-scope.sh
    ```
 
-   If no tag exists, prompt the user. Do NOT silently auto-tag:
+   The script prints two lines: `last_tag=<tag>` and `since=<YYYY-MM-DD>`.
+   Both empty when no tag exists. Read `last_tag` from the first line.
+
+   If no tag exists (`last_tag=` is empty), prompt the user. Do NOT
+   silently auto-tag:
 
    ```
    No version tag found. /sync needs a starting tag to compute release scope.
@@ -81,18 +110,30 @@ and tell the user to run /conflict-resolver first.
 
 ## Aggregate version bumps from merged PRs
 
+**Enforcement model.** `/commit-push-pr` prompts every PR author for a
+`Version bump:` declaration via `AskUserQuestion` and refuses to open a
+PR without one. This step catches stragglers — manual `gh pr create`
+calls, hot-fix branches that bypassed `/commit-push-pr`, or imports
+from outside the workflow. Missing declarations are treated as `none`
+**and surfaced permanently in the CHANGELOG** so under-documentation is
+visible rather than silent. Do NOT silently upgrade missing declarations
+to a higher level — the warning is the enforcement.
+
 7. Collect `Version bump:` declarations from all PRs merged into develop
    since the last version tag. Use `%as` for the date format (strict
    YYYY-MM-DD; `%ai` breaks GitHub search due to space separator and
    timezone offset). Pass `--limit 500` to avoid the `gh pr list` default
    cap of 30, which would silently truncate on repos with infrequent
-   tagging:
+   tagging.
+
+   The `since=<YYYY-MM-DD>` value from step 6's helper output is what you
+   pass below as `<SINCE>`. If you skipped step 6 (rare), re-run
+   `bash .claude/scripts/sync-release-scope.sh` and use its `since=` line.
 
    ```bash
-   SINCE=$(git log -1 --format=%as "$LAST_TAG")
    gh pr list --state merged --base develop \
      --limit 500 \
-     --search "merged:>=$SINCE" \
+     --search "merged:>=<SINCE>" \
      --json number,title,body,headRefName,baseRefName
    ```
 
@@ -197,6 +238,45 @@ and tell the user to run /conflict-resolver first.
        ⚠-prefixed bullets under `### Changed` — not just in the transient
        prompt. This is how under-documentation becomes permanent record.
 
+    c. Refresh tech-stack metrics in CLAUDE.md and AGENTS.md.
+
+       Both files commonly include a line like `Vitest (804 tests, 58 files)`
+       or `npm test    # Run tests (804 tests, 58 files)`. These drift
+       silently as tests are added or moved.
+
+       - Run the project's test runner with a JSON-capable reporter and
+         capture the totals. Examples:
+         - Node/Vitest: `npx vitest run --reporter=json --outputFile=/tmp/_vitest.json && jq '.numTotalTests, (.testResults | length)' /tmp/_vitest.json`
+         - Node/Jest: `npx jest --json --outputFile=/tmp/_jest.json && jq '.numTotalTests, (.testResults | length)' /tmp/_jest.json`
+         - Python/pytest: `pytest --json-report --json-report-file=/tmp/_pytest.json -q && jq '.summary.total, (.tests | map(.nodeid | split("::")[0]) | unique | length)' /tmp/_pytest.json`
+         - Cargo test: count lines from `cargo test --no-run --message-format=json | jq -s '[.[] | select(.profile.test == true)] | length'`
+
+       - Search CLAUDE.md and AGENTS.md for any line matching the pattern
+         `\d+ tests?, \d+ files?`. Update each match with the captured
+         counts. If neither file contains such a line, skip silently — not
+         every project surfaces these metrics.
+
+       - Do NOT add the metrics line if it isn't already there. This step
+         only refreshes existing claims; introducing new ones is a project
+         decision, not a `/sync` decision.
+
+## Regenerate agent-routing skill
+
+10b. Regenerate `.claude/skills/agent-routing/SKILL.md` from the project's
+     installed agent files so it reflects whatever was added/removed/renamed
+     across the merged PRs:
+
+     ```bash
+     worclaude regenerate-routing
+     ```
+
+     The regenerator reads `.claude/agents/*.md` frontmatter and replaces
+     only the content between `<!-- AUTO-GENERATED-START -->` and
+     `<!-- AUTO-GENERATED-END -->` markers — anything outside (frontmatter,
+     local notes) is preserved. If the file is missing or marker-less, a
+     fresh complete file is written. Stage the result alongside the other
+     `/sync` updates if it changed.
+
 ## Verify
 
 11. Run /verify to confirm tests and lint pass.

package/templates/commands/test-coverage.md

@@ -7,35 +7,101 @@ Delegates to the test-writer agent for test creation.
 
 ## Process
 
-1. **Measure current coverage**
+1. **Read project coverage thresholds**
+
+   Before measuring, read the project's configured threshold so the gap
+   baseline is the project's standard, not a guess. Check in this order
+   and use the first one that exists:
+
+   - Vitest: `vitest.config.ts` / `vitest.config.js` (`test.coverage.thresholds`)
+   - Jest: `jest.config.{ts,js,cjs}` or `package.json` `jest.coverageThreshold`
+   - Pytest: `pytest.ini` / `pyproject.toml` (`[tool.coverage.report] fail_under`)
+   - Go: a `// coverage:` directive in `Makefile` or CI config
+   - Fallback: 80% line coverage if no threshold is configured
+
+   Report the threshold up front so the gap analysis has a clear bar.
+
+2. **Measure current coverage**
+
    Run the coverage tool for the project:
    - Node.js: `npx vitest run --coverage` or `npx jest --coverage`
    - Python: `pytest --cov=src --cov-report=term-missing`
    - Go: `go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out`
    - Read CLAUDE.md for project-specific coverage commands
 
-2. **Identify gaps**
-   Focus on files with the lowest coverage that contain:
+3. **Identify gaps, anchored to the last release**
+
+   Focus on files with coverage **below the configured threshold** that
+   contain:
+
    - Business logic (core domain functions)
    - Error handling paths
    - Integration points (DB, API, filesystem)
-   - Recently changed code (`git diff --name-only HEAD~10`)
+   - **Recently changed code, anchored to the last release tag** (not an
+     arbitrary `HEAD~10`). Run the helper as a single command — do not
+     unpack the script body:
+
+     ```bash
+     bash .claude/scripts/test-coverage-changed-files.sh
+     ```
+
+     The helper prints one filename per line — files changed since the
+     last release tag, or the last 10 commits when no tag exists. This
+     makes "recently changed" mean "since the last release," not "since
+     some arbitrary cutoff," so coverage gaps reflect what actually ships
+     next.
+
+4. **Prioritize by risk**
 
-3. **Prioritize by risk**
    Don't aim for 100% everywhere. Prioritize:
    - HIGH: untested error handling, auth logic, data validation
    - MEDIUM: untested business rules, state transitions
    - LOW: untested getters, formatters, simple delegation
    - SKIP: generated code, framework boilerplate, config files
 
-4. **Write missing tests**
-   For each gap:
-   - Write tests that cover the untested paths
-   - Follow existing test patterns in the project
-   - Name tests as specifications ("should return 404 when user not found")
-   - Run tests to verify they pass
+5. **Confirm-then-delegate (do NOT write tests inline)**
+
+   Present the prioritized gap list to the user as a table:
+
+   ```
+   | # | File                  | Coverage | Risk | Suggested tests                          |
+   |---|-----------------------|----------|------|------------------------------------------|
+   | 1 | src/core/merger.js    | 62%      | HIGH | conflict-resolution edge cases (3 tests) |
+   | 2 | src/utils/hash.js     | 45%      | HIGH | empty input + non-UTF8 encoding (2 tests)|
+   | 3 | src/commands/init.js  | 78%      | MED  | scenario-C edge case (1 test)            |
+   ...
+   ```
+
+   Then ask the user which to close. Use **`AskUserQuestion`** when the
+   list has 2-4 candidates (its native option limit). For >4 candidates,
+   present a **numbered list** and ask the user to reply with the numbers
+   they want closed (e.g., "1, 3, 4").
+
+   ```
+   AskUserQuestion: "Which gaps should I close?"
+   - <up to 4 file/test descriptions, one per option>
+   ```
+
+   **Delegate confirmed gaps to the `test-writer` agent in a worktree.**
+   Do NOT write tests inline:
+
+   ```
+   Agent({
+     subagent_type: "test-writer",
+     description: "Close coverage gaps in <files>",
+     prompt: "Coverage gaps to close:\n<confirmed list>\n
+              Project threshold: <threshold>%.
+              Follow existing test patterns. Name tests as specifications.
+              Verify each new test passes; report any that don't and why."
+   })
+   ```
+
+   The worktree isolation keeps the main session clean if test-writer's
+   exploration touches many files.
+
+6. **Report results**
 
-5. **Report results**
+   After the agent returns:
 
    | File | Before | After | Tests Added | Notes |
    |------|--------|-------|-------------|-------|

package/templates/commands/update-claude-md.md

@@ -2,17 +2,106 @@
 description: "Propose updates to CLAUDE.md based on session work and recurring patterns"
 ---
 
-Based on this session's work, propose updates to CLAUDE.md:
+Propose updates to CLAUDE.md based on this session's work AND the project's
+captured learnings. Apply changes only with explicit per-change consent.
 
-Review what happened:
-- Any mistakes that should become rules
-- Any patterns discovered that should be documented
-- Any gotchas encountered
+## Sources of proposals
 
-Write the proposed additions to the Gotchas section or
-Critical Rules section. Show the diff before applying.
+Look at three places, in priority order:
+
+1. **`.claude/learnings/` directory** — surface promotion candidates.
+
+   `learn-capture.cjs` writes one file per `[LEARN]` category and
+   **appends** when the same category is captured again. The directory's
+   `index.json` updates `created` to the latest capture date — treat it
+   as "last touched," not "first created." See the `memory-architecture`
+   skill for the full layer model.
+
+   Concrete promotion algorithm — a learning is a candidate when at
+   least one of these holds:
+
+   - **Recurrence:** the file at `.claude/learnings/<category>.md`
+     contains **3 or more** `**Rule:**` blocks. Count by scanning the
+     file directly (the index doesn't track count). Three independent
+     captures of the same category is the threshold for "this isn't a
+     fluke."
+   - **Recency:** the index entry's `created` date is within the last
+     **14 days**. Recent learnings are warmer signals than old ones.
+   - **Drift:** the learning's content is structurally relevant to an
+     existing `CLAUDE.md` section (e.g., a "always do X" pattern that
+     belongs in `## Critical Rules` or `## Gotchas`) but the rule is
+     missing from `CLAUDE.md`.
+
+   A candidate satisfying *only* recency is weak — surface it but rank
+   it below a recurring or drift-aligned candidate. Prefer learnings
+   that hit two or three signals at once.
+
+   **Out of scope for now:** Claude Code's auto memory at
+   `~/.claude/projects/<slug>/memory/` is NOT scanned. Auto memory is
+   personal-scoped; promotion to `CLAUDE.md` (team-scoped) requires
+   the user's explicit reasoning and is mediated through `/learn`.
+   This may be revisited once Phase 6a observability ships.
+
+2. **This session's mistakes** — if Claude made the same mistake twice
+   in this session, it's a candidate for a Gotchas entry. Once-per-session
+   mistakes are not yet rule-worthy.
+
+3. **This session's discoveries** — non-obvious patterns the user
+   confirmed are worth documenting (e.g., "we always do X here because Y").
+
+## Pre-apply checks
+
+Run these before proposing any addition:
+
+### Size check
+
+Read CLAUDE.md and count lines. Compare against `worclaude doctor` thresholds:
+
+- **<= 150 lines:** safe to add. Proceed.
+- **151–200 lines (WARN zone):** ask via `AskUserQuestion` whether to
+  proceed. Each addition pushes closer to the 200-line ERROR threshold.
+- **>= 200 lines (ERROR zone):** **block additions** unless the user
+  explicitly accepts the bloat via `AskUserQuestion`. Strongly suggest
+  pruning before adding.
+
+### Dedup check
+
+For every proposed addition, scan CLAUDE.md for semantic overlap with
+existing content. If the proposed rule restates an existing rule:
+
+- Surface the existing rule + the proposed rule side-by-side.
+- Offer via `AskUserQuestion`:
+  - `update in place` — replace the existing rule with the new wording
+  - `skip` — drop the proposal (existing rule covers it)
+  - `add anyway` — add the new rule alongside (rare; only if they
+    cover genuinely different angles)
+
+Don't append duplicates silently.
+
+## Apply mechanism
+
+For each surviving proposed change, **prompt via `AskUserQuestion`**:
+
+```
+Question: "Apply this update to CLAUDE.md?"
+
+Proposed addition (in <section>):
+  <exact text to insert>
+
+- yes  — apply now
+- no   — drop this proposal
+- edit — show the text, I'll refine before saving
+```
+
+Refuse to write any change without an answer. **Do not batch multiple
+changes into one prompt** — each addition gets its own consent gate so
+the user can accept some and reject others.
+
+When all proposals are resolved, write the resulting CLAUDE.md once
+and report: "Applied N of M proposals. K dropped, L deduped, P deferred."
 
 ## Trigger Phrases
 - "update CLAUDE.md"
 - "add to rules"
 - "update project rules"
+- "promote learnings"

package/templates/commands/verify.md

@@ -1,20 +1,44 @@
 ---
-description: "Run full project verification — tests, build, lint, type checking"
+description: "Run fast read-only verification — tests + lint (and optional prettier --check)"
 ---
 
-Run full project verification:
+<!-- references package.json -->
+
+Run the project's fast read-only verification suite.
 
 When invoked with arguments, use them to scope what to verify. Example: `/verify just the auth module`
 
 Arguments: $ARGUMENTS
 
-1. Run the test suite
-2. Run the build
-3. Run the linter
-4. Run type checking (if applicable)
-5. Run any domain-specific verification
+## Scope (locked)
+
+`/verify` is intentionally narrow:
+
+1. **Run the test suite** — the project's primary test runner
+2. **Run the linter** — fail on any lint error
+3. **Optional: `prettier --check`** (or equivalent format check) — read-only
+   format drift detection. Skip if the project does not use a format checker.
+
+That is the entire scope. Report results clearly. Do not proceed if any check fails.
+
+## Read-only contract
+
+`/verify` MUST NOT modify files. No formatter auto-fix, no test fixture
+regeneration, no `--fix`-style flags. If a tool would write anything to disk
+during a check, find the read-only equivalent (e.g., `prettier --check` not
+`prettier --write`, `eslint` not `eslint --fix`).
+
+## What is NOT in /verify
+
+- **Build** — slow and not a "drift check." Use `/build-fix` if the build is broken.
+- **Type checking** — covered by the `strict` hook profile's PostToolUse hook
+  for projects that want it on every edit. Not part of the standard /verify
+  contract.
+- **Domain-specific end-to-end verification** — that is the `verify-app`
+  agent's job, invoked separately when needed.
 
-Report results clearly. Do not proceed if any check fails.
+This narrow scope is deliberate: /verify is the fast feedback loop.
+Adding more checks slows it down and erodes the "run before every commit" habit.
 
 ## Trigger Phrases
 - "verify everything"