muse-crew 0.14.4 → 0.14.6

package/docs/publish-verification.md

@@ -1,453 +1,156 @@
-# Publish content verification — parent protocol
+# Publish acknowledgement — the version protocol (0.14.6)
 
-> **UNBLOCKED (2026-09-15):** the platform's `artifact_inspect` is still
-> gone, but no platform tool is needed anymore. The platform's artifact
-> edits land in its on-disk working copy of the artifact source
-> (`~/workspace/ts-spaces/<slug>/` — verified empirically 2026-09-15:
-> added lines present, removed lines absent across real platform commits),
-> so `lib/readback-disk.js` performs the read-back deterministically: it
-> reads the working copy and emits the exact machine-readable findings
-> block `lib/verify-publish.js` already parses. No LLM, no async handoff,
-> no prose to parse. The verifier is unchanged — the sensor changed, the
-> judge didn't.
+> **Eric's publication contract (2026-09-20):** "If we hear that the artifact
+> acknowledges our version, that's it. We don't verify against content."
 >
-> Authority boundary: the sensor reads the platform's working copy — the
-> tree the hosted artifact is built/served from. A working copy that is
-> stale relative to a just-applied edit yields honest ABSENT findings and
-> the verifier fails CLOSED (parked). Staleness can only park a task,
-> never stamp provenance.
+> The content-verification architecture (read-back, `verify-publish.js`,
+> the unknown-recovery classifier) is RETIRED. Exact per-attempt version
+> acknowledgement is the SOLE positive completion criterion. Provenance
+> certifies that the issuance request was acknowledged — never byte
+> equality with the staged diff.
 
-Provenance is the artifact's claim that its live content came from a specific
-repo commit. The workflow never stamps it. This document is the parent-side
-protocol. Deterministic code detects, claims, and certifies; the tick worker
-(the live root agent) is only the async ferry for the inspection.
+## The version
 
