Issue 194 Update Projection Receipt Staging Research

Scope and conclusion

This report covers the update lifecycle, scaffold output, projection-sync script, and regression-contract lanes for issue #194. The confirmed defect has two coupled causes: a lexical /var versus /private/var guard skipped the main sync-subagents entrypoint, and updates needed to stage completed prior projection-receipt evidence before candidate synchronization. The missing-live-receipt failure remains explicit; the shipped repair canonicalizes generated entrypoint paths and stages completed prior evidence without weakening sync validation.

Primary-source evidence

• apps/cli/src/scaffold/stage.ts:1123-1144 runs the init scaffold lifecycle and calls writeScaffoldOutput inside its application callback. The output is the producer boundary for staged scaffold materialization.
• apps/cli/src/update/run.ts:3323-3408 creates the update staging directory and prepares the staged desired state before application. apps/cli/src/update/run.ts:4181-4185 then reads .devpunks/harness-projection-receipt.json from that staged directory when preserving context evidence, proving the receipt is an expected staged artifact rather than optional output.
• apps/cli/src/data/scripts/sync-subagents.mjs:1593-1602 rejects a missing or changed published receipt. :1617-1646 publishes the receipt, rereads it, and preserves explicit retry/failure errors for publication or manifest-coherence races. This is the trusted consumer contract.
• The prior IP-318 implementation record identifies “premature receipt staging” as a review RED (apps/wiki/specs/cli/IP-318-govern-project-settings-and-scaffold-state-safely/PLAN.md:294) and says receipt persistence is the final action (:296). Later delivery evidence confirms the combined path-guard and completed-prior-evidence causes.

Facts and inferences

Facts are the call/order and failure behaviors cited above. The confirmed inference is a combined failure: a lexical /var versus /private/var comparison skipped the main sync-subagents entrypoint, and updates needed to stage completed prior projection-receipt evidence before candidate synchronization. The ENOENT was therefore not an ordering-only defect or evidence of an invalid receipt.

One downstream-preservation hypothesis proposes that update should leave the live receipt untouched until all downstream staged work completes. That concern is valid for failed or partial application, but it does not explain this stack alone: the consumer cannot begin without a live receipt, and the existing sync contract already distinguishes missing, malformed, changed, and incoherent evidence. The stack and the explicit “premature receipt staging” RED select canonicalized entrypoint paths plus conditional pre-materialization staging with failure-preserving cleanup. Any later manifest/receipt commit must still retain the consumer’s explicit validation and retry errors.

Resolved during delivery

• Refined evidence: desired-state/fresh scaffold may declare a managed projection-receipt entry before top-level completion evidence exists. Prior receipt staging is required only when the live manifest's top-level projectionReceiptFile marks completed evidence; then the managed entry's path, hash, and status must agree with that receipt.
• Preserve strict missing-receipt failure for completed manifests; do not synthesize receipt evidence or weaken synchronization validation.
• Treat absent live evidence as a typed CliValidationError; do not synthesize a receipt or weaken synchronization validation.
• Keep the regression at the CLI update seam: valid evidence reaches preview and reconciliation, while missing evidence remains an explicit failure.

Synthesized contract

The CLI update path must stage a truthful live projection receipt before invoking staged sync-subagents only when the live manifest's top-level projectionReceiptFile marks completed evidence. Sync must continue to validate the receipt as a confined regular file and fail explicitly when it is missing, malformed, changed, or inconsistent with the scaffold manifest; for completed manifests, the managed entry's path, hash, and status must also agree. Desired-state/fresh scaffold declarations may precede top-level completion evidence without forcing receipt staging. Receipt and manifest evidence must remain truthful on partial failure; unrelated downstream files must not be silently preserved as a substitute for missing producer evidence.

Regression test contract

Add a CLI-only regression at the update/staging seam that starts from a valid recorded scaffold, exercises update with staged sync enabled, and proves: (1) the receipt exists before the consumer’s first read; (2) the update no longer fails deterministically with ENOENT; (3) a missing live receipt still returns the existing explicit failure; (4) malformed or changed receipt evidence remains rejected; and (5) a failed downstream action does not falsify the receipt or manifest. Keep the test isolated from generated projections and assert the ordered producer/consumer observation rather than timing.

Delivery boundary and next action

This is CLI-only release scope. It does not authorize wiki generated-projection edits, API/web changes, or a release by itself. Work must run from a clean or explicitly isolated checkout: the current checkout is dirty, with unrelated edits present, so do not infer test or diff ownership from the shared tree. Next action: run clean-worktree affected verification, then read back the PR checks.