devflow-kit 3.11.0 → 3.12.1

package/src/assets/scripts/verify-evidence.cjs

@@ -19,6 +19,8 @@
 //   node verify-evidence.cjs publish --pr <n> [--publication auto|full|off|stub] [--evidence <file>]
 //   node verify-evidence.cjs readiness --pr <n> [--require-non-author-approval true|false]
 //        [--evidence <file>] [--out <file>]
+//   node verify-evidence.cjs claim --evidence <file> --head <sha> [--plan <file>]
+//        gate | TP-<n>=<PASS|FAIL|SKIP>[:<exit>] ...
 //
 // stdout (D-VERIFY-STDOUT) is empty or exactly one of these shapes, each closed-vocabulary
 // (the render block's TP lines come from the caller's own plan file):
@@ -33,10 +35,14 @@
 //             posted:<yes|no|n/a> body:<same|changed>          (one line; wrapped here)
 //   splice    SPLICE ok|resplice (exit 0) or SPLICE conflict|malformed|oversize (exit 5)
 //   readback  READBACK ok (exit 0) or READBACK mismatch (exit 5)
-//   publish   the `## PR Evidence` block — the heading, the EVIDENCE line, one
+//   publish   the `## PR Evidence` block — the heading, the EVIDENCE line, the line
+//             `Test plan: <v>/<total> verified (VERIFIED-CI <a>, ATTESTED-LOCAL <b>)`
+//             (v is a + b, all three read from the EVIDENCE line), one
 //             `**Body**: … · **Comment**: …` line — then one `TRACEABILITY: DEGRADED
 //             (<reason>)` line per degraded part (exit 0), or exit 2 with one line:
-//             `TRACEABILITY: DEGRADED (evidence unavailable)` when it could not run,
+//             `TRACEABILITY: DEGRADED (evidence unavailable)` when it could not run (a
+//             usage error, an internal error, a failed read and a block the output gate
+//             refuses all end this way, so a `publish` never ends with empty stdout),
 //             `TRACEABILITY: DEGRADED (compliance off)` when the machine manifest does not
 //             say compliance is enabled, or `TRACEABILITY: DEGRADED (compliance state
 //             unreadable)` when that manifest cannot be read. The last two come before
@@ -55,10 +61,34 @@
 //             is removed before the first read, and a block that does not parse or a
 //             write that fails leaves no out file. The one exception is a path that
 //             git tracks (below), which is left as it is
+//   claim     D-CLAIM-APPEND: appends claim lines to the `## Claims` section of the
+//             `--evidence` file. `gate` writes `- gate:validate PASS sha:<head>
+//             by:validate`. Each `TP-<n>=<outcome>[:<exit>]` writes `- TP-<n> <outcome>
+//             sha:<head> by:test[ exit:<exit>]`. `--head` is one 40-hex SHA, else
+//             nothing is written. The `exit:` part is written only for a number from 0
+//             to 255. A TP that the plan does not list gets no line. The plan is the
+//             `## Test Plan` of the `--plan` file, or of the evidence file when `--plan`
+//             is absent. The `## Claims` section is created when absent, at the end
+//             of the file; when it is not the last section the lines go at its end
+//             (D-CLAIM-INSERT). A missing folder inside the working directory is
+//             created, and so is the file (D-CLAIM-FOLDER). The write is one append of
+//             every line, or, for a Claims section that is not last, one whole-file
+//             replace through a sibling temporary file that keeps the file's mode. The
+//             parser of pr-evidence.cjs accepts each line before it. It prints one
+//             line, exit 0:
+//             `CLAIM appended:<n> PASS:<n> FAIL:<n> SKIP:<n> skipped:<n>`
+//             (`skipped` counts the TPs that got no line), or exit 2 with
+//             `CLAIM refused (<reason>)`, the reason being `head not one sha`,
+//             `evidence file tracked` (git tracks it, or cannot say it does not),
+//             `evidence file unusable` (a file that does not parse, or a folder that is
+//             missing outside the working directory) or `plan file unusable`. A refusal
+//             writes nothing. A folder the run made is removed again when the run
+//             leaves no file in it
 // A git-tracked file counts as absent, like a tracked `.devflow/config.json`
 // (D-TRACKED-RESULT). `verify`, `publish` and `readiness` ask git about an `--evidence`
 // file before they read it, and about `--block-out`, `--comment-out`, `--stale-out` and
-// `--out` before they write or remove one. Only a clear "not tracked" answer lets the
+// `--out` before they write or remove one. `claim` asks about its `--evidence` and
+// `--plan` files, and refuses both when either is not clearly untracked. Only a clear "not tracked" answer lets the
 // file be read or written. A tracked `--evidence` file, or one git cannot answer for, is
 // dropped: the run goes on exactly as if `--evidence` was not given, and the stderr
 // summary carries the note `evidence-ignored`. A tracked out path, or one git cannot
@@ -68,14 +98,16 @@
 //
 // Exit codes:
 //   0  ok
