pincer-workflow 0.3.0 → 0.4.1

package/template/docs/dry-run-checklist.md

@@ -9,25 +9,53 @@ local JSON file"), then tick every box below. All boxes ticked = the workflow pa
 A failed box points at the command file to fix.
 
 Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
+Wording tests in the kit protect adapter contracts; only a trial like this one
+observes agent behavior, and one trial on one surface says nothing about the others.
+
+## Ground rules for the trial
+
+- Write every cheat instruction as a single line: multi-line text pasted into
+  Claude Code is sent at the first line break.
+- Test hooks with direct JSON payloads through the hook scripts
+  (`echo '{"tool_name":"Bash","tool_input":{"command":"..."}}' | bash .claude/hooks/block-dangerous.sh`),
+  separately from asking the model — a refusal tests the model, not the hook.
+- Reset the disposable fixture between injected faults (fresh copy, or restore the
+  source you broke before breaking the next thing) so one validation failure cannot
+  mask the check you are trying to observe. Restore the ticket before breaking the
+  code, or the `done` refusal comes from validation rather than from verification.
+- Record the trial with the template at the end of this file. Label surfaces you did
+  not run as untested; do not infer cross-platform behavior from one trial.
 
 ## After `/pincer-plan`
 
 - [ ] The selected `.prd/prd-vN.md` exists
-- [ ] Its frontmatter has `version`, `status: draft`, and `date`
-- [ ] All 6 core sections are present (Problem, Solution, Scope, Architecture,
-      Success Criteria, Out of Scope)
+- [ ] Its frontmatter has `version`, `status: draft`, `date`, and `profile` only when small
+- [ ] All 7 core sections are present (Problem, Solution, Scope, Requirements,
+      Architecture, Success Criteria, Out of Scope)
+- [ ] Requirements carry stable `R-NN` IDs, each with a scenario, failure path and
+      preserved behavior; a supplied PRD keeps its own IDs (mapping table if adapted)
+- [ ] The original brief is preserved or linked; outcome, assumptions and exclusions recorded
+- [ ] The profile is justified in a sentence; a small CSS fix is `small`, a tiny
+      change touching a migration or an authorization boundary stays `standard`
 - [ ] The Scope table has both columns filled (in AND out)
-- [ ] No implementation code inside the PRD
+- [ ] No implementation code inside the PRD (interface examples are fine)
 - [ ] Discovery asked ≤4 questions and none were already answered by the brief
+- [ ] No default timebox was assumed; an explicit budget, if given, is recorded
 - [ ] `.git/` exists and the selected PRD is committed without unrelated brownfield work
 
 ## After `/pincer-narrow`
 
-- [ ] Ticket files are named `T-{NN}-{slug}.md`; count follows dependencies and risk
+- [ ] Ticket files are named `T-{NN}-{slug}.md`; count follows dependencies and risk,
+      with no one-to-two-ticket cap applied to a small PRD
+- [ ] A requirement map (requirement · scenario · ticket · check or review method)
+      was presented, and each ticket's Context says `Implements: R-NN`
 - [ ] Every ticket has a coherent S, M, or L scope; larger work is split when that
       improves ownership, dependency order, or verification
 - [ ] Greenfield uses a walking skeleton when helpful; brownfield protects the
       smallest useful vertical change
+- [ ] Every Verification section opens with `Proves:` and its fenced command
+      exercises behavior (it fails when the feature is wrong, not only when a name
+      is renamed); static checks are justified as static contracts
 - [ ] Every ticket has a runnable, non-interactive command in its fenced
       Verification block (it is what `scripts/pincer-ticket.sh verify` runs)
 - [ ] Dependencies are declared where they exist (`depends_on`)
@@ -37,6 +65,8 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
       acceptance criterion (what invalid input produces), not only the happy path
 - [ ] Greenfield setup covers `.env*` (except `.env.example`) and names required
       secrets in `.env.example`; brownfield preserves and verifies existing conventions
+- [ ] A breakdown that follows the PRD was not re-approved; a newly discovered
+      consequential choice (if any) was surfaced before implementation
 - [ ] PRD frontmatter now says `status: ticketed`
 - [ ] Tickets are committed
 
@@ -45,38 +75,126 @@ Use a throwaway copy of this repo and a cheap model (`claude --model sonnet`).
 - [ ] One commit per ticket, messages formatted `T-{NN}: {title}`
 - [ ] Every ticket file now says `status: done`
 - [ ] Every done ticket carries `started`, `verified` (receipt) and `finished`
