muse-crew 0.13.2 → 0.14.0

package/docs/decisions/publish-path.md

@@ -0,0 +1,1280 @@
+# Decision history: publish path
+
+Relocated from workflow source comments during H5 (2026-09-18). The workflows keep only the relied-upon invariant inline; the full decision history lives here.
+
+<a id="fire-and-forget-trigger"></a>
+## Fire-and-forget trigger + workflow-owned observation
+
+Invariant: the trigger child returns immediately; the workflow owns observation and verdict — never trust the child's self-report.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="publish-attempt-ledger"></a>
+## Durable publish-attempt ledger
+
+Invariant: every trigger outcome is recorded in the durable ledger while the trigger is in flight; the receipt poll reads the ledger, not the child's claims.
+
+Applies to: standard, bugfix, chore.
+
+```
+// 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.
+```
+
+<a id="pre-trigger-baseline"></a>
+## Pre-trigger build-state baseline
+
+Invariant: snapshot the build state before the trigger; a build whose agent_id differs from the baseline is attributed to our edit.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="deterministic-artifact-publish"></a>
+## Deterministic artifact publish
+
+Invariant: the work agent never publishes; the parent runs the deterministic publish script and stamps the result.
+
+Applies to: standard.
+
+```
+      // 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).
+      // QA's provenance check enforces the stamp mechanically.
+```
+
+Applies to: bugfix.
+
+```
+      // 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).
+      // QA's provenance check enforces the stamp mechanically.
+```
+
+Applies to: chore.
+
+```
+      // 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.
+```
+
+
+<a id="manual-inspector-fallback"></a>
+## Manual inspector fallback
+
+Invariant: the LLM-inspector path is manual-fallback only; the mechanical path is primary.
+
+Applies to: standard.
+
+```
+      // 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).
+      // QA's provenance check enforces the stamp mechanically.
+```
+
+Applies to: bugfix.
+
+```
+      // 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).
+      // QA's provenance check enforces the stamp mechanically.
+```
+
+Applies to: chore.
+
+```
+      // 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.
+```
+
+
+<a id="step-1c-no-stamp"></a>
+## STEP 1c: no provenance stamp
+
+Invariant: no provenance stamp in STEP 1c; the stamp cannot certify content.
+
+Applies to: standard.
+
+```
+            // 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.
+            // QA's provenance check enforces the stamp mechanically.
+            // An unverified publish fails loudly in QA instead of passing
+            // silently here.
+```
+
+Applies to: bugfix.
+
+```
+            // 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.
+            // QA's provenance check enforces the stamp mechanically.
+            // An unverified publish fails loudly in QA instead of passing
+            // silently here.
+```
+
+Applies to: chore.
+
+```
+            // 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.
+```
+
+
+<a id="artifact-inspect-removed"></a>
+## artifact_inspect removed by platform
+
+Invariant: artifact_inspect was removed by the platform 2026-09-14; the parent verifies content directly.
+
+Applies to: standard.
+
+```
+            // 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.
+            // QA's provenance check enforces the stamp mechanically.
+            // An unverified publish fails loudly in QA instead of passing
+            // silently here.
+```
+
+Applies to: bugfix.
+
+```
+            // 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.
+            // QA's provenance check enforces the stamp mechanically.
+            // An unverified publish fails loudly in QA instead of passing
+            // silently here.
+```
+
+Applies to: chore.
+
+```
+            // 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.
+```
+
+
+<a id="audit-dir-fallback"></a>
+## STEP 1b durable audit-dir fallback
+
+Invariant: the audit-dir fallback uses the poll's own observations, not just its final verdict.
+
+Applies to: standard, bugfix, chore.
+
+```
+            // STEP 1b durable audit-dir fallback (2026-09-15, task aadeccc3):
+            // the poll above only observes IN-FLIGHT builds. A build that
+            // finished between the receipt capture and the poll's first check
+            // 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). Diff the audit-dir
+            // listing against the pre-trigger snapshot: a timestamped dir
+            // that appeared during the attempt window is evidence a build
+            // completed. Attribution is by window, not by build identity:
+            // the poll's saw_stranger signal only catches stranger builds in
+            // flight AT a check — a stranger that finished entirely inside
+            // the window is indistinguishable, so any observed stranger
+            // blocks attribution and the outcome stays unknown. This never
+            // re-issues the edit and never stamps provenance — ok=true only
+            // routes to the parent's independent content read-back, which
+            // remains the real verification.
+            //
+            // The poll end-state is read from the poll's own observations,
+            // not from build_done alone: a build in flight at the last check
+            // means the budget was shorter than the latency (or the build is
+            // stuck) — NOT that no build ever started; nothing observed at
+            // any check is the never-started signal.
+```
+
+<a id="applied-report-gone"></a>
+## The builder's applied report is gone
+
+Invariant: applied_report stays "missing-report" on issued triggers; null on pre-trigger/unattributed parks.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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).
+```
+
+<a id="h2-immediate-no-receipt"></a>
+## H2 verdict-first: immediate no-receipt fallback
+
+Invariant: with durable audit evidence but no receipt agent_id, read the build report now and decide the verdict once via decidePublishVerdict — never poll blind on a null receipt.
+
+Applies to: standard, bugfix, chore.
+
+```
+            // (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, 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.
+```
+
+<a id="h2-verdict-dispatch"></a>
+## H2 verdict-first: verdict dispatch
+
+Invariant: the verdict is decided exactly once; landed bypasses the receipt poll; an explicit publishFailure is preserved verbatim through post-deploy; otherwise the poll requires a real receipt (null-safe assertion records UNKNOWN and continues to STEP 2).
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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
+        // at the park site above). A later run or human matches commit hash +
+        // attempt key against the builder's eventual completion.
+        // (2026-09-16) The trigger is fire-and-forget: the observation above
+        // 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.
+        // (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.
+```
+
+Root cause, fixed 2026-09-18: the immediate-landed path set
+`skipReceiptPoll=true`, so the poll gate
+`if (rebuildTrigger.edit_started && !skipReceiptPoll)` evaluated false —
+and the code fell into an `else` the author had marked "Unreachable",
+parking with 'not attributed' even though `publishBuildLanded` was already
+true. The verdict the evidence had already set was overwritten by a branch
+that claimed it couldn't happen. The fix decides the verdict exactly once
+(above) and dispatches on it; the old "Unreachable" else is now a loud
+defensive assertion that records UNKNOWN and continues to STEP 2 — it never
+parks early and never polls blind.
+
+<a id="diff-transport"></a>
+## Publish diff transport (file-backed)
+
+Invariant: the diff travels git -> file -> deterministic script summary; the LLM never carries diff bytes; the compute script is pinned.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="chunk-containment"></a>
+## Poll-chunk exception containment
+
+Invariant: a hung or failed chunk is inconclusive, never terminal — record it and continue; fail-closed still applies after chunk 3 and the fallback are exhausted.
+
+Applies to: standard, bugfix, chore.
+
+```
+              // 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.
+```
+
+<a id="poll-accumulators"></a>
+## STEP 1b poll-signal accumulators
+
+Invariant: the poll's observations (saw-our-build, saw-stranger, last check) are OR-ed across all three chunks so a signal seen in any chunk survives the chunk boundary.
+
+Applies to: standard, bugfix, chore.
+
+```
+          // STEP 1b poll-signal accumulators (2026-09-15, task aadeccc3):
+          // the durable audit-dir fallback below needs the poll's own
+          // observations, not just its final verdict — whether our build was
+          // ever seen, whether a stranger's build was ever in flight, and
+          // what the last check observed. OR-ed across all three chunks so
+          // a signal seen in any chunk survives the chunk boundary.
+```
+
+<a id="no-evidence-unknown"></a>
+## No-evidence unknown (H2 verdict-first)
+
+Invariant: no attributable build and no durable evidence proves nothing — verdict UNKNOWN via decidePublishVerdict, recorded in the ledger, fall through to post-deploy; never poll blind on a null receipt.
+
+Applies to: standard, bugfix, chore.
+
+```
+            // No attributable build and no durable evidence — but that proves
+            // nothing (a fast-completing build can finish between polls, or
+            // the checks themselves failed). Verdict UNKNOWN via the same
+            // mapping: record it in the ledger and fall through to
+            // post-deploy. No retry: re-issuing the edit here duplicated it
+            // on 2026-09-12. Never poll blind on a null receipt.
+```
+
+<a id="explicit-refusal"></a>
+## Explicit artifact refusal
+
+Invariant: ARTIFACT_EDIT_REFUSED is conclusive negative evidence -> park rejected, skip polling; a missing/unparseable signal is NOT a refusal (stays unknown fail-closed).
+
+Applies to: standard, bugfix, chore.
+
+```
+          // 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.
+```
+
+<a id="refusal-signal"></a>
+## Explicit artifact refusal (signal format)
+
+Invariant: a refusal is conclusive negative evidence; the signal must be the ENTIRE trimmed turn output — a child quoting instructions back in prose degrades to unknown fail-closed.
+
+Applies to: standard, bugfix, chore.
+
+```
+// 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).
+```
+
+<a id="provenance-refresh"></a>
+## Provenance refresh for self-publishes
+
+Invariant: after a verified landed publish, refresh the provenance record's crew_release to the now-live release identity, preserving the existing source_commit.
+
+Applies to: standard, bugfix, chore.
+
+```
+      // 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).
+```
+
+<a id="parent-owned-verification"></a>
+## Publish content verification — parent-owned
+
+Invariant: the parent owns content verification (docs/publish-verification.md); a skipped or failed publish has nothing to verify.
+
+Applies to: standard.
+
+```
+  // 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. QA's
+  // provenance check enforces the stamp — an unverified publish fails loudly
+  // there instead of passing silently here.
+  // 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.
+```
+
+Applies to: bugfix.
+
+```
+  // 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. QA's
+  // provenance check enforces the stamp — an unverified publish fails loudly
+  // there instead of passing silently here.
+  // 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.
+```
+
+Applies to: chore.
+
+```
+  // 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.
+```
+
+
+<a id="already-merged-corrective"></a>
+## Already-merged corrective
+
+Invariant: when Review rejects an empty branch but the work is already on main (workflow-verified sha), Wren must declare it — not re-implement or re-commit already-landed work. Scoped to the empty-branch rejection.
+
+Applies to: standard, bugfix, chore.
+
+```
+    // Already-merged corrective (room #16 blocker 11): when Review rejected
+    // an empty branch but the work is already on main (the workflow verified
+    // the sha), Wren must declare it — not re-implement or re-commit
+    // already-landed work. Scoped to the empty-branch rejection; any other
+    // rejection already carries its own specific notes.
+```
+
+<a id="merge-record-helpers"></a>
+## Merge-record helpers
+
+Invariant: the integrate step records the exact merged commit in $CREW_HOME/.merge-records/<task_id> so a re-dispatched run can verify a landed merge and publish it even after the branch was reclaimed under an expired lease. All pure — no I/O, no clock.
+
+Applies to: standard, bugfix, chore.
+
+```
+// Merge-record helpers (merge-lease fix, 2026-09-12): the integrate step
+// records the exact merged commit in $CREW_HOME/.merge-records/<task_id>,
+// so a re-dispatched run can verify a landed merge and publish it even
+// after the branch was reclaimed under an expired lease. All pure — no I/O,
+// no clock. Byte-identical in standard.js, bugfix.js, chore.js.
+```
+
+<a id="publish-diff-base"></a>
+## Publish diff base (BASE..HEAD)
+
+Invariant: 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 fix. Empty tree only for a genuine first publish.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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).
+```
+
+<a id="attribution-limitation"></a>
+## Attribution timing limitation
+
+Invariant: attribution is timing-based — a stranger's build starting inside the trigger window is indistinguishable and would be misattributed; the consequence is bounded because the parent's mechanical content read-back certifies the exact commit's content. Timing narrows the candidate; content decides.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="read-back-request"></a>
+## Publish read-back request (currently unavailable)
+
+Invariant: no agent-callable read-back tool exists; verification parks at 'verification-requested'; independent read-back cannot be fabricated from the diff.
+
+Applies to: standard.
+
+```
+// Publish read-back request (agent path currently unavailable): the
+// verbatim_request the parent protocol (docs/publish-verification.md) would
+// hand to an independent read-back tool after the artifact build lands.
+// artifact_inspect was removed by the platform (2026-09-14);
+// artifact.inspect is malfunction diagnosis, not a substitute — so no
+// agent-callable read-back tool exists and this LLM-inspector request
+// cannot currently be issued. The primary sensor is now the deterministic
+// lib/readback-disk.js (reads the on-disk tree the artifact is served
+// from); this request builder is retained only as the manual fallback.
+// Pure function — no I/O, no clock. The request carries the merged diff as the expected change and asks
+// for an independent read of the artifact's actual source: for each file, the
+// exact current text of the changed regions plus a per-line present/absent
+// finding. Until a read-back path exists, the parent cannot independently
+// confirm content and verification parks at "publish: verification-requested"
+// (see docs/publish-verification.md). This preserves the circularity break
+// that hollowed canary run 8 (2026-09-11): the old verifyAppliedChanges
+// compared the builder's applied-report against the diff the report was
+// derived from — a fabricated report passed by construction. The report
+// itself is gone now (2026-09-16 fire-and-forget trigger). Independent
+// read-back cannot be
+// fabricated from the diff;
+// it must match the artifact's real content.
+```
+
+Applies to: bugfix.
+
+```
+// Publish read-back request (currently unavailable): the verbatim_request
+// the parent protocol (docs/publish-verification.md) would hand to an
+// independent read-back tool after the artifact build lands. artifact_inspect
+// was removed by the platform (2026-09-14); artifact.inspect is malfunction
+// diagnosis, not a substitute — so no agent-callable read-back tool exists
+// and this request cannot currently be issued. Pure function — no I/O, no
+// clock. The request carries the merged diff as the expected change and asks
+// for an independent read of the artifact's actual source: for each file, the
+// exact current text of the changed regions plus a per-line present/absent
+// finding. Until a read-back path exists, the parent cannot independently
+// confirm content and verification parks at "publish: verification-requested"
+// (see docs/publish-verification.md). This preserves the circularity break
+// that hollowed canary run 8 (2026-09-11): the old verifyAppliedChanges
+// compared the builder's applied-report against the diff the report was
+// derived from — a fabricated report passed by construction. The report
+// itself is gone now (2026-09-16 fire-and-forget trigger). Independent
+// read-back cannot be
+// fabricated from the diff; it must match the artifact's real content.
+```
+
+Applies to: chore.
+
+```
+// Publish read-back request (currently unavailable): the verbatim_request
+// the parent protocol (docs/publish-verification.md) would hand to an
+// independent read-back tool after the artifact build lands. artifact_inspect
+// was removed by the platform (2026-09-14); artifact.inspect is malfunction
+// diagnosis, not a substitute — so no agent-callable read-back tool exists
+// and this request cannot currently be issued. Pure function — no I/O, no
+// clock. The request carries the merged diff as the expected change and asks
+// for an independent read of the artifact's actual source: for each file, the
+// exact current text of the changed regions plus a per-line present/absent
+// finding. Until a read-back path exists, the parent cannot independently
+// confirm content and verification parks at "publish: verification-requested"
+// (see docs/publish-verification.md). This preserves the circularity break
+// that hollowed canary run 8 (2026-09-11): the old verifyAppliedChanges
+// compared the builder's applied-report against the diff the report was
+// derived from — a fabricated report passed by construction. The report
+// itself is gone now (2026-09-16 fire-and-forget trigger). Independent
+// read-back cannot be
+// fabricated from the diff; it must match the artifact's real content.
+```
+
+
+<a id="step-05-target-check"></a>
+## STEP 0.5: artifact target existence check
+
+Invariant: assert the artifact target exists before any trigger; a missing target is conclusive negative evidence -> park rejected; an inconclusive check is fail-closed unknown.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // STEP 0.5 (mechanical, room #16 blocker 10): assert the artifact
+        // target exists before any artifact_status / artifact_edit call. The
+        // project was classified as an artifact surface (deploy_slug set),
+        // but setup never provisioned the artifact — Publish then entered
+        // the trigger path against a slug with no on-disk target and the
+        // edit failed opaquely ("web artifact <slug> was not found on
+        // disk"), which the ledger could only record as unknown. A missing
+        // target is conclusive negative evidence: the edit provably did NOT
+        // go through, so this parks rejected (not unknown) with the actual
+        // missing path — no trigger issued, no blind retry, no observation
+        // polling. The check is a pure filesystem stat; the path is
+        // workflow-computed, never agent prose. An inconclusive check
+        // (throw / unparseable signal) is fail-closed unknown: without
+        // proof the target exists, no edit is issued. The slug is
+        // interpolated into a shell command — a slug outside [a-zA-Z0-9_-]
+        // (e.g. from a hand-edited space.json) is treated as inconclusive
+        // rather than risking shell injection.
+```
+
+<a id="no-builder-report"></a>
+## No builder report (fire-and-forget)
+
+Invariant: the fire-and-forget trigger carries no JSON contract; the builder's old self-report was circular by construction with a demonstrated false-negative mode.
+
+Applies to: standard, bugfix, chore.
+
+```
+          // (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
+          // self-report was circular by construction (canary run 8) with a
+          // demonstrated false-negative mode (task 23ca8f3f, 2026-09-12:
+          // applied:[] for a diff the builder had applied). The flow
+          // proceeds to the build poll regardless; real verification is the
+          // parent's independent read-back (docs/publish-verification.md)
+          // before the provenance stamp.
+```
+
+<a id="durable-evidence-snapshot"></a>
+## Durable-evidence snapshot
+
+Invariant: snapshot the audit-dir listing BEFORE the trigger; the fallback diffs before/after; if the snapshot fails, both fallback comparisons are disabled.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="already-merged-hydration"></a>
+## Already-merged hydration
+
+Invariant: when the run did not execute Build itself, recover the workflow-verified sha; the structured session field is read FIRST, the notes line is only a fallback (session notes are hard-capped at 3000 chars).
+
+Applies to: standard, bugfix, chore.
+
+```
+    // 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.
+```
+
+<a id="already-merged-declaration"></a>
+## Already-merged declaration
+
+Invariant: when the builder correctly makes no commit because the deliverable is already on main, it declares repo_diff: none (already-merged: <sha>) naming the main commit that carries the work.
+
+Applies to: standard, bugfix, chore.
+
+```
+// 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.
+```
+
+<a id="step1-builder-source"></a>
+## STEP 1: builder source tree
+
+Invariant: the builder's source tree is NOT the crew's repo; the merge diff is embedded in the edit request; the workflow verifies the report matches the diff BEFORE stamping provenance.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="verification-park"></a>
+## Verification park
+
+Invariant: the build landed but provenance is unstamped until parent verification.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // 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.
+```
+
+<a id="pretrigger-baseline"></a>
+## Pre-trigger baseline
+
+Invariant: a tiny schema'd baseline is captured before the trigger.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="agent-id-attribution"></a>
+## Agent ID attribution
+
+Invariant: the artifact build's agent_id is attributed to the edit call.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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.
+```
+
+<a id="hung-chunk"></a>
+## Hung chunk
+
+Invariant: a hung or failed chunk is inconclusive, never terminal.
+
+Applies to: standard, bugfix, chore.
+
+```
+              // 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.
+```
+
+<a id="no-attributable-build"></a>
+## No attributable build
+
+Invariant: no attributable build and no durable evidence means no publish.
+
+Applies to: standard, bugfix, chore.
+
+```
+            // No attributable build and no durable evidence — but that proves
+            // nothing (a fast-completing build can finish between polls, or
+            // the checks themselves failed). Verdict UNKNOWN via the same
+            // mapping: record it in the ledger and fall through to
+            // post-deploy. No retry: re-issuing the edit here duplicated it
+            // on 2026-09-12. Never poll blind on a null receipt.
+```
+
+<a id="already-merged"></a>
+## Already-merged attestation
+
+Invariant: when the Build gate verifies already-merged, attestation is recorded.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // 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.
+```
+
+<a id="explicit-refusal-16"></a>
+## Explicit refusal
+
+Invariant: the child must explicitly refuse artifact work.
+
+Applies to: standard, bugfix, chore.
+
+```
+          // 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.
+```
+
+<a id="publish-verify"></a>
+## Publish verification
+
+Invariant: the agent cannot verify publish; the parent does.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // 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.
+```
+
+<a id="integrate-verify"></a>
+## Integrate verification
+
+Invariant: the agent cannot verify integrate mechanically; the workflow checks the diff.
+
+Applies to: standard, bugfix, chore.
+
+```
+  // 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.
+```
+
+<a id="already-merged-idem"></a>
+## Already-merged idempotency
+
+Invariant: an already-merged repo_diff is idempotent; no rebuild.
+
+Applies to: standard, bugfix, chore.
+
+```
+    // 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.
+```
+
+<a id="ledger-trigger"></a>
+## Ledger trigger
+
+Invariant: record the trigger in the durable ledger.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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
+        // at the park site above). A later run or human matches commit hash +
+        // attempt key against the builder's eventual completion.
+        // (2026-09-16) The trigger is fire-and-forget: the observation above
+        // 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.
+        // (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.
+```
+
+<a id="trigger-await"></a>
+## Trigger await
+
+Invariant: the artifact_edit call is awaited.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // 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).
+```
+
+<a id="diff-computation"></a>
+## Diff computation
+
+Invariant: the diff is computed, the rebuild is triggered, and the report is verified.
+
+Applies to: standard, bugfix, chore.
+
+```
+        // (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).
+```
+
+<a id="already-merged-hydra"></a>
+## Already-merged hydration
+
+Invariant: when this run did not execute, hydration uses the existing merge.
+
+Applies to: standard, bugfix, chore.
+
+```
+    // 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.
+```
+
+<a id="already-merged-idem2"></a>
+## Already-merged idempotency
+
+Invariant: idempotency for already-merged tasks.
+
+Applies to: standard, bugfix, chore.
+
+```
+// 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.
+```