pincer-workflow 1.0.1 → 1.0.2

package/README.md

@@ -16,7 +16,7 @@ Install it in your project:
 npx pincer-workflow@latest init --platform all
 ```
 
-The same package is also attached to the [GitHub release](https://github.com/orchestratedbyalex/pincer-workflow/releases/tag/v1.0.1).
+The same package is also attached to the [GitHub release](https://github.com/orchestratedbyalex/pincer-workflow/releases/tag/v1.0.2).
 
 Node.js 22+, git and bash are required. PINCER uses your coding tool's own
 authentication; it does not require a provider API key.
@@ -140,23 +140,41 @@ each installed platform will run.
 ## Update
 
 ```bash
-npx pincer-workflow@latest update   # edited files get a .new sidecar
-npx pincer-workflow@latest doctor   # checks the install and agreement
+npx pincer-workflow@latest update                      # edited files get a .new sidecar
+npx pincer-workflow@latest update --platform claude    # the same, and add a platform to the install
+npx pincer-workflow@latest doctor                      # checks the install and agreement
 ```
 
 With an agreement in place, `update` also refreshes the library and regenerates the
 project copies you did not edit; an edited copy stays and gets the new version beside
 it as `<file>.new`.
 
+`update --platform <claude|codex|copilot|all>` adds a platform to an existing install,
+for example Claude Code to a project that started on Codex. The platforms already
+installed stay, the agreement and the tickets are shared, a file the project already
+had (its own `CLAUDE.md`) is kept with the kit's version beside it as `.new`, and the
+stage copies are generated for the new platform. `init` refuses a second install and
+points here.
+
+`doctor` compares every installed file with the package that runs it, not only the
+version number. A file you changed is listed as locally edited. A file that is still
+what was installed but differs from this package came from another build with the
+same version number (a pre-release, a local `npm pack`); `doctor` fails and names
+it, and `update` brings the install to this build.
+
 ## Trying it locally before release
 
 ```bash
-npm pack                                           # in this repository: pincer-workflow-1.0.1.tgz
-cp pincer-workflow-1.0.1.tgz ../some-project/ && cd ../some-project
-npx ./pincer-workflow-1.0.1.tgz init --platform all   # the ./ matters: npx treats a bare path as a command
+npm pack                                           # in this repository: pincer-workflow-1.0.2.tgz
+cp pincer-workflow-1.0.2.tgz ../some-project/ && cd ../some-project
+npx ./pincer-workflow-1.0.2.tgz init --platform all   # the ./ matters: npx treats a bare path as a command
 scripts/pincer-status.sh                           # prints "no agreement yet" and "Next: /pincer-blueprint"
 ```
 
+Use a project outside this repository. Claude Code loads every `CLAUDE.md` above the
+working directory, so a trial project nested in this checkout also gets the kit's
+developer instructions and does not behave like a real install.
+
 ## Status of the older channels
 
 - The Claude Code plugin channel is paused; the kit installs with `npx` on every platform.

package/bin/pincer.js

@@ -4,7 +4,8 @@
 //
 //   npx pincer-workflow init      install the kit into the current repo (asks which platforms)
 //   npx pincer-workflow update    refresh an install, preserving local edits; regenerate the project copies
-//   npx pincer-workflow doctor    check the health of an install
+//   npx pincer-workflow update --platform <name>   the same, and add a platform to the install
+//   npx pincer-workflow doctor    check the health of an install, file by file against this package
 //
 // No dependencies by design. The kit is markdown plus a small Node core; this tool
 // copies it carefully and never overwrites a file you edited: you get a *.new file
@@ -229,11 +230,15 @@ function regenerate(dir) {
   console.log(`  generated: ${result.written.length} written, ${result.skipped.length} unchanged, ${result.conflicted.length} kept, ${result.removed.length} removed`);
 }
 
+// How each platform starts a stage; `stage` is blueprint on a new install and status on one that grew.
+function platformSteps(platforms, stage) {
+  if (platforms.includes('claude')) console.log(`  Claude Code   start \`claude\` in this repo and run /pincer-${stage}`);
+  if (platforms.includes('codex')) console.log(`  Codex CLI     start \`codex\` in this repo and type $pincer-${stage}  (skills load from .agents/skills/; posture notes in .codex/README.md)`);
+  if (platforms.includes('copilot')) console.log(`  Copilot       enable "chat.promptFiles": true in VS Code settings, then /pincer-${stage} in chat`);
+}
 function nextSteps(platforms) {
   console.log('\nNext: run the blueprint. It looks at the repository, interviews you, and writes the agreement (harness.json and the top of AGENTS.md).');
-  if (platforms.includes('claude')) console.log('  Claude Code   start `claude` in this repo and run /pincer-blueprint');
-  if (platforms.includes('codex')) console.log('  Codex CLI     start `codex` in this repo and type $pincer-blueprint  (skills load from .agents/skills/; posture notes in .codex/README.md)');
-  if (platforms.includes('copilot')) console.log('  Copilot       enable "chat.promptFiles": true in VS Code settings, then /pincer-blueprint in chat');
+  platformSteps(platforms, 'blueprint');
   console.log('  Any session   scripts/pincer-status.sh shows where the work stands and the next command');
 }
 
