pincer-workflow 0.4.0 → 0.4.1

package/README.md

@@ -86,7 +86,7 @@ want the repo-side rules too can copy `AGENTS.md` from the
 npx pincer-workflow@latest update
 ```
 
-Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file. v0.2.2 replaces the Codex adapter: the commands are now skills in `.agents/skills/` invoked as `$pincer-*`, since Codex no longer loads `~/.codex/prompts/` — you can delete the copies there. v0.2.3 ships the playbooks, rubrics and templates under `.claude/` on every platform, which Codex- and Copilot-only installs were missing. v0.3.0 makes trust revocable: every verification attempt is recorded, `done` re-runs the check, tickets carry `prd:`, the release audit is read-only, and `.pincer.json` moves to schema 2 — an install from 0.2.x is treated as an untrusted baseline, so on the first update every changed file arrives as a `.new` proposal once; hooks now need Node 18+. v0.4.0 carries requirement IDs and `Proves:` checks from the PRD to evaluation, adds `profile: small|standard`, and saves candidate evidence under `.prd/evidence/`; the update is additive, but an existing `NOTES.md` without an `evidence:` manifest reads as stale until `/pincer-evaluate` is re-run.) Files you edited are left
+Files you never touched are refreshed in place. (Installs older than v0.2.0 gain the ticket state machine, the status report and the ticket-guard hook on update; `.claude/settings.json` conflicts if you edited it — merge the new hook entry from the `.new` file. v0.2.2 replaces the Codex adapter: the commands are now skills in `.agents/skills/` invoked as `$pincer-*`, since Codex no longer loads `~/.codex/prompts/` — you can delete the copies there. v0.2.3 ships the playbooks, rubrics and templates under `.claude/` on every platform, which Codex- and Copilot-only installs were missing. v0.3.0 makes trust revocable: every verification attempt is recorded, `done` re-runs the check, tickets carry `prd:`, the release audit is read-only, and `.pincer.json` moves to schema 2 — an install from 0.2.x is treated as an untrusted baseline, so on the first update every changed file arrives as a `.new` proposal once; hooks now need Node 18+. v0.4.0 carries requirement IDs and `Proves:` checks from the PRD to evaluation, adds `profile: small|standard`, and saves candidate evidence under `.prd/evidence/`; the update is additive, but an existing `NOTES.md` without an `evidence:` manifest reads as stale until `/pincer-evaluate` is re-run. v0.4.1 is playbook wording only: the code playbook gains one recovery exception (a tree back at the evaluated candidate is restored by the user and nothing is committed), evaluate records one check per command, and plan asks only the open part of a partly answered question.) Files you edited are left
 alone — the new version lands next to them as `<file>.new` for a manual merge.
 `npx pincer-workflow doctor` checks the health of an install (hook executable,
 `.gitignore` covering `.env*`, no unmerged `*.new` files, version current).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "PINCER — a PRD-driven agentic delivery workflow for Claude Code, Codex CLI, and GitHub Copilot. Plan · Investigate · Narrow · Code · Evaluate · Release.",
   "bin": {
     "pincer": "bin/pincer.js"

package/template/.agents/skills/pincer-code/SKILL.md

@@ -89,7 +89,20 @@ the script or `scripts/pincer-status.sh` printed, and hand the repair to the use
 performs it in their own terminal. Then return through the lifecycle — `start`,
 `verify`, `done` — so the ticket carries fresh verification; a restored receipt is
 never evidence. Do not recommend restoring source files or unrelated edits as routine
-ticket repair. Automated recovery that preserves attempt history is later work (M1).
+ticket repair. One exception: when the PRD is built with valid candidate evidence,
+tracked files other than the ticket file being restored match the evaluated candidate
+(or the candidate plus its evidence-only commit) with nothing untracked, and the
+ticket's Verification block passes when run
+directly rather than through `verify` (which would write a receipt), then
+the committed evaluation still describes the tree. Say so, name the exact command
+for the user to restore the ticket file in their own terminal, and
+do not run `verify`, refresh the receipt or commit anything — the restored file is
+what is already committed, not new evidence. If the block fails on that clean tree,
+the failure is real: keep the failed `last_check` and repair through the lifecycle.
+If source still differs from the candidate, name the differing paths and let the
+user decide rather than asking which way to fix them; permission to restore a ticket
+does not authorize discarding source changes. Automated recovery that preserves
+attempt history is later work (M1).
 
 ## Budget rules
 

package/template/.agents/skills/pincer-evaluate/SKILL.md

@@ -66,7 +66,16 @@ run the pipeline, then present results.
    write fresh evidence in step 9 — never reuse a manifest from a previous candidate.
 9. Persist evidence for the candidate under `.prd/evidence/prd-vN/<candidate>/`:
    - `checks/C-NN.log` — the command and a redacted summary or safe log of each
-     executable check. Never secrets, never an environment dump.
+     executable check. Never secrets, never an environment dump. Record
+     one check per command: `command` holds the command line as run, never prose
+     describing a session, and a manual smoke run is recorded as the command lines
+     that were run (separate entries when they establish independent outcomes).
+     Independently assessed commands — the tracked `.env` check, the secret scan,
+     the dependency audit — are separate `checks` entries with their own `result`
+     and log, so only the tool that could not run is `unverified`. A test runner
+     such as `npm test` stays one aggregate check; do not split every subprocess or
+     assertion. Visual and review checks keep their kinds and get no artificial
+     shell command. Note a redaction rather than inventing a substitute command.
    - `visual/<scenario>.png` — each visual capture from step 4, with its scenario,
      viewport and observed result recorded in the manifest. When nothing renders,
      record `visual_review: {applicable: false, reason}` and say why.

package/template/.agents/skills/pincer-plan/SKILL.md

@@ -36,12 +36,20 @@ unless the user explicitly authorized a separate change.
    IDs; do not silently replace either. Where its structure needs adapting to the
    template, record a mapping table (`their section or ID → R-NN`) inside the PRD.
 2. Ask only the questions whose answers would change the architecture or scope.
-   Batch them (max 3–4 at once). Typical ones:
+   Batch them (max 3–4 at once). A question the brief partly answers is
+   asked only for its open part, naming the settled part; when the brief settles
+   every material decision, including acceptance behavior, ask no discovery
+   question and record the brief's answers. Do not add a question to fill the budget.
+   Typical ones:
    - What does "done" look like — what will be run, demoed, or reviewed at the end?
+     A named test runner settles the verification choice, not every acceptance
+     behavior; ask about the demo or manual check only if that is still open.
    - Any required stack, or is it my choice?
    - What is explicitly out of scope?
 3. If the project has a frontend, ask one design question: "What should this feel like,
    and what should it NOT look like?" Capture the answer for the Visual Direction section.
+   The same rule applies: when the brief already supplies design direction, record it
+   and ask only about what it leaves open.
 
 Summarize your understanding in 3–5 sentences. Existing authorization in the request or
 session carries forward; ask only about an unresolved choice that materially changes the result.

package/template/.agents/skills/pincer-status/SKILL.md

@@ -23,3 +23,5 @@ start of a session. Read-only: change nothing.
    `$pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
    without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.
    Never restore a ticket file from git to clear a warning; a failed attempt is a record.