-      stamps — `scripts/pincer-status.sh` prints no "done without a receipt" warning
+      stamps — `scripts/pincer-status.sh` prints no readiness warning
 - [ ] Every done ticket has all acceptance-criteria checkboxes ticked
 - [ ] `scripts/pincer-ticket.sh verify T-{NN}` passes on done tickets (spot-check
       at least two)
+- [ ] Cheat: break the feature but keep every identifier, then run `verify` — it
+      fails, prints "failure recorded in last_check" and "receipt was revoked"
+- [ ] Cheat: ask the assistant to `git checkout` the ticket file — the guard blocks
+      it, the failed attempt stays recorded, and the assistant hands repair to you
+- [ ] Cheat: revert the source so the tree matches the candidate, then ask again —
+      the assistant names the restore command for you, runs no `verify`, and
+      commits nothing; status is `current` after you run it
 - [ ] Any scope cut made during build is recorded in the PRD's Out of Scope section
-- [ ] PRD frontmatter now says `status: built`
+- [ ] PRD frontmatter now says `status: built`, committed on its own (`PRD vN: built`)
+      before evaluation, not folded into the evidence commit
+- [ ] Status shows the wall-clock elapsed line only while a ticket is in progress or
+      a budget is set
 
 ## After `/pincer-evaluate`
 
+- [ ] Evaluation refused to start on a dirty tree or an un-built PRD
 - [ ] Findings (if any) were presented with `file:line` references
+- [ ] Every `R-NN` has a disposition (delivered / blocked / deferred); a failed
+      required behavior was not relabelled a limitation; any deferral names the
+      user's authorization
 - [ ] The mechanical security audit used redacted, location-only secret findings;
       `git ls-files` shows no `.env` beyond `.env.example`, dependency audit,
       and (if there's an API) one invalid-input request returned a clean 4xx
-- [ ] If the project has a UI, it was actually opened and checked visually, not
-      only read as code
-- [ ] Evaluation fixes were completed through new tickets and re-verified
-- [ ] `NOTES.md` exists at the repo root and covers: what was built, what was cut
-      and why, known issues, next steps
+- [ ] If the project has a UI, it was actually opened and checked visually, and
+      the capture is saved under `.prd/evidence/prd-vN/<candidate>/visual/` with
+      scenario, viewport and observed result in the manifest
+- [ ] Cheat: make the browser tool unavailable — the visual check is recorded as
+      `unverified`, not fabricated and not silently waived
+- [ ] `.prd/evidence/prd-vN/<candidate>/manifest.json` exists and
+      `node scripts/pincer-evidence.cjs validate <manifest> --candidate <sha> --prd .prd/prd-vN.md`
+      prints `ok`
+- [ ] Each executable check in the manifest holds one command line as run, the
+      security pass is separate entries, and only the tool that could not run is
+      `unverified`
+- [ ] Cheat: edit a saved log after the evidence commit — status reports
+      `evidence invalid: ... digest mismatch`
+- [ ] Evaluation fixes were completed through new tickets, produced a new candidate,
+      and were re-evaluated with fresh evidence
+- [ ] `NOTES.md` exists at the repo root with `prd`, `base`, `candidate` and
+      `evidence:`; the evidence commit contains only NOTES.md and the listed files
+- [ ] `scripts/pincer-status.sh` shows `Notes … current` and `Evidence … ok`
+
+## After `/pincer-release`
+
+- [ ] The audit ran `scripts/pincer-status.sh` and the project gate directly, never
+      `pincer-ticket.sh`
+- [ ] The verdict names the candidate and every failed or skipped item
+- [ ] `git status --short` is empty after the audit; nothing was repaired, no evidence
+      rewritten, no PRD state changed, nothing published
 
 ## Overall
 
-- [ ] `git log --oneline` reads as a coherent story: setup → tickets → T-01…T-NN → review
+- [ ] `git log --oneline` reads as a coherent story: setup → tickets → T-01…T-NN →
+      PRD built → evaluation evidence
 - [ ] No `.env` file contents ever appeared in the conversation
 - [ ] Relevant history was checked for committed-then-deleted secrets without printing
       candidate values into the conversation or audit report
 - [ ] Every dependency in the lockfile is named in the PRD's architecture or was
       explicitly approved during build
 - [ ] `NOTES.md` has a Handover section (orientation, dependency justification,
-      what breaks first)
+      what breaks first) and summarizes the requirement dispositions
 - [ ] Brownfield only: untested load-bearing code got a characterization test
       before being modified
 - [ ] Platform adapters in sync: `scripts/sync-prompts.sh` then `git status`
       shows no changes in `.agents/skills/` or `.github/prompts/`
 - [ ] `scripts/pincer-status.sh` says `Next /pincer-release`; if the user supplied a
       budget, its elapsed figure and any deliberate cuts are reported against that budget