@@ -259,24 +264,33 @@ function parsePlatformFlag(args) {
 
 async function cmdInit(args) {
   const dir = process.cwd();
-  if (readManifest(dir)) fail(`this repo already has PINCER installed (${MANIFEST} exists) — use \`pincer update\`.`);
+  if (readManifest(dir)) fail(`this repo already has PINCER installed (${MANIFEST} exists) — use \`pincer update\`, or \`pincer update --platform <name>\` to add a platform.`);
   const platforms = parsePlatformFlag(args) || (process.stdin.isTTY ? await askPlatforms() : [...PLATFORMS]);
   console.log(`\nInstalling PINCER v${VERSION} for: ${platforms.join(', ')}\n`);
   report(install(dir, platforms, null, {}));
   nextSteps(platforms);
 }
 
-async function cmdUpdate() {
+// `--platform` adds to the install: the platforms already there stay, the named ones
+// that are new get their files the way init would write them, and an existing file
+// of theirs (a CLAUDE.md the project already had) is kept with a .new beside it.
+async function cmdUpdate(args = []) {
   const dir = process.cwd();
   const manifest = readManifest(dir);
   if (!manifest) fail(`no ${MANIFEST} here — run \`pincer init\` first.`);
-  console.log(`\nUpdating PINCER ${manifest.version} -> ${VERSION} for: ${manifest.platforms.join(', ')}\n`);
+  const added = (parsePlatformFlag(args) || []).filter((p) => !manifest.platforms.includes(p));
+  const platforms = [...manifest.platforms, ...added];
+  console.log(`\nUpdating PINCER ${manifest.version} -> ${VERSION} for: ${platforms.join(', ')}${added.length ? ` (adding: ${added.join(', ')})` : ''}\n`);
   // A manifest without a schema could have adopted a local edit as its baseline;
   // there is no safe way to tell those from upstream files after the fact.
   const baseline = TRUSTED_SCHEMAS.includes(manifest.schema) ? manifest.files : null;
   if (!baseline) console.log('  Legacy baselines are untrusted; differing files will be preserved for review.');
-  report(install(dir, manifest.platforms, baseline, manifest.generated));
+  report(install(dir, platforms, baseline, manifest.generated));
   regenerate(dir);
+  if (added.length) {
+    console.log(`\nAdded ${added.join(', ')}. The agreement and the tickets are shared; start there with the status stage:`);
+    platformSteps(added, 'status');
+  }
 }
 
 function cmdDoctor() {
@@ -302,6 +316,30 @@ function cmdDoctor() {
   const stale = fs.existsSync(TEMPLATE) && manifest.version !== VERSION;
   check(!stale, `install is current (v${manifest.version})`, 'run: pincer update');
 
+  // The version label is not proof: a pre-release or a local build can carry the same
+  // number. Every installed file is compared with this package's copy. One that differs
+  // and was changed since it was installed is a local edit; one that still is what was
+  // installed came from another build. With an older label the line above says it all.
+  const shipped = fs.existsSync(TEMPLATE) ? new Set(filesFor(manifest.platforms)) : new Set();
+  const edited = [];
+  const foreign = [];
+  for (const [rel, installed] of Object.entries(manifest.files)) {
+    const p = path.join(dir, rel);
+    if (!fs.existsSync(p)) continue;
+    const current = sha(fs.readFileSync(p));
+    if (shipped.has(rel) && current === sha(fs.readFileSync(path.join(TEMPLATE, rel)))) continue;
+    if (current !== installed) edited.push(rel);
+    else foreign.push(rel);
+  }
+  const absent = [...shipped].filter((rel) => !(rel in manifest.files));
+  if (fs.existsSync(TEMPLATE) && !stale) {
+    const differences = [
+      foreign.length ? `from another build labelled v${manifest.version}: ${foreign.join(', ')}` : '',
+      absent.length ? `not installed: ${absent.join(', ')}` : '',
+    ].filter(Boolean).join('; ');
+    check(!differences, `installed files match this package (v${VERSION})`, `${differences} — run: pincer update`);
+  }
+
   // The agreement, checked with the engine this install carries.
   if (!fs.existsSync(path.join(dir, 'harness.json'))) {
     console.log('  note  no harness.json yet — run /pincer-blueprint');
@@ -318,9 +356,6 @@ function cmdDoctor() {
 
   const obsolete = OBSOLETE.filter((rel) => fs.existsSync(path.join(dir, rel)) && !(rel in manifest.files) && !(rel in generated));
   if (obsolete.length) console.log(`  note  obsolete kit file(s) from an earlier version, safe to delete: ${obsolete.join(', ')}`);
-  const edited = Object.entries(manifest.files)
-    .filter(([rel, h]) => fs.existsSync(path.join(dir, rel)) && sha(fs.readFileSync(path.join(dir, rel))) !== h)
-    .map(([rel]) => rel);
   if (edited.length) console.log(`  note  locally edited (kept as-is on update): ${edited.join(', ')}`);
 
   const leftovers = [...new Set([...walk(TEMPLATE), ...Object.keys(manifest.files), ...Object.keys(generated)])].flatMap((rel) => {
@@ -339,7 +374,7 @@ function usage() {
 
 Usage:
   npx pincer-workflow init [--platform claude|codex|copilot|all]
-  npx pincer-workflow update
+  npx pincer-workflow update [--platform claude|codex|copilot|all]   (--platform adds a platform)
   npx pincer-workflow doctor
 
 After init, run the blueprint (/pincer-blueprint or $pincer-blueprint): it writes the
@@ -351,7 +386,7 @@ const invoked = process.argv[1] && (() => { try { return fs.realpathSync(process
 if (invoked) {
   const [cmd, ...rest] = process.argv.slice(2);
   if (cmd === 'init') await cmdInit(rest);
-  else if (cmd === 'update') await cmdUpdate();
+  else if (cmd === 'update') await cmdUpdate(rest);
   else if (cmd === 'doctor') cmdDoctor();
   else { usage(); process.exit(cmd ? 1 : 0); }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pincer-workflow",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "PINCER — a harness builder for AI coding agents. It looks at your project, interviews you, writes the project agreement, and runs the pipeline that agreement describes. Claude Code, Codex CLI and GitHub Copilot.",
   "bin": {
     "pincer": "bin/pincer.js"

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

@@ -44,6 +44,10 @@ function lexShell(source) {
       continue;
     }
     if ('|;&><()'.includes(ch)) {
+      // A number glued to a redirect (2>, 1>>, 0<) is its file descriptor, not an argument.
+      // The number after `>&` is that redirect's target, even with another redirect glued on.
+      const dupTarget = tokens.length > 1 && tokens[tokens.length - 1].op === '&' && tokens[tokens.length - 2].op === '>';
+      if ((ch === '>' || ch === '<') && /^[0-9]+$/.test(word) && !dupTarget) word = '';
       push();
       const pair = source.slice(i, i + 2);
       if (['||', '&&', '>>', '<<'].includes(pair)) { tokens.push({ op: pair }); i++; }
@@ -56,18 +60,42 @@ function lexShell(source) {
   return tokens;
 }
 
+// Where an output redirect can never write a file: the sinks every shell has.
+const SINKS = ['/dev/null', '/dev/stdout', '/dev/stderr', '/dev/tty'];
+
+// Each command's words, its operators and the targets of its output redirects.
+// `redirects` holds one entry per `>`, `>>`, `>|`, `&>` or `>&file`: the target
+// word, or null when none follows. Duplicating or closing a file descriptor
+// (`2>&1`, `>&2`, `2>&-`) and writing to a sink open no file, so they are left
+// out of `redirects` and their target is not an argument of the command either.
 function shellCommands(source) {
+  const tokens = lexShell(source);
   const commands = [];
   let words = [];
   let operators = [];
+  let redirects = [];
   const finish = (separator = '') => {
-    if (words.length || operators.length) commands.push({ words, operators, separator });
-    words = []; operators = [];
+    if (words.length || operators.length) commands.push({ words, operators, redirects, separator });
+    words = []; operators = []; redirects = [];
   };
-  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);
+  const word = (index) => (tokens[index] && tokens[index].value !== undefined ? tokens[index].value : null);
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.value !== undefined) { words.push(token.value); continue; }
+    if (token.op !== '>' && token.op !== '>>') {
+      if (['|', ';', '&&', '||', '(', ')'].includes(token.op)) finish(token.op);
+      else operators.push(token.op);
+      continue;
+    }
+    operators.push(token.op);
+    let at = i + 1;
+    const amp = token.op === '>' && tokens[at] && tokens[at].op === '&';
+    const clobber = token.op === '>' && !amp && tokens[at] && tokens[at].op === '|';
+    if (amp || clobber) at++;
+    const target = word(at);
+    if (target !== null && ((amp && /^([0-9]+-?|-)$/.test(target)) || SINKS.includes(target))) { i = at; continue; }
+    redirects.push(target);
+    if (clobber) i++; // `>|` is one operator, not a pipe: its target stays with this command
   }
   finish();
   return commands;
@@ -177,6 +205,8 @@ function ticketPath(value) {
 const ENGINE_FILES = ['scripts/pincer-ticket.sh', 'scripts/pincer-status.sh', 'scripts/pincer-blueprint.cjs', 'scripts/pincer-evidence.cjs', 'scripts/sync-prompts.sh', '.claude/settings.json'];
 const ENGINE_DIRS = ['scripts/pincer', '.claude/hooks'];
 const ENGINE_WORD = /(^|[\\/\s'"`=(])(\.\/)?(scripts[\\/]pincer([\\/]|$)|scripts[\\/](pincer-ticket\.sh|pincer-status\.sh|pincer-blueprint\.cjs|pincer-evidence\.cjs|sync-prompts\.sh)|\.claude[\\/]hooks([\\/]|$)|\.claude[\\/]settings\.json)/;
+// A redirect target that names a ticket, however the path is spelled.
+const TICKET_TARGET = /(^|[\\/])tickets[\\/]+T-[0-9]+/i;
 const ENGINE_MESSAGE = 'the engine (scripts/pincer-*.sh, scripts/pincer-*.cjs, scripts/pincer/) and the hooks (.claude/hooks/, .claude/settings.json) are installed by pincer-workflow and never edited by an agent; refresh them with `npx pincer-workflow update`.';
 
 function projectRoot() {
@@ -262,16 +292,39 @@ function guardEdits(tool, toolInput) {
   if (!sameState(before ?? '', after)) block('ticket lifecycle fields may only be changed by pincer-ticket.sh.');
 }
 
+// What an output redirect can reach: 'protected' (a ticket, the engine or the
+// hooks), 'other' (a literal path that is none of those) or 'unknown'. A target
+// is unknown when it cannot be resolved here: none was written, the shell
+// computes it ($VAR, a substitution, a glob, ~), or the same command line
+// changes directory or links a file first (`moved`), so a relative or aliased
+// path may land anywhere. Unknown targets are judged as every redirect used to be.
+// A relative target is resolved from the project root and from where the shell
+// stands (the payload's cwd, which an earlier `cd` may have moved).
+function redirectReach(target, moved) {
+  if (target === null) return 'unknown';
+  if (ENGINE_WORD.test(target) || TICKET_TARGET.test(target)) return 'protected';
+  if (moved || /[$`*?[\]{}~!]/.test(target)) return 'unknown';
+  const bases = [projectRoot(), process.cwd(), typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : projectRoot()];
+  const spellings = [...new Set(bases.map(base => path.resolve(base, target)))];
+  for (const file of [...spellings]) {
+    try { spellings.push(fs.realpathSync(file)); } catch { /* not there yet: nothing to follow */ }
+  }
+  if (spellings.some(file => enginePath(file) || ENGINE_WORD.test(file) || TICKET_TARGET.test(file))) return 'protected';
+  // A bare T-NN name is a ticket wherever the shell happens to stand.
+  if (!path.isAbsolute(target) && /^T-[0-9]+/i.test(path.basename(target))) return 'unknown';
+  return 'other';
+}
+
 // The one shell writer of lifecycle fields: `pincer-ticket.sh <start|verify|done> T-NN`
 // (three words) or `pincer-ticket.sh accept T-NN ...`, directly or through
 // `node scripts/pincer/cli.cjs ticket ...`, alone on its line.
 function isExactPincerCall(source) {
   const commands = shellCommands(source).filter(command => command.words.length);
   if (commands.length !== 1 || commands[0].separator) return false;
-  // An output redirection is a write, whatever runs in front of it: fall through to
-  // ticketShellMutation so its target is tested like any other path. Without this,
-  // adding a verb to the list below silently opened a new carrier for it.
-  if (commands[0].operators.some(op => op === '>' || op === '>>')) return false;
+  // An output redirection to a file is a write, whatever runs in front of it: fall
+  // through to ticketShellMutation so its target is tested like any other path. Without
+  // this, adding a verb to the list below silently opened a new carrier for it.
+  if (commands[0].redirects.length) return false;
   const { executable, args, words: raw } = commandParts(commands[0]);
   let words = [raw[raw.length - args.length - 1], ...args];
   if (['bash', 'sh', 'node'].includes(executable)) words = words.slice(1);
@@ -353,8 +406,13 @@ function ticketShellMutation(source, depth = 0) {
   if (depth > 2) return false;
   if (isExactPincerCall(source)) return false;
   const commands = shellCommands(source);
+  const moved = commands.some(command => ['cd', 'pushd', 'popd', 'ln'].includes(commandParts(command).executable));
   for (const command of commands) {
     const { executable, args, words } = commandParts(command);
+    // A redirect onto a ticket, the engine or the hooks is a write whatever the command is.
+    const reach = command.redirects.map(target => redirectReach(target, moved));
+    if (reach.includes('protected')) return true;
+    const blindWrite = reach.includes('unknown');
     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;
@@ -369,17 +427,18 @@ function ticketShellMutation(source, depth = 0) {
     }
     // A lookalike of the writer anywhere but the project's own path is refused outright.
     if (words.some(lookalikeWriter)) return true;
-    // Writes to the engine or the hooks: a redirect, or a file-writing executable, with
-    // an engine path among the arguments (the script a shell or node runs does not count).
+    // Writes to the engine or the hooks: a redirect whose target cannot be resolved, or a
+    // file-writing executable, with an engine path among the arguments (the script a shell
+    // or node runs does not count).
     const scriptArgs = ['node', 'bash', 'sh', 'zsh'].includes(executable) ? 1 : 0;
     if (args.slice(scriptArgs).some(arg => ENGINE_WORD.test(arg))) {
-      if (command.operators.some(op => op === '>' || op === '>>')) return true;
+      if (blindWrite) return true;
       if (['rm', 'mv', 'cp', 'install', 'truncate', 'tee', 'ed', 'ex', 'python', 'python3', '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;
     }
     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 (blindWrite) 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;

package/template/docs/engine.md

@@ -101,10 +101,9 @@ agreement, stage off or invalid `harness.json`, 130 interrupted.
 - `done T-NN`: `in_progress` to `done` when the receipt matches the current block, no newer check failed, and every criterion is ticked; stamps `finished`.
 - `accept T-NN --by "<name>" --words "<their words>"`: on a done ticket writes the three acceptance fields together; refuses a name that is not an acceptor and empty words.
 
-`scripts/pincer-status.sh` runs `node scripts/pincer/cli.cjs status`: the report, or
-`--json` for data. `--stage <name>` prints `on` and exits 0, or the reason and exits 3;
-a name that is not a stage exits 2. An invalid `harness.json` still renders the report
-and then exits 3.
+`scripts/pincer-status.sh` runs `node scripts/pincer/cli.cjs status`:
+- The report, or `--json` for data. `--stage <name>` prints `on` and exits 0, or the reason and exits 3; a name that is not a stage exits 2. An invalid `harness.json` still renders the report and then exits 3.
+- `Next:` is the first rule that matches, judged on the change in hand and not on the project's history: verify a ticket in progress, code an open one, wait for a draft spec's approval, narrow an approved spec that no ticket names in its `spec:` field, then evaluate, then release. With `stages.evaluate.evidence` on, evaluate stays next until one manifest covers every done ticket not yet accepted: the ticket file at the manifest's `candidate` commit is done with the receipt it carries now. `--json` lists the others under `unevaluated`; outside a git repository any manifest counts.
 
 `scripts/pincer-evidence.cjs` runs `node scripts/pincer/cli.cjs evidence`:
 `validate <manifest> [--candidate <sha>]` prints `ok <candidate>` or one
@@ -243,7 +242,7 @@ subagent env vars, Copilot org policy and Codex project trust override any file.
 
 ## Platform notes
 
-- Claude Code: `.claude/settings.json` wires two PreToolUse hooks. `block-dangerous.sh` refuses destructive commands. `ticket-guard.sh` refuses edits to the eight lifecycle fields and any shell command that writes, resets or restores a ticket file, allowing only exact calls of the project's own `scripts/pincer-ticket.sh start|verify|done|accept` and the `cli.cjs ticket` form at the same path; a lookalike script elsewhere is refused. It also refuses edits and shell writes to the engine (`scripts/pincer-*`, `scripts/pincer/`) and to the hooks (`.claude/hooks/`, `.claude/settings.json`), which `npx pincer-workflow update` refreshes. The guard matches `T-NN-*.md` under any directory named `tickets`; a `homes.tickets` that does not end in `tickets` loses hook coverage, and the rule in `AGENTS.md` carries the weight alone. The hook does not read `harness.json`. It is a guardrail against documented mistake forms, not a security boundary: the sandbox and the approval controls remain that boundary.
+- Claude Code: `.claude/settings.json` wires two PreToolUse hooks. `block-dangerous.sh` refuses destructive commands. `ticket-guard.sh` refuses edits to the eight lifecycle fields and any shell command that writes, resets or restores a ticket file, allowing only exact calls of the project's own `scripts/pincer-ticket.sh start|verify|done|accept` and the `cli.cjs ticket` form at the same path; a lookalike script elsewhere is refused. It also refuses edits and shell writes to the engine (`scripts/pincer-*`, `scripts/pincer/`) and to the hooks (`.claude/hooks/`, `.claude/settings.json`), which `npx pincer-workflow update` refreshes. A redirect counts as a write by its target: onto a ticket, the engine or the hooks it is refused whatever the command; duplicating a file descriptor (`2>&1`, `>&2`), discarding output (`2>/dev/null`) and saving a read to another literal path are reads and pass; a target the shell computes (a variable, a glob, a path after `cd`) is refused when the command names a protected file. The guard matches `T-NN-*.md` under any directory named `tickets`; a `homes.tickets` that does not end in `tickets` loses hook coverage, and the rule in `AGENTS.md` carries the weight alone. The hook does not read `harness.json`. It is a guardrail against documented mistake forms, not a security boundary: the sandbox and the approval controls remain that boundary.
 - Codex: reads `AGENTS.md` natively; the stages are skills under `.agents/skills/`, invoked as `$pincer-<stage>`; the roster agents are `.codex/agents/<name>.toml`, generated from the library, and Codex loads `.codex/` only in a project marked trusted. No hook. Posture in `~/.codex/config.toml`: `approval_policy = "on-request"` and `sandbox_mode = "workspace-write"`; never run with approvals disabled. Status warns about missing, failed or stale receipts and about hand-edited fields.
 - Copilot: `.github/copilot-instructions.md` points at `AGENTS.md`; the stages are prompt files under `.github/prompts/`, invoked as `/pincer-<stage>` with prompt files enabled; the roster agents are the files under `.claude/agents/`, which VS Code reads in the Claude format. No hook; the same rule.
 - Everywhere: Node 22 or newer, git and bash. `gh` only for the forge-facing steps the skills name. The engine runs offline.

package/template/scripts/pincer/status.cjs

@@ -8,6 +8,7 @@ const parse = require('./parse.cjs');
 const harnessModule = require('./harness.cjs');
 const models = require('./models.cjs');
 const generate = require('./generate.cjs');
+const util = require('./util.cjs');
 
 const SCRIPT = 'scripts/pincer-ticket.sh';
 const { STAGES, ALWAYS_ON, HARNESS_FILE } = harnessModule;
@@ -54,11 +55,12 @@ function specEntries(root, specsDir) {
 }
 function ticketEntry(root, file) {
   const text = readText(root, file);
-  const entry = { id: idOf(file), file, status: null, started: null, verified: null, lastCheck: null, accepted: null, acceptedBy: null, ready: false, problem: null, depends: [] };
+  const entry = { id: idOf(file), file, status: null, spec: null, started: null, verified: null, lastCheck: null, accepted: null, acceptedBy: null, ready: false, problem: null, depends: [] };
   if (text === null) { entry.problem = 'cannot read the file'; return entry; }
   const v = parse.validateTicket(file, text);
   const fields = v.fields;
   entry.status = fields.status || null;
+  entry.spec = fields.spec || null;
   entry.started = fields.started || null;
   entry.verified = fields.verified || null;
   entry.lastCheck = fields.last_check || null;
@@ -80,10 +82,44 @@ function manifests(root, evidenceDir) {
     .filter((file) => fs.existsSync(path.join(root, file)));
 }
 
+// The done tickets still awaiting acceptance that no saved evidence covers. A
+// manifest covers a ticket when the ticket file at the manifest's candidate
+// commit is done with the receipt the ticket carries now: the candidate holds
+// that finished work, and nothing was verified again after it. The acceptance
+// fields may differ. One manifest has to cover all of them. Outside a git
+// repository this cannot be told, and any manifest counts.
+function unevaluated(root, report) {
+  const pending = report.tickets.filter((t) => !t.problem && t.status === 'done' && !t.accepted);
+  const ids = pending.map((t) => t.id);
+  if (!pending.length || !report.evidence.length) return ids;
+  if (util.tryGit(root, ['rev-parse', '--is-inside-work-tree']) !== 'true') return [];
+  const candidates = report.evidence
+    .map((file) => util.readJson(path.join(root, file)))
+    .filter((doc) => doc && typeof doc === 'object' && typeof doc.candidate === 'string' && /^[0-9a-f]{40}$/.test(doc.candidate))
+    .sort((a, b) => String(b.created || '').localeCompare(String(a.created || '')))
+    .map((doc) => doc.candidate);
+  const covers = (candidate, t) => {
+    const then = util.tryGit(root, ['show', `${candidate}:./${t.file}`]);
+    return then !== null && parse.frontmatterField(then, 'status') === 'done' && parse.frontmatterField(then, 'verified') === (t.verified || '');
+  };
+  return candidates.some((candidate) => pending.every((t) => covers(candidate, t))) ? [] : ids;
+}
+
+// An approved spec that still needs tickets: no ticket names it in its `spec:`
+// field. A ticket without that field may belong to any spec, so while one is
+// still on its way to acceptance nothing is called unnarrowed.
+const specRef = (ref) => path.posix.normalize(String(ref).replace(/\\/g, '/'));
+function unnarrowed(report) {
+  if (report.stages.plan !== 'on') return null;
+  if (report.tickets.some((t) => !t.spec && !(t.status === 'done' && t.accepted))) return null;
+  const named = new Set(report.tickets.filter((t) => t.spec).map((t) => specRef(t.spec)));
+  return report.specs.find((s) => s.status === 'approved' && !named.has(specRef(s.file))) || null;
+}
+
 // The whole picture, as data. `harness` is null without a valid agreement;
 // `harnessProblem` says why when the file exists but does not validate.
 function gather(root) {
-  const report = { name: path.basename(root), harness: null, harnessProblem: null, stages: {}, models: null, specs: [], tickets: [], evidence: [], warnings: [], next: '' };
+  const report = { name: path.basename(root), harness: null, harnessProblem: null, stages: {}, models: null, specs: [], tickets: [], evidence: [], unevaluated: [], warnings: [], next: '' };
   const loaded = harnessModule.load(root);
   let homes = harnessModule.homes(null);
   if (loaded.ok) {
@@ -99,6 +135,7 @@ function gather(root) {
   report.specs = specEntries(root, homes.specs);
   report.tickets = parse.ticketFiles(root, homes.tickets).map((file) => ticketEntry(root, file));
   report.evidence = manifests(root, homes.evidence);
+  if (wantsEvidence(report)) report.unevaluated = unevaluated(root, report);
   for (const t of report.tickets) {
     if (t.problem) { report.warnings.push(`${t.file}: ${t.problem}`); continue; }
     if (t.status === 'done' && !t.ready) report.warnings.push(`${t.id} done: ${t.readiness}`);
@@ -108,7 +145,11 @@ function gather(root) {
   return report;
 }
 
-// The one thing to do next, first rule that matches.
+const wantsEvidence = (report) => Boolean(report.harness) && report.stages.evaluate === 'on' && Boolean(report.harness.stages.evaluate.evidence);
+
+// The one thing to do next, first rule that matches. Every rule looks at the
+// change in hand, never at the project's history: an approved spec no ticket
+// names is narrowed, and finished tickets are evaluated on their own candidate.
 function nextCommand(report) {
   if (!report.harness) return '/pincer-blueprint';
   const tickets = report.tickets;
@@ -126,7 +167,8 @@ function nextCommand(report) {
   const stale = tickets.find((t) => t.status === 'done' && !t.ready);
   if (stale) return `${SCRIPT} verify ${stale.id}`;
   if (draft) return `/pincer-plan ${draft.file} (awaiting approval)`;
-  if (report.stages.evaluate === 'on' && report.harness.stages.evaluate.evidence && report.evidence.length === 0) return '/pincer-evaluate';
+  if (unnarrowed(report)) return report.stages.narrow === 'on' ? '/pincer-narrow' : '/pincer-code';
+  if (wantsEvidence(report) && (report.evidence.length === 0 || (report.unevaluated || []).length)) return '/pincer-evaluate';
   const unaccepted = tickets.find((t) => t.status === 'done' && !t.accepted);
   if (unaccepted) {
     // Acceptance is the floor even with release off: then the next step is the accept call itself.