+   The one exception is the tree-back-at-candidate case in the recovery section of
+   `$pincer-code`: the user restores the ticket file, and nothing is verified or committed.

package/template/.claude/commands/pincer-code.md

@@ -87,7 +87,20 @@ the script or `scripts/pincer-status.sh` printed, and hand the repair to the use
 performs it in their own terminal. Then return through the lifecycle — `start`,
 `verify`, `done` — so the ticket carries fresh verification; a restored receipt is
 never evidence. Do not recommend restoring source files or unrelated edits as routine
-ticket repair. Automated recovery that preserves attempt history is later work (M1).
+ticket repair. One exception: when the PRD is built with valid candidate evidence,
+tracked files other than the ticket file being restored match the evaluated candidate
+(or the candidate plus its evidence-only commit) with nothing untracked, and the
+ticket's Verification block passes when run
+directly rather than through `verify` (which would write a receipt), then
+the committed evaluation still describes the tree. Say so, name the exact command
+for the user to restore the ticket file in their own terminal, and
+do not run `verify`, refresh the receipt or commit anything — the restored file is
+what is already committed, not new evidence. If the block fails on that clean tree,
+the failure is real: keep the failed `last_check` and repair through the lifecycle.
+If source still differs from the candidate, name the differing paths and let the
+user decide rather than asking which way to fix them; permission to restore a ticket
+does not authorize discarding source changes. Automated recovery that preserves
+attempt history is later work (M1).
 
 ## Budget rules
 

package/template/.claude/commands/pincer-evaluate.md

