pincer-workflow 0.6.0 → 0.7.0

package/README.md

@@ -31,15 +31,80 @@ On Codex CLI the commands are skills, invoked by mention rather than slash:
 `$pincer-plan <brief>` → `$pincer-narrow` → `$pincer-code` → `$pincer-evaluate`
 → `$pincer-release`, and `$pincer-status`.
 
+## Your first change, end to end
+
+The five commands above are the shape of the work. This is the whole journey for one
+change on a project that wants strict requirement coverage — the path most of the
+runtime exists to support. Every step is a real command; none of them is optional
+ceremony, and the two read-only reports (`coverage scaffold`, `resume --brief`) write
+nothing.
+
+```bash
+# 1. Install, then plan and break down the work.
+npx pincer-workflow init
+#    /pincer-plan <brief>      → .prd/prd-v1.md with R-NN requirements and S-NN scenarios
+#    /pincer-narrow            → tickets/T-*.md, one per unit of work
+
+# 2. Register the change and select it in this worktree.
+node scripts/pincer-runtime.cjs register --prd .prd/prd-v1.md
+node scripts/pincer-runtime.cjs change select prd-v1
+
+# 3. Choose your coverage. Default is fine: tickets, checks and evidence work without
+#    this step. Strict coverage additionally binds every S-NN to a ticket and a check.
+#    Start the map from the draft — it lists every scenario and ticket for you:
+node scripts/pincer-runtime.cjs coverage scaffold --change prd-v1
+
+# 4. Author .prd/coverage/prd-v1.json yourself from that draft, then review the links.
+#    The draft never invents a link, a check command or a scope disposition, and it is
+#    not a map: `coverage adopt` refuses it. Working through its Unresolved list is the
+#    authoring step.
+
+# 5. Adopt strict coverage explicitly, then record the user's actual approval.
+node scripts/pincer-runtime.cjs coverage adopt --preview --change prd-v1
+node scripts/pincer-runtime.cjs coverage adopt --apply   --change prd-v1
+node scripts/pincer-runtime.cjs change authorize prd-v1 --agreement <digest> \
+  --reference "<where the user said it>" --excerpt "<the user's approval, quoted>"
+node scripts/pincer-runtime.cjs change activate prd-v1
+
+# 6. Implement. One commit per ticket; `done` refuses without a current passing check.
+#    /pincer-code
+
+# 7. Come back tomorrow, or in a fresh session with no memory of any of this:
+node scripts/pincer-runtime.cjs resume --brief
+#    → one screen: the change, the authorization verdict, the coverage label, the
+#      blocker categories with counts, and the exact next command. `resume` (no
+#      --brief) prints every row; the brief names the command that shows them.
+
+# 8. Evaluate and audit.
+#    /pincer-evaluate          → validated evidence under .prd/evidence/
+#    /pincer-release           → read-only pass/fail audit
+```
+
+Adoption grants no approval, and approval is never inferred: `coverage adopt` records
+the agreement, `change authorize` records what the user actually said about it, and a
+generic "continue" authorizes no revised scope. Edit the PRD, the tickets or the map
+afterwards and the agreement changes — the runtime reports `AGREEMENT_CHANGED` and
+waits for a fresh decision rather than carrying the old approval forward.
+
+### Pinning a management kit
+
+The kit under `scripts/` is code that the workflow also runs *on* the project. When you
+are changing that code, manage the work with a pinned released copy from outside the
+tree rather than with the version you are editing — extract the scripts from a release
+tag into a directory outside the repository, record its digest, and run the lifecycle
+commands from there. A project that only uses PINCER never needs this; a project that
+develops it does.
+
 ### Claude Code
 
-Works immediately: the commands, the two subagents, the `.env` deny rules and
+Installs complete: the commands, the two subagents, the `.env` deny rules and
 the destructive-command and ticket-guard hooks install to `.claude/`. Start
-`claude` in the repo and run `/pincer-plan <brief>`.
+`claude` in the repo and run `/pincer-plan <brief>`. See
+[platform support](#platform-support) for what that install has been observed to do.
 
 ### Codex CLI
 
-Works immediately as well: `AGENTS.md` loads natively, and the six commands
+Installs complete as well: `AGENTS.md` loads natively, and the six commands
 install as skills under `.agents/skills/`, which Codex discovers from the repo
 (no copying into your home directory — Codex removed custom prompts and
 `~/.codex/prompts/` in early 2026). Start `codex` in the repo, then type
@@ -61,6 +126,28 @@ Full notes in `.codex/README.md`.
 Enable `"chat.promptFiles": true` in VS Code settings, then run `/pincer-plan`
 in chat. `.github/copilot-instructions.md` is wired to `AGENTS.md`.
 
+## Platform support
+
+Two different claims, kept apart on purpose. **Installation-tested** means the packed
+artifact installs and its files land where they should, proven by the suites in this
+repository on every push. **Live-observed** means a real agent session carried a real
+change through the workflow on that surface and the artifacts were reviewed. An
+installation check is not a platform trial, and packaged parity is not live success.
+
+| Surface | Installation-tested | Live-observed |
+| --- | --- | --- |
+| Claude Code (`npx pincer-workflow init`) | yes — packed install, layout and generated parity | not for this release |
+| Codex CLI (`.agents/skills/`) | yes — packed install and skill layout | not for this release |
+| GitHub Copilot (VS Code prompts) | yes — packed install and prompt layout | no |
+| Claude Code plugin (marketplace) | yes — plugin build parity | no |
+| Windows (native, no POSIX shell) | no | no |
+
+No live platform trial has been observed for the current release. The work that would
+produce one — a full strict journey on Claude Code and on Codex, plus a real cross-agent
+handoff resumed from files — is open, and until it reports, every "live-observed" cell
+above stays as it reads. Earlier releases have their own recorded trials under `docs/`;
+those describe the versions they were run against, not this one.
+
 ## Claude Code plugin (alternative)
 
 Claude users can install PINCER as a plugin instead — commands arrive
@@ -80,17 +167,6 @@ and Copilot). Installing both gives you duplicate commands. Plugin users who
 want the repo-side rules too can copy `AGENTS.md` from the
 [template](template/AGENTS.md).
 
-## Update
-
-```bash
-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. 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. v0.5.0 adds the runtime: `scripts/pincer-runtime.cjs` with its modules under `scripts/pincer-runtime/` now implements the ticket lifecycle, status, migration and evidence export, and `pincer-ticket.sh` / `pincer-status.sh` delegate to it, so every command needs Node.js 18+; unmigrated projects keep their receipts and behavior. Run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md` to see what migration would change; after `--apply`, `verify` records attempts with captured logs under the ignored `.pincer/runtime/` and writes no receipt into the ticket, `done` consumes the current passing attempt against the current source, and `/pincer-evaluate` exports evidence schema 2 from runtime attempts. `docs/runtime-contracts.md` is the contract; `pincer doctor` tells you when a migration is available and never migrates on its own. The next version keeps several changes side by side: `register` writes a change record (schema 2) that retains every earlier change, the worktree selects the change it works on (`change select`), the user's approval is recorded against the reviewed agreement (`change authorize`), the lifecycle is explicit (`change activate|pause|resume|complete|reopen|cancel|supersede`), and `resume` prints where to continue from files alone. A v0.5.0 binding converts with the same `migrate --preview` / `--apply`; the converted change is planned with no authorization, its old attempts and evaluation are history until verified again, and the old free-text authorization never authorizes execution. Selection and local attempts are per worktree; records are tracked and shared through git; completed means ready for evaluation, not released. The next version also raises the floor to Node.js 22+, because 18 and 20 are past end of life. It separately fixes a defect that was never version-specific: a command whose output exceeded one pipe buffer (65,536 bytes) lost the tail when the process exited and still exited 0, on every version including 22 and 24. Every write is now synchronous, so piped `--json` is complete. Updating the kit inside a migrated project changes tracked runtime files, so every done ticket's attempt reads `SOURCE_CHANGED` until it is verified again; update between changes, not mid-ticket. An update from 0.4.x leaves the retired `scripts/pincer-ticket-lib.sh` on disk; `pincer doctor` names it and it is safe to delete.) 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).
-
 ## What you get
 
 | Piece | Purpose |
