pincer-workflow 0.7.0 → 1.0.1

package/template/scripts/sync-prompts.sh

@@ -1,51 +1,3 @@
 #!/bin/bash
-# Generates the Codex CLI and GitHub Copilot adapters from the canonical
-# PINCER playbooks in .claude/commands/. The playbooks are the single source
-# of truth: edit them, re-run this script, commit the result.
-#
-#   .agents/skills/pincer-*/SKILL.md    — Codex CLI skills (repo-local; Codex
-#                                         removed custom prompts in 0.9x, see
-#                                         openai/codex#16115). Invoke by typing
-#                                         $pincer-plan <brief> in a Codex session.
-#   .github/prompts/pincer-*.prompt.md  — VS Code Copilot prompt files
-#                                         (enable: "chat.promptFiles": true)
-set -euo pipefail
-cd "$(dirname "$0")/.."
-
-mkdir -p .agents/skills .github/prompts
-
-count=0
-for src in .claude/commands/pincer-*.md; do
-  name=$(basename "$src" .md)
-  desc=$(sed -n 's/^description: *"\{0,1\}\([^"]*\)"\{0,1\}$/\1/p' "$src" | head -1)
-  if grep -q '^argument-hint:.*optional' "$src"; then
-    argument_text="the text that follows the \`\$$name\` mention, if any (when omitted, use the playbook's documented default)"
-  else
-    argument_text="the text that follows the \`\$$name\` mention in the user's message (ask only if the required input is missing)"
-  fi
-  body=$(awk 'flag; /^---$/ { if (++c == 2) flag = 1 }' "$src")
-
-  # Codex: one skill directory per playbook. Skills have no $ARGUMENTS
-  # substitution and are invoked as $name mentions, so the argument placeholder
-  # becomes prose and cross-references to /pincer-* become $pincer-* (the
-  # leading-context guard keeps paths like scripts/pincer-status.sh intact).
-  mkdir -p ".agents/skills/$name"
-  {
-    printf -- '---\nname: %s\ndescription: "%s"\n---\n' "$name" "$desc"
-    printf '<!-- Generated from %s by scripts/sync-prompts.sh — edit the source, not this file -->\n\n' "$src"
-    printf '%s\n' "$body" \
-      | sed "s/\$ARGUMENTS/$argument_text/g" \
-      | sed -e 's#^/pincer-\([a-z]*\)#$pincer-\1#' -e 's#\([^A-Za-z0-9_./]\)/pincer-\([a-z]*\)#\1$pincer-\2#g'
-  } > ".agents/skills/$name/SKILL.md"
-
-  # Copilot: prompt-file frontmatter; $ARGUMENTS becomes an input variable.
-  {
-    printf -- '---\nmode: agent\ndescription: "%s"\n---\n' "$desc"
-    printf '<!-- Generated from %s by scripts/sync-prompts.sh — edit the source, not this file -->\n\n' "$src"
-    printf '%s\n' "$body" | sed 's/\$ARGUMENTS/${input:request:Task brief or arguments (optional)}/g'
-  } > ".github/prompts/$name.prompt.md"
-
-  count=$((count + 1))
-done
-
-echo "Synced $count playbooks -> .agents/skills/ and .github/prompts/"
+# Regenerates the project copies, Codex skills and Copilot prompts from the library and harness.json (scripts/pincer/cli.cjs generate).
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/pincer/cli.cjs" generate "$@"

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