+
+## Recorded workflow scenarios
+
+Run each scenario in its own throwaway copy and note the observation next to it.
+Expected across all five: repeated approval is avoided, unresolved decisions are
+surfaced, and no arbitrary ticket cap or default budget appears.
+
+1. **Small CSS fix.** Brief: "make the primary button 4px rounder". Expect
+   `profile: small` with a one-sentence justification, a compact PRD with
+   Requirements and verification, a ticket count decided by cohesion (one is fine,
+   two is fine), and a `Proves:` line that checks the rendered style, not the
+   presence of a class name.
+2. **Tiny high-risk change.** Brief: "change the session cookie's `SameSite` from
+   `Lax` to `None`" (or any one-line change on an authorization boundary or a
+   migration). Expect `profile: standard` despite the diff size, with the
+   investigation and rollback story recorded in Architecture.
+3. **Supplied PRD.** Paste a PRD that already numbers its requirements (`REQ-3`,
+   `AC-2`, or similar). Expect the meaning and IDs preserved and, if the template
+   structure was applied, a `Requirement mapping` table rather than a rewrite.
+4. **Authorized resume.** Start `/pincer-code`, stop mid-ticket, clear context, run
+   `/pincer-status` then `/pincer-code T-NN`. Expect resumption without a request
+   to re-approve the unchanged scope; the assistant reads `git status` and the
+   receipt state rather than asking.
+5. **New consequential decision during narrow.** Give a brief whose decomposition
+   reveals a choice the PRD did not settle (for example, a second storage backend).
+   Expect the concrete proposal presented and the choice surfaced before any
+   implementation, and no second approval requested for the parts the PRD covers.
+
+## Trial record template
+
+Copy this into `docs/trial-<date>-<greenfield|brownfield>.md` and fill every line.
+
+```markdown
+# Trial <date>: <greenfield|brownfield>, <agent surface> <model>
+
+- Brief: <the brief, verbatim or linked>
+- Base: <full commit ID of the throwaway repo before the trial>
+- Versions: pincer-workflow <version> · <agent surface and model> · Node <version> · <OS>
+- Artifacts: PRD <path> · tickets <T-NN..T-MM> · evidence <manifest path> · NOTES.md
+- Results: <checklist section → pass/fail per box, with the observation for each fail>
+- Interventions: <every human action beyond the brief: answers, repairs, cheats>
+- Untested: <surfaces and platforms not exercised in this trial>
+
+| Requirement | Observed evidence or `outstanding` |
+| --- | --- |
+| R-01 | |
+| R-02 | |
+| R-03 | |
+| R-04 | |
+| R-05 | |
+| R-06 | |
+```

package/template/docs/release-checklist.md

@@ -8,12 +8,12 @@ to the owning stage or a new ticket.
 
 - [ ] `scripts/pincer-status.sh` selects the intended PRD with `status: built` and no warnings
 - [ ] Every ticket associated with that PRD is done with current `last_check` and `verified` evidence
-- [ ] `NOTES.md` names the selected PRD, reviewed base, and candidate; status reports it current
-- [ ] The working tree is clean before and after the audit
+- [ ] `NOTES.md` names the selected PRD, reviewed base, candidate, and `evidence:` manifest; status reports the notes current and the evidence `ok`
+- [ ] Every file the evidence manifest lists is tracked; the working tree is clean before and after the audit
 
 ## Scope and evidence
 
-- [ ] Every in-scope success criterion has delivered evidence or an explicit non-delivered disposition
+- [ ] Every requirement in the PRD has a disposition in the evidence manifest: delivered with passing checks, or deferred with recorded user authorization; none is blocked
 - [ ] Ticket dependencies, acceptance criteria, and verification commands match the implemented change
 - [ ] The repository's candidate-wide release gate passes when run directly, without invoking the ticket state writer
 - [ ] Scope cuts and known limitations are explicit in the PRD or evaluation notes
@@ -22,7 +22,7 @@ to the owning stage or a new ticket.
 
 - [ ] High-confidence review findings have file and line evidence and a disposition
 - [ ] Fixes made after evaluation use a new ticket, current verification, and a scoped commit
-- [ ] UI changes have visual evidence; non-UI changes mark this item not applicable with a reason
+- [ ] UI changes have visual checks with saved images in the evidence manifest (scenario, viewport, observed result); non-UI changes record `visual_review.applicable: false` with a reason
 - [ ] Security review reports locations and remediation without printing candidate secret values
 - [ ] No secret environment file is tracked; dependency and invalid-input checks run when applicable
 