-//   1  usage error — stdout entirely empty, usage on stderr
+//   1  usage error — stdout entirely empty, usage on stderr (a `publish` usage error is
+//      exit 2 with the evidence unavailable line instead)
 //   2  input unusable — a file could not be read (missing, not a regular file,
 //      oversize, not UTF-8), the evidence file or the state directory is
 //      malformed, or the PR body's test-plan block cannot serve as the plan.
 //      For `publish` and `readiness` (D-OP-SCRIPT-POINTER) it is the DEGRADED
 //      result: the operation could not read what it needs, and the stdout above
-//      says so
-//   3  output write failed — no stdout line is printed
+//      says so. For `claim` it is the refusal line above
+//   3  output write failed — no stdout line is printed (a `claim` write leaves the
+//      evidence file as it was)
 //   4  remote or internal failure before any verdict — `gh pr view` failed or
 //      answered something unusable, or an unexpected internal error
 //   5  output gate refused — `check` found the file invalid, the EVIDENCE line
@@ -223,6 +255,12 @@ const DECISIVE_REVIEW_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'DISMIS
 const SPLICE_LINE_RE = /^SPLICE (?<outcome>ok|resplice|conflict|malformed|oversize)$/;
 const READBACK_LINE_RE = /^READBACK (?<outcome>ok|mismatch)$/;
 
+/** D-CLAIM-APPEND: the stdout shapes of `claim`, and the closed set of its refusal reasons. */
+const CLAIM_APPENDED_RE = /^CLAIM appended:(?<n>[0-9]{1,3}) PASS:(?<pass>[0-9]{1,3}) FAIL:(?<fail>[0-9]{1,3}) SKIP:(?<skip>[0-9]{1,3}) skipped:(?<skipped>[0-9]{1,3})$/;
+const CLAIM_REFUSAL_RE = /^CLAIM refused \((?<reason>head not one sha|evidence file tracked|evidence file unusable|plan file unusable)\)$/;
+/** One `claim` argument: the TP, its outcome, and an exit the script keeps only as a number from 0 to 255. */
+const CLAIM_ARG_RE = /^TP-(?<n>[1-9][0-9]{0,2})=(?<outcome>PASS|FAIL|SKIP)(?::(?<exit>[^\s]{1,12}))?$/;
+
 const USAGE = [
   'Usage: node verify-evidence.cjs check tp|block|exceptions|wave <file>',
   '       node verify-evidence.cjs check wave --links-only <file>',
@@ -234,6 +272,8 @@ const USAGE = [
   '       node verify-evidence.cjs publish --pr <n> [--publication auto|full|off|stub] [--evidence <file>]',
   '       node verify-evidence.cjs readiness --pr <n> [--require-non-author-approval true|false]',
   '            [--evidence <file>] [--out <file>]',
+  '       node verify-evidence.cjs claim --evidence <file> --head <sha> [--plan <file>]',
+  '            gate | TP-<n>=<PASS|FAIL|SKIP>[:<exit>] ...',
 ].join('\n');
 
 // ---------------------------------------------------------------------------
@@ -253,11 +293,12 @@ const USAGE = [
  * @typedef {{ ghCalls: number, runViews: number, throttled: boolean }} Budget
  *
  * @typedef {{ exec: ExecFn, env: NodeJS.ProcessEnv, cwd: string, now: () => number,
- *   deadline: number, budget: Budget, notes: Set<string>, stderr: (text: string) => void,
- *   ghCap?: number }} Io
+ *   deadline: number, budget: Budget, notes: Set<string>, made: string[],
+ *   stderr: (text: string) => void, ghCap?: number }} Io
  *   The imperative shell's one context: every call goes through it, so every
  *   bound is counted in one place. `notes` holds closed tokens for the stderr
- *   summary, never input bytes. `ghCap` replaces CAPS.GH_CALLS for a stage that
+ *   summary, never input bytes. `made` holds the folders a `claim` run created, deepest
+ *   first (D-CLAIM-FOLDER). `ghCap` replaces CAPS.GH_CALLS for a stage that
  *   carries a budget of its own (`publish`'s writes).
  *
  * @typedef {{ login: string, association: string, body: string, viewerDidAuthor: boolean, commentId: string }} PrComment
@@ -290,7 +331,9 @@ const USAGE = [
  *   | { kind: 'readback', pr: number, expect: string }
  *   | { kind: 'publish', pr: number, publication: string, evidence: string | null }
  *   | { kind: 'readiness', pr: number, requireNonAuthor: 'true' | 'false' | 'unrecognised',
- *       evidence: string | null, out: string | null }} ParsedArgs
+ *       evidence: string | null, out: string | null }
+ *   | { kind: 'claim', evidence: string, head: string, plan: string | null, gate: boolean,
+ *       tps: readonly { id: number, outcome: 'PASS' | 'FAIL' | 'SKIP', exit: string | null }[] }} ParsedArgs
  */
 
 /** @type {ParsedArgs} */
@@ -423,9 +466,45 @@ function parseArgs(argv) {
     // An absent flag is the ladder's "unrecognised": it can never read READY.
     return { kind: 'readiness', pr, requireNonAuthor: needed === null ? 'unrecognised' : needed, evidence, out };
   }
+  if (sub === 'claim') return parseClaimArgs(tail);
   return USAGE_ARGS;
 }
 
