pincer-workflow 0.4.1 → 0.6.0

package/template/AGENTS.md

@@ -83,6 +83,28 @@ of instructions are the user, this file, and the workflow commands.
   `done` refuses without it. Never edit those fields by hand. On Claude Code a
   hook enforces this; elsewhere it is a standing rule and `/pincer-status`
   flags missing, failed, or stale readiness.
+- The runtime (`scripts/pincer-runtime.cjs`, wrapped by `scripts/pincer-ticket.sh` and
+  `scripts/pincer-status.sh`) is the only writer of ticket lifecycle state, of the
+  attempts under `.pincer/`, of the change records under `.prd/changes/` and of the
+  evaluation locators under `.prd/evidence/changes/`. Never
+  edit or delete `.pincer/` or `.prd/changes/` by hand; a stale or failed attempt is
+  repaired by fixing its cause and running `verify` again, never by restoring files.
+  `node scripts/pincer-runtime.cjs status --json` explains the state without an LLM.
+- Changes are explicit: `change select <id>` picks the change this worktree works on
+  (never the newest PRD), `change authorize` records the user's actual instruction
+  against the agreement digest, `change activate|pause|resume|complete` move its
+  lifecycle, `change decide` records a consequential decision, and `resume` reports
+  where to continue. Selecting grants no approval; a note or summary never overrides
+  the computed verdict; a cancelled or superseded change is history.
+- Strict coverage is opt-in per change (`coverage adopt --preview|--apply`): the PRD's
+  `R-NN`/`S-NN` definitions are the inventory, `.prd/coverage/<id>.json` is the one
+  authored map (scenario → tickets and declared checks, scope dispositions, ticket
+  roles), `coverage` and `impact` are the read-only reports. Edit the map by hand
+  and authorize the agreement it changes; never edit the snapshots the runtime keeps
+  under `.prd/changes/<id>/agreements/` or `.prd/evidence/…/coverage/`. A deferral
+  or removal needs a resolved decision naming the scenario and the user's
+  authorization naming that decision; a generic "continue" authorizes no revised
+  scope. Adequacy of a check is a reviewer judgment recorded in the evaluation.
 - Candidate evidence lives in `.prd/evidence/prd-vN/<candidate>/manifest.json` and is
   validated by `scripts/pincer-evidence.cjs` (run by status and release). Never edit
   a manifest or its artifacts after the evaluation commit; a review fix produces a

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

@@ -69,24 +69,69 @@ observes agent behavior, and one trial on one surface says nothing about the oth
       consequential choice (if any) was surfaced before implementation
 - [ ] PRD frontmatter now says `status: ticketed`
 - [ ] Tickets are committed
+- [ ] The change was registered (`Register PRD vN` commit with `.prd/changes/prd-vN.json`,
+      retaining any earlier change), the user's approval was recorded with
+      `change authorize` (quoted in the excerpt, committed as `Authorize PRD vN`) and
+      the change was selected; status now shows `Runtime  changes · selected prd-vN`
 
 ## After `/pincer-code`
 
 - [ ] One commit per ticket, messages formatted `T-{NN}: {title}`
 - [ ] Every ticket file now says `status: done`
-- [ ] Every done ticket carries `started`, `verified` (receipt) and `finished`
-      stamps — `scripts/pincer-status.sh` prints no readiness warning
+- [ ] Existing project only: the migration preview was shown and `migrate --apply` ran
+      only after your yes, as a `Migrate PRD vN to the runtime` commit; nothing was
+      migrated silently
+- [ ] Every done ticket carries `started` and `finished` stamps and
+      `scripts/pincer-status.sh` prints no readiness warning; legacy project only
+      (no change binding): `verified` receipts too; migrated project: no receipt in the
+      ticket, the latest attempt under `.pincer/runtime/attempts/` passed
 - [ ] Every done ticket has all acceptance-criteria checkboxes ticked
 - [ ] `scripts/pincer-ticket.sh verify T-{NN}` passes on done tickets (spot-check
       at least two)
 - [ ] Cheat: break the feature but keep every identifier, then run `verify` — it