@@ -1,240 +0,0 @@
----
-name: pincer-code
-description: "Implement tickets sequentially with verification and one commit per ticket"
----
-<!-- Generated from .claude/commands/pincer-code.md by scripts/sync-prompts.sh — edit the source, not this file -->
-
-
-# $pincer-code — Ticket Implementation
-
-You are implementing the tickets in `tickets/` sequentially. The approved PRD, ticket
-breakdown, and existing session authorization define the work; run continuously and report
-progress between tickets unless a material scope or design decision appears.
-
-**Initial request:** the text that follows the `$pincer-code` mention, if any (when omitted, use the playbook's documented default)
-
-Ticket state lives in the ticket file's frontmatter and is written **only** by
-`scripts/pincer-ticket.sh` (`start` → `verify` → `done`). `verify` runs the ticket's
-Verification block and stamps a receipt only on a green exit; `done` refuses without a
-receipt that matches the current check, or with unticked acceptance criteria. Never edit
-`status`, `started`, `last_check`, `verified`, or `finished` by hand — on Claude Code a hook blocks it.
-On a migrated project (a change binding under `.prd/changes/`; the `Runtime` line of
-`scripts/pincer-status.sh` names it) `verify` records an attempt under `.pincer/runtime/`
-and writes no receipt into the ticket, and `done` consumes the current passing attempt
-against the current source without re-running the check. `.pincer/`, `.prd/changes/` and `.prd/evidence/changes/`
-are written only by the runtime; never edit or delete them by hand. On a project with
-change records (`Runtime  changes …`) every `start`, `verify` and `done` first passes
-the change gate: the ticket's change must be selected in this worktree, `active`
-(`verify` also runs on a `completed` change), on a compatible branch, and authorized
-for the current agreement — otherwise the command refuses with `SELECTION_REQUIRED`,
-`WRONG_CHANGE`, `LIFECYCLE_BLOCKED`, `BASE_MISMATCH`, `DECISION_REQUIRED`,
-`AUTHORIZATION_REQUIRED` or `AGREEMENT_CHANGED` before anything runs or is written.
-
-## Before the loop
-
-Run `scripts/pincer-status.sh`. It lists every ticket's state, what is blocked, elapsed
-build time from the clock, and the next action. If a ticket is `in_progress`, you are
-resuming: read it, check `git status` / `git diff` for uncommitted work, and continue
-from wherever the receipt says you are. Do not ask the user to reconfirm unchanged,
-previously authorized work. Read the `Runtime` line before the first ticket. `changes` (change records under
-`.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. `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
-with `change resume <id>`. On a change with strict coverage (`Coverage strict …` in status) also read
-`node scripts/pincer-runtime.cjs coverage` — it names the scenario, ticket, check or
-decision that is next and every structural gap (`COVERAGE_INCOMPLETE`,
-`SCOPE_UNAUTHORIZED`, `OBLIGATION_MISSING`) — and, after any PRD, ticket or map edit,
-`node scripts/pincer-runtime.cjs impact` (`--from G-NN` for another baseline): it
-lists the affected scenarios, tickets and checks with reasons and the dependency
-dependents separately, and reports an unscoped PRD change or unavailable history
-rather than "no impact". `legacy` and no ticket of this PRD carries legacy
-receipts → register now (`node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md`,
-commit `.prd/changes/` and `.gitignore` as `Register PRD vN`), then record the user's
-approval (`change authorize …`, as `$pincer-narrow` describes), select and activate.
-`legacy` with legacy receipts, or a v0.5.0 binding (`Runtime  change <id> · revision …`)
-→ run `node scripts/pincer-runtime.cjs migrate --preview --prd .prd/prd-vN.md`, show
-the plan (backups, receipts imported as history, the converted binding, the
-`.gitignore` line, the local selection) and ask once whether to apply. Apply only on
-a yes, then commit the rewritten tickets, `.gitignore` and the record as `Migrate PRD
-vN to the runtime`. The migrated change is planned with no authorization: record the
-user's actual earlier instruction with `change authorize` (the v0.5.0 free text is
-history only) and activate it. Never migrate silently, and never apply when the
-preview reports a conflict.
-
-## Loop (per ticket, in dependency order)
-
-1. **Start:** `scripts/pincer-ticket.sh start T-{NN}` — refuses while a `depends_on` ticket
-   isn't done, and stamps the start time. Read the ticket and the files it references.
-   Announce: "Starting T-{NN}: {title}."
-2. **Implement.** Follow the conventions in `AGENTS.md` and the PRD's architecture and
-   visual direction. Installing a dependency not named in the PRD's architecture is a
-   stop-and-ask: verify it's the real package on the registry (linked repo, downloads —
-   hallucinated names get typosquatted), say why it earns its place, and wait for a yes.
-   For an S ticket, implement directly. For an M ticket touching isolated files, you may
-   dispatch a subagent with a clean prompt: paste the full ticket body, the relevant
-   conventions, and nothing else.
-3. **Verify:** `scripts/pincer-ticket.sh verify T-{NN}` — runs the Verification block and
-   writes the receipt only if it exits 0 (after migration it records an attempt with the
-   captured log under `.pincer/runtime/` and writes no receipt into the ticket; readiness
-   derives from the latest attempt and the current source). Red → fix and re-run; report the actual output,
-   not assumptions. Green output is the definition of done, not your confidence. If the
-   check only validated syntax or a build, say so — that is not behavioral proof. A
-   visual judgment is recorded separately in evaluation, not as the receipt, and a tool
-   the check needs but cannot run yields an explicit `unverified` result, never
-   fabricated output.
-4. **Self-review the diff** before committing: silent failures (empty catches,
-   un-awaited promises), leftover debug code, drift from the ticket's acceptance criteria.
-   Then a security sweep of the same diff:
-   - Check for secret-like assignments without printing values. If a scanner reports a
-     possible secret, report only its file and line until the value is safely redacted;
-     environment references and names in `.env.example` are allowed.
-   - External input touched by this diff is validated server-side, and untrusted
-     content (user input, LLM output) is escaped where rendered — per the
-     Security defaults in `AGENTS.md`.
-   - No error path leaks internals (stack traces, key names with values) to the client.
-   If the review changed code, run `verify` again — the receipt must match the code you commit.
-5. **Close the ticket:** tick every verified acceptance-criteria checkbox (`- [ ]` → `- [x]`;
-   editing the checkboxes is allowed), then `scripts/pincer-ticket.sh done T-{NN}`. After
-   migration `done` consumes the current passing attempt and does not re-run the check; it
-   refuses with a reason code (`SOURCE_CHANGED`, `CHECK_CHANGED`, `CHECK_FAILED`,
-   `CRITERIA_UNTICKED`, …) and the next step when the latest attempt is not current. A
-   criterion that was cut is a scope change to record in the PRD, not a box to skip.
-   Inspect `git status --short`, preserve pre-existing staged work, and stage only the
-   explicit paths changed for this ticket plus its ticket file. Review `git diff --cached`
-   before committing as `T-{NN}: {title}`.
-6. Give a one-line progress update ("T-02 done, 3 remaining") and continue. Quote the
-   wall-clock elapsed figure from `scripts/pincer-status.sh` when it shows one — it
-   appears while a ticket is in progress or a budget is set, and it is not a measure
-   of active execution time.
-
-## Recovering a ticket file
-
-Ticket lifecycle fields are written only by `scripts/pincer-ticket.sh`, and the guard
-also blocks shell restores that would touch ticket files from the assistant's shell:
-`git checkout`/`git restore`/`git switch` naming a ticket path or a normalized
-pathspec that cannot be shown to stay outside `tickets/` (the whole tree, `.`, `:/`,
-`:(top)`, globs, absolute or unexpanded paths, `tickets/…` in any spelling, a
-`-C tickets` prefix), force flags (`-f`, `--force`, `--discard-changes`,
-`--pathspec-from-file`), `git reset --hard|--merge|--keep`, `git stash` (except
-`list`, `show`, `create`, `store`), `git clean -f` without a narrow pathspec,
-`git checkout-index -a` and `git read-tree -u|--reset`, including when wrapped in
-`bash -c`, `eval`, `nice`, `time`, `nohup`, `timeout` or `xargs`. Restoring HEAD
-would erase a newer failed attempt and revive an old passing receipt. Branch
-switches and file-specific restores outside `tickets/` stay allowed. The guard is a
-pattern-based safety net for documented mistake forms, not a complete shell
-boundary; the receipt and status checks remain the source of trust. When a ticket file is malformed or its state was hand
-edited, preserve the malformed contents as they are, report the validation error that
-the script or `scripts/pincer-status.sh` printed, and hand the repair to the user, who
-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. 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; the recorded
-failure is explained by a working-tree change that has since been reverted (the failed
-`last_check` was stamped while source differed from the candidate, and that difference
-is gone); and the ticket's Verification block passes when run
-directly rather than through `verify` (which would write a receipt), in the
-same execution context as `verify` — the same shell, working directory, `PATH`
-and environment, with no substituted binary and no repair made first — 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.
-A changed executable, runner, working directory or environment repair requires a
-new recorded verification through `verify`; the exception does not apply to it.
-An unexplained failure cannot be cleared by restoring a receipt: when no
-since-reverted source change explains it (a service down, a missing dependency, a
-check that reads external data), keep the failure, name the cause you observed, and
-ask for the environment to be repaired before `verify` runs again.
-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.
-After migration (a change binding exists) recovery is the lifecycle itself: retain the
-failure, repair the cause, run `verify` again; readiness derives from the latest attempt,
-both attempts stay in `.pincer/runtime/` and no tracked file changes. Never restore a
-ticket file or delete `.pincer/runtime` to obtain a green status; the legacy exception
-above applies only before migration. A session that died mid-`verify` leaves a `running`
-attempt: run `node scripts/pincer-runtime.cjs recover`, which finalizes it as
-`interrupted` once the owner process is gone, then `verify` again.
-
-## Changes: pausing, decisions and completion
-
-- Stopping before the change is complete (end of session, switching to another
-  change): `node scripts/pincer-runtime.cjs change pause <id> --reason "<why>" --note "<handoff for the next session>"`
-  and commit the record. Pausing keeps every ticket state, attempt and authorization;
-  it refuses while a check is running (`recover` first if its owner died). A fresh
-  session runs `resume`, then `change resume <id>` under the existing authorization —
-  do not ask the user to re-approve unchanged scope. Another change's work in the
-  meantime makes this change's passing attempts `SOURCE_CHANGED`; verify again, do
-  not ask for approval again.
-- A newly discovered consequential choice: `node scripts/pincer-runtime.cjs change decide <id> --summary "<the question>"`
-  blocks execution (`DECISION_REQUIRED`) until the user answers; record the answer with
-  `change decide <id> --resolve D-NN --reference "<where>" --excerpt "<the user's words>"`,
-  then `change authorize <id> --agreement <digest> --reference … --excerpt … --decision D-NN`.
-  A revision within the user's delegation (for example an added regression check for
-  approved behavior) records `change authorize <id> --agreement <digest> --delegated --basis A-NN --explanation "<why it stays within the delegation>"`
-  without asking again, and the changed check still needs fresh verification.
-- Editing the PRD under its filename, or a ticket's acceptance text, dependencies,
-  size, timeout, association or check — and, with strict coverage, a scenario's text,
-  a map link, a declared command or timeout, or a scope entry — changes the agreement:
-  execution refuses with `AGREEMENT_CHANGED` (status shows the structural difference;
-  `impact` explains it) until its disposition is recorded as above. Ticking criteria, starting or closing tickets and recording
-  attempts never change it. An `AGREEMENT_CHANGED` caused by an edit this session
-  did not make — a revised PRD, an added or changed ticket found on resume — is a
-  consequential decision: raise it with `change decide <id> --summary "<what changed>"`,
-  report the structural difference (and the `impact` report) and stop. A general instruction to continue,
-  resume or not re-ask never authorizes new scope; record a `user` authorization for
-  the revised agreement only for an instruction that names the revised content. With strict coverage a scenario that will not be delivered is
-  never dropped from the map or the PRD: it is deferred or removed through a decision
-  the user resolves naming it, a `scope` entry (a removal keeps a tombstone naming the
-  prior agreement) and an authorization naming that decision; `coverage` reports
-  `OBLIGATION_MISSING` or `SCOPE_UNAUTHORIZED` until then, and `change complete`
-  refuses. A revised check declaration (a stricter command, an added check) within the
-  user's delegation is a `--delegated` authorization and needs fresh verification.
-- When every ticket is done and ready: `node scripts/pincer-runtime.cjs change complete <id>`
-  (it refuses unfinished tickets, unticked criteria, stale or failed verification and
-  open decisions; with strict coverage also an incomplete map, an unauthorized
-  disposition or a missing obligation, before the ticket gate) and commit the record
-  as `Complete PRD vN`. Completion never asks for candidate evidence. Completed means ready
-  for evaluation, not evaluated or released; a later finding is `change reopen <id> --reason …`
-  plus a fix ticket.
-
-## Budget rules
-
-- If the user set `PINCER_BUILD_BUDGET_MIN` or stated another budget, use the elapsed
-  figure from `scripts/pincer-status.sh` rather than estimating. If the remaining tickets won't fit,
-  stop and propose a scope cut: which remaining tickets to drop or shrink. Cutting scope
-  deliberately beats an unfinished mess — record the cut in the PRD's Out of Scope.
-- If a ticket reveals the plan was wrong, stop and say so rather than silently diverging.
-  Update the ticket/PRD, then continue.
-
-## When all tickets are done
-
-On a project with change records, complete the change first (`change complete <id>`,
-committed as `Complete PRD vN`). Then update the PRD to `status: built` and commit that change on its own (`PRD vN: built`).
-The built transition is part of the candidate that `$pincer-evaluate` reviews; it is
-never moved into a later evidence-only commit. Then finish with:
-"All tickets built. Run `$pincer-evaluate` for a final quality pass."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-material choice not already authorized, and prepare the concrete proposal before
-asking. A decision the user delegated (for example "pick the architecture") does not
-need another approval when you exercise it, but a newly discovered consequential
-choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover, and on a project with change records as
-a `change authorize` record (the user's words as the excerpt, or a `--delegated`
-disposition with its basis). An agent-written record or a status
-field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.

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