-## Why the parent stamps
-
-The builder's `applied` report is derived from the diff the workflow carries
-to it — so `verifyAppliedChanges` (report vs. diff) is circular: a fabricated
-report passes by construction. Canary run 8 (2026-09-11) proved it: the build
-was hollow, the report matched the diff, the workflow stamped provenance, and
-all eight phases went green on stale content. The old post-hoc check
-(get-provenance vs. HEAD) only verified the stamp, not the content.
-
-Task `23ca8f3f` (2026-09-12, canary `orchestra-dashboard-2`) proved the report
-is unreliable in the other direction too: the builder applied the one-line
-diff, the applied-report came back `applied: []`, and the workflow's old
-applied-report gate parked the task fail-closed as unverified — on a publish
-that had actually landed. A later independent read-back of the live artifact
-showed the change present.
-
-The rule: **the builder's applied report is never a verification signal, in
-either direction.** A matching report certifies nothing (it is derived from
-the carried diff — circular by construction, canary run 8). A mismatching or
-empty report blocks nothing (false-negative mode demonstrated by `23ca8f3f`).
-The workflow dropped the report entirely on 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 its prose ("workflow agent output was not JSON"), parking a task whose
-edit may have gone through. The trigger is now awaited and scanned for a
-single explicit refusal signal — `ARTIFACT_EDIT_REFUSED: <text>` as the
-entire trimmed turn output — and nothing else is consumed from the return.
-An exact refusal is conclusive negative evidence (parks `rejected`, skips
-observation polling); any other output (including prose quoting the signal)
-is inconclusive and follows the existing fail-closed observation path.
-`applied_report` is `missing-report` on ledger lines for issued triggers
-(pre-trigger parks and unattributed-unknown parks write null — no trigger
-was observed, so there is nothing to report). The
-parent ignores the (absent) report entirely when deciding whether to stamp.
-
-The contract is split on purpose:
-
-- **Workflow-owned:** carrying the merged diff to the builder, attributing
-  the edit itself (fire-and-forget trigger — no builder report — via
-  pre-trigger toolcheck, pre-trigger build-state baseline, and post-trigger
-  build-state diff), the build-completion poll, post-deploy cleanup,
-  recording the Publish session completed, and parking with `publish:
-  verification-requested <commit>` instead of stamping. The workflow does NOT trigger the read-back inspection — an
-  async inspection triggered from inside a workflow run delivers its result
-  to the root agent, never back into the run, so a workflow-side trigger is
-  an orphan the verifier cannot consume. The parent triggers the one
-  inspection it can actually receive.
-- **Parent-owned (deterministic code, ferried by the tick worker):**
-  scanning for verification-pending parks, atomically claiming them,
-  building the read-back request, triggering the inspection, waiting for the
-  result, comparing it mechanically against the merged diff, checking
-  build-ID correlation and supersession, stamping provenance only on a
-  match, reading the stamp back exactly, logging the terminal verdict, and
-  re-queuing the task to `in_progress`.
-
-No artifact publish completes without parent-stamped provenance. A missing or
-mismatched read-back never stamps.
-
-## The carried diff: BASE..HEAD from the stamped provenance
-
-The "merged diff" the workflow carries is `BASE..HEAD` where `BASE` is the
-previously-stamped provenance `source_commit` — the artifact's actual
-content — never `HEAD^1`. (Task `0c53af4e`, 2026-09-14: a push-time
-reconcile merge put the task's own changes behind an intermediate merge, so
-`HEAD^1..HEAD` carried only the reconcile delta and silently omitted the
-task's fix; the artifact built without it. The stamped base is the only
-ground truth for what the artifact already has; `BASE..HEAD` is the complete
-unpublished delta.)
-
-The workflow reads the base via `get-provenance` before computing the diff,
-and the computation is guarded mechanically:
-
-- Empty base (no provenance stamped) → the empty tree
-  `4b825dc642cb6eb9a060e54bf8d69288fbee4904`, and only then. A present but
-  malformed base SHA parks fail-closed.
-- `git merge-base --is-ancestor BASE HEAD` must pass; a non-ancestor base
-  parks fail-closed (the stamped provenance must lead to the integrated
-  commit, otherwise the artifact has drifted or the stamp is wrong).
-- The agent-reported base must equal the stamped base; a mismatch parks.
-- The expected base content hashes (pre-publish observation) are computed at
-  the stamped base, not the merge parent — the artifact's tree should match
-  the stamp, and the observation is only meaningful against it.
-
-The parent verifier (`lib/verify-publish.js`, `--base`) and the read-back
-request builder (`lib/build-readback-request.js`, `--base`) use the identical
-base: the previously-stamped provenance, or the empty tree for a genuine
-first publish. Request builder and verifier never disagree on the base.
-
-**Diff transport (room #14, 2026-09-17):** the diff is computed by the
-deterministic `lib/compute-publish-diff.js` (pinned per-run alongside the
-other lifecycle files), which writes the raw diff bytes to
-`$CREW_HOME/.publish-diffs/<taskId>[-rN].diff` and returns only a small JSON
-summary (`sha256`, `changed_lines` = added+removed, `has_binary`,
-`has_rename`). The LLM never carries diff bytes — an earlier shape asked an
-agent to return the raw diff as a JSON string field, and the JSON ferry
-dropped a valid 700-line diff ("Publish diff parsed to zero files"). The
-trigger agent verifies the file with `sha256sum` before any `artifact_edit`
-call and pastes the verified content into the edit. The 200 changed-line
-budget counts added+removed lines from the summary, never raw diff output
-lines (context lines inflated the old count ~2x).
-
-## The shape: code detects, the tick ferries, code certifies
-
-A standalone verification workflow cannot work with the async inspection
-model: async inspection results are delivered to the root agent of the
-agent tree, never into a workflow run — so a verify workflow would wait
-forever for a result it can never receive. The tick worker IS the live
-root agent, so it is the only component that can both trigger an
-inspection and receive its result. (The inspection tool itself,
-`artifact_inspect`, was removed by the platform 2026-09-14 — see the
-BLOCKED notice at the top.)
-
-But the tick worker is a generalist LLM, and the certification decision is
-safety-critical: a misjudged "match" stamps unverified content, and nothing
-downstream can ever detect it (QA checks the stamp, not the content). So the
-LLM never judges. The division:
-
-1. **Scan (code):** `scan-verification-pending` finds parked tasks whose
-   latest parent note is `publish: verification-requested`, with no terminal
-   verdict and no unexpired claim. It atomically claims each one by logging
-   `publish: verification-claimed <expiry>` (1-hour lease) — the task stays
-   parked, so the dispatcher never dispatches QA mid-verification, and a
-   second tick cannot start a duplicate verification. It also reconciles the
-   verified-but-still-parked gap (verdict recorded, re-queue lost to a crash)
-   back to `in_progress`.
-2. **Build (code):** `build-readback-request.js` builds the EXACT inspection
-   request from the publish delta — `git diff <base> <commit>` where
-   `<base>` is the previously-stamped provenance `source_commit` (or the
-   empty tree for a first publish). The tick never hand-writes the request,
-   and never uses `commit^1` as the base: push-time reconcile merges put
-   the task's own changes behind an intermediate merge, so `commit^1`
-   covers only the reconcile delta (2026-09-14, task `0c53af4e`).
-3. **Ferry (tick worker):** runs the deterministic sensor
-   `lib/readback-disk.js` (`--repo-path`, `--commit`, `--base` — the same
-   base as step 2 — `--slug` from the project's `deploy_slug`, `--task-id`)
-   and saves its stdout to the result file. The sensor exits 0 only when it
-   actually read the working copy; on a non-zero exit the tick must NOT
-   save stdout — log `publish: verification-procedural-error <commit>
-   <stderr>` and leave the task parked for the next tick to retry (a sensor
-   failure is procedural — the read could not be performed — not a content
-   verdict). `build-readback-request.js` is retained for the manual LLM
-   fallback below.
-4. **Certify (code):** `verify-publish.js` parses the inspector's
-   machine-readable findings block, compares every added/removed diff line
-   against the reported present/absent verdicts, checks build-ID correlation
-   and supersession via git, and only then stamps provenance, reads the
-   stamp back exactly, logs the terminal verdict, and re-queues to
-   `in_progress`. Unparseable findings, mismatches, supersession, and stamp
-   failures all fail CLOSED with a terminal `publish: verification-failed`
-   verdict — never a stamp. The terminal vocabulary is a closed registry in
-   `lib/publish-note-vocabulary.js` (D7, 2026-09-19): `scan-publish-unknown`
-   skips a recognized terminal note as terminal with its meaning named (never
-   as `unrecognized-publish-note`), and `verify-publish.js`'s `terminal()`
-   asserts its emitted verb is in the registry before writing.
-   `tests/publish-note-vocabulary.test.js` closes the enum structurally:
-   every `publish: <verb>` literal in lib/ must be declared in the terminal
-   registry or the pinned transitional set, so no future terminal verb ships
-   unrecognized.
-   - **Envelope:** the tick saves the COMPLETE handoff — the full prose
-     report AND the full JSON result, both verbatim (raw prose, JSON, or
-     both concatenated are all accepted). Observed 2026-09-14: the
-     platform's JSON envelope carries NO machine-readable findings
-     block; the block lives in the prose handoff. The verifier locates
-     the findings block in prose text and JSON string values (including
-     double-encoded ones) and prefers the block whose file paths cover
-     the expected diff — an echoed request template or stray prose never
-     outranks the real block. No covering block => `unreadable-result`,
-     fail closed. Saving JSON-only strands verification.
-     fail closed.
-   - **Release identity:** `scan-verification-pending` resolves
-     `crew_release` through the crew home's `current` symlink (the immutable
-     active release) and cross-checks it against the running code's own
-     realpath. Unresolvable or disputed => the scan throws fail-closed
-     BEFORE writing any claim — provenance is never stamped `unknown`, and
-     a stale cron body running an old release cannot certify.
-
-The tick body (seed/cron-body-template.md, step 4.5) wires these together.
-The publisher never certifies itself, and the LLM never makes the
-safety-critical match decision.
-
-## The park
-
-When the artifact build lands, the workflow parks the task with the message:
+Each publish attempt carries a deterministic version:
 
 ```
-publish: verification-requested <commit> (build <agent_id|agent_id unobserved>) — artifact build landed, post-deploy
-finalized, provenance NOT stamped. Parent: run docs/publish-verification.md.
+sha256("publish-version:v1:" + task_id + ":" + commit + ":" + publish_attempt)
 ```
 
-The parked message is stored as `Parked: publish: verification-requested
-<commit> …`. Match on the contained exact string
-`publish: verification-requested`. The `<commit>` is the merged commit whose
-content must be verified. The `(build …)` suffix carries the
-`build.agent_id` the workflow observed for this publish attempt (the
-artifact system's in-flight build correlation ID — the parent uses it for the
-build-ID correlation in step 4b); `agent_id unobserved` means the edit was
-accepted but the workflow never correlated it to a builder run. The merge
-lock is already released (post-deploy ran before the park), so the parked
-task holds no resources.
-
-## Parent verification procedure
-
-The automated path is the tick body's step 4.5 (scan → build → ferry →
-verify). The manual fallback below is the same protocol run by hand; it
-exists for when the artifact namespace is unavailable to the tick worker.
-
-For a task parked with `publish: verification-requested <commit>`:
-
-1. **Resolve the project.** Read the task's project via the Crew API
-   (`get-project`); you need `repo_path` (the git checkout) and the artifact
-   slug (the project's publish target).
-2. **Expected change.** The publish delta is `git diff <base> <commit>`
-   in `repo_path`, where `<base>` is the previously-stamped provenance
-   `source_commit` for this project (read it via
-   `get-provenance --json '{"project_id":"<id>"}'` — provenance is
-   per-project; without `project_id` the call exits 2; use the empty-tree sha
-   `4b825dc642cb6eb9a060e54bf8d69288fbee4904` when no provenance is
-   stamped yet — a first publish). Never use `commit^1` as the base and
-   never take the expected change from the builder's report: push-time
-   reconcile merges violate the `merge^1 == previously-published tree`
-   invariant, so `commit^1..commit` can omit the task's own fix
-   (2026-09-14, task `0c53af4e`).
-3. **Actual content.** Run `lib/readback-disk.js` with `--repo-path`,
-   `--commit`, `--base` (the same base as step 2), `--slug`, and
-   `--task-id`, and save its stdout to the result file — this is the
-   deterministic read-back; it emits the machine-readable findings block
-   directly. (LLM fallback: if the disk working copy is unavailable, call
-   the artifact inspector with `repair_authorized: false` and the
-   `verbatim_request` built by `lib/build-readback-request.js`, passing
-   `--build-agent-id` from the park message's `(build …)` suffix when it
-   is not `agent_id unobserved`.) The findings block grammar:
-   ```
-   FILE: <path>
-   ADDED: <exact added line> :: PRESENT|ABSENT
-   REMOVED: <exact removed line> :: PRESENT|ABSENT
-   END_FILE
-   ```
-   If no read-back can be obtained at all, log
-   `publish: verification-blocked <commit> <reason>` and leave the task
-   parked for human attention. Never stamp without a read-back.
-4. **Compare mechanically.** For every added (`+`) line in the diff, the
-   read-back's machine-readable block must report it PRESENT in the
-   artifact's current source. For every removed (`-`) line, it must report
-   it ABSENT — with one mechanical exemption: a removed line that also
-   occurs verbatim in untouched code has zero discriminating power (its
-   presence proves nothing about whether the old block survived), so the
-   verifier exempts it instead of failing a good publish. The exemption is
-   computed, never judged: a removed line L in file F is exempt iff L
-   occurs in F's old tree (at `<base>`) strictly more times than the diff
-   removes it (2026-09-15, task `00bca4b8` — a valid publish parked because
-   two removed lines occurred identically in the untouched WorkflowSteps
-   component). The comparison is computed by `lib/verify-publish.js` —
-   never by eyeballing prose. A missing or malformed findings block fails
-   closed as `unreadable-result`, never as a pass.
-4b. **Build-ID correlation.** The read-back may have inspected a different
-   build's output than this publish attempt's:
-   1. **Expected** = the agent_id in the park message's `(build …)` suffix.
-      If the suffix says `agent_id unobserved`, look up the workflow's
-      durable publish ledger at `$CREW_HOME/.publish-ledger/<slug>.jsonl`
-      for the `submitted` entries with this `<commit>`: the OLDEST is the
-      trigger issuance (its `agent_id` is always null — the trigger instant,
-      not a build identity); the receipt-bearing `submitted`, if present, is
-      a LATER entry carrying the observed `agent_id` — use that one here
-      (if it is absent or null, this step is vacuous).
-   2. **Live** = whether the expected agent_id appears anywhere in the
-      read-back result (the live artifact status exposes no durable
-      agent_id — only an in-flight correlation ID that expires with the
-      publish attempt, so absence is the common case, not evidence of a
-      mismatch).
-   3. If expected is non-null and the read-back positively reports a
-      DIFFERENT live build identity for this attempt's output, log
-      `publish: build-mismatch <commit> expected <expected> observed
-      <live>`, stay parked, never stamp, never re-queue.
-   4. Otherwise the content match from step 4 decides — the stamp certifies
-      CONTENT, not the builder's identity. Log the correlation outcome
-      (correlated / unobserved) in the `publish: verified` note.
-5. **Supersession check.** Before stamping, prove the inspected live
-   artifact still represents the commit being certified: `git rev-parse
-   HEAD` in `repo_path` must equal `<commit>`. If HEAD has moved (a later
-   Publish landed), the read-back is stale — log
-   `publish: superseded <commit> by <head>` and leave the task parked for
-   human attention. Never stamp a superseded commit.
-6. **Stamp, verify the stamp, then re-queue** (all in `lib/verify-publish.js`;
-   the manual equivalent):
-   - **Match** — stamp provenance with the Crew API CLI `set-provenance`
-     (the crew-owned store). Do NOT use the artifact's `setprovenance`
-     action — it writes a different, non-authoritative store that QA never
-     reads, so the stamp would be invisible to every gate:
-     `set-provenance --json '{"project_id":"<id>","source_commit":"<commit>","crew_release":"<release>","task_id":"<task>"}'`
-     (crew_release is the basename of the active release, e.g.
-     `pkg-0.7.10`). This is the full publish-verification stamp — it
-     records a verified publish. Do not confuse it with the
-     provenance *refresh* (re-pointing `crew_release` at the active
-     release after a crew upgrade without a new publish), which also goes
-     through `set-provenance` but keeps the existing `source_commit`.
-     Then read the stamp back with
-     `get-provenance --json '{"project_id":"<id>"}'`
-     and confirm source_commit, crew_release, and task_id match exactly
-     what was sent — a stamp that cannot be read back is not a stamp. Only
-     then log the task note event
-     `publish: verified <commit> (<inspection_id>)` and re-queue with
-     `update-task` → state `in_progress` (never `todo` — `todo`
-     restarts Triage and resets retry accounting). The dispatcher resumes
-     at QA from the completed Publish session (standard/bugfix); chore has
-     no QA — it proceeds to terminal completion. QA's provenance check
-     (standard/bugfix) enforces the stamp mechanically.
-   - **Mismatch** — do NOT stamp. Log the exact FAIL evidence with
-     `publish: content-mismatch <commit> <details>` (quote the observed
-     lines from the read-back) and leave the task parked. Never stamp
-     provenance on a mismatch; never re-queue a mismatched publish into
-     QA — QA would fail it and burn rework budget communicating a Publish
-     problem that is not QA's to solve. The task stays parked for human
-     attention; the loop does not retry the verification.
-   - **Stamp failure** — if `set-provenance` fails after a matched read-back,
-     log `publish: stamp-failed <commit> <reason>` and leave the task parked
-     for human attention. Never re-queue an unstamped-but-verified task into
-     QA — QA would fail it and burn rework budget on a stamping problem.
-
-## Crash recovery
-
-- **Tick dies before triggering the inspection:** the claim expires after
-  1 hour; the next scan re-claims and re-verifies from scratch. The stamp
-  is an idempotent upsert, so a duplicate verification cannot corrupt it.
-- **Tick dies after the inspection but before the stamp:** same as above —
-  the next scan re-runs the whole verification (new inspection, new
-  comparison). Wasteful but correct.
-- **Crash between stamp and re-queue:** the next scan sees
-  `publish: verified` on a still-parked task and reconciles it to
-  `in_progress`. Failure verdicts are never reconciled — they stay parked
-  for human attention.
-- **Two ticks verify concurrently:** impossible — the atomic claim means the
-  second scan sees the unexpired `publish: verification-claimed` note and
-  skips. The lease expiry bounds the damage if a claimer dies.
-
-## Unknown-outcome recovery (2026-09-14, Gate 1 Journey 3 attempt 7; fire-and-forget 2026-09-16)
-
-Attempt 7 parked at Publish with outcome `unknown`: the rebuild trigger's
-child failed structured closeout and the in-flight-only build-state poll
-could not see the completed build — even though the build HAD run (a fresh
-platform audit directory existed). 2026-09-16 (clean-room task `e2a8d9f8`)
-showed the failure is worse than a catchable throw: the runtime's
-JSON-candidate heuristic rejects the trigger call itself ("workflow agent
-output was not JSON") whenever the child returns prose, whether or not the
-edit went through. The trigger is therefore fire-and-forget — no schema, no
-consumed return value — and the workflow always attributes the edit itself.
-Two mechanisms close the gap.
-
-**1. Pre-trigger toolcheck + baseline.** Before the trigger, a tiny schema'd
-child proves the artifact tool namespace is available (one bounded retry on
-explicit negative evidence — the only safe retry on the publish path:
-without the tools the edit provably did not go through) and captures a
-pre-trigger build-state baseline. After the trigger, the workflow diffs the
-post-trigger build state against the baseline: a build whose `agent_id` is
-new relative to the baseline is this edit's receipt. The baseline build's
-`agent_id` is never substituted — a build already in flight at baseline
-predates the trigger and is never attributed to this edit.
-
-**2. Workflow-side durable evidence.** Before the rebuild trigger, the
-workflow snapshots the artifact's audit-directory listing
-(`~/workspace/ts-spaces/<slug>/audits/` — best-effort, never a gate). When
-no in-flight receipt was observed, it re-lists and diffs: a timestamped
-directory that appeared during the trigger window is positive evidence the
-edit went through and the build completed. The fallback never re-issues the
-edit, never stamps provenance, and only routes to the parent's independent
-content read-back. No new directory still parks `unknown` fail-closed. The
-ledger's `detail` line distinguishes the two confirmations: `… edit
-confirmed via durable audit evidence (new audit dir …)` vs `… build receipt
-captured by workflow-owned build-state observation (pre/post-trigger diff)`.
-
-The fallback's known limitation: audit directories are not attributed to
-tasks, so two concurrent publishes to the same artifact could cross-read.
-The consequence is bounded — the fallback only routes to the parent
-read-back, and the parent still certifies the exact commit's content
-mechanically (a wrong build's content fails closed as `publish:
-content-mismatch` / `publish: build-mismatch`, never stamps).
-
-**2. `resolve-publish-unknown` (Crew API).** For attempts already parked
-`unknown` before this fix: given a task parked with a latest ledger outcome
-of `unknown`, it derives the publish window (Integrate-completion event →
-unknown-outcome park event) and checks for a timestamped audit build inside
-that window. On evidence, it appends `unknown-resolved` to the ledger
-(never rewriting the original entry), writes `publish: unknown-resolved`
-and a mirrored `publish: verification-requested <commit>` note (the mirror
-is timestamped strictly later so the scan sees it as the latest), and leaves
-the task parked for the normal scan. Still-unknown cases stay parked:
-unparked task, non-`unknown` latest ledger outcome, missing commit, no audit
-build in the window, unobservable window, or an already-resolved attempt
-(idempotent).
-
-## Exact note-event prefixes
-
-Case-sensitive, exact-prefix matches — match on prefixes, never on English
-meaning:
-
-- `publish: verification-requested <commit>` — workflow park; contained in
-  the stored `Parked: …` message.
-- `publish: verification-claimed <ISO-expiry>` — parent scan; atomic claim
-  with lease. Not a verdict.
-- `publish: verified <commit> (<inspection_id>)` — parent, after stamping
-  AND reading the stamp back exactly; re-queued to `in_progress` (never
-  `todo`).
-- `publish: content-mismatch <commit> <details>` — parent; exact FAIL
-  evidence quoted; stays parked, never stamped, never re-queued to QA.
-- `publish: build-mismatch <commit> expected <expected> observed <live>` —
-  parent; the read-back positively identified a different build's output
-  (step 4b); stays parked, never stamped, never re-queued.
-- `publish: superseded <commit> by <head>` — parent; HEAD moved past the
-  commit; stays parked for human attention.
-- `publish: verification-blocked <commit> <reason>` — parent; no read-back
-  obtainable; stays parked for a human.
-- `publish: unknown-resolved <commit>` — recovery; durable build evidence
-  found inside the publish window for a previously-unknown attempt (see
-  "Unknown-outcome recovery"). The original `unknown` outcome is preserved;
-  the mirrored `verification-requested` note (written strictly later) is
-  what the scan claims.
-- `publish: stamp-failed <commit> <reason>` — parent; read-back matched but
-  the stamp call failed; stays parked for a human.
-- `publish: reconciled verified-but-parked -> in_progress` — parent scan;
-  the verified verdict was recorded but the re-queue was lost.
-
-## Workflow differences
-
-- **standard / bugfix:** after `publish: verified`, the dispatcher resumes
-  at QA from the completed Publish session. QA's provenance check enforces
-  the stamp mechanically — an unstamped publish fails loudly there.
-- **chore:** there is no QA phase. After `publish: verified` (stamp +
-  exact stamp read-back), the dispatcher proceeds to terminal completion.
-  The parent's stamp read-back is the final gate — no downstream phase
-  re-checks it.
+- `task_id` — the crew task
+- `commit` — the merge commit being published
+- `publish_attempt` — 1, 2, 3 (numeric; separate from the workflow's
+  string replay key `attempt`)
+
+`lib/compute-publish-diff.js --task-id <id> --attempt <n>` derives the version
+and synthesizes it into the staged diff as a `.crew-publish-version-<task_id>`
+new-file hunk. The receipt is scoped per task, not per slug: two tasks of
+the same project can sit in `edit-issued` concurrently, and a shared
+per-slug receipt would let each issuance overwrite the other's
+acknowledgement. The diff checksum covers the version hunk. The version is
+NEVER committed to the repo — it exists only in the staged diff and the
+ledger.
+
+## The attempt loop
+
+1. **Workflow (Publish phase):** computes the diff with `--task-id` /
+   `--attempt 1`, records ONE issuer-stamped `publish-intent` ledger entry
+   (`outcome: "publish-intent"`, `issuer: "workflow"`, carrying `diff_path`,
+   `diff_sha256`, `version`, `base`), parks with
+   `publish: publish-requested <commit> attempt=1`. The workflow NEVER issues
+   the edit — its children cannot reach `artifact_edit`.
+
+2. **Tick worker (`scan-publish-intent`):** claims the parked intent (1-hour
+   lease, CAS on `claim_expiry`), re-derives the version (never trusts the
+   ledger's), verifies the staged diff's sha256, checks the base against
+   stamped provenance. Then issues the edit DIRECTLY in its own turn —
+   the tick worker is the only caller class that can reach `artifact_edit`.
+
+3. **Tick worker (`record-intent-issuance`):** records the outcome:
+   - `accepted` → issuer-stamped `submitted` ledger entry +
+     `publish: edit-issued` note. The ack scan owns the task from here.
+   - `refused` → `rejected` entry + terminal `publish: publish-refused`.
+     The platform said no; parked for human attention.
+
+4. **Ack scan (`scan-ack-pending`):** every tick, for each `edit-issued` task:
+   - Reads the artifact's on-disk `.crew-publish-version-<task_id>` receipt — the
+     SOLE positive evidence (2026-09-20 REVIEW removed the circular
+     builder-report positive path).
+   - A builder report that echoes the EXACT version with outcome `refused`
+     (`record-builder-report` mechanically requires the version in
+     `report_text`) is the explicit-refusal channel — never an ack.
+   - **Any exact on-disk acknowledgement for an issued version on the same
+     task/commit counts** — including a late earlier attempt's version.
+   - On ack: stamps provenance, writes terminal
+     `publish: version-acknowledged`, re-queues the task.
+   - On explicit refusal: terminal `publish: publish-refused`.
+   - On window expiry (30 minutes per attempt, anchored at the LATEST
+     issuance): stages attempt N+1 with a FRESH version, immediately
+     claimable (no backoff).
+   - When the 2-hour total budget from the FIRST issuance is exhausted:
+     terminal `publish: version-timeout`.
+
+## Bounds (Eric's, re-set 2026-09-20)
+
+- 30-minute acknowledgement window per attempt (anchored at the latest issuance)
+- 2-hour total budget from the first issuance — then terminal `publish: version-timeout`
+- No backoff: a reissue is immediately claimable
+- The window is evidence-set: room #25's one healthy ack landed ~15-17
+  minutes after issuance — the window is ~2x that plus margin. The ledger
+  records issued_at and first-seen ack per attempt, so the distribution is
+  measurable and the window is tunable from real data
+- Explicit refusal is terminal (never re-issued)
+- Silence is unknown — fails closed
+
+## What the version proves
+
+The version on the artifact's disk proves the platform applied THIS attempt's
+edit request. It does NOT prove the content matches the staged diff byte-
+for-byte — and per Eric's contract, we don't check. The builder is trusted
+to apply the diff it was given; the version proves the request landed.
+
+**Receipt scope.** The version receipt proves the edit was adopted into the
+artifact's on-disk source tree — NOT that a rebuild succeeded, and NOT
+that a redeployment picked it up. A version acknowledgement followed by a
+failed build leaves the served bundle stale with a green publish verdict;
+that gap belongs to the artifact platform's build pipeline, not to this
+machine.
+
+## Operator recovery
+
+A task parked at Publish with a terminal note (`publish: version-timeout`,
+`publish: publish-refused`, `publish: publish-unissuable`) is the designed
+human decision point — parked→Todo is a human call, never automatic.
+
+**Diagnose before requeue.** The park note names the reason; the evidence
+lives in two places:
+
+- `$CREW_HOME/.publish-ledger/<deploy-slug>.jsonl` — the append-only
+  ledger: every intent, issuance, acknowledgement, and refusal for the
+  task, with commits, attempts, versions, and timestamps.
+- `$CREW_HOME/.publish-diffs/<task-id>-a<attempt>.diff` — the staged
+  checksummed diff that was (or was to be) issued.
+
+**Timeout semantics.** `publish: version-timeout` means the version was
+unobserved within the 2-hour total budget — NOT "not deployed." The edit may
+still have landed (the platform applied it but the receipt was never
+observed, or the observation raced the window). Before requeueing:
+
+1. Check the artifact's current on-disk source for the version. If present,
+   the edit landed — stamp provenance manually or requeue to let the ack
+   scan observe it.
+2. If absent, the edit likely did not land. Fix the cause (tool
+   availability, platform refusal, stale base), then move the task to Todo.
+   The next Publish run stages a fresh diff with a fresh version.
+
+**Never requeue blindly.** A timeout without diagnosis risks a duplicate
+edit (the unobserved edit may have landed). The machine fails closed for
+exactly this reason — the human opens it only with evidence.
+
+## Decommissioning
+
+This machine is a compensating control for the platform's missing real
+completion receipt: `artifact_edit` returns no build handle and no
+deployment verdict, so the crew attributes completion by content (the
+version) instead. The day the platform issues a trustworthy receipt — one
+that names the edit, its outcome, and its build — delete this machine:
+the version derivation, the receipt file, both scans' publish paths, and
+the `publish:` note verbs that belong to them. Until then, the
+compensating control IS the receipt.
+
+## Retired
+
+- `lib/verify-publish.js` — content verifier (deleted)
+- `lib/readback-disk.js` — disk read-back sensor (deleted)
+- `lib/build-readback-request.js` — read-back request builder (deleted)
+- `lib/classify-publish-absence.js` — unknown-recovery classifier (deleted)
+- `lib/check-intent-freshness.js` — intent freshness check (deleted)
+- `lib/retry-publish.js` — retry harness (deleted)
+- `lib/publish-content.js` — publish content helper (deleted)
+
+The `publish: verification-requested`, `publish: verification-claimed`,
+`publish: ambiguous`, `publish: retry-superseded`, `publish: retry-refused`,
+`publish: verified`, `publish: superseded`, `publish: verification-failed`,
+and `publish: intent-unverifiable` note verbs are legacy — the exact
+registry in `lib/publish-note-vocabulary.js` (no wildcard families).
+Recognized so old history skips as terminal, never written anew.