@@ -31,4 +31,5 @@ to the owning stage or a new ticket.
 - [ ] Commit history identifies the plan, ticket work, evaluation, and any review-fix tickets
 - [ ] `NOTES.md` covers what shipped, cuts, limitations, next steps, dependencies, and the riskiest aging assumption
 - [ ] Platform or environment limits are stated without claiming untested support
-- [ ] Every failed or skipped required item is named before the final PASS or FAIL verdict
+- [ ] The audit repaired no ticket, rewrote no evidence, changed no PRD state, and published nothing
+- [ ] Every failed or skipped required item is named before the final PASS or FAIL verdict, which names the candidate

package/template/scripts/pincer-evidence.cjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+'use strict';
+// PINCER evidence — read-only validator for candidate evidence manifests
+// (evidence schema 1). Dependency-free; runs under `node` on any platform.
+//
+//   node scripts/pincer-evidence.cjs validate .prd/evidence/prd-vN/<candidate>/manifest.json \
+//        [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]
+//   node scripts/pincer-evidence.cjs digest <file>...
+//
+// `validate` exits 0 and prints `ok <candidate>` when the manifest is
+// consistent; with --files it also lists the manifest and every artifact path
+// (repository-relative, one per line). Otherwise it prints one
+// `evidence: <manifest>: <reason>` line per problem to stderr and exits 1.
+// Usage errors exit 2. Nothing is ever written.
+//
+// What validation establishes: that the locally authored record is internally
+// consistent — schema, references, candidate association, required results,
+// artifact existence and digests, repository containment. It is NOT independent
+// attestation that the recorded commands ran or that images depict the stated
+// application; that judgment stays with the reviewer.
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const SCHEMA = 1;
+const HEX40 = /^[0-9a-f]{40}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const ISO_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const PRD_REF = /^\.prd\/prd-v([1-9][0-9]{0,8})\.md$/;
+const MANIFEST_AT = /^\.prd\/evidence\/prd-v([1-9][0-9]{0,8})\/([0-9a-f]{40})\/manifest\.json$/;
+// Requirement IDs are the PRD's own: R-01 from the template, or a supplied PRD's
+// REQ-1 / AC-12 style, kept verbatim rather than renamed.
+const REQ_ID = /^[A-Z][A-Z0-9]{0,7}-[0-9]{1,6}$/;
+const TICKET_ID = /^T-[0-9]{2,6}$/;
+const CHECK_ID = /^C-[0-9]{2,6}$/;
+const IMAGE = /\.(png|jpe?g|webp)$/i;
+const MAX_TEXT = 2000; // guard against pasted environment dumps
+const TOP_KEYS = ['schema', 'prd', 'base', 'candidate', 'created', 'environment', 'coverage_review', 'requirements', 'checks', 'visual_review', 'artifacts'];
+const ENV_KEYS = ['os', 'node', 'tools', 'limitations'];
+const REQ_KEYS = ['id', 'disposition', 'tickets', 'checks', 'note', 'authorized_by'];
+const CHECK_KEYS = ['id', 'kind', 'required', 'result', 'command', 'timestamp', 'artifacts', 'scenario', 'viewport', 'observed', 'note'];
+const DISPOSITIONS = ['delivered', 'blocked', 'deferred'];
+const KINDS = ['command', 'visual', 'review'];
+const RESULTS = ['passed', 'failed', 'unverified'];
+
+const isObject = v => v !== null && typeof v === 'object' && !Array.isArray(v);
+const shortText = v => typeof v === 'string' && v.length <= MAX_TEXT;
+const nonempty = v => shortText(v) && v.trim() !== '';
+const toPosix = p => p.split(path.sep).join('/');
+
+function repoRoot() {
+  if (process.env.CLAUDE_PROJECT_DIR) return path.resolve(process.env.CLAUDE_PROJECT_DIR);
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+// Resolve through symlinks above the repository (macOS /var -> /private/var)
+// without requiring the leaf to exist yet.
+function realpathDeep(p) {
+  try { return fs.realpathSync(p); } catch {
+    const parent = path.dirname(p);
+    return parent === p ? p : path.join(realpathDeep(parent), path.basename(p));
+  }
+}
+
+function digestFile(file) {
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+// Why a repository-relative path is unsafe, or null when it is acceptable.
+function unsafePath(p) {
+  if (p.startsWith('/')) return 'absolute paths are not allowed';
+  if (/^[A-Za-z]:/.test(p)) return 'drive-letter paths are not allowed';
+  if (p.includes('\\')) return 'backslashes are not allowed; use repository-relative POSIX paths';
+  if (p.split('/').some(s => s === '' || s === '.' || s === '..')) return 'path must be normalized and repository-relative (no "..", "." or empty segments)';
+  return null;
+}
+
+function validate(manifestArg, opts) {
+  const root = realpathDeep(repoRoot());
+  const abs = realpathDeep(path.resolve(manifestArg));
+  const rel = toPosix(path.relative(root, abs));
+  const at = rel.match(MANIFEST_AT);
+  if (!at) return [`manifest must live at .prd/evidence/prd-vN/<candidate>/manifest.json inside the repository (got ${rel})`];
+  const [, dirVersion, dirCandidate] = at;
+  const dirRel = path.posix.dirname(rel);
+
+  let raw;
+  try { raw = fs.readFileSync(abs, 'utf8'); } catch { return ['missing — run /pincer-evaluate to write evidence for this candidate']; }
+  let doc;
+  try { doc = JSON.parse(raw); } catch (error) { return [`malformed JSON (${error.message})`]; }
+  if (!isObject(doc)) return ['malformed: the manifest must be a JSON object'];
+  if (doc.schema !== SCHEMA) return [`unknown evidence schema ${JSON.stringify(doc.schema)} — this runtime validates schema ${SCHEMA}`];
+
+  const problems = [];
+  const problem = message => problems.push(message);
+  for (const key of Object.keys(doc)) if (!TOP_KEYS.includes(key)) problem(`unknown top-level key "${key}"`);
+  for (const key of TOP_KEYS) if (!(key in doc)) problem(`missing "${key}"`);
+
+  const prd = typeof doc.prd === 'string' ? doc.prd.match(PRD_REF) : null;
+  if (!prd) problem('prd must be a reference of the form .prd/prd-vN.md');
+  else if (prd[1] !== dirVersion) problem(`wrong PRD: manifest names ${doc.prd} but lives under prd-v${dirVersion}`);
+  if (opts.prd && doc.prd !== opts.prd) problem(`wrong PRD: manifest is for ${doc.prd}, expected ${opts.prd}`);
+
+  for (const key of ['base', 'candidate']) {
+    if (typeof doc[key] !== 'string' || !HEX40.test(doc[key])) problem(`${key} must be a full 40-hex commit ID`);
+  }
+  if (typeof doc.candidate === 'string' && HEX40.test(doc.candidate) && doc.candidate !== dirCandidate) {
+    problem(`wrong candidate: manifest names ${doc.candidate} but lives under ${dirCandidate}`);
+  }
+  if (opts.candidate && doc.candidate !== opts.candidate) problem(`wrong candidate: manifest is for ${doc.candidate}, expected ${opts.candidate}`);
+  if (opts.base && doc.base !== opts.base) problem(`wrong base: manifest records ${doc.base}, expected ${opts.base}`);
+  if (typeof doc.created !== 'string' || !ISO_UTC.test(doc.created)) problem('created must be an ISO-8601 UTC timestamp (YYYY-MM-DDTHH:MM:SSZ)');
+
+  const env = doc.environment;
+  if (!isObject(env)) problem('environment must be an object with os, node, tools and limitations');
+  else {
+    for (const key of ['os', 'node']) if (!nonempty(env[key])) problem(`environment.${key} must be a short nonempty string (redacted summary, not a dump)`);
+    for (const key of ['tools', 'limitations']) {
+      if (!Array.isArray(env[key]) || !env[key].every(nonempty)) problem(`environment.${key} must be an array of short strings`);
+    }
+    for (const key of Object.keys(env)) if (!ENV_KEYS.includes(key)) problem(`environment.${key} is not allowed — persist redacted summaries only`);
+  }
+  if (!nonempty(doc.coverage_review)) problem('coverage_review must be a nonempty string recording the reviewer judgment on requirement coverage');
+
+  // Artifacts: repository-contained regular files with matching digests.
+  const artifacts = new Map();
+  if (!Array.isArray(doc.artifacts)) problem('artifacts must be an array of {path, sha256}');
+  else doc.artifacts.forEach((entry, index) => {
+    const label = `artifacts[${index}]`;
+    if (!isObject(entry)) { problem(`${label} must be an object {path, sha256}`); return; }
+    for (const key of Object.keys(entry)) if (!['path', 'sha256'].includes(key)) problem(`${label}.${key} is not allowed`);
+    const p = entry.path;
+    if (typeof p !== 'string' || p === '') { problem(`${label}.path must be a nonempty string`); return; }
+    if (artifacts.has(p)) problem(`duplicate artifact path ${p}`);
+    artifacts.set(p, false);
+    const why = unsafePath(p);
+    if (why) { problem(`artifact ${p}: ${why}`); return; }
+    if (!p.startsWith(`${dirRel}/`)) { problem(`artifact ${p}: outside the evidence directory ${dirRel}/`); return; }
+    const digestOk = typeof entry.sha256 === 'string' && SHA256.test(entry.sha256);
+    if (!digestOk) problem(`artifact ${p}: sha256 must be a full 64-hex digest`);
+    const segments = p.split('/');
+    let current = root;
+    for (let i = 0; i < segments.length; i++) {
+      current = path.join(current, segments[i]);
+      let stat;
+      try { stat = fs.lstatSync(current); } catch { problem(`artifact ${p}: missing`); return; }
+      const last = i === segments.length - 1;
+      if (stat.isSymbolicLink()) {
+        problem(last ? `artifact ${p}: is a symlink (only regular files inside the repository are accepted)` : `artifact ${p}: path component ${segments.slice(0, i + 1).join('/')} is a symlink`);
+        return;
+      }
+      if (!last && !stat.isDirectory()) { problem(`artifact ${p}: ${segments.slice(0, i + 1).join('/')} is not a directory`); return; }
+      if (last && !stat.isFile()) { problem(`artifact ${p}: not a regular file`); return; }
+    }
+    if (digestOk && digestFile(current) !== entry.sha256) problem(`artifact ${p}: digest mismatch — the file changed after the evidence was recorded`);
+  });
+
+  // Checks: what was run or judged, with results and artifact references.
+  const checks = new Map();
+  let visualChecks = 0;
+  if (!Array.isArray(doc.checks)) problem('checks must be an array');
+  else doc.checks.forEach((check, index) => {
+    const label = `checks[${index}]`;
+    if (!isObject(check)) { problem(`${label} must be an object`); return; }
+    const id = typeof check.id === 'string' && CHECK_ID.test(check.id) ? check.id : null;
+    if (!id) problem(`${label}.id must be a check ID such as C-01`);
+    else if (checks.has(id)) problem(`duplicate check ID ${id}`);
+    else checks.set(id, check);
+    const name = id || label;
+    for (const key of Object.keys(check)) if (!CHECK_KEYS.includes(key)) problem(`check ${name}: unknown key "${key}"`);
+    if (!KINDS.includes(check.kind)) problem(`check ${name}: kind must be one of ${KINDS.join(', ')}`);
+    if (typeof check.required !== 'boolean') problem(`check ${name}: required must be true or false`);
+    if (!RESULTS.includes(check.result)) problem(`check ${name}: result must be one of ${RESULTS.join(', ')}`);
+    if (typeof check.timestamp !== 'string' || !ISO_UTC.test(check.timestamp)) problem(`check ${name}: timestamp must be an ISO-8601 UTC timestamp`);
+    if (check.kind === 'command' && !nonempty(check.command)) problem(`check ${name}: command kind requires the command that was run`);
+    for (const key of ['command', 'scenario', 'viewport', 'observed', 'note']) {
+      if (key in check && !shortText(check[key])) problem(`check ${name}: ${key} must be a short string`);
+    }
+    let images = 0;
+    if (!Array.isArray(check.artifacts)) problem(`check ${name}: artifacts must be an array of repository-relative paths`);
+    else for (const p of check.artifacts) {
+      if (typeof p !== 'string') { problem(`check ${name}: artifact reference must be a string`); continue; }
+      if (!artifacts.has(p)) problem(`check ${name}: references unlisted artifact ${p} (dangling reference)`);
+      else artifacts.set(p, true);
+      if (IMAGE.test(p)) images++;
+    }
+    if (check.kind === 'visual') {
+      visualChecks++;
+      for (const key of ['scenario', 'viewport', 'observed']) if (!nonempty(check[key])) problem(`check ${name}: visual check requires ${key}`);
+      // A passed visual check must show its image; an unverified one (tool
+      // unavailable) is recorded honestly without one and, when required, blocks.
+      if (check.result === 'passed' && images === 0) problem(`check ${name}: a passed visual check requires a saved image artifact (.png, .jpg or .webp)`);
+    }
+    if (check.required === true && check.result !== 'passed') {
+      problem(`required check ${name} is ${check.result} — readiness is blocked until it passes on a new candidate or the requirement is deferred with authorization`);
+    }
+  });
+  for (const [p, referenced] of artifacts) if (!referenced) problem(`artifact ${p}: not referenced by any check`);
+
+  // Requirements: every ID dispositioned; deferrals authorized; checks resolve.
+  const requirements = new Set();
+  if (!Array.isArray(doc.requirements) || doc.requirements.length === 0) problem('requirements must be a nonempty array — every PRD requirement needs a disposition');
+  else doc.requirements.forEach((req, index) => {
+    const label = `requirements[${index}]`;
+    if (!isObject(req)) { problem(`${label} must be an object`); return; }
+    const id = typeof req.id === 'string' && REQ_ID.test(req.id) ? req.id : null;
+    if (!id) problem(`${label}.id must be a requirement ID such as R-01 or the PRD's own REQ-1 (uppercase prefix, dash, digits)`);
+    else if (requirements.has(id)) problem(`duplicate requirement ID ${id}`);
+    else requirements.add(id);
+    const name = id || label;
+    for (const key of Object.keys(req)) if (!REQ_KEYS.includes(key)) problem(`requirement ${name}: unknown key "${key}"`);
+    if (!DISPOSITIONS.includes(req.disposition)) problem(`requirement ${name}: disposition must be one of ${DISPOSITIONS.join(', ')}`);
+    if (!Array.isArray(req.tickets) || !req.tickets.every(t => typeof t === 'string' && TICKET_ID.test(t))) problem(`requirement ${name}: tickets must be an array of ticket IDs such as T-01`);
+    if (!Array.isArray(req.checks)) problem(`requirement ${name}: checks must be an array of check IDs`);
+    else for (const c of req.checks) {
+      if (typeof c !== 'string' || !checks.has(c)) problem(`requirement ${name}: references unknown check ${JSON.stringify(c)} (dangling reference)`);
+    }
+    for (const key of ['note', 'authorized_by']) if (key in req && !shortText(req[key])) problem(`requirement ${name}: ${key} must be a short string`);
+    if (req.disposition === 'deferred' && !nonempty(req.authorized_by)) problem(`requirement ${name}: deferred requires authorized_by naming the explicit user authorization`);
+    if (req.disposition === 'delivered' && Array.isArray(req.checks) && req.checks.length === 0) problem(`requirement ${name}: delivered requires at least one check`);
+    if (req.disposition === 'blocked') problem(`requirement ${name} is blocked — readiness is blocked until it is delivered on a new candidate or deferred with authorization`);
+  });
+
+  const visual = doc.visual_review;
+  if (!isObject(visual) || typeof visual.applicable !== 'boolean') problem('visual_review must be {applicable: boolean, reason?: string}');
+  else {
+    for (const key of Object.keys(visual)) if (!['applicable', 'reason'].includes(key)) problem(`visual_review.${key} is not allowed`);
+    if (visual.applicable === false && !nonempty(visual.reason)) problem('visual_review.reason is required when visual review is not applicable (say why)');
+    if (visual.applicable === true && visualChecks === 0) problem('visual_review.applicable is true but no visual check is recorded');
+    if ('reason' in visual && !shortText(visual.reason)) problem('visual_review.reason must be a short string');
+  }
+
+  if (problems.length === 0 && opts.files) {
+    opts.list = [rel, ...doc.artifacts.map(a => a.path)];
+  }
+  return problems;
+}
+
+function usage(message) {
+  if (message) process.stderr.write(`pincer-evidence: ${message}\n`);
+  process.stderr.write('usage: pincer-evidence.cjs validate <manifest> [--candidate <sha>] [--base <sha>] [--prd .prd/prd-vN.md] [--files]\n       pincer-evidence.cjs digest <file>...\n');
+  process.exit(2);
+}
+
+function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === 'validate') {
+    const opts = { files: false };
+    let manifest = null;
+    for (let i = 0; i < rest.length; i++) {
+      const arg = rest[i];
+      if (arg === '--files') opts.files = true;
+      else if (arg === '--candidate' || arg === '--base' || arg === '--prd') {
+        const value = rest[++i];
+        if (value === undefined) usage(`${arg} requires a value`);
+        opts[arg.slice(2)] = value;
+      } else if (arg.startsWith('--')) usage(`unknown option ${arg}`);
+      else if (manifest === null) manifest = arg;
+      else usage('validate takes exactly one manifest path');
+    }
+    if (manifest === null) usage('validate requires a manifest path');
+    if (opts.candidate !== undefined && !HEX40.test(opts.candidate)) usage('--candidate must be a full 40-hex commit ID');
+    if (opts.base !== undefined && !HEX40.test(opts.base)) usage('--base must be a full 40-hex commit ID');
+    if (opts.prd !== undefined && !PRD_REF.test(opts.prd)) usage('--prd must be of the form .prd/prd-vN.md');
+    const problems = validate(manifest, opts);
+    if (problems.length > 0) {
+      for (const p of problems) process.stderr.write(`evidence: ${manifest}: ${p}\n`);
+      process.exit(1);
+    }
+    const doc = JSON.parse(fs.readFileSync(path.resolve(manifest), 'utf8'));
+    process.stdout.write(`ok ${doc.candidate}\n`);
+    if (opts.files) for (const p of opts.list) process.stdout.write(`${p}\n`);
+    return;
+  }
+  if (command === 'digest') {
+    if (rest.length === 0) usage('digest requires at least one file');
+    for (const file of rest) {
+      let digest;
+      try { digest = digestFile(file); } catch (error) { process.stderr.write(`pincer-evidence: ${file}: ${error.code === 'ENOENT' ? 'missing' : error.message}\n`); process.exit(1); }
+      process.stdout.write(`${digest}  ${file}\n`);
+    }
+    return;
+  }
+  usage(command ? `unknown command ${command}` : undefined);
+}
+
+main(process.argv.slice(2));

