pincer-workflow 0.2.3 → 0.4.0

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

@@ -5,20 +5,34 @@ argument-hint: "Brief description of the task/feature (paste the full brief if y
 
 # /pincer-plan — PRD Creation
 
-You are turning a task brief into a compact PRD. This runs inside a short delivery
-timebox (~2 hours total), so discovery is brief and the PRD is lean. The PRD feeds
+You are turning a task brief into a reviewable PRD. Scale discovery and detail to
+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, say so and ask whether
-this is a new version of it (`.prd/prd-v{N+1}.md` — old versions are never overwritten)
-or a fresh start; if tickets are in progress, stop and point at `/pincer-code` instead.
+First run `scripts/pincer-status.sh`. If a PRD already exists, preserve it and select
+the next unused numeric version for this change. Use the brief and repository state to
+distinguish a revision from a new change; ask only if that distinction changes scope or
+architecture. If tickets for the current PRD are in progress, resume `/pincer-code`
+unless the user explicitly authorized a separate change.
 
-## Phase 1: Discovery (~5 min)
+## 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?
@@ -27,9 +41,10 @@ or a fresh start; if tickets are in progress, stop and point at `/pincer-code` i
 3. If the project has a frontend, ask one design question: "What should this feel like,
    and what should it NOT look like?" Capture the answer for the Visual Direction section.
 
-Summarize your understanding in 3–5 sentences and confirm before moving on.
+Summarize your understanding in 3–5 sentences. Existing authorization in the request or
+session carries forward; ask only about an unresolved choice that materially changes the result.
 
-## Phase 2: Codebase scan (conditional, ~5 min)
+## Phase 2: Codebase scan (conditional)
 
 If the repo already contains source code, launch 1–2 `codebase-explorer` agents in parallel
 (one for architecture/structure, one for patterns relevant to the feature). Read the 2–3 most
