release-skill 0.8.1 → 0.9.0

package/src/core/hooks.mjs

@@ -43,22 +43,6 @@ const ENV_KEY_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 // Validation
 // ---------------------------------------------------------------------------
 
-/**
- * A release plan binds at most one postPublish declaration. Both prepare
- * and adoption assessment consume this pure rule and retain their own
- * error codes and presentation. Declaration contents are validated by
- * the existing postPublish validator, not by this cross-unit check.
- *
- * @param {Array<Object>} units - config.releaseUnits.
- * @returns {null|{unitIds: string[]}} Sorted conflicting unit IDs, or null.
- */
-export function findPostPublishUnitConflict(units) {
-  const declaring = (units ?? [])
-    .filter((unit) => unit && typeof unit === 'object' && unit.postPublish !== undefined);
-  if (declaring.length <= 1) return null;
-  return { unitIds: declaring.map((unit) => unit.id).sort() };
-}
-
 /**
  * Validate the shape of a hook descriptor against the project contract.
  *

package/src/core/plan.mjs

@@ -202,7 +202,8 @@ export function validatePlan(plan) {
 }
 
 /**
- * planVersion 2 digest scope (design: t1-2-digest-decoupling.md §4.1).
+ * planVersion 2/3 digest scope (design: t1-2-digest-decoupling.md §4.1;
+ * v3 inherits the v2 scope per 多发布单元 postPublish v3 §4.2).
  *
  * The record layer -- top-level `digest`, lifecycle `status`, `createdAt`,
  * the whole `baseline` object, and each action's runtime `status` -- is
@@ -210,8 +211,10 @@ export function validatePlan(plan) {
  * but is excluded from the digest. Everything else (planVersion, units with
  * every frozenSnapshot artifact identity field, externalActions identity,
  * production, configDigest, verificationGates, snapshotDigest) binds.
+ * For v3 the frozen `postPublish` array and every item binding field stay in
+ * the binding layer: any order or binding change moves the digest.
  *
- * This is the ONLY place the v2 record layer is defined.
+ * This is the ONLY place the v2/v3 record layer is defined.
  *
  * @param {object} plan - A plan object.
  * @returns {object} The binding-layer projection of the plan.
@@ -242,9 +245,12 @@ function stripRecordLayerV2(plan) {
  *
  * Digest scope forks on `plan.planVersion` (centralized here, never spread
  * elsewhere):
- * - planVersion 2: record-layer fields (status/createdAt/baseline/action
+ * - planVersion 2/3: record-layer fields (status/createdAt/baseline/action
  *   status/digest) are stripped before hashing, so re-preparing over the
- *   same sources yields the same digest. See `stripRecordLayerV2`.
+ *   same sources yields the same digest. See `stripRecordLayerV2`. v3
+ *   inherits the v2 scope exactly (multi-release-unit postPublish v3 §4.2);
+ *   versions beyond {2,3} are NOT admitted and stay fail-closed on the
+ *   legacy v1 path rather than being silently bound to v2 semantics.
  * - planVersion 1 or absent (legacy): only the top-level `digest` field is
  *   stripped. Byte-for-byte legacy semantics -- this path must never change.
  *
@@ -258,7 +264,7 @@ export function computePlanDigest(plan) {
   // 而是经 digest.mjs 的宽松输入域包装（contracts 权威序列化 + 本地归一化）
   // 后由 Foundation digestBytes 摘要 —— 对纯 JSON 计划与 digestDocument 字节
   // 完全一致，对含 undefined 的计划保持迁移前字节语义。
-  if (plan.planVersion === 2) {
+  if (plan.planVersion === 2 || plan.planVersion === 3) {
     return sha256Hex(canonicalJson(stripRecordLayerV2(plan)));
   }
   // Strip the digest field if present so the hash is self-consistent.
@@ -341,14 +347,15 @@ export async function writePlanImmutable(planPath, plan) {
       // EEXIST 直接抛冲突，无幂等分支；wrapper 补齐，fail-closed 无双路径）。
       const existing = await readFile(planPath, 'utf8').catch(() => null);
       if (existing === json) return { planPath, planDigest };
-      // planVersion 2 (design: t1-2-digest-decoupling.md §4.1): record-layer
-      // fields (status/createdAt/baseline) are excluded from the digest, so
+      // planVersion 2/3 (design: t1-2-digest-decoupling.md §4.1; v3 inherits
+      // the scope per 多发布单元 postPublish v3 §4.2): record-layer fields
+      // (status/createdAt/baseline) are excluded from the digest, so
       // re-preparing over identical binding content yields the SAME digest
       // with legitimately different bytes. Reuse the existing authority IFF
       // it is genuinely self-consistent (its embedded digest and recomputed
       // digest both equal this digest) -- the authority is never replaced.
       // Any other divergence (tampering, malformed file) still fails closed.
-      if (plan.planVersion === 2 && existing !== null) {
+      if ((plan.planVersion === 2 || plan.planVersion === 3) && existing !== null) {
         let existingPlan = null;
         try {
           existingPlan = JSON.parse(existing);
@@ -386,7 +393,7 @@ export async function writePlanImmutable(planPath, plan) {
 /**
  * Canonical normalized freeze timestamp shape (`YYYY-MM-DDTHH:MM:SS+00:00`).
  * Mirrors the frozenSnapshot.commitTimestamp pattern in the release-plan
- * schema; used by the planVersion 2 completeness gate, which requires a
+ * schema; used by the planVersion 2/3 completeness gate, which requires a
  * canonical normalized timestamp without re-binding it to plan.createdAt.
  */
 const CANONICAL_COMMIT_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\+00:00$/;
