specweave 1.0.593 → 2.0.0

package/plugins/specweave/skills/do/SKILL.md

@@ -1,273 +1,55 @@
 ---
-description: Execute increment tasks following spec and plan with sync hooks. Use when saying "implement", "start working", "execute tasks", or "continue increment". IMPORTANT - Before starting, check task count and domain count. If 3+ domains or 15+ tasks, recommend sw:team-lead instead (ask user for confirmation, or auto-invoke in auto mode).
-version: 1.0.0
+description: Work an increment task by task through the ledger: task next, claim, implement, commit, task done with evidence. Use when saying "implement", "start working", or "continue increment".
+version: 2.0.0
 argument-hint: "<increment-id>"
 ---
 
 # Do Increment
 
-## Project Overrides
-
-**Skill Memories**: If `.specweave/skill-memories/do.md` exists, read and apply its learnings.
-
-## Project Context
-
-**Project Context**: If `.specweave/config.json` exists, read it for testing mode, TDD enforcement, and multi-project settings. Check for active increments in `.specweave/increments/*/metadata.json`.
-
-Execute a SpecWeave increment by running tasks from tasks.md with automatic AC-sync after every task completion.
+Work an increment task by task through the ledger. State lives in
+`.specweave/increments/<id>/ledger.jsonl` (append-only); `tasks.md` holds the
+definitions. Never hand-edit status lines — `specweave task done` renders them.
 
 ## Usage
 
 ```
-sw:do <increment-id>    # Execute specific increment
-sw:do                   # Auto-select best candidate
-sw:do <id> --model <model-id>  # Override the model (effort stays at xhigh)
+sw:do [<increment-id>]     # id optional when exactly one increment is active
 ```
 
-- `<increment-id>`: Optional. Supports "001", "0001", "1", "0042", or "0153-feature-name" formats.
-- `--model <model-id>`: Optional. Overrides the model. Effort stays at `xhigh`.
-
-All tasks execute at the `xhigh` effort tier (Opus 4.7 default). Use `--model` to override the model if needed, but effort stays at xhigh.
-
-## Tool-Use Rationale
-
-- **Read**: Load spec.md, plan.md, tasks.md, and any referenced living docs before executing a task.
-- **Edit**: Apply task-scoped code changes and flip `[ ]` → `[x]` in tasks.md after verification passes.
-- **Write**: Create new files the task defines (source, tests, migrations).
-- **Bash**: Run the task's test command and project-level verification (`npx vitest run`, `pytest`, `go test ./...`).
-
----
-
-## Workflow
-
-### Step 1: Smart Increment Auto-Selection
+## Loop (repeat until `task next` returns nothing)
 