@@ -110,6 +186,17 @@ alone — the new version lands next to them as `<file>.new` for a manual merge.
 | `docs/release-checklist.md` | General, read-only candidate audit used by `/pincer-release` |
 | `docs/dry-run-checklist.md` | Separate manual platform trial for the Pincer kit |
 
+## Update
+
+```bash
+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. 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. v0.5.0 adds the runtime: `scripts/pincer-runtime.cjs` with its modules under `scripts/pincer-runtime/` now implements the ticket lifecycle, status, migration and evidence export, and `pincer-ticket.sh` / `pincer-status.sh` delegate to it, so every command needs Node.js 18+; unmigrated projects keep their receipts and behavior. Run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md` to see what migration would change; after `--apply`, `verify` records attempts with captured logs under the ignored `.pincer/runtime/` and writes no receipt into the ticket, `done` consumes the current passing attempt against the current source, and `/pincer-evaluate` exports evidence schema 2 from runtime attempts. `docs/runtime-contracts.md` is the contract; `pincer doctor` tells you when a migration is available and never migrates on its own. v0.6.0 keeps several changes side by side: `register` writes a change record (schema 2) that retains every earlier change, the worktree selects the change it works on (`change select`), the user's approval is recorded against the reviewed agreement (`change authorize`), the lifecycle is explicit (`change activate|pause|resume|complete|reopen|cancel|supersede`), and `resume` prints where to continue from files alone. A v0.5.0 binding converts with the same `migrate --preview` / `--apply`; the converted change is planned with no authorization, its old attempts and evaluation are history until verified again, and the old free-text authorization never authorizes execution. Selection and local attempts are per worktree; records are tracked and shared through git; completed means ready for evaluation, not released. v0.6.0 also raises the floor to Node.js 22+, because 18 and 20 are past end of life. It separately fixes a defect that was never version-specific: a command whose output exceeded one pipe buffer (65,536 bytes) lost the tail when the process exited and still exited 0, on every version including 22 and 24. Every write is now synchronous, so piped `--json` is complete. Updating the kit inside a migrated project changes tracked runtime files, so every done ticket's attempt reads `SOURCE_CHANGED` until it is verified again; update between changes, not mid-ticket. An update from 0.4.x leaves the retired `scripts/pincer-ticket-lib.sh` on disk; `pincer doctor` names it and it is safe to delete.) 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).
+
 ## Design principles
 
 - **Approval gates scale with decision cost** — a human owns architecture, scope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "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"
@@ -14,7 +14,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "test": "node test/smoke.test.js && node test/installer.test.js && node test/ticket.test.js && node test/validation.test.js && node test/verification.test.js && node test/behavioral-verification.test.js && node test/evidence.test.js && node test/candidate.test.js && node test/recovery.test.js && node test/hooks.test.js && node test/runtime-parse.test.js && node test/coverage-inventory.test.js && node test/coverage-map.test.js && node test/coverage-agreement.test.js && node test/coverage-adoption.test.js && node test/coverage-readiness.test.js && node test/coverage-impact.test.js && node test/coverage-checks.test.js && node test/coverage-evidence.test.js && node test/coverage-reports.test.js && node test/runtime-identity.test.js && node test/change-registry.test.js && node test/change-selection.test.js && node test/change-agreement.test.js && node test/change-authorization.test.js && node test/change-lifecycle.test.js && node test/change-command-gates.test.js && node test/change-evidence-context.test.js && node test/change-evaluations.test.js && node test/change-resume.test.js && node test/change-trial-record.test.js && node test/change-review-packet.test.js && node test/runtime-state.test.js && node test/change-transactions.test.js && node test/runtime-status.test.js && node test/runtime-output.test.js && node test/runtime-runner.test.js && node test/runtime-lifecycle.test.js && node test/runtime-migrate.test.js && node test/change-migration.test.js && node test/runtime-evidence.test.js && node test/workflow.test.js && node test/contracts.test.js && node test/change-contracts.test.js && node test/coverage-contracts.test.js && node test/distribution.test.js && node test/change-distribution.test.js && node test/coverage-distribution.test.js && node test/delivery-benchmark.test.js && node test/coverage-trial-record.test.js && node test/coverage-review-packet.test.js"
+    "test": "node test/smoke.test.js && node test/installer.test.js && node test/strict-onboarding.test.js && node test/ticket.test.js && node test/validation.test.js && node test/verification.test.js && node test/behavioral-verification.test.js && node test/evidence.test.js && node test/candidate.test.js && node test/recovery.test.js && node test/hooks.test.js && node test/runtime-parse.test.js && node test/coverage-inventory.test.js && node test/coverage-map.test.js && node test/coverage-scaffold.test.js && node test/coverage-agreement.test.js && node test/coverage-adoption.test.js && node test/coverage-readiness.test.js && node test/coverage-impact.test.js && node test/coverage-checks.test.js && node test/coverage-evidence.test.js && node test/coverage-reports.test.js && node test/runtime-identity.test.js && node test/change-registry.test.js && node test/change-selection.test.js && node test/change-agreement.test.js && node test/change-authorization.test.js && node test/change-lifecycle.test.js && node test/change-command-gates.test.js && node test/change-evidence-context.test.js && node test/change-evaluations.test.js && node test/change-resume.test.js && node test/resume-brief.test.js && node test/change-trial-record.test.js && node test/change-review-packet.test.js && node test/runtime-state.test.js && node test/change-transactions.test.js && node test/runtime-status.test.js && node test/runtime-output.test.js && node test/runtime-runner.test.js && node test/runtime-lifecycle.test.js && node test/runtime-migrate.test.js && node test/change-migration.test.js && node test/runtime-evidence.test.js && node test/workflow.test.js && node test/improvement-contracts.test.js && node test/contracts.test.js && node test/change-contracts.test.js && node test/coverage-contracts.test.js && node test/distribution.test.js && node test/change-distribution.test.js && node test/coverage-distribution.test.js && node test/effort-records.test.js && node test/execution-freeze.test.js && node test/delivery-benchmark.test.js && node test/delivery-benchmark-v7.test.js && node test/benchmark-orchestrator.test.js && node test/strict-pilot-records.test.js && node test/platform-trial-records.test.js && node test/improvement-trial-records.test.js && node test/coverage-trial-record.test.js && node test/coverage-review-packet.test.js && node test/improvement-review-packet.test.js && node test/readiness-contracts.test.js && node test/benchmark-effective-inputs.test.js && node test/release-preparation.test.js && node test/benchmark-run-claims.test.js && node test/benchmark-environment.test.js && node test/benchmark-browser.test.js && node test/benchmark-restart.test.js && node test/benchmark-usage-completeness.test.js && node test/benchmark-terminal-records.test.js && node test/study-readiness.test.js && node test/benchmark-allocation.test.js && node test/benchmark-prepared-bases.test.js && node test/benchmark-study-launch.test.js"
   },
   "keywords": [
     "claude-code",

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

@@ -40,7 +40,10 @@ previously authorized work. Read the `Runtime` line before the first ticket. `ch
 `.prd/changes/`) → run `node scripts/pincer-runtime.cjs resume` and follow its `Next`
 line: it names the selected change, its lifecycle state, the agreement and the
 authorization verdict, the blockers in order and the exact next command, all from the
-files on disk. Select the change to work on (`node scripts/pincer-runtime.cjs change
+files on disk. `resume --brief` is the same report projected to counts and one next
+action — the same verdict and the same `Next` line, with every blocker category kept
+and its `Detail` line naming the command that prints the rows it grouped. Prefer it
+when you are orienting, and read the full report when a blocker needs its detail. Select the change to work on (`node scripts/pincer-runtime.cjs change
 select <id>`; selection is local metadata and touches no source), activate it
 (`change activate <id>`; refused until the user's authorization is recorded with
 `change authorize` and no consequential decision is open) and resume a paused change

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

@@ -39,7 +39,17 @@ discovered consequential choice is surfaced before implementation.
      in the ticket Objective. Resolve missing coverage and conflicting criteria with
      the user before implementation; do not start with an unmapped required scenario. On a change with change records, author the map once as
      `.prd/coverage/<change id>.json` (coverage map schema 1, "Coverage map" in
-     `docs/runtime-contracts.md`): one `scenarios` row per `S-NN` naming its
+     `docs/runtime-contracts.md`). Start from
+     `node scripts/pincer-runtime.cjs coverage scaffold --change <change id>`: it prints
+     a read-only draft listing every live scenario exactly once with its requirement,
+     every ticket with its objective, its own `Implements:` claim and its Verification
+     text, and an `Unresolved` list of what is still unauthored. It writes nothing,
+     adopts nothing and decides nothing — it removes the transcription, not the
+     judgment, so a ticket's claim is material to check rather than a link, and no check
+     command, ticket role or scope disposition is ever invented. The draft is not a map:
+     it carries no `schema` key and `coverage adopt` refuses it. You author the real map
+     yourself, working through the draft's unresolved entries:
+     one `scenarios` row per `S-NN` naming its
      implementing tickets and declared checks, every ticket of the change in
      `tickets` as `implements` or `enables` (with a rationale), each check declared
      once in `checks` with its kind, `required` flag and, for a command, the exact

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

