muse-crew 0.13.1 → 0.13.3

package/workflows/chore.js

@@ -26,25 +26,10 @@ const startStepIndex = inputs.start_step_index || 0;
 // resolution back via updatetask in the self-claim below.
 const RESOLVED_WORKFLOW = inputs.resolved_workflow || null;
 const WORKFLOW_WAS_NULL = inputs.workflow_was_null === true;
-// One-shot recovery routing: the dispatcher sets inputs.next_phase when it
-// routes this run via an explicit recover-task redirect. The value is
-// consumed (cleared) atomically by the successful self-claim below:
-// claim-task takes expected_next_phase and clears the matching next_phase in
-// the same transaction as the winning session insert, so no platform death
-// can slip between claim and consumption and replay the routing. A stale or
-// superseded routing survives — only an exact match clears.
-// what the dispatcher routed on.
+// See docs/decisions/workflow-core.md#oneshot-recovery: the dispatcher sets input for one-shot recovery routing.
 const NEXT_PHASE_ROUTED = (typeof inputs.next_phase === "string" && inputs.next_phase.length > 0) ? inputs.next_phase : null;
 
-// Visual verdict protocol availability — the workflow parks for parent-run
-// baseline capture ONLY when the protocol is fully shipped. The protocol
-// requires docs/visual-verdict.md in the release AND the parent-side
-// capture tooling (task b309a97d, "QA owns the visual verdict"). Until both
-// exist, the park would deadlock waiting for a parent who cannot fulfill
-// it.
-// Effective value for this run, resolved by the dispatcher from the
-// project's visual_protocol setting (null=inherits crew default=off).
-// Manual launches without the arg default to off (previous behavior).
+// See docs/decisions/qa-reproduce.md#visual-protocol-avail: the workflow parks if the visual protocol is unavailable.
 var VISUAL_PROTOCOL_AVAILABLE = inputs.visual_protocol === true;
 
 // crewHome is required — the dispatcher always passes it (crew-dispatch.js
@@ -142,15 +127,7 @@ const COMPUTE_DIFF_SRC = crewHome + "/current/lib/compute-publish-diff.js";
 const COMPUTE_DIFF = RUN_LIB + "/compute-publish-diff.js";
 const CLASSIFY_SURFACE_SRC = crewHome + "/current/lib/classify-surface.js";
 const CLASSIFY_SURFACE = RUN_LIB + "/classify-surface.js";
-// The seven basenames the pin step must materialize — asserted mechanically
-// by workflow code from the verbatim listing, never from agent prose.
-// COMPUTE_DIFF is the deterministic publish-diff computer (room #14,
-// 2026-09-17): the diff is computed by this script, never ferried as an
-// agent JSON string. Pinned like the other publish-critical modules so a
-// mid-run release swap cannot change it under the workflow.
-// CLASSIFY_SURFACE is the surface classifier (room #15, 2026-09-18):
-// crew-api.js statically imports it, so the pin must carry it — a pin
-// without it kills every claim with ERR_MODULE_NOT_FOUND.
+// See docs/decisions/qa-reproduce.md#pin-basenames: the pin step materializes the required scripts.
 const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
@@ -200,12 +177,7 @@ const SURFACE_TRIAGE_DESC = SURFACE_ARTIFACT
   : SURFACE_TERMINAL
     ? "This project's user-facing surface is terminal: a command-line interface."
     : "This project's user-facing surface is unclassified (environment_type not set): judge by what a user would directly observe.";
-// UX doctrine page: the shared UX bar for this run's surface, resolved
-// mechanically — every phase prompt reads UX_DOCTRINE_PATH, never a
-// hardcoded filename. Canonical map: lib/ux-doctrine.js (mirrored here as a
-// one-liner because the workflow runtime's relative-import support is
-// unverified; tests pin the mirror). Null on unclassified surfaces: no
-// shared page, and prompts say so instead of naming the wrong one.
+// See docs/decisions/qa-reproduce.md#ux-doctrine-page: the shared UX bar for this run's surface.
 const UX_DOCTRINE_PAGE = SURFACE_TERMINAL ? "terminal-ux.md" : (SURFACE_ARTIFACT ? "artifact-ux.md" : null);
 const UX_DOCTRINE_PATH = UX_DOCTRINE_PAGE ? crewHome + "/current/docs/" + UX_DOCTRINE_PAGE : null;
 const PUBLISH_SLUG = projectConfig.deploy_slug || "";
@@ -216,21 +188,7 @@ if (!taskId) {
   throw new Error("task_id is required in args");
 }
 
