pincer-workflow 0.3.0 → 0.4.0

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

@@ -18,13 +18,26 @@ run the pipeline, then present results.
    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>`.
-   Require a clean candidate before review, excluding only the notes being written.
+   The candidate is the clean, committed tree that already includes the implementation,
+   the ticket closures 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.)
-3. Yourself, in parallel, check spec compliance: does what was built match every ticket's
-   acceptance criteria and the PRD scope? List any gaps.
+   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. 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.
@@ -42,28 +55,66 @@ run the pipeline, then present results.
    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 (within the timebox) or noting as known-issue.
+   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.
-9. Close out: write a brief `NOTES.md` at the repo root with frontmatter:
+   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>/`:
+   - `checks/C-NN.log` — the command and a redacted summary or safe log of each
+     executable check. Never secrets, never an environment dump.
+   - `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
    ---
    ```
-   Record the candidate before the separate NOTES commit. Status accepts a later
-   commit only when its diff from the candidate changes solely `NOTES.md`; changes
-   to source, tickets, or PRD require reevaluation. Legacy notes without these
-   references do not establish readiness. Then describe what was built, what was cut
+   Then commit NOTES.md, the manifest and its listed artifacts — 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` and the evidence files
+   the manifest lists; changes to source, tests, configuration, tickets, the PRD or
+   other evaluations 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). Commit it. This is the first document a reviewer of this repo
-   should read.
-10. Suggest `/pincer-release` as the final step: "Run `/pincer-release` for a pass/fail audit of 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. 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 — ask.

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

@@ -7,7 +7,10 @@ argument-hint: "Path to PRD (optional — defaults to the latest in .prd/)"
 
 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.
+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:** $ARGUMENTS
 
@@ -26,10 +29,29 @@ change's dependencies and risk, plus any budget the user supplied.
      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`.
+     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.
    - 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").
+   - 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,
@@ -46,12 +68,29 @@ change's dependencies and risk, plus any budget the user supplied.
    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.
+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. Reuse existing authorization for the same
-scope and order; ask only when the breakdown introduces a material decision or scope change.
+Present the concrete breakdown and build order as a report, not a question. Reuse
+existing authorization for the same scope and order.
 
-5. Once authorized, 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. Finish with:
+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. 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. 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 — ask.

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

@@ -9,6 +9,14 @@ You are turning a task brief into a reviewable PRD. Scale discovery and detail t
 the change's uncertainty, risk, and any time budget the user supplied. The PRD feeds
 `/pincer-narrow` next.
 
+Choose the planning profile and record why it fits: `profile: small` for bounded
+scope, low risk, known behavior and straightforward verification; otherwise
+`standard` (the default). Few changed lines alone do not qualify — migrations,
+authorization boundaries, uncertain requirements and broad effects need proper
+investigation even for a tiny patch. Honor an explicit budget the user supplied;
+there is no default timebox, and a budget never silently cuts requirements —
+record any cut in Out of Scope.
+
 **Initial request:** $ARGUMENTS
 
 First run `scripts/pincer-status.sh`. If a PRD already exists, preserve it and select
@@ -20,7 +28,11 @@ unless the user explicitly authorized a separate change.
 ## Phase 1: Discovery
 
 1. If `$ARGUMENTS` contains the brief, extract what you can before asking anything.
-   Never ask a question the brief already answers.
+   Never ask a question the brief already answers. Preserve or link the original
+   brief in the PRD, and record the desired outcome, assumptions and exclusions.
+   If the user supplied a PRD, review it: keep its meaning and existing requirement
+   IDs; do not silently replace either. Where its structure needs adapting to the
+   template, record a mapping table (`their section or ID → R-NN`) inside the PRD.
 2. Ask only the questions whose answers would change the architecture or scope.
    Batch them (max 3–4 at once). Typical ones:
    - What does "done" look like — what will be run, demoed, or reviewed at the end?
@@ -68,6 +80,11 @@ concrete scope and architecture; do not repeat an approval already given for the
 ## Phase 4: Write the PRD
 
 1. Load `.claude/references/prd-template.md` and write all core sections.
+   In Requirements, assign stable `R-NN` IDs within the selected PRD: a revision
+   keeps existing IDs and adds new ones, never renumbers. Every requirement has
+   observable acceptance scenarios, the relevant failure paths, and the existing
+   behavior it must preserve — `/pincer-narrow` maps each scenario to a ticket and
+   a check, and `/pincer-evaluate` dispositions every ID.
 2. Include optional sections when risk or the product context warrants them.
 3. Save to the next unused `.prd/prd-v{N}.md` (create `.prd/` if needed), with `N`
    matching the filename and frontmatter:
