@tianhai/pi-workflow-kit 0.18.1 → 1.0.0

package/skills/pwk-code-review/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: pwk-code-review
+description: "Review a completed requirement's code — trace the logic, check spec alignment against the acceptance criteria, fix code smells, and run a production hazard check. Runs after each requirement in pwk-executing-tasks. Unlocked: may edit code to apply smell fixes."
+---
+
+# Code Review
+
+Review the code just implemented for a requirement. **Unlocked** — you may edit code to apply smell fixes; flag everything else as a follow-up.
+
+## Process
+
+1. **Identify the scope** — the requirement just completed (from the progress file / most recent commit). Read its acceptance criteria and integration tests from the plan doc. Run `git log --oneline -5` and `git diff` to see exactly what changed for this requirement.
+
+2. **🔍 Code tracing** — trace the new/changed code paths end-to-end against the integration tests. For each path: does data flow correctly from entry to the asserted outcome? Note any branch the tests don't exercise, any dead branch, any path where the trace breaks.
+
+3. **📐 Spec alignment** — for each acceptance criterion, point to the code and the test that satisfy it. A criterion with no covering code or no test is a **gap**. Code that does more than the criteria specify is **scope creep** — flag it.
+
+4. **🧹 Code smells — fix these directly:**
+   - Shallow modules (interface nearly as complex as the implementation)
+   - Duplication
+   - Missing seams / premature abstraction
+   - Poor naming, magic values, dead code
+   Apply the fix, re-run the integration tests (must stay green), and commit. If a smell needs a refactor large enough to risk the requirement, **flag** it instead of applying.
+
+5. **⚠️ Production hazard check** — audit the changed code against the high-risk hazards. For each, write `[SAFE]` (1-line justification) or `[TRIGGERED]` (concrete mitigation):
+   1. **Unbounded operations** — multi-key deletions/scans (`KEYS`, raw `SCAN` loops), or full-table loads filtered in memory.
+   2. **Missing indexes** — hot queries on unindexed columns (table scans under load).
+   3. **Unbounded concurrency** — unthrottled fan-out (`Promise.all` without batch limits).
+   4. **Long-running transactions** — holding DB connections/locks across slow external calls.
+   5. **Query/command interpolation** — raw variables merged into SQL or shell (injection).
+   6. **Unrestricted uploads / temp flooding** — uploads to local temp without limits or `finally` cleanup.
+   7. **Silent swallowing loops** — background workers catching and suppressing exceptions without logging/back-off.
+   Also check the design's `## Production-risk areas`, if any.
+
+6. **Report** — summarize: tracing findings, spec gaps, smells fixed (with commits), hazards `[TRIGGERED]`. Non-trivial findings become follow-up items — the user decides whether to address now or defer.
+7. **Mark done** — update the requirement's progress-file row from `🔎 review` to `✅ done`. Done means reviewed, not just committed.
+
+## Principles
+
+- **Tracing and spec alignment are the core** — they catch what tests miss: untested branches, missing criteria, scope creep.
+- **Fix smells in place; flag everything else.** Don't redesign.
+- **Be proportional** — a one-function change doesn't need the depth of a batch pipeline.
+
+## After the review
+
+Return to `/skill:pwk-executing-tasks` for the next requirement, or `/skill:pwk-finalizing` if all requirements are done.

package/skills/pwk-diagnose/SKILL.md

@@ -53,4 +53,5 @@ Required before declaring done:
 - Regression test passes (or absence of seam is documented)
 - All `[DEBUG-...]` instrumentation removed
 - Ask: what would have prevented this bug?
-- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/plans/adr/` capturing that insight
+- If the answer is a repeatable pattern, append a **generic** rule to `docs/lessons.md` (strip domain specifics) so future sessions catch it early.
+- If the bug was caused by an architectural problem (no good test seam, tangled callers, hidden coupling), suggest writing an ADR to `docs/adr/` capturing that insight

package/skills/pwk-executing-tasks/SKILL.md

@@ -1,380 +1,154 @@
 ---
 name: pwk-executing-tasks
-description: "Use this to implement an approved plan task-by-task. Run after pwk-writing-plans, before finalizing."
+description: "Implement a plan requirement-by-requirement with test-first discipline and full autonomy. Run after pwk-writing-plans. Each requirement: write integration tests (red) → checkpoint → implement to green → checkpoint → pwk-code-review."
 ---
 
 # Executing Tasks
 
-Implement the plan from `docs/plans/*-implementation.md` task by task, with file-based progress tracking and session-aware context management.
+Implement the plan from `docs/plans/*-implementation.md` requirement-by-requirement, with file-based progress tracking.
+
+The plan is a **behavioral spec** (acceptance criteria + integration tests). You have **full autonomy** to choose structure, signatures, and internals — the acceptance criteria and integration tests define *what*; you decide *how*. Do not ask the plan for implementation steps; it deliberately doesn't contain them.
 
 ## Before you start
 
-1. **Check git state** — run `git status` and `git log --oneline -5`. Note any uncommitted changes.
-2. **Find the plan** — look for `docs/plans/*-design.md` to get the Features table. Find the feature with status `🔄 planned`. The plan doc is `docs/plans/YYYY-MM-DD-<topic>-<slugified-feature-name>-implementation.md`. If no design doc exists, fall back to looking for a single `*-implementation.md` (backward compatibility with plans not using the feature table). This covers plans created without a brainstorm session (no design doc or Features table). If multiple plan docs exist and no design doc, ask the user which one to execute.
-3. **Check for existing progress** — look for `docs/plans/*-progress.md`. If one exists matching the plan, this is a **resume** (see [Resume](#resume)). If not, this is a **first run** (see [First run](#first-run)).
+1. **Check git state** — `git status` and `git log --oneline -5`. Note uncommitted changes.
+2. **Find the plan + report** — look for `docs/plans/*-implementation.md`. If several, list them and ask which. Print a one-line discovery report, e.g. `Found: design "auth" — execute phase (1/3 requirements done)`. If a matching `*-progress.md` exists, this is a **resume** (see [Resume](#resume)).
+3. **Workspace isolation should already be done** — `pwk-writing-plans` set up the branch/worktree before handoff. If you land here still on `main`, tell the user the workspace wasn't set up and suggest doing it before executing.
 
 ## First run
 
-1. **Parse the implementation plan** — read the plan and extract all `## Task N:` headings. Build the progress table with all tasks as `⬜ pending`.
-2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
-
-   - **Branch** (smaller changes):
-     ```
-     git checkout -b <feature-name>
-     ```
-   - **Worktree** (larger features, keeps main clean):
-     ```
-     git worktree add ../<repo>-<feature-name> -b <feature-name>
-     ```
-
-   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
-
-3. **If worktree was chosen — hand off to new session:**
-
-   a. Ensure the worktree's `docs/plans/` directory exists:
-      ```
-      mkdir -p <worktree>/docs/plans
-      mkdir -p <worktree>/docs/plans/adr
-      ```
-
-   b. Move plan docs into the worktree:
-
-      > When using the feature table, all plan docs for this design move together — completed feature plans, the current feature's plan, and the design doc. This is intentional: the worktree works on one design at a time.
-
-      ```
-      mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
-      ```
-
-   c. Commit the removal on the current branch (if any plan docs were committed):
-      ```
-      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
-      git rm -r docs/plans/adr/ 2>/dev/null || true
-      git commit -m "chore: move plan docs to worktree for <feature-name>"
-      ```
-
-   d. Stop and show the user:
-      ```
-      ✅ Worktree created at ../<repo>-<feature-name>
-      📄 Plan docs moved to the worktree.
-
-      To continue, start a new session there:
-        cd ../<repo>-<feature-name> && pi
-
-      Then run: /skill:pwk-executing-tasks
-      ```
-
-   e. **Create the progress file** in the worktree — save to `<worktree>/docs/plans/<plan-name>-progress.md`:
-
-      ```markdown
-      # Progress: <topic>
-
-      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-      Branch: <feature-name>
-      Started: <ISO timestamp>
-      Last updated: <ISO timestamp>
-
-      | # | Status | Task | Commit |
-      |---|--------|------|--------|
-      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-      ```
-
-      This ensures the new session in the worktree will detect the progress file and resume correctly.
-
-   f. **Do not proceed with task execution.** The session ends here.
-
-4. **If branch was chosen — continue with execution:**
-
-   a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
-
-      ```markdown
-      # Progress: <topic>
+1. **Parse the plan** — read all `## Requirement N:` headings. Build the progress table with all requirements as `⬜ pending`. Process them in **listed order** — the plan is already in build order; do not reorder.
+2. **Setup pre-flight** — if the plan has a `## Setup` section, follow it: install dependencies, apply migrations, and seed data. Run the existing test suite to confirm nothing broke. **⏸ CHECKPOINT: setup** — present the migration/output to the human and wait for approval.
+   - **approve** → continue.
+   - **request changes** → revise and re-present.
+   (Only runs on the first `First run` — the progress file is created after this step, so a resumed session skips setup.)
+3. **Create the progress file** at `docs/plans/<plan-name>-progress.md`:
 
-      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-      Branch: <actual branch name>
-      Started: <ISO timestamp>
-      Last updated: <ISO timestamp>
+   ```markdown
+   # Progress: <topic>
 
-      | # | Status | Task | Commit |
-      |---|--------|------|--------|
-      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-      ```
+   Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
+   Branch: <branch>
+   Started: <ISO timestamp>
+   Last updated: <ISO timestamp>
 
-      Use the actual branch name — whether it's the original branch or a new one from the isolation step.
-
-   b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
-      ```
-      git add docs/plans/ && git commit -m "docs: add design and implementation plan"
-      ```
-
-   c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
+   | # | Status | Requirement | Commit |
+   |---|--------|-------------|--------|
+   | 1 | ⬜ pending | <requirement name> | — |
+   ```
+4. **Commit the plan docs** — `git add docs/plans/ && git commit -m "docs: add implementation plan"`.
+5. Begin requirement 1 (see [Per-requirement execution](#per-requirement-execution)).
 
 ## Resume
 
-1. **Read the progress file** — find the first task with status `⬜ pending`, `❌ failed`, or `🔄 in-progress`.
-2. **Handle in-progress task** — if a task is `🔄 in-progress` (mid-task crash):
-   - Check `git log --oneline` since the last `✅ done` task's commit
-   - If commits exist: ask the user — "Task N was in progress and commits were made. Continue from here, or reset it to pending?"
-   - If no commits: restart the task (reset to `🔄 in-progress` and begin)
-3. **Handle failed task** — if a task is `❌ failed`:
-   - Show the failure reason from the progress file
-   - Ask: "Retry, skip, or abort?"
-4. **Handle pending task** — proceed normally
-5. **All done** — if no `⬜ pending` or `❌ failed` tasks remain, show summary and suggest `/skill:pwk-finalizing`
-6. **Begin task execution** — proceed from the identified task
+1. Read the progress file. Find the first requirement that is `⬜ pending`, `🔄 in-progress`, `⏸ tests-review`, or `⏸ complete-review`.
+2. Resume from the recorded state:
+   - `⏸ tests-review` / `⏸ complete-review` → re-present that checkpoint and wait.
+   - `🔄 in-progress` mid-write → continue the requirement.
+   - `⬜ pending` → start it.
 
 ## Progress file
 
-**Path:** `docs/plans/<plan-name>-progress.md`
-
-**Status values:**
+Path: `docs/plans/<plan-name>-progress.md`. Update the matching row directly (not via pattern matching that could corrupt the table). Update `Last updated` on every change.
 
 | Status | Meaning |
 |--------|---------|
 | `⬜ pending` | Not started |
-| `🔄 in-progress` | Currently executing plan steps |
-| `⏸ test-review` | Paused at checkpoint: test, waiting for human approval |
-| `⏸ done-review` | Paused at checkpoint: done, waiting for human approval |
-| `✅ done` | Committed successfully |
-| `❌ failed` | Could not complete (append `Failed: <reason>`) |
+| `🔄 in-progress` | Writing tests or implementing |
+| `⏸ tests-review` | Paused at checkpoint: tests, awaiting human approval |
+| `⏸ complete-review` | Paused at checkpoint: complete, awaiting human approval |
+| `🔎 review` | Committed; `pwk-code-review` in progress |
+| `✅ done` | `pwk-code-review` complete (smells fixed, hazards noted), all green |
+| `❌ failed` | Could not complete; partial work discarded/reverted (append `Failed: <reason>`) |
 | `⏭ skipped` | User chose to skip |
 
-**Update rules:**
-- Mark `🔄 in-progress` immediately when starting a task
-- Mark `⏸ test-review` or `⏸ done-review` when the agent reaches a `⏸ CHECKPOINT` gate in the plan — this must happen BEFORE any `git add` or `git commit`
-- Can only return to `🔄 in-progress` after the human explicitly says "approve"
-- Mark `✅ done` + record commit hash only after successful `git commit`
-- Cannot go from `🔄 in-progress` → `✅ done` if the task has a checkpoint — must go through the review status first
-- `git add` and `git commit` happen AFTER human approval, never before
-- Mark `❌ failed` + append reason when the agent can't proceed after retrying
-- Mark `⏭ skipped` when the user says "skip"
-- Update `Last updated` timestamp on every change
-- Preserve checkpoint labels in the task description column
-
-## Per-task execution
-
-For each task:
-
-1. **Mark in-progress** — update the progress file: `🔄 in-progress`
-2. **Read the plan** — read the plan's overview section (everything before `## Task 1:`). Extract the `Design:` and `Feature:` metadata to know which design doc and feature row this execution covers. If no `Design:` or `Feature:` metadata is present, the plan covers the entire design (no feature table). Skip design doc reading and proceed directly to task execution. Otherwise, check the current feature's status in the design doc's Features table. Skim all `## Task N:` headings for dependency awareness. Then read the current task's body in full. **Read `docs/lessons.md`** if it exists — follow all rules listed there while working on this task.
-3. **Execute the plan steps** — follow each numbered step in the task body, in order. As you work, shift your cognitive focus through three frames:
-
-   **QA Test frame** (when writing/running tests): Focus entirely on translating the task's `Given/When/Then` Acceptance Criteria into precise failing tests. Before running tests, verify the test environment is sandboxed — no real database connections, API calls, or live services. External dependencies must be mocked or stubbed. Ensure the test environment is isolated (e.g., `NODE_ENV=test`, `GO_ENV=test`, or equivalent for your stack).
-
-   **Pragmatic Developer frame** (when implementing): Focus on the simplest possible code to make the tests green. Do not over-engineer or add code for future requirements. Keep complexity to a bare minimum.
-
-   **Senior Refactoring frame** (when refactoring): Evaluate the craftsmanship of the code. Check for:
-   - **Shallow modules** — is the interface nearly as complex as the implementation? Can complexity be hidden behind a simpler interface?
-   - **Deletion test** — if you deleted this module, would complexity vanish (pass-through) or reappear across callers (earning its keep)?
-   - **Duplication** — extract repeated patterns
-   - **Seam discipline** — don't introduce abstraction unless something actually varies across it. One adapter = hypothetical seam. Two adapters = real seam
-
-   Run tests after each refactor step. Never refactor while tests are failing.
-
-   Stop at any `⏸ CHECKPOINT` gate (see [Checkpoint gates](#checkpoint-gates--when-the-plan-says-stop)).
-4. **Verify against task description** — re-read the task from the plan. Does the implementation satisfy every requirement listed? If not, fix before proceeding.
-5. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
-
-   Before writing, apply the **generalization test**: would this rule apply equally to a completely different feature or domain in this repo? If not, rewrite it — strip out specific service names, entity types, and domain concepts, and express the underlying pattern instead. If you can't express a generic form, don't write the rule.
-
-   ❌ **Domain-specific** (only survives this sprint):
-   > "Always validate `userId` before calling `UserProfile.Get`"
-
-   ✅ **Generic** (applies across the whole repo):
-   > "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
-6. **Commit** — after all steps are done (no checkpoint gates remain in the task), `git add` the relevant files and commit with a clear message.
-7. **Update progress** — mark `✅ done` + record the commit hash.
-8. **Update design doc** — if the progress file shows all tasks for the current feature are `✅ done`, find the design doc (from plan metadata), and mark the current feature row as `✅ done` in the Features table.
-9. **Suggest session break if needed** — after completing ~3-5 tasks since the last break, suggest:
-   ```
-   ✅ Tasks N-M done (commits: abc, def)
-   Progress: X/Y tasks done
-   ⏭  Next: Task [N+1] — [description]
-   💡 Context is building up. For clean context on remaining tasks:
-      /new  then  /skill:pwk-executing-tasks
-      (or just say "continue" to keep going here)
+## Per-requirement execution
+
+For each requirement:
+
+1. **Mark in-progress** — `🔄 in-progress`.
+2. **Write the integration tests (red).** Read the requirement's acceptance criteria + integration-test cases from the plan and write the actual test files. Run them — confirm they **fail** (red). If they pass immediately, the behavior may already exist or the tests are wrong; investigate before proceeding.
+3. **⏸ CHECKPOINT: tests.** Stop. Do not implement yet. Mark `⏸ tests-review`. Present the integration tests and the failing output to the human, and wait for approval. The human reviews whether the right behaviors are being specified.
+   - **approve** → return to `🔄 in-progress` and continue.
+   - **request changes** → revise the tests, re-run, re-present.
+4. **Implement (green).** With full autonomy, implement whatever is needed to make the integration tests pass and satisfy the acceptance criteria — you choose the structure, modules, signatures, and internals. Run the tests after each meaningful change. Refactor for clarity (shallow modules, no duplication, seam discipline) while tests stay green.
+5. **Learn.** If you caught a repeat mistake, append a **generic** rule to `docs/lessons.md` (strip domain specifics).
+6. **⏸ CHECKPOINT: complete.** Stop. Do **not** commit yet. Mark `⏸ complete-review`. Run the tests (show passing output) and `git diff`, present the implementation to the human, and wait for approval.
+   - **approve** → return to `🔄 in-progress` and continue.
+   - **request changes** → revise, re-run, re-present at this same checkpoint.
+7. **Commit.** `git add` the relevant files and commit with a clear message. (Status stays `🔄 in-progress` — not done yet.)
+8. **Code review.** Mark `🔎 review`. Attempt isolated code-review via the `subagent` tool — four agents review the same diff in parallel, each from a different dimension (each gets a fresh context window, zero pollution from previous requirements):
+
+   Gather the requirement's scope: acceptance criteria, integration test cases, and git diff (`git log --oneline -5 && git diff HEAD~N..HEAD`).
+
+   **If the `subagent` tool is available**, invoke it with parallel tasks:
+   ```json
+   {
+     "tasks": [
+       {"agent": "pwk-spec-reviewer", "task": "<scope + diff here>\n\n## Spec Review\nFor each acceptance criterion, point to the code and test that satisfy it. Flag gaps (criterion with no covering code or test) and scope creep (code beyond criteria). Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
+       {"agent": "pwk-tracing-reviewer", "task": "<scope + diff here>\n\n## Trace Review\nTrace every new/changed code path end-to-end against tests. Note untested branches, dead branches, paths where the trace breaks. Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
+       {"agent": "pwk-smell-reviewer", "task": "<scope + diff here>\n\n## Smell Review\nReport: shallow modules (interface ≈ implementation complexity), duplication, missing seams / premature abstraction, poor naming, magic values, dead code. Flag only: smells requiring risky large refactors. Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."},
+       {"agent": "pwk-hazard-reviewer", "task": "<scope + diff here>\n\n## Hazard Review\nAudit changed code against these hazards: unbounded ops (KEYS/SCAN/full-table loads), missing indexes, unbounded concurrency (Promise.all without limits), long-running transactions, query/command interpolation (injection), unrestricted uploads/temp flooding, silent swallowing loops. Write [SAFE] (1-line reason) or [TRIGGERED] (mitigation). Report only — do not modify files. Your findings are collected by the parent agent which applies fixes and commits changes."}
+     ],
+     "agentScope": "both",
+     "cwd": "<repo-root>"
+   }
    ```
-   Also suggest at checkpoint review pauses when multiple tasks have been completed since the last break. Respect the user's choice if they say "continue".
-10. **Loop** — go back to step 1 for the next `⬜ pending` task, or see [After all tasks](#after-all-tasks) if none remain.
 
-### `docs/lessons.md` format
-
-```markdown
-# Lessons Learned
-
-<!--
-Agent: read this at the start of each task during executing-tasks.
-Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
-Retire rules that no longer apply during finalizing.
--->
-
-## Rules
-
-- <new rule here>
-```
+   **On success:** collect all findings. For smell-review findings: identify the smells, apply the fixes yourself (re-run integration tests after changes — must stay green, commit). For trace/spec/hazard findings: flag as follow-ups for human decision or later fix. Update the progress-file row to `✅ done`. Flag non-trivial issues as follow-ups.
 
-When adding a new rule during execution, always append it under `## Rules`. The categorization into specific headers (e.g., `## Tool Usage`, `## Testing Patterns`) is done during finalizing — never during execution.
+   **Fallback** (subagent unavailable or returns error): revert to inline review — run `/skill:pwk-code-review` for this requirement as before.
+9. **Loop** — go to step 1 for the next `⬜ pending` requirement, or see [After all requirements](#after-all-requirements).
 
-### Checkpoint gates — when the plan says STOP
+### Checkpoint gates are mandatory
 
-The plan marks certain steps with `⏸ **CHECKPOINT: test**` or `⏸ **CHECKPOINT: done**`. These are hard stop points. When you reach one:
-
-1. **Stop executing immediately.** Do not proceed to the next step in the task. Do not pass go.
-2. **Do NOT run `git add` or `git commit`.** The code stays uncommitted until the human approves.
-3. Update the progress file to `⏸ test-review` or `⏸ done-review`.
-4. Present the checkpoint review (see below).
-5. **Wait for the human to respond.** Do not continue executing steps, do not commit, do not move to the next task.
-6. On approval, update progress back to `🔄 in-progress` and continue with the next step in the task.
-
-The whole point of checkpoints is that the human reviews code at critical moments before the agent proceeds further. If you skip past a checkpoint without waiting, you defeat this purpose.
-
-| Checkpoint type | What the agent has done at this point | What needs human approval |
-|---|---|---|
-| `checkpoint: test` | Written failing tests, confirmed they fail | The test design — are the right things being tested? |
-| `checkpoint: done` | Implemented, refactored, written lessons | The implementation approach, the refactoring choices |
-
-**For `checkpoint: test`:** Only the test file should exist at this point. No implementation code yet. The human reviews the test to confirm the right behavior is being specified.
-
-**For `checkpoint: done`:** All code changes are made but NOT committed. Run `git diff` (not `git diff --cached` — nothing should be staged) to show the human what changed. The human reviews before anything is committed.
-
-## Checkpoint review
-
-When you hit a checkpoint gate, present a review to the human and **stop all execution** until they respond.
-
-### At `checkpoint: test`
-
-You have written the failing tests and confirmed they fail. No implementation code exists yet.
-
-Present:
-```
-⏸ Paused at checkpoint: test for task [N]
-
-**Test file:** `path/to/test.ts`
-
-**Test code:**
-[show the full test code]
-
-**Test results:** [paste the failing test output showing which tests fail and why]
-
-**What this validates:** [summarize the behavior these tests specify]
-**Next step after approval:** Write the implementation to make these tests pass
-
-What would you like to do?
-- **approve** — I'll implement to make these tests pass
-- **request changes** — tell me what to change in the tests
-- **revert** — undo this task and go back to pending
-- **skip** — skip this task entirely
-- **stop** — pause here, resume later with /skill:pwk-executing-tasks
-- **status** — show the full progress table
-```
-
-### At `checkpoint: done`
-
-You have implemented the code, run the refactor step, and written any lessons. Nothing is committed yet.
-
-Present:
-```
-⏸ Paused at checkpoint: done for task [N]
-
-**What was done:** [brief summary — what feature/fix was implemented]
-
-**Test results:** [run tests now, paste the passing output]
-
-**Diff:** [run `git diff` — the unstaged changes are what this task produced]
-[paste the full diff]
-
-**Refactoring done:** [what changed during refactor, or "none needed — [reason]"]
-**Lessons learned:** [new rule added to docs/lessons.md, or "none"]
-**Next step after approval:** git add, commit, and move to next task
-
-What would you like to do?
-- **approve** — I'll commit and move to the next task
-- **request changes** — tell me what to change, I'll update and re-present
-- **revert** — undo this task and go back to pending
-- **skip** — skip this task entirely
-- **stop** — pause here, resume later with /skill:pwk-executing-tasks
-- **status** — show the full progress table
-```
-
-**Do not commit before the human approves.** The diff you show at `checkpoint: done` is the uncommitted work. If the human requests changes, make the edits, re-run tests, and re-present the updated diff at the same checkpoint. Repeat until they say "approve".
-
-Only after approval: `git add` the relevant files, commit, and mark the task `✅ done`.
-
-## Progress file updates
-
-Update the progress file by reading it, modifying the relevant row's status and commit hash, and writing it back. Target the specific task row — do not use pattern-matching approaches (e.g. sed) that could corrupt the table.
-
-Update `Last updated` timestamp on every change.
+Both checkpoints are **hard stops, not optional**. When you reach one:
+- Stop executing immediately. Do not pass it without explicit human approval.
+- **Never** `git add` or `git commit` before the human approves at a checkpoint.
+- Mark the progress file to the review status **before** pausing.
 
 ## User override commands
 
-The user can issue these commands at any time during execution:
-
 | User says | Agent does |
 |-----------|-----------|
-| `skip` | Mark current task `⏭ skipped`, move to next |
+| `skip` | Mark current requirement `⏭ skipped`, move to next |
 | `status` | Show the progress table |
-| `stop` | Mark current task back to `⬜ pending`, suggest `/new` |
-| `retry` | Re-read current task section, start over |
-
-## Receiving code review
+| `stop` | Restore current requirement to its pre-in-progress state, suggest `/new` to resume later |
+| `retry` | Re-read the requirement, start over |
 
-When the user shares code review feedback (outside of a checkpoint pause):
+## Receiving feedback (outside a checkpoint)
 
-1. **Verify the criticism** — read the relevant code. Is the feedback accurate?
-2. **Evaluate the suggestion** — is the proposed fix the right approach? Consider alternatives.
-3. **Implement or push back** — if valid, fix it, re-run tests, and amend the commit. If not, explain why with evidence from the codebase.
-4. **Don't blindly implement** — every suggestion should be verified against the code before accepting.
-
-## If you're stuck
+When the user shares review feedback outside a checkpoint: verify the criticism against the code, evaluate the suggestion, then implement (with tests) or push back with evidence. Don't blindly apply.
 
-1. Re-read the current task section from the plan — you may have drifted from the spec
-2. Check git log — recent commits may reveal context
-3. Ask the user — it's better to clarify than to guess wrong
-4. If still stuck after asking, mark the task `❌ failed` with the reason in the progress file and move to the next task
-5. **Check `docs/lessons.md`** — a previous lesson may be relevant to your current problem.
+## After all requirements
 
-## After all tasks
+When no `⬜ pending` or `❌ failed` requirements remain, run the **integration gate** before suggesting finalize. Per-requirement code-review only saw each requirement's diff in isolation — this is where you prove the requirements *compose* into the feature:
 
-When no `⬜ pending` or `❌ failed` tasks remain for the current feature, read the design doc's Features table. Show the per-task summary from the progress file, then check for more features:
+1. **Run the FULL test suite** (not just the last requirement's tests). Every test must pass. A failure here means one requirement regressed another — fix it now, in execute context, while the progress file and fix autonomy are at hand.
+2. **Confirm the requirements compose** into the feature the design doc described. Each requirement passed alone; do they deliver the intended end-to-end behavior *together*? If integration exposes a gap, fix it here (with tests) before shipping.
 
-### More features remaining
+Only when the full suite is green and the feature works end-to-end:
 
 ```
-✅ Feature "<feature name>" complete.
-
-| # | Status | Task |
-|---|--------|------|
-| 1 | ✅ done | Create User model |
-| 2 | ✅ done | Add signup endpoint |
-
-⏭  Next: "<next pending feature name>"
-💡 Options:
-   - Plan next feature: /skill:pwk-writing-plans
-   - Verify this feature first: /skill:pwk-verify
-   - Or just say "continue"
-```
+✅ All requirements complete — integration verified!
 
-### All features complete
+| # | Status | Requirement |
+|---|--------|-------------|
+| 1 | ✅ done | <name> |
+| … | … | … |
 
+   - Ship: /skill:pwk-finalizing
 ```
-✅ All features complete!
 
-| # | Status | Feature |
-|---|--------|---------|
-| 1 | ✅ done | User signup |
-| 2 | ✅ done | Email verification |
-| 3 | ⏭ skipped | Password reset |
+## If you're stuck
 
-| # | Status | Task |
-|---|--------|------|
-| 1 | ✅ done | Create User model |
-| 2 | ✅ done | Add signup endpoint |
-| ... | ... | ... |
+1. Re-read the requirement's acceptance criteria — you may have drifted.
+2. Check `git log` for context.
+3. Ask the user — clarify beats guessing.
+4. If still stuck:
+   - Discard uncommitted changes (`git restore .`).
+   - If the requirement has already been committed (step 7 completed), also revert its commit(s) so partial work leaves no trace on the shipped branch (`git revert HEAD --no-edit` if only the requirement commit; `git revert HEAD~N..HEAD --no-edit` if multiple commits including code-review smell fixes).
 
-   - Verify everything: /skill:pwk-verify
-   - Ship: /skill:pwk-finalizing
-```
+   **Never leave a failed requirement's partial work on the shipped branch.** Dead code from incomplete requirements must be cleaned up before moving on.
+5. Mark `❌ failed` with the reason and move on.
+6. Check `docs/lessons.md` — a prior lesson may apply.