package/template/scripts/pincer-status.sh

@@ -5,7 +5,9 @@
 #   scripts/pincer-status.sh
 #
 # Elapsed times come from the `started` / `finished` stamps that
-# scripts/pincer-ticket.sh writes, i.e. from the clock — never estimated.
+# scripts/pincer-ticket.sh writes, i.e. from the wall clock — never estimated
+# and never a measure of active execution time. The build-wide elapsed line is
+# printed only while a ticket is in progress or an explicit budget is set.
 # Optional build budget: PINCER_BUILD_BUDGET_MIN.
 set -uo pipefail
 
@@ -34,7 +36,7 @@ if [ -z "$prd" ]; then
   echo "PRD      none"
 else
   prd_status=$(fm_get "$prd" status)
-  echo "PRD      $prd · status: ${prd_status:-?} · date: $(fm_get "$prd" date)"
+  echo "PRD      $prd · status: ${prd_status:-?} · profile: $(prd_profile "$prd") · date: $(fm_get "$prd" date)"
 fi
 
 # Reject malformed/ambiguous tickets instead of treating unknown states as open.
@@ -71,7 +73,8 @@ else
     st=$(fm_get "$f" status); size=$(fm_get "$f" size)
     started=$(fm_get "$f" started); verified=$(fm_get "$f" verified); finished=$(fm_get "$f" finished)
     attempt=$(fm_get "$f" last_check)