+/**
+ * D-CLAIM-APPEND: `claim` takes its flags first, then either the one word `gate` or
+ * one to CAPS.TPS `TP-<n>=<outcome>[:<exit>]` arguments, each TP at most once. A bad
+ * flag or argument is a usage error. `--head` is not checked here: a value that is not
+ * one SHA is a refusal with a line, since the caller passes what its report shows.
+ *
+ * @param {readonly string[]} tail
+ * @returns {ParsedArgs}
+ */
+function parseClaimArgs(tail) {
+  let flagCount = 0;
+  while (flagCount < tail.length && tail[flagCount].startsWith('--')) flagCount += 2;
+  const f = parseFlags(tail.slice(0, flagCount), { '--evidence': 'value', '--head': 'value', '--plan': 'value' });
+  const evidence = f === null ? null : flagValue(f, '--evidence');
+  const head = f === null ? null : flagValue(f, '--head');
+  const plan = f === null ? null : flagValue(f, '--plan');
+  const items = tail.slice(flagCount);
+  if (evidence === null || head === null || items.length === 0 || items.length > CAPS.TPS) return USAGE_ARGS;
+  if (items.length === 1 && items[0] === 'gate') {
+    return plan === null ? { kind: 'claim', evidence, head, plan, gate: true, tps: [] } : USAGE_ARGS;
+  }
+  const tps = [];
+  for (const item of items) {
+    const m = CLAIM_ARG_RE.exec(item);
+    if (m === null || m.groups === undefined) return USAGE_ARGS;
+    tps.push({
+      id: Number(m.groups.n),
+      outcome: /** @type {'PASS' | 'FAIL' | 'SKIP'} */ (m.groups.outcome),
+      exit: m.groups.exit === undefined ? null : m.groups.exit,
+    });
+  }
+  if (new Set(tps.map(tp => tp.id)).size !== tps.length) return USAGE_ARGS;
+  return { kind: 'claim', evidence, head, plan, gate: false, tps };
+}
+
 // ---------------------------------------------------------------------------
 // Bounded file I/O
 // ---------------------------------------------------------------------------
@@ -516,6 +595,97 @@ function writeTextFile(filePath, text) {
   }
 }
 