@@ -64,7 +64,16 @@ run the pipeline, then present results.
    write fresh evidence in step 9 — never reuse a manifest from a previous candidate.
 9. Persist evidence for the candidate under `.prd/evidence/prd-vN/<candidate>/`:
    - `checks/C-NN.log` — the command and a redacted summary or safe log of each
-     executable check. Never secrets, never an environment dump.
+     executable check. Never secrets, never an environment dump. Record
+     one check per command: `command` holds the command line as run, never prose
+     describing a session, and a manual smoke run is recorded as the command lines
+     that were run (separate entries when they establish independent outcomes).
+     Independently assessed commands — the tracked `.env` check, the secret scan,
+     the dependency audit — are separate `checks` entries with their own `result`
+     and log, so only the tool that could not run is `unverified`. A test runner
+     such as `npm test` stays one aggregate check; do not split every subprocess or
+     assertion. Visual and review checks keep their kinds and get no artificial
+     shell command. Note a redaction rather than inventing a substitute command.
    - `visual/<scenario>.png` — each visual capture from step 4, with its scenario,
      viewport and observed result recorded in the manifest. When nothing renders,
      record `visual_review: {applicable: false, reason}` and say why.

package/template/.claude/commands/pincer-plan.md

@@ -34,12 +34,20 @@ unless the user explicitly authorized a separate change.
    IDs; do not silently replace either. Where its structure needs adapting to the
    template, record a mapping table (`their section or ID → R-NN`) inside the PRD.
 2. Ask only the questions whose answers would change the architecture or scope.
-   Batch them (max 3–4 at once). Typical ones:
+   Batch them (max 3–4 at once). A question the brief partly answers is
+   asked only for its open part, naming the settled part; when the brief settles
+   every material decision, including acceptance behavior, ask no discovery
+   question and record the brief's answers. Do not add a question to fill the budget.
+   Typical ones:
    - What does "done" look like — what will be run, demoed, or reviewed at the end?
+     A named test runner settles the verification choice, not every acceptance
+     behavior; ask about the demo or manual check only if that is still open.
    - Any required stack, or is it my choice?
    - What is explicitly out of scope?
 3. If the project has a frontend, ask one design question: "What should this feel like,
    and what should it NOT look like?" Capture the answer for the Visual Direction section.
+   The same rule applies: when the brief already supplies design direction, record it
+   and ask only about what it leaves open.
 
 Summarize your understanding in 3–5 sentences. Existing authorization in the request or
 session carries forward; ask only about an unresolved choice that materially changes the result.

package/template/.claude/commands/pincer-status.md