@@ -76,6 +93,7 @@ concrete scope and architecture; do not repeat an approval already given for the
    version: {N}
    status: draft
    date: {today}
+   profile: small   # only when small; omit for standard
    ---
    ```
 4. If `.git/` doesn't exist, run `git init`. Commit the PRD and only the intended setup
@@ -85,3 +103,14 @@ concrete scope and architecture; do not repeat an approval already given for the
 Present the saved draft and obtain approval only when the same scope/architecture was not
 already authorized. Finish with: "PRD saved to `.prd/prd-v{N}.md`. Run `/pincer-narrow`
 to break it into work items."
+
+## 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. 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 — ask.

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

@@ -6,7 +6,11 @@ argument-hint: "Stage to check (optional: plan | narrow | code | evaluate — de
 # /pincer-release — Workflow Audit
 
 You are auditing the current repo state against `docs/release-checklist.md`. Read-only:
-report pass/fail, never fix anything — fixes belong to the stage commands.
+report pass/fail, never fix anything — fixes belong to the stage commands. Release does
+not repair tickets, rewrite evidence, change PRD state, or publish. A check that mutates
+the candidate invalidates the audit: if `git status --short` is not empty afterwards,
+the verdict is FAIL and names the mutation. The verdict is reported to the user; a
+durable runtime-owned release record is later work.
 
 **Requested stage:** $ARGUMENTS
 
@@ -25,13 +29,23 @@ report pass/fail, never fix anything — fixes belong to the stage commands.
    - Receipts: every done ticket carries current `last_check` and `verified` evidence;
      any status warning fails the audit. Do not call `pincer-ticket.sh` from Release:
      it writes receipts and would invalidate the evaluated candidate.
+   - Evidence: `scripts/pincer-status.sh` runs the shared validator
+     (`scripts/pincer-evidence.cjs`) against the manifest `NOTES.md` names. The `Notes`
+     line must read `current` and the `Evidence` line `ok`; any other text fails the
+     audit with that diagnostic. Do not re-implement evidence checks and do not accept
+     screenshots described in chat: read the manifest's `checks`, requirement
+     dispositions and `visual_review`. Validation establishes that the record is
+     consistent, not that the commands ran — say so if asked.
+   - Every file the manifest lists is tracked, and `git status --short` is empty before
+     and after the audit.
    - Run the repository's candidate-wide release gate directly (`npm test`, or the
      equivalent declared by the project) and report its actual output. Any failure
      blocks PASS. Confirm `git status --short` remains clean afterward.
 4. For judgment items (tickets genuinely S/M, history reads as a story), give your
    verdict AND one sentence of evidence — never a bare pass.
 5. Present a table: checklist item | pass/fail/skipped | evidence. Order by stage.
-6. End with a one-line verdict: "PASS — workflow artifacts complete" or
-   "FAIL — {n} items failed; fix via {command}". For each failure, name the command
+6. End with a one-line verdict naming the candidate: "PASS — candidate {sha}: workflow
+   artifacts complete" or "FAIL — candidate {sha}: {n} items failed; fix via {command}".
+   Fixes go through a new ticket, a new candidate and a new evaluation. For each failure, name the command
    file (`.claude/commands/*.md`) whose instructions should be tightened if the
    failure is a workflow bug rather than a run mistake.

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

@@ -11,11 +11,13 @@ start of a session. Read-only: change nothing.
 ## Steps
 
 1. Run `scripts/pincer-status.sh`. It reads the artifacts on disk (`.prd/`, `tickets/`,
-   `NOTES.md`) and prints the PRD state, every ticket with its state and clock-based
-   elapsed time, what is blocked, build time against any explicit user budget, any warnings (a ticket
-   marked done without a verification receipt), and the next command to run.
+   `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 evidence verdict for the evaluated
+   candidate, any warnings (each readiness problem once), and the next command to run.
 2. Report in three lines: where the workflow is, what is in progress or blocked, and the
    next command. Quote the `Next` line as-is.
 3. 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/hooks/hook-policy.cjs

@@ -86,18 +86,34 @@ function commandParts(command) {
     while (i < words.length && words[i].startsWith('-')) i++;
   }
   while (['command', 'builtin', 'exec'].includes(words[i])) i++;
-  const executable = words[i] ? path.basename(words[i]) : '';
+  // Transparent wrappers: the command they run is the one that matters.
+  while (['nice', 'nohup', 'time', 'timeout', 'xargs'].includes(words[i])) {
+    const wrapper = words[i++];
+    while (i < words.length && words[i].startsWith('-')) {
+      if (['-n', '-s', '-k', '--signal', '--kill-after', '-I', '-L', '-P', '-d', '-a'].includes(words[i])) i++;
+      i++;
+    }
+    if (wrapper === 'timeout' && /^[0-9]/.test(words[i] || '')) i++;
+  }
+  const executable = words[i] ? path.basename(words[i]).toLowerCase() : '';
   return { executable, args: words.slice(i + 1), words };
 }
 
+// Index of a shell's -c flag, including bundled forms such as -lc or -ec.
+function shellCommandFlag(args) {
+  return args.findIndex(arg => /^-[A-Za-z]*c[A-Za-z]*$/.test(arg));
+}
+
 function gitSubcommand(args) {
-  let i = 0;
+  let i = 0, cdir = '';
   while (i < args.length) {
-    if (['-C', '-c', '--git-dir', '--work-tree'].includes(args[i])) i += 2;
+    if (args[i] === '-C') { cdir = args[i + 1] || ''; i += 2; }
+    else if (args[i] === '-c' && /^alias\./.test(args[i + 1] || '')) return { name: 'alias', args: [], cdir };
+    else if (['-c', '--git-dir', '--work-tree'].includes(args[i])) i += 2;
     else if (args[i].startsWith('-')) i++;
-    else return { name: args[i], args: args.slice(i + 1) };
+    else return { name: args[i], args: args.slice(i + 1), cdir };
   }
-  return { name: '', args: [] };
+  return { name: '', args: [], cdir };
 }
 
 function dangerousReason(source, depth = 0) {
@@ -129,7 +145,7 @@ function dangerousReason(source, depth = 0) {
     if (executable === 'chmod' && args.some(arg => /^(0?777|a\+rwx)$/.test(arg)))
       return 'mass permission changes are not allowed.';
     if (['sh', 'bash', 'zsh'].includes(executable)) {
-      const c = args.indexOf('-c');
+      const c = shellCommandFlag(args);
       if (c !== -1 && typeof args[c + 1] === 'string') {
         const nested = dangerousReason(args[c + 1], depth + 1);
         if (nested) return nested;
@@ -223,11 +239,88 @@ function isExactPincerCall(source) {
   return action === 'bind' ? words.length === 4 : words.length === 3;
 }
 
-function ticketShellMutation(source) {
+// A pathspec is "wide" when, after normalisation, it cannot be shown to stay
+// outside tickets/: the whole tree, an absolute or unexpanded path, a glob at
+// the top level, or anything whose first segment is tickets. Exclude entries
+// never widen. `cdir` is a `git -C <dir>` prefix.
+function widePathspec(arg, cdir = '') {
+  if (/[$`]/.test(arg) || /[$`]/.test(cdir) || cdir.startsWith('/') || cdir.startsWith('~') || /^[A-Za-z]:[\\/]/.test(cdir)) return true;
+  let p = arg;
+  if (p.startsWith(':(')) {
+    const end = p.indexOf(')');
+    if (end < 0) return true;
+    const magic = p.slice(2, end).split(',').map(s => s.trim());
+    if (magic.includes('exclude')) return false;
+    p = p.slice(end + 1);
+    if (magic.includes('top')) cdir = '';
+  } else if (p.startsWith(':/')) { p = p.slice(2); cdir = ''; }
+  else if (p.startsWith(':!') || p.startsWith(':^')) return false;
+  else if (p.startsWith(':')) p = p.slice(1);
+  if (p.startsWith('/') || p.startsWith('~') || /^[A-Za-z]:[\\/]/.test(p)) return true;
+  if (cdir) p = `${cdir}/${p}`;
+  const segments = [];
+  for (const segment of p.split(/[\\/]+/)) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') { if (!segments.length) return true; segments.pop(); continue; }
+    segments.push(segment);
+  }
+  if (!segments.length) return true;
+  if (/[*?[{]/.test(segments[0])) return true;
+  return segments[0].toLowerCase() === 'tickets';
+}
+
+// Git forms that restore the working tree wholesale — and with it any ticket file
+// whose failed attempt would be erased and whose revoked receipt would come back.
+function wholeTreeRestore(sub) {
+  const { name, args, cdir } = sub;
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--') { positional.push(...args.slice(i + 1)); break; }
+    if (['-e', '--exclude', '--source', '-b', '-B', '--orphan', '-c', '-C', '--conflict'].includes(arg)) { i++; continue; }
+    if (arg.startsWith('-')) continue;
+    positional.push(arg);
+  }
+  const force = args.some(arg => arg === '--force' || arg === '--discard-changes' || /^-[A-Za-z]*f[A-Za-z]*$/.test(arg));
+  const fromFile = args.some(arg => arg === '--pathspec-from-file' || arg.startsWith('--pathspec-from-file='));
+  const patch = args.some(arg => arg === '-p' || arg === '--patch');
+  // `git checkout <ref>` / `git switch <ref>`: one positional, no `--`, no force flag is a branch switch,
+  // allowed even through a variable; every pathspec form keeps the wide test.
+  const branchSwitch = (name === 'checkout' || name === 'switch') && positional.length === 1 && !args.includes('--');
+  const wide = branchSwitch ? widePathspec(positional[0].replace(/[$`]/g, 'x'), cdir) : positional.some(p => widePathspec(p, cdir));
+  switch (name) {
+    case 'alias': return true;
+    case 'checkout': case 'switch': return force || fromFile || wide || (patch && positional.length === 0);
+    case 'restore': return fromFile || wide || positional.length === 0;
+    case 'reset': return args.some(arg => ['--hard', '--merge', '--keep'].includes(arg));
+    case 'stash':
+      if (args.some(arg => arg === '-h' || arg === '--help')) return false;
+      return !['list', 'show', 'create', 'store'].includes(positional[0] || '');
+    case 'clean': return force && (positional.length === 0 || wide);
+    case 'checkout-index': return args.some(arg => arg === '--all' || /^-[A-Za-z]*a/.test(arg));
+    case 'read-tree': return args.some(arg => arg === '--reset' || /^-[A-Za-z]*u/.test(arg));
+    default: return false;
+  }
+}
+
+function ticketShellMutation(source, depth = 0) {
+  if (depth > 2) return false;
   if (isExactPincerCall(source)) return false;
   const commands = shellCommands(source);
   for (const command of commands) {
     const { executable, args, words } = commandParts(command);
+    if (['sh', 'bash', 'zsh'].includes(executable)) {
+      const c = shellCommandFlag(args);
+      if (c !== -1 && typeof args[c + 1] === 'string' && ticketShellMutation(args[c + 1], depth + 1)) return true;
+    }
+    if (executable === 'eval' && ticketShellMutation(args.join(' '), depth + 1)) return true;
+    if (executable === 'git') {
+      const sub = gitSubcommand(args);
+      if (wholeTreeRestore(sub)) return true;
+      const viaXargs = command.words.some(word => path.basename(word).toLowerCase() === 'xargs');
+      const stdinPathspec = !sub.args.some(arg => !arg.startsWith('-')) || sub.args[sub.args.length - 1] === '--';
+      if (viaXargs && ['checkout', 'restore', 'clean'].includes(sub.name) && stdinPathspec) return true;
+    }
     const hasTicket = words.some(ticketPath) || /(^|[\s'"`])tickets[\\/]T-[0-9]+[^\s'"`]*/.test(source);
     if (!hasTicket) continue;
     if (command.operators.some(op => op === '>' || op === '>>')) return true;