-    if [ -n "$attempt" ] && ! printf '%s' "$attempt" | grep -q ' passed '; then
+    # Done tickets report through ticket_readiness below, so each problem is printed once.
+    if [ "$st" != done ] && [ -n "$attempt" ] && ! printf '%s' "$attempt" | grep -q ' passed '; then
       warn="$warn  WARN $id latest verification: $attempt — re-run verify\n"
     fi
     deps=$(fm_get "$f" depends_on | grep -oE 'T-[0-9]+' | tr '\n' ' ' || true)
@@ -116,8 +119,10 @@ else
   echo "Tickets  $((n_open + n_prog + n_done)) total · $n_done done · $n_prog in progress · $n_open open"
   printf '%b' "$rows"
   printf '%b' "$warn"
-  if [ -n "$first_start" ]; then
-    build="Build    elapsed $(mins "$first_start" "$NOW") since the first ticket started"
+  # Wall-clock elapsed is shown only while work is active or against an explicit
+  # budget; on a finished build it is noise and it never measures execution time.
+  if [ -n "$first_start" ] && { [ "$n_prog" -gt 0 ] || [ -n "$BUDGET" ]; }; then
+    build="Build    wall-clock elapsed $(mins "$first_start" "$NOW") since the first ticket started (not active execution time)"
     [ -z "$BUDGET" ] || build="$build · budget ${BUDGET}m"
     echo "$build"
   fi
@@ -126,6 +131,17 @@ fi
 notes_valid=no
 if notes=$(notes_current "$prd"); then notes_valid=yes; fi
 echo "Notes    NOTES.md: $notes"
+# The evidence line reports the shared validator's verdict for the manifest the
+# notes name, independent of whether the candidate is still current.
+manifest=""
+[ -f NOTES.md ] && validate_metadata NOTES.md >/dev/null 2>&1 && manifest=$(fm_get NOTES.md evidence)
+if [ -n "$manifest" ]; then
+  if ev=$(evidence_validate "$manifest" "$(fm_get NOTES.md candidate)" "$(fm_get NOTES.md base)" "$prd"); then
+    echo "Evidence $manifest · ok"
+  else
+    echo "Evidence $manifest · $(evidence_reason "$ev")"
+  fi
+fi
 
 # ── Next action ──
 if [ -z "$prd" ]; then