@dzhechkov/harness-core 0.4.5 → 0.5.1

package/src/feature-adr-routing.ts

@@ -411,7 +411,36 @@ const CODE_LANDING_PIPELINE_PREFIXES = ['features/', '.dz/', '.agentic-qe/', 'ro
 
 export type CodeLandedBarrierCoder = 'claude' | 'codex' | 'codex-fallback';
 
-export type CodeLandingStatus = 'landed' | 'not-yet-flushed' | 'genuinely-not-landed';
+/** Probe-side landing status. `'inconclusive'` (NEW) is the honest fourth state: the barrier RAN
+ *  but established nothing — an empty target set, an unverifiable baseline, a dead or unparseable
+ *  probe. Pre-epoch there were only three values, so "the instrument did not answer" had to be
+ *  spelled as one of the three answers, and it was spelled `landed`. */
+export type CodeLandingStatus = 'landed' | 'not-yet-flushed' | 'genuinely-not-landed' | 'inconclusive';
+
+/** Code-STAGE result domain (ADR-003 Condition 3). `'synchronous'` is deliberately NOT in the probe
+ *  union: only the non-barrier (Claude-coder) branch may set it, so a codex run can never LABEL its
+ *  way past the persist allowlist. `'not-yet-flushed'` is likewise absent — it is a mid-poll state,
+ *  never a stage outcome. */
+export type CodeStageLandingStatus = 'landed' | 'genuinely-not-landed' | 'inconclusive' | 'synchronous';
+
+/** Bumped whenever the landing protocol's meaning changes. Recorded on every code-stage result so a
+ *  pre-protocol checkpoint reads as no-checkpoint instead of resuming into new semantics. */
+export const LANDING_PROTOCOL_VERSION = 2;
+
+/** R6: salted into the code stage's checkpoint hash PARTS (not the schema version — ADR-003 keeps
+ *  `CKPT_SCHEMA_VERSION` at 'fa-ckpt-2' deliberately, so ONLY the code stage re-runs). */
+export const LANDING_HASH_TOKEN = 'landing-v2';
+
+/** Why a landing verdict is INCONCLUSIVE. Typed, because "we do not know" needs to say WHICH
+ *  unknown — the operator repair differs per reason and a single untyped bucket reads as noise. */
+export type LandingInconclusiveReason =
+  | 'empty-plan-block'
+  | 'override-unpollable'
+  | 'no-plan-block'
+  | 'no-baseline'
+  | 'baseline-unverified'
+  | 'probe-failure'
+  | 'malformed-signal';
 
 export interface GitStatusEntry {
   readonly raw: string;
@@ -425,23 +454,49 @@ export interface CodeLandingSnapshot {
   readonly maxWaitMs: number;
   readonly expectedPaths: readonly string[];
   readonly changedEntries: readonly GitStatusEntry[];
+  /** the pre-Step-7 baseline. Absent/null ⇒ 'no-baseline' (the delta cannot be computed). */
+  readonly baseline?: BaselineVerification | null;
+  /** path → `git hash-object` NOW, for the paths in `changedEntries`. */
+  readonly currentHashes?: Readonly<Record<string, string>>;
 }
 
 export interface CodeLandingDecision {
   readonly status: CodeLandingStatus;
+  readonly reason?: LandingInconclusiveReason;
   readonly changed: number;
   readonly elapsedMs: number;
   readonly elapsedSeconds: number;
   readonly expectedPaths: readonly string[];
+  /** NEWLY-CHANGED matches only — a path that was already dirty before the coder ran is not a match. */
   readonly matchedExpectedPaths: readonly string[];
   readonly changedPaths: readonly string[];
-  readonly predicate: 'expected-path' | 'any-code-change' | 'empty-before-timeout' | 'empty-after-timeout';
+  /** `'expected-path'` and `'any-code-change'` are DELETED with their branches (ADR-003 / H4):
+   *  matching an ESTABLISHED target is now the only landing predicate, and "any code change" was
+   *  the fallback that read an unrelated dirty file as Codex's work. */
+  readonly predicate: 'newly-changed' | 'no-expected-targets' | 'empty-before-timeout' | 'empty-after-timeout';
   readonly qeSignalLine: string;
 }
 
+/**
+ * The CLOSED landing-predicate vocabulary, as DATA (QE F6) — exhaustive-record derived, so `tsc`
+ * fails the build if the union gains or loses a member. `'expected-path'` and `'any-code-change'`
+ * are DELETED; a consumer that still matches on them will find them absent from this list too.
+ */
+const CODE_LANDING_PREDICATE_SET: Record<CodeLandingDecision['predicate'], true> = {
+  'newly-changed': true,
+  'no-expected-targets': true,
+  'empty-before-timeout': true,
+  'empty-after-timeout': true,
+};
+export const CODE_LANDING_PREDICATES = Object.keys(CODE_LANDING_PREDICATE_SET) as readonly CodeLandingDecision['predicate'][];
+
 export interface CodeLandedBarrierPlan {
   readonly enabled: boolean;
-  readonly mode: 'expected-files' | 'any-code-change';
+  /** `'any-code-change'` survives ONLY as the disabled-barrier placeholder — it is unreachable
+   *  while `enabled` is true (an enabled barrier with no targets is now `'inconclusive'`). */
+  readonly mode: 'expected-files' | 'any-code-change' | 'inconclusive';
+  /** set iff mode === 'inconclusive'. */
+  readonly inconclusiveReason?: LandingInconclusiveReason;
   readonly sleepsMs: readonly number[];
   readonly sleepsSeconds: readonly number[];
   readonly pollWindowMs: number;
@@ -458,26 +513,55 @@ export function needsCodeLandedBarrier(coderUsed: string | null | undefined): bo
   return coderUsed === 'codex' || coderUsed === 'codex-fallback';
 }
 
-export function normalizeCodeLandingPath(path: string): string {
+/** Why a declared expected-target line was refused. Pre-epoch `normalizeCodeLandingPath` returned
+ *  `''` for every reject with NO reason, so a plan whose whole block was mistyped looked exactly
+ *  like a plan with no block — and both degraded to "any code change counts". */
+export type ExpectedTargetRejectReason =
+  | 'empty-after-strip'
+  | 'absolute-path'
+  | 'traversal'
+  | 'pipeline-artifact-path'
+  | 'not-a-path';
+
+export interface ExpectedTargetsValidation {
+  /** the EXPECTED_CODE_TARGETS: block exists in the plan text at all. */
+  readonly present: boolean;
+  readonly accepted: readonly string[];
+  readonly rejected: readonly { readonly line: string; readonly reason: ExpectedTargetRejectReason }[];
+}
+
+/** The normalization half, with no accept/reject opinion. */
+function stripCodeLandingPath(path: string): string {
   let p = String(path || '').trim().replace(/\\/g, '/');
   while (p.indexOf('./') === 0) p = p.slice(2);
-  p = p.replace(/\/+/g, '/');
-  if (!p) return '';
-  if (p[0] === '/') return '';
-  if (p === '..' || p.indexOf('../') === 0 || p.indexOf('/../') >= 0 || p.endsWith('/..')) return '';
-  if (/[\0\r\n\t "'\x60$;&|<>*?()[\]{}!]/.test(p)) return '';
-  if (p.endsWith('/')) return '';
+  return p.replace(/\/+/g, '/');
+}
+
+/** The rejection half, in classification order, NAMING the reason. `normalizeCodeLandingPath` and
+ *  `validateExpectedTargetsBlock` both route through this, so the accept set cannot drift between
+ *  "what the barrier polls" and "what the Step-6/7 boundary reports as accepted". */
+function classifyCodeLandingPathReject(path: string): ExpectedTargetRejectReason | null {
+  const p = stripCodeLandingPath(path);
+  if (!p) return 'empty-after-strip';
+  if (p[0] === '/') return 'absolute-path';
+  if (p === '..' || p.indexOf('../') === 0 || p.indexOf('/../') >= 0 || p.endsWith('/..')) return 'traversal';
+  if (/[\0\r\n\t "'\x60$;&|<>*?()[\]{}!]/.test(p)) return 'not-a-path';
+  if (p.endsWith('/')) return 'not-a-path';
   for (const prefix of CODE_LANDING_PIPELINE_PREFIXES) {
     const bare = prefix.slice(0, -1);
-    if (p === bare || p.indexOf(prefix) === 0) return '';
+    if (p === bare || p.indexOf(prefix) === 0) return 'pipeline-artifact-path';
   }
-  return p;
+  return null;
+}
+
+export function normalizeCodeLandingPath(path: string): string {
+  return classifyCodeLandingPathReject(path) === null ? stripCodeLandingPath(path) : '';
 }
 
 export function filterPollableCodePaths(paths: readonly string[]): readonly string[] {
   const out: string[] = [];
   const seen = new Set<string>();
-  for (const path of paths) {
+  for (const path of paths || []) {
     const normalized = normalizeCodeLandingPath(path);
     if (!normalized || seen.has(normalized)) continue;
     seen.add(normalized);
@@ -489,122 +573,605 @@ export function filterPollableCodePaths(paths: readonly string[]): readonly stri
 export function codeLandedBarrierPlan(
   coderUsed: string | null | undefined,
   expectedPaths: readonly string[] = [],
+  inconclusiveReason?: LandingInconclusiveReason,
 ): CodeLandedBarrierPlan {
-  const enabled = needsCodeLandedBarrier(coderUsed);
-  const pollWindowSeconds = DEFAULT_CODE_LANDING_MAX_WAIT_MS / 1000;
+  const enabled = needsCodeLandedBarrier(coderUsed)
+  const pollWindowSeconds = DEFAULT_CODE_LANDING_MAX_WAIT_MS / 1000
   if (!enabled) {
+    return { enabled: false, mode: 'any-code-change', sleepsMs: [], sleepsSeconds: [], pollWindowMs: 0, pollWindowSeconds: 0, expectedPaths: [], emptySignal: '' }
+  }
+  const filteredExpectedPaths = filterPollableCodePaths(expectedPaths || [])
+  if (filteredExpectedPaths.length === 0) {
     return {
-      enabled: false,
-      mode: 'any-code-change',
+      enabled: true,
+      mode: 'inconclusive',
+      inconclusiveReason: inconclusiveReason === undefined ? 'empty-plan-block' : inconclusiveReason,
       sleepsMs: [],
       sleepsSeconds: [],
       pollWindowMs: 0,
       pollWindowSeconds: 0,
       expectedPaths: [],
-      emptySignal: '',
-    };
+      emptySignal: codeLandingEmptySignal(pollWindowSeconds),
+    }
   }
-  const filteredExpectedPaths = filterPollableCodePaths(expectedPaths);
   return {
     enabled: true,
-    mode: filteredExpectedPaths.length > 0 ? 'expected-files' : 'any-code-change',
+    mode: 'expected-files',
     sleepsMs: DEFAULT_CODE_LANDING_BACKOFF_MS,
     sleepsSeconds: CODE_LANDED_BARRIER_SLEEPS_SECONDS,
     pollWindowMs: DEFAULT_CODE_LANDING_MAX_WAIT_MS,
-    pollWindowSeconds,
+    pollWindowSeconds: pollWindowSeconds,
     expectedPaths: filteredExpectedPaths,
     emptySignal: codeLandingEmptySignal(pollWindowSeconds),
-  };
+  }
+}
+
+// ── Expected-target sourcing (ADR-003) ───────────────────────────────────────────────────────
+
+export interface SourcedCodeTargets {
+  /** the match set IS the established set — a path that did not ESTABLISH cannot MATCH. */
+  readonly targets: readonly string[];
+  readonly establishedBy: 'args' | 'plan' | null;
+  readonly reason?: 'override-unpollable' | 'empty-plan-block' | 'no-plan-block';
+  /** what the coder SAID it would write. Diagnostic only: NEVER unioned into targets, NEVER matched.
+   *  Pre-epoch this was unioned in, which let the agent under test declare its own success criteria. */
+  readonly scrapeDiagnostic: readonly string[];
+}
+
+/** Flatten the many shapes an expected-target value arrives in (string, array, {wrote}, {paths}). */
+export function addExpectedCodeTarget(value: unknown, out: string[]): void {
+  if (value === null || value === undefined) return
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) addExpectedCodeTarget(value[i], out)
+    return
+  }
+  if (typeof value === 'object') {
+    const obj = value as { wrote?: unknown; paths?: unknown }
+    if (Array.isArray(obj.wrote)) addExpectedCodeTarget(obj.wrote, out)
+    if (Array.isArray(obj.paths)) addExpectedCodeTarget(obj.paths, out)
+    return
+  }
+  const lines = String(value).split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const candidate = String(lines[i] || '').replace(/^[-*]\s+/, '').replace(/^\x60+|\x60+$/g, '').trim()
+    if (candidate) out.push(candidate)
+  }
+}
+
+/** Read the `EXPECTED_CODE_TARGETS:` block out of arbitrary text. The block ends at the next
+ *  ALL-CAPS heading line — the shared grammar, used for BOTH the plan block (which establishes)
+ *  and the Codex scrape (which only ever diagnoses). */
+export function extractExpectedCodeTargetsFromText(text: string | null | undefined): string[] {
+  const out: string[] = []
+  const lines = String(text || '').split(/\r?\n/)
+  let inBlock = false
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = String(lines[i] || '').trim()
+    if (/^EXPECTED_CODE_TARGETS:\s*$/i.test(trimmed)) { inBlock = true; continue }
+    if (!inBlock) continue
+    if (!trimmed) continue
+    if (/^[A-Z][A-Z0-9_ -]*:\s*$/.test(trimmed)) break
+    out.push(trimmed.replace(/^[-*]\s+/, '').replace(/^\x60+|\x60+$/g, '').trim())
+  }
+  return out
+}
+
+/**
+ * Where the barrier's expected targets come from, in ADR-003's precedence: an explicit non-empty
+ * ARGS override REPLACES the plan (never unions with it); otherwise the PLAN's block establishes;
+ * the Codex scrape establishes NOTHING.
+ *
+ * The override is NARROWING-ONLY on purpose: args provided but all-unpollable returns an EMPTY
+ * target set with reason 'override-unpollable' and does NOT fall through to the plan. A silent
+ * fall-through would mean "I asked you to watch exactly these files" quietly became "watch the
+ * plan's files", i.e. the operator's narrowing was ignored without a word.
+ */
+export function sourceExpectedCodeTargets(
+  argTargets: unknown,
+  planBlockText: string | null,
+  codexText: string,
+): SourcedCodeTargets {
+  const scrapeRaw: string[] = []
+  addExpectedCodeTarget(extractExpectedCodeTargetsFromText(codexText), scrapeRaw)
+  const scrapeDiagnostic = filterPollableCodePaths(scrapeRaw)
+
+  const argRaw: string[] = []
+  addExpectedCodeTarget(argTargets, argRaw)
+  if (argRaw.length > 0) {
+    const argPaths = filterPollableCodePaths(argRaw)
+    if (argPaths.length > 0) return { targets: argPaths, establishedBy: 'args', scrapeDiagnostic: scrapeDiagnostic }
+    return { targets: [], establishedBy: null, reason: 'override-unpollable', scrapeDiagnostic: scrapeDiagnostic }
+  }
+
+  if (planBlockText === null || planBlockText === undefined) {
+    return { targets: [], establishedBy: null, reason: 'no-plan-block', scrapeDiagnostic: scrapeDiagnostic }
+  }
+  const planRaw: string[] = []
+  addExpectedCodeTarget(extractExpectedCodeTargetsFromText(planBlockText), planRaw)
+  const planPaths = filterPollableCodePaths(planRaw)
+  if (planPaths.length > 0) return { targets: planPaths, establishedBy: 'plan', scrapeDiagnostic: scrapeDiagnostic }
+  return { targets: [], establishedBy: null, reason: 'empty-plan-block', scrapeDiagnostic: scrapeDiagnostic }
+}
+
+/**
+ * Line-level validation of the plan's block at the Step-6/7 boundary (R13) — BEFORE Step 7 spends
+ * tokens. Every rejected line is reported WITH its reason, so a whole-block typo can never present
+ * as "no block declared".
+ */
+export function validateExpectedTargetsBlock(planText: string | null): ExpectedTargetsValidation {
+  const text = String(planText || '')
+  const present = /^EXPECTED_CODE_TARGETS:\s*$/im.test(text)
+  const lines = extractExpectedCodeTargetsFromText(text)
+  const accepted: string[] = []
+  const rejected: { line: string; reason: ExpectedTargetRejectReason }[] = []
+  const seen = new Set<string>()
+  for (const line of lines) {
+    const reason = classifyCodeLandingPathReject(line)
+    if (reason !== null) { rejected.push({ line: line, reason: reason }); continue }
+    const normalized = normalizeCodeLandingPath(line)
+    if (seen.has(normalized)) continue
+    seen.add(normalized)
+    accepted.push(normalized)
+  }
+  return { present: present, accepted: accepted, rejected: rejected }
+}
+
+// ── Pre-Step-7 baseline (R5 + ADR-003 Condition 2) ───────────────────────────────────────────
+
+export interface BaselineEntry {
+  /** `git hash-object` of the path at capture time; `'-'` when unhashable (deleted, unreadable). */
+  readonly hash: string;
+  readonly path: string;
+}
+
+export interface BaselineVerification {
+  readonly ok: boolean;
+  readonly reason?: 'no-baseline' | 'baseline-unverified';
+  /** [] unless ok — a baseline that failed verification has no usable entries, by construction. */
+  readonly entries: readonly BaselineEntry[];
+}
+
+let CKSUM_TABLE: number[] | null = null;
+
+function cksumTable(): number[] {
+  if (CKSUM_TABLE !== null) return CKSUM_TABLE;
+  const table: number[] = [];
+  for (let i = 0; i < 256; i++) {
+    let c = i << 24;
+    for (let k = 0; k < 8; k++) c = (c & 0x80000000) !== 0 ? ((c << 1) ^ 0x04c11db7) >>> 0 : (c << 1) >>> 0;
+    table.push(c >>> 0);
+  }
+  CKSUM_TABLE = table;
+  return table;
+}
+
+/** UTF-8 bytes without TextEncoder — the workflow mirror runs in a sandbox with no host globals. */
+function utf8Bytes(s: string): number[] {
+  const out: number[] = [];
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80) { out.push(c); continue; }
+    if (c < 0x800) { out.push(0xc0 | (c >> 6), 0x80 | (c & 0x3f)); continue; }
+    if (c >= 0xd800 && c <= 0xdbff && i + 1 < s.length) {
+      const next = s.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        const cp = 0x10000 + ((c - 0xd800) << 10) + (next - 0xdc00);
+        out.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 0x3f), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+        i++;
+        continue;
+      }
+    }
+    out.push(0xe0 | (c >> 12), 0x80 | ((c >> 6) & 0x3f), 0x80 | (c & 0x3f));
+  }
+  return out;
+}
+
+/**
+ * POSIX `cksum` CRC (polynomial 0x04C11DB7, length-augmented, final complement) — the PURE twin of
+ * the shell trailer the capture command writes. Known vector: the empty body is 4294967295, and the
+ * test suite cross-checks one fixture against a REAL `cksum` run (H7) so the twin cannot drift.
+ */
+export function posixCksum(body: string): number {
+  const table = cksumTable();
+  const bytes = utf8Bytes(body === null || body === undefined ? '' : String(body));
+  let crc = 0;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = ((crc << 8) ^ (table[((crc >>> 24) ^ (bytes[i] || 0)) & 0xff] || 0)) >>> 0;
+  }
+  let len = bytes.length;
+  while (len > 0) {
+    crc = ((crc << 8) ^ (table[((crc >>> 24) ^ (len & 0xff)) & 0xff] || 0)) >>> 0;
+    len = Math.floor(len / 256);
+  }
+  return (~crc) >>> 0;
+}
+
+/**
+ * Parse + VERIFY a captured baseline. The trailer (`count=<n> cksum=<c>`) is not decoration: a
+ * baseline is the only thing standing between "this path changed" and "this path was ALREADY dirty
+ * when the coder started", so a truncated or edited baseline must read as UNKNOWN, never as a
+ * smaller-but-fine baseline. Every trailer failure collapses to 'baseline-unverified'.
+ *
+ * A valid trailer with ZERO entries is OK — that is a clean tree, a real and common state.
+ */
+export function verifyPreCodeBaseline(text: string | null | undefined): BaselineVerification {
+  if (text === null || text === undefined) return { ok: false, reason: 'no-baseline', entries: [] }
+  const raw = String(text)
+  if (raw.trim() === '') return { ok: false, reason: 'no-baseline', entries: [] }
+  const lines = raw.split('\n')
+  let trailerIndex = -1
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (String(lines[i] || '').trim() === '') continue
+    trailerIndex = i
+    break
+  }
+  if (trailerIndex < 0) return { ok: false, reason: 'no-baseline', entries: [] }
+  const trailer = /^count=(\d+) cksum=(\d+)$/.exec(String(lines[trailerIndex] || '').trim())
+  if (trailer === null) return { ok: false, reason: 'baseline-unverified', entries: [] }
+  const bodyLines = lines.slice(0, trailerIndex)
+  const body = bodyLines.length > 0 ? bodyLines.join('\n') + '\n' : ''
+  const entries: BaselineEntry[] = []
+  for (const line of bodyLines) {
+    const trimmed = String(line || '')
+    if (trimmed.trim() === '') continue
+    const m = /^(\S+) (.+)$/.exec(trimmed)
+    if (m === null) return { ok: false, reason: 'baseline-unverified', entries: [] }
+    entries.push({ hash: String(m[1] || ''), path: String(m[2] || '') })
+  }
+  if (entries.length !== Number(trailer[1])) return { ok: false, reason: 'baseline-unverified', entries: [] }
+  if (posixCksum(body) !== Number(trailer[2])) return { ok: false, reason: 'baseline-unverified', entries: [] }
+  return { ok: true, entries: entries }
+}
+
+/** Parsed verdict of a baseline CAPTURE attempt (QE F2). The capture agent's stdout is a signal the
+ *  workflow must READ, not a formality: a capture that failed leaves either no file or a stale one
+ *  from an earlier attempt, and both make the barrier's later answer meaningless. */
+export interface ParsedBaselineCapture {
+  readonly ok: boolean;
+  /** the baseline file THIS attempt actually wrote, as reported by the capture itself. */
+  readonly path: string | null;
+  readonly entries: number | null;
+  readonly cksum: number | null;
+  readonly reason?: 'capture-failed' | 'no-signal' | 'unsafe-path';
+}
+
+/** PARSE-NEVER-SYNTHESIZE for the capture step: empty/garbage stdout is `no-signal`, an explicit
+ *  failure line is `capture-failed`, and ONLY a well-formed `BASELINE-CAPTURED entries=<n>
+ *  cksum=<c>` line is success. Never infer success from the absence of an error. */
+export function parseBaselineCapture(text: string | null | undefined, expectedPrefix?: string): ParsedBaselineCapture {
+  const raw = text === null || text === undefined ? '' : String(text)
+  if (raw.trim() === '') return { ok: false, path: null, entries: null, cksum: null, reason: 'no-signal' }
+  if (/BASELINE-CAPTURE-FAILED/.test(raw)) return { ok: false, path: null, entries: null, cksum: null, reason: 'capture-failed' }
+  const m = /BASELINE-CAPTURED path=(\S+) entries=(\d+) cksum=(\d+)/.exec(raw)
+  if (m === null) return { ok: false, path: null, entries: null, cksum: null, reason: 'no-signal' }
+  const path = String(m[1] || '')
+  // The path arrives via an agent-relayed stdout, so it is UNTRUSTED text that later becomes a shell
+  // argument. Refuse anything with a metacharacter, and — when the caller says where it asked for the
+  // file — refuse a path outside that prefix. A capture that reports a path we did not ask for is a
+  // failed capture, not a relocated one.
+  if (path === '' || /[\0\r\n\t "'\x60$;&|<>*?()[\]{}!]/.test(path)) {
+    return { ok: false, path: null, entries: null, cksum: null, reason: 'unsafe-path' }
+  }
+  if (expectedPrefix !== undefined && path.indexOf(expectedPrefix) !== 0) {
+    return { ok: false, path: null, entries: null, cksum: null, reason: 'unsafe-path' }
+  }
+  return { ok: true, path: path, entries: Number(m[2]), cksum: Number(m[3]) }
+}
+
+/**
+ * The shell the capture agent runs immediately BEFORE the coder is dispatched.
+ *
+ * FAIL-CLOSED (QE F2), at EVERY step. The pre-fix pipeline sent `git status` through a pipe with
+ * its stderr discarded and its exit status unchecked, so a FAILED status call produced an empty
+ * path list and therefore a checksum-VALID, ZERO-ENTRY baseline — a baseline that verifies
+ * perfectly and claims the tree was clean. Every later path then looks absent-from-baseline, i.e.
+ * newly changed, i.e. LANDED. Round-2 QE found the SAME shape one layer down: the five transforms
+ * after the status call were themselves an unchecked pipeline. So each step now writes its own file
+ * and its status is checked individually; any failure emits `BASELINE-CAPTURE-FAILED` and writes
+ * NOTHING. The file is published (atomic `mv`) only after the
+ * trailer is written, so a failed attempt leaves the previous state untouched rather than a
+ * half-baseline — and the caller must PARSE the success signal (`parseBaselineCapture`) rather than
+ * assume the file on disk belongs to this attempt.
+ *
+ * ATTEMPT-UNIQUE, decided SHELL-SIDE (QE F2). A single stable path let a baseline from an EARLIER,
+ * failed attempt survive and be read by a later probe as if it belonged to that run — and a stale
+ * baseline verifies perfectly while answering about a tree it never saw. The caller passes a
+ * PREFIX; the shell appends `$(date +%s).$$` and REPORTS the path it wrote, so the only path any
+ * consumer can use is the one this execution produced. The uniqueness cannot be generated by the
+ * caller: the workflow that calls this runs in a sandbox with no clock and no randomness (INV-12 —
+ * `Date.now(` and `Math.random(` are lint-banned there, MEASURED via `loop-lint`), so a
+ * caller-side stamp would be a token that cannot exist at the only call site that needs it.
+ *
+ * `--untracked-files=all` (QE F3) is load-bearing, not tidiness: without it a brand-new file inside
+ * a brand-new directory is reported as `?? dir/` — the DIRECTORY, not the file — and the barrier's
+ * exact-match predicate can never match the expected path.
+ */
+export function preCodeBaselineCaptureCmd(repo: string, baselinePathPrefix: string): string {
+  // Every step is status-checked and writes to its OWN file in a scratch dir. The pre-fix version
+  // ran the five transforms as one pipeline whose status nobody read (QE round-2 F2b): a failing
+  // stage produced an EMPTY path list, which then produced a checksum-VALID zero-entry baseline —
+  // a baseline that verifies perfectly and claims the tree was clean, after which every path looks
+  // absent-from-baseline, i.e. newly changed, i.e. LANDED. Same failure shape as the unchecked
+  // `git status`, one layer down.
+  //
+  // `grep` needs its own rule: exit 1 means "no line matched", which is LEGAL and common — at
+  // Step-7 time the only dirty files are often the pipeline's own `features/<slug>/…` artifacts,
+  // and filtering all of them away is the correct answer, not a failure. Only exit > 1 is an error.
+  // (This is why the alternative "empty result from non-empty input ⇒ transform-failed" rule was
+  // NOT used: it would fail-closed on the normal feature-adr run.)
+  const fail = (reason: string): string =>
+    'rm -rf "$sc"; echo "BASELINE-CAPTURE-FAILED reason=' + reason + '"; exit 1';
+  return (
+    'repo=' + codeLandingShellQuote(repo) + '; pre=' + codeLandingShellQuote(baselinePathPrefix) + '; ' +
+    'sc=$(mktemp -d) || { echo "BASELINE-CAPTURE-FAILED reason=mktemp-failed"; exit 1; }; ' +
+    'mkdir -p "$(dirname -- "$pre")" || { ' + fail('mkdir-failed') + '; }; ' +
+    'out="$pre.$(date +%s).$$.txt"; tmp="$sc/base"; ' +
+    'if ! git -C "$repo" status --porcelain --untracked-files=all > "$sc/0"; then ' + fail('git-status-failed') + '; fi; ' +
+    'if ! sed -E "s/^...//" "$sc/0" > "$sc/1"; then ' + fail('transform-failed') + '; fi; ' +
+    'if ! sed -E "s/.* -> //" "$sc/1" > "$sc/2"; then ' + fail('transform-failed') + '; fi; ' +
+    'grep -vE "^(features/|[.]dz/|[.]agentic-qe/|roam/)" "$sc/2" > "$sc/3"; g=$?; ' +
+    'if [ "$g" -gt 1 ]; then ' + fail('transform-failed') + '; fi; ' +
+    'if ! sed "/^$/d" "$sc/3" > "$sc/4"; then ' + fail('transform-failed') + '; fi; ' +
+    'if ! sort "$sc/4" > "$sc/paths"; then ' + fail('transform-failed') + '; fi; ' +
+    ': > "$tmp" || { ' + fail('transform-failed') + '; }; ' +
+    'while IFS= read -r p; do h=$(git -C "$repo" hash-object -- "$p" 2>/dev/null); ' +
+    '[ -z "$h" ] && h="-"; printf "%s %s\\n" "$h" "$p" >> "$tmp"; done < "$sc/paths"; ' +
+    'if ! sort -o "$tmp" "$tmp"; then ' + fail('transform-failed') + '; fi; ' +
+    'n=$(wc -l < "$tmp" | tr -d " "); c=$(cksum < "$tmp" | awk "{print \\$1}"); ' +
+    'if [ -z "$n" ] || [ -z "$c" ]; then ' + fail('transform-failed') + '; fi; ' +
+    'printf "count=%s cksum=%s\\n" "$n" "$c" >> "$tmp" || { ' + fail('transform-failed') + '; }; ' +
+    'if ! mv "$tmp" "$out"; then ' + fail('publish-failed') + '; fi; ' +
+    'rm -rf "$sc"; ' +
+    'echo "BASELINE-CAPTURED path=$out entries=$n cksum=$c"'
+  );
+}
+
+/** Was `path` changed BY THE CODER, rather than already dirty when the baseline was taken?
+ *  Absent from the baseline ⇒ yes. Present with a DIFFERENT current hash ⇒ yes. Present with the
+ *  same hash, or present with no current hash to compare ⇒ NO (fail-closed: without hash evidence
+ *  a pre-dirty path must not read as landed — that read is exactly acid 003-5a). */
+function isNewlyChanged(
+  path: string,
+  baseline: BaselineVerification | null | undefined,
+  currentHashes: Readonly<Record<string, string>> | undefined,
+): boolean {
+  if (!baseline || !baseline.ok) return false
+  let recorded = null
+  for (const entry of baseline.entries) {
+    if (entry.path === path) { recorded = entry.hash; break }
+  }
+  if (recorded === null) return true
+  const now = currentHashes ? currentHashes[path] : undefined
+  if (now === undefined) return false
+  return now !== recorded
 }
 
 export function codeLandedBarrierHasLanded(
   changedPaths: readonly string[],
   expectedPaths: readonly string[] = [],
+  baseline?: BaselineVerification | null,
+  currentHashes?: Readonly<Record<string, string>>,
 ): boolean {
-  const filteredChangedPaths = filterPollableCodePaths(changedPaths);
-  const filteredExpectedPaths = filterPollableCodePaths(expectedPaths);
-  if (filteredExpectedPaths.length === 0) return filteredChangedPaths.length > 0;
-  const changed = new Set(filteredChangedPaths);
+  const filteredChangedPaths = filterPollableCodePaths(changedPaths)
+  const filteredExpectedPaths = filterPollableCodePaths(expectedPaths)
+  // ADR-003: an EMPTY expected set can never establish landing. The pre-epoch `return
+  // filteredChangedPaths.length > 0` here is why an unrelated dirty file read as Codex's work.
+  if (filteredExpectedPaths.length === 0) return false
+  const changed = new Set(filteredChangedPaths)
   for (const expectedPath of filteredExpectedPaths) {
-    if (changed.has(expectedPath)) return true;
+    if (!changed.has(expectedPath)) continue
+    // no baseline supplied ⇒ this is the plain dirty-match question (decideCodeLanding does the
+    // delta filtering itself); with a baseline ⇒ the newly-changed predicate.
+    if (baseline === undefined) return true
+    if (isNewlyChanged(expectedPath, baseline, currentHashes)) return true
   }
-  return false;
+  return false
 }
 
 export function decideCodeLanding(snapshot: CodeLandingSnapshot): CodeLandingDecision {
-  const maxWaitMs = Math.max(0, snapshot.maxWaitMs);
-  const elapsedMs = Math.max(0, snapshot.elapsedMs);
-  const elapsedSeconds = Math.floor(elapsedMs / 1000);
-  const expectedPaths = filterPollableCodePaths(snapshot.expectedPaths);
-  const changedPaths = filterPollableCodePaths(snapshot.changedEntries.map((entry) => entry.path));
-  const changed = new Set(changedPaths);
-  const matchedExpectedPaths = expectedPaths.filter((path) => changed.has(path));
-
-  if (expectedPaths.length > 0 && matchedExpectedPaths.length > 0) {
+  const maxWaitMs = Math.max(0, snapshot.maxWaitMs)
+  const elapsedMs = Math.max(0, snapshot.elapsedMs)
+  const elapsedSeconds = Math.floor(elapsedMs / 1000)
+  const expectedPaths = filterPollableCodePaths(snapshot.expectedPaths)
+  const changedPaths = filterPollableCodePaths(snapshot.changedEntries.map(function (entry) { return entry.path }))
+
+  // (1) nothing was ESTABLISHED to watch for. Pre-epoch this fell through to "any code change
+  // counts" and returned status=landed off an unrelated dirty file.
+  if (expectedPaths.length === 0) {
     return {
-      status: 'landed',
-      changed: matchedExpectedPaths.length,
-      elapsedMs,
-      elapsedSeconds,
-      expectedPaths,
-      matchedExpectedPaths,
-      changedPaths,
-      predicate: 'expected-path',
-      qeSignalLine:
-        'CODEX-LANDING-SIGNAL status=landed changed=' +
-        matchedExpectedPaths.length +
-        ' after=' +
-        elapsedSeconds +
-        's predicate=expected-path matched=' +
-        matchedExpectedPaths.join(','),
-    };
+      status: 'inconclusive',
+      reason: 'empty-plan-block',
+      changed: 0,
+      elapsedMs: elapsedMs,
+      elapsedSeconds: elapsedSeconds,
+      expectedPaths: expectedPaths,
+      matchedExpectedPaths: [],
+      changedPaths: changedPaths,
+      predicate: 'no-expected-targets',
+      qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=no-expected-targets reason=empty-plan-block',
+    }
   }
 
-  if (expectedPaths.length === 0 && changedPaths.length > 0) {
+  // (2) without a VERIFIED baseline the newly-changed delta cannot be computed at all. Answering
+  // the dirty-match question instead would silently re-open acid 003-5a, so we answer "unknown".
+  const baseline = snapshot.baseline
+  if (!baseline || !baseline.ok) {
+    const reason = baseline && baseline.reason ? baseline.reason : 'no-baseline'
+    return {
+      status: 'inconclusive',
+      reason: reason,
+      changed: 0,
+      elapsedMs: elapsedMs,
+      elapsedSeconds: elapsedSeconds,
+      expectedPaths: expectedPaths,
+      matchedExpectedPaths: [],
+      changedPaths: changedPaths,
+      predicate: 'newly-changed',
+      qeSignalLine: 'CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=' + reason,
+    }
+  }
+
+  const changed = new Set(changedPaths)
+  const matchedExpectedPaths = expectedPaths.filter(function (path) {
+    return changed.has(path) && isNewlyChanged(path, baseline, snapshot.currentHashes)
+  })
+
+  if (matchedExpectedPaths.length > 0) {
     return {
       status: 'landed',
-      changed: changedPaths.length,
-      elapsedMs,
-      elapsedSeconds,
-      expectedPaths,
-      matchedExpectedPaths,
-      changedPaths,
-      predicate: 'any-code-change',
+      changed: matchedExpectedPaths.length,
+      elapsedMs: elapsedMs,
+      elapsedSeconds: elapsedSeconds,
+      expectedPaths: expectedPaths,
+      matchedExpectedPaths: matchedExpectedPaths,
+      changedPaths: changedPaths,
+      predicate: 'newly-changed',
       qeSignalLine:
         'CODEX-LANDING-SIGNAL status=landed changed=' +
-        changedPaths.length +
+        matchedExpectedPaths.length +
         ' after=' +
         elapsedSeconds +
-        's predicate=any-code-change',
-    };
+        's predicate=newly-changed matched=' +
+        matchedExpectedPaths.join(','),
+    }
   }
 
   if (elapsedMs < maxWaitMs) {
     return {
       status: 'not-yet-flushed',
       changed: 0,
-      elapsedMs,
-      elapsedSeconds,
-      expectedPaths,
+      elapsedMs: elapsedMs,
+      elapsedSeconds: elapsedSeconds,
+      expectedPaths: expectedPaths,
       matchedExpectedPaths: [],
-      changedPaths,
+      changedPaths: changedPaths,
       predicate: 'empty-before-timeout',
       qeSignalLine: 'CODEX-LANDING-SIGNAL status=not-yet-flushed changed=0 after ' + elapsedSeconds + 's — not yet flushed',
-    };
+    }
   }
 
-  const terminalSeconds = Math.ceil(maxWaitMs / 1000);
+  const terminalSeconds = Math.ceil(maxWaitMs / 1000)
   return {
     status: 'genuinely-not-landed',
     changed: 0,
-    elapsedMs,
+    elapsedMs: elapsedMs,
     elapsedSeconds: terminalSeconds,
-    expectedPaths,
+    expectedPaths: expectedPaths,
     matchedExpectedPaths: [],
-    changedPaths,
+    changedPaths: changedPaths,
     predicate: 'empty-after-timeout',
     qeSignalLine: 'CODEX-LANDING-SIGNAL status=genuinely-not-landed ' + codeLandingEmptySignal(terminalSeconds),
-  };
+  }
+}
+
+// ── The single normalization helper: probe stdout → status, parsed EXACTLY ONCE ───────────────
+
+export interface ParsedLandingSignal {
+  readonly status: 'landed' | 'genuinely-not-landed' | 'inconclusive';
+  readonly reason?: LandingInconclusiveReason;
+}
+
+/**
+ * PARSE-NEVER-SYNTHESIZE, applied to the barrier the same way ADR-001 applies it to a QE verdict:
+ * a probe that returned nothing, or text with no signal line, is NOT a clean "not landed" and NOT
+ * a landed — it is `inconclusive` with the reason naming which failure it was. An unknown status
+ * token (including a stray mid-poll `not-yet-flushed` reaching a terminal position) is malformed,
+ * never trusted. Every consumer reads THIS function's output; no consumer re-regexes the note.
+ */
+export function parseLandingSignal(probeText: string | null | undefined): ParsedLandingSignal {
+  const text = probeText === null || probeText === undefined ? '' : String(probeText)
+  if (text.trim() === '') return { status: 'inconclusive', reason: 'probe-failure' }
+  const lines = text.split(/\r?\n/)
+  let signal = ''
+  for (let i = 0; i < lines.length; i++) {
+    if (String(lines[i] || '').indexOf('CODEX-LANDING-SIGNAL status=') >= 0) { signal = String(lines[i] || ''); break }
+  }
+  if (signal === '') return { status: 'inconclusive', reason: 'malformed-signal' }
+  const m = /CODEX-LANDING-SIGNAL status=([A-Za-z-]+)/.exec(signal)
+  const status = m === null ? '' : String(m[1] || '')
+  if (status === 'landed') return { status: 'landed' }
+  if (status === 'genuinely-not-landed') return { status: 'genuinely-not-landed' }
+  if (status !== 'inconclusive') return { status: 'inconclusive', reason: 'malformed-signal' }
+  const r = /reason=([a-z-]+)/.exec(signal)
+  const reason = r === null ? '' : String(r[1] || '')
+  switch (reason) {
+    case 'empty-plan-block':
+    case 'override-unpollable':
+    case 'no-plan-block':
+    case 'no-baseline':
+    case 'baseline-unverified':
+    case 'probe-failure':
+    case 'malformed-signal':
+      return { status: 'inconclusive', reason: reason }
+    default:
+      return { status: 'inconclusive', reason: 'malformed-signal' }
+  }
+}
+
+function codeLandingShellQuote(value: string): string {
+  return "'" + String(value).replace(/'/g, "'\"'\"'") + "'"
+}
+
+/**
+ * The probe shell (pure half of the workflow's inline copy). Obligations, in order:
+ *
+ *   1. mode 'inconclusive' short-circuits — polling with no established target is exactly what
+ *      produced the false "any code change" landing verdict.
+ *   2. VERIFY the baseline trailer BEFORE any absent-from-baseline reasoning, because a truncated
+ *      baseline makes every missing path look newly changed, i.e. makes everything look LANDED.
+ *   3. only then poll with the newly-changed predicate: in the porcelain AND (absent from the
+ *      baseline OR `git hash-object` differs).
+ *
+ * Terminal landed / genuinely-not-landed lines keep today's grammar so parseLandingSignal covers all.
+ *
+ * Three properties of the POLL that are load-bearing rather than stylistic:
+ *
+ * - `--untracked-files=all` (QE F3): without it git reports a brand-new file inside a brand-new
+ *   directory as `?? dir/` — the DIRECTORY — so an exact match against the expected FILE path can
+ *   never fire and a genuinely landed file reads as not-landed.
+ * - the match set is NEVER truncated (QE F3): the pre-fix probe piped the porcelain through
+ *   `head -200` and then searched THAT, so on any tree with more than 200 dirty entries the
+ *   predicate silently stopped seeing the tail. Our own settled tree had 292. The cap now applies
+ *   ONLY to the human-readable file list that gets echoed.
+ * - the probe's own scratch files live in `mktemp` space, NOT beside the baseline: a redirection
+ *   creates its target BEFORE the command writes to it, so a scratch file next to the baseline
+ *   appears in the very `git status` it is about to feed (MEASURED — a capture into a fixture repo
+ *   recorded its own `.raw` file as the tree's only dirty entry). In production the path sits under
+ *   `features/` and the pipeline-prefix filter hid it; the filter is not the guarantee.
+ * - the baseline lookup compares the path as a LITERAL (QE F4): it used to interpolate the path into
+ *   a `sed -E` pattern, where `.` and `+` — both legal in the accepted path grammar — are regex
+ *   metacharacters, so `a.b.ts` could match the recorded line for `axb.ts` and pick up the WRONG
+ *   hash. `awk -v` with a field-split equality has no pattern semantics at all.
+ */
+export function codeLandingProbeCmd(repo: string, plan: CodeLandedBarrierPlan, baselineAbsPath: string): string {
+  if (plan.mode === 'inconclusive') {
+    const reason = plan.inconclusiveReason === undefined ? 'empty-plan-block' : plan.inconclusiveReason
+    return 'echo "CODEX-LANDING-SIGNAL status=inconclusive predicate=no-expected-targets reason=' + reason + '"; echo "files:"; echo "(none)"'
+  }
+  const expectedList = plan.expectedPaths.length > 0 ? plan.expectedPaths.map(codeLandingShellQuote).join(' ') : "''"
+  return (
+    'repo=' + codeLandingShellQuote(repo) + '; base=' + codeLandingShellQuote(baselineAbsPath) + '; ' +
+    'sleeps="' + plan.sleepsSeconds.join(' ') + '"; expected_count=' + plan.expectedPaths.length + '; elapsed=0; ' +
+    'if [ ! -f "$base" ]; then echo "CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=no-baseline"; echo "files:"; echo "(none)"; exit 0; fi; ' +
+    'body=$(mktemp) || { echo "CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=probe-failure"; echo "files:"; echo "(none)"; exit 0; }; ' +
+    'pfile=$(mktemp) || { rm -f "$body"; echo "CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=probe-failure"; echo "files:"; echo "(none)"; exit 0; }; ' +
+    'bl=$(wc -l < "$base" | tr -d " "); head -n $((bl - 1)) "$base" > "$body"; ' +
+    'tr_line=$(tail -n 1 "$base"); tr_n=$(printf "%s" "$tr_line" | sed -nE "s/^count=([0-9]+) cksum=([0-9]+)$/\\1/p"); ' +
+    'tr_c=$(printf "%s" "$tr_line" | sed -nE "s/^count=([0-9]+) cksum=([0-9]+)$/\\2/p"); ' +
+    'n_body=$(wc -l < "$body" | tr -d " "); c_body=$(cksum < "$body" | awk "{print \\$1}"); ' +
+    'if [ -z "$tr_n" ] || [ "$tr_n" != "$n_body" ] || [ "$tr_c" != "$c_body" ]; then rm -f "$body" "$pfile"; echo "CODEX-LANDING-SIGNAL status=inconclusive predicate=newly-changed reason=baseline-unverified"; echo "files:"; echo "(none)"; exit 0; fi; ' +
+    'newly(){ recorded=$(awk -v want="$1" \'{ i = index($0, " "); if (i > 0 && substr($0, i + 1) == want) { print substr($0, 1, i - 1); exit } }\' "$body"); ' +
+    'if [ -z "$recorded" ]; then return 0; fi; now=$(git -C "$repo" hash-object -- "$1" 2>/dev/null); ' +
+    'if [ -z "$now" ] || [ "$now" = "$recorded" ]; then return 1; fi; return 0; }; ' +
+    'poll(){ git -C "$repo" status --porcelain --untracked-files=all 2>/dev/null | sed -E "s/^...//" | sed -E "s/.* -> //" | grep -vE "^(features/|[.]dz/|[.]agentic-qe/|roam/)" | sed "/^$/d" > "$pfile"; ' +
+    'n=$(wc -l < "$pfile" | tr -d " "); ' +
+    'matched=""; for p in ' + expectedList + '; do [ -z "$p" ] && continue; ' +
+    'if grep -Fx -- "$p" "$pfile" >/dev/null && newly "$p"; then matched="$p"; break; fi; done; ' +
+    'if [ -n "$matched" ]; then echo "CODEX-LANDING-SIGNAL status=landed changed=1 after=${elapsed}s predicate=newly-changed"; echo "matched=$matched"; echo "files:"; head -40 "$pfile"; rm -f "$body" "$pfile"; exit 0; fi; }; ' +
+    'poll; for wait in $sleeps; do sleep "$wait"; elapsed=$((elapsed + wait)); poll; done; ' +
+    'echo "CODEX-LANDING-SIGNAL status=genuinely-not-landed ' + plan.emptySignal + '"; echo "predicate=newly-changed observed=$n"; ' +
+    'echo "files:"; if [ -s "$pfile" ]; then head -40 "$pfile"; else echo "(none)"; fi; rm -f "$body" "$pfile"'
+  );
 }
 
 /**
@@ -912,3 +1479,58 @@ export function checkArtifactRoot(root: string): string | null {
   if (hasDotDotSegment(root)) return 'artifact root contains a ".." segment: ' + root;
   return null;
 }
+
+
+// ── K2 plan-completeness gate (feature fa-plan-gate-wiring) ────────────────────────────────────
+// Step 7 must not start on an incomplete plan. The gate is a SCRIPT the pipeline shells out to;
+// these two pure halves build its command and PARSE its verdict. The workflow inlines byte-equivalent
+// copies (drift-guarded), because the workflow sandbox cannot import.
+
+/** The one path the pipeline calls. Repo-relative — the command `cd`s into the repo root first. */
+export const PLAN_GATE_SCRIPT = '.claude/skills/feature-adr/scripts/check-plan-completeness.mjs';
+
+export interface PlanGateVerdict {
+  /** 'pass' ONLY when the script's own last line AND its exit code agree on PASS. */
+  verdict: 'pass' | 'fail' | 'not-established';
+  /** The script's exit code as reported by the `K2_EXIT=` trailer, or null when unparseable. */
+  exit: number | null;
+  reason: string;
+  output: string;
+}
+
+/**
+ * The EXACT command the gate agent runs. `2>&1` folds stderr in (a crash must be visible, not
+ * silently empty) and the `K2_EXIT=` trailer carries the exit code back through an agent that can
+ * only return text.
+ */
+export function planCompletenessGateCmd(repo: string, featureDir: string, tier?: string | null): string {
+  const q = (s: string) => "'" + String(s).replace(/'/g, "'\\''") + "'"
+  const t = (typeof tier === 'string' && tier !== '') ? ' --tier=' + q(tier) : ''
+  return 'cd ' + q(repo) + ' && node ' + q(PLAN_GATE_SCRIPT) + ' ' + q(featureDir) + t + ' 2>&1; echo K2_EXIT=$?'
+}
+
+/**
+ * PARSE-NEVER-SYNTHESIZE. An empty reply, a reply with no verdict line, a missing/unknown exit code,
+ * or a verdict line that DISAGREES with the exit code are all `not-established` — never a pass. The
+ * quiet failure this forecloses: a dead or chatty agent reading as a clean gate.
+ */
+export function parsePlanGateVerdict(raw: string | null | undefined): PlanGateVerdict {
+  const text = String(raw === null || raw === undefined ? '' : raw)
+  const output = text.slice(0, 2000)
+  if (text.trim() === '') return { verdict: 'not-established', exit: null, reason: 'empty-agent-reply', output: output }
+  // G-F1 (reproduced by execution): the checker ECHOES plan-controlled content, so a forged verdict
+  // line and a forged K2_EXIT trailer can appear EARLIER in this stream. The script always writes its
+  // own verdict LAST, so both halves anchor to the LAST match — a first-match read let a planted
+  // 'K2 plan-completeness: PASS (0) K2_EXIT=0' target line forge a pass on a genuine FAIL/1 run.
+  const exitAll = text.match(/K2_EXIT=(\d+)/g)
+  const lastExit = exitAll === null ? null : /K2_EXIT=(\d+)/.exec(String(exitAll[exitAll.length - 1]))
+  const exitCode = lastExit === null ? null : Number(lastExit[1])
+  const verdictAll = text.match(/K2 plan-completeness:\s*(PASS|FAIL|NOT-ESTABLISHED)/g)
+  if (verdictAll === null) return { verdict: 'not-established', exit: exitCode, reason: 'no-verdict-line', output: output }
+  const lastVerdict = String(verdictAll[verdictAll.length - 1])
+  const byName = lastVerdict.indexOf('PASS') >= 0 ? 'pass' : (lastVerdict.indexOf('FAIL') >= 0 ? 'fail' : 'not-established')
+  const byExit = exitCode === 0 ? 'pass' : (exitCode === 1 ? 'fail' : (exitCode === 3 ? 'not-established' : null))
+  if (byExit === null) return { verdict: 'not-established', exit: exitCode, reason: 'unknown-exit-code', output: output }
+  if (byExit !== byName) return { verdict: 'not-established', exit: exitCode, reason: 'verdict-exit-mismatch', output: output }
+  return { verdict: byName, exit: exitCode, reason: 'script-verdict', output: output }
+}