@@ -251,7 +344,7 @@ if (mode === 'dangerous') {
   if (['Edit', 'Write', 'MultiEdit'].includes(payload.tool_name)) guardEdits(payload.tool_name, payload.tool_input);
   else if (payload.tool_name === 'Bash') {
     if (typeof payload.tool_input.command !== 'string') block('Bash payload must contain a string command.');
-    if (ticketShellMutation(payload.tool_input.command)) block('shell commands may not write or reset ticket files; use pincer-ticket.sh for lifecycle state.');
+    if (ticketShellMutation(payload.tool_input.command)) block('shell commands may not write, reset, or restore ticket files (including whole-tree checkout/restore, reset --hard, stash, clean -f); use pincer-ticket.sh for lifecycle state.');
   }
 } else {
   block('hook policy mode is invalid.');

package/template/.claude/references/prd-template.md

@@ -3,15 +3,31 @@
 Used by `/pincer-plan` Phase 4. Core sections are always included. Add optional detail
 when uncertainty, product context, or risk warrants it; a small fix may remain compact.
 
+## Profile
+
+The frontmatter field `profile: small | standard` sets the planning weight; a PRD
+without it is `standard`. `small` means bounded scope, low risk, known behavior and
+straightforward verification. Few changed lines alone do not qualify: migrations,
+authorization boundaries, uncertain requirements and broad effects stay `standard`
+even for a tiny patch. The PRD records in one or two sentences why the profile fits.
+
+A small PRD keeps Problem (with the outcome), Scope, Requirements with scenarios,
+Success Criteria (its verification), risks and exclusions, and omits empty sections
+and repetition. Interface examples may clarify a contract; implementation code must
+not substitute for requirements in any profile.
+
 ---
 
 ## Core Sections (always include)
 
 ### 1. Problem
-What problem does this solve? Who has it? (2–4 sentences.)
+What problem does this solve? Who has it? (2–4 sentences.) Preserve or link the
+original brief (quote it in an appendix or name where it lives) so the source of
+every requirement stays reviewable.
 
 ### 2. Solution
-One-paragraph summary of what we're building.
+One-paragraph summary of what we're building: the desired outcome, the assumptions
+it rests on, and what it deliberately excludes.
 
 ### 3. Scope
 
@@ -19,7 +35,22 @@ One-paragraph summary of what we're building.
 | --- | --- |
 | ... | ... |
 
-### 4. Architecture
+### 4. Requirements
+One entry per requirement with a stable ID. IDs are assigned once within this PRD
+and never renumbered: a revision keeps existing IDs and adds new ones. Tickets
+name the IDs they implement and evaluation dispositions every ID.
+
+#### R-01 — short title
+- Scenario: an observable acceptance scenario (given / when / then, or a command
+  and its expected output). Add one line per scenario.
+- Failure path: what invalid input or the relevant failure produces.
+- Preserve: existing behavior this must not change (brownfield).
+
+When the user supplied a PRD, keep its meaning and its existing requirement IDs.
+If its structure needs adapting to this template, add a `Requirement mapping`
+table under this section (`their section or ID → R-NN`) instead of rewriting it.
+
+### 5. Architecture
 
 #### Structure
 ```
@@ -32,13 +63,13 @@ What each component does, owns, and depends on.
 #### Data flow
 Input → processing → output.
 
-### 5. Success Criteria
+### 6. Success Criteria
 
 | Criterion | How to verify |
 | --- | --- |
 | ... | a command to run or a thing to observe |
 
-### 6. Out of Scope
+### 7. Out of Scope
 Explicit list. Anything cut for time during `/pincer-code` gets appended here with a reason.
 
 ---
@@ -62,7 +93,8 @@ Include when something outside our control or a migration/rollback concern could
 
 ## Formatting Rules
 
-- Save as `.prd/prd-v{N}.md` with YAML frontmatter (`version`, `status`, `date`).
+- Save as `.prd/prd-v{N}.md` with YAML frontmatter (`version`, `status`, `date`,
+  and `profile` when small).
 - Status lifecycle: `draft → ticketed → built`.
 - Diagrams as ASCII or markdown tables only.
 - No implementation code and no exact line numbers — those belong in tickets.

package/template/.claude/references/ticket-template.md

@@ -17,6 +17,8 @@ One sentence: what to build and why.
 ## Context
 - Relevant files: `src/path/to/file.ts` (what's there / what to follow)
 - PRD section: which part of the PRD this implements
+- Implements: R-01, R-03 (requirement IDs from the PRD; enabling work that
+  implements no requirement states its purpose in the Objective instead)
 
 ## Requirements
 - Concrete, checkable requirements. No vague "handle errors properly" —
@@ -27,6 +29,7 @@ One sentence: what to build and why.
 - [ ] Observable behavior 2
 
 ## Verification
+Proves: one line — what this check establishes and which regression it detects.
 ```bash
 # command(s) the builder runs to prove the criteria — tests, build, curl, etc.
 ```
@@ -57,6 +60,18 @@ Rules:
   requires that receipt to match the current block. Never write these by hand.
 - The Verification block is a fenced `bash` block that exits 0 only when the
   ticket is done — non-interactive, no "check by hand".
+- The Verification section opens with a one-line `Proves:` statement: what the
+  check establishes and which regression it detects. Executable changes need
+  checks that exercise observable behavior — including relevant rejection paths
+  and, in brownfield work, preservation of existing behavior. Reuse adequate
+  focused tests rather than inventing ad-hoc commands. A build, a syntax check, or
+  an identifier grep alone does not prove a feature works: the check must fail
+  when the behavior is wrong, not only when a name is renamed. Static assertions
+  may be primary evidence for static contracts (generated files, adapter wording)
+  when `Proves:` explains that fit.
+- Manual visual judgment is recorded separately during evaluation, never as the
+  Verification command. When a tool the check needs is unavailable, the result is
+  an explicit `unverified`, never fabricated output or a silent waiver.
 - Every ticket must be verifiable without human judgment where possible.
 - If the ticket's surface accepts external input (HTTP, form, file, LLM output),
   Requirements must state the validation and the rejection behavior, and