devflow-kit 3.8.0 → 3.10.0

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

@@ -10,6 +10,7 @@
 //
 // Usage:
 //   node verify-evidence.cjs check tp|block|exceptions|wave <file>
+//   node verify-evidence.cjs check wave --links-only <file>
 //   node verify-evidence.cjs render --plan <file>
 //   node verify-evidence.cjs verify --pr <n> [--publication <mode>] [--evidence <file>]
 //        [--state <dir>] [--block-out <file>] [--comment-out <file>] [--stale-out <file>] [--approval]
@@ -17,11 +18,15 @@
 //   node verify-evidence.cjs readback --pr <n> --expect <file>
 //   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>]
 //
 // 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):
-//   check     nothing — the exit code is the answer; the diagnostic is on stderr
-//   render    the creation block: markers, `## Test Plan`, every TP unticked
+//   check     nothing — the exit code is the answer; the diagnostic is on stderr.
+//             `check wave --links-only` also admits the links-only wave block (the
+//             `## Related Issues` heading and `Refs #<n>` or `Refs <KEY-N>` lines, no
+//             evidence section); plain `check wave` refuses that block as malformed
+//   render   the creation block: markers, `## Test Plan`, every TP unticked
 //   verify    EVIDENCE pr:<n> head:<sha> total:<n> VERIFIED-CI:<n> ATTESTED-LOCAL:<n>
 //             UNVERIFIED:<n> STALE:<n> FAILED:<n> INDETERMINATE:<n> stale:<ids|none>
 //             exceptions:<kinds|none> approval:<yes|no|unchecked> key:<hex>
@@ -30,11 +35,34 @@
 //   readback  READBACK ok (exit 0) or READBACK mismatch (exit 5)
 //   publish   the `## PR Evidence` block — the heading, the EVIDENCE line, one
 //             `**Body**: … · **Comment**: …` line — then one `TRACEABILITY: DEGRADED
-//             (<reason>)` line per degraded part (exit 0), or the one line
-//             `TRACEABILITY: DEGRADED (evidence unavailable)` (exit 2)
+//             (<reason>)` line per degraded part (exit 0), or exit 2 with one line:
+//             `TRACEABILITY: DEGRADED (evidence unavailable)` when it could not run,
+//             `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
+//             any gh call, from the machine manifest alone
 //   readiness the `## Merge Readiness` block (exit 0), or the same block with
 //             `**Status**: DEGRADED (<reason>)` and one `TRACEABILITY: DEGRADED
-//             (<reason>)` line after it (exit 2)
+//             (<reason>)` line after it (exit 2). `--evidence <file>` reads the test
+//             plan and the claims from a local evidence file, as `verify --evidence`
+//             does. `--out <file>` also writes the file `READINESS pr:<n>
+//             head:<40hex|none> status:<READY|NOT_READY|DEGRADED> source=<local|pr>`
+//             (one line; wrapped here), then that same block. `source=local` names
+//             the `--evidence` file as the plan's source and `source=pr` names the
+//             PR's own record. Stdout does not change, and the command makes no
+//             remote write.
+//             A file an earlier run left at the out path never outlives this run: it
+//             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
+// 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
+// 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
+// answer for, is refused as a write failure (exit 3, empty stdout) and left untouched.
 // No byte of a PR body, a comment, a review or a gh/git answer is ever printed: the
 // boundary re-checks every stdout line against these shapes before writing it.
 //
@@ -59,7 +87,8 @@
 //     `require.main === module` boundary is the only stdout write and the only
 //     exitCode assignment
 //   - every subprocess is spawned with an argv array (never a shell), stdin
-//     ignored, a timeout and a maxBuffer; every loop and every API fan-out has a
+//     ignored and a maxBuffer, and every one but the local tracked-file check
+//     (D-TRACKED-RESULT) has a timeout; every loop and every API fan-out has a
 //     fixed bound, and the whole run has a wall-clock deadline
 //   - a revision reaches git only after SHA_RE, so none can start with `-`; `--`
 //     ends the revision list of the one command that takes a pathspec (diff)
@@ -75,9 +104,10 @@ const crypto = require('crypto');
 const childProcess = require('child_process');
 
 const PE = require(path.join(__dirname, 'pr-evidence.cjs'));
-// D-READINESS-CLASSIFIER: the CI classification is ci-wait's own, so the two scripts
-// cannot disagree. Its main is guarded by `require.main === module`: requiring it
-// starts nothing.
+// D-READINESS-CLASSIFIER: the CI classifier, the merge gate and the workflow-list probe
+// are ci-wait's own, so the two scripts cannot disagree; only ci-wait polls until its
+// deadline, since readiness makes one read. Its main is guarded by
+// `require.main === module`: requiring it starts nothing.
 const CW = require(path.join(__dirname, 'ci-wait.cjs'));
 
 // ---------------------------------------------------------------------------
@@ -123,11 +153,13 @@ const DEADLINE_MS = 90000;
 /**
  * D-PUBLISH-BOUNDS: `publish` runs `verify` under the deadline above, then its writes
  * under a deadline of their own and a gh budget of their own. The writes are at most
- * seven calls: two body reads (the compare-and-swap), a body edit and one retry, one
- * read-back, a comment and one retry. A scrub is bounded by its own timeout, not by
- * the deadline, so one that starts just before the writes' deadline can end up to
- * REDACT_TIMEOUT_MS after it. The worst case is 90 s + 60 s + 20 s; the caller's
- * 180 s Bash timeout covers it with room for node's startup.
+ * eight calls: two body reads (the compare-and-swap), a body edit and one retry, one
+ * read-back, then the comment. A new comment is a post and one retry (seven in all).
+ * An edit of the viewer's own comment is the edit, one retry and one read of the
+ * comment (eight in all). A scrub is bounded by its own timeout, not by the deadline,
+ * so one that starts just before the writes' deadline can end up to REDACT_TIMEOUT_MS
+ * after it. The worst case is 90 s + 60 s + 20 s; the caller's 180 s Bash timeout
+ * covers it with room for node's startup.
  */
 const PUBLISH_DEADLINE_MS = 60000;
 const PUBLISH_GH_CALLS = 8;
@@ -151,9 +183,12 @@ const PR_VIEW_MAX_BUFFER = 64 * 1024 * 1024;
 const RUN_LIST_MAX_BUFFER = 1024 * 1024;
 const RUN_VIEW_MAX_BUFFER = 65536;
 const LINE_MAX_BUFFER = 4096;
+/** A comment read back as a JSON string: 65,536 characters, each escaped to six, fit. */
+const COMMENT_READ_MAX_BUFFER = 8 * 65536;
 /** `gh pr checks` and the thread-count GraphQL answer: a thousand rows of names fit. */
 const READINESS_MAX_BUFFER = 4 * 1024 * 1024;
-const READINESS_MAX_CHECKS = 1000;
+/** Where line 1 of the readiness out file says the test plan came from: the `--evidence` file, or the PR's own record. */
+const READINESS_SOURCES = Object.freeze(['local', 'pr']);
 /** 5,000 paths of 4,096 bytes overflow this; an overflow reads as an unresolved diff. */
 const DIFF_MAX_BUFFER = 16 * 1024 * 1024;
 const FETCH_MAX_BUFFER = 1024 * 1024;
@@ -173,6 +208,14 @@ const PR_FIELDS = 'body,comments,reviews,author,headRefOid,baseRefOid,isCrossRep
 const PR_RE = /^[1-9][0-9]{0,9}$/;
 const SHA40_RE = /^[0-9a-f]{40}$/;
 
+/**
+ * A pull-request comment's url, anchored: the pull number, then the numeric id in the
+ * fragment. The host is not pinned (GitHub Enterprise Server hosts work). There is no
+ * `m` flag, so `$` is the end of the string and a trailing newline is refused.
+ */
+const COMMENT_URL_RE = /^https:\/\/[^/\s?#]+\/[^/\s?#]+\/[^/\s?#]+\/pull\/([1-9][0-9]{0,9})#issuecomment-([1-9][0-9]{0,19})$/;
+/** A comment id as a string of digits: up to 20, so an id beyond 2^53 stays exact. */
+const COMMENT_ID_RE = /^[1-9][0-9]{0,19}$/;
 /** A review state that decides a login's position on the PR (D6). */
 const DECISIVE_REVIEW_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'DISMISSED']);
 