@@ -1,178 +0,0 @@
----
-name: pincer-evaluate
-description: "Final quality pass over everything built — high-confidence findings only"
----
-<!-- Generated from .claude/commands/pincer-evaluate.md by scripts/sync-prompts.sh — edit the source, not this file -->
-
-
-# $pincer-evaluate — Final Quality Pass
-
-You are reviewing all work built this session against the PRD and tickets. Autonomous —
-run the pipeline, then present results.
-
-## Steps
-
-1. Run `scripts/pincer-status.sh`. Review only tickets associated with the selected
-   PRD. Every such ticket should be `done` with a current receipt; if one
-   is still open or in progress, stop and ask whether it was cut (then it goes in the
-   PRD's Out of Scope) or should be finished first via `$pincer-code`. Then get the full
-   diff of the change: identify the actual base commit before this change from
-   its ticket commits and recorded context. If it cannot be established, resolve
-   that uncertainty before claiming a complete review. Record full commit IDs for
-   `base` and `candidate` (`git rev-parse HEAD`), then review `git diff <base>..<candidate>`.
-   The candidate is the clean, committed tree that already includes the implementation,
-   the ticket closures, on a project with change records the `change complete` commit
-   (the `Runtime` line reads `… · completed ·`; `check` and `evidence export` refuse an
-   active, paused or unauthorized change), and the PRD `status: built` commit:
-   `git status --short` must be empty before review. If anything is uncommitted or the PRD is not yet built, return
-   to `$pincer-code`; do not review a dirty tree.
-2. Dispatch a `code-quality-reviewer` agent with: the diff, the PRD's Success Criteria and
-   Scope sections, and the list of tickets. If the diff is large, split by area and
-   dispatch two in parallel. (No subagents on this platform? Review the diff yourself
-   in a separate pass, applying `.claude/agents/code-quality-reviewer.md` as the rubric.)
-   Keep the reviewer's report — or its explicit no-findings statement — for step 9,
-   where it is saved as an artifact; a review that left no record cannot be audited.
-3. Yourself, in parallel, check spec compliance. On a change with strict coverage
-   (`Coverage strict …` in status) start from `node scripts/pincer-runtime.cjs coverage`:
-   its structure must be complete, and its scenario rows are the obligations — the
-   export derives every disposition from the map and the outcomes, so you do not
-   author `requirements`; your judgment is recorded as `adequacy` (whether the
-   declared checks and reviews really establish their scenarios) and in
-   `coverage_review`. Otherwise, for every requirement `R-NN` in the
-   PRD record one disposition: `delivered` (evidence on this candidate), `blocked`
-   (required behavior failed or was left unverified — this blocks PASS; do not relabel
-   it a known limitation to pass), or `deferred` (only with explicit user authorization;
-   record the scope decision in the PRD's Out of Scope and evaluate the revised
-   candidate). Compare what was built against every ticket's acceptance criteria and
-   the PRD scope, and list any gaps. Whether the requirement map is complete and each
-   check is semantically adequate is your judgment as reviewer — record that judgment
-   in the evaluation; the kit is not a mechanical traceability engine and does not
-   validate requirement-revision impact.
-4. If the project has a UI, look at it — don't only read the code. Start it, open it in
-   the browser (screenshot via Chrome DevTools MCP if available), and check it against
-   the PRD's Visual Direction and Success Criteria. Note anything visibly broken or off.
-5. Run a mechanical security audit:
-   - Inspect the relevant history with a secret scanner that redacts values, when one is
-     available. Otherwise review likely locations without copying candidate values into
-     output. Report file, line, and remediation only; a secret committed then deleted is
-     still leaked.
-   - `.gitignore` covers `.env*` (except `.env.example`), and `git ls-files | grep -i env`
-     shows only `.env.example`.
-   - `npm audit --omit=dev` (or the ecosystem's equivalent) — report high/critical only.
-   - If there's an HTTP API: hit one endpoint with invalid input (empty, oversized)
-     and confirm a clean 4xx with a generic message, no stack trace.
-6. Filter the agent's findings: report only issues you'd flag in a real PR review —
-   concrete bugs, silent failures, misleading code. Drop nitpicks and style opinions.
-7. Present findings as a short list with `file:line` references, ordered by severity.
-   Security findings always rank above style-adjacent ones. For each, say whether you
-   recommend fixing now through a ticket or recording it as a known issue.
-8. Fix findings clearly within the authorized PRD through a new ticket associated with
-   that PRD. Use `pincer-ticket.sh` to start, verify, and close it, then make a scoped
-   `T-{NN}: {title}` commit. Ask only when a fix changes scope, architecture, or another
-   material decision; never make an ad-hoc `review: fixes` commit. Every fix commit
-   produces a new candidate: re-record `candidate`, re-run the checks against it, and
-   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>/`.
-   Strict coverage: run every declared command check as
-   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha>` (no command, no
-   timeout: the map's declaration is the only source, and a supplied command is
-   `CHECK_UNDECLARED`); record each declared review or visual obligation in the
-   draft with its `result` and an artifact saved under the candidate's evidence
-   directory (a required one that is not passed with an artifact is
-   `REVIEW_MISSING`); write `adequacy: { verdict: "adequate" | "inadequate", note }`;
-   list every declared check once and no `requirements` (they are derived). The
-   export writes the inventory and map snapshots under `coverage/`, derives the
-   scenario and requirement rows and `delivery` (original versus agreed scope) and
-   validates them against the committed candidate; an `inadequate` judgment or a
-   failed required check is recorded honestly and blocks readiness. Migrated
-   project without strict coverage (the `Runtime` status line names a change): run
-   each executable check through the runtime on the clean candidate view —
-   `node scripts/pincer-runtime.cjs check C-NN --candidate <sha> -- <command>` (one
-   command per check, the command line as run; `npm test` stays one aggregate check) —
-   then write the authored fields to a draft outside the evidence directory, for
-   example `.pincer/drafts/<sha>.json`: `environment.tools` and `environment.limitations`,
-   `coverage_review`, `requirements`, review and visual checks with their saved
-   artifacts, `visual_review`, and a stub `{"id": "C-NN", "kind": "command",
-   "required": true|false}` for each executable check. Then run
-   `node scripts/pincer-runtime.cjs evidence export --candidate <sha> --base <base> --prd .prd/prd-vN.md --draft <file>`.
-   The export writes `checks/C-NN.log` from the captured logs, fills `command`,
-   `result`, `provenance: runtime` and `attempt` from the attempts, labels review and
-   visual checks `provenance: authored`, computes the digests and writes an evidence
-   schema 2 manifest; it refuses a dirty tree, a HEAD that is not the candidate, a stub
-   without an attempt, and a `passed` or `failed` command result written by hand. On a
-   project with change records the export also appends the evaluation to the change's
-   locator `.prd/evidence/changes/<id>.json` (the identity of this change's
-   evaluation; root `NOTES.md` stays the human summary and may be overwritten by a
-   later change's evaluation without losing this one) — commit the locator with the
-   evidence. A tool that cannot run is recorded as an authored command check with
-   `result: unverified` and a note, as before. Legacy project (no change binding):
-   author the schema 1 manifest as follows.
-   - `checks/C-NN.log` — the command and a redacted summary or safe log of each
-     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.
-   - `review/code-quality.md` — the reviewer's findings from step 2 with their
-     dispositions, or its explicit no-findings statement, recorded as a check of
-     kind `review` and referenced by the requirements it covers.
-   - `manifest.json` — evidence schema 1 (field list in the header of
-     `scripts/pincer-evidence.cjs`): selected PRD, full `base` and `candidate` IDs,
-     `created`, `environment` with tool limitations, `coverage_review` (your judgment
-     from step 3), one `requirements` entry per `R-NN` with its disposition, tickets
-     and check IDs, one `checks` entry per check with `kind`, `required`, `result`,
-     `command`, timestamp and artifact paths, and `artifacts` with digests from
-     `node scripts/pincer-evidence.cjs digest <file>...`.
-   A tool you cannot run yields a check with `result: unverified` and a note — never a
-   fabricated artifact. A deferred requirement carries `authorized_by` naming the
-   user's explicit authorization. Then run
-   `node scripts/pincer-evidence.cjs validate .prd/evidence/prd-vN/<candidate>/manifest.json --candidate <candidate> --prd .prd/prd-vN.md`
-   and correct the manifest until it prints `ok`; the same validator runs in status
-   and release. It checks the record's consistency, not that the commands ran.
-10. Close out: write a brief `NOTES.md` at the repo root with frontmatter:
-   ```yaml
-   ---
-   prd: .prd/prd-vN.md
-   base: <full reviewed base commit ID>
-   candidate: <full reviewed candidate commit ID>
-   evidence: .prd/evidence/prd-vN/<candidate>/manifest.json
-   ---
-   ```
-   Then commit NOTES.md, the manifest, its listed artifacts and (change records) the
-   evaluation locator — and nothing else —
-   as `evaluate: PRD vN candidate <short sha>`. Status accepts this later commit only
-   when its diff from the candidate is limited to `NOTES.md`, the candidate's evidence
-   directories and evaluation locators; changes to source, tests, configuration,
-   tickets, the PRD or the change record (a lifecycle transition after the
-   candidate) require reevaluation. Legacy notes without these references
-   do not establish readiness. Then describe what was built, what was cut
-   and why, known issues, and what you'd do next with more time. Then a **Handover**
-   section, written for the stranger who inherits this repo in six months: how to get
-   oriented (which file to read first), what each dependency is for and why it earned
-   its place, and what breaks first as the code ages (the riskiest assumption, the
-   least-tested path). This is the first document a reviewer of this repo should read;
-   summarize the requirement dispositions from the manifest in it.
-11. Suggest `$pincer-release` as the final step: "Run `$pincer-release` for a pass/fail audit of the
-   whole workflow's artifacts."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-material choice not already authorized, and prepare the concrete proposal before
-asking. A decision the user delegated (for example "pick the architecture") does not
-need another approval when you exercise it, but a newly discovered consequential
-choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover, and on a project with change records as
-a `change authorize` record (the user's words as the excerpt, or a `--delegated`
-disposition with its basis). An agent-written record or a status
-field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.

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

@@ -1,148 +0,0 @@
----
-name: pincer-narrow
-description: "Turn the approved PRD into local, AI-ready ticket files"
----
-<!-- Generated from .claude/commands/pincer-narrow.md by scripts/sync-prompts.sh — edit the source, not this file -->
-
-
-# $pincer-narrow — PRD to Local Tickets
-
-You are decomposing the PRD into coherent, independently verifiable tickets stored as
-local markdown files (no external tracker needed). Ticket count and size follow the
-change's dependencies and risk, plus any budget the user supplied. There is no hard
-one-to-two-ticket cap for small PRDs and no default timebox: cohesion and dependencies
-decide the count. A breakdown that follows the PRD needs no second approval; a newly
-discovered consequential choice is surfaced before implementation.
-
-**Initial request:** the text that follows the `$pincer-narrow` mention, if any (when omitted, use the playbook's documented default)
-
-## Steps
-
-1. Run `scripts/pincer-status.sh`. If tickets already exist for another PRD, leave them
-   as history. New tickets continue the numbering and existing ones are never renumbered.
-   If tickets already exist for this PRD, extend them only when the current request already
-   authorizes that work; otherwise present the concrete addition before asking. Then read the
-   PRD (`the text that follows the `$pincer-narrow` mention, if any (when omitted, use the playbook's documented default)` or the latest `.prd/prd-v*.md`). If its status isn't `draft`, ask
-   which PRD to use.
-2. Decompose into tickets. Rules:
-   - Each ticket is one coherent unit. Use S, M, or L as relative scope indicators and
-     split work when that improves dependency order, verification, or ownership.
-   - For greenfield work, use a walking skeleton when it reduces integration risk. For
-     brownfield work, begin with the smallest protected vertical change; add a
-     characterization ticket before changing load-bearing code that lacks coverage.
-   - Order by dependency; note blockers explicitly ("depends on T-01").
-   - Build the requirement map: for every `R-NN` in the PRD and each of its
-     scenarios, name the ticket that owns the implementation and the executable
-     check that exercises it, or an explicit review method when no executable check
-     exists. Record the IDs in each ticket's Context as `Implements: R-NN, R-MM`
-     (a navigation aid). Enabling work that implements no requirement states its purpose
-     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`). 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
-     command line and timeout, and a `scope` entry (`deferred` or `removed`) for a
-     scenario this change will not deliver, naming the decision that records the
-     user's choice. The map is authored work you edit by hand; the runtime never
-     rewrites it, and it validates it against the PRD's definitions.
-   - Every ticket gets a runnable command in its Verification block — a fenced `bash`
-     block that exits 0 only when the ticket is done. `scripts/pincer-ticket.sh verify`
-     runs it verbatim and stamps the receipt that `done` requires, so it must be
-     non-interactive and self-contained (no "check by hand"). An optional
-     `timeout: <seconds>` frontmatter field (default 600) bounds the run; it is part of
-     the check identity, so changing it invalidates earlier passes.
-   - Each Verification section opens with `Proves:` — what the check establishes and
-     which regression it detects. A check for an executable change must exercise
-     observable behavior (including relevant rejection paths and, in brownfield work,
-     preservation of existing behavior) and fail when the behavior is wrong, not only
-     when an identifier is renamed. Reuse adequate focused tests. A build, a syntax
-     check, or an identifier grep alone is not proof; static assertions are primary
-     evidence only for static contracts such as generated files, and `Proves:` says so.
-   - Adequacy is a judgment about what the command observes, never a word match: do
-     not call a command sufficient because it contains `grep`, `test`, or a runner
-     name, nor insufficient for lacking them. Manual visual judgment is recorded
-     separately in evaluation; a tool the check needs but cannot run yields an
-     explicit `unverified` result, never fabricated evidence or a silent waiver.
-   - If the brief or stack implies automated tests, at least one ticket's verification
-     command must be the test runner (e.g. `npm test`) — manual checks alone don't count.
-   - Any ticket whose surface accepts external input (HTTP endpoint, form, file,
-     LLM output) gets an acceptance criterion for the reject path — what invalid
-     input produces (e.g. "empty goal → 400 with a clear message"), not only the
-     happy path.
-   - A greenfield setup ticket includes `.gitignore` covering `.env*` (except
-     `.env.example`) and an `.env.example` naming any required secrets before any
-     secret can exist in the repo. In brownfield repositories, preserve and verify
-     the existing ignore and environment conventions.
-3. Write each ticket to `tickets/T-{NN}-{slug}.md` using
-   `.claude/references/ticket-template.md`, with `status: open` and an explicit
-   `prd: .prd/prd-vN.md` naming the selected PRD. Never infer this association from
-   numbering or old notes. The other state fields
-   (`started`, `last_check`, `verified`, `finished`) are added later by `scripts/pincer-ticket.sh` —
-   never write them yourself.
-4. Present the ticket list (number, title, size, dependencies) as a table, followed
-   by the requirement map as a second table (requirement · scenario · ticket · check
-   or review method). Whether the map is complete and each check is adequate is your
-   judgment as the author; say so rather than presenting the table as mechanical proof.
-
-Present the concrete breakdown and build order as a report, not a question. Reuse
-existing authorization for the same scope and order.
-
-5. Finalize. A breakdown that follows the PRD is already authorized by the PRD: do not
-   ask whether to proceed. Update the selected PRD frontmatter to `status: ticketed`,
-   inspect existing staged changes, stage that PRD and the explicit new ticket paths,
-   review `git diff --cached`, and commit only those paths. Ask first — and finalize
-   once it is resolved — only when step 4 surfaced a newly discovered consequential
-   choice or a scope change the PRD does not cover. Then register the change when the
-   `Runtime` status line says `legacy` and no ticket of this PRD carries legacy
-   receipts, or `changes` (the project already keeps change records):
-   `node scripts/pincer-runtime.cjs register --prd .prd/prd-vN.md` writes the change
-   record `.prd/changes/prd-vN.json` (retaining every earlier change); stage
-   `.prd/changes/` and `.gitignore` (registration adds `.pincer/` to it) and commit them
-   as `Register PRD vN`. Then record the user's actual approval against the agreement
-   the record binds — `node scripts/pincer-runtime.cjs change show prd-vN --json`
-   prints the agreement digest — with
-   `node scripts/pincer-runtime.cjs change authorize prd-vN --agreement <digest> --reference "<where the user said it>" --excerpt "<the user's approval, quoted>"`,
-   select it for this worktree (`node scripts/pincer-runtime.cjs change select prd-vN`)
-   and commit `.prd/changes/` as `Authorize PRD vN`. When the map was authored, adopt
-   strict coverage explicitly: `node scripts/pincer-runtime.cjs coverage adopt --preview --change prd-vN`
-   shows the inventory, the map digest and the agreement it records (it refuses an
-   incomplete map, naming the scenario or ticket); `--apply` writes the schema 3
-   record with a backup and grants nothing — record the user's approval of that
-   agreement with `change authorize` (the same instruction, if it named this
-   breakdown; a delegated disposition needs its basis) and commit `.prd/coverage/`
-   and `.prd/changes/` as `Adopt strict coverage for PRD vN`. A scenario the user
-   deferred or removed is a decision: `change decide --summary "<the choice>"`,
-   `--resolve D-NN` with the user's words naming the scenario, the `scope` entry in
-   the map, then `change authorize … --decision D-NN`. Never record a disposition
-   the user did not state; `coverage` reports `SCOPE_UNAUTHORIZED` until it is. The excerpt records the user's own
-   words; running the command proves nothing by itself, and a registration, a PRD
-   status or a passing check never becomes an authorization. A project whose tickets
-   carry legacy receipts, or that still holds a v0.5.0 binding (`Runtime  change <id> ·
-   revision …`), is migrated from `$pincer-code` after a preview, never here. Finish with:
-   "Tickets ready in `tickets/`. Run `$pincer-code` to start implementing."
-
-## Authorization rule (shared by plan, narrow, code and evaluate)
-
-Reuse explicit authorization for the same scope and decisions; ask only about a
-material choice not already authorized, and prepare the concrete proposal before
-asking. A decision the user delegated (for example "pick the architecture") does not
-need another approval when you exercise it, but a newly discovered consequential
-choice is surfaced before implementation. Record the authorization basis and the
-scope it covers in the PRD or the handover, and on a project with change records as
-a `change authorize` record (the user's words as the excerpt, or a `--delegated`
-disposition with its basis). An agent-written record or a status
-field is not authenticated human approval. When resuming without the context that
-granted authorization, do not invent it — read the `resume` report; an authorization
-it reports as `current` needs no repeat approval, and any other verdict is asked.