-// Closeout is deterministic: the work agent returns the runtime's native
-// transport envelope {"status": "ok", "result": "<prose report>"} with no
-// schema, so the workflow receives the report as a plain string. There is no
-// {"report"} wrapper: that invented shape invited agents to improvise sibling
-// keys (notably "status"), which the runtime duck-types as its own envelope
-// and fatally misparses. The envelope is the runtime's own documented shape
-// — not a demand for machine-structured reasoning.
-// The verdict is extracted mechanically by extractVerdict below — never by an
-// agent. The summary is the worker's report truncated. The release decision
-// comes from extractReleaseDecision. No formatter agent: it added a failure
-// mode while contributing nothing the workflow doesn't compute itself.
-// Steps whose passed=false drives a control-flow branch (rework bounce,
-// block) declare their verdict explicitly on a VERDICT: line. The verdict is
-// extracted DETERMINISTICALLY by workflow code (extractVerdict) — never by
-// an agent. Missing, malformed, or contradictory lines fail the phase (never silently pass).
+// See docs/decisions/workflow-core.md#closeout-envelope: the work agent returns the runtime's native envelope; verdict extracted mechanically.
 const VERDICT_STEPS = ["Build", "Review", "Integrate", "Publish"];
 function extractVerdict(workerText) {
   // The verdict is the LAST VERDICT: PASS/FAIL in the report (contract: end
@@ -254,16 +212,7 @@ function extractVerdict(workerText) {
   if (uniq.length !== 1) return { ok: false, count: matches.length };
   return { ok: true, passed: last.value === "PASS" };
 }
-// Verdict re-ask (bug cd18ccc2): a verdict-step report that fails
-// extractVerdict is not failed immediately. Stochastic verdict-line
-// non-compliance (the agent did the work but omitted or garbled the VERDICT
-// line) gets up to two bounded follow-up agent() calls whose only job is to
-// read the preserved report and emit exactly one VERDICT line. The verdict
-// is still extracted mechanically by extractVerdict — the re-ask agent
-// transcribes, never decides the phase outcome. Each attempt uses a fresh
-// stable-key suffix so a cached failure can never replay deterministically.
-// Exhaustion keeps the existing fail-closed behavior. This is structure, not
-// prompt hardening: no instruction text was stern-ified to get here.
+// See docs/decisions/workflow-core.md#verdict-reask: a report that fails extractVerdict gets bounded re-ask calls.
 function verdictReaskKey(stepName, reworkSuffix, attempt) {
   return "verdict-reask-" + stepName + reworkSuffix + "-a" + attempt;
 }
@@ -321,12 +270,7 @@ function workRetryKey(stepName, reworkSuffix, attempt) {
 function attemptKey(base, reworkCount) {
   return base + (reworkCount > 0 ? "-r" + reworkCount : "");
 }
-// pinLifecycle(key) — snapshot the lifecycle scripts into RUN_LIB and return
-// the verbatim `ls -1` listing so WORKFLOW CODE asserts the six pinned
-// basenames; the agent cannot self-certify. (The pin step was the one place
-// the workflows trusted agent prose: task 24be1cd6 walked to Publish on an
-// empty pin dir.) Byte-identical across standard/bugfix/chore — pinned by
-// tests/pin-location.test.js.
+// See docs/decisions/qa-reproduce.md#pin-lifecycle: snapshot the lifecycle scripts in the pin.
 function pinLifecycle(key) {
   return agent(
     "Snapshot lifecycle scripts for version pinning.\n" +
@@ -530,24 +474,7 @@ function hydrateReleaseDecision(rec) {
 // read-back cannot be
 // fabricated from the diff; it must match the artifact's real content.
 
-// Durable publish-attempt ledger (2026-09-12): every artifact publish
-// attempt is recorded append-only at $CREW_HOME/.publish-ledger/<slug>.jsonl
-// on persistent disk (NOT /tmp). The ledger is the correlation record for
-// publish attempts whose outcome is UNKNOWN. When the rebuild trigger's
-// child returns prose instead of JSON (structured-output failure), the edit
-// may already have been accepted as pending_init — and artifact_status
-// cannot see pending_init (diagnostic canary 2026-09-12: an edit accepted
-// as pending_init was immediately followed by an all-false status check,
-// and the old retry issued a DUPLICATE edit). "No build visible" is NOT
-// evidence the edit did not go through, so the workflow never blind-retries
-// on an unknown outcome: it records the attempt and parks fail-closed. A
-// human or a later run correlates the accepted edit via the ledger (commit
-// hash + attempt key + the artifact build's agent_id when one was observed)
-// instead of guessing from a blind status poll.
-// Best-effort observability: a failed write is logged loudly but never
-// throws — the caller's park/proceed decision never depends on the ledger.
-// Byte-identical across standard/bugfix/chore — pinned by
-// tests/publish-ledger.test.js.
+// See docs/decisions/publish-path.md#publish-attempt-ledger: every trigger outcome is recorded in the durable ledger.
 async function recordPublishLedger(entry, rework) {
   try {
     var ledgerDir = crewHome + "/.publish-ledger";
@@ -597,45 +524,19 @@ function extractMarkerLines(workerText) {
   return markers.join("\n");
 }
 
-// Already-merged idempotency (canary 2026-09-15, task 1d692d91): when the
-// builder correctly makes no commit because the deliverable is already on
-// main (a prior merge or hand-repair landed it), it declares
-// `repo_diff: none (already-merged: <sha>)` naming the main commit that
-// carries the work. Room #16 blocker 11 (2026-09-18): the line anchor
-// missed Wren's mid-paragraph declaration, and the persisted notes truncated
-// the tail — so the anchor is gone and a sha followed by `)`, whitespace, or
-// end-of-string (truncation) is accepted. The sha is hex-only (7-40 chars)
-// so the workflow can interpolate it into the mechanical ancestor check
-// without injection risk; a over-long hex run never matches (the lookahead
-// fails on the extra hex char). Pure — pinned byte-identical across
-// standard/bugfix/chore.
+// See docs/decisions/publish-path.md#already-merged-idem2: idempotency for already-merged tasks.
 function extractAlreadyMerged(workerText) {
   var m = /repo_diff:\s*none\s*\(already-merged:\s*([0-9a-f]{7,40})(?=[\s)]|$)/i.exec(workerText || "");
   return m ? { sha: m[1].toLowerCase() } : { sha: null };
 }
 
-// Explicit artifact refusal (room #16 blocker 10, 2026-09-18): the rebuild
-// trigger child ends its turn with `ARTIFACT_EDIT_REFUSED: <text>` when
-// artifact_edit explicitly refuses the edit (e.g. the artifact does not
-// exist). A refusal is conclusive negative evidence — the edit provably did
-// NOT go through — distinct from an unconsumed trigger return (unknown).
-// Pure — pinned byte-identical across standard/bugfix/chore.
-// The signal must be the ENTIRE trimmed turn output (not a line within prose):
-// the trigger child is instructed to end its turn with exactly this line and
-// nothing else. A confused child quoting the instructions back in prose must
-// NOT produce a conclusive negative — that degrades to unknown (fail-closed).
+// See docs/decisions/publish-path.md#refusal-signal: the refusal signal must be the ENTIRE trimmed turn output.
 function extractRefusal(workerText) {
   var m = /^ARTIFACT_EDIT_REFUSED:\s*(.+?)\s*$/.exec(String(workerText || "").trim());
   return m ? m[1].slice(0, 300) : null;
 }
 
-// Worktree confinement: the Build agent must declare the exact worktree
-// path it built in on a `worktree:` marker line. The workflow compares it
-// against WORKTREE_HINT mechanically (exact string match) — never by
-// reading agent prose. This closes the hole where a builder whose prepare
-// failed freelanced into a different checkout (canary, 2026-09-11): the
-// honest-but-confused case fails here, and a fabricated path is caught one
-// phase later when Review's inspect finds no commits in the configured repo.
+// See docs/decisions/qa-reproduce.md#worktree-confinement: the Build agent must declare its worktree.
 function extractWorktree(workerText) {
   var lines = (workerText || "").split("\n");
   var found = null;
@@ -665,26 +566,7 @@ function extractExperiential(workerText) {
   if (!r) return null;
   return r[1].toLowerCase() === "yes";
 }
-function buildVisualCapturePlan(taskTitle, taskDescription, kind, captureTargets) {
-  // Deterministic visual-capture frame. kind: "baseline" | "postchange".
-  // This string IS the capture script: fixed viewport matrix, scroll
-  // positions, and interaction states — the inspection agent executes it
-  // verbatim, nothing is improvised. Task-specific targets fill the slots.
-  var title = String(taskTitle || "").replace(/"/g, "'").slice(0, 120);
-  var targets = String(captureTargets || "").trim() ||
-    String(taskDescription || "").replace(/"/g, "'").slice(0, 300);
-  return "VISUAL CAPTURE — " + kind.toUpperCase() + " — task: " + title + ". " +
-    "Target views/controls: " + targets + ". " +
-    "For EACH target, capture exactly: " +
-    "(1) desktop 1440x900, full view, scrolled to top; " +
-    "(2) desktop 1440x900, scrolled so the target is vertically centered; " +
-    "(3) mobile 390x844, scrolled so the target is vertically centered; " +
-    "(4) desktop 1440x900, hover state on the target control; " +
-    "(5) desktop 1440x900, keyboard-focus state on the target control; " +
-    "(6) desktop 1440x900, active/pressed state if the target is a button or control. " +
-    "Also record: console error count, the ARIA tree of the target region, any horizontal overflow. " +
-    "Name captures " + kind + "-<n>-<viewport>-<state>. Return the captures, not a summary.";
-}
+
 // Experiential flag resolution: the task is experiential when Sage's Triage
 // report ends with the machine-read marker "experiential: yes". The flag is
 // opt-in — a missing or garbled line degrades to "unknown", which callers
@@ -825,23 +707,9 @@ function releaseDecisionText() {
   if (!releaseDecision) return "no machine-readable release decision from the Build report";
   return "release: " + releaseDecision.release + (releaseDecision.version_bump ? ", version_bump: " + releaseDecision.version_bump : " (no version_bump line)");
 }
-// Park the task for human attention and end the run. "blocked" is never
-// manually authored — the dashboard derives it mechanically from unmet
-// dependencies — so a workflow outcome that needs a human parks the task
-// instead. Parking is one atomic dashboard action (parktask): the parked
-// state and the explanatory note land in one transaction, never half.
-// The dispatcher skips parked tasks; a human moving parked→todo
-// mechanically resets the retry counters. Returns the workflow result
-// envelope the launcher sees. If the park call itself fails, the run
-// reports "failed" (retryable) so the next tick re-attempts the park —
-// a lost park is never reported as parked.
-// Terminal cleanup: the run's last act at every park/fail boundary. A run
-// that parks or fails must not leak its worktree, branch, or merge lock.
-// The lifecycle's terminal-cleanup releases the lock unconditionally and
-// reclaims the worktree+branch ONLY when the task branch is fully merged
-// into main (then it is redundant); unmerged work is preserved for the
-// human by design. Fire-and-forget with one bounded retry — the merge-lock
-// lease expiry and the orphan sweep are the backstop for a dead transport.
+// Terminal cleanup: the run's last act — release the lock unconditionally;
+// reclaim worktree+branch only when fully merged (unmerged work is preserved
+// for the human by design). See `docs/decisions/workflow-core.md#park-contract`.
 async function terminalCleanup() {
   for (var attempt = 1; attempt <= 2; attempt++) {
     try {
@@ -1104,14 +972,7 @@ while (i < STEPS.length) {
     lockHolder = taskId + "/" + activeSessionId;
   }
 
-  // ── Capture: baseline evidence for experiential tasks ─────────────
-  // Hazel's QA capture pass runs right after Triage, before Map, for tasks
-  // Sage flagged experiential. The capture itself is parent-driven (the
-  // inspection handoff arrives at the root agent, outside this script), so
-  // when no baseline evidence is recorded yet the script logs a note event
-  // and parks with the exact parent protocol + resume path. Never fails the
-  // task over missing evidence: after two requests, baseline:none is
-  // recorded and the task continues without baseline comparison.
+  // See docs/decisions/qa-reproduce.md#capture-baseline: baseline evidence for experiential tasks is captured before work begins.
   if (step.name === "Capture") {
     var capExp = await resolveExperiential();
     var bounceSuffix = (mapGateBounceCount > 0 ? "-g" + mapGateBounceCount : "");
@@ -1133,12 +994,7 @@ while (i < STEPS.length) {
       continue;
     }
     var capStatus = await baselineStatus();
-    // Stale-decision guard: a "baseline: none (visual protocol unavailable)"
-    // note is only durable while the protocol is unavailable. When
-    // VISUAL_PROTOCOL_AVAILABLE is true, that old decision no longer
-    // stands — fall through to the request path for a fresh capture
-    // attempt. Exact-string trim comparison against the workflow's own
-    // written message (explicit state, never English matching).
+    // See docs/decisions/qa-reproduce.md#stale-decision-guard: a stale baseline decision parks fail-closed.
     var baselineLatestMessage = ("baseline: " + capStatus.baseline_kind + capStatus.baseline_refs).trim();
     var baselineStale = VISUAL_PROTOCOL_AVAILABLE && baselineLatestMessage === "baseline: none (visual protocol unavailable)";
     if (capStatus.baseline_found && !baselineStale) {
@@ -1283,17 +1139,7 @@ while (i < STEPS.length) {
       (PUBLISH_TYPE === "npm" ? " End your report with the release: and version_bump: lines exactly as specified above — keep them on their own lines, lowercase, unrephrased — then a line `worktree: ` followed by the exact working directory path from above (copy it verbatim \u2014 it must match character-for-character), then a final line with exactly: VERDICT: PASS if the build is complete, VERDICT: FAIL if it is not." : " End your report with a line `worktree: ` followed by the exact working directory path from above (copy it verbatim \u2014 it must match character-for-character), then exactly one line: VERDICT: PASS if the build is complete, VERDICT: FAIL if it is not.");
 
   } else if (step.name === "Review") {
-    // Already-merged hydration: when this run did not execute Build itself
-    // (dispatcher resume at Review after a platform death between phases),
-    // recover the workflow-verified sha. Room #16 blocker 11: the structured
-    // session field is read FIRST — the `already_merged_verified:` notes line
-    // is only a fallback, because session notes are hard-capped at 3000
-    // chars and a truthful declaration at the report's tail was silently
-    // truncated. The structured value was written by the workflow after a
-    // mechanical ancestor check — it is trusted; the builder's bare
-    // declaration never is. Absent both, the mechanical fact below reads
-    // "none declared" and Cass fails closed. The hydration read is best-effort:
-    // a transport throw degrades to "none declared" rather than crashing Review.
+    // See docs/decisions/publish-path.md#already-merged-hydra: when this run did not execute, hydration uses the existing merge.
     if (!alreadyMergedSha) {
       var hydResult = null;
       try {
@@ -1401,25 +1247,7 @@ while (i < STEPS.length) {
         "published: muse-crew@" + publishTarget.target + "\n" +
         "VERDICT: PASS\n\n";
         } else if (PUBLISH_TYPE === "artifact") {
-      // Deterministic artifact publish (canary b5efd1b1, 2026-09-10): the work
-      // agent claimed "Rebuilt and deployed" while no build ran and no
-      // provenance was stamped — prose-trusted side effects, the same failure
-      // class as the npm double-skip (bb739316). The npm path already runs one
-      // deterministic script; the artifact path now has the same shape. Lock
-      // refresh, rebuild trigger, build-completion poll, and post-deploy are
-      // narrow schema'd bookkeeping calls owned by the workflow — the work
-      // agent reports on the mechanical outcome and cannot skip what it never
-      // owned. Any step failing parks with an honest, step-specific reason
-      // (fail-closed). There is deliberately NO workflow-side provenance
-      // stamp: the builder's applied-report is circular (canary run 8,
-      // 2026-09-11), so the stamp moved to the parent — after the build
-      // lands, the workflow records the session completed and parks with
-      // "publish: verification-requested". The parent owns verification
-      // (docs/publish-verification.md); the primary sensor is the
-      // deterministic lib/readback-disk.js (the agent-callable read-back
-      // tool is unavailable — artifact_inspect was removed by the platform
-      // 2026-09-14 — so the LLM-inspector path is manual-fallback only).
-      // Chore has no QA: the parent's verification is the final gate.
+      // See docs/decisions/publish-path.md#deterministic-artifact-publish: the work agent never publishes; the parent runs the deterministic publish script.
       var artifactPublish = null;
       var publishLockRefreshed = false;
       var publishSkippedNoLock = false;
@@ -1446,20 +1274,7 @@ while (i < STEPS.length) {
           }
           publishLockRefreshed = true;
         }
-        // STEP 1 (mechanical): carry the merged change to the artifact
-        // builder. The builder's source tree is NOT the crew's repo —
-        // canary run 4 (2026-09-11) proved it: Publish asked for "rebuild
-        // from current source. Do not modify any source files" and the
-        // builder rebuilt a stale copy predating the canary's changes, then
-        // the workflow stamped the new commit hash on the stale build.
-        // Provenance fiction; all eight phases passed. The merge diff is
-        // embedded in the edit request; the builder applies it to its own
-        // tree and reports the applied changes; the workflow verifies the
-        // report matches the diff BEFORE stamping provenance. A mismatch
-        // parks without stamping — the stamp must never certify a build
-        // whose content was not verified.
-        // Skipped entirely when no lock was held — nothing merged, nothing
-        // to ship.
+        // See docs/decisions/publish-path.md#step1-builder-source: the builder's source tree is NOT the crew's repo; verify report before stamping.
         if (!publishSkippedNoLock) {
         // The trigger key of the attempt that last ran, for the publish ledger.
         // Minted once here (not re-minted per use site) so the ledger always
@@ -1540,20 +1355,7 @@ while (i < STEPS.length) {
           return await parkTask("Publish cannot proceed for task " + taskId + ": the artifact target preflight was inconclusive (no parsable signal). Target existence is unproven, so no edit was issued and nothing was retried blindly. Human attention needed.");
         }
         log("Publish artifact preflight for task " + taskId + ": target " + artifactTargetDir + " present");
-        // (below) the diff computation, rebuild trigger, application
-        // verification, bounded poll, and provenance stamp. The builder
-        // only makes the artifact_edit call and reports the applied
-        // changes — no prose claim to trust. If the artifact tool namespace
-        // is missing from this child it reports honestly and the workflow
-        // retries once with a fresh key (bounded); anything else parks.
-        // Publish diff base (2026-09-14, task 0c53af4e): the carried diff is
-        // BASE..HEAD where BASE is the previously-stamped provenance
-        // source_commit — NOT HEAD^1. A push-time reconcile merge puts the
-        // task's own changes behind an intermediate merge, so HEAD^1..HEAD
-        // silently drops the task's fix while the artifact builds without
-        // it. The stamped base is the artifact's actual content; BASE..HEAD
-        // is the complete unpublished delta. Empty tree only for a genuine
-        // first publish (no provenance stamped yet).
+        // See docs/decisions/publish-path.md#diff-computation: the diff is computed, the rebuild is triggered, and the report is verified.
         var EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
         var provResult = await agent(
           crewCmd("get-provenance", { project_id: LAUNCH_PROJECT_ID }) + "\n" +
@@ -1569,16 +1371,7 @@ while (i < STEPS.length) {
         } else if (!/^[0-9a-f]{40}$/.test(publishBase)) {
           return await parkTask("Publish base '" + publishBase + "' is not a valid commit SHA — cannot compute the publish diff. Human attention needed.");
         }
-        // Publish diff transport (room #14, 2026-09-17): the diff used to be
-        // ferried as a JSON string field in the agent's response — the agent
-        // produced a valid 700-line diff on disk but the JSON ferry dropped
-        // it, and the parse saw zero files ("Publish diff parsed to zero
-        // files"). The diff now travels git -> file -> deterministic script
-        // summary; the LLM never carries diff bytes. The agent is pure hands:
-        // it runs exactly one command (the PINNED compute-publish-diff.js —
-        // a mid-run release swap cannot change it under the workflow) and
-        // returns the small JSON summary verbatim. All fail-closed parks
-        // below are unchanged in meaning.
+        // See docs/decisions/publish-path.md#diff-transport: the diff travels via file, not the LLM.
         var publishDiffFile = crewHome + "/.publish-diffs/" + taskId + (reworkCount > 0 ? "-r" + reworkCount : "") + ".diff";
         var diffResult = await agent(
           "Run exactly one command and nothing else:\n" +
@@ -1603,6 +1396,7 @@ while (i < STEPS.length) {
           return await parkTask("Publish diff base mismatch: script reported '" + String(diffSummary.base || "").slice(0, 12) + "' but the stamped base is '" + publishBase.slice(0, 12) + "'. Human attention needed.");
         }
         var mergeCommitForPublish = String(diffSummary.commit || "").trim();
+        var mergeCommitShortForPublish = String(mergeCommitForPublish).substring(0, 7) || "unknown";
         var publishDiffSha256 = String(diffSummary.sha256 || "");
         if (!diffSummary.bytes) {
           return await parkTask("Publish diff is empty for commit " + (mergeCommitForPublish || "unknown") + " — a merge lock was held but there is no change to carry. Human attention needed.");
@@ -1654,37 +1448,11 @@ while (i < STEPS.length) {
           "- If artifact_edit is not available after the load, do NOT improvise — end your turn.\n" +
           "- You do NOT call setprovenance, artifact_inspect, or post-deploy yourself.\n" +
           "No report is needed: do not return JSON, do not summarize what you did, do not echo the diff. End your turn after the artifact_edit call.\n";
-        // The artifact build's agent_id, attributed to this edit by the
-        // workflow-owned observation below. The agent_id is the artifact
-        // system's in-flight correlation ID (research 2026-09-12):
-        // artifact.edit returns pending_init with NO agent_id, but
-        // artifact_status exposes build.agent_id immediately after
-        // acceptance, stable across polls. Recorded in the ledger so an
-        // attempt correlates to the exact builder run; null when no build
-        // was ever observed.
+        // See docs/decisions/publish-path.md#agent-id-attribution: the artifact build's agent_id is attributed to the edit call.
         var rebuildAgentId = null;
-        // The builder's applied report is gone (2026-09-16): it rode on the
-        // trigger's JSON closeout contract, which is removed below. The
-        // parent's independent read-back (docs/publish-verification.md) is
-        // the verification — this field stays "missing-report" on ledger
-        // lines for issued triggers; pre-trigger parks (toolcheck
-        // rejected/inconclusive) and unattributed-unknown parks write null
-        // (no trigger was observed, so there is nothing to report).
+        // See docs/decisions/publish-path.md#applied-report-gone: the builder's applied report is gone; the workflow verifies differently.
         var publishAppliedObservation = "missing-report";
-        // Durable-evidence snapshot (2026-09-14): the observation below only
-        // detects IN-FLIGHT builds. A build that finished before the
-        // observation leaves no in-flight trace — but the platform's audit
-        // harness leaves a durable one:
-        // ~/workspace/ts-spaces/<slug>/audits/<timestamp>-<id>/ per
-        // completed build. Snapshot the listing BEFORE the trigger so the
-        // fallback can diff before/after: a directory appearing during the
-        // trigger window is positive evidence the edit went through and
-        // the build completed. Best-effort and non-gating: if the snapshot
-        // fails, auditBeforeOk stays false and BOTH fallback comparisons
-        // are disabled (2026-09-16, critic finding 4) — without a baseline,
-        // an empty before-list would make every historical audit dir look
-        // "new". No wall-clock in-script (deterministic replay) — the
-        // comparison is a pure before/after set diff.
+        // See docs/decisions/publish-path.md#durable-evidence-snapshot: snapshot the audit-dir listing BEFORE the trigger; fallback diffs before/after.
         var auditDirsBeforeTrigger = [];
         var auditBeforeOk = false;
         try {
@@ -1701,36 +1469,7 @@ while (i < STEPS.length) {
         } catch (auditBeforeErr) {
           log("Publish audit-dir snapshot before trigger failed for task " + taskId + " (non-fatal): audit fallback DISABLED for this attempt — without a baseline, historical dirs would look new: " + (auditBeforeErr && auditBeforeErr.message ? auditBeforeErr.message : auditBeforeErr));
         }
-        // Fire-and-forget trigger + workflow-owned observation (2026-09-16,
-        // clean-room task e2a8d9f8): the trigger's JSON closeout contract
-        // traveled over the stochastic text channel, and the runtime's
-        // JSON-candidate heuristic misfired on it ("workflow agent output
-        // was not JSON: no JSON object or array found in final response"),
-        // parking a task whose edit may have gone through. The contract's
-        // content was already observation-only (the applied report never
-        // gated; the pre_hashes were diagnostic-only), so the contract is
-        // removed: the trigger carries NO schema and its return value is
-        // never consumed, which takes the extraction heuristic out of this
-        // call entirely. The workflow attributes the edit itself through
-        // the tiny schema'd reads below — no prose is parsed for the
-        // trigger outcome.
-        // (Probe, 2026-09-16: the workflow scope exposes only agent() —
-        // tool_search, artifact_edit and artifact_status are undefined
-        // there — so the workflow cannot call the artifact tools directly;
-        // observation still goes through minimal child calls with tiny
-        // schemas, never a broad JSON contract.)
-        //
-        // Pre-trigger toolcheck (tiny, schema'd): the artifact namespace is
-        // deferred for workflow children — the child self-loads it and emits
-        // one exact signal line, read mechanically (never English prose).
-        // Only a parsed ARTIFACT_TOOLS: missing signal is explicit negative
-        // evidence: it gets one bounded retry with a fresh key, then parks
-        // rejected — without the tools the edit provably did NOT go through,
-        // so this is the one safe retry on the publish path. A throw (or an
-        // unparseable signal) is INCONCLUSIVE transport noise, never
-        // evidence of missing tools (2026-09-16, critic finding 3): it is
-        // recorded, it retries once in case the flake clears, but it can
-        // never take the rejected path.
+        // See docs/decisions/publish-path.md#fire-and-forget-trigger: the trigger child returns immediately; the workflow owns observation and verdict.
         var publishToolsOk = false;
         var publishToolsMissing = false;
         for (var toolcheckAttempt = 1; toolcheckAttempt <= 2 && !publishToolsOk; toolcheckAttempt++) {
@@ -1778,14 +1517,7 @@ while (i < STEPS.length) {
           }, reworkCount);
           return await parkTask("Publish cannot proceed for task " + taskId + ": the artifact tool namespace was explicitly missing (parsed signal — the edit provably did not go through, so no trigger was issued and nothing was retried blindly). Human attention needed.");
         }
-        // Pre-trigger build-state baseline (tiny, schema'd): one read of
-        // artifact_status. The post-trigger observation diffs against this
-        // baseline — a build whose agent_id was absent from (or differs
-        // from) the baseline is attributed to our edit; a build already in
-        // flight at baseline predates the trigger and is never attributed
-        // to it. If the baseline read itself fails, receipt attribution is
-        // skipped and the durable audit-dir evidence below is the only
-        // positive signal.
+        // See docs/decisions/publish-path.md#pretrigger-baseline: a tiny schema'd baseline is captured before the trigger.
         var baselineAgentId = null;
         var baselineFailed = false;
         try {
@@ -1802,32 +1534,13 @@ while (i < STEPS.length) {
           baselineFailed = true;
           log("Publish pre-trigger baseline read failed for task " + taskId + " (" + (baselineErr && baselineErr.message ? baselineErr.message : baselineErr) + ") — receipt attribution skipped; durable audit-dir evidence is the only positive signal");
         }
-        // The trigger itself: the artifact_edit call is AWAITED (the workflow
-        // waits for it to complete) but its return value is intentionally
-        // UNCONSUMED — NO schema, so no schema validation can fail this
-        // call: a schema-less call resolves to the child's raw response as
-        // a plain string (probed live 2026-09-16 — never parsed, never
-        // throws on content). One caveat, also probed: the runtime still
-        // scans the response for a JSON candidate, and an unparseable
-        // {...}-looking substring in the child's prose throws ("response
-        // JSON candidate", probe P6). The prompt tells the child to end its
-        // turn with no prose at all, which keeps the common case clean —
-        // but the channel is stochastic, so any throw is possible and
-        // inconclusive: the edit may still have gone through, so the
-        // outcome stays unknown until the observation below confirms it —
-        // never inferred from the throw, and never blind-retried (a blind
-        // re-trigger duplicated the edit on 2026-09-12).
+        // See docs/decisions/publish-path.md#trigger-await: the artifact_edit call is awaited.
         var rebuildTrigger = null;
         try {
           var triggerText = String(await agent(rebuildPrompt,
             { key: rebuildAttemptKey, label: "Triggering artifact rebuild" }) || "");
           log("Publish rebuild trigger for task " + taskId + " returned (" + triggerText.length + " chars; awaited; scanned only for the explicit refusal signal)");
-          // Explicit refusal (room #16 blocker 10): the child ends its turn
-          // with ARTIFACT_EDIT_REFUSED when artifact_edit explicitly refused.
-          // Conclusive negative evidence — the edit provably did NOT go
-          // through — so this parks rejected and skips observation polling.
-          // A missing/unparseable signal is NOT a refusal: it stays unknown
-          // and fail-closed below.
+          // See docs/decisions/publish-path.md#explicit-refusal-16: the child must explicitly refuse artifact work.
           var refusalText = extractRefusal(triggerText);
           if (refusalText) {
             await recordPublishLedger({
@@ -1874,17 +1587,79 @@ while (i < STEPS.length) {
           log("Publish post-trigger build-state check failed for task " + taskId + " (" + (buildCheckErr && buildCheckErr.message ? buildCheckErr.message : buildCheckErr) + ") — this signal is unknown, not negative");
         }
         var observedAgentId = (buildState && buildState.build && typeof buildState.build.agent_id === "string" && buildState.build.agent_id) || null;
-        // Known limitation (failure-mode audit 2026-09-16): attribution
-        // is timing-based — any agent_id new relative to the baseline is
-        // treated as this edit's receipt. A stranger's build starting inside
-        // the trigger window is indistinguishable by timing and would be
-        // misattributed here. The consequence is bounded: the completion
-        // poll below tracks the recorded id, and the parent's mechanical
-        // content read-back (docs/publish-verification.md) certifies the
-        // exact commit's content — a wrong build's content fails closed as
-        // verification-failed, never stamped. Timing narrows the candidate;
-        // content decides.
+        // See docs/decisions/publish-path.md#attribution-limitation: attribution is timing-based; content verification bounds the risk.
         var receiptAgentId = (!buildStateFailed && !baselineFailed && observedAgentId && observedAgentId !== baselineAgentId) ? observedAgentId : null;
+        // auditReportOk: pure tri-state read of a report.json body —
+        // true (build ok), false (build failed), null (missing or
+        // unreadable — not evidence either way). The child returns the
+        // raw body verbatim; interpretation lives here, never in prose.
+        // Hoisted to Publish-step scope (before the receipt branch) so both
+        // the immediate and post-poll audit fallbacks share it on every path —
+        // the receipt path skips the else below, which must not leave these
+        // undefined.
+        var auditReportOk = function (raw) {
+          if (typeof raw !== "string") return null;
+          var trimmed = raw.trim();
+          if (trimmed === "" || trimmed === "MISSING") return null;
+          var parsed;
+          try { parsed = JSON.parse(trimmed); } catch (e) { return null; }
+          if (parsed && typeof parsed.ok === "boolean") return parsed.ok;
+          return null;
+        };
+        // (2026-09-18, H2 verdict-first) Publish-verdict vocabulary. The
+        // verdict is one of "landed" | "unknown". Decided once,
+        // before the receipt poll, and dispatched on — never re-derived.
+        // Pure and self-contained: unit-tested by
+        // tests/publish-verdict-first.test.js.
+        // See docs/decisions/publish-path.md#h2-verdict-dispatch.
+        var decidePublishVerdict = function (opts) {
+          var immediateReport = (opts && "immediateReport" in opts) ? opts.immediateReport : null;
+          var newDirCount = (opts && typeof opts.newDirCount === "number") ? opts.newDirCount : 0;
+          if (newDirCount === 1 && immediateReport === true) return { verdict: "landed", unattributableReason: null };
+          if (newDirCount === 1 && immediateReport === false) return { verdict: "unknown", unattributableReason: "audit-report-ok-false" };
+          if (newDirCount === 1) return { verdict: "unknown", unattributableReason: "audit-report-unreadable-or-missing" };
+          if (newDirCount === 0) return { verdict: "unknown", unattributableReason: "no-new-audit-dir-in-window" };
+          return { verdict: "unknown", unattributableReason: "audit-dir-ambiguity", ambiguousDirCount: newDirCount };
+        };
+        // (2026-09-18, H2 message contract, design §1.5) The human line is
+        // the output of a mechanical field→template mapping: the trigger
+        // commit short-sha, one plain clause per unattributable reason, the
+        // no-republish warning, the ledger path with (outcome: unknown), and
+        // the unknown-recovery clause. The appendix carries every machine
+        // field. Pure and self-contained: unit-tested by
+        // tests/publish-verdict-first.test.js.
+        var composeUnattributedParkReason = function (fields) {
+          var f = fields || {};
+          var task = f.taskId || taskId;
+          var reason = f.unattributableReason || "unknown-outcome";
+          var shortSha = String(f.commitShortSha || "").substring(0, 7) || "unknown";
+          var reasonClauses = {
+            "no-new-audit-dir-in-window": "no build could be tied to this attempt",
+            "audit-report-unreadable-or-missing": "the build's report is unreadable",
+            "audit-dir-ambiguity": "more than one build appeared in the check window",
+            "stranger-build-observed-during-poll": "a different build was running during the check",
+            "status-read-errors-during-poll": "status reads kept failing"
+          };
+          var clause = reasonClauses[reason] || "no build could be tied to this attempt";
+          return "Publish outcome unknown for task " + task +
+            ": the trigger was sent for commit " + shortSha + " but the outcome could not be confirmed — " + clause + ". " +
+            "Do NOT republish: if the trigger was accepted, a retry duplicates the build (2026-09-12). " +
+            "The attempt is in the ledger at " + crewHome + "/.publish-ledger/" + PUBLISH_SLUG + ".jsonl (outcome: unknown) " +
+            "and the crew's unknown-recovery will re-examine it. " +
+            "Appendix: unattributable_reason=" + reason +
+            "; poll_end_state=" + (f.pollEndState || "not-polled") +
+            "; saw_our_build=" + (f.sawOurBuild ? "true" : "false") +
+            "; new_audit_dirs=" + (f.newAuditDirCount == null ? 0 : f.newAuditDirCount) +
+            "; poll_chunks_failed=" + (f.chunkFailures == null ? 0 : f.chunkFailures) +
+            "; poll_status_errors=" + (f.pollStatusErrors == null ? 0 : f.pollStatusErrors) + ".";
+        };
+        // publishFailure is declared here (per-Publish-pass scope) so the
+        // post-poll explicit build failure survives to the final routing
+        // below; publishUnknownFields carries the structured unknown fields
+        // for the single composed fail-closed park. Both re-initialize on
+        // every pass — a rework re-entry never leaks a stale verdict.
+        var publishFailure = null;
+        var publishUnknownFields = null;
         if (receiptAgentId) {
           // The edit went through — a build with a new agent_id appeared
           // after the trigger. The parent's independent read-back
@@ -1903,31 +1678,6 @@ while (i < STEPS.length) {
           }, reworkCount);
         } else {
           var newAuditDirs = [];
-          // auditReportOk: pure tri-state read of a report.json body —
-          // true (build ok), false (build failed), null (missing or
-          // unreadable — not evidence either way). The child returns the
-          // raw body verbatim; interpretation lives here, never in prose.
-          // Defined here so both the immediate and post-poll audit
-          // fallbacks share it.
-          var auditReportOk = function (raw) {
-            if (typeof raw !== "string") return null;
-            var trimmed = raw.trim();
-            if (trimmed === "" || trimmed === "MISSING") return null;
-            var parsed;
-            try { parsed = JSON.parse(trimmed); } catch (e) { return null; }
-            if (parsed && typeof parsed.ok === "boolean") return parsed.ok;
-            return null;
-          };
-          // (2026-09-16, critic finding 2) When durable audit evidence
-          // confirms (or refutes) the build, there is no receipt agent_id
-          // to chain the completion poll to — skipReceiptPoll bypasses the
-          // poll below, which with a null receipt could only observe
-          // strangers or nothing.
-          var skipReceiptPoll = false;
-          // publishFailure is declared here (moved up from below) so the
-          // immediate audit fallback can record an explicit build failure
-          // without the later declaration resetting it.
-          var publishFailure = null;
           try {
             var auditAfter = await agent(
               "List the artifact audit directories for slug \"" + PUBLISH_SLUG + "\" (best-effort, never a gate).\n" +
@@ -1947,88 +1697,109 @@ while (i < STEPS.length) {
             log("Publish audit-dir re-list after trigger failed for task " + taskId + " (non-fatal, durable-evidence check degraded): " + (auditAfterErr && auditAfterErr.message ? auditAfterErr.message : auditAfterErr));
           }
           if (newAuditDirs.length > 0) {
-            rebuildTrigger = { edit_started: true };
             rebuildAgentId = null;
             newAuditDirs.sort();
             var newestImmediateDir = newAuditDirs[newAuditDirs.length - 1];
             log("Publish rebuild trigger for task " + taskId + ": new audit dir(s) during the trigger window (" + newAuditDirs.join(", ") + ") — the edit went through and a build completed; no in-flight receipt was observed.");
-            // (2026-09-16, critic finding 2) Durable audit evidence exists,
+            // (2026-09-18, H2 verdict-first) Durable audit evidence exists,
             // but there is no receipt agent_id to chain the completion poll
             // to — polling with a null receipt can only observe strangers
             // (any running build differs from "null") or nothing, burning
-            // 10.5 minutes to park unknown. Read the build report now
-            // instead of polling: ok=true confirms completion and routes
-            // directly to parent verification (the poll is skipped);
-            // ok=false is explicit failure; unreadable is unknown.
+            // 10.5 minutes to park unknown. Read the build report now instead
+            // of polling, then decide the verdict ONCE via
+            // decidePublishVerdict: exactly one new dir with ok=true lands
+            // (attribution by window, not identity — never poll blind);
+            // ok=false is UNKNOWN with the failure evidence preserved in the
+            // ledger detail (the evidence is explicit, the attribution is
+            // not); unreadable / zero / ambiguous dirs are UNKNOWN.
+            // Verdict-first: landed bypasses the poll below, unknown falls
+            // through to post-deploy. STEP 2 runs on every path.
+            // See docs/decisions/publish-path.md#h2-verdict-dispatch.
             var immediateReportOk = null;
-            try {
-              var immediateOkRead = await agent(
-                "Read the artifact build report for slug \"" + PUBLISH_SLUG + "\".\n" +
-                "Run: cat ~/workspace/ts-spaces/" + PUBLISH_SLUG + "/audits/" + newestImmediateDir + "/report.json 2>/dev/null || echo MISSING\n" +
-                "Return JSON { \"raw\": \"<verbatim file contents, or the literal string MISSING when the file does not exist>\" } and nothing else.",
-                { key: attemptKey("publish-audit-ok-immediate-" + taskId, reworkCount), label: "Reading build report for audit-confirmed build",
-                  schema: { type: "object", properties: { raw: { type: "string" } }, required: ["raw"] } }
-              );
-              immediateReportOk = auditReportOk(immediateOkRead && immediateOkRead.raw);
-            } catch (immediateOkErr) {
-              log("Publish build-report read for audit-confirmed dir failed for task " + taskId + " (treated as unknown): " + (immediateOkErr && immediateOkErr.message ? immediateOkErr.message : immediateOkErr));
-              immediateReportOk = null;
+            // (N1) Read the report only when exactly one new dir exists:
+            // ambiguity (>1) forces UNKNOWN regardless — don't shell out to
+            // read a report that will be discarded.
+            if (newAuditDirs.length === 1) {
+              try {
+                var immediateOkRead = await agent(
+                  "Read the artifact build report for slug \"" + PUBLISH_SLUG + "\".\n" +
+                  "Run: cat ~/workspace/ts-spaces/" + PUBLISH_SLUG + "/audits/" + newestImmediateDir + "/report.json 2>/dev/null || echo MISSING\n" +
+                  "Return JSON { \"raw\": \"<verbatim file contents, or the literal string MISSING when the file does not exist>\" } and nothing else.",
+                  { key: attemptKey("publish-audit-ok-immediate-" + taskId, reworkCount), label: "Reading build report for audit-confirmed build",
+                    schema: { type: "object", properties: { raw: { type: "string" } }, required: ["raw"] } }
+                );
+                immediateReportOk = auditReportOk(immediateOkRead && immediateOkRead.raw);
+              } catch (immediateOkErr) {
+                log("Publish build-report read for audit-confirmed dir failed for task " + taskId + " (treated as unknown): " + (immediateOkErr && immediateOkErr.message ? immediateOkErr.message : immediateOkErr));
+                immediateReportOk = null;
+              }
             }
-            if (immediateReportOk === true) {
+            var immediateVerdict = decidePublishVerdict({ editStarted: true, immediateReport: immediateReportOk, newDirCount: newAuditDirs.length });
+            if (immediateVerdict.verdict === "landed") {
               publishBuildLanded = true;
               artifactPublish = { source_commit: mergeCommitForPublish, pending_parent_verification: true };
-              skipReceiptPoll = true;
-              log("Publish build landed for task " + taskId + " via immediate durable audit evidence (audit dir " + newestImmediateDir + ", report ok=true) — receipt poll skipped (no receipt to chain to), routing directly to parent verification");
               await recordPublishLedger({
                 commit: mergeCommitForPublish,
                 attempt: rebuildAttemptKey,
                 agent_id: null,
                 applied_report: publishAppliedObservation,
                 outcome: "submitted",
-                detail: "durable audit evidence shows a build completed during the attempt window (audit dir " + newestImmediateDir + ", report ok=true); receipt poll skipped (no receipt agent_id), routed to parent verification"
-              }, reworkCount);
-            } else if (immediateReportOk === false) {
-              skipReceiptPoll = true;
-              publishFailure = "Artifact build FAILED for slug " + PUBLISH_SLUG + " (audit dir " + newestImmediateDir + ", report ok=false — immediate audit evidence, no receipt observed). Explicit negative evidence: a build ran and failed. The publish did not land — provenance was not stamped. Fail-closed.";
-              await recordPublishLedger({
-                commit: mergeCommitForPublish,
-                attempt: rebuildAttemptKey,
-                agent_id: null,
-                applied_report: publishAppliedObservation,
-                outcome: "failed",
-                detail: "a build ran and failed: audit dir " + newestImmediateDir + " report ok=false (immediate audit evidence, no receipt)"
+                detail: "durable audit evidence shows a build completed during the attempt window (no receipt agent_id — attribution by window, not identity; receipt poll bypassed (verdict decided), routed to parent verification)"
               }, reworkCount);
+              log("Publish verdict LANDED for task " + taskId + ": a completed build was observed during the attempt window — receipt poll bypassed (verdict decided, no receipt to chain to), routing directly to parent verification.");
             } else {
+              // Verdict UNKNOWN on the immediate path. ok=false is explicit
+              // failure evidence but not an attributable failure — the ledger
+              // records unknown with the evidence preserved in the detail,
+              // and the flow continues to post-deploy (never parks early).
+              publishUnknownFields = {
+                taskId: taskId,
+                unattributableReason: immediateVerdict.unattributableReason,
+                pollEndState: "not-polled",
+                sawOurBuild: false,
+                newAuditDirCount: newAuditDirs.length,
+                chunkFailures: 0,
+                pollStatusErrors: 0
+              };
+              var immediateDetail = "durable audit-dir fallback could not prove a completed build for this attempt (unattributable_reason=" + immediateVerdict.unattributableReason + ", no receipt agent_id)";
+              if (immediateReportOk === false) {
+                immediateDetail += "; explicit failure evidence preserved: report ok=false for audit dir " + newestImmediateDir;
+              }
+              if (immediateVerdict.unattributableReason === "audit-dir-ambiguity") {
+                immediateDetail += "; audit-dir ambiguity: " + newAuditDirs.length + " new dirs in window";
+              }
               await recordPublishLedger({
                 commit: mergeCommitForPublish,
                 attempt: rebuildAttemptKey,
                 agent_id: null,
-                applied_report: null,
+                applied_report: publishAppliedObservation,
                 outcome: "unknown",
-                detail: "new audit dir " + newestImmediateDir + " appeared during the trigger window but its build report is unreadable/missing; no receipt agent_id to poll — outcome unknown, fail-closed with no blind retry"
+                detail: immediateDetail
               }, reworkCount);
-              return await parkTask("Publish outcome unknown for task " + taskId + ": a new audit dir (" + newestImmediateDir + ") appeared during the trigger window but its build report is unreadable, and no in-flight receipt was observed to poll. The edit may have completed. Correlate the accepted edit via the publish ledger at " + crewHome + "/.publish-ledger/" + PUBLISH_SLUG + ".jsonl — do NOT reissue the edit blindly: if the trigger was accepted, a retry duplicates it (2026-09-12). Verify independently whether the build completed (audit dir + report, or the parent's content read-back) before deciding the next step. Fail-closed.");
+              log("Publish verdict UNKNOWN for task " + taskId + ": " + immediateDetail + " — continuing to post-deploy; never polling blind and never parking early.");
             }
           } else {
-            // No attributable build and no durable evidence — but that
-            // proves nothing (a fast-completing build can finish between
-            // polls, or the checks themselves failed). The outcome is
-            // UNKNOWN. No retry: re-issuing the edit here duplicated it on
-            // 2026-09-12. Record the attempt durably and park fail-closed;
-            // correlate via the ledger, never by guessing from a blind poll.
-            log("Publish rebuild trigger for task " + taskId + ": no attributable build observed and no new audit dir — outcome UNKNOWN. Recording the attempt and parking fail-closed; no blind retry.");
+            // See docs/decisions/publish-path.md#no-attributable-build: no attributable build and no durable evidence means no publish.
+            publishUnknownFields = {
+              taskId: taskId,
+              unattributableReason: decidePublishVerdict({ editStarted: true, immediateReport: null, newDirCount: 0 }).unattributableReason,
+              pollEndState: "not-polled",
+              sawOurBuild: false,
+              newAuditDirCount: 0,
+              chunkFailures: 0,
+              pollStatusErrors: 0
+            };
             await recordPublishLedger({
               commit: mergeCommitForPublish,
               attempt: rebuildAttemptKey,
               agent_id: null,
-              applied_report: null,
+              applied_report: publishAppliedObservation,
               outcome: "unknown",
-              detail: "fire-and-forget trigger; post-trigger build-state poll saw no attributable build (or the check failed) and the audit-dir diff found no new dir; the edit may have been accepted as pending_init"
+              detail: "no new audit dir appeared in the trigger window and no receipt agent_id was observed — the edit was issued fire-and-forget, so completion is unproven; never poll blind on a null receipt"
             }, reworkCount);
-            return await parkTask("Publish outcome unknown for task " + taskId + ": the rebuild trigger was issued fire-and-forget (no schema, so no validation failure mode; a candidate-parse throw stays possible and is inconclusive), and the follow-up observation could not attribute a build to the edit for slug " + PUBLISH_SLUG + " — no in-flight build with a new agent_id appeared in the poll window and no new audit dir landed. The edit may have been accepted as pending_init, so no retry was issued: a blind retry duplicated the edit on 2026-09-12. The attempt is recorded in the publish ledger at " + crewHome + "/.publish-ledger/" + PUBLISH_SLUG + ".jsonl (commit " + String(mergeCommitForPublish || "unknown").slice(0, 12) + "). Correlate the accepted edit via the ledger and the builder's eventual completion — do NOT reissue the edit blindly. Verify independently whether the build completed before deciding the next step. Fail-closed.");
+            log("Publish verdict UNKNOWN for task " + taskId + ": no new audit dir in window and no receipt — continuing to post-deploy; never polling blind and never parking early.");
           }
         }
-
         // Durable publish-attempt ledger: record the trigger outcome while the
         // attempt key and commit are in scope. Every attempt lands here with
         // its outcome — submitted, rejected, or unknown (unknown is recorded
@@ -2038,9 +1809,45 @@ while (i < STEPS.length) {
         // already recorded the ledger's submitted line on both positive paths
         // and parked on unknown — there is no applied report to observe and
         // no rejection signal to record.
-        // (publishFailure is declared with the immediate audit fallback
-        // above so an explicit build failure there survives to here.)
-        if (rebuildTrigger.edit_started && !skipReceiptPoll) {
+        // (2026-09-18, H2 verdict-first) The verdict was decided exactly
+        // once above; dispatch on it. landed bypasses the receipt poll
+        // (the audit evidence already proved completion); an explicit
+        // publishFailure is preserved verbatim through post-deploy.
+        // Otherwise the verdict is open — but the poll below is only
+        // legitimate against a real receipt: the null-safe assertion records
+        // UNKNOWN and continues to STEP 2 instead of polling blind.
+        // See docs/decisions/publish-path.md#h2-verdict-dispatch.
+        if (publishBuildLanded) {
+          log("Publish verdict already LANDED for task " + taskId + " — bypassing receipt poll.");
+        } else if (publishFailure) {
+          // design §1.2 pre-poll branch — currently unassigned; kept for the converged dispatch shape.
+          log("Publish verdict already FAILED for task " + taskId + " — preserved verbatim through post-deploy.");
+        } else if (!rebuildTrigger || !rebuildTrigger.edit_started) {
+          // Loud defensive assertion (replaces the old lying "Unreachable"
+          // else): with no receipt state the poll would observe strangers or
+          // nothing — record UNKNOWN and continue to STEP 2. Never park
+          // early here; never poll blind.
+          if (!publishUnknownFields) {
+            publishUnknownFields = {
+              taskId: taskId,
+              unattributableReason: "no-receipt-state",
+              pollEndState: "not-polled",
+              sawOurBuild: false,
+              newAuditDirCount: 0,
+              chunkFailures: 0,
+              pollStatusErrors: 0
+            };
+            await recordPublishLedger({
+              commit: mergeCommitForPublish,
+              attempt: rebuildAttemptKey,
+              agent_id: null,
+              applied_report: publishAppliedObservation,
+              outcome: "unknown",
+              detail: "no receipt state was recorded for this attempt — never polling blind; continuing to post-deploy"
+            }, reworkCount);
+          }
+          log("Publish verdict UNKNOWN for task " + taskId + ": no receipt state recorded — never polling blind, continuing to post-deploy.");
+        } else {
           // (2026-09-16) There is no builder report: the fire-and-forget
           // trigger carries no JSON contract, so there is nothing to
           // compare and no pre-hash diagnostic. The builder's old
@@ -2113,13 +1920,7 @@ while (i < STEPS.length) {
                   timeoutMs: 270000 }
               );
             } catch (chunkErr) {
-              // A hung or failed chunk is inconclusive, never terminal:
-              // record it and continue to the next chunk. (2026-09-16,
-              // clean-room task 1febe8eb: the platform's 270s agent
-              // timeout killed chunk 2, which threw out of this loop —
-              // skipping chunk 3 AND the STEP 1b audit-dir fallback and
-              // parking on the exception path.) Fail-closed still applies
-              // after chunk 3 and the fallback are exhausted.
+              // See docs/decisions/publish-path.md#hung-chunk: a hung or failed chunk is inconclusive, never terminal.
               chunkFailures.push("chunk " + chunk + ": " + (chunkErr && chunkErr.message ? chunkErr.message : chunkErr));
               log("Artifact build poll chunk " + chunk + " of 3 failed (" + (chunkErr && chunkErr.message ? chunkErr.message : chunkErr) + ") \u2014 continuing to the next chunk; build completion still unproven.");
             }
@@ -2135,20 +1936,7 @@ while (i < STEPS.length) {
             buildPoll = { build_done: false, status: (buildPoll && buildPoll.status) || "build still running after the 10.5-minute bounded poll" };
           }
           if (buildPoll.build_done && pollSawOurBuild) {
-            // STEP 1c (mechanical): NO provenance stamp here. Canary run 8
-            // (2026-09-11) proved the stamp cannot certify content: the
-            // builder's applied-report was derived from the carried diff, so
-            // the old report check was circular — a fabricated report
-            // passed by construction, and every phase went green on a hollow
-            // build. The stamp moves to the parent (docs/publish-verification.md);
-            // the deterministic lib/readback-disk.js is the primary sensor
-            // (the agent-callable read-back tool is unavailable —
-            // artifact_inspect was removed by the platform 2026-09-14 — so
-            // the LLM-inspector path is manual-fallback only), and the task
-            // parks for parent verification.
-            // Chore has no QA: the parent's verification is the final gate.
-            // An unverified publish fails loudly in QA instead of passing
-            // silently here.
+            // See docs/decisions/publish-path.md#step-1c-no-stamp: no provenance stamp in STEP 1c.
             publishBuildLanded = true;
             artifactPublish = { source_commit: mergeCommitForPublish, pending_parent_verification: true };
             log("Publish build landed for task " + taskId + " — provenance stamp deferred to parent content verification");
@@ -2231,7 +2019,11 @@ while (i < STEPS.length) {
                 detail: "durable audit evidence shows a build completed during the attempt window (audit dir " + newestAuditDirAfterPoll + ", report ok=true); routed to parent verification"
               }, reworkCount);
             } else if (auditOkAfterPoll === false) {
-              publishFailure = "Artifact build FAILED for slug " + PUBLISH_SLUG + " (audit dir " + newestAuditDirAfterPoll + ", report ok=false). Explicit negative evidence: a build ran and failed (attribution by window, not by build identity — no stranger build was observed in flight during the poll). The publish did not land — provenance was not stamped. Fail-closed.";
+              // Explicit negative evidence under the stranger guard: a build
+              // ran and failed during the poll window with no stranger in
+              // flight. This is an attributable failure — preserved verbatim
+              // through post-deploy. Message contract unchanged.
+              publishFailure = "Artifact build FAILED for slug " + PUBLISH_SLUG + " (audit dir " + newestAuditDirAfterPoll + ", report ok=false). Explicit negative evidence: a build ran and failed (attribution by window, not by build identity — no stranger build was observed in flight during the poll). The publish did not land — provenance was not stamped — your change was NOT published. Build log: ~/workspace/ts-spaces/" + PUBLISH_SLUG + "/audits/" + newestAuditDirAfterPoll + "/. This explicit failure is not auto-retried. Appendix: attribution=window; report=ok=false; provenance=unstamped.";
               await recordPublishLedger({
                 commit: mergeCommitForPublish,
                 attempt: rebuildAttemptKey,
@@ -2245,7 +2037,19 @@ while (i < STEPS.length) {
                 : ((pollStatusErrors > 0 && !pollSawOurBuild) ? "status-read-errors-during-poll"
                 : (pollEndState === "build-still-running-at-poll-end" ? "build-still-running-at-poll-end"
                 : (newAuditDirsAfterPoll.length === 0 ? "no-new-audit-dir-in-window" : "audit-report-unreadable-or-missing")));
-              publishFailure = "Artifact build completion unproven (fail-closed, no provenance stamped): unattributable_reason=" + unattributableReason + "; poll_end_state=" + pollEndState + "; " + "saw_our_build=" + pollSawOurBuild + "; new_audit_dirs=" + newAuditDirsAfterPoll.length + "; poll_chunks_failed=" + chunkFailures.length + "; poll_status_errors=" + pollStatusErrors + ". Attribution is by window, not by build identity. The publish may or may not have landed. Fail-closed.";
+              // Verdict UNKNOWN (poll path): the build cannot be attributed
+              // to this attempt. The fields feed the single composed
+              // fail-closed park reason after post-deploy — never a
+              // fabricated verdict, never a silent pass.
+              publishUnknownFields = {
+                taskId: taskId,
+                unattributableReason: unattributableReason,
+                pollEndState: pollEndState,
+                sawOurBuild: pollSawOurBuild,
+                newAuditDirCount: newAuditDirsAfterPoll.length,
+                chunkFailures: chunkFailures.length,
+                pollStatusErrors: pollStatusErrors
+              };
               await recordPublishLedger({
                 commit: mergeCommitForPublish,
                 attempt: rebuildAttemptKey,
@@ -2256,11 +2060,8 @@ while (i < STEPS.length) {
               }, reworkCount);
             }
           }
-        } else {
-          // Unreachable: the observation above either attributes the edit
-          // (edit_started) or parks. Defensive only — never a silent pass.
-          publishFailure = "Artifact rebuild trigger failed: the edit was not attributed to any observed build. The publish is unattributed (not proven landed, not proven failed) — provenance was not stamped. Fail-closed.";
         }
+
         } // end: publishSkippedNoLock — no rebuild, no stamp, nothing to ship
         // STEP 2 (mechanical, always — skip path included): post-deploy
         // commits builder leftovers if any, removes the worktree, and releases
@@ -2284,6 +2085,19 @@ while (i < STEPS.length) {
               ? " Post-deploy finalized cleanup."
               : " Post-deploy also failed (" + (postDeploy.output || "no output") + ") — worktree and lock state unknown."));
           }
+          if (!publishBuildLanded) {
+            // Verdict UNKNOWN (single fail-closed park — post-deploy always
+            // runs first; no early parks anywhere above). Machine contract:
+            // "unattributable_reason=" and "poll_end_state=" are always
+            // present; attribution is by window, not identity.
+            // (2026-09-18, H2 message contract) Thread the commit short-sha
+            // through the unknown fields so the human line names the trigger
+            // commit (design §1.5: "the trigger was sent for commit <short-sha>").
+            if (publishUnknownFields) publishUnknownFields.commitShortSha = mergeCommitShortForPublish;
+            return await parkTask(composeUnattributedParkReason(publishUnknownFields) + (postDeploy.deployed
+              ? " Post-deploy finalized cleanup."
+              : " Post-deploy also failed (" + (postDeploy.output || "no output") + ") — worktree and lock state unknown."));
+          }
           if (!postDeploy.deployed) {
             return await parkTask("Post-deploy failed after the artifact build landed: " + (postDeploy.output || "no output") + ". The build may have landed but worktree cleanup and lock release are unknown — human attention needed.");
           }
@@ -2508,18 +2322,7 @@ while (i < STEPS.length) {
     }
     log("Build worktree confinement passed: " + wt.path);
 
-    // Already-merged idempotency: a `repo_diff: none (already-merged:
-    // <sha>)` declaration is verified mechanically — <sha> must resolve
-    // and be an ancestor of main in the configured repo. A fabricated or
-    // mistaken declaration fails the phase here (the dispatcher retries
-    // Build under its consecutive-failure cap); a verified declaration is
-    // recorded in alreadyMergedSha for Review's no-diff branch. Without
-    // this guard, Build correctly doing nothing left Review with no
-    // mechanical way to accept an empty diff, and Cass rejected for "no
-    // commits ahead of main — the builder likely forgot to commit" while
-    // the deliverable sat on main (canary 2026-09-15, task 1d692d91).
-    // The sha is hex-only by construction (extractAlreadyMerged), so
-    // interpolating it into the shell command cannot inject.
+    // See docs/decisions/publish-path.md#already-merged-idem: an already-merged repo_diff is idempotent; no rebuild.
     var am = extractAlreadyMerged(workerText);
     if (am.sha) {
       var amCheck = await agent(
@@ -2565,20 +2368,7 @@ while (i < STEPS.length) {
   };
   let passed = stepResult.passed === true;
 
-  // Deterministic integrate verification: the agent cannot self-certify a
-  // merge. After the Integrate agent claims success, the workflow confirms
-  // mechanically that the task branch tip is an ancestor of main via the
-  // lifecycle script's verify-merge command (which resolves the branch
-  // through the crew registry — never by reconstructing "task/"+taskId — so
-  // the check cannot verify the wrong branch). The VERIFIED marker is matched
-  // by regex on the script's own stdout; agent prose is never read. This
-  // closes the hole where an agent reported "merged empty" while approved
-  // commits were still stranded on the task branch (bug b1b1f919). A genuine
-  // empty-diff Integrate (MERGED_EMPTY: no commits ahead of main) verifies
-  // vacuously — the tip is then an ancestor of main. Verification failure is
-  // an operational step failure, not a park: the dispatcher retries Integrate
-  // under its consecutive-failure cap, and the retry finds the commits still
-  // on the branch and performs the real merge — self-healing.
+  // See docs/decisions/publish-path.md#integrate-verify: the agent cannot verify integrate mechanically; the workflow checks the diff.
   if (step.name === "Integrate" && passed) {
     var integrateVerifyOut = "";
     try {
@@ -2609,17 +2399,7 @@ while (i < STEPS.length) {
   // retryable under the dispatcher's consecutive-failure cap.
   const status = passed ? "completed" : (step.name === "Integrate" || step.name === "Publish" ? "failed" : "rejected");
 
-  // Deterministic publish verification: the agent cannot self-certify a publish.
-  // Skip-aware (park 2026-09-11): when the deterministic publish script found
-  // no merge lock held (empty-diff Integrate), it skips the publish path
-  // gracefully and emits the machine-readable PUBLISH_SKIPPED=no-lock-held
-  // marker. The preflight (bugfix 2026-09-17) emits
-  // PUBLISH_SKIPPED=no-npm-publish when npm publish is not configured on
-  // this machine (helper or credential absent) — also before any mutation.
-  // Verification is then vacuous — nothing was shipped, and the
-  // registry must NOT have moved. The marker is script-emitted explicit state
-  // (pasted verbatim per the Publish agent instructions), not agent prose; a
-  // report without the marker still runs the full verification fail-closed.
+  // See docs/decisions/publish-path.md#publish-verify: the agent cannot verify publish; the parent does.
   var publishVerified = false;
   var npmPublishSkipped = false;
   if (step.name === "Publish" && PUBLISH_TYPE === "npm" && publishTarget) {
@@ -2645,15 +2425,7 @@ while (i < STEPS.length) {
           publishTarget.target + " (" + publishTarget.base + " + " + publishTarget.scope + "). The publish did not land.");
       }
       publishVerified = true;
-      // Provenance refresh for self-publishes (task 7946d2a4): the npm path
-      // installs and activates a new immutable release (crew-release.sh deploy
-      // swaps the `current` symlink inside publish-npm.sh) but never stamped
-      // the dashboard's provenance record — every crew release left
-      // crew_release pointing at a pruned release. After a verified landed
-      // publish, refresh the record's crew_release to the now-live release
-      // identity, preserving the existing source_commit (the dashboard
-      // artifact's build source — a crew-repo commit here would fail the
-      // dashboard QA source check).
+      // See docs/decisions/publish-path.md#provenance-refresh: refresh crew_release after landed publish, preserving source_commit.
       try {
         var provRefresh = await agent(
           "Run in shell and return the stdout verbatim:\n" + crewCmd("get-provenance", { project_id: LAUNCH_PROJECT_ID }) + "\n" +
@@ -2683,31 +2455,10 @@ while (i < STEPS.length) {
     } // end: !npmPublishSkipped — a skipped publish has nothing to verify
   }
 
-  // Publish content verification — parent-owned (docs/publish-verification.md).
-  // The old block read back the workflow's OWN provenance stamp and compared
-  // it to HEAD: that verifies the stamp, not the content. Canary run 8
-  // (2026-09-11) passed it with a hollow build — the stamp was honest, the
-  // artifact was stale, all eight phases green. The stamp now moves to the
-  // parent (docs/publish-verification.md); the independent read-back step
-  // is currently unavailable (no agent-callable read-back tool exists —
-  // artifact_inspect was removed by the platform 2026-09-14), so the parent
-  // cannot confirm content and the task parks for verification.
-  // Skip-aware (park 2026-09-11): an empty-diff Integrate takes no merge
-  // lock, and the deterministic publish path skips rebuild/stamp entirely —
-  // there is no new content to verify, so verification is vacuous.
-  // publishSkippedNoLock is workflow-computed state from the explicit
-  // lock-status read in STEP 0, not agent prose.
-  // The parent (tick worker) triggers the ONE read-back inspection it can
-  // actually receive (async results go to the root agent, never into a
-  // workflow run — a workflow-side trigger would be an orphan). The workflow
-  // only parks; the parent's scan builds the request deterministically via
-  // lib/build-readback-request.js and ferries the inspection.
-  // publishBuildLanded and publishSkippedNoLock are workflow-computed state;
-  // a skipped or failed publish has nothing to verify.
-  // Session notes. Machine-readable marker lines are extracted from the full
-  // worker report and appended AFTER the slice so a long report can never
-  // amputate them; later phases (Review reading repo_diff:, QA backstop
-  // reading TARGET_VERSION=) depend on them.
+  // Parent-owned verification (docs/publish-verification.md): the parent's
+  // scan builds the request via lib/build-readback-request.js and ferries
+  // the inspection; a skipped or failed publish has nothing to verify.
+  // See docs/decisions/publish-path.md#parent-owned-verification for history.
   let summary;
   var workerMarkers = extractMarkerLines(workerText);
   if (step.name === "Publish" && PUBLISH_TYPE === "npm" && publishTarget && (publishVerified || npmPublishSkipped)) {
@@ -2721,12 +2472,7 @@ while (i < STEPS.length) {
   } else {
     summary = (stepResult.summary || "Step completed").slice(0, 2000 - workerMarkers.length - 1) + (workerMarkers ? "\n" + workerMarkers : "");
   }
-  // Already-merged attestation: when the Build gate verified the builder's
-  // already-merged declaration, the workflow records its own marker line in
-  // the session notes (like the builder markers above, it is appended after
-  // the slice so it can never be amputated). A later run resumed at Review
-  // hydrates alreadyMergedSha from this workflow-attested line — never from
-  // the builder's declaration alone.
+  // See docs/decisions/publish-path.md#already-merged: when the Build gate verifies already-merged, attestation is recorded.
   if (step.name === "Build" && alreadyMergedSha) {
     summary += "\nalready_merged_verified: " + alreadyMergedSha;
   }
@@ -2798,18 +2544,17 @@ while (i < STEPS.length) {
     return { status: "failed", task_id: taskId, reason: "Publish failed: " + summary };
   }
 
-  // Publish verification park: the build landed and post-deploy finalized,
-  // but provenance is UNSTAMPED until the parent's independent read-back
-  // (docs/publish-verification.md) confirms the artifact's actual content
-  // matches the merged diff. The parent stamps provenance, then re-queues;
-  // the dispatcher resumes at QA, whose provenance check enforces the stamp
-  // mechanically. A failed Publish never reaches this park — it returned
-  // failed above and retries under the dispatcher's cap. The merge lock is
-  // already released (post-deploy), so the parked task holds no resources.
+  // See docs/decisions/publish-path.md#verification-park: the build landed but provenance is unstamped until parent verification.
   if (passed && step.name === "Publish" && PUBLISH_TYPE === "artifact" && PUBLISH_SLUG && !publishSkippedNoLock && publishBuildLanded) {
+    // Success contract (2026-09-18, H2): the parent asked for exactly
+    // one build for this publish. The build landed — do NOT republish: a
+    // duplicate build would re-publish the same change. content_check=pending
+    // means the parent's independent read-back has not happened yet; this
+    // park is NOT proof the content is correct.
     return await parkTask("publish: verification-requested " + mergeCommitForPublish +
-      " (build " + (rebuildAgentId || "agent_id unobserved") + ")" +
-      " — artifact build landed, post-deploy finalized, provenance NOT stamped. Parent: run docs/publish-verification.md.");
+      " Do NOT republish: a duplicate build would re-publish the same change. " +
+      "Artifact build landed, post-deploy finalized, provenance not stamped — the crew has not yet independently confirmed the live artifact contains exactly the change; waiting on the manual read-back in docs/publish-verification.md. " +
+      "Appendix: build=" + (rebuildAgentId || "agent_id unobserved") + "; provenance=unstamped; content_check=pending.");
   }
 
   i++;