@@ -12,7 +12,19 @@ start of a session. Read-only: change nothing.
 
 ## Steps
 
-1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
+1. On a project with change records, start with
+   `node scripts/pincer-runtime.cjs resume --brief`. It is one read that answers the
+   question this command exists for: the selected change and its lifecycle, the
+   authorization verdict, the coverage label, ticket and attempt counts, every blocking
+   reason category with its count, and the exact next command — the full report's own,
+   copied, never recomputed. Reading the full `resume`, `status` and `coverage` reports
+   in sequence to find one next action costs several kilobytes to answer in a line, and
+   on a large change the full report grows with the work while the answer does not.
+   Read further only when the brief gives you a reason to: it ends with the `Detail`
+   line naming the command that prints every row it grouped.
+2. When you need the detail — a blocker you must act on, a ticket list, an attempt
+   history — run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`,
+   `tickets/`,
    `NOTES.md`) and prints the PRD state and profile, every ticket with its state and
    clock-based elapsed time, what is blocked, wall-clock build time while a ticket is in
    progress or against an explicit user budget, the `Runtime` line (legacy receipts or
@@ -20,8 +32,8 @@ start of a session. Read-only: change nothing.
    candidate, any warnings (each readiness problem once), and the next command to run.
    `scripts/pincer-status.sh --json` prints one status object with reason codes and the
    next action for tooling; `node scripts/pincer-runtime.cjs ready [T-NN]` is the
-   read-only gate. On a project with change records (`Runtime  changes …`) run
-   `node scripts/pincer-runtime.cjs resume` as well: it reports the selected change, its
+   read-only gate. On a project with change records (`Runtime  changes …`)
+   `node scripts/pincer-runtime.cjs resume` is the full report: it reports the selected change, its
    lifecycle, agreement and authorization, decisions, references, tickets, attempts,
    candidate, the authored handoff note and the next command, and never writes;
    `change list` shows every retained change, `status --change <id>` and
@@ -30,12 +42,14 @@ start of a session. Read-only: change nothing.
    `strict` or `unverified`; on a strict change `node scripts/pincer-runtime.cjs coverage`
    (and `impact` after an edit) name the exact scenario, ticket, check or decision
    that is next — quote them rather than inferring coverage from the ticket list.
-2. Report in three lines: where the workflow is, what is in progress or blocked, and the
+   On a legacy project there is no change record to summarize, so `pincer-status.sh`
+   is the first read.
+3. Report in three lines: where the workflow is, what is in progress or blocked, and the
    next command. Quote the `Next` line as-is. When the `Runtime` line says `legacy`,
    add the register or migrate command it names as the step that precedes the next
    ticket (fresh project → `register`, legacy receipts → `migrate --preview`, a v0.5.0
    binding → `migrate --preview`, no selection → `change select <id>`).
-3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
+4. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
    `$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.

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

@@ -38,7 +38,10 @@ previously authorized work. Read the `Runtime` line before the first ticket. `ch
 `.prd/changes/`) → run `node scripts/pincer-runtime.cjs resume` and follow its `Next`
 line: it names the selected change, its lifecycle state, the agreement and the
 authorization verdict, the blockers in order and the exact next command, all from the
-files on disk. Select the change to work on (`node scripts/pincer-runtime.cjs change
+files on disk. `resume --brief` is the same report projected to counts and one next
+action — the same verdict and the same `Next` line, with every blocker category kept
+and its `Detail` line naming the command that prints the rows it grouped. Prefer it
+when you are orienting, and read the full report when a blocker needs its detail. Select the change to work on (`node scripts/pincer-runtime.cjs change
 select <id>`; selection is local metadata and touches no source), activate it
 (`change activate <id>`; refused until the user's authorization is recorded with
 `change authorize` and no consequential decision is open) and resume a paused change

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

@@ -37,7 +37,17 @@ discovered consequential choice is surfaced before implementation.
      in the ticket Objective. Resolve missing coverage and conflicting criteria with
      the user before implementation; do not start with an unmapped required scenario. On a change with change records, author the map once as
      `.prd/coverage/<change id>.json` (coverage map schema 1, "Coverage map" in
-     `docs/runtime-contracts.md`): one `scenarios` row per `S-NN` naming its
+     `docs/runtime-contracts.md`). Start from
+     `node scripts/pincer-runtime.cjs coverage scaffold --change <change id>`: it prints
+     a read-only draft listing every live scenario exactly once with its requirement,
+     every ticket with its objective, its own `Implements:` claim and its Verification
+     text, and an `Unresolved` list of what is still unauthored. It writes nothing,
+     adopts nothing and decides nothing — it removes the transcription, not the
+     judgment, so a ticket's claim is material to check rather than a link, and no check
+     command, ticket role or scope disposition is ever invented. The draft is not a map:
+     it carries no `schema` key and `coverage adopt` refuses it. You author the real map
+     yourself, working through the draft's unresolved entries:
+     one `scenarios` row per `S-NN` naming its
      implementing tickets and declared checks, every ticket of the change in
      `tickets` as `implements` or `enables` (with a rationale), each check declared
      once in `checks` with its kind, `required` flag and, for a command, the exact

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

@@ -10,7 +10,19 @@ start of a session. Read-only: change nothing.
 
 ## Steps
 
-1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
+1. On a project with change records, start with
+   `node scripts/pincer-runtime.cjs resume --brief`. It is one read that answers the
+   question this command exists for: the selected change and its lifecycle, the
+   authorization verdict, the coverage label, ticket and attempt counts, every blocking
+   reason category with its count, and the exact next command — the full report's own,
+   copied, never recomputed. Reading the full `resume`, `status` and `coverage` reports
+   in sequence to find one next action costs several kilobytes to answer in a line, and
+   on a large change the full report grows with the work while the answer does not.
+   Read further only when the brief gives you a reason to: it ends with the `Detail`
+   line naming the command that prints every row it grouped.
+2. When you need the detail — a blocker you must act on, a ticket list, an attempt
+   history — run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`,
+   `tickets/`,
    `NOTES.md`) and prints the PRD state and profile, every ticket with its state and
    clock-based elapsed time, what is blocked, wall-clock build time while a ticket is in
    progress or against an explicit user budget, the `Runtime` line (legacy receipts or
@@ -18,8 +30,8 @@ start of a session. Read-only: change nothing.
    candidate, any warnings (each readiness problem once), and the next command to run.
    `scripts/pincer-status.sh --json` prints one status object with reason codes and the
    next action for tooling; `node scripts/pincer-runtime.cjs ready [T-NN]` is the
-   read-only gate. On a project with change records (`Runtime  changes …`) run
-   `node scripts/pincer-runtime.cjs resume` as well: it reports the selected change, its
+   read-only gate. On a project with change records (`Runtime  changes …`)
+   `node scripts/pincer-runtime.cjs resume` is the full report: it reports the selected change, its
    lifecycle, agreement and authorization, decisions, references, tickets, attempts,
    candidate, the authored handoff note and the next command, and never writes;
    `change list` shows every retained change, `status --change <id>` and
@@ -28,12 +40,14 @@ start of a session. Read-only: change nothing.
    `strict` or `unverified`; on a strict change `node scripts/pincer-runtime.cjs coverage`
    (and `impact` after an edit) name the exact scenario, ticket, check or decision
    that is next — quote them rather than inferring coverage from the ticket list.
-2. Report in three lines: where the workflow is, what is in progress or blocked, and the
+   On a legacy project there is no change record to summarize, so `pincer-status.sh`
+   is the first read.
+3. Report in three lines: where the workflow is, what is in progress or blocked, and the
    next command. Quote the `Next` line as-is. When the `Runtime` line says `legacy`,
    add the register or migrate command it names as the step that precedes the next
    ticket (fresh project → `register`, legacy receipts → `migrate --preview`, a v0.5.0
    binding → `migrate --preview`, no selection → `change select <id>`).
-3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
+4. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
    `/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.

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

