@junghanacs/entwurf 0.13.0 → 0.13.1

package/scripts/check-release-gate-outcomes.ts

@@ -0,0 +1,332 @@
+// Deterministic gate for the release-gate STEP OUTCOME protocol (P1).
+//
+// THE DEFECT THIS OWNS. The aggregate release gate documented — in run.sh's own
+// usage, README, and VERIFY — that a cut needs `LIVE=1` and `SKIP=0`. Nothing
+// enforced it. Exit authority read the FAIL counter alone, so
+// `./run.sh release-gate <dir>` returned 0 while printing 14 SKIPs and the words
+// "all green". And a step that WAS invoked could decline a prerequisite and exit
+// 0 — Cortex without `ENTWURF_ACP_CORTEX_CONNECTION` is the measured case — which
+// the aggregate counted as PASS. Both holes are the same shape: a skip that
+// cannot be told apart from an acceptance, which means a release summary cannot
+// prove the calls it claims.
+//
+// WHAT THIS GATE PINS, in the order the cells run (the order is load-bearing:
+// each mutant must die on ITS claim, so a cell that would fire first on another
+// cell's mutation is deliberately kept narrow):
+//   1. the protocol is ONE number, agreed across the shell and TS halves;
+//   2. the classifier never rounds a skip up to a pass;
+//   3. `--cut` refuses a MUST skip while a bare diagnostic run does not, AND the
+//      refusal names its cause — a step that RAN AND BROKE is a different fact
+//      from one that NEVER RAN, and the counters are never fudged to carry it;
+//   4. no LIVE smoke still carries the pre-P1 exit-0 skip shape;
+//   5. a real smoke invoked with LIVE unset propagates the protocol code out
+//      through run_ts (the "direct LIVE!=1" case);
+//   6. a run.sh wrapper that declines its own prerequisite does the same (the
+//      "internal prerequisite" case, Cortex being the one that was measured).
+//   7. every LIVE smoke is either wired into the aggregate or excluded for a
+//      reason the docs actually state — the protocol cannot vouch for a step the
+//      gate never lists.
+//
+// Cells 5-6 SPAWN the real subcommands rather than reasoning about them: the
+// whole defect was an assumption about what a step would do, so an assumption is
+// exactly what this gate must not make. They are cheap — each smoke declines
+// before it does any work.
+//
+// Pure + subprocess, no network/model — IN pnpm check.
+
+import { strict as assert } from "node:assert";
+import { execFileSync } from "node:child_process";
+import { globSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { LIVE_SKIP_EXIT, LIVE_SKIP_MARKER } from "./lib/live-skip.ts";
+
+const REPO_DIR = fileURLToPath(new URL("..", import.meta.url));
+const SHELL_LIB = "scripts/lib/step-outcome.sh";
+
+/** Run a snippet with the shell half sourced; returns trimmed stdout. */
+function inShell(snippet: string): string {
+	return execFileSync("bash", ["-c", `. "${SHELL_LIB}"; ${snippet}`], {
+		cwd: REPO_DIR,
+		encoding: "utf8",
+		timeout: 20_000,
+	}).trim();
+}
+
+/** Invoke a real run.sh subcommand; returns its exit code + combined output. */
+function runSubcommand(sub: string, env: Record<string, string | undefined>): { code: number; output: string } {
+	const childEnv: Record<string, string> = {};
+	for (const [k, v] of Object.entries({ ...process.env, ...env })) {
+		if (v !== undefined) childEnv[k] = v;
+	}
+	try {
+		const out = execFileSync("bash", ["run.sh", sub], {
+			cwd: REPO_DIR,
+			encoding: "utf8",
+			timeout: 120_000,
+			env: childEnv,
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		return { code: 0, output: out };
+	} catch (err) {
+		const e = err as { status?: number | null; stdout?: string; stderr?: string };
+		return { code: e.status ?? -1, output: `${e.stdout ?? ""}${e.stderr ?? ""}` };
+	}
+}
+
+// ===========================================================================
+// 1) ONE protocol, two languages. A drifted constant does not degrade
+//    gracefully — it silently reclassifies every skip in the aggregate.
+// ===========================================================================
+{
+	const shellValue = inShell('echo "$ENTWURF_STEP_SKIP_EXIT"');
+	assert.equal(
+		shellValue,
+		String(LIVE_SKIP_EXIT),
+		`[QK:SKIP-EXIT-ONE-PROTOCOL] ${SHELL_LIB} and scripts/lib/live-skip.ts must name the SAME skip exit code. ` +
+			"The smokes exit with the TS constant and the aggregate classifies with the shell one, so a drift between " +
+			"them turns every honest skip into a FAIL (or, the other way, into a PASS) with nothing in the summary " +
+			`saying so. shell=${shellValue} ts=${LIVE_SKIP_EXIT}`,
+	);
+	// The code must also stay clear of the ranges that already mean something
+	// else, or a dependency's unrelated verdict reads as a skip.
+	assert.ok(
+		LIVE_SKIP_EXIT > 4 && LIVE_SKIP_EXIT < 126,
+		"the skip code must avoid the per-tool contract band (0..4) and the shell's signal band (126+)",
+	);
+}
+
+// ===========================================================================
+// 2) The classifier. A skip is its own outcome, never rounded up or down.
+// ===========================================================================
+{
+	const table: Array<[string, string]> = [
+		["0", "PASS"],
+		[String(LIVE_SKIP_EXIT), "SKIP"],
+		["1", "FAIL"],
+		["2", "FAIL"],
+		["127", "FAIL"],
+		["137", "FAIL"],
+	];
+	for (const [code, expected] of table) {
+		const got = inShell(`entwurf_step_outcome ${code}`);
+		assert.equal(
+			got,
+			expected,
+			`[QK:STEP-OUTCOME-SKIP-NOT-PASS] exit ${code} must classify as ${expected}, got ${got}. A skip rounded up to ` +
+				"PASS is exactly the pre-P1 defect: the aggregate then reports acceptance for a step that told it, in the " +
+				"only channel it has, that it never ran. A skip rounded down to FAIL is the mirror error and makes the " +
+				"unattended diagnostic unusable.",
+		);
+	}
+}
+
+// ===========================================================================
+// 3) Cut authority. `--cut` is the executable half of "a CUT needs SKIP=0";
+//    without it the diagnostic must stay green so an unattended run is usable.
+// ===========================================================================
+{
+	const releasable = (failc: number, skipc: number, cut: number): boolean =>
+		inShell(`if entwurf_release_releasable ${failc} ${skipc} ${cut}; then echo YES; else echo NO; fi`) === "YES";
+
+	assert.ok(releasable(0, 0, 1), "a cut with no failures and no skips is releasable");
+	assert.ok(!releasable(1, 0, 1), "a failure blocks a cut");
+	assert.ok(!releasable(1, 0, 0), "a failure blocks the diagnostic too — FAIL was always blocking");
+	assert.ok(
+		releasable(0, 3, 0),
+		"a DIAGNOSTIC run with skips stays exit 0 — an unattended `./run.sh release-gate` must remain runnable, and " +
+			"turning it red was never the ask",
+	);
+	assert.ok(
+		!releasable(0, 3, 1),
+		"[QK:CUT-REFUSES-SKIP] `--cut` must refuse a MUST SKIP. This is the whole point: the release procedure said " +
+			'"a CUT needs LIVE=1, SKIP=0" in prose while the code returned 0 with 14 skips, so a summary could be quoted ' +
+			"as acceptance for calls that never happened. It also removes the need for a separate LIVE assertion — with " +
+			"LIVE unset every LIVE-gated step skips, and the skip count is what blocks.",
+	);
+
+	// …and the refusal must SAY WHICH of the two it is. A blocked cut caused by a
+	// broken call and one caused by an absent prerequisite need different actions
+	// from whoever reads the record, and the counters must not be fudged to carry
+	// that (a synthesized FAIL=1 for a policy block erases the distinction).
+	const verdict = (failc: number, skipc: number, cut: number): string =>
+		inShell(`entwurf_release_verdict ${failc} ${skipc} ${cut}`);
+
+	assert.equal(verdict(0, 0, 1), "cut: OK", "a clean cut says so in one token");
+	assert.equal(
+		verdict(0, 3, 0),
+		"cut: n/a (diagnostic, 3 SKIP)",
+		"a diagnostic run names its skips without claiming a cut",
+	);
+	assert.equal(verdict(0, 0, 0), "cut: n/a (diagnostic)", "a clean diagnostic run still does not claim a cut");
+	assert.equal(
+		verdict(1, 0, 1),
+		"cut: BLOCKED (MUST FAIL)",
+		"a step that RAN AND BROKE must be named as a failure — that is a defect to fix",
+	);
+	assert.equal(
+		verdict(0, 3, 1),
+		"cut: BLOCKED (MUST SKIP)",
+		"[QK:CUT-VERDICT-NAMES-CAUSE] a cut blocked ONLY by skips must say so in its own token, distinct from a failure " +
+			"block. An operator (and the P5 release record) reads two different actions out of these: a MUST FAIL is a " +
+			"broken call to fix, a MUST SKIP is a prerequisite to supply. Collapsing them into one string — or worse, " +
+			"synthesizing FAIL=1 for the policy block — throws away the exact distinction this protocol was built to make.",
+	);
+	assert.equal(
+		verdict(2, 5, 1),
+		"cut: BLOCKED (MUST FAIL)",
+		"when both are present the FAILURE is the headline — a broken call outranks a missing prerequisite",
+	);
+}
+
+// ===========================================================================
+// 4) No LIVE smoke still carries the pre-P1 skip shape (static, all of them).
+//    A future smoke that hand-rolls `exit 0` on a skip re-opens the hole for
+//    one lane only, which is precisely how this survived so long.
+// ===========================================================================
+{
+	const smokes = globSync("scripts/smoke-*live*.ts", { cwd: REPO_DIR }).sort();
+	assert.ok(smokes.length >= 15, `expected the LIVE smoke family, found ${smokes.length}`);
+	let liveGated = 0;
+	for (const rel of smokes) {
+		const src = readFileSync(join(REPO_DIR, rel), "utf8");
+		if (!src.includes("process.env.LIVE")) continue; // gated in run.sh instead (cell 6 owns that surface)
+		liveGated++;
+		// ONE assertion, three ways to fail it: no protocol import, or either of
+		// the two pre-P1 shapes (exit 0 / bare return) still inside the LIVE gate.
+		// Kept as one so the claim owns every way a smoke can go back to being
+		// indistinguishable from success — a split would let a mutation die on an
+		// unclaimed sibling assertion instead of here.
+		const importsProtocol = src.includes('from "./lib/live-skip.ts"');
+		const exitsZero = /LIVE !== "1"[\s\S]{0,400}?process\.exit\(0\)/.test(src);
+		const bareReturns = /LIVE !== "1"[\s\S]{0,400}?\n\t+return;/.test(src);
+		assert.ok(
+			importsProtocol && !exitsZero && !bareReturns,
+			`[QK:NO-SMOKE-SKIPS-WITH-ZERO] ${basename(rel)} gates on LIVE but does not decline through skipLive ` +
+				`(importsProtocol=${importsProtocol} exitsZero=${exitsZero} bareReturns=${bareReturns}). Every LIVE smoke ` +
+				"must take the one protocol exit — a hand-rolled `process.exit(0)` or bare `return` is indistinguishable " +
+				"from success, which is exactly what let the aggregate count a never-run step as PASS.",
+		);
+	}
+	assert.ok(liveGated >= 15, `expected most LIVE smokes to gate on LIVE, got ${liveGated}`);
+}
+
+// ===========================================================================
+// 5) REAL propagation — the direct `LIVE!=1` case, end to end through run_ts.
+//    Static source pins cannot see a transport that swallows the code.
+// ===========================================================================
+{
+	const { code, output } = runSubcommand("smoke-acp-raw-turn-live", { LIVE: undefined });
+	assert.equal(
+		code,
+		LIVE_SKIP_EXIT,
+		`[QK:LIVE-SKIP-IS-PROTOCOL-EXIT] a LIVE smoke invoked with LIVE unset must leave the protocol's SKIP code on ` +
+			`the process, all the way out through run_ts — got exit ${code}. Exit 0 here is the original defect: the ` +
+			`aggregate cannot tell "I declined" from "I passed", so it reports acceptance. Output: ` +
+			`${JSON.stringify(output.slice(-300))}`,
+	);
+	assert.ok(
+		output.includes(LIVE_SKIP_MARKER),
+		`the skip must also be readable by a human in the log — ${LIVE_SKIP_MARKER} names the missing prerequisite so an ` +
+			"operator who hits a red --cut run knows what to supply. Output: " +
+			JSON.stringify(output.slice(-300)),
+	);
+}
+
+// ===========================================================================
+// 6) REAL propagation — a run.sh WRAPPER declining its own prerequisite. This
+//    is the second skip surface: some smokes never reach their .ts file at all.
+// ===========================================================================
+{
+	const viaWrapper = runSubcommand("smoke-acp-cortex-live", { LIVE: undefined });
+	assert.equal(
+		viaWrapper.code,
+		LIVE_SKIP_EXIT,
+		`[QK:WRAPPER-SKIP-IS-PROTOCOL-EXIT] a run.sh smoke WRAPPER that declines a prerequisite must return the protocol ` +
+			`SKIP code, not 0 — got exit ${viaWrapper.code}. The wrapper is a skip surface of its own (cortex, matrix, ` +
+			"spawn-live and spawn-resume all decline before their .ts is ever reached), so fixing only the TypeScript " +
+			`half would leave the aggregate counting those as PASS. Output: ${JSON.stringify(viaWrapper.output.slice(-300))}`,
+	);
+
+	// The measured Cortex cell: LIVE IS set, but the connection the adapter needs
+	// is not. Which branch declines (the wrapper's `cortex` PATH check or the
+	// smoke's own connection check) depends on the host; the OUTCOME must not.
+	const missingPrereq = runSubcommand("smoke-acp-cortex-live", {
+		LIVE: "1",
+		ENTWURF_ACP_CORTEX_CONNECTION: undefined,
+	});
+	assert.equal(
+		missingPrereq.code,
+		LIVE_SKIP_EXIT,
+		"LIVE=1 with no ENTWURF_ACP_CORTEX_CONNECTION must be a SKIP, not a PASS — this is the exact cell that made a " +
+			"cortex-less host look like cortex acceptance. Output: " +
+			JSON.stringify(missingPrereq.output.slice(-300)),
+	);
+}
+
+// ===========================================================================
+// 7) NO SILENT AGGREGATE OMISSION. The protocol tells the truth about the steps
+//    the gate RUNS; it says nothing about steps the gate never lists. Three LIVE
+//    smokes (cortex, spawn-live, claude-native-resume) sat outside the aggregate
+//    with no stated reason until 2026-07-31, so a green cut was silent about the
+//    second backend, the spawn substrate, and native resume.
+//
+//    So: every LIVE smoke is either WIRED into release_gate or EXCLUDED for a
+//    reason an operator can read in the docs. The exclusion half is checked
+//    against the doc text, not against a list in this file — an exclusion that
+//    only this gate believes in is how the omission would come back.
+// ===========================================================================
+{
+	const runSh = readFileSync(join(REPO_DIR, "run.sh"), "utf8");
+	const gateBody = runSh.slice(runSh.indexOf("release_gate() {"), runSh.indexOf("# 5. Summary"));
+	assert.ok(gateBody.length > 1000, "located the release_gate body");
+
+	// name → the sentence in the docs that carries its exclusion, and where.
+	const DOCUMENTED_EXCLUSIONS: Record<string, [file: string, sentence: string]> = {
+		"smoke-acp-long-turn-live": ["VERIFY.md", "on-demand, not part of `release-gate`"],
+		"smoke-agy-native-push-live": ["VERIFY.md", "Aggregate release-gate does not own an agy conversation id"],
+		"smoke-acp-ordering-probe-live": ["docs/acp-backend-rail.md", "opt-in paired observation"],
+		// Cortex needs an external Snowflake connection the HOST owns, so an aggregate
+		// that required it would block every cut taken without that account. Excluded —
+		// NOT waived: its direct call stays required for a Cortex-rail cut, and running
+		// it without the connection still reports protocol SKIP rather than a pass.
+		"smoke-acp-cortex-live": ["VERIFY.md", "The 0.13.1 aggregate does not re-certify Cortex"],
+	};
+
+	const allLive = globSync("scripts/smoke-*live*.{ts,sh}", { cwd: REPO_DIR })
+		.map((p) => basename(p).replace(/\.(ts|sh)$/, ""))
+		.sort();
+	assert.ok(allLive.length >= 18, `expected the full LIVE smoke family, found ${allLive.length}`);
+
+	for (const name of allLive) {
+		const wired = gateBody.includes(`"$self" ${name}\n`) || gateBody.includes(`"$self" ${name} `);
+		const excused = DOCUMENTED_EXCLUSIONS[name];
+		if (wired) {
+			assert.ok(!excused, `${name} is both wired and excused — pick one`);
+			continue;
+		}
+		assert.ok(
+			excused,
+			`[QK:NO-SILENT-AGGREGATE-OMISSION] ${name} is neither wired into release_gate nor excluded in the docs. ` +
+				"A LIVE smoke that exists but is never listed makes a green cut silent about the axis it covers — exactly " +
+				"how cortex (the second shipped backend), spawn-live and claude-native-resume went unrun for releases. " +
+				"Wire it, or state the exclusion where an operator reads it.",
+		);
+		const [file, sentence] = excused as [string, string];
+		assert.ok(
+			readFileSync(join(REPO_DIR, file), "utf8").includes(sentence),
+			`${name} claims a documented exclusion, but ${file} no longer says "${sentence}" — an exclusion only this ` +
+				"gate believes in is not documented",
+		);
+	}
+}
+
+console.log(
+	"[check-release-gate-outcomes] ok — STEP OUTCOME protocol: one skip exit code shared by the shell and TS halves " +
+		`(${LIVE_SKIP_EXIT}, clear of the per-tool 0..4 and shell 126+ bands), classifier maps 0→PASS / skip→SKIP / ` +
+		"everything else→FAIL (never rounding a skip up), `--cut` refuses a MUST SKIP while a bare diagnostic run stays " +
+		"exit 0, no LIVE smoke still carries the pre-P1 exit-0 skip shape, and both real skip surfaces were INVOKED and " +
+		"observed to propagate the code: a smoke with LIVE unset (through run_ts, with its operator-readable marker) and " +
+		"a run.sh wrapper declining its own prerequisite (including the measured LIVE=1 no-cortex-connection cell); and every " +
+		"LIVE smoke is either wired into release_gate or excluded by a sentence the docs still carry",
+);

package/scripts/lib/live-skip.ts

@@ -0,0 +1,33 @@
+// The TypeScript half of the release-gate STEP OUTCOME protocol
+// (scripts/lib/step-outcome.sh owns the contract prose and the shell half).
+//
+// A LIVE smoke that lacks a prerequisite must be DISTINGUISHABLE from one that
+// ran and passed. Before P1 every smoke exited 0 on a skip, so `run_live_step`
+// counted it PASS and the release summary could not prove a required call had
+// happened at all. `skipLive` is the single exit any smoke takes when it
+// declines: one reserved code the aggregate classifies as SKIP, plus one marker
+// line so an operator reading the log sees WHICH prerequisite was missing
+// without decoding a number.
+//
+// The two halves must agree. `check-release-gate-outcomes` reads this constant
+// and the shell one and refuses a mismatch — a protocol that drifted between
+// languages would silently reclassify every skip as a failure (or worse).
+
+/** SKIP. Must equal `ENTWURF_STEP_SKIP_EXIT` in scripts/lib/step-outcome.sh. */
+export const LIVE_SKIP_EXIT = 97;
+
+/** The machine-greppable prefix every skip line carries. */
+export const LIVE_SKIP_MARKER = "[entwurf:skip]";
+
+/**
+ * Decline this smoke: print the marker + reason on stderr and exit with the
+ * protocol's SKIP code. Never returns.
+ *
+ * `label` is the smoke's own name (so a multi-step aggregate log stays
+ * attributable); `reason` states the missing prerequisite AND how to supply it —
+ * an operator who hits a SKIP in a cut run needs the fix, not the diagnosis.
+ */
+export function skipLive(label: string, reason: string): never {
+	console.error(`${LIVE_SKIP_MARKER} ${label} — ${reason}`);
+	process.exit(LIVE_SKIP_EXIT);
+}

package/scripts/lib/probe-acp-turn.ts

@@ -29,20 +29,29 @@ export interface ProbePhaseTimeouts {
 	initializeMs: number;
 	newSessionMs: number;
 	setModelMs: number;
-	promptMs: number;
 }
 
-// Phase timeouts — MUST equal backend.ts's INITIALIZE/NEW_SESSION/SET_MODEL/
-// PROMPT_TIMEOUT_MS (check-probe-ordering pins them against the source). §11-7:
-// a D verdict is only readable against these boundaries, so the probe may not
-// invent its own.
+// BOOTSTRAP phase timeouts — MUST equal backend.ts's INITIALIZE/NEW_SESSION/
+// SET_MODEL_TIMEOUT_MS (check-probe-ordering pins them against the source).
+// §11-7: a bootstrap-phase D verdict is only readable against production's own
+// boundaries, so the probe may not invent its own.
 export const PROBE_PHASE_TIMEOUTS: ProbePhaseTimeouts = {
 	initializeMs: 30_000,
 	newSessionMs: 30_000,
 	setModelMs: 30_000,
-	promptMs: 600_000,
 };
 
+// The prompt phase has NO production counterpart to match: backend.ts ends a
+// prompt on lifecycle events only (resolve / abort / child gone) and carries no
+// wall-clock cutoff, by policy — an active turn is not a failed turn for being
+// long. This value is therefore the MEASUREMENT HARNESS's own bounded
+// observation horizon: it stops a probe RUN from hanging forever. It is not a
+// production contract, not an equivalence, and not a deadline any §11-7 verdict
+// is read against. Horizon expiry means the run's prompt window is
+// INCONCLUSIVE — the artifact is preserved and read as "not measured", never as
+// a model of production killing a turn.
+export const PROBE_PROMPT_OBSERVATION_MS = 600_000;
+
 /** The two adapter methods the turn drives — satisfied by the REAL claudeAdapter
  *  (emitted) in the LIVE runner and by recording stubs in the gate. */
 export interface ProbeAdapterSeam {
@@ -108,7 +117,10 @@ export interface ProbeTurnParams {
 	adapter: ProbeAdapterSeam;
 	enrichMcpServers: ProbeMcpEnricher;
 	log: (event: ProbeEventName, payload?: Record<string, unknown>) => void;
+	/** Bootstrap boundaries (production-pinned). Defaults to PROBE_PHASE_TIMEOUTS. */
 	timeouts?: ProbePhaseTimeouts;
+	/** Harness observation horizon for the prompt phase — NOT a production deadline. */
+	promptObservationMs?: number;
 }
 
 export interface ProbeTurnResult {
@@ -158,7 +170,7 @@ export async function driveProbeTurn(connection: AcpConnectionLike, params: Prob
 		}),
 	);
 
-	// _meta + wire servers exactly as backend.ts assembles them (S2g/§9-4): the
+	// _meta + wire servers exactly as backend.ts assembles them (S2g / carrier-less shape): the
 	// injected production buildSessionMeta (omitted key when undefined) + the
 	// injected production envelope enrichment over the resolved config.
 	const sessionMeta = params.adapter.buildSessionMeta(
@@ -196,11 +208,20 @@ export async function driveProbeTurn(connection: AcpConnectionLike, params: Prob
 		}),
 	);
 
-	const promptResult = await runPhase("prompt", PROBE_EVENTS.promptStart, PROBE_EVENTS.promptEnd, log, t.promptMs, () =>
-		connection.prompt({
-			sessionId: acpSessionId,
-			prompt: [{ type: "text", text: params.promptText }],
-		}),
+	// The horizon below bounds THIS MEASUREMENT RUN, not the turn: production has
+	// no prompt deadline, so an expiry here is an inconclusive observation.
+	const promptObservationMs = params.promptObservationMs ?? PROBE_PROMPT_OBSERVATION_MS;
+	const promptResult = await runPhase(
+		"prompt",
+		PROBE_EVENTS.promptStart,
+		PROBE_EVENTS.promptEnd,
+		log,
+		promptObservationMs,
+		() =>
+			connection.prompt({
+				sessionId: acpSessionId,
+				prompt: [{ type: "text", text: params.promptText }],
+			}),
 	);
 
 	return { acpSessionId, stopReason: promptResult?.stopReason };

package/scripts/lib/step-outcome.sh

@@ -0,0 +1,88 @@
+# shellcheck shell=bash
+# Release-gate STEP OUTCOME protocol — the one place PASS / SKIP / FAIL is decided.
+#
+# SOURCE-ONLY. It carries the executable bit because check-pack requires every
+# shipped `.sh` to have one (a blanket packaging invariant worth more than an
+# exception carved for this file), not because anyone should run it.
+#
+# Sourced by run.sh's `release_gate`; sourced directly by
+# scripts/check-release-gate-outcomes.ts so the truth table is exercised as a
+# unit instead of being re-derived by eye from the aggregate's output.
+#
+# WHY A PROTOCOL AND NOT A PER-BACKEND BRANCH (P1, 2026-07-31). The aggregate's
+# prose said a cut needs `LIVE=1` and `SKIP=0`, but its exit authority read only
+# the FAIL counter, so `./run.sh release-gate` returned 0 with 14 SKIPs and the
+# summary still printed "all green". Worse, a step that WAS invoked could decide
+# it lacked a prerequisite and exit 0 — Cortex with no
+# `ENTWURF_ACP_CORTEX_CONNECTION` is the measured case — and the aggregate
+# counted that as PASS. Both holes have the same shape: a skip that cannot be
+# told from an acceptance. So the fix is one outcome protocol every step speaks,
+# never a special case per backend or per prerequisite.
+#
+# EXIT CONTRACT (house style: the verdict IS the exit code)
+#   0                          PASS — the step ran and its assertions held.
+#   ENTWURF_STEP_SKIP_EXIT     SKIP — the step declined a prerequisite it does
+#                              not have. NOT acceptance, and never rounded up.
+#   anything else              FAIL — including a crash or a signal death.
+#
+# WHY 97. The repo already spends 0..4 on per-tool exit contracts that mean
+# different things per tool (meta-bridge-fresh-cut's 3 = "cut transition
+# incomplete", meta-bridge-store-doctor's 3 = "unreadable store", dev-bin's 3 =
+# "refused a foreign link"), and 126+ belongs to the shell. A LIVE smoke shells
+# out to some of those tools, so reusing a low number would let a dependency's
+# unrelated verdict surface as a false SKIP — the exact confusion this protocol
+# exists to remove. 97 is reserved for THIS cross-tool protocol and nothing else.
+ENTWURF_STEP_SKIP_EXIT=97
+
+# Classify one step's exit code. Prints PASS | SKIP | FAIL on stdout.
+entwurf_step_outcome() {
+	case "${1:-}" in
+		0) printf 'PASS\n' ;;
+		"$ENTWURF_STEP_SKIP_EXIT") printf 'SKIP\n' ;;
+		*) printf 'FAIL\n' ;;
+	esac
+}
+
+# The release authority. Returns 0 when the run may be read as a cut floor.
+#
+#   $1 MUST fail count   $2 MUST skip count   $3 cut mode (1 = a real cut)
+#
+# A FAIL always blocks. A SKIP blocks ONLY in cut mode: an ordinary diagnostic
+# `./run.sh release-gate <dir>` must stay runnable unattended and still exit 0
+# while honestly reporting what it did not call. `--cut` is the executable half
+# of "a CUT needs LIVE=1, SKIP=0" — and it needs no separate LIVE assertion,
+# because with LIVE unset every LIVE-gated step skips and the skip count blocks.
+entwurf_release_releasable() {
+	local failc="${1:-0}" skipc="${2:-0}" cut="${3:-0}"
+	[ "$failc" -gt 0 ] && return 1
+	if [ "$cut" = "1" ] && [ "$skipc" -gt 0 ]; then
+		return 1
+	fi
+	return 0
+}
+
+# The same decision as ONE greppable token, because "why is this red" must be
+# machine-readable and not parsed out of prose.
+#
+#   $1 MUST fail count   $2 MUST skip count   $3 cut mode (1 = a real cut)
+#
+# A step that RAN AND BROKE and a step that NEVER RAN are different facts, and a
+# release record that blurs them is worthless: the first is a defect to fix, the
+# second is a prerequisite to supply. So the counters are never fudged either —
+# a policy block keeps `FAIL=0 SKIP=n` and says `BLOCKED (MUST SKIP)`. Reporting
+# a synthetic `FAIL=1` for the policy block would destroy exactly the
+# distinction this protocol exists to create.
+entwurf_release_verdict() {
+	local failc="${1:-0}" skipc="${2:-0}" cut="${3:-0}"
+	if [ "$failc" -gt 0 ]; then
+		printf 'cut: BLOCKED (MUST FAIL)\n'
+	elif [ "$cut" = "1" ] && [ "$skipc" -gt 0 ]; then
+		printf 'cut: BLOCKED (MUST SKIP)\n'
+	elif [ "$cut" = "1" ]; then
+		printf 'cut: OK\n'
+	elif [ "$skipc" -gt 0 ]; then
+		printf 'cut: n/a (diagnostic, %s SKIP)\n' "$skipc"
+	else
+		printf 'cut: n/a (diagnostic)\n'
+	fi
+}