@@ -182,6 +225,7 @@ const READBACK_LINE_RE = /^READBACK (?<outcome>ok|mismatch)$/;
 
 const USAGE = [
   'Usage: node verify-evidence.cjs check tp|block|exceptions|wave <file>',
+  '       node verify-evidence.cjs check wave --links-only <file>',
   '       node verify-evidence.cjs render --plan <file>',
   '       node verify-evidence.cjs verify --pr <n> [--publication <mode>] [--evidence <file>]',
   '            [--state <dir>] [--block-out <file>] [--comment-out <file>] [--stale-out <file>] [--approval]',
@@ -189,6 +233,7 @@ const USAGE = [
   '       node verify-evidence.cjs readback --pr <n> --expect <file>',
   '       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>]',
 ].join('\n');
 
 // ---------------------------------------------------------------------------
@@ -215,7 +260,8 @@ const USAGE = [
  *   summary, never input bytes. `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 }} PrComment
+ * @typedef {{ login: string, association: string, body: string, viewerDidAuthor: boolean, commentId: string }} PrComment
+ *   `commentId` is the comment's numeric id as digits, or '' when its url did not parse.
  * @typedef {{ login: string, association: string, state: string }} PrReview
  * @typedef {{ number: number, head: string, base: string, body: string, author: string,
  *   isCrossRepository: boolean | undefined, comments: readonly PrComment[],
@@ -223,8 +269,9 @@ const USAGE = [
  *   The one `gh pr view` answer, parsed. Lists are chronological, newest last.
  *
  * @typedef {{ exec?: ExecFn, cwd?: string, now?: () => number, stderr?: (text: string) => void,
- *   formatLine?: (fields: object) => unknown }} MainDeps
- *   Injected by tests only; `formatLine` reaches the output gate.
+ *   formatLine?: (fields: object) => unknown, manifestPath?: string }} MainDeps
+ *   Injected by tests only; `formatLine` reaches the output gate. `manifestPath` replaces
+ *   the machine manifest that `publish` reads; production always reads ~/.devflow/manifest.json.
  *
  * @typedef {{ code: number, stdout: string }} Outcome
  */
@@ -235,14 +282,15 @@ const USAGE = [
 
 /**
  * @typedef {{ kind: 'usage' }
- *   | { kind: 'check', what: 'tp' | 'block' | 'exceptions' | 'wave', file: string }
+ *   | { kind: 'check', what: 'tp' | 'block' | 'exceptions' | 'wave', file: string, linksOnly: boolean }
  *   | { kind: 'render', plan: string }
  *   | { kind: 'verify', pr: number, publication: string, evidence: string | null, state: string | null,
  *       blockOut: string | null, commentOut: string | null, staleOut: string | null, approval: boolean }
  *   | { kind: 'splice', pr: number, state: string, block: string, out: string }
  *   | { kind: 'readback', pr: number, expect: string }
  *   | { kind: 'publish', pr: number, publication: string, evidence: string | null }
- *   | { kind: 'readiness', pr: number, requireNonAuthor: 'true' | 'false' | 'unrecognised' }} ParsedArgs
+ *   | { kind: 'readiness', pr: number, requireNonAuthor: 'true' | 'false' | 'unrecognised',
+ *       evidence: string | null, out: string | null }} ParsedArgs
  */
 
 /** @type {ParsedArgs} */
@@ -303,10 +351,12 @@ function parseArgs(argv) {
   const sub = rest[0];
   const tail = rest.slice(1);
   if (sub === 'check') {
-    if (tail.length !== 2 || !['tp', 'block', 'exceptions', 'wave'].includes(tail[0])) return USAGE_ARGS;
-    const file = tail[1];
+    // `check wave --links-only <file>` is the one three-argument form: the links-only wave block is opt-in.
+    const linksOnly = tail.length === 3 && tail[0] === 'wave' && tail[1] === '--links-only';
+    if ((tail.length !== 2 && !linksOnly) || !['tp', 'block', 'exceptions', 'wave'].includes(tail[0])) return USAGE_ARGS;
+    const file = tail[tail.length - 1];
     if (typeof file !== 'string' || file === '' || file.startsWith('-') || file.length > MAX_ARG_CHARS) return USAGE_ARGS;
-    return { kind: 'check', what: /** @type {'tp' | 'block' | 'exceptions' | 'wave'} */ (tail[0]), file };
+    return { kind: 'check', what: /** @type {'tp' | 'block' | 'exceptions' | 'wave'} */ (tail[0]), file, linksOnly };
   }
   if (sub === 'render') {
     const f = parseFlags(tail, { '--plan': 'value' });
@@ -358,13 +408,20 @@ function parseArgs(argv) {
     return { kind: 'publish', pr, publication, evidence };
   }
   if (sub === 'readiness') {
-    const f = parseFlags(tail, { '--pr': 'value', '--require-non-author-approval': 'value' });
+    const f = parseFlags(tail, {
+      '--pr': 'value', '--require-non-author-approval': 'value', '--evidence': 'value', '--out': 'value',
+    });
     const pr = f === null ? null : parsePr(flagValue(f, '--pr'));
     if (f === null || pr === null) return USAGE_ARGS;
     const needed = flagValue(f, '--require-non-author-approval');
     if (needed !== null && needed !== 'true' && needed !== 'false') return USAGE_ARGS;
+    const evidence = flagValue(f, '--evidence');
+    const out = flagValue(f, '--out');
+    // The out file is never the evidence file: two spellings of one path (`./a.md` and `a.md`)
+    // and two names of one file (a hard link or a symlink) are both refused before any read.
+    if (evidence !== null && out !== null && (path.resolve(evidence) === path.resolve(out) || sameFile(evidence, out))) return USAGE_ARGS;
     // An absent flag is the ladder's "unrecognised": it can never read READY.
-    return { kind: 'readiness', pr, requireNonAuthor: needed === null ? 'unrecognised' : needed };
+    return { kind: 'readiness', pr, requireNonAuthor: needed === null ? 'unrecognised' : needed, evidence, out };
   }
   return USAGE_ARGS;
 }
@@ -373,6 +430,24 @@ function parseArgs(argv) {
 // Bounded file I/O
 // ---------------------------------------------------------------------------
 
+/**
+ * Whether two paths name one file: the same device and inode, links followed. A path
+ * that does not exist, or cannot be inspected, names no file.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function sameFile(a, b) {
+  try {
+    const first = fs.statSync(a, { bigint: true, throwIfNoEntry: false });
+    const second = fs.statSync(b, { bigint: true, throwIfNoEntry: false });
+    return first !== undefined && second !== undefined && first.dev === second.dev && first.ino === second.ino;
+  } catch (_) {
+    return false;
+  }
+}
+
 /**
  * Read a regular file of at most MAX_FILE_BYTES as strict UTF-8, or null. The
  * open adds O_NONBLOCK, so a FIFO put in a file's place cannot block, and the
@@ -414,19 +489,30 @@ function readTextFile(filePath) {
 /**
  * Write `text` to `filePath`, refusing anything that already exists and is not a
  * regular file (a directory, a FIFO, a symlink). Returns whether it was written.
+ * The lstat refuses first. The open adds O_NOFOLLOW, so a link put in the file's
+ * place after the lstat is refused, never followed, and O_NONBLOCK, so a FIFO put
+ * there cannot block; the fstat re-checks the opened object.
  *
  * @param {string} filePath
  * @param {string} text
  * @returns {boolean}
  */
 function writeTextFile(filePath, text) {
+  let fd;
   try {
     const st = fs.lstatSync(filePath, { throwIfNoEntry: false });
     if (st !== undefined && !st.isFile()) return false;
-    fs.writeFileSync(filePath, text, { encoding: 'utf8', mode: 0o600 });
+    const c = fs.constants;
+    fd = fs.openSync(filePath, c.O_WRONLY | c.O_CREAT | c.O_TRUNC | (c.O_NOFOLLOW || 0) | (c.O_NONBLOCK || 0), 0o600);
+    if (!fs.fstatSync(fd).isFile()) return false;
+    fs.writeFileSync(fd, text, 'utf8');
     return true;
   } catch (_) {
     return false;
+  } finally {
+    if (fd !== undefined) {
+      try { fs.closeSync(fd); } catch (_) { /* the write already decided */ }
+    }
   }
 }
 
@@ -492,12 +578,13 @@ function refusedCall(reason) {
 }
 
 /**
- * One bounded subprocess call, normalized. The argv array is a fresh copy.
+ * One bounded subprocess call, normalized. The argv array is a fresh copy. A null
+ * `timeout` sets no time limit on the call.
  *
  * @param {Io} io
  * @param {string} file
  * @param {readonly string[]} args
- * @param {number} timeout
+ * @param {number | null} timeout
  * @param {number} maxBuffer
  * @returns {CallResult}
  */
@@ -506,7 +593,7 @@ function runCall(io, file, args, timeout, maxBuffer) {
     cwd: io.cwd,
     env: io.env,
     stdio: ['ignore', 'pipe', 'pipe'],
-    timeout,
+    ...(timeout === null ? {} : { timeout }),
     maxBuffer,
     windowsHide: true,
     shell: false,
@@ -585,18 +672,103 @@ function gh(io, args, maxBuffer) {
 
 /**
  * Every git call: `-c core.fsmonitor=false` first, so no repository-configured
- * hook runs (D-NO-FSMONITOR), and bounded by the deadline.
+ * hook runs (D-NO-FSMONITOR), and refused once the deadline has passed. A null
+ * `timeout` sets no time limit on the call itself.
  *
  * @param {Io} io
  * @param {readonly string[]} args
- * @param {number} timeout
+ * @param {number | null} timeout
  * @param {number} maxBuffer
  * @returns {CallResult}
  */
 function git(io, args, timeout, maxBuffer) {
   const left = remaining(io);
   if (left === 0) { io.notes.add('deadline'); return refusedCall('deadline'); }
-  return runCall(io, 'git', ['-c', 'core.fsmonitor=false', ...args], Math.min(timeout, left), maxBuffer);
+  return runCall(io, 'git', ['-c', 'core.fsmonitor=false', ...args], timeout === null ? null : Math.min(timeout, left), maxBuffer);
+}
+
+// ---------------------------------------------------------------------------
+// Tracked files — D-TRACKED-RESULT
+// ---------------------------------------------------------------------------
+
+/** What git says, asked with LC_ALL=C, of a path that sits in no repository. */
+const NOT_A_REPOSITORY_RE = /\bnot a git repository\b/;
+
+/**
+ * D-TRACKED-RESULT: whether git tracks one absolute path, asked of the repository the
+ * path sits in (`-C` its directory, the name taken literally). `untracked` is a clear
+ * answer only: git exits 0 and lists nothing, or says the directory is in no
+ * repository. A listed path is `tracked`. A git that could not run or answered
+ * anything else, and a call refused past the deadline, is `unknown`. The call sets no
+ * time limit.
+ *
+ * @param {Io} io
+ * @param {string} abs
+ * @returns {'untracked' | 'tracked' | 'unknown'}
+ */
+function trackedStateOf(io, abs) {
+  const probe = Object.assign({}, io, { env: Object.assign({}, io.env, { LC_ALL: 'C' }) });
+  const r = git(probe, ['-C', path.dirname(abs), '--literal-pathspecs', 'ls-files', '-z', '--', path.basename(abs)], null, LINE_MAX_BUFFER);
+  if (!answered(r)) return 'unknown';
+  if (r.status === 0) return r.stdout.length === 0 ? 'untracked' : 'tracked';
+  return r.status === 128 && NOT_A_REPOSITORY_RE.test(r.stderr) ? 'untracked' : 'unknown';
+}
+
+/**
+ * D-TRACKED-RESULT: a git-tracked file counts as absent, like a tracked
+ * `.devflow/config.json`. A path is `untracked` only when git says so for the path as
+ * spelled and for the file it resolves to (a link is judged by both names); one tracked
+ * name makes it `tracked`, and one name git could not answer for makes it `unknown`.
+ * It never throws.
+ *
+ * @param {Io} io
+ * @param {string} file
+ * @returns {'untracked' | 'tracked' | 'unknown'}
+ */
+function trackedState(io, file) {
+  try {
+    const abs = path.resolve(file);
+    const names = [abs];
+    try {
+      const real = fs.realpathSync(abs);
+      if (real !== abs) names.push(real);
+    } catch (_) { /* a path that names nothing has no other name */ }
+    /** @type {'untracked' | 'tracked' | 'unknown'} */
+    let state = 'untracked';
+    for (const name of names) {
+      const one = trackedStateOf(io, name);
+      if (one === 'tracked') return 'tracked';
+      if (one === 'unknown') state = 'unknown';
+    }
+    return state;
+  } catch (_) {
+    return 'unknown';
+  }
+}
+
+/**
+ * D-TRACKED-RESULT: the paths a `verify`, `publish` or `readiness` run reads or writes
+ * as a result file. An out path (`--block-out`, `--comment-out`, `--stale-out`,
+ * `--out`) that is not clearly untracked is refused before any read or removal, with
+ * 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.
+ *
+ * @param {Io} io
+ * @param {ParsedArgs} args
+ * @returns {{ args: ParsedArgs } | { outcome: Outcome }}
+ */
+function admitPaths(io, args) {
+  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] : [];
+  if (outs.some(file => file !== null && trackedState(io, file) !== 'untracked')) {
+    return { outcome: refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written') };
+  }
+  if (args.evidence === null || trackedState(io, args.evidence) === 'untracked') return { args };
+  io.notes.add('evidence-ignored');
+  return { args: Object.assign({}, args, { evidence: null }) };
 }
 
 /**
@@ -625,6 +797,19 @@ function loginArg(login) {
   return login;
 }
 
+/**
+ * Assert a comment id before it reaches gh's argv (an API path segment):
+ * COMMENT_ID_RE, so no `/`, `..`, `?` or option can ride on PR data. commentIdOf
+ * only ever yields such ids; this is that precondition held at the sink.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function commentIdArg(id) {
+  if (typeof id !== 'string' || !COMMENT_ID_RE.test(id)) throw new Error('verify-evidence: unchecked comment id');
+  return id;
+}
+
 // ---------------------------------------------------------------------------
 // The PR (one gh pr view)
 // ---------------------------------------------------------------------------
@@ -646,6 +831,21 @@ function loginOf(author) {
   return typeof login === 'string' && login.length <= 100 ? login : '';
 }
 
+/**
+ * The numeric id of a PR comment, read from its url, as the digits themselves:
+ * never Number(), so an id beyond 2^53 stays exact. '' unless the url is a bounded
+ * string of the anchored pull-comment form AND names the PR that was read.
+ *
+ * @param {unknown} url
+ * @param {number} pr
+ * @returns {string}
+ */
+function commentIdOf(url, pr) {
+  if (typeof url !== 'string' || url.length > MAX_URL_CHARS) return '';
+  const m = COMMENT_URL_RE.exec(url);
+  return m !== null && m[1] === String(pr) ? m[2] : '';
+}
+
 /**
  * Parse the `gh pr view --json` answer into PrFacts, or null when it is not the
  * PR that was asked for or a field has the wrong shape. Malformed list entries
@@ -671,6 +871,7 @@ function parsePrJson(json, pr) {
       association: typeof x.authorAssociation === 'string' ? x.authorAssociation : '',
       body: typeof x.body === 'string' ? x.body : '',
       viewerDidAuthor: x.viewerDidAuthor === true,
+      commentId: commentIdOf(x.url, pr),
     });
   });
   const reviews = o.reviews.slice(-CAPS.REVIEWS).map(r => {
@@ -751,6 +952,38 @@ function markerComments(pr) {
   return pr.comments.filter(c => PE.MARKERS.EVIDENCE_RE.test(firstLine(c.body))).reverse();
 }
 
+/**
+ * @typedef {{ id: string, marker: string, editable: boolean }} EditTarget
+ *   `id` is the comment's id ('' when unreadable); `marker` is its first line;
+ *   `editable` is false when a later comment from another login is itself an
+ *   evidence marker.
+ */
+
+/**
+ * The comment a publish would edit in place: the viewer's NEWEST comment whose first
+ * line starts with the evidence head prefix, whatever its key. "The viewer's" is the
+ * server-asserted `viewerDidAuthor` flag, so only an own comment is ever a target
+ * (never another login's comment, such as a maintainer's or a bot's). A malformed own
+ * comment (the prefix alone) is a valid target, so an edit repairs it.
+ *
+ * `editable` guards the trust order: verify trusts the newest evidence comment by
+ * list position, and an edit keeps its old position, so editing is safe only when
+ * no strict marker comment from another login comes after the target. A later
+ * prefix-only comment from another login is not a record and does not block. The
+ * strict trust functions (markerComments, resolveTrust, findTrustedRecord) stay as
+ * they are.
+ *
+ * @param {{ comments: readonly PrComment[] }} pr  chronological, newest last
+ * @returns {EditTarget | null}
+ */
+function editTarget(pr) {
+  const at = pr.comments.findLastIndex(c => c.viewerDidAuthor && firstLine(c.body).startsWith(PE.MARKERS.EVIDENCE_HEAD_PREFIX));
+  if (at === -1) return null;
+  const c = pr.comments[at];
+  const editable = !pr.comments.slice(at + 1).some(x => !x.viewerDidAuthor && PE.MARKERS.EVIDENCE_RE.test(firstLine(x.body)));
+  return Object.freeze({ id: c.commentId, marker: firstLine(c.body), editable });
+}
+
 /**
  * D-VERIFY-APPROVAL (D6): each login's LATEST decisive review — APPROVED,
  * CHANGES_REQUESTED or DISMISSED — in chronological order.
@@ -1437,35 +1670,40 @@ function bodyUpdate(io, plan, ev, body) {
 
 /**
  * The comment (D-VERIFY-PUBLICATION) and whether it is already posted: only the
- * viewer's own comment whose first line is this exact marker (head and key)
- * counts, so a spoofed marker never suppresses a post. `off`, or nothing to
- * record, is no comment (`n/a`). Null when it fails to render.
+ * viewer's own NEWEST evidence comment (the edit target) whose first line is this
+ * exact marker (head and key) counts, so a spoofed marker never suppresses a post
+ * and an older exact match behind a newer own comment of another key reads `no`
+ * (the newer one is what a publish edits). `off`, or nothing to record, is no
+ * comment (`n/a`). Null when it fails to render.
  *
  * @param {{ tps: readonly any[] }} plan
  * @param {any} ev
  * @param {'full' | 'off' | 'stub'} mode
- * @param {PrFacts} pr
+ * @param {EditTarget | null} target
  * @returns {{ text: string, posted: 'yes' | 'no' | 'n/a' } | null}
  */
-function commentUpdate(plan, ev, mode, pr) {
+function commentUpdate(plan, ev, mode, target) {
   if (mode === 'off' || (ev.records.length === 0 && ev.exceptions.length === 0)) return { text: '', posted: 'n/a' };
   const rendered = PE.render(plan, ev, mode);
   if (!rendered.ok) return null;
   const marker = firstLine(rendered.value.text);
-  const posted = pr.comments.some(c => c.viewerDidAuthor && firstLine(c.body) === marker) ? 'yes' : 'no';
+  const posted = target !== null && target.marker === marker ? 'yes' : 'no';
   return { text: rendered.value.text, posted };
 }
 
 /**
- * --stale-out: only STALE TPs whose text hash equals the trusted record's — text a
- * trusted author already published, never unrecorded PR text (containment).
+ * --stale-out: the STALE TPs. A plan from the PR body lists only those whose text hash
+ * equals the trusted record's — text a trusted author already published, never
+ * unrecorded PR text (containment). A plan from the `--evidence` file is the caller's
+ * own local text, so every STALE TP of it is listed.
  *
  * @param {readonly TpInput[]} inputs
  * @param {readonly { state: string }[]} records
+ * @param {boolean} fromFile  whether the plan came from the evidence file
  * @returns {string}
  */
-function staleOutText(inputs, records) {
-  const lines = inputs.filter((x, i) => records[i].state === 'STALE' && x.recorded).map(x => x.tp.line);
+function staleOutText(inputs, records, fromFile) {
+  const lines = inputs.filter((x, i) => records[i].state === 'STALE' && (fromFile || x.recorded)).map(x => x.tp.line);
   return lines.length === 0 ? '' : ['## Test Plan', ...lines].join('\n') + '\n';
 }
 
@@ -1492,24 +1730,43 @@ function writeOutputs(args, body, blockText, commentText, staleText) {
 }
 
 /**
+ * @typedef {{ outcome: Outcome, target: EditTarget | null }} VerifyPass
+ *   The verify result and the viewer's edit target from the same PR snapshot (null on
+ *   every refusal). The target stays in memory: it never reaches stdout, a flag or a file.
+ */
+
+/**
+ * @param {Io} io
+ * @param {number} code
+ * @param {string} reason  a fixed phrase from this file, never input bytes
+ * @returns {VerifyPass}
+ */
+function refusedPass(io, code, reason) {
+  return { outcome: refuse(io, code, reason), target: null };
+}
+
+/**
+ * One verify pass: the Outcome the `verify` subcommand prints, and the edit target
+ * the same snapshot gave. `posted` in the EVIDENCE line is taken from that target.
+ *
  * @param {Io} io
  * @param {Extract<ParsedArgs, { kind: 'verify' }>} args
  * @param {MainDeps} deps
- * @returns {Outcome}
+ * @returns {VerifyPass}
  */
-function runVerify(io, args, deps) {
+function verifyPass(io, args, deps) {
   // Inputs first: an unusable evidence file or state directory decides before any call.
   /** @type {EvidenceInput | null} */
   let evidence = null;
   if (args.evidence !== null) {
     evidence = loadEvidence(args.evidence);
-    if (evidence === null) return refuse(io, EXIT_CODES.INPUT_UNUSABLE, 'evidence file unusable');
+    if (evidence === null) return refusedPass(io, EXIT_CODES.INPUT_UNUSABLE, 'evidence file unusable');
     if (evidence.malformed > 0) io.notes.add('malformed-claims');
   }
-  if (args.state !== null && !isRealDirectory(args.state)) return refuse(io, EXIT_CODES.INPUT_UNUSABLE, 'state directory unusable');
+  if (args.state !== null && !isRealDirectory(args.state)) return refusedPass(io, EXIT_CODES.INPUT_UNUSABLE, 'state directory unusable');
 
   const pr = parsePrJson(prView(io, args.pr, PR_FIELDS), args.pr);
-  if (pr === null) return refuse(io, EXIT_CODES.REMOTE_FAILURE, 'the PR could not be read');
+  if (pr === null) return refusedPass(io, EXIT_CODES.REMOTE_FAILURE, 'the PR could not be read');
 
   const trust = resolveTrust(io, pr, args.approval);
   const record = findTrustedRecord(pr, trust);
@@ -1520,12 +1777,12 @@ function runVerify(io, args, deps) {
   // trusted record's.
   const fromFile = evidence !== null && evidence.plan !== null;
   const plan = fromFile ? /** @type {any} */ (evidence).plan : bodyPlan(pr.body);
-  if (plan === null) return refuse(io, EXIT_CODES.INPUT_UNUSABLE, 'the PR body test-plan block cannot serve as the plan');
+  if (plan === null) return refusedPass(io, EXIT_CODES.INPUT_UNUSABLE, 'the PR body test-plan block cannot serve as the plan');
   if (!fromFile && !coversRecord(plan, record)) {
-    return refuse(io, EXIT_CODES.INPUT_UNUSABLE, 'the PR body test-plan block drops a TP the trusted record carries');
+    return refusedPass(io, EXIT_CODES.INPUT_UNUSABLE, 'the PR body test-plan block drops a TP the trusted record carries');
   }
   const inputs = tpInputs(plan, evidence, record, fromFile);
-  if (inputs === null) return refuse(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'a TP line failed its grammar');
+  if (inputs === null) return refusedPass(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'a TP line failed its grammar');
 
   const repo = prepareRepo(io, pr);
   /** @type {RunMemo} */
@@ -1539,7 +1796,7 @@ function runVerify(io, args, deps) {
     : record.kind === 'record' ? record.exceptions : [];
   const key = PE.dedupeKey({ records, exceptions }, sha256);
   const tally = PE.tally(records.map(r => r.state));
-  if (!key.ok || !tally.ok) return refuse(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the records failed their grammar');
+  if (!key.ok || !tally.ok) return refusedPass(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the records failed their grammar');
 
   const mode = publicationMode(args.publication);
   const ev = {
@@ -1550,8 +1807,9 @@ function runVerify(io, args, deps) {
     exceptions,
   };
   const body = bodyUpdate(io, plan, ev, pr.body);
-  const comment = commentUpdate(plan, ev, mode, pr);
-  if (body === null || comment === null) return refuse(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the block or the comment failed to render');
+  const target = editTarget(pr);
+  const comment = commentUpdate(plan, ev, mode, target);
+  if (body === null || comment === null) return refusedPass(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the block or the comment failed to render');
 
   const line = gateEvidenceLine(deps, {
     pr: pr.number,
@@ -1565,12 +1823,22 @@ function runVerify(io, args, deps) {
     posted: comment.posted,
     body: body.changed ? 'changed' : 'same',
   }, plan.tps.length);
-  if (line === null) return refuse(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the EVIDENCE line failed its gate');
+  if (line === null) return refusedPass(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the EVIDENCE line failed its gate');
 
-  if (!writeOutputs(args, pr.body, body.blockText, comment.text, staleOutText(inputs, records))) {
-    return refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
+  if (!writeOutputs(args, pr.body, body.blockText, comment.text, staleOutText(inputs, records, fromFile))) {
+    return refusedPass(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
   }
-  return { code: EXIT_CODES.OK, stdout: line + '\n' };
+  return { outcome: { code: EXIT_CODES.OK, stdout: line + '\n' }, target };
+}
+
+/**
+ * @param {Io} io
+ * @param {Extract<ParsedArgs, { kind: 'verify' }>} args
+ * @param {MainDeps} deps
+ * @returns {Outcome}
+ */
+function runVerify(io, args, deps) {
+  return verifyPass(io, args, deps).outcome;
 }
 
 /**
@@ -1698,7 +1966,7 @@ function runCheck(io, args) {
   let result;
   if (args.what === 'tp') result = PE.parsePlan(sectionOrWhole(text, 'testPlan'));
   else if (args.what === 'exceptions') result = PE.parseExceptions(sectionOrWhole(text, 'exceptions'));
-  else if (args.what === 'wave') result = PE.parseWaveBlock(text);
+  else if (args.what === 'wave') result = PE.parseWaveBlock(text, { linksOnly: args.linksOnly });
   else {
     const b = PE.parseBlock(text);
     // R7 pastes only the creation form: TP lines, none ticked.
@@ -1749,13 +2017,22 @@ const REASON_RE = /^[a-z0-9][a-z0-9 -]{0,59}$/;
 /** What a `publish` result prints when it could not run at all (exit 2). */
 const EVIDENCE_UNAVAILABLE_LINE = 'TRACEABILITY: DEGRADED (evidence unavailable)';
 
+/** What a `publish` result prints when the machine manifest does not say compliance is enabled (exit 2). */
+const COMPLIANCE_OFF_LINE = 'TRACEABILITY: DEGRADED (compliance off)';
+
+/** What a `publish` result prints when the machine manifest cannot be read (exit 2). */
+const COMPLIANCE_UNREADABLE_LINE = 'TRACEABILITY: DEGRADED (compliance state unreadable)';
+
+/** 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]);
+
 /**
  * @typedef {{ status: string, reason: string | null }} Part
  *   One half of the `publish` answer: a closed status, or `DEGRADED` with its reason.
  */
 
 const BODY_STATUSES = Object.freeze(['EDITED', 'UNCHANGED', 'SKIPPED']);
-const COMMENT_STATUSES = Object.freeze(['POSTED', 'SKIPPED', 'OFF']);
+const COMMENT_STATUSES = Object.freeze(['POSTED', 'SKIPPED', 'OFF', 'EDITED']);
 
 /**
  * @param {string} status
@@ -1900,6 +2177,18 @@ function ghWrite(io, args) {
   return { ok: r.ok, serverError: isServerError(r) };
 }
 
+/**
+ * The DEGRADED part for a gh write that failed: the 5xx phrase after a server error,
+ * else the phrase of the failed step. It runs no gh call.
+ *
+ * @param {{ ok: boolean, serverError: boolean }} result  what ghWrite returned
+ * @param {string} reason  a fixed phrase from this file
+ * @returns {Part}
+ */
+function writeFailedPart(result, reason) {
+  return degradedPart(result.serverError ? '5xx on update-pr-evidence' : reason);
+}
+
 /**
  * The context for the writes: a gh budget and a deadline of their own, the same
  * notes. The throttle flag carries over, so a rate limit that verify hit stops the
@@ -1938,38 +2227,152 @@ function publishBody(io, pr, fields, files) {
   if (outcome === 'conflict') return okPart('SKIPPED');
   if (outcome !== 'ok' && outcome !== 'resplice') return degradedPart('splice ' + outcome);
   const edit = ghWrite(io, ['pr', 'edit', String(pr), '--body-file', files.body]);
-  if (!edit.ok) return degradedPart(edit.serverError ? '5xx on update-pr-evidence' : 'gh pr edit failed');
+  if (!edit.ok) return writeFailedPart(edit, 'gh pr edit failed');
   const back = runReadback(io, { kind: 'readback', pr, expect: files.body });
   return back.code === EXIT_CODES.OK && back.stdout === 'READBACK ok\n' ? okPart('EDITED') : degradedPart('body read-back mismatch');
 }
 
 /**
- * The comment half: the append-only evidence comment, scrubbed (D11) and re-measured
- * after the scrub, posted once. An already-posted comment is never touched.
+ * Whether the comment just edited now reads back as the scrubbed text: one GET of it
+ * as a JSON string, compared after one trailing newline is normalised on each side.
+ * The edit itself runs silent, so this is the only read of the comment. Any failure
+ * to read or parse is "no". Neither the comment nor gh's stderr is printed.
+ *
+ * @param {Io} io  the write-stage context
+ * @param {string} id  a comment id commentIdOf produced
+ * @param {string} expected  the scrubbed comment text (never the unscrubbed file)
+ * @returns {boolean}
+ */
+function commentReadsBack(io, id, expected) {
+  const r = gh(io, ['api', 'repos/{owner}/{repo}/issues/comments/' + commentIdArg(id), '--jq', '.body | @json'], COMMENT_READ_MAX_BUFFER);
+  if (!r.ok) return false;
+  try {
+    const body = JSON.parse(stripOneNewline(r.stdout.toString('utf8')));
+    return typeof body === 'string' && stripOneNewline(body) === stripOneNewline(expected);
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * The comment half: the evidence comment, scrubbed (D11) and re-measured after the
+ * scrub. When the viewer's own evidence comment is a safe target (no strict marker
+ * from another login follows it), that comment is edited in place (one PATCH of the
+ * scrubbed file) and read back against it. Otherwise a new comment is posted once.
+ * A comment that already carries this head and key is skipped. An own target with no
+ * readable id is DEGRADED before the scrub, with no write. A failed edit or
+ * read-back is a DEGRADED result and never falls back to a post. Nothing is deleted.
  *
  * @param {Io} io  the write-stage context
  * @param {number} pr
  * @param {{ posted: string }} fields  the EVIDENCE line's fields
  * @param {{ commentRaw: string, comment: string }} files
+ * @param {EditTarget | null} target  the viewer's newest evidence comment in the snapshot
+ *   verify read, or null when there is none
  * @returns {Part}
  */
-function publishComment(io, pr, fields, files) {
+function publishComment(io, pr, fields, files, target) {
   if (fields.posted === 'yes') return okPart('SKIPPED');
   if (fields.posted === 'n/a') return okPart('OFF');
+  const edit = target !== null && target.editable;
+  if (edit && target.id === '') return degradedPart('comment id unreadable');
   if (!scrub(io, files.commentRaw, files.comment)) return degradedPart('redaction unavailable');
   const text = readTextFile(files.comment);
   if (text === null || text === '') return degradedPart('redaction unavailable');
   if (text.length > COMMENT_POST_MAX_CHARS) return degradedPart('comment over size cap');
+  if (edit) {
+    const patch = ghWrite(io, ['api', '--method', 'PATCH',
+      'repos/{owner}/{repo}/issues/comments/' + commentIdArg(target.id),
+      '-F', 'body=@' + files.comment, '--silent']);
+    if (!patch.ok) return writeFailedPart(patch, 'comment edit failed');
+    return commentReadsBack(io, target.id, text) ? okPart('EDITED') : degradedPart('comment read-back mismatch');
+  }
   const post = ghWrite(io, ['pr', 'comment', String(pr), '--body-file', files.comment]);
-  if (post.ok) return okPart('POSTED');
-  return degradedPart(post.serverError ? '5xx on update-pr-evidence' : 'gh pr comment failed');
+  return post.ok ? okPart('POSTED') : writeFailedPart(post, 'gh pr comment failed');
+}
+
+/**
+ * The machine manifest, ~/.devflow/manifest.json, or null when the home directory is
+ * not absolute (a relative one would resolve against the repository). No environment
+ * variable relocates it, and no repository file stands in for it.
+ *
+ * @returns {string | null}
+ */
+function machineManifestPath() {
+  let home;
+  try {
+    home = os.homedir();
+  } catch (_) {
+    return null;
+  }
+  return typeof home === 'string' && path.isAbsolute(home) ? path.join(home, '.devflow', 'manifest.json') : null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * The compliance switch of the machine manifest, read with this file's regular-file
+ * rules (a link is followed, as every other reader of the machine manifest does). The
+ * accepted shape is the one the CLI keeps, `features.compliance` as
+ * `{ enabled: boolean, frameworks: string[] }`; a manifest from before compliance
+ * existed has no such key and reads as off. A value in any other shape is `unreadable`,
+ * where the CLI heals it to off: this guard only lets a publish through on a record it
+ * can trust.
+ *
+ * @param {string | null} manifestPath
+ * @returns {'enabled' | 'off' | 'unreadable'}
+ */
+function machineComplianceState(manifestPath) {
+  if (manifestPath === null) return 'unreadable';
+  const text = readTextFile(manifestPath);
+  if (text === null) return 'unreadable';
+  /** @type {unknown} */
+  let manifest;
+  try {
+    manifest = JSON.parse(text);
+  } catch (_) {
+    return 'unreadable';
+  }
+  if (!isRecord(manifest) || !isRecord(manifest.features)) return 'unreadable';
+  const compliance = manifest.features.compliance;
+  if (compliance === undefined) return 'off';
+  if (!isRecord(compliance) || typeof compliance.enabled !== 'boolean') return 'unreadable';
+  if (!Array.isArray(compliance.frameworks) || !compliance.frameworks.every(f => typeof f === 'string')) return 'unreadable';
+  return compliance.enabled ? 'enabled' : 'off';
+}
+
+/**
+ * The publish guard: with compliance off, or its state unreadable, `publish` ends here,
+ * before a work directory is made and before any gh call. It reads the machine manifest
+ * under the user's home folder and nothing else, so no repository file can switch it on.
+ * It ignores the devflow folder override. It returns its outcome and never throws: the
+ * catch in main turns a throw into "evidence unavailable", which would hide the reason.
+ *
+ * @param {Io} io
+ * @param {MainDeps} deps
+ * @returns {Outcome | null}  the refusal, or null when compliance is enabled
+ */
+function publishRefusal(io, deps) {
+  const state = machineComplianceState(typeof deps.manifestPath === 'string' ? deps.manifestPath : machineManifestPath());
+  if (state === 'enabled') return null;
+  io.stderr('verify-evidence: publish: '
+    + (state === 'off' ? 'compliance is off on this machine' : 'the machine compliance state could not be read') + '\n');
+  return { code: EXIT_CODES.INPUT_UNUSABLE, stdout: (state === 'off' ? COMPLIANCE_OFF_LINE : COMPLIANCE_UNREADABLE_LINE) + '\n' };
 }
 
 /**
  * The whole update-pr-evidence operation, in the order the operation always had:
- * verify; only on `body:changed` scrub, splice, `gh pr edit`, read back; only on
- * `posted:no` scrub and `gh pr comment`. The work files live in one private directory
- * this call makes and removes.
+ * the compliance guard; verify; only on `body:changed` scrub, splice, `gh pr edit`,
+ * read back; only on `posted:no` scrub, then edit the viewer's own evidence comment in
+ * place and read it back, or post a new one when there is none to edit or a newer
+ * evidence comment from another login follows it. The work files live in one private
+ * directory this call makes and removes.
  *
  * @param {Io} io
  * @param {Extract<ParsedArgs, { kind: 'publish' }>} args
@@ -1977,6 +2380,8 @@ function publishComment(io, pr, fields, files) {
  * @returns {Outcome}
  */
 function runPublish(io, args, deps) {
+  const refused = publishRefusal(io, deps);
+  if (refused !== null) return refused;
   /** @type {string} */
   let dir;
   try {
@@ -2000,18 +2405,18 @@ function runPublish(io, args, deps) {
       commentRaw: file('comment.raw'),
       comment: file('comment'),
     };
-    const verified = runVerify(io, {
+    const verified = verifyPass(io, {
       kind: 'verify', pr: args.pr, publication: args.publication, evidence: args.evidence, state,
       blockOut: files.notesRaw, commentOut: files.commentRaw, staleOut: null, approval: false,
     }, deps);
-    if (verified.code !== EXIT_CODES.OK) return evidenceUnavailable(io, 'verify did not answer');
-    const line = stripOneNewline(verified.stdout);
+    if (verified.outcome.code !== EXIT_CODES.OK) return evidenceUnavailable(io, 'verify did not answer');
+    const line = stripOneNewline(verified.outcome.stdout);
     const parsed = PE.parseEvidenceLine(line);
     if (!parsed.ok || parsed.value.pr !== args.pr) return evidenceUnavailable(io, 'verify answered something else');
 
     const stage = writeStageIo(io);
     const body = publishBody(stage, args.pr, parsed.value, files);
-    const comment = publishComment(stage, args.pr, parsed.value, files);
+    const comment = publishComment(stage, args.pr, parsed.value, files, verified.target);
     return { code: EXIT_CODES.OK, stdout: renderPublishBlock(line, body, comment) };
   } finally {
     try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* the OS clears its temp directory */ }
@@ -2162,21 +2567,28 @@ function parseJsonOrNull(text) {
 }
 
 /**
- * The PR's review decision. `gh pr view` answers `""` or null when no rule asks for a
- * review; a string outside the three documented values reads UNRECOGNISED, and the
- * ladder never lets that reach READY.
+ * The PR's review decision, merge state and head, from one `gh pr view` read. The
+ * decision answers `""` or null when no rule asks for a review; a string outside the
+ * three documented values reads UNRECOGNISED, and the ladder never lets that reach READY.
+ * `mergeable` is the string GitHub printed, or null when the key is absent or not a
+ * string; `head` is the PR head when it is 40 lowercase hex, else null. Neither makes the
+ * decision unreadable: the CI read treats them as unknown and never as a pass.
  *
  * @param {Io} io
  * @param {number} pr
- * @returns {Read<string | null>}
+ * @returns {Read<{ decision: string | null, mergeable: string | null, head: string | null }>}
  */
-function readDecision(io, pr) {
-  const r = gh(io, ['pr', 'view', String(pr), '--json', 'reviewDecision'], LINE_MAX_BUFFER);
+function readPrView(io, pr) {
+  const r = gh(io, ['pr', 'view', String(pr), '--json', 'reviewDecision,mergeable,headRefOid'], LINE_MAX_BUFFER);
   if (!r.ok) return { ok: false, reason: readFailure(r) };
-  const value = obj(parseJsonOrNull(r.stdout.toString('utf8'))).reviewDecision;
-  if (value === null || value === '') return { ok: true, value: null };
+  const fields = obj(parseJsonOrNull(r.stdout.toString('utf8')));
+  const value = fields.reviewDecision;
+  const mergeable = typeof fields.mergeable === 'string' ? fields.mergeable : null;
+  const head = typeof fields.headRefOid === 'string' && SHA40_RE.test(fields.headRefOid) ? fields.headRefOid : null;
+  if (value === null || value === '') return { ok: true, value: { decision: null, mergeable, head } };
   if (typeof value !== 'string') return { ok: false, reason: 'review decision unreadable' };
-  return { ok: true, value: ['APPROVED', 'CHANGES_REQUESTED', 'REVIEW_REQUIRED'].includes(value) ? value : 'UNRECOGNISED' };
+  const decision = ['APPROVED', 'CHANGES_REQUESTED', 'REVIEW_REQUIRED'].includes(value) ? value : 'UNRECOGNISED';
+  return { ok: true, value: { decision, mergeable, head } };
 }
 
 /**
@@ -2215,49 +2627,105 @@ function readThreads(io, pr) {
   return { ok: true, value: { unresolved, approximate: total > THREADS_PAGE } };
 }
 
+/** CI that could not be established: the ladder reads it as `status unknown`, never READY. */
+const CI_INDETERMINATE = Object.freeze({ status: 'INDETERMINATE', failing: '-' });
+
 /**
- * D-READINESS-CLASSIFIER: the CI status, by check-ci-status's fetch (exit 0 or 8 is a
- * result; "no checks reported" or `[]` is NO_CI; any other failure is INDETERMINATE)
- * and ci-wait's classifier over `bucket`. Failing names are sanitized and bounded by
- * ci-wait's own formatter.
+ * D-READINESS-WORKFLOWS: whether the repository has an active workflow file, by ci-wait's
+ * one read-only call and parser. A call that fails or is refused, and a reply the parser
+ * cannot read, give null: not knowing, never "no workflow file".
+ *
+ * @param {Io} io
+ * @returns {boolean | null}
+ */
+function probeWorkflows(io) {
+  const r = gh(io, CW.WORKFLOWS_ARGS, READINESS_MAX_BUFFER);
+  return r.ok ? CW.parseActiveWorkflows(r.stdout.toString('utf8')) : null;
+}
+
+/**
+ * An empty check list: ci-wait's merge gate decides (D-CI-WORKFLOWS). The workflow list
+ * is asked only when the gate asks for it, so a PR that cannot be NO_CI costs no call. A
+ * gate answer other than keep is INDETERMINATE.
+ *
+ * @param {Io} io
+ * @param {string | null} mergeable
+ * @returns {{ status: string, failing: string }}
+ */
+function readEmptyCi(io, mergeable) {
+  const first = CW.mergeGate('NO_CI', mergeable);
+  const gate = first === 'probe' ? CW.mergeGate('NO_CI', mergeable, probeWorkflows(io)) : first;
+  return gate === 'keep' ? { status: 'NO_CI', failing: '-' } : CI_INDETERMINATE;
+}
+
+/**
+ * D-READINESS-CLASSIFIER: the CI status, read once. The checks come from `gh pr checks`
+ * over name,state,bucket,workflow, with check-ci-status's exit rule (exit 0 or 8 is a
+ * result; any other failure is INDETERMINATE). The rows come from ci-wait's parser, and the
+ * status from ci-wait's classifier (D-CI-WORKFLOW-RULE) and merge gate (D-CI-MERGE-STATE,
+ * D-CI-WORKFLOWS), where the rules are written, so the two scripts cannot disagree. A
+ * conflicting PR reads INDETERMINATE before any checks call, and "no checks reported" or
+ * `[]` goes to readEmptyCi. An unknown merge state, a failed workflow-list call and an
+ * unreadable reply are INDETERMINATE, never DEGRADED. Failing names are sanitized and
+ * bounded by ci-wait's own formatter. PASSING does not prove that the test workflow ran by
+ * name.
  *
  * @param {Io} io
  * @param {number} pr
+ * @param {string | null} mergeable  GitHub's merge state of the PR, from readPrView
  * @returns {{ status: string, failing: string }}
  */
-function readCi(io, pr) {
-  const r = gh(io, ['pr', 'checks', String(pr), '--json', 'name,state,bucket'], READINESS_MAX_BUFFER);
-  const indeterminate = { status: 'INDETERMINATE', failing: '-' };
-  if (!answered(r)) return indeterminate;
+function readCi(io, pr, mergeable) {
+  if (CW.isConflicting(mergeable)) return CI_INDETERMINATE;
+  const r = gh(io, ['pr', 'checks', String(pr), '--json', 'name,state,bucket,workflow'], READINESS_MAX_BUFFER);
+  if (!answered(r)) return CI_INDETERMINATE;
   if (r.status !== 0 && r.status !== 8) {
     if (/Could not resolve to a PullRequest/.test(r.stderr)) return { status: 'NO_PR', failing: '-' };
-    return /no checks reported/i.test(r.stderr) ? { status: 'NO_CI', failing: '-' } : indeterminate;
-  }
-  const rows = parseJsonOrNull(r.stdout.toString('utf8'));
-  if (!Array.isArray(rows) || rows.length > READINESS_MAX_CHECKS) return indeterminate;
-  if (rows.length === 0) return { status: 'NO_CI', failing: '-' };
-  const checks = [];
-  for (const row of rows) {
-    const x = obj(row);
-    if (typeof x.name !== 'string' || typeof x.bucket !== 'string') return indeterminate;
-    checks.push({ name: x.name, bucket: x.bucket });
+    return /no checks reported/i.test(r.stderr) ? readEmptyCi(io, mergeable) : CI_INDETERMINATE;
   }
+  const checks = CW.parseChecks(r.stdout.toString('utf8'));
+  if (checks === null) return CI_INDETERMINATE;
+  if (checks.length === 0) return readEmptyCi(io, mergeable);
   const c = CW.classifyChecks(checks);
+  if (CW.mergeGate(c.status, mergeable, null) !== 'keep') return CI_INDETERMINATE;
   return { status: c.status, failing: CW.formatNames(c.failing) };
 }
 
+/**
+ * D-READINESS-HEAD: CI counts for one head. `gh pr checks` answers for whatever head the
+ * PR has when it is called, and the evidence is read after it, so a push in between would
+ * pair a CI result with evidence of another head. PASSING and NO_CI stand only when the
+ * head read with the review decision, before the checks call, and the head the evidence
+ * was read at are both 40 lowercase hex and equal; otherwise CI is INDETERMINATE. FAILING,
+ * PENDING and the rest stay: they hold the ladder back on their own.
+ *
+ * @param {{ status: string, failing: string }} ci
+ * @param {unknown} viewHead  the head read before the checks call, or null
+ * @param {unknown} evidenceHead  the head the evidence was read at, or null when it is unknown
+ * @returns {{ status: string, failing: string }}
+ */
+function bindCiHead(ci, viewHead, evidenceHead) {
+  if (ci.status !== 'PASSING' && ci.status !== 'NO_CI') return ci;
+  /** @param {unknown} head */
+  const isHead = head => typeof head === 'string' && SHA40_RE.test(head);
+  const bound = isHead(viewHead) && isHead(evidenceHead) && viewHead === evidenceHead;
+  return bound ? ci : CI_INDETERMINATE;
+}
+
 /**
  * The test-plan evidence at the head, by `verify --approval`: known only on exit 0
- * with one EVIDENCE line for this PR (the old step 4's rule).
+ * with one EVIDENCE line for this PR (the old step 4's rule). `evidence` is the local
+ * evidence file `readiness --evidence` names, or null to read the PR's own record.
  *
  * @param {Io} io
  * @param {number} pr
+ * @param {string | null} evidence
  * @param {MainDeps} deps
  * @returns {any | null}  the parsed EVIDENCE fields, or null when the evidence is unknown
  */
-function readEvidence(io, pr, deps) {
+function readEvidence(io, pr, evidence, deps) {
   const verified = runVerify(io, {
-    kind: 'verify', pr, publication: '', evidence: null, state: null,
+    kind: 'verify', pr, publication: '', evidence, state: null,
     blockOut: null, commentOut: null, staleOut: null, approval: true,
   }, deps);
   if (verified.code !== EXIT_CODES.OK) return null;
@@ -2275,6 +2743,15 @@ function approvalText(require, evidence) {
   return evidence !== null && evidence.approval === 'yes' ? 'yes' : 'no';
 }
 
+/**
+ * @param {string | null} decision  the review decision from readPrView
+ * @returns {string}  the word the Details line prints for it
+ */
+function decisionLabel(decision) {
+  if (decision === null) return 'none';
+  return decision === 'UNRECOGNISED' ? 'unrecognised' : decision;
+}
+
 /**
  * A readiness answer that could not be reached: a DEGRADED block (exit 2) whose Details
  * say `unavailable` for what was never read.
@@ -2301,22 +2778,28 @@ function readinessDegraded(pr, reason, known) {
  * count it cannot establish, is DEGRADED; an unreadable CI status or unknown evidence
  * is an input to the ladder, which never lets either reach READY.
  *
+ * @typedef {{ outcome: Outcome, head: string | null }} ReadinessPass
+ *   The answer, and the PR head its first read gave (null when that read gave none).
+ *
  * @param {Io} io
  * @param {Extract<ParsedArgs, { kind: 'readiness' }>} args
  * @param {MainDeps} deps
- * @returns {Outcome}
+ * @returns {ReadinessPass}
  */
-function runReadiness(io, args, deps) {
+function readinessPass(io, args, deps) {
   const unreadApproval = approvalText(args.requireNonAuthor, null);
-  const decision = readDecision(io, args.pr);
-  if (!decision.ok) return readinessDegraded(args.pr, decision.reason, { approval: unreadApproval });
-  const decisionText = decision.value === null ? 'none' : decision.value === 'UNRECOGNISED' ? 'unrecognised' : decision.value;
+  const view = readPrView(io, args.pr);
+  if (!view.ok) return { outcome: readinessDegraded(args.pr, view.reason, { approval: unreadApproval }), head: null };
+  const head = view.value.head;
+  const reviewDecision = view.value.decision;
+  const decisionText = decisionLabel(reviewDecision);
   const threads = readThreads(io, args.pr);
   if (!threads.ok) {
-    return readinessDegraded(args.pr, threads.reason, { decision: decisionText, approval: unreadApproval });
+    return { outcome: readinessDegraded(args.pr, threads.reason, { decision: decisionText, approval: unreadApproval }), head };
   }
-  const ci = readCi(io, args.pr);
-  const fields = readEvidence(io, args.pr, deps);
+  const ciRead = readCi(io, args.pr, view.value.mergeable);
+  const fields = readEvidence(io, args.pr, args.evidence, deps);
+  const ci = bindCiHead(ciRead, view.value.head, fields === null ? null : fields.head);
   /** @type {EvidenceFacts | null} */
   const evidence = fields === null ? null : {
     total: fields.total,
@@ -2328,7 +2811,7 @@ function runReadiness(io, args, deps) {
   const verdict = readinessVerdict({
     unresolved: threads.value.unresolved,
     approximate: threads.value.approximate,
-    decision: decision.value,
+    decision: reviewDecision,
     ci: ci.status,
     failing: ci.failing,
     evidence,
@@ -2348,7 +2831,95 @@ function runReadiness(io, args, deps) {
         + ' (VERIFIED-CI ' + evidence.verifiedCi + ', ATTESTED-LOCAL ' + evidence.attestedLocal + ')',
     approval: approvalText(args.requireNonAuthor, evidence),
   };
-  return { code: EXIT_CODES.OK, stdout: renderReadinessBlock(block) };
+  return { outcome: { code: EXIT_CODES.OK, stdout: renderReadinessBlock(block) }, head };
+}
+
+/**
+ * D-READINESS-OUT: `readiness --out <file>`. The file holds the READINESS line, then the
+ * block exactly as it prints. The status in the line is the one the block's own parse
+ * gives, so the line and the block cannot disagree. The head is the PR head the first
+ * read gave, or `none`. The source is `local` when the plan was asked for from the
+ * `--evidence` file and `pr` when it was asked for from the PR's own record; the line
+ * ends with it as `source=<local|pr>`, and any other value is refused like a block that
+ * does not parse. writeTextFile refuses a path that exists and is not a regular
+ * file, a symlink included, so no link is followed. The command makes no gh write.
+ *
+ * One rule covers every outcome: a file from an earlier run never outlives this run.
+ * runReadiness removes the earlier regular file before the first read; here, a block the
+ * output gate would refuse is never written and is the gate's refusal, and a file that
+ * cannot be written is the write refusal, with the regular file the write left removed.
+ * Either way nothing is printed and no out file remains. A path that git tracks never
+ * gets here: admitPaths refuses it first and leaves the file as it is.
+ *
+ * @param {Io} io
+ * @param {string} file
+ * @param {number} pr
+ * @param {Outcome} outcome  the answer readinessPass or readinessDegraded gave
+ * @param {string | null} head
+ * @param {string | undefined} source  one of READINESS_SOURCES
+ * @returns {Outcome}
+ */
+function writeReadinessOut(io, file, pr, outcome, head, source) {
+  const block = parseReadinessBlock(outcome.stdout);
+  if (block === null || !READINESS_SOURCES.includes(/** @type {string} */ (source))) {
+    removeOutFile(file);
+    return refuse(io, EXIT_CODES.OUTPUT_GATE_REFUSED, 'the readiness out file failed its grammar');
+  }
+  const line = [
+    'READINESS', 'pr:' + pr, 'head:' + (head === null ? 'none' : head), 'status:' + block.status, 'source=' + source,
+  ].join(' ');
+  if (!writeTextFile(file, line + '\n' + outcome.stdout)) {
+    removeOutFile(file);
+    return refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
+  }
+  return outcome;
+}
+
+/**
+ * Remove the regular file an earlier run left at `file`. A path that names nothing, a
+ * link, a FIFO or a directory is left as it is: writeTextFile creates the first and
+ * refuses the rest. The lstat never follows a link. False when a regular file could not
+ * be removed.
+ *
+ * @param {string} file
+ * @returns {boolean}
+ */
+function removeOutFile(file) {
+  try {
+    const st = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (st !== undefined && st.isFile()) fs.unlinkSync(file);
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Where the run asked for the test plan: the local evidence file `--evidence` names, or the
+ * PR's own record. It follows the flag alone, so every status of one invocation names the
+ * same source.
+ *
+ * @param {Extract<ParsedArgs, { kind: 'readiness' }>} args
+ * @returns {'local' | 'pr'}
+ */
+function planSource(args) {
+  return args.evidence === null ? 'pr' : 'local';
+}
+
+/**
+ * @param {Io} io
+ * @param {Extract<ParsedArgs, { kind: 'readiness' }>} args
+ * @param {MainDeps} deps
+ * @returns {Outcome}
+ */
+function runReadiness(io, args, deps) {
+  // A file an earlier run left at the out path goes before the first read, so a run that
+  // stops anywhere after this leaves no earlier answer behind.
+  if (args.out !== null && !removeOutFile(args.out)) {
+    return refuse(io, EXIT_CODES.WRITE_FAILED, 'an output file could not be written');
+  }
+  const pass = readinessPass(io, args, deps);
+  return args.out === null ? pass.outcome : writeReadinessOut(io, args.out, args.pr, pass.outcome, pass.head, planSource(args));
 }
 
 // ---------------------------------------------------------------------------
@@ -2415,29 +2986,38 @@ function main(argv, deps) {
     notes: new Set(),
     stderr: typeof d.stderr === 'function' ? d.stderr : (text => { process.stderr.write(text); }),
   };
-  const args = parseArgs(argv);
-  if (args.kind === 'usage') {
+  const parsed = parseArgs(argv);
+  if (parsed.kind === 'usage') {
     io.stderr(USAGE + '\n');
     return { code: EXIT_CODES.USAGE, stdout: '' };
   }
+  let args = parsed;
   /** @type {Outcome} */
   let outcome;
   try {
-    if (args.kind === 'check') outcome = runCheck(io, args);
-    else if (args.kind === 'render') outcome = runRender(io, args);
-    else if (args.kind === 'verify') outcome = runVerify(io, args, d);
-    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 outcome = runReadback(io, args);
+    const admitted = admitPaths(io, parsed);
+    if ('outcome' in admitted) outcome = admitted.outcome;
+    else {
+      args = admitted.args;
+      if (args.kind === 'check') outcome = runCheck(io, args);
+      else if (args.kind === 'render') outcome = runRender(io, args);
+      else if (args.kind === 'verify') outcome = runVerify(io, args, d);
+      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 outcome = runReadback(io, args);
+    }
   } catch (err) {
     // An injected exec that throws, or a broken invariant (rev): no verdict. The two
     // scripted operations still answer in their own DEGRADED form, since a caller
     // prints whatever they print.
     const label = 'internal error (' + errorLabel(err) + ')';
     if (args.kind === 'publish') outcome = evidenceUnavailable(io, label);
-    else if (args.kind === 'readiness') outcome = readinessDegraded(args.pr, 'internal error', {});
-    else outcome = refuse(io, EXIT_CODES.REMOTE_FAILURE, label);
+    else if (args.kind === 'readiness') {
+      // The earlier out file is already gone (runReadiness), so the DEGRADED answer is the one file this run leaves.
+      outcome = readinessDegraded(args.pr, 'internal error', {});
+      if (args.out !== null) outcome = writeReadinessOut(io, args.out, args.pr, outcome, null, planSource(args));
+    } else outcome = refuse(io, EXIT_CODES.REMOTE_FAILURE, label);
   }
   if (io.notes.size > 0) io.stderr('verify-evidence: notes: ' + [...io.notes].sort().join(',') + '\n');
   return outcome;
@@ -2476,7 +3056,7 @@ function settleOutcome(outcome) {
   if (o.stdout.startsWith('## PR Evidence\n')) {
     return o.code === EXIT_CODES.OK && parsePublishBlock(o.stdout) !== null ? pass : failed;
   }
-  if (o.stdout === EVIDENCE_UNAVAILABLE_LINE + '\n') return o.code === EXIT_CODES.INPUT_UNUSABLE ? pass : failed;
+  if (PUBLISH_REFUSAL_LINES.some(line => o.stdout === line + '\n')) return o.code === EXIT_CODES.INPUT_UNUSABLE ? pass : failed;
   if (o.stdout.startsWith('## Merge Readiness\n')) {
     const block = parseReadinessBlock(o.stdout);
     if (block === null) return failed;
@@ -2532,8 +3112,12 @@ module.exports = Object.freeze({
   BODY_STATUSES,
   COMMENT_STATUSES,
   readinessVerdict,
+  bindCiHead,
   renderPublishBlock,
   parsePublishBlock,
   renderReadinessBlock,
   parseReadinessBlock,
+  writeReadinessOut,
+  commentIdOf,
+  editTarget,
 });