+/**
+ * Append `text` to `filePath` in one write, creating the file when it is absent. The same
+ * refusals as writeTextFile apply: a path that exists and is not a regular file, a link
+ * put in its place (O_NOFOLLOW), a FIFO (O_NONBLOCK). A write that does not complete
+ * cuts the file back to its length before the append, or removes the file when this call
+ * created it, so a failed append leaves no part of `text`. Returns whether it was written.
+ *
+ * @param {string} filePath
+ * @param {string} text
+ * @returns {boolean}
+ */
+function appendTextFile(filePath, text) {
+  let fd;
+  let created = false;
+  try {
+    const st = fs.lstatSync(filePath, { throwIfNoEntry: false });
+    if (st !== undefined && !st.isFile()) return false;
+    created = st === undefined;
+    const c = fs.constants;
+    fd = fs.openSync(filePath, c.O_WRONLY | c.O_APPEND | c.O_CREAT | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0), 0o600);
+    const before = fs.fstatSync(fd);
+    if (!before.isFile()) return false;
+    const bytes = Buffer.from(text, 'utf8');
+    try {
+      if (fs.writeSync(fd, bytes) === bytes.length) return true;
+    } catch (_) { /* cut back below */ }
+    try { fs.ftruncateSync(fd, before.size); } catch (_) { /* the write already failed */ }
+    if (created) fs.unlinkSync(filePath);
+    return false;
+  } catch (_) {
+    return false;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (_) { /* the write already decided */ }
+    }
+  }
+}
+
+/**
+ * Replace the regular file `filePath` with `text` and keep its `mode`: the text goes to a
+ * sibling temporary file, in the same folder, which a rename then puts in the file's place.
+ * It refuses first what appendTextFile refuses, so the two writes of a claim agree: a file
+ * this process may not write, a link put in its place (O_NOFOLLOW), a FIFO (O_NONBLOCK) or
+ * any other object that is not a regular file. The probe opens the file for an append and
+ * writes nothing. A write that fails leaves the file as it was and the temporary file
+ * removed, so a failed replace never truncates it. The temporary file is created new
+ * (O_EXCL) and never through a link (O_NOFOLLOW), and takes the old mode on its own
+ * descriptor, since the umask would otherwise set the new file's mode. Returns whether the
+ * file was replaced.
+ *
+ * @param {string} filePath
+ * @param {string} text
+ * @param {number} mode  the permission bits of the file it replaces
+ * @returns {boolean}
+ */
+function replaceTextFile(filePath, text, mode) {
+  const c = fs.constants;
+  let probe;
+  try {
+    probe = fs.openSync(filePath, c.O_WRONLY | c.O_APPEND | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0));
+    if (!fs.fstatSync(probe).isFile()) return false;
+  } catch (_) {
+    return false;
+  } finally {
+    if (probe !== undefined) {
+      try { fs.closeSync(probe); } catch (_) { /* the probe wrote nothing */ }
+    }
+  }
+  const temp = path.join(path.dirname(filePath), '.' + path.basename(filePath) + '.claim-' + process.pid);
+  let fd;
+  try {
+    fd = fs.openSync(temp, c.O_WRONLY | c.O_CREAT | c.O_EXCL | (c.O_NOFOLLOW || 0), 0o600);
+  } catch (_) {
+    return false;
+  }
+  try {
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, text, 'utf8');
+    fs.closeSync(fd);
+    fd = undefined;
+    fs.renameSync(temp, filePath);
+    return true;
+  } catch (_) {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (_) { /* the write already failed */ }
+    }
+    try { fs.unlinkSync(temp); } catch (_) { /* the temporary file is already gone */ }
+    return false;
+  }
+}
+
 /**
  * @param {string} dir
  * @returns {boolean}
@@ -753,13 +923,18 @@ function trackedState(io, file) {
  * the write failure (exit 3): no file is written. An `--evidence` file that is not
  * clearly untracked is dropped, so the run goes on exactly as if `--evidence` was not
  * given; the stderr summary then carries the closed note `evidence-ignored`. Stdout
- * keeps its grammar.
+ * keeps its grammar. A `claim` run has its own refusal line for each of these cases
+ * (claimRefusalReason).
  *
  * @param {Io} io
  * @param {ParsedArgs} args
  * @returns {{ args: ParsedArgs } | { outcome: Outcome }}
  */
 function admitPaths(io, args) {
+  if (args.kind === 'claim') {
+    const reason = claimRefusalReason(io, args);
+    return reason === null ? { args } : { outcome: claimRefusal(reason) };
+  }
   if (args.kind !== 'verify' && args.kind !== 'publish' && args.kind !== 'readiness') return { args };
   const outs = args.kind === 'verify' ? [args.blockOut, args.commentOut, args.staleOut]
     : args.kind === 'readiness' ? [args.out] : [];
@@ -1424,7 +1599,16 @@ function runsAt(io, memo, sha) {
  */
 function loadEvidence(file) {
   const text = readTextFile(file);
-  if (text === null) return null;
+  return text === null ? null : parseEvidenceText(text);
+}
+
+/**
+ * The sections of an evidence file's text, parsed (see loadEvidence).
+ *
+ * @param {string} text
+ * @returns {EvidenceInput | null}  null when unusable
+ */
+function parseEvidenceText(text) {
   const sections = PE.evidenceSections(text);
   if (!sections.ok) return null;
   let plan = null;
@@ -2026,6 +2210,21 @@ const COMPLIANCE_UNREADABLE_LINE = 'TRACEABILITY: DEGRADED (compliance state unr
 /** Every line a `publish` that did not run may print. The boundary admits each one with exit 2 only. */
 const PUBLISH_REFUSAL_LINES = Object.freeze([EVIDENCE_UNAVAILABLE_LINE, COMPLIANCE_OFF_LINE, COMPLIANCE_UNREADABLE_LINE]);
 
+/** The answer of every `publish` that could not give its block: the one line, exit 2. */
+const PUBLISH_UNAVAILABLE = Object.freeze({ code: EXIT_CODES.INPUT_UNUSABLE, stdout: EVIDENCE_UNAVAILABLE_LINE + '\n' });
+
+/**
+ * Whether argv asks for `publish`. The boundary reads it after any failure, a usage
+ * error and a throw included, so settleOutcome can answer a failed `publish` with
+ * PUBLISH_UNAVAILABLE.
+ *
+ * @param {readonly string[]} argv  process.argv
+ * @returns {boolean}
+ */
+function isPublishRun(argv) {
+  return Array.isArray(argv) && argv[2] === 'publish';
+}
+
 /**
  * @typedef {{ status: string, reason: string | null }} Part
  *   One half of the `publish` answer: a closed status, or `DEGRADED` with its reason.
@@ -2077,8 +2276,26 @@ function traceReasons(body, comment) {
 }
 
 /**
- * The `## PR Evidence` block of the update-pr-evidence contract, then its TRACEABILITY
- * lines.
+ * The test-plan tally that both scripted blocks print: `<verified>/<total>`, the given
+ * word, then the two counts that make up `verified`. The readiness block prints it with
+ * no word and the publish block with ` verified`.
+ *
+ * @param {{ total: number, counts: Readonly<Record<string, number>> }} fields  the parsed EVIDENCE line
+ * @param {'' | ' verified'} word
+ * @returns {string}
+ */
+function planTally(fields, word) {
+  const verifiedCi = fields.counts['VERIFIED-CI'];
+  const attestedLocal = fields.counts['ATTESTED-LOCAL'];
+  return (verifiedCi + attestedLocal) + '/' + fields.total + word
+    + ' (VERIFIED-CI ' + verifiedCi + ', ATTESTED-LOCAL ' + attestedLocal + ')';
+}
+
+/**
+ * The `## PR Evidence` block of the update-pr-evidence contract: the EVIDENCE line, the
+ * `Test plan:` line read from it, the Body and Comment line, then its TRACEABILITY lines.
+ * The caller holds the precondition that `evidenceLine` parses; a line that does not is a
+ * broken invariant, which the catch in main turns into "evidence unavailable".
  *
  * @param {string} evidenceLine
  * @param {Part} body
@@ -2086,9 +2303,12 @@ function traceReasons(body, comment) {
  * @returns {string}
  */
 function renderPublishBlock(evidenceLine, body, comment) {
+  const evidence = PE.parseEvidenceLine(evidenceLine);
+  if (!evidence.ok) throw new Error('verify-evidence: unchecked evidence line');
   const lines = [
     '## PR Evidence',
     evidenceLine,
+    'Test plan: ' + planTally(evidence.value, ' verified'),
     '**Body**: ' + partText(body) + ' · **Comment**: ' + partText(comment),
     ...traceReasons(body, comment).map(r => 'TRACEABILITY: DEGRADED (' + r + ')'),
   ];
@@ -2110,8 +2330,8 @@ function parsePart(text, statuses) {
 
 /**
  * D-OP-BLOCK-GATE: read a `publish` block back into its parts, or null when it is not
- * exactly what renderPublishBlock prints. The boundary prints a block only when this
- * accepts it.
+ * exactly what renderPublishBlock prints, so a `Test plan:` line that disagrees with the
+ * EVIDENCE line is refused. The boundary prints a block only when this accepts it.
  *
  * @param {string} text  the whole stdout, its final newline included
  * @returns {{ evidenceLine: string, body: Part, comment: Part } | null}
@@ -2119,9 +2339,9 @@ function parsePart(text, statuses) {
 function parsePublishBlock(text) {
   if (typeof text !== 'string' || !text.endsWith('\n') || text.length > 8192) return null;
   const lines = text.slice(0, -1).split('\n');
-  if (lines.length < 3 || lines.length > 5 || lines[0] !== '## PR Evidence') return null;
+  if (lines.length < 4 || lines.length > 6 || lines[0] !== '## PR Evidence') return null;
   if (!PE.parseEvidenceLine(lines[1]).ok) return null;
-  const m = PUBLISH_PARTS_RE.exec(lines[2]);
+  const m = PUBLISH_PARTS_RE.exec(lines[3]);
   if (m === null || m.groups === undefined) return null;
   const body = parsePart(m.groups.body, BODY_STATUSES);
   const comment = parsePart(m.groups.comment, COMMENT_STATUSES);
@@ -2138,7 +2358,7 @@ function parsePublishBlock(text) {
  */
 function evidenceUnavailable(io, reason) {
   io.stderr('verify-evidence: publish: ' + reason + '\n');
-  return { code: EXIT_CODES.INPUT_UNUSABLE, stdout: EVIDENCE_UNAVAILABLE_LINE + '\n' };
+  return PUBLISH_UNAVAILABLE;
 }
 
 /**
@@ -2826,9 +3046,7 @@ function readinessPass(io, args, deps) {
       : String(threads.value.unresolved),
     decision: decisionText,
     ci: ci.status,
-    plan: evidence === null ? 'unavailable'
-      : (evidence.verifiedCi + evidence.attestedLocal) + '/' + evidence.total
-        + ' (VERIFIED-CI ' + evidence.verifiedCi + ', ATTESTED-LOCAL ' + evidence.attestedLocal + ')',
+    plan: fields === null ? 'unavailable' : planTally(fields, ''),
     approval: approvalText(args.requireNonAuthor, evidence),
   };
   return { outcome: { code: EXIT_CODES.OK, stdout: renderReadinessBlock(block) }, head };
@@ -2922,6 +3140,289 @@ function runReadiness(io, args, deps) {
   return args.out === null ? pass.outcome : writeReadinessOut(io, args.out, args.pr, pass.outcome, pass.head, planSource(args));
 }
 
+// ---------------------------------------------------------------------------
+// claim — D-CLAIM-APPEND
+// ---------------------------------------------------------------------------
+//
+// A Test or Validate report becomes claim lines in the evidence file. The caller passes
+// only the facts of its report (the HEAD, the gate, one outcome per TP). This script owns
+// the rest: the line shapes (the claim parser of pr-evidence.cjs accepts each one before
+// it is written), the HEAD rule, the exit range, the `## Claims` section and the append.
+// A claim is an input to `verify`, never a state: only pr-evidence.cjs and `verify`
+// assign states.
+
+/**
+ * @param {string} reason  one of the CLAIM_REFUSAL_RE reasons
+ * @returns {Outcome}
+ */
+function claimRefusal(reason) {
+  return { code: EXIT_CODES.INPUT_UNUSABLE, stdout: 'CLAIM refused (' + reason + ')\n' };
+}
+
+/** The most folders one path can hold: the bound of the walk up to the nearest folder that exists. */
+const FOLDER_DEPTH_MAX = 4096;
+
+/**
+ * Whether `child` lies below `parent`, by name alone. `parent` itself, and a path outside
+ * it, are not below it.
+ *
+ * @param {string} parent  absolute
+ * @param {string} child  absolute
+ * @returns {boolean}
+ */
+function isBelow(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel !== '' && rel !== '..' && !rel.startsWith('..' + path.sep) && !path.isAbsolute(rel);
+}
+
+/**
+ * D-CLAIM-FOLDER: the folder of the evidence file exists, or this run makes it. The Write
+ * tool made the folders of a file in 3.11.0, so a first claim into a folder that is not
+ * there yet worked. A run makes a folder only inside the working directory: the folder lies
+ * below `io.cwd` by name, and the nearest folder that already exists resolves to `io.cwd` or
+ * below it, so a link out of the working directory makes nothing. Each folder it makes goes
+ * to `io.made`, deepest first, for removeMadeFolders. A path that holds a file where a folder
+ * must be, or that the run may not make, is unusable. After each folder is made, its real path
+ * must lie below the real working directory; if a link swapped in after the first check led the
+ * folder out, the run is unusable and removeMadeFolders takes the folder away again. This check
+ * narrows the window for such a swap; it does not close it, because the later open of the
+ * evidence file resolves the path again.
+ *
+ * @param {Io} io
+ * @param {string} dir  absolute
+ * @returns {boolean}  whether the folder exists now
+ */
+function ensureClaimFolder(io, dir) {
+  if (isRealDirectory(dir)) return true;
+  try {
+    const root = path.resolve(io.cwd);
+    if (fs.lstatSync(dir, { throwIfNoEntry: false }) !== undefined || !isBelow(root, dir)) return false;
+    let near = dir;
+    for (let i = 0; i < FOLDER_DEPTH_MAX && fs.lstatSync(near, { throwIfNoEntry: false }) === undefined; i++) {
+      near = path.dirname(near);
+    }
+    const real = fs.realpathSync(near);
+    const realRoot = fs.realpathSync(root);
+    if (real !== realRoot && !isBelow(realRoot, real)) return false;
+    let at = near;
+    for (const part of path.relative(near, dir).split(path.sep)) {
+      at = path.join(at, part);
+      fs.mkdirSync(at);
+      io.made.unshift(at);
+      if (!isBelow(realRoot, fs.realpathSync(at))) return false;
+    }
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Take away the folders a `claim` run made. Each goes through rmdir, which refuses a folder
+ * that holds anything, so a folder that holds the evidence file, or a file another process
+ * put there, stays. It is never a recursive delete.
+ *
+ * @param {Io} io
+ * @returns {void}
+ */
+function removeMadeFolders(io) {
+  for (const dir of io.made.splice(0)) {
+    try { fs.rmdirSync(dir); } catch (_) { /* a folder that holds a file stays */ }
+  }
+}
+
+/**
+ * The reason a `claim` run must not start, or null. Nothing is read or written before
+ * this, but the folder of the evidence file, when it is missing: the HEAD is one 40-hex
+ * SHA, each path is a path the commands build, the evidence file sits in a folder that
+ * exists or that the run makes inside the working directory (D-CLAIM-FOLDER), and git says
+ * clearly that neither file is tracked (D-TRACKED-RESULT).
+ *
+ * @param {Io} io
+ * @param {Extract<ParsedArgs, { kind: 'claim' }>} args
+ * @returns {string | null}
+ */
+function claimRefusalReason(io, args) {
+  if (!SHA40_RE.test(args.head)) return 'head not one sha';
+  if (!EVIDENCE_PATH_RE.test(args.evidence) || !ensureClaimFolder(io, path.dirname(path.resolve(args.evidence)))) return 'evidence file unusable';
+  if (args.plan !== null && !EVIDENCE_PATH_RE.test(args.plan)) return 'plan file unusable';
+  if (trackedState(io, args.evidence) !== 'untracked') return 'evidence file tracked';
+  if (args.plan !== null && trackedState(io, args.plan) !== 'untracked') return 'plan file unusable';
+  return null;
+}
+
+/**
+ * Whether one line is exactly one claim to the claim parser of pr-evidence.cjs.
+ *
+ * @param {string} line
+ * @returns {boolean}
+ */
+function claimLineOk(line) {
+  const r = PE.parseClaims(line);
+  if (!r.ok) return false;
+  const gates = r.value.gates;
+  return r.value.malformed === 0 && r.value.tp.size + (gates.validate === null ? 0 : 1) + (gates.qa === null ? 0 : 1) === 1;
+}
+
+/**
+ * Assert a line before it is written: one claim to the claim parser. Every caller builds
+ * the line from parts that are already checked; this is that precondition held at the sink.
+ *
+ * @param {string} line
+ * @returns {string}
+ */
+function claimLine(line) {
+  if (!claimLineOk(line)) throw new Error('verify-evidence: unchecked claim line');
+  return line;
+}
+
+/**
+ * The text to append: the lines, behind the `## Claims` heading when the file has no such
+ * section (a blank line first, when the file holds anything). The caller appends only when
+ * the section is the last of the file, so the lines go at its end.
+ *
+ * @param {string} text  the evidence file as it is, '' when it is absent
+ * @param {boolean} hasSection
+ * @param {readonly string[]} lines
+ * @returns {string}
+ */
+function claimAppendText(text, hasSection, lines) {
+  const body = lines.join('\n') + '\n';
+  if (text === '') return PE.CLAIMS_HEADING + '\n' + body;
+  const lead = text.endsWith('\n') ? '' : '\n';
+  return hasSection ? lead + body : lead + '\n' + PE.CLAIMS_HEADING + '\n' + body;
+}
+
+/**
+ * D-CLAIM-INSERT: the whole text with the lines put at the end of a `## Claims` section that
+ * another section follows: behind the last row of the section that is not blank, before the
+ * blank rows that precede the next heading. A row is blank as the parser of pr-evidence.cjs
+ * reads it, an empty row once its CR is gone. A text with no such section comes back as it was.
+ *
+ * @param {string} text
+ * @param {readonly string[]} lines
+ * @returns {string}
+ */
+function claimInsertText(text, lines) {
+  const rows = text.split('\n');
+  /** @param {string} row @returns {string} */
+  const bare = row => row.replace(/\r$/, '');
+  const start = rows.findIndex(row => bare(row) === PE.CLAIMS_HEADING);
+  if (start === -1) return text;
+  let end = rows.findIndex((row, i) => i > start && (bare(row) === '##' || bare(row).startsWith('## ')));
+  if (end === -1) end = rows.length;
+  let last = end - 1;
+  while (last > start && bare(rows[last]) === '') last--;
+  rows.splice(last + 1, 0, ...lines);
+  return rows.join('\n');
+}
+
+/**
+ * Whether `inserted` is `text` with the lines added at the end of its `## Claims` section and
+ * nothing else changed, as the parser of pr-evidence.cjs reads both: the Claims section grew by
+ * exactly the lines, its other sections are the same, and the result parses as an evidence file.
+ * This is the check the replace is held to before it writes.
+ *
+ * @param {string} text
+ * @param {string} inserted
+ * @param {readonly string[]} lines
+ * @returns {boolean}
+ */
+function claimInserted(text, inserted, lines) {
+  const before = PE.evidenceSections(text);
+  const after = PE.evidenceSections(inserted);
+  if (!before.ok || !after.ok || before.value.claims === null) return false;
+  return after.value.claims === before.value.claims + '\n' + lines.join('\n')
+    && after.value.testPlan === before.value.testPlan
+    && after.value.exceptions === before.value.exceptions
+    && parseEvidenceText(inserted) !== null;
+}
+
+/**
+ * The TP numbers the plan lists: the `## Test Plan` of the `--plan` file, else of the
+ * evidence file. A plan with no TP line, or no plan section, lists none. Null when the
+ * `--plan` file cannot serve as a plan.
+ *
+ * @param {Extract<ParsedArgs, { kind: 'claim' }>} args
+ * @param {EvidenceInput} evidence
+ * @returns {Set<number> | null}
+ */
+function claimPlanIds(args, evidence) {
+  let plan = evidence.plan;
+  if (args.plan !== null) {
+    const text = readTextFile(args.plan);
+    const parsed = text === null ? null : PE.parsePlan(sectionOrWhole(text, 'testPlan'));
+    if (parsed === null || (!parsed.ok && parsed.error.code !== 'empty')) return null;
+    plan = parsed.ok ? parsed.value : { tps: [] };
+  }
+  return new Set((plan === null ? [] : plan.tps).map(tp => tp.id));
+}
+
+/**
+ * D-CLAIM-APPEND: `claim`. The checks of claimRefusalReason have passed (admitPaths).
+ * The evidence file is read as `verify` reads it; a file that does not parse is refused, as
+ * `verify` refuses it. Then every line is built and checked, and one write puts them all in.
+ * That write is an append when the `## Claims` section is the last section or is absent. When
+ * another section follows it, the write is a whole-file replace (D-CLAIM-INSERT) that adds the
+ * lines at the end of the Claims section, held to claimInserted before it writes. One claim
+ * run writes at a time, as the commands run it. A run that writes no line (every TP off the
+ * plan) changes no file.
+ *
+ * @param {Io} io
+ * @param {Extract<ParsedArgs, { kind: 'claim' }>} args
+ * @returns {Outcome}
+ */
+function runClaim(io, args) {
+  const file = path.resolve(args.evidence);
+  /** @type {fs.Stats | undefined} */
+  let st;
+  try {
+    st = fs.lstatSync(file, { throwIfNoEntry: false });
+  } catch (_) {
+    return claimRefusal('evidence file unusable');
+  }
+  if (st !== undefined && !st.isFile()) return claimRefusal('evidence file unusable');
+  const text = st === undefined ? '' : readTextFile(file);
+  const evidence = text === null ? null : parseEvidenceText(text);
+  if (text === null || evidence === null) return claimRefusal('evidence file unusable');
+  const headings = text.split('\n').map(row => row.replace(/\r$/, '')).filter(row => row === '##' || row.startsWith('## '));
+  const hasSection = headings.includes(PE.CLAIMS_HEADING);
+  const sectionFollowed = hasSection && headings[headings.length - 1] !== PE.CLAIMS_HEADING;
+  const listed = args.gate ? new Set() : claimPlanIds(args, evidence);
+  if (listed === null) return claimRefusal('plan file unusable');
+
+  /** @type {string[]} */
+  const lines = [];
+  const tally = { PASS: 0, FAIL: 0, SKIP: 0 };
+  if (args.gate) {
+    lines.push(claimLine('- gate:validate PASS sha:' + args.head + ' by:validate'));
+    tally.PASS++;
+  }
+  for (const tp of args.tps) {
+    if (!listed.has(tp.id)) continue;
+    const bare = '- TP-' + tp.id + ' ' + tp.outcome + ' sha:' + args.head + ' by:test';
+    const withExit = tp.exit === null ? bare : bare + ' exit:' + tp.exit;
+    lines.push(claimLine(claimLineOk(withExit) ? withExit : bare));
+    tally[tp.outcome]++;
+  }
+  if (lines.length > 0) {
+    let written;
+    if (sectionFollowed) {
+      const inserted = claimInsertText(text, lines);
+      if (!claimInserted(text, inserted, lines)) return claimRefusal('evidence file unusable');
+      written = replaceTextFile(file, inserted, st === undefined ? 0o600 : st.mode & 0o777);
+    } else {
+      written = appendTextFile(file, claimAppendText(text, hasSection, lines));
+    }
+    if (!written) return refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
+  }
+  const skipped = args.gate ? 0 : args.tps.length - lines.length;
+  return {
+    code: EXIT_CODES.OK,
+    stdout: 'CLAIM appended:' + lines.length + ' PASS:' + tally.PASS + ' FAIL:' + tally.FAIL + ' SKIP:' + tally.SKIP + ' skipped:' + skipped + '\n',
+  };
+}
+
 // ---------------------------------------------------------------------------
 // main — returns {code, stdout}; never calls process.exit
 // ---------------------------------------------------------------------------
@@ -2984,6 +3485,7 @@ function main(argv, deps) {
     deadline: now() + DEADLINE_MS,
     budget: { ghCalls: 0, runViews: 0, throttled: false },
     notes: new Set(),
+    made: [],
     stderr: typeof d.stderr === 'function' ? d.stderr : (text => { process.stderr.write(text); }),
   };
   const parsed = parseArgs(argv);
@@ -3005,6 +3507,7 @@ function main(argv, deps) {
       else if (args.kind === 'splice') outcome = runSplice(io, args);
       else if (args.kind === 'publish') outcome = runPublish(io, args, d);
       else if (args.kind === 'readiness') outcome = runReadiness(io, args, d);
+      else if (args.kind === 'claim') outcome = runClaim(io, args);
       else outcome = runReadback(io, args);
     }
   } catch (err) {
@@ -3019,6 +3522,7 @@ function main(argv, deps) {
       if (args.out !== null) outcome = writeReadinessOut(io, args.out, args.pr, outcome, null, planSource(args));
     } else outcome = refuse(io, EXIT_CODES.REMOTE_FAILURE, label);
   }
+  removeMadeFolders(io);
   if (io.notes.size > 0) io.stderr('verify-evidence: notes: ' + [...io.notes].sort().join(',') + '\n');
   return outcome;
 }
@@ -3038,12 +3542,26 @@ function errorLabel(err) {
 /**
  * D-VERIFY-STDOUT: settle whatever main() returned into what the boundary may
  * print. The code must be a known exit code and stdout must be empty or one of
- * the closed shapes for that code; anything else prints nothing and exits 4.
+ * the closed shapes for that code; anything else prints nothing and exits 4. A
+ * `publish` run is the exception: it never settles to empty stdout, so what would
+ * print nothing prints the evidence unavailable line with exit 2.
  *
  * @param {unknown} outcome
+ * @param {boolean} [publish]  true when the run is a `publish`
  * @returns {Outcome}
  */
-function settleOutcome(outcome) {
+function settleOutcome(outcome, publish) {
+  const settled = settleShape(outcome);
+  return publish === true && settled.stdout === '' ? PUBLISH_UNAVAILABLE : settled;
+}
+
+/**
+ * The shape check of settleOutcome, for every subcommand.
+ *
+ * @param {unknown} outcome
+ * @returns {Outcome}
+ */
+function settleShape(outcome) {
   const o = /** @type {any} */ (outcome);
   const failed = { code: EXIT_CODES.REMOTE_FAILURE, stdout: '' };
   if (o === null || typeof o !== 'object' || typeof o.stdout !== 'string') return failed;
@@ -3073,6 +3591,14 @@ function settleOutcome(outcome) {
     const passing = readback.groups.outcome === 'ok';
     return o.code === (passing ? EXIT_CODES.OK : EXIT_CODES.OUTPUT_GATE_REFUSED) ? { code: o.code, stdout: o.stdout } : failed;
   }
+  const claimRefused = CLAIM_REFUSAL_RE.exec(text);
+  if (claimRefused !== null) return o.code === EXIT_CODES.INPUT_UNUSABLE ? pass : failed;
+  const claimed = CLAIM_APPENDED_RE.exec(text);
+  if (claimed !== null && claimed.groups !== undefined) {
+    const g = claimed.groups;
+    const sums = Number(g.n) === Number(g.pass) + Number(g.fail) + Number(g.skip);
+    return o.code === EXIT_CODES.OK && sums && Number(g.n) <= CAPS.TPS && Number(g.skipped) <= CAPS.TPS ? pass : failed;
+  }
   if (o.code !== EXIT_CODES.OK) return failed;
   if (PE.parseEvidenceLine(text).ok) return { code: o.code, stdout: o.stdout };
   const block = PE.parseBlock(text);
@@ -3094,7 +3620,7 @@ if (require.main === module) {
     process.stderr.write('verify-evidence: internal error (' + errorLabel(err) + ')\n');
     outcome = { code: EXIT_CODES.REMOTE_FAILURE, stdout: '' };
   }
-  const settled = settleOutcome(outcome);
+  const settled = settleOutcome(outcome, isPublishRun(process.argv));
   if (settled.stdout !== '') process.stdout.write(settled.stdout);
   process.exitCode = settled.code;
 }