@@ -40,7 +40,10 @@ previously authorized work. Read the `Runtime` line before the first ticket. `ch
 `.prd/changes/`) → run `node scripts/pincer-runtime.cjs resume` and follow its `Next`
 line: it names the selected change, its lifecycle state, the agreement and the
 authorization verdict, the blockers in order and the exact next command, all from the
-files on disk. Select the change to work on (`node scripts/pincer-runtime.cjs change
+files on disk. `resume --brief` is the same report projected to counts and one next
+action — the same verdict and the same `Next` line, with every blocker category kept
+and its `Detail` line naming the command that prints the rows it grouped. Prefer it
+when you are orienting, and read the full report when a blocker needs its detail. Select the change to work on (`node scripts/pincer-runtime.cjs change
 select <id>`; selection is local metadata and touches no source), activate it
 (`change activate <id>`; refused until the user's authorization is recorded with
 `change authorize` and no consequential decision is open) and resume a paused change

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

@@ -39,7 +39,17 @@ discovered consequential choice is surfaced before implementation.
      in the ticket Objective. Resolve missing coverage and conflicting criteria with
      the user before implementation; do not start with an unmapped required scenario. On a change with change records, author the map once as
      `.prd/coverage/<change id>.json` (coverage map schema 1, "Coverage map" in
-     `docs/runtime-contracts.md`): one `scenarios` row per `S-NN` naming its
+     `docs/runtime-contracts.md`). Start from
+     `node scripts/pincer-runtime.cjs coverage scaffold --change <change id>`: it prints
+     a read-only draft listing every live scenario exactly once with its requirement,
+     every ticket with its objective, its own `Implements:` claim and its Verification
+     text, and an `Unresolved` list of what is still unauthored. It writes nothing,
+     adopts nothing and decides nothing — it removes the transcription, not the
+     judgment, so a ticket's claim is material to check rather than a link, and no check
+     command, ticket role or scope disposition is ever invented. The draft is not a map:
+     it carries no `schema` key and `coverage adopt` refuses it. You author the real map
+     yourself, working through the draft's unresolved entries:
+     one `scenarios` row per `S-NN` naming its
      implementing tickets and declared checks, every ticket of the change in
      `tickets` as `implements` or `enables` (with a rationale), each check declared
      once in `checks` with its kind, `required` flag and, for a command, the exact

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

@@ -12,7 +12,19 @@ start of a session. Read-only: change nothing.
 
 ## Steps
 
-1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
+1. On a project with change records, start with
+   `node scripts/pincer-runtime.cjs resume --brief`. It is one read that answers the
+   question this command exists for: the selected change and its lifecycle, the
+   authorization verdict, the coverage label, ticket and attempt counts, every blocking
+   reason category with its count, and the exact next command — the full report's own,
+   copied, never recomputed. Reading the full `resume`, `status` and `coverage` reports
+   in sequence to find one next action costs several kilobytes to answer in a line, and
+   on a large change the full report grows with the work while the answer does not.
+   Read further only when the brief gives you a reason to: it ends with the `Detail`
+   line naming the command that prints every row it grouped.
+2. When you need the detail — a blocker you must act on, a ticket list, an attempt
+   history — run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`,
+   `tickets/`,
    `NOTES.md`) and prints the PRD state and profile, every ticket with its state and
    clock-based elapsed time, what is blocked, wall-clock build time while a ticket is in
    progress or against an explicit user budget, the `Runtime` line (legacy receipts or
@@ -20,8 +32,8 @@ start of a session. Read-only: change nothing.
    candidate, any warnings (each readiness problem once), and the next command to run.
    `scripts/pincer-status.sh --json` prints one status object with reason codes and the
    next action for tooling; `node scripts/pincer-runtime.cjs ready [T-NN]` is the
-   read-only gate. On a project with change records (`Runtime  changes …`) run
-   `node scripts/pincer-runtime.cjs resume` as well: it reports the selected change, its
+   read-only gate. On a project with change records (`Runtime  changes …`)
+   `node scripts/pincer-runtime.cjs resume` is the full report: it reports the selected change, its
    lifecycle, agreement and authorization, decisions, references, tickets, attempts,
    candidate, the authored handoff note and the next command, and never writes;
    `change list` shows every retained change, `status --change <id>` and
@@ -30,12 +42,14 @@ start of a session. Read-only: change nothing.
    `strict` or `unverified`; on a strict change `node scripts/pincer-runtime.cjs coverage`
    (and `impact` after an edit) name the exact scenario, ticket, check or decision
    that is next — quote them rather than inferring coverage from the ticket list.
-2. Report in three lines: where the workflow is, what is in progress or blocked, and the
+   On a legacy project there is no change record to summarize, so `pincer-status.sh`
+   is the first read.
+3. Report in three lines: where the workflow is, what is in progress or blocked, and the
    next command. Quote the `Next` line as-is. When the `Runtime` line says `legacy`,
    add the register or migrate command it names as the step that precedes the next
    ticket (fresh project → `register`, legacy receipts → `migrate --preview`, a v0.5.0
    binding → `migrate --preview`, no selection → `change select <id>`).
-3. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
+4. If a ticket is `in_progress`, read it and `git status`, then offer to resume it with
    `/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.

package/template/docs/runtime-contracts.md

@@ -893,8 +893,8 @@ it selects nothing, completes nothing, runs nothing and writes nothing.
 
 ## Resume report
 
-`resume [--change <id>] [--json]` is read-only inspection of the selected (or named)
-change for a fresh session; it is distinct from `change resume`, the lifecycle
+`resume [--change <id>] [--brief] [--json]` is read-only inspection of the selected
+(or named) change for a fresh session; it is distinct from `change resume`, the lifecycle
 operation. It launches no check, records no approval, changes no selection and writes
 no file; repeated runs are byte-identical apart from `generated`. Resume JSON schema 1:
 
@@ -938,6 +938,40 @@ command to run):
 7. `completed` without a current evaluation → `/pincer-evaluate`;
 8. evaluated and current → `/pincer-release` (read-only audit).
 
+### Brief resume
+
+`resume --brief [--change <id>] [--json]` is a **projection of the report `resume`
+already computes**, for a fresh session that needs the next action without paying for
+every row to find it. It is not a second policy engine: `next` is the full report's
+own object, copied, and no verdict, readiness value or precedence rule is recomputed.
+It composes with `--change` and `--json`, keeps the full report's exit code, and
+writes nothing.
+
+Brief JSON envelope — `brief: 1` with `of` naming the schema it projects, so nothing
+reading resume JSON ever sees a new shape:
+
+```
+{ brief: 1, kind: "resume-brief", of: 2, generated, root, mode,
+  selection: { change | null, problem | null },
+  change: { id, prd, base, lifecycle } | null,
+  agreement: { current, verdict, authorized: { id, disposition } | null } | null,
+  coverage: { label, strict, structure, implementation } | null,
+  tickets: { total, by_status: { open, in_progress, done }, not_ready },
+  attempts: { total, running, current_failed },
+  candidate: { notes, candidate, evidence } | null,
+  blockers: { total, categories: [ { code, count } ] },
+  next: <the full report's next, verbatim>,
+  detail: { command, prd, tickets: [ paths ], omitted } }
+```
+
+Grouping may collapse **repetition**; it may never collapse a **category**. Every
+distinct blocker code of the full report appears in `blockers.categories` with its
+exact count, and `blockers.total`, `tickets.total` and `attempts.total` equal the full
+report's own lengths. `detail.omitted` states how many rows the brief did not print
+and `detail.command` is the exact command that prints them, so nothing is hidden —
+only deferred. The default `resume` human output and resume JSON schema 2 are
+unchanged.
+
 ## Migration and rollback
 
 `migrate --preview --prd .prd/prd-vN.md` prints the plan and writes nothing. It exits 0