@@ -21,3 +21,5 @@ start of a session. Read-only: change nothing.
    `/pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
    without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.
    Never restore a ticket file from git to clear a warning; a failed attempt is a record.
+   The one exception is the tree-back-at-candidate case in the recovery section of
+   `/pincer-code`: the user restores the ticket file, and nothing is verified or committed.

package/template/.github/prompts/pincer-code.prompt.md

@@ -89,7 +89,20 @@ the script or `scripts/pincer-status.sh` printed, and hand the repair to the use
 performs it in their own terminal. Then return through the lifecycle — `start`,
 `verify`, `done` — so the ticket carries fresh verification; a restored receipt is
 never evidence. Do not recommend restoring source files or unrelated edits as routine
-ticket repair. Automated recovery that preserves attempt history is later work (M1).
+ticket repair. One exception: when the PRD is built with valid candidate evidence,
+tracked files other than the ticket file being restored match the evaluated candidate
+(or the candidate plus its evidence-only commit) with nothing untracked, and the
+ticket's Verification block passes when run
+directly rather than through `verify` (which would write a receipt), then
+the committed evaluation still describes the tree. Say so, name the exact command
+for the user to restore the ticket file in their own terminal, and
+do not run `verify`, refresh the receipt or commit anything — the restored file is
+what is already committed, not new evidence. If the block fails on that clean tree,
+the failure is real: keep the failed `last_check` and repair through the lifecycle.
+If source still differs from the candidate, name the differing paths and let the
+user decide rather than asking which way to fix them; permission to restore a ticket
+does not authorize discarding source changes. Automated recovery that preserves
+attempt history is later work (M1).
 
 ## Budget rules
 

package/template/.github/prompts/pincer-evaluate.prompt.md

@@ -66,7 +66,16 @@ run the pipeline, then present results.
    write fresh evidence in step 9 — never reuse a manifest from a previous candidate.
 9. Persist evidence for the candidate under `.prd/evidence/prd-vN/<candidate>/`:
    - `checks/C-NN.log` — the command and a redacted summary or safe log of each
-     executable check. Never secrets, never an environment dump.
+     executable check. Never secrets, never an environment dump. Record
+     one check per command: `command` holds the command line as run, never prose
+     describing a session, and a manual smoke run is recorded as the command lines
+     that were run (separate entries when they establish independent outcomes).
+     Independently assessed commands — the tracked `.env` check, the secret scan,
+     the dependency audit — are separate `checks` entries with their own `result`
+     and log, so only the tool that could not run is `unverified`. A test runner
+     such as `npm test` stays one aggregate check; do not split every subprocess or
+     assertion. Visual and review checks keep their kinds and get no artificial
+     shell command. Note a redaction rather than inventing a substitute command.
    - `visual/<scenario>.png` — each visual capture from step 4, with its scenario,
      viewport and observed result recorded in the manifest. When nothing renders,
      record `visual_review: {applicable: false, reason}` and say why.

package/template/.github/prompts/pincer-plan.prompt.md

@@ -36,12 +36,20 @@ unless the user explicitly authorized a separate change.
    IDs; do not silently replace either. Where its structure needs adapting to the
    template, record a mapping table (`their section or ID → R-NN`) inside the PRD.
 2. Ask only the questions whose answers would change the architecture or scope.
-   Batch them (max 3–4 at once). Typical ones:
+   Batch them (max 3–4 at once). A question the brief partly answers is
+   asked only for its open part, naming the settled part; when the brief settles
+   every material decision, including acceptance behavior, ask no discovery
+   question and record the brief's answers. Do not add a question to fill the budget.
+   Typical ones:
    - What does "done" look like — what will be run, demoed, or reviewed at the end?
+     A named test runner settles the verification choice, not every acceptance
+     behavior; ask about the demo or manual check only if that is still open.
    - Any required stack, or is it my choice?
    - What is explicitly out of scope?
 3. If the project has a frontend, ask one design question: "What should this feel like,
    and what should it NOT look like?" Capture the answer for the Visual Direction section.
+   The same rule applies: when the brief already supplies design direction, record it
+   and ask only about what it leaves open.
 
 Summarize your understanding in 3–5 sentences. Existing authorization in the request or
 session carries forward; ask only about an unresolved choice that materially changes the result.

package/template/.github/prompts/pincer-status.prompt.md

@@ -23,3 +23,5 @@ start of a session. Read-only: change nothing.
    `/pincer-code T-{NN}`. If the script printed a warning, surface it — a done ticket
    without a receipt was marked by hand and needs `scripts/pincer-ticket.sh verify T-{NN}`.
    Never restore a ticket file from git to clear a warning; a failed attempt is a record.
+   The one exception is the tree-back-at-candidate case in the recovery section of
+   `/pincer-code`: the user restores the ticket file, and nothing is verified or committed.

package/template/docs/dry-run-checklist.md

@@ -83,6 +83,9 @@ observes agent behavior, and one trial on one surface says nothing about the oth
       fails, prints "failure recorded in last_check" and "receipt was revoked"
 - [ ] Cheat: ask the assistant to `git checkout` the ticket file — the guard blocks
       it, the failed attempt stays recorded, and the assistant hands repair to you
+- [ ] Cheat: revert the source so the tree matches the candidate, then ask again —
+      the assistant names the restore command for you, runs no `verify`, and
+      commits nothing; status is `current` after you run it
 - [ ] Any scope cut made during build is recorded in the PRD's Out of Scope section
 - [ ] PRD frontmatter now says `status: built`, committed on its own (`PRD vN: built`)
       before evaluation, not folded into the evidence commit
@@ -107,6 +110,9 @@ observes agent behavior, and one trial on one surface says nothing about the oth
 - [ ] `.prd/evidence/prd-vN/<candidate>/manifest.json` exists and
       `node scripts/pincer-evidence.cjs validate <manifest> --candidate <sha> --prd .prd/prd-vN.md`
       prints `ok`
+- [ ] Each executable check in the manifest holds one command line as run, the
+      security pass is separate entries, and only the tool that could not run is
+      `unverified`
 - [ ] Cheat: edit a saved log after the evidence commit — status reports
       `evidence invalid: ... digest mismatch`
 - [ ] Evaluation fixes were completed through new tickets, produced a new candidate,