@@ -44,7 +59,7 @@ touches are load-bearing, what test coverage protects them (run the suite, don't
 and the blast radius + rollback story for the change. Record these in the PRD's
 Architecture section. Greenfield speed assumptions do not transfer to brownfield work.
 
-## Phase 3: Architecture (~5 min)
+## Phase 3: Architecture
 
 Propose the architecture: components, data flow, integration points, and key decisions.
 - Recommend one approach; mention an alternative only when the trade-off is real.
@@ -57,23 +72,45 @@ Propose the architecture: components, data flow, integration points, and key dec
 - Verify the contract of any external API the plan builds on (one live request or the
   current official docs) before designing around it — endpoint shapes remembered from
   training data are guesses.
-- Bias every decision toward "finishable in the remaining time". Cut before you gold-plate.
+- Respect any explicit delivery budget. Record deliberate cuts in Out of Scope.
 
-**Gate (heavy):** Ask for explicit approval of the architecture before writing the PRD.
+Prepare the full draft before seeking any approval still required. The user should review a
+concrete scope and architecture; do not repeat an approval already given for the same decision.
 
-## Phase 4: Write the PRD (~5 min)
+## Phase 4: Write the PRD
 
 1. Load `.claude/references/prd-template.md` and write all core sections.
-2. Include optional sections only when they earn their space in the timebox.
-3. Save to `.prd/prd-v1.md` (create `.prd/` if needed) with frontmatter:
+   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:
    ```yaml
    ---
-   version: 1
+   version: {N}
    status: draft
    date: {today}
+   profile: small   # only when small; omit for standard
    ---
    ```
-4. If `.git/` doesn't exist, run `git init` and make an initial commit containing the
-   PRD and this `.claude/` setup — planning should be visible in the history.
-
-Finish with: "PRD saved to `.prd/prd-v1.md`. Run `/pincer-narrow` to break it into work items."
+4. If `.git/` doesn't exist, run `git init`. Commit the PRD and only the intended setup
+   paths after inspecting existing staged work; planning should be visible in history
+   without absorbing unrelated brownfield changes.
+
+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

@@ -5,28 +5,47 @@ argument-hint: "Stage to check (optional: plan | narrow | code | evaluate — de
 
 # /pincer-release — Workflow Audit
 
-You are auditing the current repo state against `docs/dry-run-checklist.md`. Read-only:
-report pass/fail, never fix anything — fixes belong to the stage commands.
+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. 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
 
 ## Steps
 
-1. Read `docs/dry-run-checklist.md` — it is the source of truth for what to check.
-2. Run `scripts/pincer-status.sh` to determine which stages have run (it reads `.prd/`,
-   `tickets/`, `NOTES.md`; add `git log`). If `$ARGUMENTS` names a stage, check only up
+1. Read `docs/release-checklist.md` — it is the source of truth for product-candidate
+   readiness. `docs/dry-run-checklist.md` is a separate manual platform trial and must
+   not impose toy-project or Pincer-kit assumptions on this audit.
+2. Run `scripts/pincer-status.sh` to determine the selected PRD and which stages have run
+   (it reads `.prd/`, associated `tickets/`, `NOTES.md`; add `git log`). If `$ARGUMENTS`
+   names a stage, check only up
    to that stage.
 3. Check every applicable item mechanically where possible:
    - File existence and frontmatter: read the files.
    - Commit format and story: `git log --oneline`.
-   - Receipts: every done ticket carries `verified:` (a status warning means one was
-     marked done by hand). Re-run at least two checks with
-     `scripts/pincer-ticket.sh verify T-{NN}` — on a done ticket it re-checks without
-     touching the receipt — and report actual output.
+   - 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 the 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/block-dangerous.sh

@@ -1,20 +1,9 @@
 #!/bin/bash
-# PreToolUse guardrail for Bash commands. Blocks destructive or pipe-to-shell
-# patterns regardless of permission mode — these are never auto-approved; a
-# human runs them in their own terminal if truly intended.
-# Exit 2 blocks the tool call; stderr goes back to the agent.
-
-input=$(cat)
-
-if printf '%s' "$input" | grep -qE \
-  -e 'rm -rf?( -[a-z]+)* +(/|~|\$HOME)' \
-  -e 'git push[^|;&]*(--force|-f)( |$)' \
-  -e '(curl|wget)[^|;&]*\|[[:space:]]*(sudo )?(ba|z)?sh' \
-  -e 'chmod( -R)? +777' \
-  -e '--dangerously-skip-permissions' \
-  -e 'git reset --hard[^|;&]*origin/'; then
-  echo "Blocked by PINCER guardrail: destructive or pipe-to-shell command. If this is genuinely intended, the user runs it manually in their own terminal." >&2
+# PreToolUse guardrail for Bash commands. The Node helper parses the hook JSON
+# before inspecting the actual command and recognizes the documented command
+# forms without matching harmless strings elsewhere in the payload.
+command -v node >/dev/null 2>&1 || {
+  echo 'Blocked by PINCER guardrail: Node.js is required to parse hook input safely.' >&2
   exit 2
-fi
-
-exit 0
+}
+exec node "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/hook-policy.cjs" dangerous

package/template/.claude/hooks/hook-policy.cjs

@@ -0,0 +1,351 @@
+#!/usr/bin/env node
+const fs = require('node:fs');
+const path = require('node:path');
+
+const mode = process.argv[2];
+const input = fs.readFileSync(0, 'utf8');
+
+function block(message) {
+  const label = mode === 'ticket' ? 'ticket guard' : 'guardrail';
+  process.stderr.write(`Blocked by PINCER ${label}: ${message}\n`);
+  process.exit(2);
+}
+
+let payload;
+try {
+  payload = JSON.parse(input);
+} catch {
+  block('hook input is not valid JSON.');
+}
+if (!payload || typeof payload !== 'object' || Array.isArray(payload) ||
+    typeof payload.tool_name !== 'string' || !payload.tool_input ||
+    typeof payload.tool_input !== 'object' || Array.isArray(payload.tool_input)) {
+  block('hook input must contain tool_name and a tool_input object.');
+}
+
+function lexShell(source) {
+  const tokens = [];
+  let word = '';
+  let quote = '';
+  const push = () => { if (word) tokens.push({ value: word }); word = ''; };
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (quote) {
+      if (ch === quote) quote = '';
+      else if (ch === '\\' && quote === '"' && i + 1 < source.length) word += source[++i];
+      else word += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; continue; }
+    if (ch === '\\' && i + 1 < source.length) { word += source[++i]; continue; }
+    if (/\s/.test(ch)) {
+      push();
+      if (ch === '\n') tokens.push({ op: ';' });
+      continue;
+    }
+    if ('|;&><()'.includes(ch)) {
+      push();
+      const pair = source.slice(i, i + 2);
+      if (['||', '&&', '>>', '<<'].includes(pair)) { tokens.push({ op: pair }); i++; }
+      else tokens.push({ op: ch });
+      continue;
+    }
+    word += ch;
+  }
+  push();
+  return tokens;
+}
+
+function shellCommands(source) {
+  const commands = [];
+  let words = [];
+  let operators = [];
+  const finish = (separator = '') => {
+    if (words.length || operators.length) commands.push({ words, operators, separator });
+    words = []; operators = [];
+  };
+  for (const token of lexShell(source)) {
+    if (token.value !== undefined) words.push(token.value);
+    else if (['|', ';', '&&', '||', '(', ')'].includes(token.op)) finish(token.op);
+    else operators.push(token.op);
+  }
+  finish();
+  return commands;
+}
+
+function commandParts(command) {
+  const words = [...command.words];
+  let i = 0;
+  while (i < words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i])) i++;
+  if (words[i] === 'env') {
+    i++;
+    while (i < words.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[i]) || words[i].startsWith('-'))) i++;
+  }
+  if (words[i] === 'sudo') {
+    i++;
+    while (i < words.length && words[i].startsWith('-')) i++;
+  }
+  while (['command', 'builtin', 'exec'].includes(words[i])) 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, cdir = '';
+  while (i < args.length) {
+    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), cdir };
+  }
+  return { name: '', args: [], cdir };
+}
+
+function dangerousReason(source, depth = 0) {
+  if (depth > 2) return '';
+  const commands = shellCommands(source);
+  for (let i = 0; i < commands.length; i++) {
+    const { executable, args, words } = commandParts(commands[i]);
+    if ((executable === 'claude' || (executable === 'npx' && args.some(arg => arg === 'claude'))) &&
+        words.includes('--dangerously-skip-permissions')) return 'permission bypass flags are not allowed.';
+    if (executable === 'git') {
+      const sub = gitSubcommand(args);
+      if (sub.name === 'push' && sub.args.some(arg => arg === '-f' || arg === '--force' || arg.startsWith('--force=')))
+        return 'force-push commands are not allowed.';
+      if (sub.name === 'reset' && sub.args.includes('--hard') && sub.args.some(arg => /^origin\//.test(arg)))
+        return 'hard resets to a remote branch are not allowed.';
+    }
+    if (executable === 'rm') {
+      let recursive = false, force = false;
+      const targets = [];
+      for (const arg of args) {
+        if (arg === '--recursive') recursive = true;
+        else if (arg === '--force') force = true;
+        else if (/^-[^-]/.test(arg)) { recursive ||= /[rR]/.test(arg.slice(1)); force ||= /f/.test(arg.slice(1)); }
+        else if (arg !== '--') targets.push(arg);
+      }
+      if (recursive && force && targets.some(arg => arg.startsWith('/') || arg === '~' || arg.startsWith('~/') || arg === '$HOME' || arg.startsWith('$HOME/') || arg.startsWith('${HOME}')))
+        return 'recursive forced deletion of an absolute or home path is not allowed.';
+    }
+    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 = shellCommandFlag(args);
+      if (c !== -1 && typeof args[c + 1] === 'string') {
+        const nested = dangerousReason(args[c + 1], depth + 1);
+        if (nested) return nested;
+      }
+    }
+    if (['curl', 'wget'].includes(executable) && commands[i].separator === '|') {
+      const next = commandParts(commands[i + 1] || { words: [] }).executable;
+      if (['sh', 'bash', 'zsh'].includes(next)) return 'downloading content directly into a shell is not allowed.';
+    }
+  }
+  return '';
+}
+
+const TICKET_PATH = /(^|[\\/])tickets[\\/]T-[0-9]+[^\\/]*\.md$/;
+const PROTECTED = ['status', 'started', 'last_check', 'verified', 'finished'];
+
+function ticketPath(value) {
+  return typeof value === 'string' && TICKET_PATH.test(value);
+}
+
+function stateFields(content) {
+  const result = Object.fromEntries(PROTECTED.map(key => [key, []]));
+  let scope = String(content ?? '');
+  if (scope.startsWith('---\n')) {
+    const end = scope.indexOf('\n---', 4);
+    if (end !== -1) scope = scope.slice(4, end + 1);
+  }
+  for (const line of scope.split(/\r?\n/)) {
+    const match = line.match(/^([a-z_]+):[ \t]*(.*)$/);
+    if (match && PROTECTED.includes(match[1])) result[match[1]].push(match[2]);
+  }
+  return result;
+}
+
+const sameState = (a, b) => JSON.stringify(stateFields(a)) === JSON.stringify(stateFields(b));
+
+function absoluteToolPath(file) {
+  const root = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return path.isAbsolute(file) ? file : path.resolve(root, file);
+}
+
+function existingContent(file) {
+  try { return fs.readFileSync(absoluteToolPath(file), 'utf8'); }
+  catch { return null; }
+}
+
+function applyEdit(content, oldText, newText, replaceAll = false) {
+  if (typeof oldText !== 'string' || typeof newText !== 'string') block('edit payload must contain string old_string and new_string values.');
+  if (!oldText) block('edit old_string must not be empty.');
+  if (replaceAll) return content.split(oldText).join(newText);
+  const index = content.indexOf(oldText);
+  return index === -1 ? content : content.slice(0, index) + newText + content.slice(index + oldText.length);
+}
+
+function guardEdits(tool, toolInput) {
+  const file = toolInput.file_path;
+  if (typeof file !== 'string') block(`${tool} payload must contain a string file_path.`);
+  if (!ticketPath(file)) return;
+  const before = existingContent(file);
+  if (tool === 'Write') {
+    if (typeof toolInput.content !== 'string') block('Write payload must contain string content.');
+    if (before !== null) {
+      if (!sameState(before, toolInput.content)) block('ticket lifecycle fields may only be changed by pincer-ticket.sh.');
+    } else {
+      const state = stateFields(toolInput.content);
+      if (state.status.length !== 1 || state.status[0].split(/[ \t]+#/)[0].trim() !== 'open' ||
+          PROTECTED.slice(1).some(key => state[key].length))
+        block('new tickets must start with status: open and no lifecycle receipts or timestamps.');
+    }
+    return;
+  }
+  const edits = tool === 'MultiEdit' ? toolInput.edits : [toolInput];
+  if (!Array.isArray(edits)) block('MultiEdit payload must contain an edits array.');
+  let after = before ?? '';
+  for (const edit of edits) {
+    if (!edit || typeof edit !== 'object') block('each edit must be an object.');
+    after = applyEdit(after, edit.old_string, edit.new_string, edit.replace_all === true);
+  }
+  if (!sameState(before ?? '', after)) block('ticket lifecycle fields may only be changed by pincer-ticket.sh.');
+}
+
+function isExactPincerCall(source) {
+  const commands = shellCommands(source).filter(command => command.words.length);
+  if (commands.length !== 1 || commands[0].separator) return false;
+  const { executable, args } = commandParts(commands[0]);
+  let words = [executable, ...args];
+  if (['bash', 'sh'].includes(words[0])) words = words.slice(1);
+  if (!/pincer-ticket\.sh$/.test(words[0] || '')) return false;
+  const action = words[1];
+  if (!['start', 'verify', 'done', 'bind'].includes(action)) return false;
+  return action === 'bind' ? words.length === 4 : words.length === 3;
+}
+
+// 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;
+    if (['rm', 'mv', 'cp', 'install', 'truncate', 'touch', 'tee', 'ed', 'ex'].includes(executable)) return true;
+    if (['python', 'python3', 'node', 'ruby'].includes(executable)) return true;
+    if (['sed', 'perl'].includes(executable) && args.some(arg => /^-[^-]*i/.test(arg) || arg === '--in-place' || arg.startsWith('--in-place='))) return true;
+    if (executable === 'git') {
+      const sub = gitSubcommand(args).name;
+      if (['checkout', 'restore', 'reset', 'clean'].includes(sub)) return true;
+    }
+  }
+  return false;
+}
+
+if (mode === 'dangerous') {
+  if (payload.tool_name !== 'Bash') process.exit(0);
+  if (typeof payload.tool_input.command !== 'string') block('Bash payload must contain a string command.');
+  const reason = dangerousReason(payload.tool_input.command);
+  if (reason) block(reason);
+} else if (mode === 'ticket') {
+  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, 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.');
+}