@@ -568,8 +575,9 @@ export function validatePlanActionCompleteness(plan, options = {}) {
       }
       if (!frozen.commitTimestamp || typeof frozen.commitTimestamp !== 'string') {
         failures.push(`unit "${unitId}" frozenSnapshot.commitTimestamp is missing; legacy production plans without a freeze timestamp are rejected, never silently backfilled`);
-      } else if (plan.planVersion === 2) {
-        // planVersion 2 (design: t1-2-digest-decoupling.md §4.2): the freeze
+      } else if (plan.planVersion === 2 || plan.planVersion === 3) {
+        // planVersion 2/3 (design: t1-2-digest-decoupling.md §4.2; v3 inherits
+        // the semantics per 多发布单元 postPublish v3 §4.2): the freeze
         // timestamp is derived from the headCommit committer date, so it no
         // longer equals plan.createdAt (record-layer real clock). It must
         // still be a canonical normalized timestamp -- the same pattern the

package/src/core/postpublish-approval.mjs

@@ -47,6 +47,7 @@ import { ReleaseError, GATE_FAILED } from './errors.mjs';
 import { computePlanDigest } from './plan.mjs';
 import { computeApprovalDigest, validateApprovalTimeWindow } from './approval.mjs';
 import { resolvePresetRequiresApproval } from './presets.mjs';
+import { normalizePostPublishView, validatePostPublishHookIdUniqueness } from './postpublish.mjs';
 import { readTrustedPackageResource } from './trusted-resource.mjs';
 
 const postpublishApprovalSchema = JSON.parse((await readTrustedPackageResource(
@@ -79,7 +80,8 @@ export function validatePostPublishApprovalRecordSchema(approval) {
  * - record shape (postpublish-approval-record schema; additionalProperties
  *   is false, so plan-level fields like approvedActions are rejected);
  * - planDigest equals the computed plan digest;
- * - hookId names a hook declared in the frozen plan's postPublish.hooks;
+ * - hookId names a hook declared in the frozen plan's postPublish
+ *   declarations (unified normalized view, globally unique across units);
  * - that hook actually declares requiresApproval: true;
  * - the shared approval time window (24h max, 5-minute skew, unexpired).
  *
@@ -103,7 +105,15 @@ export function validatePostPublishApproval(plan, approval, options = {}) {
     );
   }
 
-  const hooks = plan.postPublish?.hooks ?? [];
+  // §4.3 unified normalization (rework R-02): the frozen plan's postPublish
+  // may be the legacy single declaration (planVersion 1/2) or the v3
+  // declaration array; every consumer resolves declared hooks through the
+  // SAME normalized view, and the SAME array-level uniqueness authority
+  // re-asserts that hookId is globally unique across declarations — one
+  // (planDigest, hookId) approval must never authorize two units.
+  const declarations = normalizePostPublishView(plan);
+  validatePostPublishHookIdUniqueness(declarations);
+  const hooks = declarations.flatMap((declaration) => declaration.hooks ?? []);
   const hook = hooks.find((entry) => entry.id === approval.hookId);
   if (!hook) {
     throw new ReleaseError(

package/src/core/postpublish-bundle.mjs

@@ -244,28 +244,38 @@ function sameClosureResources(actual, expected) {
 }
 
 /**
- * Re-verify the frozen execution bundle and install ONLY the verified bytes
- * into the detached tag worktree. Runs BEFORE any hook or external write.
+ * Verify the frozen execution bundle closure WITHOUT installing anything
+ * (rework R-01: the full-declaration preflight reuses this exact
+ * implementation before the first external write — a later declaration's
+ * missing/drifted bundle must fail the whole saga with zero writes).
  *
- * Steps:
+ * Steps (the first half of verifyAndInstallExecutionBundle, shared verbatim):
  * 1. Strictly read every frozen resource from the digest-addressed store
  *    (`readFileStrict` with the frozen sha256 content guard); the file mode
  *    must still equal the publication mode — any deviation is tamper;
  * 2. recompute the closure through Foundation in a disposable workspace and
- *    compare it (digest + resources) with the plan's frozen closure;
- * 3. exclusively publish the verified bytes into the worktree — an occupied
- *    target means the bundle would shadow a frozen tag file and fails closed.
+ *    compare it (digest + resources) with the plan's frozen closure.
  *
  * @param {object} params
- * @param {object} params.plan - Frozen plan (postPublish.executionBundle).
+ * @param {object} params.postPublish - The CURRENT declaration being
+ *   verified (REQUIRED, rework R-06: the v1/v2 normalized single item or the
+ *   v3 loop item; an array fails closed).
  * @param {string} params.planPath - Absolute plan authority path (mechanical
  *   bundle-root anchor).
- * @param {string} params.worktreePath - Detached tag worktree root.
- * @returns {Promise<{installed: string[]}>} Installed relative paths.
+ * @returns {Promise<{verified: boolean, bytesByPath: Map<string, Buffer>}>}
+ *   `verified: false` with an empty map when the declaration carries no
+ *   executionBundle (a legal no-bundle declaration).
  */
-export async function verifyAndInstallExecutionBundle({ plan, planPath, worktreePath } = {}) {
-  const bundle = plan?.postPublish?.executionBundle;
-  if (!bundle) return { installed: [] };
+export async function verifyExecutionBundle({ planPath, postPublish } = {}) {
+  const declaration = postPublish;
+  if (!declaration || typeof declaration !== 'object') {
+    fail('verifyExecutionBundle requires the current postPublish declaration; pass the normalized single item or the v3 loop item explicitly');
+  }
+  if (Array.isArray(declaration)) {
+    fail('verifyExecutionBundle requires the current postPublish declaration, never the declaration array');
+  }
+  const bundle = declaration.executionBundle;
+  if (!bundle) return { verified: false, bytesByPath: new Map() };
   const closure = bundle.closure;
   if (!closure || !Array.isArray(closure.resources) || typeof closure.digest !== 'string') {
     fail('plan carries a malformed executionBundle closure');
@@ -318,10 +328,38 @@ export async function verifyAndInstallExecutionBundle({ plan, planPath, worktree
     fail(`bundle closure recomputation failed: ${cause?.message ?? cause}`, { kind: cause?.details?.kind });
   }
 
+  return { verified: true, bytesByPath };
+}
+
+/**
+ * Re-verify the frozen execution bundle (the SAME closure verification the
+ * full-declaration preflight runs) and install ONLY the verified bytes into
+ * the detached tag worktree. Runs BEFORE any hook or external write.
+ *
+ * Install step: exclusively publish the verified bytes into the worktree —
+ * an occupied target means the bundle would shadow a frozen tag file and
+ * fails closed.
+ *
+ * @param {object} params
+ * @param {object} params.postPublish - The CURRENT declaration being
+ *   executed (v3 multi-unit contract §4.3). REQUIRED (rework R-06): callers
+ *   must pass the declaration explicitly — v1/v2 callers pass the single item
+ *   obtained from normalizePostPublishView(), v3 callers pass their loop
+ *   item. Omitting it fails closed; an array never matches (fail-closed).
+ * @param {string} params.planPath - Absolute plan authority path (mechanical
+ *   bundle-root anchor).
+ * @param {string} params.worktreePath - Detached tag worktree root.
+ * @returns {Promise<{installed: string[]}>} Installed relative paths.
+ */
+export async function verifyAndInstallExecutionBundle({ planPath, worktreePath, postPublish } = {}) {
+  const { bytesByPath } = await verifyExecutionBundle({ planPath, postPublish });
+  const declaration = postPublish;
+  const closure = declaration?.executionBundle?.closure;
+
   // Install verified bytes into the tag worktree — exclusively: the bundle
   // must never overwrite (shadow) a file that already belongs to the tag.
   const installed = [];
-  for (const resource of closure.resources) {
+  for (const resource of closure?.resources ?? []) {
     try {
       await publishFileExclusive(worktreePath, resource.path, bytesByPath.get(resource.path), {
         mode: EXECUTION_BUNDLE_FILE_MODE,

package/src/core/postpublish.mjs

@@ -481,6 +481,131 @@ export function validatePostPublishDeclaration(postPublish, options = {}) {
   return postPublish;
 }
 
+/**
+ * Version-aware read-only normalization of the frozen plan's postPublish
+ * field (multi-release-unit postPublish v3, design §4.2 归一表).
+ *
+ * This is the SINGLE normalization seam every reader (approve, distribute,
+ * postVerify, ship, verify, recovery, publish, reconcile, approval) must use
+ * to obtain the declaration array view. The accepted shape is derived from
+ * `plan.planVersion` ONLY — readers must never guess the shape from the
+ * field value (no shape sniffing), and no second normalizer or compatibility
+ * schema may exist. Pure and strictly read-only: never mutates the plan and
+ * never rewrites legacy plans, summaries, or evidence.
+ *
+ * | planVersion | input shape   | result           |
+ * |-------------|---------------|------------------|
+ * | 1/2         | absent        | []               |
+ * | 1/2         | single object | [declaration]    |
+ * | 1/2         | array         | rejected         |
+ * | 3           | array         | the array itself |
+ * | 3           | object/absent | rejected         |
+ *
+ * Values outside the table (null, primitives, unknown planVersion) fail
+ * closed with GATE_FAILED: a schema-valid plan can never produce them, and a
+ * reader must never paper over a shape it does not understand.
+ *
+ * @param {object} plan - Frozen plan (schema-valid by the caller's contract).
+ * @returns {object[]} The declaration array view (empty for legacy absent).
+ * @throws {ReleaseError} GATE_FAILED on any shape/version mismatch.
+ */
+export function normalizePostPublishView(plan) {
+  const version = plan?.planVersion;
+  const postPublish = plan?.postPublish;
+  if (version === 1 || version === 2) {
+    if (postPublish === undefined) return [];
+    if (Array.isArray(postPublish)) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `planVersion ${version} plans must not carry a postPublish array; only planVersion 3 accepts the array shape`,
+        { planVersion: version, postPublishKind: 'array' },
+      );
+    }
+    if (postPublish === null || typeof postPublish !== 'object') {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `planVersion ${version} plans must carry a single postPublish object or none; found ${postPublish === null ? 'null' : typeof postPublish}`,
+        { planVersion: version },
+      );
+    }
+    return [postPublish];
+  }
+  if (version === 3) {
+    if (!Array.isArray(postPublish)) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        `planVersion 3 plans must carry a postPublish array (possibly empty); found ${postPublish === undefined ? 'no postPublish field' : postPublish === null ? 'null' : 'a single object'}`,
+        { planVersion: 3, postPublishKind: postPublish === undefined ? 'absent' : postPublish === null ? 'null' : 'object' },
+      );
+    }
+    return postPublish;
+  }
+  throw new ReleaseError(
+    GATE_FAILED,
+    `cannot normalize postPublish shape: unknown planVersion ${String(version)}`,
+    { planVersion: version },
+  );
+}
+
+/**
+ * Array-level domain validation: every EXPLICIT hooks[].id must be unique
+ * across the whole declaration array (multi-release-unit postPublish v3,
+ * design §9.2 rule 3; rework R-02). The (planDigest, hookId) approval
+ * contract binds each explicit hook id plan-wide, so a duplicate across
+ * units must fail before any approval is minted or consumed and before any
+ * side effect — JSON Schema cannot express cross-array business uniqueness,
+ * so this function is the SINGLE runtime authority for it.
+ *
+ * Every entry only normalizes its input to the declaration array view and
+ * calls this function: prepare, setup/adoption assessment, approve, the
+ * postpublish approval validator, distribute, and postVerify. Target and
+ * internal probe local ids may repeat across units (checkpoints are
+ * unit-namespaced); explicit hook ids may not.
+ *
+ * @param {object[]} declarations - The declaration array view
+ *   (`normalizePostPublishView()` output, or the per-unit postPublish blocks
+ *   collected by prepare/setup).
+ * @throws {ReleaseError} GATE_FAILED with details { hookId, unitIds } on the
+ *   first cross-unit duplicate.
+ */
+export function validatePostPublishHookIdUniqueness(declarations) {
+  const explicitHookIdOwner = new Map();
+  for (const declaration of declarations ?? []) {
+    for (const hook of declaration?.hooks ?? []) {
+      const owner = explicitHookIdOwner.get(hook.id);
+      if (owner !== undefined && owner !== declaration.unitId) {
+        throw new ReleaseError(
+          GATE_FAILED,
+          `postPublish hook id "${hook.id}" is declared by units "${owner}" and "${declaration.unitId}"; explicit hooks[].id must be unique across the whole project (target and probe local ids may repeat across units)`,
+          { hookId: hook.id, unitIds: [owner, declaration.unitId] },
+        );
+      }
+      explicitHookIdOwner.set(hook.id, declaration.unitId);
+    }
+  }
+}
+
+/**
+ * Deterministically derive the checkpoint action id for one postPublish
+ * local action (target probe/mirror or hook) inside one release unit
+ * (§4.3 checkpoint binding). planVersion 3 namespaces every action id under
+ * the owning declaration's unitId (`unitId/localId`); legacy plans keep the
+ * bare local id so pre-existing checkpoint records and approvals stay valid.
+ * This is the SINGLE derivation used by every consumer (distribute,
+ * postVerify, recovery, verify), so a checkpoint id can never drift between
+ * the run records, the recovery mapping, and the approval binding.
+ *
+ * @param {object} params
+ * @param {number} params.planVersion - Frozen plan's planVersion.
+ * @param {string} params.unitId - Owning declaration's unitId.
+ * @param {string} params.localId - Local action id (`probe-<target.id>`,
+ *   `<target.id>`, or the hook id).
+ * @returns {string} The checkpoint action id.
+ */
+export function postPublishActionId({ planVersion, unitId, localId }) {
+  return planVersion === 3 ? `${unitId}/${localId}` : localId;
+}
+
 /**
  * Order targets so every target comes after its dependsOn target.
  *
@@ -595,24 +720,39 @@ export function effectiveHookRequiresApproval(hook) {
  *
  * @param {object} args
  * @param {object} args.plan - Frozen plan (digest + units + postPublish).
+ * @param {object} args.postPublish - THE current declaration the caller is
+ *   executing. REQUIRED (rework R-06): callers must pass the declaration
+ *   explicitly — the unit identity is never derived from a global
+ *   single-object read (contract §4.3). v1/v2 callers pass the single item
+ *   obtained from normalizePostPublishView(); v3 callers pass their loop
+ *   item. Omitting it fails closed with GATE_FAILED; a declaration ARRAY
+ *   (or anything non-object) fails closed too.
  * @param {string} args.runId - Current distribute run id.
  * @param {object} args.sourceRun - Sealed source run (finishedAt = publishedAt).
  * @param {string} args.payloadDir - Materialized payload directory.
  * @param {'distribute'|'postVerify'} args.phase
  * @param {object} [args.verifyEvidence] - Verify evidence (postVerify phase).
  * @returns {object} The context projection.
+ * @throws {ReleaseError} GATE_FAILED when no single declaration is in scope.
  */
-export function buildPostPublishContext({ plan, runId, sourceRun, payloadDir, phase, verifyEvidence }) {
-  const postPublish = plan.postPublish ?? {};
-  const unit = (plan.units ?? []).find((entry) => entry.id === postPublish.unitId);
+export function buildPostPublishContext({ plan, postPublish, runId, sourceRun, payloadDir, phase, verifyEvidence }) {
+  const declaration = postPublish;
+  if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration)) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `buildPostPublishContext requires the current postPublish declaration; found ${declaration === undefined ? 'no declaration' : Array.isArray(declaration) ? 'a declaration array' : typeof declaration}`,
+      { planVersion: plan?.planVersion, unitId: declaration?.unitId ?? null },
+    );
+  }
+  const unit = (plan.units ?? []).find((entry) => entry.id === declaration.unitId);
   const frozenSnapshot = unit?.frozenSnapshot ?? {};
   return {
     planDigest: plan.digest,
     runId,
-    unitId: postPublish.unitId,
+    unitId: declaration.unitId,
     version: unit?.targetVersion,
-    tag: postPublish.tag,
-    commit: postPublish.tagCommit,
+    tag: declaration.tag,
+    commit: declaration.tagCommit,
     ...(frozenSnapshot.tree !== undefined ? { tree: frozenSnapshot.tree } : {}),
     ...(frozenSnapshot.manifestDigest !== undefined ? { manifestDigest: frozenSnapshot.manifestDigest } : {}),
     publishedAt: sourceRun?.finishedAt,

package/src/core/preset-executor.mjs

@@ -22,12 +22,17 @@
  * @module core/preset-executor
  */
 
+import { rm } from 'node:fs/promises';
+
 import { ReleaseError, POST_PUBLISH_VERIFY_FAILED } from './errors.mjs';
 import { resolveProposalInboxTransport } from './presets.mjs';
 import { executeNotifyHandoffHook } from './notify-handoff.mjs';
 import {
+  buildProposalDocument,
   executeProposalInboxGitPushHook,
   executeProposalInboxLocalFileHook,
+  observeProposalInboxGitPush,
+  proposalFileName,
 } from './proposal-inbox.mjs';
 import { executeMarketplaceRegistryEntryHook } from './marketplace-registry-entry.mjs';
 import { executeDocsRefreshHook } from './docs-refresh-preset.mjs';
@@ -173,3 +178,51 @@ export async function executePresetHook(params) {
     }
   }
 }
+
+/**
+ * Narrow READ-ONLY preset preflight (rework R-01): deterministic conflicts a
+ * preset can already recognize from its existing observe-before-write
+ * observation, evaluated BEFORE the first external write of the phase. This
+ * is NOT a second dispatch table and NOT a lock — it only covers the presets
+ * whose observation implementation already exists (proposal-inbox git-push:
+ * the proposal path exists with different bytes -> the shared observation
+ * throws REMOTE_CONFLICT), and every preset hook is re-observed at execution
+ * time regardless.
+ *
+ * Returns `null` for presets/transports without a read-only deterministic
+ * conflict observation (proposal-inbox local-file, notify-handoff, ...) —
+ * their execution-phase observe-before-write stays the only gate.
+ *
+ * @param {object} params
+ * @param {object} params.hook - Declared preset hook entry.
+ * @param {object} params.contextProjection - The deterministic §2.3 context
+ *   projection of the current run (the same bytes the execution-phase
+ *   delivery serializes; lineage-stable runId).
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @returns {Promise<{verdict: string, proposalPath: string}|null>}
+ * @throws {ReleaseError} REMOTE_CONFLICT/REMOTE_UNAVAILABLE from the shared
+ *   observation implementation.
+ */
+export async function preflightPresetHook(params) {
+  const { hook, contextProjection, exec } = params ?? {};
+  if (!hook || typeof hook.preset !== 'string') return null;
+  if (hook.preset !== 'proposal-inbox') return null;
+  const target = hook.config?.target;
+  if (!target) return null; // targetOptional degradation: nothing remote to observe.
+  const transport = resolveProposalInboxTransport(hook.config);
+  if (transport !== 'git-push') return null; // local-file: no deterministic remote conflict observation.
+
+  // The same observation implementation the execution-phase delivery uses:
+  // build the byte-deterministic proposal and observe-before-write.
+  const document = buildProposalDocument(contextProjection);
+  const proposalPath = proposalFileName(contextProjection.unitId, contextProjection.version);
+  const { cloneDir, verdict } = await observeProposalInboxGitPush({
+    remoteUrl: target.remoteUrl,
+    branch: target.branch,
+    proposalPath,
+    proposalDocument: document,
+    ...(exec !== undefined ? { exec } : {}),
+  });
+  await rm(cloneDir, { recursive: true, force: true }).catch(() => {});
+  return { verdict, proposalPath };
+}

package/src/core/proposal-inbox.mjs

@@ -288,40 +288,42 @@ export async function crossCheckPushedCommit(exec, remoteUrl, branch, pushedComm
 }
 
 /**
- * Deliver one proposal document through the git-push transport:
- * clone -> write (absent only) -> commit (frozen identity) -> push.
+ * Observe-before-write for the git-push transport (rework R-01): clone the
+ * downstream into a fresh disposable checkout and compare any existing
+ * proposal bytes with the serialized document. This is the SINGLE observation
+ * implementation shared by the execution-phase delivery (observe-before-write)
+ * and the full-declaration preflight (deterministic conflict detection BEFORE
+ * the first external write) — no second observe algorithm or dispatch table.
  *
- * - identical existing content -> NO_CHANGE, nothing written;
- * - different existing content -> REMOTE_CONFLICT (human decision);
- * - NEVER --force.
+ * - existing identical content -> verdict 'IDENTICAL';
+ * - different existing content -> REMOTE_CONFLICT (human decision), thrown
+ *   from here so preflight and delivery can never drift apart;
+ * - absent -> verdict 'ABSENT'.
  *
- * No preset-level dry-run (R4 review m-3): the command-level DRY_RUN skip
- * contract skips preset hooks wholesale (SKIPPED/DRY_RUN checkpoints in
- * distribute/postVerify) before this delivery is ever invoked, so a dryRun
- * parameter here would be unreachable dead surface.
+ * On success the CALLER owns `cloneDir` and must remove it (the delivery
+ * continues writing/committing/pushing from that checkout; the preflight
+ * discards it immediately). On any thrown failure the clone dir is already
+ * removed.
  *
  * @param {object} params
  * @param {string} params.remoteUrl - Downstream repository URL.
  * @param {string} params.branch - Downstream branch.
  * @param {string} params.proposalPath - Repository-relative proposal path.
  * @param {object} params.proposalDocument - The proposal document.
- * @param {object} params.commitIdentity - Frozen { name, email }.
  * @param {Function} [params.exec] - Injectable git exec (tests).
- * @returns {Promise<{ status: 'EXECUTED'|'NO_CHANGE', observation: object }>}
+ * @returns {Promise<{cloneDir: string, previousHead: string|null, verdict: 'ABSENT'|'IDENTICAL'}>}
  */
-export async function deliverProposalGitPush(params) {
+export async function observeProposalInboxGitPush(params) {
   const {
     remoteUrl,
     branch,
     proposalPath,
     proposalDocument,
-    commitIdentity,
     exec: execOpt,
   } = params ?? {};
   assertSafeRemoteUrl(remoteUrl);
   assertSafeBranch(branch);
   assertSafeProposalPath(proposalPath);
-  assertCommitIdentity(commitIdentity);
   if (!proposalDocument || typeof proposalDocument !== 'object' || Array.isArray(proposalDocument)) {
     throw new ReleaseError(GATE_FAILED, 'proposal-inbox requires a proposal document');
   }
@@ -365,7 +367,7 @@ export async function deliverProposalGitPush(params) {
       await git(['checkout', '--quiet', '--orphan', branch]);
     }
 
-    // Observe-before-write: an existing proposal decides the outcome.
+    // Observe: an existing proposal decides the outcome.
     const targetPath = join(cloneDir, proposalPath);
     let existing = null;
     try {
@@ -373,20 +375,82 @@ export async function deliverProposalGitPush(params) {
     } catch {
       existing = null;
     }
-    if (existing !== null) {
-      if (existing === serialized) {
-        return {
-          status: 'NO_CHANGE',
-          observation: { mode: 'no-change', previousHead, branchTip: previousHead },
-        };
-      }
-      throw new ReleaseError(
-        REMOTE_CONFLICT,
-        `proposal ${proposalPath} already exists in ${redactUrlCredentialsIfPresent(remoteUrl)} with different content; overwriting a downstream proposal requires a human decision`,
-        { remoteUrl: redactUrlCredentialsIfPresent(remoteUrl), proposalPath },
-      );
+    if (existing === null) {
+      return { cloneDir, previousHead, verdict: 'ABSENT' };
+    }
+    if (existing === serialized) {
+      return { cloneDir, previousHead, verdict: 'IDENTICAL' };
     }
+    throw new ReleaseError(
+      REMOTE_CONFLICT,
+      `proposal ${proposalPath} already exists in ${redactUrlCredentialsIfPresent(remoteUrl)} with different content; overwriting a downstream proposal requires a human decision`,
+      { remoteUrl: redactUrlCredentialsIfPresent(remoteUrl), proposalPath },
+    );
+  } catch (cause) {
+    await rm(cloneDir, { recursive: true, force: true }).catch(() => {});
+    throw cause;
+  }
+}
 
+/**
+ * Deliver one proposal document through the git-push transport:
+ * observe -> write (absent only) -> commit (frozen identity) -> push.
+ *
+ * - identical existing content -> NO_CHANGE, nothing written;
+ * - different existing content -> REMOTE_CONFLICT (human decision);
+ * - NEVER --force.
+ *
+ * The observe-before-write step calls the SAME shared observation
+ * implementation the full-declaration preflight uses, so the execution phase
+ * always re-observes the remote (the preflight is never a lock).
+ *
+ * No preset-level dry-run (R4 review m-3): the command-level DRY_RUN skip
+ * contract skips preset hooks wholesale (SKIPPED/DRY_RUN checkpoints in
+ * distribute/postVerify) before this delivery is ever invoked, so a dryRun
+ * parameter here would be unreachable dead surface.
+ *
+ * @param {object} params
+ * @param {string} params.remoteUrl - Downstream repository URL.
+ * @param {string} params.branch - Downstream branch.
+ * @param {string} params.proposalPath - Repository-relative proposal path.
+ * @param {object} params.proposalDocument - The proposal document.
+ * @param {object} params.commitIdentity - Frozen { name, email }.
+ * @param {Function} [params.exec] - Injectable git exec (tests).
+ * @returns {Promise<{ status: 'EXECUTED'|'NO_CHANGE', observation: object }>}
+ */
+export async function deliverProposalGitPush(params) {
+  const {
+    remoteUrl,
+    branch,
+    proposalPath,
+    proposalDocument,
+    commitIdentity,
+    exec: execOpt,
+  } = params ?? {};
+  assertCommitIdentity(commitIdentity);
+  const exec = typeof execOpt === 'function' ? execOpt : defaultExec;
+  const serialized = `${JSON.stringify(proposalDocument, null, 2)}\n`;
+
+  // Shared observe-before-write: identical -> NO_CHANGE; different -> the
+  // shared observation throws REMOTE_CONFLICT (human decision).
+  const { cloneDir, previousHead, verdict } = await observeProposalInboxGitPush({
+    remoteUrl,
+    branch,
+    proposalPath,
+    proposalDocument,
+    ...(execOpt !== undefined ? { exec: execOpt } : {}),
+  });
+
+  try {
+    if (verdict === 'IDENTICAL') {
+      return {
+        status: 'NO_CHANGE',
+        observation: { mode: 'no-change', previousHead, branchTip: previousHead },
+      };
+    }
+
+    const git = (args, options = {}) => exec('git', args, { cwd: cloneDir, shell: false, timeout: GIT_TIMEOUT_MS, ...options });
+    const targetPath = join(cloneDir, proposalPath);
     await mkdir(dirname(targetPath), { recursive: true });
     await writeFile(targetPath, serialized);
     await git(['add', '-A']);