-When no ID provided, auto-select (NEVER ask user for ID):
-
-1. Scan by priority: `in-progress` > `planned` > `ready_for_review` (with incomplete tasks) > `backlog` (with incomplete tasks)
-2. For each candidate, count incomplete tasks: `grep -c '^\- \[ \]'` + `grep -c '\*\*Status\*\*: \[ \]'` in tasks.md
-3. Select best candidate and auto-promote to in-progress if needed
-4. If no candidates, show status summary and offer: create new, close ready_for_review, resume backlog, or view status
-
-### Step 1.5: Auto-Mode Context Override
-
-When running inside an active auto session (`.specweave/state/auto-mode.json` has `active: true`):
-
-1. **Explicit ID takes priority**: If an explicit increment ID was passed (e.g., `sw:do 0252`), use it directly — skip this step
-2. **Stop hook guidance**: If the stop hook feedback in the current conversation mentions a specific increment ID (e.g., "Continue: sw:do 0252"), use that ID
-3. **Read incrementIds**: If no ID from above, read `incrementIds` array from `auto-mode.json` and use the **first entry** — this is the increment prioritized by scoring at session start
-4. **Skip filesystem scanning**: When auto-mode context provides an increment ID via steps 2 or 3, skip Step 1's filesystem scanning entirely — auto-mode context takes priority
-
-This ensures the execution loop stays focused on the contextually correct increment rather than re-scanning the filesystem each iteration.
-
-### Step 2: Load Context
-
-1. **Find increment directory**: Normalize ID to 4-digit format, match `.specweave/increments/NNNN-*/`
-2. **Load files**: Read `spec.md`, `plan.md`, `tasks.md`, `tests.md`
-3. **Load living docs**: Check ADRs and specs in `.specweave/docs/internal/` for related context
-4. **Verify readiness**: Status is planned/in-progress, no blocking deps, tasks exist
-5. **Task count validation**: If >25 tasks, warn and offer to split, phase, or use `sw:auto`/`sw:team-lead`
-6. **Validate AC presence** (MANDATORY):
-   Check that spec.md contains AC-IDs (e.g., `AC-US1-01`). If missing: add ACs to spec.md before proceeding. Do NOT proceed without ACs in spec.md.
-
-### Step 2.5: PR-Based Branch Setup (conditional)
-
-Check push strategy:
-```bash
-PUSH_STRATEGY=$(jq -r '.cicd.pushStrategy // "direct"' .specweave/config.json 2>/dev/null)
-```
+1. **Pick**: `specweave task next <id>` — prints the first open task whose deps are done and whose `Files` are not held by another agent. If several increments are active, pass the id.
+2. **Claim**: `specweave task claim T-NN <id>`. Exit 3 = someone else owns it (pick another), 4 = its Files overlap a live claim, 6 = deps not done. Never edit before claiming.
+3. **Read**: the task's `AC:` ids in spec.md and its `Files:`; open plan.md (or spec.md Approach) only for that scope.
+4. **Implement** inside the task's `Files` only. Need another file → claim the task that owns it, or add a task (`### T-NN Title` + `- AC: … | Files: … | Test: …`).
+5. **Commit** with the increment id in the subject: `git commit -m "<id>: <what>"`.
+6. **Done with evidence**: `specweave task done T-NN <id> --run "<Test command>"` (uses the task's `Test:` when `--run` is omitted). Exit 5 = the command failed → task stays open; fix and re-run. No `Test:` → `--evidence "<sha + what you ran>"`. Never claim completion without a fresh, passing run.
+7. **Stuck?** `specweave task block T-NN <id> --reason "<what is missing>"`; not needed? `specweave task skip T-NN <id> --reason "<why>"` (terminal).
+8. Go to 1.
 
-**If `pr-based`:**
-1. Read git config:
-   ```bash
-   BRANCH_PREFIX=$(jq -r '.cicd.git.branchPrefix // "sw/"' .specweave/config.json 2>/dev/null)
-   ```
-2. Compute branch name: `BRANCH_NAME="${BRANCH_PREFIX}${INCREMENT_ID}"`
-3. Check current branch: `CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)`
-4. If not on the feature branch:
-   - Branch exists? `git branch --list ${BRANCH_NAME}` → `git checkout ${BRANCH_NAME}`
-   - Branch doesn't exist? `git checkout -b ${BRANCH_NAME}`
-5. For umbrella/multi-repo: repeat in each `repositories/*/*/` that has a `.git` directory
-6. Log: `"Working on feature branch: ${BRANCH_NAME}"`
+## Rules
 
-**If `direct`:** Skip this step entirely (no-op, current behavior preserved).
+- One agent per worktree when 2+ agents share the increment; branch name contains the increment id.
+- Append only: never edit or delete ledger lines, never touch another task's state line.
+- If a claim older than 2h (config `tasks.leaseHours`) has no `done`, it is stale — `task next` offers it again; `task claim --force` takes it over.
+- Stopping for any reason: `specweave task release --all-mine` then `sw:handoff`.
+- No CLI? Append the line yourself: `echo '{"t":"T-01","e":"claim","by":"<agent>","at":"<ISO>"}' >> ledger.jsonl` (PowerShell: `[IO.File]::AppendAllText`). `by` = `SPECWEAVE_AGENT` or `<tool>@<host>`.
 
-### Step 2.7: Execution Strategy Check
+## Increment selection (no id given)
 
-**Skip this step if already running inside `sw:auto` or `sw:team-lead`.** Check `.specweave/state/auto-mode.json` — if `active: true`, skip.
+- Exactly one `metadata.json` with `status: active` → use it.
+- Several → `specweave task list` errors listing candidates; ask which, or take the one named in the auto-mode context / stop-hook feedback.
+- None active but exactly one `planned` → the CLI uses it, and `task claim` starts it (`planned → active`). `specweave start <id>` does it explicitly.
+- None at all → `sw:increment` first.
 
-Assess increment complexity to recommend the best execution mode:
+## Finish (mandatory, never stop to ask)
 
-1. **Count pending tasks**: `grep -c '^\- \[ \]\|Status\*\*: \[ \]' tasks.md`
-2. **Count domains**: Scan spec.md and plan.md for distinct technology areas (frontend, backend, database, API, DevOps, security, mobile, ML/AI). Each distinct area = 1 domain.
-3. **Count ACs**: `grep -c 'AC-US' spec.md`
-
-**Recommendation matrix** (see CLAUDE.md Execution Strategy):
-
-| Tasks | Domains | Action |
-|-------|---------|--------|
-| ≤8 | 1 | Proceed with `sw:do` silently |
-| 9-15 | 1-2 | Suggest `sw:auto` for unattended execution |
-| >15 | 1-2 | Recommend `sw:auto` (many tasks benefit from autonomous loop) |
-| any | 3+ | Recommend `sw:team-lead` for parallel multi-agent execution |
-
-**When recommending (non-auto mode)**, use `AskUserQuestion` with these options:
-- `sw:do` — Continue manual step-by-step (current mode)
-- `sw:auto` — Autonomous sequential execution (unattended, stop-hook loop)
-- `sw:team-lead` — Parallel multi-agent execution (higher quality for multi-domain, uses more tokens)
-
-Include trade-off note: "Team-lead and auto modes consume more tokens but deliver higher precision and quality for complex work."
-
-If user chooses auto or team-lead, invoke the chosen skill with the increment ID and **stop sw:do execution**.
-
-**In auto mode (`.specweave/state/auto-mode.json` active)**: If 3+ domains detected, automatically invoke `sw:team-lead` instead of proceeding sequentially.
-
-### Step 3: TDD Setup
-
-Read `testMode` from metadata.json:
-```bash
-TEST_MODE=$(cat "$INCREMENT_PATH/metadata.json" | jq -r '.testMode // "test-after"')
-```
-
-If TDD mode active:
-- Show TDD reminder banner (RED > GREEN > REFACTOR)
-- Detect phase from task title markers: `[RED]`, `[GREEN]`, `[REFACTOR]`
-- **Validate TDD markers exist** in tasks.md. If missing:
-  - `strict` enforcement: BLOCK, require regeneration via `sw:increment`
-  - `warn` (default): warn and proceed
-  - `off`: silent pass
-- **Enforce order**: GREEN requires RED complete; REFACTOR requires GREEN complete
-  - Read enforcement: `jq -r '.testing.tddEnforcement // "warn"' .specweave/config.json`
-  - `strict`: block violations; `warn`: warn but allow; `off`: no check
-
-### Step 4: Smart Resume
-
-1. Parse tasks.md, find first incomplete task (`[ ]`)
-2. Run every task at the `xhigh` effort tier (Opus 4.7 default) — legacy tiered hints in tasks.md are ignored
-3. Show resume context with completion percentage
-
-### Step 5: Update Status
-
-If status is "planned", update to "in-progress" with start date in spec.md frontmatter.
-
-### Step 6: Execute Tasks Sequentially
-
-#### Iron Law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
-
-Before marking ANY task `[x]`, you MUST run verification and see it pass:
-
-1. **Run the task's test command** — if the task has a `**Test**:` or `**Test Plan**:` block, execute the test command specified there. Capture the output.
-2. **Fallback to project-level tests** — if no task-specific test exists, run the project test command (e.g., `npx vitest run`, `pytest`, `go test ./...`).
-3. **Failing test = task stays `[ ]`** — if the test command fails, the task is NOT complete. Present the failure output, diagnose, fix, and re-run until green.
-4. **Evidence is mandatory** — "should work" is not evidence. "Tests pass" without running them is not evidence. Only fresh command output counts.
-
----
+When `task next` says nothing is claimable and every task is done or skipped:
 
-For each task:
-
-1. **Read task details**: ID, description, ACs, file paths
-2. **Run at xhigh effort**: All tasks execute at the `xhigh` effort tier (Opus 4.7 default). `--model` only overrides the model; effort stays at xhigh.
-3. **Execute**: Follow plan.md architecture, implement, write clean code
-4. **Verify**: Run the task's test command (see Iron Law above). Only proceed if green.
-5. **Mark complete**: Change `[ ]` to `[x]` in tasks.md — ONLY after verification passes
-
-**After EVERY task completion** (CRITICAL):
-
-- **AC-sync hook fires automatically** (via PostToolUse on Edit/Write) updating spec.md ACs
-- **Update docs inline**: CLAUDE.md (new commands/config/skills), README.md (user-facing changes), CHANGELOG.md (API/breaking changes), openapi.yaml (if API task + apiDocs.enabled)
-- **GitHub sync** (if plugin enabled): close task issue, check off in epic, post completion comment
-- Continue to next incomplete task
-
-### Step 6.5: Per-Task Review Gate (Opt-In)
-
-**Check config flag**:
-```bash
-PER_TASK_REVIEW=$(jq -r '.quality.perTaskReview // false' .specweave/config.json 2>/dev/null)
-```
-
-**Skip this gate entirely if**:
-- `quality.perTaskReview` is absent or `false` (default — backward compatible)
-- Running inside `sw:team-lead` (team-lead has its own review flow). Detect via: `ls ~/.claude/teams/ 2>/dev/null | head -1` — if any entries exist, skip.
-
-**When the gate is active** (`perTaskReview: true`), after each task passes verification (Step 6) but before moving to the next task:
-
-#### Sub-review 1: Spec Compliance
-
-Dispatch a lightweight review checking whether this task's implementation satisfies its linked ACs:
-
-- Read the task's `**Satisfies ACs**:` field to get the relevant AC IDs
-- For each AC, verify the implementation matches the spec requirement
-- Adversarial framing: "Prove each AC is satisfied with evidence from the code diff"
-- If any AC is not satisfied: fix before proceeding
-
-#### Sub-review 2: Code Quality
-
-Dispatch a focused code quality review of ONLY this task's diff:
-
-- Review only files changed by this task (not the entire codebase)
-- Check: correctness, error handling, naming, no obvious security issues
-- Severity threshold: only CRITICAL and HIGH findings block progress
-- MINOR and SUGGESTION findings are noted but don't block
-
-#### Gate Rule
-
-Both sub-reviews must pass before marking the task `[x]` and moving to the next task. If either review finds blocking issues (CRITICAL/HIGH), fix them first. This prevents drift from accumulating across tasks.
-
-### Step 7: Handle Blockers
-
-If task blocked: document in tasks.md, present options to user, skip or pause depending on severity.
-
-### Step 8: Run Tests
-
-After testable tasks: run relevant tests, fix failures immediately, only continue when green.
-
-### Step 9: Completion (MANDATORY AUTO-CHAIN — NEVER STOP HERE)
-
-**CRITICAL**: When all tasks are done, IMMEDIATELY chain to closure. Do NOT stop to ask for review, do NOT report "all tasks complete" and wait. The quality gates inside `sw:done` (grill, judge-llm, PM validation) ARE the review. If the user wants to re-open, they can.
-
-When all tasks done:
-1. Run `sw:sync-docs update` to sync living docs
-2. Run tests: `npx vitest run` (if test framework detected)
-
-#### Step 9a: Closure via Subagent (Claude Code — preferred)
-
-If the `Agent` tool is available, spawn a closure subagent for a fresh context:
-
-```typescript
-Agent({
-  subagent_type: "sw:sw-closer",
-  prompt: "Close increment <ID>. Increment path: .specweave/increments/<ID>/",
-  description: "Close increment <ID>"
-})
-```
-
-The sw-closer runs grill, judge-llm, PM gates, and `specweave complete` in an isolated context.
-Do NOT invoke `sw:grill` or `sw:done` inline when using the subagent path.
-
-#### Step 9b: Direct Closure (Non-cloud tools / fallback)
-
-If the `Agent` tool is NOT available (Cursor, Copilot, Aider, OpenCode), invoke closure directly:
-
-1. Invoke `Skill({ skill: "sw:grill" })` with increment ID — writes required `grill-report.json`
-2. Invoke `Skill({ skill: "sw:done" })` with increment ID — runs judge-llm, PM gates, closes, and syncs to GitHub/Jira/ADO
-
-Non-cloud tools typically have fresh context per skill invocation, so inline closure works without overflow.
-
-**Anti-pattern** (NEVER do this): "All tasks are complete. Would you like me to close the increment?" — Just close it.
-
----
-
-## Credentials Auto-Execute
-
-Before deployment tasks, check credentials (NEVER display values):
-```bash
-grep -qE "SUPABASE|DATABASE_URL|CF_|AWS_|HETZNER" .env 2>/dev/null && echo "Credentials found"
-```
-If found: execute directly. If missing: ask user for credential.
-
----
+1. `specweave verify <id>` → `reports/verify.json` (project test/lint/build + AC table + ledger).
+2. Invoke `Skill({ skill: "sw:done" })` with the id. It runs the optional review and `specweave complete`.
 
-Run `sw:validate` after execution to ensure quality before closing with `sw:done`.
+Anti-pattern: "All tasks are complete. Should I close?" — close it.
 
 ## Resources
 

package/plugins/specweave/skills/done/SKILL.md

@@ -1,281 +1,40 @@
 ---
-description: Close increment with PM 3-gate validation (tasks, tests, docs). Use when all tasks complete and saying "close increment", "we're done", or "finish up".
-version: 1.0.0
-argument-hint: "<increment-id> [--auto]"
+disable-model-invocation: true
+description: Close an increment: ledger check, specweave verify, optional review, then specweave complete. Use when all tasks are done and saying "close increment", "we are done", or "finish up".
+version: 2.0.0
+argument-hint: "<increment-id> [--reason <text>]"
 ---
 
-# Close Increment (PM Validated)
+# Close Increment
 
-## Tool-Use Rationale
-
-- **Bash**: Invoke the CLI closure gate (`specweave complete`), run `npx vitest run` and `npx playwright test` to verify the suite is green, and read `jq` values from `.specweave/config.json`.
-- **Read**: Load `code-review-report.json`, `grill-report.json`, `judge-llm-report.json`, and `rubric.md` to evaluate gate outcomes.
-- **Edit**: Update `metadata.json` status and any inline docs (CLAUDE.md, CHANGELOG.md) touched by the closure step.
-
-## Prompt Caching
-
-`sw:done` is a closure orchestrator that chains `code-reviewer`, `simplify`, `grill`, and `judge-llm`. Because the same increment context is loaded four times over, Anthropic's ephemeral prompt caching gives closure a substantial cost/latency win.
-
-**Files cached by default** (via `static-context-loader`):
-- `CLAUDE.md` (project root)
-- `.specweave/config.json`
-- The active increment's `spec.md`
-- The active increment's `rubric.md` (if present)
-
-**Cache window**: 5-minute TTL (Anthropic's `cache_control: { type: "ephemeral" }` breakpoint). Consecutive gate invocations within the TTL read the cached prefix instead of re-tokenizing it.
-
-**Extending the list**: Add paths to `cache.staticContextFiles` in `.specweave/config.json`:
-```json
-{
-  "cache": {
-    "staticContextFiles": [
-      "CLAUDE.md",
-      ".specweave/config.json",
-      ".specweave/docs/internal/specs/team-conventions.md"
-    ]
-  }
-}
-```
-
-**Disable caching**: Set `cache.staticContextFiles: []` in `.specweave/config.json`. Closure gates will still run but without the shared prefix cache.
-
-See `.specweave/docs/internal/specs/config-reference.md` and `opus-47-migration.md` for the full caching setup.
-
-## Project Overrides
-
-**Skill Memories**: If `.specweave/skill-memories/done.md` exists, read and apply its learnings.
-
-**PM-Led Closure**: Validate tasks, tests, and docs before closing.
-
-**AUTO-CLOSURE DEFAULT**: After `sw:do` completes all tasks, `sw:done` runs automatically — no user confirmation needed. Quality gates (code-review, simplify, grill, judge-llm, PM validation) provide the safety net. If something is wrong, the user can re-open the increment.
-
-## Context Overflow Prevention
-
-For large multi-agent sessions (via `sw:team-lead`), running `sw:done` directly may cause context overflow due to loading 4+ skill definitions into an already-full context. Instead, `sw:team-merge` spawns `sw:sw-closer` subagents that run the full closure pipeline in isolated fresh contexts -- one per increment. The `sw-closer` agent definition is at `plugins/specweave/agents/sw-closer.md`.
-
-If you are closing an increment from a normal (non-team) session, use `sw:done` directly as documented below.
+Closure = **verify → optional review → `specweave complete`**. The only hard
+gate is `reports/verify.json` with `ok: true`. Grill / judge / rubric reports
+are optional evidence and never block.
 
 ## Usage
 
 ```
-sw:done <increment-id> [--auto]
+sw:done <increment-id>                    # normal closure
+sw:done <increment-id> --reason "<why>"   # close without a green verify (recorded as metadata.closeReason)
 ```
 
-Argument: Required increment ID (e.g., "001", "0001", "0042", "0153-feature-name"). Numeric portion extracted and zero-padded to 4 digits.
-
-## Options
-
-| Option | Description |
-|--------|-------------|
-| `--auto` | Legacy flag, now a no-op. Auto-closure is the default for all modes. All quality gates (code-review, simplify, grill, judge-llm, Gate 0, PM gates) always enforced. |
-
----
-
-## Workflow
-
-### Step 1: Self-Awareness Check (OPTIONAL)
-
-If closing a SpecWeave framework increment, show post-closure reminders: update CHANGELOG.md, CLAUDE.md, consider version bump, run `npm test && npm run rebuild`, check for breaking changes. Informational only, not blocking.
-
-### Step 2: Code Review (MANDATORY — STOP GATE with Fix Loop)
-
-**The CLI blocks closure if `code-review-report.json` is missing (when required).** Do NOT skip this step.
-
-1. Check config: `jq -r '.codeReview.required // true' .specweave/config.json` — if `false`, skip to Step 3
-2. Read max iterations: `MAX_ITER=$(jq -r '.codeReview.maxFixIterations // 5' .specweave/config.json 2>/dev/null)` — default cap is **5** in SpecWeave 1.1.0 (Opus 4.7 converges faster per iteration, so a higher cap catches edge cases without stalling closure)
-3. Read blocking severities: defaults are `critical`, `high`, `medium` (configurable via `codeReview.blockingSeverities`)
-4. **Iteration loop** (ITERATION=1):
-   a. Invoke `Skill({ skill: "sw:code-reviewer", args: "--increment <id>" })`
-   b. **Verify report written**: `Bash({ command: "test -f .specweave/increments/<id>/reports/code-review-report.json && echo OK || echo MISSING" })`
-   c. If report MISSING: write it manually from code-reviewer output using the Write tool
-   d. Read the report JSON: parse the `summary` object for severity counts
-   e. **Evaluate blocking findings**: Sum counts for `critical` + `high` + `medium` (or configured severities)
-   f. If no blocking findings → PASS, continue to Step 3
-   g. If blocking findings exist AND ITERATION < MAX_ITER:
-      - Display findings summary
-      - Implement fixes for all critical/high/medium issues from the report
-      - Increment ITERATION
-      - Delete the stale report: `rm -f .specweave/increments/<id>/reports/code-review-report.json`
-      - Go back to step 4a (re-run code-reviewer)
-   h. If blocking findings exist AND ITERATION >= MAX_ITER:
-      - **STOP closure** — display remaining findings
-      - Log: "Code review failed after {N} fix iterations. {X} findings remain."
-      - Increment stays in-progress
-
-### Step 3: Simplify (Non-Blocking Cleanup)
-
-Code review passed. Run simplify to clean up code before the grill examines it.
-
-1. Invoke `Skill({ skill: "simplify" })` — this is a built-in Claude Code skill, NOT a `sw:` skill
-2. `/simplify` spawns 3 parallel agents checking: duplication, readability, efficiency
-3. Apply any suggested improvements
-4. **Non-blocking**: Even if simplify finds issues, proceed to Step 4 (Grill)
-5. Purpose: Clean code before grill reduces grill findings and improves ship readiness
-
-### Step 4: Inline Grill Review (MANDATORY — STOP GATE)
-
-**The CLI blocks closure if `grill-report.json` is missing.** Do NOT skip this step.
-
-1. Check config: `jq -r '.grill.required // true' .specweave/config.json` — if `false`, skip to Step 5
-2. Invoke `Skill({ skill: "sw:grill" })` with incrementId
-3. **Verify report written**: `Bash({ command: "test -f .specweave/increments/<id>/reports/grill-report.json && echo OK || echo MISSING" })`
-4. If report MISSING: write it manually from grill output using the Write tool
-5. BLOCKERs or CRITICALs (shipReadiness: NOT READY) → STOP closure, ask user to fix
-6. Passes → continue
-
-### Step 5: Judge LLM Validation (MANDATORY — STOP GATE)
-
-**A report file MUST be written regardless of outcome (even WAIVED if consent denied).**
-
-1. **Consent check**: Check `externalModels` in config. If denied, write WAIVED report and continue
-2. Invoke `Skill({ skill: "sw:judge-llm" })` with `--last-commit` (or `--staged`)
-3. **Verify report written**: `Bash({ command: "test -f .specweave/increments/<id>/reports/judge-llm-report.json && echo OK || echo MISSING" })`
-4. If report MISSING: write a WAIVED report with reason "Skill did not produce report"
-5. **APPROVED** → continue | **CONCERNS** → show, allow continuation | **REJECTED** → STOP closure
-6. No ANTHROPIC_API_KEY or consent denied → write WAIVED report, continue
-
-### Step 6: Status Validation
-
-- `ready_for_review` -> Proceed
-- `active` -> Check all tasks done, transition to `ready_for_review` first
-- `completed` -> Already closed, warn user
-- `backlog` / `paused` / `abandoned` -> BLOCK with error
-
-**No confirmation needed**: Proceed directly to closure. Quality gates (code-review, simplify, grill, judge-llm, Gate 0, PM gates) are the safety net — NOT user confirmation prompts. NEVER stop to ask "should I close this?" — just close it. If a gate fails, the increment stays open automatically. If the user disagrees with closure, they can re-open.
-
-### Step 7: Load Increment Context
-
-1. Find increment directory: normalize ID to 4-digit, match `.specweave/increments/0001-*/`
-2. Load: `spec.md`, `plan.md`, `tasks.md`, `tests.md`
-
-### Step 8: Automated Completion Validation (Gate 0)
-
-MANDATORY, cannot be bypassed. Runs BEFORE PM validation.
-
-1. **Sync ACs first**: `ACStatusManager.syncACStatus(incrementId)` -- prevents race conditions with background hooks
-2. **Desync check**: `DesyncDetector.validateOrThrow(incrementId)` -- blocks if metadata.json/spec.md inconsistent
-3. **Completion validation**: `IncrementCompletionValidator.validateCompletion(incrementId)`
-
-**Rubric Quality Contract**: If `rubric.md` exists in the increment directory, rubric evaluation runs automatically via the completion-validator. The validator reads rubric.md, evaluates all criteria against gate reports (grill-report.json, code-review-report.json, judge-llm-report.json), and blocks closure if any `[blocking]` criterion has status FAIL or PENDING. Advisory failures are reported as warnings. If rubric.md does not exist, the existing hardcoded gates run unchanged (backward compatible). Review any blocking rubric failures before retrying closure.
-
-**Gate 0 validates**:
-- All ACs checked in spec.md (`- [x] **AC-...`)
-- All tasks completed in tasks.md (`**Status**: [x] completed`)
-- Required files exist (spec.md, tasks.md)
-- Tasks count in frontmatter matches checked tasks (source of truth)
-- AC coverage: all ACs covered by tasks (100%), no orphan tasks, all US linkage valid
-
-If validation fails -> increment stays in-progress, command exits.
-
-### Step 9: PM Validation (3 Gates)
-
-PM validation report goes in: `.specweave/increments/####-name/reports/PM-VALIDATION-REPORT.md`
-
-**Gate 1 - Tasks Completed**: All P1 done, P2 done or deferred with reason, P3 done/deferred/backlogged, no blocked tasks, ACs met.
-
-**Gate 2a - E2E Tests (AUTOMATED, BLOCKING)**: Detect playwright/cypress configs (including `repositories/*/*-e2e`). If found, run them. E2E failure blocks closure. No E2E detected -> skip.
-
-**Gate 2 - Tests Passing**: All suites passing, coverage >80% critical paths, no unexplained skips, tests align with ACs.
-
-**Gate 3 - Documentation Updated**: CLAUDE.md, README.md, CHANGELOG.md updated as needed. Inline docs complete. No stale references.
-
-### Step 10: PM Decision
-
-**All gates pass**:
-1. Create marker file: `mkdir -p .specweave/state && touch .specweave/state/.sw-done-in-progress`
-2. Run completion via CLI: `Bash({ command: "specweave complete <id> --yes" })` — the CLI re-verifies quality gate reports (code-review-report.json, grill-report.json, judge-llm-report.json) exist. It also triggers `LifecycleHookDispatcher.onIncrementDone()` for living docs sync, GitHub Project sync, and issue closure.
-3. Remove marker file: `rm -f .specweave/state/.sw-done-in-progress`
-4. Generate completion report, update backlog
-
-**CRITICAL**: Do NOT directly edit metadata.json to set status. Always use the `specweave complete` CLI command — it is the single completion path that triggers all post-closure hooks.
-
-**Any gate fails**:
-- Show failures and blockers with estimated fix effort
-- If GitHub issue exists, reopen it with failure details
-- Increment remains in-progress
-
-### Step 10.5: Pull Request Creation (pr-based only)
-
-Check push strategy:
-```bash
-PUSH_STRATEGY=$(jq -r '.cicd.pushStrategy // "direct"' .specweave/config.json 2>/dev/null)
-```
-
-**If `pr-based`:**
-1. Invoke `sw:pr` skill: `Skill({ skill: "sw:pr", args: "<increment-id>" })`
-2. Verify PR was created: check metadata.json for `prRefs` with `state: "open"`
-3. If PR creation failed: **warn but do NOT block closure**. The increment is already completed. PR is a distribution mechanism, not a quality gate.
-4. Display PR URL(s) for human review.
-
-**If `direct`:** Skip this step entirely (existing behavior unchanged).
-
-### Step 11: Post-Closure Sync (AUTOMATIC via CLI hooks)
-
-The `specweave complete` call in Step 10 triggers `LifecycleHookDispatcher.onIncrementDone()` which automatically handles:
-
-- **Living docs sync** (`sync_living_docs` flag): Updates feature specs and user story files
-- **GitHub Project sync** (`sync_to_github_project` flag): Pushes spec to GitHub Project
-- **Issue closure** (`close_github_issue` flag): Closes GitHub/JIRA/ADO issues via SyncCoordinator
-
-After the CLI completes, display the sync result summary:
-
-```
-| Hook                     | Result                    |
-|--------------------------|---------------------------|
-| Living docs sync         | OK / FAILED: {reason}     |
-| GitHub Project sync      | OK / SKIPPED              |
-| Issue closure            | OK / SKIPPED              |
-```
-
-If any operation failed, display: "Run `sw:progress-sync` to retry failed sync operations."
-
-**Supplemental closure** (not handled by hooks — run manually if applicable):
-
-**A) Close external-origin issue** (E-suffix increments only): Parse `metadata.external_ref` (format: `github#owner/repo#number`). Check `sync.settings.canUpdateStatus` permission. Close via `gh issue close -R`.
-
-**B) Close ALL per-user-story GitHub issues**: If the hook-based closure missed any, search by title pattern:
-1. Read `sync.github.owner` and `sync.github.repo` from config.json
-2. Extract the feature ID from spec.md frontmatter or increment ID
-3. For EACH user story in spec.md, search: `gh issue list -R {owner}/{repo} --search "[{feature_id}][{us_id}]" --state open --json number`
-4. Close each: `gh issue close {number} -R {owner}/{repo} -c "Completed as part of increment {increment_id}"`
-
-### Step 12: Sync Living Docs (MANDATORY)
-
-Execute: `Skill({ skill: "sw:sync-docs" })` with the increment ID. Do NOT just mention it -- actually invoke it. This serves as a verification pass to confirm living docs are up to date after closure.
-
-### Step 12b: Update Links in Docs (MANDATORY)
-
-After living docs sync, update cross-references and bidirectional links so existing docs reference the newly created feature specs. Do NOT skip this step:
-
-1. Read the feature spec files created by Step 12 (`.specweave/docs/internal/specs/{project}/FS-XXX/FEATURE.md` and `us-*.md`)
-2. Update existing docs (FEATURE-CATALOG, module docs, etc.) with links to the new specs
-3. Verify bidirectional links between increment → feature spec → living docs
-4. Change `[DRAFT]` → `[COMPLETE]` on doc sections matching completed ACs
-
-Verify that `.specweave/docs/internal/specs/{project}/FS-XXX/` contains `FEATURE.md` and `us-*.md` files. If missing, re-run Step 12.
-
-### Step 13: Post-Closure Quality Assessment
-
-Runs ONLY if closure succeeded. Invoke: `sw:qa ${incrementId}`
-
-Evaluates 7 dimensions: Clarity, Testability, Completeness, Feasibility, Maintainability, Edge Cases, Risk Assessment.
-
-- Score >=80 -> PASS, proceed
-- Score 60-79 -> CONCERNS, log and suggest improvements
-- Score <60 -> FAIL, recommend follow-up increment
-
-Report saved to: `.specweave/increments/####/reports/qa-post-closure.md`
+## Steps
 