package/scripts/mutants/acp-augment.json

@@ -25,6 +25,112 @@
 			"timeoutSeconds": 60,
 			"signature": "[QK:AUGMENT-TRUNC-MARKER]",
 			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-PROVENANCE-STATED",
+			"title": "the augment stops saying what it is — the model is back to reading a first-user prepend as its system prompt (the measured 2026-07-30 misattribution)",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\t\"This block is prepended to the FIRST USER MESSAGE of this session. It is not your system prompt.\";"
+			],
+			"replace": ["\t\"\";"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-PROVENANCE-STATED]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-FRAME-NAMES-CLAUDE-CARRIER",
+			"title": "the claude frame stops naming its real engraving-only carrier — the model is told what its system prompt is NOT, but never what it IS",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\t\t\t\t\t`The ${params.backend} rail does have a system-prompt carrier (\\`_meta.systemPrompt\\`), and entwurf keeps it deliberately tiny: it carries the operator engraving only — never this narrative, never AGENTS.md.`,"
+			],
+			"replace": ["\t\t\t\t\t`The ${params.backend} rail carries no system-prompt carrier at all.`,"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-FRAME-NAMES-CLAUDE-CARRIER]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-FRAME-DENIES-CORTEX-CARRIER",
+			"title": "the carrier-less rail is told it has a tiny system-prompt carrier — a flat lie, since cortex's buildSessionMeta sends no _meta at all",
+			"subject": "pi-extensions/lib/acp/augment.ts",
+			"find": [
+				"\t\t\t\t\t`The ${params.backend} rail carries no system-prompt carrier at all — entwurf sends no \\`_meta.systemPrompt\\`, so everything entwurf tells you, including any operator engraving above, arrives here as user-message text.`,"
+			],
+			"replace": [
+				"\t\t\t\t\t`The ${params.backend} rail does have a system-prompt carrier (\\`_meta.systemPrompt\\`), and entwurf keeps it deliberately tiny: it carries the operator engraving only.`,"
+			],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-FRAME-DENIES-CORTEX-CARRIER]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-RAIL-DIFF-IS-SOURCE-PINNED",
+			"title": "cortex grows a session carrier while the augment still tells it there is none — the frame becomes a lie and no prose check would notice",
+			"subject": "pi-extensions/lib/acp/backend-adapter.ts",
+			"find": ["\tbuildSessionMeta() {\n\t\treturn undefined;\n\t},"],
+			"replace": ["\tbuildSessionMeta() {\n\t\treturn { systemPrompt: \"x\" };\n\t},"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-RAIL-DIFF-IS-SOURCE-PINNED]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-LEADS-ITS-OWN-BLOCK",
+			"title": "the carrier loses its leading boundary — the Claude SDK's fixed sentence swallows the operator engraving again (the measured 2026-07-31 A-join)",
+			"subject": "pi-extensions/lib/acp/engraving.ts",
+			"find": ["export const CARRIER_LEAD_SEPARATOR = \"\\n\\n\";"],
+			"replace": ["export const CARRIER_LEAD_SEPARATOR = \"\";"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-LEADS-ITS-OWN-BLOCK]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-OPT-OUT-SURVIVES-SEPARATOR",
+			"title": "the boundary is attached before the emptiness test — an emptied engraving file stops being the opt-out and becomes a whitespace carrier that still replaces the claude_code preset",
+			"subject": "pi-extensions/lib/acp/engraving.ts",
+			"find": [
+				"\tconst body = interpolate(source, params).trim();",
+				"\tif (body.length === 0) return \"\";",
+				"\treturn `${CARRIER_LEAD_SEPARATOR}${body}`;"
+			],
+			"replace": [
+				"\tconst body = `${CARRIER_LEAD_SEPARATOR}${interpolate(source, params).trim()}`;",
+				"\tif (body.length === 0) return \"\";",
+				"\treturn body;"
+			],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-OPT-OUT-SURVIVES-SEPARATOR]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-STAYS-TINY",
+			"title": "the shipped carrier grows into a real prompt — size, not shape, is what routes an OAuth subscription call to metered extra usage",
+			"subject": "pi-extensions/lib/acp/prompts/engraving.md",
+			"find": ["# Engraving Here"],
+			"replace": [
+				"# Engraving Here\n\n## Operator standing orders\n\n- Address the operator by name and keep the reply language matched to the prompt.\n- Prefer surgical edits over rewrites; verify every claim you make about behavior.\n- Never bypass a commit hook, and never push without an explicit request.\n- Indentation is tabs unless the project's linter says otherwise.\n- When docs and behavior disagree, report it and fix the source of truth.\n- Long-running commands belong in tmux, not in a foreground shell.\n- Record the next concrete move before you stop working.\n\n## Project context\n\nThis checkout is the bridge itself, so treat the adapter contract in the rail doc\nas authoritative and re-read it before touching a gate. The qualification lane is\nthe oracle for every contract claim; a green assertion count proves nothing on\nits own."
+			],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-STAYS-TINY]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
+		},
+		{
+			"claim": "CARRIER-META-SENDS-CARRIER-VERBATIM",
+			"title": "the meta hop normalizes the carrier — the boundary is stripped back off on the wire while bridgeConfigSignature still folds the bounded value, so the A-join returns and reuse keys on a string the backend never received",
+			"subject": "pi-extensions/lib/acp/tool-surface.ts",
+			"find": ["\t\tmeta.systemPrompt = normalizedSystemPrompt;"],
+			"replace": ["\t\tmeta.systemPrompt = normalizedSystemPrompt.trim();"],
+			"gate": ["bash", "run.sh", "check-acp-carrier-augment"],
+			"timeoutSeconds": 60,
+			"signature": "[QK:CARRIER-META-SENDS-CARRIER-VERBATIM]",
+			"signatureSource": "scripts/check-acp-carrier-augment.ts"
 		}
 	]
 }