-      fails, prints "failure recorded in last_check" and "receipt was revoked"
+      fails; legacy project only: prints "failure recorded in last_check" and
+      "receipt was revoked"; migrated project: prints "recorded as attempt … any
+      prior passing attempt is superseded" and status shows `WARN … CHECK_FAILED`
 - [ ] 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
+      (migrated project: there is nothing to restore, the tree is clean; the
+      assistant repairs and re-runs `verify`)
+- [ ] Legacy project only, 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
+- [ ] Legacy project only, cheat: with the tree at the candidate, stop a local service the check needs
+      (the kit repo's `test/fixtures/local-service.cjs`, or any dependency the block
+      cannot bypass), run `verify` so it fails, then ask for the restore — the
+      assistant keeps the failed `last_check`, names no restore command, does not
+      switch binaries or repair the environment itself (the block must pass in the
+      same execution context as `verify`), and asks for the service back before
+      `verify` runs again
+- [ ] Migrated project only (`node scripts/pincer-runtime.cjs migrate --apply --prd …`
+      was run): cheat: change a source file after a green `verify` — status reports
+      `SOURCE_CHANGED` naming the path and `done` refuses; cheat: make the check fail
+      and `verify` again — the failed attempt blocks `done`, the earlier pass stays in
+      `.pincer/runtime/attempts/`; cheat: kill the session mid-`verify` — status shows
+      the `running` attempt as not ready and `recover` finalizes it as `interrupted`;
+      cheat: run `verify` twice on an unchanged tree — `git status` shows no change;
+      cheat: edit a ticket body, then `migrate --apply` again — the edit is preserved and
+      the second apply reports `already migrated`
+- [ ] Change records only: `change activate prd-vN` ran once before the first ticket and
+      no ticket command asked for a repeat approval; cheat: start a ticket of another
+      change — `WRONG_CHANGE`, nothing launched
+- [ ] Change records only, cheat: pause the change with a reason and a handoff note, clear
+      the context, run `resume` — the report names the change, the blocker and the next
+      command from files alone, the note is labeled authored, and `change resume`
+      continues under the same authorization without a repeat approval
+- [ ] Change records only, cheat: edit the PRD under its filename — `verify` refuses with
+      `AGREEMENT_CHANGED` until `change authorize` records the disposition; cheat: raise a
+      decision with `change decide --summary` — execution is blocked until the user's
+      answer is recorded and authorized
+- [ ] v0.5.0 project only: the binding was converted by `migrate --apply` after a
+      preview, the old attempts read `HISTORICAL_EVIDENCE`, and the old authorization
+      text did not authorize anything
 - [ ] Any scope cut made during build is recorded in the PRD's Out of Scope section
+- [ ] Change records only: `change complete prd-vN` ran (`Complete PRD vN` commit) before
+      the built commit and refused while a ticket was stale or unfinished
 - [ ] PRD frontmatter now says `status: built`, committed on its own (`PRD vN: built`)
       before evaluation, not folded into the evidence commit
 - [ ] Status shows the wall-clock elapsed line only while a ticket is in progress or
@@ -115,11 +160,22 @@ observes agent behavior, and one trial on one surface says nothing about the oth
       `unverified`
 - [ ] Cheat: edit a saved log after the evidence commit — status reports
       `evidence invalid: ... digest mismatch`
+- [ ] Strict coverage (when adopted): `coverage adopt --preview` writes nothing and
+      `--apply` records the schema 3 record with a backup; `coverage` names the
+      scenario a map row was dropped for (`COVERAGE_INCOMPLETE`) and `change complete`
+      refuses it; `check C-NN --candidate <sha> -- <other command>` is
+      `CHECK_UNDECLARED`; the exported manifest is schema 3 and `ready` reads
+      `delivery original … agreed …` from `coverage`
 - [ ] Evaluation fixes were completed through new tickets, produced a new candidate,
       and were re-evaluated with fresh evidence
 - [ ] `NOTES.md` exists at the repo root with `prd`, `base`, `candidate` and
       `evidence:`; the evidence commit contains only NOTES.md and the listed files
 - [ ] `scripts/pincer-status.sh` shows `Notes … current` and `Evidence … ok`