@@ -1556,6 +1590,7 @@ are unchanged.
 | --- | --- | --- | --- |
 | `coverage` | `[--change <id>] [--json]` | nothing | the phase-specific coverage report of the selected (or named) change; exit 0 when the report was computed (complete or not), 4 when the inputs cannot be read |
 | `impact` | `[--change <id>] [--from G-NN \| A-NN] [--json]` | nothing | structural differences between the current authored inputs and a retained agreement; exit 0 when computed (`unchanged`, `changed` or `unavailable`), 4 on invalid input |
+| `coverage scaffold` | `--change <id> [--json]` | nothing | the read-only coverage draft ("Coverage draft"); exit 0 when a draft was produced, 4 when the inputs cannot be read |
 | `coverage adopt` | `--preview \| --apply --change <id> [--agreement <digest>]` | apply: the backup, the schema 3 record, the adoption snapshot | preview writes nothing; exit 0 / 1 (conflict) / 4 (invalid state) |
 | `check` | `C-NN --candidate <sha>` (strict) | an attempt | the declared command; `--timeout` and `-- <command>` are `CHECK_UNDECLARED` in a strict change |
 
@@ -1563,6 +1598,57 @@ are unchanged.
 write no file; repeated runs are byte-identical apart from `generated`. Their human
 output and their JSON name the same IDs, codes and next action.
 