-Quality assessment runs AFTER closure (not blocking delivery). Critical issues trigger follow-up increment creation.
+1. **Ledger check**: `specweave task list <id>`. Every task must be `done` or `skipped`. Open/claimed tasks → go back to `sw:do` (or `task skip … --reason "<why>"`). Release your own claims: `specweave task release --all-mine`.
+2. **Verify**: `specweave verify <id>`. Runs `testing.commands` from config (else `npm run test|lint|build`, `cargo test`, `pytest`, `go test ./...`), writes `reports/verify.md` + `reports/verify.json`. Non-zero exit → fix, re-run. Do not proceed on red without a `--reason` from the user.
+3. **Review (recommended for anything user-facing, optional otherwise)**: invoke `Skill({ skill: "sw:review" })` — fresh context, adversarial, findings cite `path:line`, written to `reports/review.md`. Fix critical/high findings, re-run step 2 if code changed.
+4. **Docs touched?** If the increment changed commands, config, or user-facing behaviour, update README/CHANGELOG/CLAUDE.md `## Commands` in the same commit. Living docs sync only if `livingDocs` is enabled in config (`specweave docs sync <id>`).
+5. **Complete**: `Bash({ command: "specweave complete <id> --yes" })`. The CLI refuses when `verify.json` is missing or not ok unless `--reason "<text>"` is given; it prints a notice when `reports/review.md` is absent; it sets `status: completed` and syncs GitHub/Jira/ADO when configured. **Never edit `metadata.json` status by hand.**
+6. **Handoff**: if work continues elsewhere (follow-ups, another increment), `sw:handoff`.
 
-### Step 14: Handle Incomplete Work
+Report in one paragraph: verify result, review verdict (or "skipped"), commit sha(s), anything deferred.
 
-If scope creep detected, offer options:
-- A) Complete all tasks (estimate effort)
-- B) Move extra tasks to next increment (close now)
-- C) Split into 2 increments (recommended)
+## Rules
 
-Transfer tasks creates new increment with dependencies on current one.
+- Never ask "should I close?" — closure follows automatically when tasks are done; the user can re-open.
+- `--skip-validation` exists for emergencies only; prefer `--reason` so the reason is recorded.
+- Multi-agent sessions (`sw:team`): only the lead runs `sw:done`, after every agent has released and handed off.
+- Failed sync after completion: `specweave sync push <id>` retries; closure itself already succeeded.
 
 ## Resources