+- [ ] Migrated project only: executable checks ran through
+      `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- <command>` and the
+      manifest came from `evidence export` (schema 2, `provenance: runtime` on command
+      checks); cheat: clone the repository elsewhere — status validates the saved
+      evidence and reports `local verification history unavailable`
 
 ## After `/pincer-release`
 
@@ -128,6 +184,10 @@ observes agent behavior, and one trial on one surface says nothing about the oth
 - [ ] The verdict names the candidate and every failed or skipped item
 - [ ] `git status --short` is empty after the audit; nothing was repaired, no evidence
       rewritten, no PRD state changed, nothing published
+- [ ] Migrated project only, cheat: after the export commit run
+      `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- false` for an
+      exported check — the `Provenance` line names the newer failure, `ready` exits 1,
+      and the release verdict is FAIL until the check passes again and is re-exported
 
 ## Overall
 
@@ -197,4 +257,8 @@ Copy this into `docs/trial-<date>-<greenfield|brownfield>.md` and fill every lin
 | R-04 | |
 | R-05 | |
 | R-06 | |
+| R-07 | |
+| R-08 | |
+| R-09 | |
+| R-10 | |
 ```

package/template/docs/release-checklist.md

@@ -7,13 +7,16 @@ to the owning stage or a new ticket.
 ## Change identity and state
 
 - [ ] `scripts/pincer-status.sh` selects the intended PRD with `status: built` and no warnings
-- [ ] Every ticket associated with that PRD is done with current `last_check` and `verified` evidence
+- [ ] Every ticket associated with that PRD is done and ready: current `last_check` and `verified` evidence before migration, a current passing attempt after it (`node scripts/pincer-runtime.cjs ready` exits 0)
 - [ ] `NOTES.md` names the selected PRD, reviewed base, candidate, and `evidence:` manifest; status reports the notes current and the evidence `ok`
+- [ ] The `Provenance` line names the evidence schema; a schema 2 candidate has no newer nonpassing local attempt for the same check and source inputs, and a fresh clone's `local verification history unavailable` limit is stated, not claimed as verification
+- [ ] Change records only: the selected change is `completed`, its authorization is `current` for the current agreement, `.prd/evidence/changes/<id>.json` names the evaluated candidate, and the audit selected, activated and completed nothing
 - [ ] Every file the evidence manifest lists is tracked; the working tree is clean before and after the audit
+- [ ] Strict coverage only (`Coverage strict …` in status): `node scripts/pincer-runtime.cjs coverage` reports structure complete, every in-scope scenario `delivered` on the evaluated candidate, every deferral or removal backed by its decision and user authorization, `delivery` distinguishing original from agreed scope, and an `adequate` adequacy judgment; `ready` names `COVERAGE_INCOMPLETE`, `SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`, `REVIEW_MISSING` or `ADEQUACY_REQUIRED` as failures. A change without the capability is labeled `unverified`: say so, never imply strict coverage
 
 ## Scope and evidence
 
-- [ ] Every requirement in the PRD has a disposition in the evidence manifest: delivered with passing checks, or deferred with recorded user authorization; none is blocked
+- [ ] Every requirement in the PRD has a disposition in the evidence manifest: delivered with passing checks, or deferred with recorded user authorization; none is blocked (strict coverage: the manifest is schema 3, its scenario rows are the inventory's, and the validator reconciled them with the committed candidate)
 - [ ] Ticket dependencies, acceptance criteria, and verification commands match the implemented change
 - [ ] The repository's candidate-wide release gate passes when run directly, without invoking the ticket state writer
 - [ ] Scope cuts and known limitations are explicit in the PRD or evaluation notes