+### Coverage draft
+
+`coverage scaffold --change <id> [--json]` projects the validated inventory, the
+change's tickets and any authored map into one reviewable **draft**. It exists to
+remove transcription, not judgment: authoring `.prd/coverage/<id>.json` means copying
+every live scenario, every ticket role and every check declaration out of documents
+the runtime has already parsed, and that copying is all this removes.
+
+The draft **decides nothing**. It never invents a link, a check command, a ticket role
+or a scope disposition; an entry it cannot resolve from authored content stays
+`unresolved`. A ticket's own `Implements:`/`Scenarios:` claim and its Verification
+text are reported under `candidates` with the ticket's file, as material to read —
+never promoted into `scenarios` or `checks`. IDs on those lines that the inventory
+does not define are not reported at all, because a ticket naming other tickets is not
+a scenario claim.
+
+Draft envelope — `draft: 1`, and deliberately **no `schema` key**, so `readMap`
+refuses it with `COVERAGE_INVALID: unsupported coverage map schema undefined`:
+
+```
+{ draft: 1, kind: "coverage-draft", change, prd,
+  inventory: { digest, requirements, scenarios },
+  authored: { map: <path> | null, digest | null },
+  scenarios: { "S-NN": { requirement, state, tickets: [], checks: [] } },
+  scope:     { "S-NN": { disposition, decision, prior, note, state } },
+  tickets:   { "T-NN": { role, rationale, state } },
+  checks:    { "C-NN": { kind, required, command, timeout, cwd, obligation, note, state } },
+  candidates: { tickets: { "T-NN": { file, objective, implements: [], scenarios: [], verification } } },
+  unresolved: [ { code, id, detail } ],
+  next: { action, command } }
+```
+
+`state` is `authored` for content read from the existing map and `unresolved`
+otherwise. Every live inventory scenario appears exactly once across `scenarios` and
+`scope`. Authored rows the inventory no longer defines are **preserved and flagged**
+(`SCENARIO_STALE`), never dropped: removing an obligation is a decision with its own
+disposition and authorization. Unresolved codes are `SCENARIO_UNLINKED`,
+`CHECK_UNDECLARED`, `TICKET_UNCLASSIFIED`, `SCENARIO_STALE` and `TICKET_FOREIGN`.
+
+The draft body carries no timestamp, so two calls on identical authored inputs are
+byte-identical. Scaffolding writes no file, launches no check, changes no selection,
+adopts nothing and records no approval; a malformed, unsupported, symlinked or
+out-of-root map is refused with exit 4 before any draft is printed, because silently
+dropping authored content is the one failure this command must not have.
+
+A draft is **not a coverage map and confers no readiness**. The route is unchanged:
+author `.prd/coverage/<id>.json` by hand, review the links, `coverage` validates it,
+`coverage adopt --preview|--apply` adopts it, and `change authorize` records the
+user's instruction covering the new agreement. Editing the inputs afterwards still
+yields `AGREEMENT_CHANGED`.
+
 Coverage JSON schema 1:
 
 ```

package/template/scripts/pincer-runtime/readiness.cjs

@@ -70,7 +70,12 @@ function migratedTicketReadiness({ text, fields, timeout, attempt, legacyReceipt
     default: return { ready: false, reasons: [reason('ATTEMPT_ERROR', `attempt ${id} has unknown outcome ${JSON.stringify(attempt.outcome)}`, 'verify')] };
   }
   if (current.prdRevision && attempt.context && attempt.context.prd_revision !== current.prdRevision) {
-    reasons.push(reason('REVISION_CHANGED', 'the PRD revision changed since the passing attempt', 'register --rebind, then verify'));
+    // The remedy is mode-specific. `register --rebind` is the v0.4.1/v0.5.0 repair and
+    // changes mode refuses it outright (AGREEMENT_CHANGED: "--rebind is not supported
+    // for change records"), so naming it there sends the reader to a command the
+    // runtime will not run — the defect class T-80 closed for the coverage report.
+    reasons.push(reason('REVISION_CHANGED', 'the PRD revision changed since the passing attempt',
+      mode === 'changes' ? 'change revise, record its authorization, then verify' : 'register --rebind, then verify'));
   }
   if (attempt.check && attempt.check.digest !== parse.checkDigest(text, timeout)) {
     reasons.push(reason('CHECK_CHANGED', 'the Verification block or timeout changed since the passing attempt', 'verify'));

package/template/scripts/pincer-runtime/resume.cjs

@@ -202,4 +202,72 @@ function render(r) {
   return `${lines.join('\n')}\n`;
 }
 
-module.exports = { SCHEMA, build, decide, render };
+// --- The brief projection (docs/runtime-contracts.md, "Brief resume") ----------------
+// A fresh session reads the full report to answer one question — what do I do next —
+// and pays for every ticket row, attempt row and repeated blocker detail to get it.
+// The brief keeps the answer and the counts and drops the repetition.
+//
+// It is a projection, not a second report: `next` is the full report's own object,
+// copied, and every distinct blocker code survives with its exact count. Grouping may
+// collapse repetition; it may never collapse a category, because a category is the
+// reason a gate will refuse. Nothing here recomputes a verdict, caches readiness or
+// decides an action, and `detail` names the command that prints every omitted row.
+const BRIEF = 1;
+const BRIEF_KIND = 'resume-brief';
+
+function brief(r) {
+  const counts = {};
+  for (const b of r.blockers) counts[b.code] = (counts[b.code] || 0) + 1;
+  const byStatus = { open: 0, in_progress: 0, done: 0 };
+  let notReady = 0;
+  for (const t of r.tickets) {
+    if (t.status in byStatus) byStatus[t.status]++;
+    if (!t.readiness.ready) notReady++;
+  }
+  const running = r.attempts.filter(a => a.outcome === 'running').length;
+  const currentFailed = r.attempts.filter(a => a.current && a.outcome !== 'passed').length;
+  const cov = r.coverage;
+  return {
+    brief: BRIEF, kind: BRIEF_KIND, of: SCHEMA,
+    generated: r.generated, root: r.root, mode: r.mode,
+    selection: r.selection,
+    change: r.change ? { id: r.change.id, prd: r.change.prd, base: r.change.base, lifecycle: r.change.lifecycle.state } : null,
+    agreement: r.agreement ? { current: r.agreement.current, verdict: r.agreement.verdict, authorized: r.agreement.authorized ? { id: r.agreement.authorized.id, disposition: r.agreement.authorized.disposition } : null } : null,
+    coverage: cov ? { label: cov.label, strict: cov.strict, structure: cov.strict && cov.structure ? cov.structure.complete : null, implementation: cov.strict && cov.implementation ? cov.implementation.scenarios : null } : null,
+    tickets: { total: r.tickets.length, by_status: byStatus, not_ready: notReady },
+    attempts: { total: r.attempts.length, running, current_failed: currentFailed },
+    candidate: r.candidate ? { notes: r.candidate.notes, candidate: r.candidate.candidate, evidence: r.candidate.evidence ? r.candidate.evidence.verdict : null } : null,
+    blockers: { total: r.blockers.length, categories: Object.keys(counts).map(code => ({ code, count: counts[code] })) },
+    next: r.next,
+    detail: {
+      command: `${RUNTIME} resume${r.change ? ` --change ${r.change.id}` : ''}`,
+      prd: r.references ? r.references.prd.path : null,
+      tickets: r.references ? r.references.tickets.map(t => t.file) : [],
+      omitted: r.tickets.length + r.attempts.length + Math.max(0, r.blockers.length - Object.keys(counts).length),
+    },
+  };
+}
+
+function renderBrief(b) {
+  const lines = [];
+  const short = s => (typeof s === 'string' ? s.slice(0, 12) : '—');
+  lines.push(`PINCER resume --brief · ${b.generated} · ${b.root}`);
+  if (!b.change) {
+    lines.push(`Selection  ${b.selection && b.selection.change ? b.selection.change : 'none'}${b.selection && b.selection.problem ? ` · ${b.selection.problem.code}: ${b.selection.problem.detail}` : ''}`);
+  } else {
+    const c = b.change, a = b.agreement;
+    lines.push(`Change     ${c.id} · ${c.prd} · base ${c.base.slice(0, 7)} · ${c.lifecycle}`);
+    lines.push(`Agreement  ${a.current ? short(a.current) : 'unavailable'} · ${a.verdict}${a.authorized ? ` · authorized ${a.authorized.id} (${a.authorized.disposition})` : ' · not authorized'}`);
+    if (b.coverage) lines.push(`Coverage   ${b.coverage.label}${b.coverage.strict ? ` · structure ${b.coverage.structure ? 'complete' : 'incomplete'} · implementation ${b.coverage.implementation.complete}/${b.coverage.implementation.total - b.coverage.implementation.dispositioned} scenarios` : ''}`);
+    const t = b.tickets;
+    lines.push(`Tickets    ${t.total} · ${t.by_status.done} done · ${t.by_status.in_progress} in progress · ${t.by_status.open} open · ${t.not_ready} not ready`);
+    lines.push(`Attempts   ${b.attempts.total}${b.attempts.running ? ` · ${b.attempts.running} running` : ''}${b.attempts.current_failed ? ` · ${b.attempts.current_failed} current not passed` : ''}`);
+    if (b.candidate) lines.push(`Candidate  ${b.candidate.notes === 'current' ? `current (${String(b.candidate.candidate).slice(0, 7)})` : b.candidate.notes}${b.candidate.evidence ? ` · evidence ${b.candidate.evidence}` : ''}`);
+  }
+  lines.push(`Blockers   ${b.blockers.total ? b.blockers.categories.map(x => `${x.code}${x.count > 1 ? ` ×${x.count}` : ''}`).join(' · ') : 'none'}`);
+  lines.push(`Next       ${b.next.action}: ${b.next.command}`);
+  lines.push(`Detail     ${b.detail.command}${b.detail.omitted ? ` (${b.detail.omitted} row(s) not shown)` : ''}${b.detail.prd ? ` · ${b.detail.prd}` : ''}`);
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { SCHEMA, BRIEF, BRIEF_KIND, build, decide, render, brief, renderBrief };

package/template/scripts/pincer-runtime/scaffold.cjs

@@ -0,0 +1,254 @@
+'use strict';
+// PINCER runtime — the coverage draft (docs/runtime-contracts.md, "Coverage draft").
+// `coverage scaffold --change <id>` projects the validated PRD inventory, the change's
+// tickets and any authored map into one reviewable draft. It exists because authoring
+// `.prd/coverage/<id>.json` means transcribing every live scenario, every ticket role
+// and every check declaration out of documents the runtime has already parsed; that
+// transcription is the measured cost this removes (docs/prd-v7-pilots.md).
+//
+// What it must never do is decide. The draft carries no semantic judgment: an
+// unresolved scenario stays unresolved, a check command is never invented, a ticket
+// role is never guessed, and a scope disposition is never chosen. Candidate tickets
+// and their existing verification text are listed as *material to read*, with their
+// file provenance, never promoted into a link or a declaration.
+//
+// The envelope is `draft: 1` with no `schema` key, so `coverage.validateMap` refuses
+// it: a draft written to disk is not a coverage map and cannot become one by being
+// saved. The real map is authored by hand, validated by `coverage`, adopted by
+// `coverage adopt` and authorized by `change authorize`, exactly as before.
+//
+// Pure and read-only: nothing here writes a file, launches a check, changes a
+// selection or records an approval. The draft body carries no timestamp, so two calls
+// on identical authored inputs produce byte-identical output.
+const fs = require('node:fs');
+const path = require('node:path');
+const parse = require('./parse.cjs');
+const requirements = require('./requirements.cjs');
+const coverage = require('./coverage.cjs');
+
+const DRAFT = 1;
+const KIND = 'coverage-draft';
+const RUNTIME = 'node scripts/pincer-runtime.cjs';
+// Unresolved codes, in report order. These describe the draft, not the runtime state:
+// they say what a human still has to author, never what a gate will refuse.
+const UNRESOLVED_ORDER = ['SCENARIO_UNLINKED', 'CHECK_UNDECLARED', 'TICKET_UNCLASSIFIED', 'SCENARIO_STALE', 'TICKET_FOREIGN'];
+
+const AUTHORED = 'authored';
+const UNRESOLVED = 'unresolved';
+
+// The first line under a ticket heading, used as the objective a reviewer reads.
+function firstLine(text, heading) {
+  const rows = parse.lines(text);
+  const i = rows.findIndex(l => l.trim() === heading);
+  if (i === -1) return null;
+  const next = rows.slice(i + 1).find(l => l.trim() !== '');
+  return next ? next.trim() : null;
+}
+// The IDs a ticket's own Context section claims ("- Implements: R-04." and
+// "- Scenarios: S-10, S-11."). Classified against the live inventory rather than by
+// prefix, because tickets name other tickets on the same lines — T-03 of the strict
+// fixture says "Implements: none (enables T-01, T-02)", and reading that as two
+// scenario claims would be the draft inventing a link out of prose. An ID the
+// inventory does not define is not reported at all.
+const CLAIM_LINE = /^[ \t]*[-+*][ \t]+(?:Implements|Scenarios|Requirements):/;
+function claimsOf(text, inventory) {
+  const ids = new Set();
+  for (const row of parse.lines(text)) {
+    if (!CLAIM_LINE.test(row)) continue;
+    for (const id of row.match(new RegExp(requirements.ID, 'g')) || []) ids.add(id);
+  }
+  const claimed = [...ids];
+  return {
+    requirements: requirements.sortIds(claimed.filter(id => inventory.requirements[id])),
+    scenarios: requirements.sortIds(claimed.filter(id => inventory.scenarios[id])),
+  };
+}
+// The ticket's own Verification fence, verbatim, as provenance for a reviewer. It is
+// quoted, never turned into a check declaration: whether it proves the scenario is a
+// judgment the draft does not make.
+function verificationOf(text) {
+  const commands = parse.verificationCommands(text);
+  return commands && commands.length ? commands.join('\n') : null;
+}
+
+// build(root, record) → { ok, code, problems, draft }
+// `code` is set only when the inputs cannot be read; a missing map is the normal case
+// this command exists for, not an error.
+function build(root, record) {
+  const fail = (code, problems) => ({ ok: false, code, problems, draft: null });
+  const inv = requirements.readInventory(root, record.prd);
+  if (!inv.ok) return fail(inv.code, inv.problems);
+  const inventory = inv.inventory;
+
+  // An absent map is expected; an unreadable one is not — silently dropping authored
+  // content would be the one way this command could destroy work.
+  const rel = coverage.file(record.change);
+  const real = coverage.realFile(root, rel);
+  let authored = null;
+  if (!real) {
+    const m = coverage.readMap(root, record);
+    if (!m.ok) return fail(m.code, m.problems);
+    authored = m;
+  } else if (!real.endsWith(': missing')) {
+    return fail('COVERAGE_INVALID', [`${rel}: ${real.slice(rel.length + 2)}`]);
+  }
+
+  const t = coverage.ticketsOf(root, record);
+  if (!t.ok) return fail(t.code, t.problems);
+
+  const map = authored ? authored.map : null;
+  const unresolved = [];
+  const note = (code, id, detail) => unresolved.push({ code, id, detail });
+
+  // --- scenarios: every live scenario exactly once, authored rows preserved ----------
+  const scenarios = {};
+  const scope = {};
+  for (const id of requirements.sortIds(Object.keys(inventory.scenarios))) {
+    const live = inventory.scenarios[id];
+    const authoredScope = map && map.scope ? map.scope[id] : null;
+    if (authoredScope) {
+      scope[id] = { ...authoredScope, state: AUTHORED };
+      continue;
+    }
+    const row = map && map.scenarios ? map.scenarios[id] : null;
+    const tickets = row ? [...row.tickets] : [];
+    const checks = row ? [...row.checks] : [];
+    const resolved = Boolean(row) && tickets.length > 0 && checks.length > 0;
+    scenarios[id] = { requirement: live.requirement, state: resolved ? AUTHORED : UNRESOLVED, tickets, checks };
+    if (!row) note('SCENARIO_UNLINKED', id, `${id} (${live.requirement}) has no row in scenarios or scope`);
+    else if (!tickets.length) note('SCENARIO_UNLINKED', id, `${id} is linked to no ticket`);
+    else if (!checks.length) note('CHECK_UNDECLARED', id, `${id} is linked to no check`);
+  }
+  // A map row naming a scenario the inventory no longer defines is authored content:
+  // it is preserved and flagged, never deleted, because removing an obligation is a
+  // decision with its own disposition and authorization.
+  if (map) {
+    for (const id of requirements.sortIds(Object.keys(map.scenarios))) {
+      if (scenarios[id] || scope[id]) continue;
+      scenarios[id] = { requirement: null, state: UNRESOLVED, tickets: [...map.scenarios[id].tickets], checks: [...map.scenarios[id].checks] };
+      note('SCENARIO_STALE', id, `${id} has a row but is not a scenario of ${record.prd}`);
+    }
+    for (const id of requirements.sortIds(Object.keys(map.scope))) {
+      if (scope[id] || inventory.scenarios[id]) continue;
+      scope[id] = { ...map.scope[id], state: UNRESOLVED };
+      note('SCENARIO_STALE', id, `${id} has a scope row but is not a scenario of ${record.prd}`);
+    }
+  }
+
+  // --- tickets: authored roles preserved; unclassified tickets named, not classified --
+  const tickets = {};
+  for (const id of requirements.sortIds(Object.keys(t.tickets))) {
+    const row = map && map.tickets ? map.tickets[id] : null;
+    if (row) tickets[id] = { role: row.role, rationale: row.rationale, state: AUTHORED };
+    else {
+      tickets[id] = { role: null, rationale: null, state: UNRESOLVED };
+      note('TICKET_UNCLASSIFIED', id, `${id} has no role; classify it as implements or enables (an enabling ticket needs a rationale)`);
+    }
+  }
+  if (map) {
+    for (const id of requirements.sortIds(Object.keys(map.tickets))) {
+      if (tickets[id]) continue;
+      tickets[id] = { role: map.tickets[id].role, rationale: map.tickets[id].rationale, state: UNRESOLVED };
+      note(t.others[id] ? 'TICKET_FOREIGN' : 'SCENARIO_STALE', id,
+        t.others[id] ? `${id} is a ticket of ${t.others[id]}, not of ${record.prd}` : `${id} has a row but no ticket file is associated with ${record.prd}`);
+    }
+  }
+
+  // --- checks: authored declarations preserved verbatim; none invented ---------------
+  const checks = {};
+  if (map) for (const id of Object.keys(map.checks).sort()) checks[id] = { ...map.checks[id], state: AUTHORED };
+  // Every check a scenario links to must be declared; an undeclared one is named.
+  for (const [sid, row] of Object.entries(scenarios)) {
+    for (const c of row.checks) {
+      if (checks[c]) continue;
+      note('CHECK_UNDECLARED', c, `${c} is linked from ${sid} but has no declaration`);
+    }
+  }
+
+  // --- candidates: material to read, with provenance. Never a link. -----------------
+  const candidates = { tickets: {} };
+  for (const id of requirements.sortIds(Object.keys(t.tickets))) {
+    const entry = t.tickets[id];
+    const claims = claimsOf(entry.text, inventory);
+    candidates.tickets[id] = {
+      file: entry.file,
+      objective: firstLine(entry.text, '## Objective'),
+      implements: claims.requirements,
+      scenarios: claims.scenarios,
+      verification: verificationOf(entry.text),
+    };
+  }
+
+  unresolved.sort((a, b) => (UNRESOLVED_ORDER.indexOf(a.code) - UNRESOLVED_ORDER.indexOf(b.code)) || requirements.compareIds(a.id, b.id));
+  const draft = {
+    draft: DRAFT,
+    kind: KIND,
+    change: record.change,
+    prd: record.prd,
+    inventory: { digest: inventory.digest, requirements: Object.keys(inventory.requirements).length, scenarios: Object.keys(inventory.scenarios).length },
+    authored: { map: authored ? authored.file : null, digest: authored ? authored.digest : null },
+    scenarios, scope, tickets, checks, candidates, unresolved,
+    next: nextAction(record, unresolved, authored),
+  };
+  return { ok: true, code: null, problems: [], draft };
+}
+
+// What the reader does next. A complete draft does not adopt anything: it says the map
+// is ready to be reviewed and validated, which is a different claim from "correct".
+function nextAction(record, unresolved, authored) {
+  if (unresolved.length) {
+    const first = unresolved[0];
+    return { action: `author the unresolved entries (${unresolved.length}), starting with ${first.id}`, command: `edit ${coverage.file(record.change)} — ${first.detail}` };
+  }
+  if (!authored) return { action: 'author the map from this draft, then validate it', command: `edit ${coverage.file(record.change)}, then ${RUNTIME} coverage --change ${record.change}` };
+  return { action: 'review the authored map, then preview adoption', command: `${RUNTIME} coverage adopt --preview --change ${record.change}` };
+}
+
+function render(d) {
+  const lines = [];
+  const count = o => Object.keys(o).length;
+  lines.push(`PINCER coverage draft · change ${d.change} · ${d.prd}`);
+  lines.push(`Inventory  ${d.inventory.requirements} requirement(s), ${d.inventory.scenarios} scenario(s) · digest ${d.inventory.digest.slice(0, 12)}`);
+  lines.push(`Authored   ${d.authored.map ? `${d.authored.map} · digest ${d.authored.digest.slice(0, 12)}` : 'no map yet'}`);
+  lines.push('');
+  lines.push(`Scenarios  ${count(d.scenarios)} linked row(s), ${count(d.scope)} scope row(s)`);
+  for (const [id, s] of Object.entries(d.scenarios)) {
+    const marker = s.state === AUTHORED ? ' ' : '?';
+    lines.push(`  ${marker} ${id}  ${s.requirement || '(not in the inventory)'}  tickets ${s.tickets.length ? s.tickets.join(', ') : '—'}  checks ${s.checks.length ? s.checks.join(', ') : '—'}`);
+  }
+  for (const [id, s] of Object.entries(d.scope)) {
+    lines.push(`  ${s.state === AUTHORED ? ' ' : '?'} ${id}  scope: ${s.disposition}${s.decision ? ` (${s.decision})` : ''}${s.note ? ` — ${s.note}` : ''}`);
+  }
+  lines.push('');
+  lines.push(`Tickets    ${count(d.tickets)}`);
+  for (const [id, t] of Object.entries(d.tickets)) {
+    const c = d.candidates.tickets[id];
+    lines.push(`  ${t.state === AUTHORED ? ' ' : '?'} ${id}  role ${t.role || '—'}${t.rationale ? ` (${t.rationale})` : ''}${c && c.objective ? `  · ${c.objective}` : ''}`);
+    if (t.state !== AUTHORED && c) {
+      const claimed = [...c.implements, ...c.scenarios];
+      if (claimed.length) lines.push(`      the ticket says it implements ${claimed.join(', ')} (${c.file}) — a statement to check, not a link`);
+      if (c.verification) lines.push(`      its Verification block runs: ${c.verification.split('\n')[0]}${c.verification.includes('\n') ? ' …' : ''}`);
+    }
+  }
+  lines.push('');
+  lines.push(`Checks     ${count(d.checks)}`);
+  for (const [id, c] of Object.entries(d.checks)) {
+    lines.push(`  ${c.state === AUTHORED ? ' ' : '?'} ${id}  ${c.kind}${c.required ? ', required' : ''}  ${c.kind === 'command' ? c.command : c.obligation}`);
+  }
+  if (!count(d.checks)) lines.push('    none declared — a check is authored, never derived from a ticket');
+  lines.push('');
+  if (d.unresolved.length) {
+    lines.push(`Unresolved ${d.unresolved.length}`);
+    for (const u of d.unresolved) lines.push(`  ${u.code}  ${u.detail}`);
+  } else {
+    lines.push('Unresolved none — every scenario has a row, every ticket a role, every linked check a declaration');
+  }
+  lines.push('');
+  lines.push('This is a draft, not a coverage map: it carries no schema, and `coverage`,');
+  lines.push('`coverage adopt` and the agreement digest do not accept it. Author');
+  lines.push(`${coverage.file(d.change)} yourself, review the links, then validate and adopt it.`);
+  lines.push(`Next       ${d.next.action}: ${d.next.command}`);
+  return `${lines.join('\n')}\n`;
+}
+
+module.exports = { DRAFT, KIND, UNRESOLVED_ORDER, AUTHORED, UNRESOLVED, build, render, nextAction };

package/template/scripts/pincer-runtime.cjs

@@ -16,8 +16,8 @@
 //   node scripts/pincer-runtime.cjs change authorize <id> --agreement <digest> (--reference <text> --excerpt <text> | --delegated --basis A-NN --explanation <text>) [--decision D-NN]...
 //   node scripts/pincer-runtime.cjs change decide <id> --summary <text> [--id D-NN] | --resolve D-NN --reference <text> --excerpt <text>
 //   node scripts/pincer-runtime.cjs change activate|pause|resume|complete|reopen|cancel|supersede <id> [--reason <text>] [--note <text>] [--decision D-NN] [--with <id>]
-//   node scripts/pincer-runtime.cjs resume [--change <id>] [--json]
-//   node scripts/pincer-runtime.cjs coverage [--change <id>] [--json] · coverage adopt --preview|--apply --change <id> [--agreement <digest>]
+//   node scripts/pincer-runtime.cjs resume [--change <id>] [--brief] [--json]
+//   node scripts/pincer-runtime.cjs coverage [--change <id>] [--json] · coverage scaffold --change <id> [--json] · coverage adopt --preview|--apply --change <id> [--agreement <digest>]
 //   node scripts/pincer-runtime.cjs impact [--change <id>] [--from G-NN|A-NN] [--json]
 //
 // Exit codes: 0 ok · 1 failed/not ready/refused · 2 usage · 3 state busy ·
@@ -77,8 +77,8 @@ function usage(message) {
     '       pincer-runtime.cjs change decide <id> --summary <text> [--id D-NN] | --resolve D-NN --reference <text> --excerpt <text>\n' +
     '       pincer-runtime.cjs change activate|resume|complete <id> · change pause <id> --reason <text> [--note <text>] · change reopen <id> --reason <text>\n' +
     '       pincer-runtime.cjs change cancel <id> --decision D-NN --reason <text> · change supersede <id> --with <id> --decision D-NN\n' +
-    '       pincer-runtime.cjs resume [--change <id>] [--json]   (the read-only report; `change resume` is the lifecycle operation)\n' +
-    '       pincer-runtime.cjs coverage [--change <id>] [--json] · coverage adopt --preview|--apply --change <id> [--agreement <digest>]\n' +
+    '       pincer-runtime.cjs resume [--change <id>] [--brief] [--json]   (the read-only report; `change resume` is the lifecycle operation)\n' +
+    '       pincer-runtime.cjs coverage [--change <id>] [--json] · coverage scaffold --change <id> [--json] · coverage adopt --preview|--apply --change <id> [--agreement <digest>]\n' +
     '       pincer-runtime.cjs impact [--change <id>] [--from G-NN|A-NN] [--json]\n');
   process.exit(EXIT.USAGE);
 }
@@ -422,6 +422,22 @@ function cmdRegister(root, args) {
 // entry into strict coverage (docs/runtime-contracts.md, "Adoption and rollback").
 function cmdCoverage(root, args) {
   const [sub, ...rest] = args;
+  // coverage scaffold --change <id> [--json] — the read-only coverage draft
+  // (docs/runtime-contracts.md, "Coverage draft"). Writes nothing and launches nothing;
+  // the draft it prints is not a map and `coverage adopt` does not accept it.
+  if (sub === 'scaffold') {
+    const o = parseOptions(rest, { switches: ['--json'], valued: ['--change'] });
+    if (o.positional.length) usage(`unexpected argument ${o.positional[0]} (coverage scaffold takes --change <id> [--json])`);
+    if (!o.change) usage('coverage scaffold requires --change <id>');
+    const scaffold = require('./pincer-runtime/scaffold.cjs');
+    const resolved = changes.resolveSelected(root, { change: o.change });
+    if (resolved.code) fail('pincer', `${resolved.code}: ${resolved.problem}`, exitForCode(resolved.code));
+    const result = scaffold.build(root, resolved.record);
+    if (!result.ok) fail('pincer', `${result.code}: ${result.problems[0]}`, exitForCode(result.code));
+    if (o.json) io.out(`${JSON.stringify(result.draft, null, 2)}\n`);
+    else io.out(scaffold.render(result.draft));
+    process.exit(EXIT.OK);
+  }
   if (sub !== 'adopt') {
     // The read-only coverage report (docs/runtime-contracts.md, "Coverage and impact commands").
     const o = parseOptions(args, { switches: ['--json'], valued: ['--change'] });
@@ -476,9 +492,18 @@ function cmdImpact(root, args) {
 
 // resume [--change <id>] [--json] — the read-only resume report (never the lifecycle operation).
 function cmdResume(root, args) {
-  const o = parseOptions(args, { switches: ['--json'], valued: ['--change'] });
+  const o = parseOptions(args, { switches: ['--json', '--brief'], valued: ['--change'] });
   if (o.positional.length) usage(`unexpected argument ${o.positional[0]}`);
   const result = resume.build(root, { change: o.change || null });
+  // --brief is a projection of the same computed report: same verdict, same next
+  // action, same blocker categories, fewer bytes (docs/runtime-contracts.md, "Brief
+  // resume"). It never recomputes a decision and never changes the exit code.
+  if (o.brief) {
+    const brief = resume.brief(result.json);
+    if (o.json) io.out(`${JSON.stringify(brief, null, 2)}\n`);
+    else io.out(resume.renderBrief(brief));
+    process.exit(result.exit);
+  }
   if (o.json) io.out(`${JSON.stringify(result.json, null, 2)}\n`);
   else io.out(result.text);
   process.exit(result.exit);