@mriekki/project-forge 4.1.0 → 4.2.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "738dca3e03d110da0837d35d45101d2315f13a6f",
+      "commit": "d84829629d151c85bbe4680bc2297abfdf3a3022",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "149812159cafdfeeca04645e129392021b8b9e09",
+      "commit": "e974c227d9d0768e64605550709db89ccaf93434",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -31,6 +31,7 @@
     {"source": "src/project_forge_deployment/profile_migration.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profile_migration.py"},
     {"source": "src/project_forge_deployment/profile_repository.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profile_repository.py"},
     {"source": "src/project_forge_deployment/profiles.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py"},
+    {"source": "src/project_forge_deployment/proof_receipt.py", "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py"},
     {"source": "src/project_forge_deployment/registry_access.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py"},
     {"source": "src/project_forge_deployment/registry_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/registry_cli.py"},
     {"source": "src/project_forge_deployment/route_registry.py", "destination": "tools/project-forge-deployment/project_forge_deployment/route_registry.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "738dca3e03d110da0837d35d45101d2315f13a6f",
+      "commit": "d84829629d151c85bbe4680bc2297abfdf3a3022",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -22,7 +22,7 @@
         {
           "source": "core/instructions/project-forge-workflow.instructions.md",
           "destination": ".github/instructions/project-forge-workflow.instructions.md",
-          "sha256": "a6b28d916b67c9eec3831e414b56be3636512f7f7740523d22aaaf6efa00d335"
+          "sha256": "85568ba56681831e34c63aa14f91702522a451e8b2fa883da631d609440d7a7c"
         },
         {
           "source": "core/instructions/project-forge-docs.instructions.md",
@@ -52,7 +52,7 @@
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "2f1b88b31b2c7233a00ab9293cd98a5fade00e114e1a442a793affbc7fe4ad83"
+          "sha256": "deb64d0e7ce3a7788e5674182c9788219f2422468ed3e0cc767d49ce569acaea"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -107,7 +107,7 @@
         {
           "source": "core/skills/upstream-fix/SKILL.md",
           "destination": ".github/skills/upstream-fix/SKILL.md",
-          "sha256": "72466740638688f99b0a1dd6c56ef7bc90ac218b27642d0af8b3237074b97fec"
+          "sha256": "cec11a112840b37a5ff61e28281d26eb9490e9d7b05df99ae5fa152231316798"
         },
         {
           "source": "core/skills/wait-what/SKILL.md",
@@ -328,7 +328,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "149812159cafdfeeca04645e129392021b8b9e09",
+      "commit": "e974c227d9d0768e64605550709db89ccaf93434",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -404,12 +404,12 @@
         {
           "source": "src/project_forge_deployment/environment_probe.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py",
-          "sha256": "5f4bba4a9e01b97eccdf67919d49894c9d264fae0edd63f742baaa18e42f69d0"
+          "sha256": "4e9a49a7cf0427dcdef1e28f955297569ec8cd0ee9d071404ef876e3ce036313"
         },
         {
           "source": "src/project_forge_deployment/environment_setup.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_setup.py",
-          "sha256": "1554c2954a024f8419f44eb2ab3fdc129334de41df6038628bade9cb7a803950"
+          "sha256": "a79919da8655a6c42fded3224373f6381d15c8c68869b70c31d6edb7702fd348"
         },
         {
           "source": "src/project_forge_deployment/errors.py",
@@ -419,7 +419,7 @@
         {
           "source": "src/project_forge_deployment/home_lab.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/home_lab.py",
-          "sha256": "071391b687aac7e4bade0a27bf7d47257935a21c8f9151138fe74185f6c54cfb"
+          "sha256": "481b22ee7983dbe39b9e727ad874356a5dc4d55a4d7380545f2577e4a9ea45e7"
         },
         {
           "source": "src/project_forge_deployment/image_transfer.py",
@@ -471,6 +471,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py",
           "sha256": "c8fb1c378af9d39d28f46b300064bec967e2a6f7a13e22d089fc00413c42fd9d"
         },
+        {
+          "source": "src/project_forge_deployment/proof_receipt.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py",
+          "sha256": "9b4bbb559747fc4ee3ba984a050fc6425e532527ae82f9897c73e04d8d0291b6"
+        },
         {
           "source": "src/project_forge_deployment/registry_access.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py",
@@ -519,7 +524,7 @@
         {
           "source": "src/project_forge_deployment/ssh.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/ssh.py",
-          "sha256": "916a272ed5978df642e6084a3030c32f2c9dcb4b3b686a194428f9810ec55e9d"
+          "sha256": "88d59b62f63dc6b7206b6074dd109af4ea7c8f022f506e67f7204f1f06240d26"
         },
         {
           "source": "src/project_forge_deployment/teardown.py",
@@ -554,7 +559,7 @@
         {
           "source": "docs/ENVIRONMENT_PROOF.md",
           "destination": "docs/project-forge/ENVIRONMENT_PROOF.md",
-          "sha256": "f635a87ada6a22deb09a3ac0f1c99f8e32119bb8bff3613d77db2ed876dc2552"
+          "sha256": "2ce7225ad6166a4ee30f51ea67ec077de0c29ce3a5c39b4ff57bf11cbe25e927"
         },
         {
           "source": "docs/images/developer-environment-journey.svg",

package/assets/generated/core/core/instructions/project-forge-workflow.instructions.md

@@ -34,7 +34,9 @@ For deployment readiness, inspect existing non-secret configuration before askin
 
 Shared managed code keeps its canonical owner. When a consumer contains `CORE_BASELINE.json` or `DEPLOYMENT_BASELINE.json`, treat those baselines as ownership evidence. A temporary edit to a shared-managed consumer file may be used to diagnose or prove a reusable defect, but it is not the canonical deliverable.
 
-Before consumer delivery, run available managed-baseline integrity checks. If Core- or Deployment-Kit-managed files have unexplained local drift, stop before staging/commit/push and route the reusable change through `/upstream-fix`. Fix the owning canonical repository, deliver/merge it there under normal gates, then adopt the exact accepted shared commit back into the consumer through the appropriate update boundary and retest in consumer context.
+When reusable Project Forge drift is detected, distinguish unexplained drift from an explained temporary upstream proof. Unexplained managed drift remains fail-closed before delivery writes. For explained drift, route through `/upstream-fix`, preserve `.project-forge/UPSTREAM_FIX_HANDOFF.md`, and offer one explicit `Continue consumer work with acknowledged Project Forge drift` override when the current work can proceed without committing the managed workaround. That override is session/work-item continuation authority only; it does not authorize committing shared-managed paths, editing baselines, bypassing required CI/policy, or claiming that the canonical fix has been adopted.
+
+After an accepted continuation override, do not repeatedly halt normal consumer implementation solely because the same documented managed workaround remains present. Keep the handoff and workaround unstaged. Before consumer `/deliver`, warn about the acknowledged drift, selectively stage only accepted consumer-owned changes, and disclose when local validation depended on the workaround. Required CI/policy remains authoritative. If the workaround is staged, appears in the proposed consumer commit/PR, no longer matches the handoff, or ownership becomes ambiguous, stop and re-evaluate.
 
 Package-managed generated Projects use `/project-forge-update`. Direct `/core-sync` remains only for component-only Core consumers without `PROJECT_FORGE_BASELINE.json` and is not part of the normal greenfield Project command surface.
 

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -132,6 +132,8 @@ When application source/runtime exists, converge only the repository-owned local
 
 Verify supported tools/versions using repository setup/doctor tooling when present. Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions.
 
+Treat **installation**, **version compatibility**, and **operational readiness** as separate evidence when tooling exposes those distinctions. A successful CLI/version probe does not prove that the backing service/runtime is operational. For Docker-based setup, do not call the runtime ready merely because `docker --version` succeeds; require the repository/doctor operational probe before relying on Docker Engine capability.
+
 ### B. Local persistence
 
 For SQLite local development, resolve the project-owned database path and migration/initialization contract from repository evidence. Prefer installed Deployment Kit local SQLite ensure/status primitives when available.
@@ -244,6 +246,63 @@ For remote SSH preserve strict host identity. Unknown/changed host identity is a
 
 Remote readiness does not require configuring Production when the selected environment is non-Production. Production classification remains project topology/policy, not a literal-name check.
 
+### Guided remote failure recovery is part of `/setup`
+
+A supported deterministic setup/readiness failure is not, by itself, the end of `/setup`. When installed Deployment Kit tooling returns structured diagnosis or a bounded next action, continue through that diagnosis automatically until one of these boundaries is reached:
+
+- the failure is repaired through already-authorized routine setup work;
+- a missing human fact is required;
+- a separate write/Production/destructive authorization is required;
+- a trusted-console or already-authorized administrative action is required;
+- the capability is unsupported or remains blocked after bounded diagnosis.
+
+Do **not** merely repeat an opaque subprocess exit code and tell the developer to fix access independently when deterministic diagnosis is available.
+
+For SSH target-access failure, prefer the Deployment Kit's structured environment setup status/plan evidence. Preserve distinct categories such as:
+
+```text
+name resolution / address path
+TCP reachability
+host identity/trust
+server-advertised authentication methods
+configured identity fingerprint/offered key
+local signing/passphrase/agent failure
+remote public-key rejection
+remote account/source-policy rejection
+```
+
+Keep credentials, private keys, raw secure-prompt content, and unbounded SSH transcripts out of conversational diagnostics and journals.
+
+If client-side evidence shows that the configured key reached the server but access is still rejected, stop reinstalling the same key. Route to a trusted target console or already-authorized administrative session to inspect effective account/source policy. Do not guess that `AllowUsers`, `AllowGroups`, PAM, or another server rule is the exact cause until server-side evidence establishes it.
+
+### Gate password-assisted bootstrap on server capability
+
+Before recommending a password-assisted/Home Lab bootstrap against a reachable server, use deterministic evidence of the server-advertised authentication methods when the installed Deployment Kit supports that probe.
+
+- If password or keyboard-interactive authentication is not advertised, do not send the developer through a password bootstrap that cannot succeed.
+- Route instead to strict key onboarding plus a trusted console/already-authorized session for any required server-side key/account-policy change.
+- Never recommend enabling password SSH merely to make Project Forge onboarding work.
+
+For Production-class environments, prefer the higher-assurance Strict onboarding path for new target trust/access unless the project/operator explicitly chooses a different supported security profile. Staging and other non-Production environments use the same target-access mechanics, with their own environment classification and authorization policy.
+
+### Console-assisted recovery instructions
+
+When a trusted-console action is required, optimize for reliable execution rather than dense shell snippets:
+
+- one short command or one coherent semicolon-separated command per step;
+- avoid unnecessary wildcards, escaping, and shell-specific quoting;
+- say explicitly what the developer should run versus what output to return;
+- state the expected evidence and the stop condition;
+- use screenshot inspection when transcription is repeatedly failing.
+
+Never silently edit `sshd`, widen account/source policy, disable host verification, or switch authentication policy merely to make setup pass.
+
+### Treat target evidence and environment evidence separately
+
+A verified workstation-to-target access relationship may be reused by multiple Projects/environments that bind to the same logical target. Environment proof remains specific to the Project + named environment + target + adapter/isolation contract.
+
+When Staging and Production share one physical target, explicitly surface the shared failure domain and verify that their Project/environment-owned runtime identity, compose project, route/port allocation, persistence paths, and locking cannot collide. Staging evidence does not become Production evidence merely because the host is shared.
+
 ## 8. Prove supported remote mechanics with a disposable Project Forge probe
 
 When the installed Deployment Kit exposes environment proof operations, a selected remote environment should normally be taken through an end-to-end **environment proof deployment** during setup.
@@ -276,6 +335,8 @@ For a Production-class environment, keep the proof explicitly labeled as a **PRO
 
 If cleanup fails, report `PROOF PASSED — CLEANUP ACTION NEEDED`; do not claim a clean setup.
 
+When installed Deployment Kit provides a durable local proof receipt or equivalent discoverable evidence, record/reuse it rather than relying on chat history. Reuse only while its target binding, host identity, workstation identity, adapter/provenance, logical environment, and cleanup result remain applicable. A new chat alone must not invalidate valid machine evidence.
+
 ## 9. `repair` is bounded and fail-closed
 
 `/setup repair` may re-run safe deterministic setup/readiness operations after classifying the blocker. It may create missing local directories/caches, restore dependencies, rebuild outputs, create a new owned local database, run normal forward initialization, or recreate an owned disposable/local runtime when the repository contract permits those actions.

package/assets/generated/core/core/skills/upstream-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upstream-fix
-description: Route reusable bugs discovered in a consumer to the canonical shared repository, allow bounded upstream implementation, and return adoption through the consumer's actual provenance/update boundary.
+description: Route reusable bugs discovered in a consumer to the canonical shared repository, allow bounded upstream implementation, preserve a portable handoff, and let consumer work continue with explicitly acknowledged temporary Project Forge drift.
 argument-hint: "[optional problem summary]"
 user-invocable: true
 disable-model-invocation: true
@@ -15,8 +15,10 @@ The governing rule is:
 ```text
 discover in consumer
 → diagnose/prove in consumer
-→ fix in owning canonical repository
-→ deliver there
+→ classify canonical owner
+→ preserve a portable upstream handoff
+→ optionally continue consumer work with acknowledged temporary drift
+→ fix/deliver in owning canonical repository
 → adopt through the consumer's recorded distribution boundary
 → verify again in consumer
 ```
@@ -29,10 +31,11 @@ Invoking `/upstream-fix` authorizes:
 
 - read-only ownership/provenance inspection in the consumer;
 - classification to the smallest canonical owner;
+- creation/update of the ignored local handoff artifact `.project-forge/UPSTREAM_FIX_HANDOFF.md`;
 - inspection of already-available local canonical repository candidates;
 - when ownership and the bounded patch are clear and a canonical checkout is safe, routine creation/use of one short-lived canonical work branch and application of only that bounded fix plus focused tests/docs.
 
-Invocation does **not** authorize commit, push, PR creation, merge, release publication, package publication, deployment, rewriting/discarding consumer work, or changing multiple canonical repositories in one bounded fix.
+Invocation does **not** authorize commit, push, PR creation, merge, release publication, package publication, deployment, rewriting/discarding consumer work, changing multiple canonical repositories in one bounded fix, or committing a temporary shared-managed consumer workaround.
 
 Normal review and `/deliver` occur later while focused on the owning canonical repository.
 
@@ -99,7 +102,7 @@ Owner: package/platform repository supported by evidence
 
 If the package payload is correct but generation/publication/orchestration materializes it incorrectly, classify Bootstrap/control-plane ownership from evidence rather than patching a generated consumer.
 
-If ownership is genuinely ambiguous, stop at `UPSTREAM OWNER UNCLEAR`. Do not write to multiple repositories speculatively.
+If ownership is genuinely ambiguous, report `UPSTREAM OWNER UNCLEAR`. Preserve the observed evidence in the handoff artifact, but do not write to multiple repositories speculatively.
 
 ## 4. Temporary consumer proof
 
@@ -111,12 +114,95 @@ Report it explicitly:
 TEMPORARY SHARED-MANAGED PROOF
 Consumer path: <path>
 Canonical owner: <repo>
-Do not deliver this consumer copy.
+Do not deliver this consumer copy as product code.
 ```
 
 Do not silently discard the proof and do not stage/commit it as ordinary consumer implementation.
 
-## 5. Resolve a safe canonical checkout
+## 5. Preserve a portable handoff
+
+Once a likely shared owner exists, create or refresh:
+
+```text
+.project-forge/UPSTREAM_FIX_HANDOFF.md
+```
+
+This file is workstation/session evidence for transfer into ChatGPT or another canonical-owner workspace. It is not product documentation and must remain unstaged/uncommitted. Generated Project Forge projects normally ignore `.project-forge/`; if repository policy does not ignore it, keep the handoff out of the consumer delivery diff.
+
+Include only observed/non-secret evidence:
+
+```markdown
+# Project Forge Upstream Fix Handoff
+
+## Consumer context
+- Repository: <owner/repo or local identity>
+- Branch/work item: <observed>
+- Project Forge package/baseline: <observed version/commit/profile>
+
+## Classification
+- Owner: <Core | Deployment Kit | Platform | Bootstrap | Control Plane | unclear>
+- Canonical repository: <repo when known>
+- Managed consumer paths involved: <paths>
+
+## Problem
+<concise symptom and expected behavior>
+
+## Reproduction
+<minimal observed reproduction>
+
+## Temporary consumer proof
+- Status: <none | local proof present>
+- Paths: <paths>
+- Diff summary: <summary, not secrets>
+- Validation: <observed checks>
+
+## Recommended upstream scope
+<smallest reusable change and focused regression coverage>
+
+## Adoption boundary
+<package release / component sync / regeneration / other evidence-backed path>
+
+## Consumer continuation
+- Override: <not requested | accepted>
+- Managed workaround must remain unstaged/uncommitted: yes
+- Known dependency of current consumer checks on workaround: <yes/no/unknown>
+```
+
+The handoff is useful even when a canonical checkout is unavailable or the upstream fix will be handled later.
+
+## 6. Consumer continuation override
+
+A reusable-platform defect is **not automatically a reason to halt the consumer work item**.
+
+After classification/handoff, when the current consumer work can still proceed without committing the temporary shared-managed workaround, present one bounded single-select choice through the host-native question UI when available:
+
+- `Continue consumer work with acknowledged Project Forge drift` — permits the current consumer session/work item to continue while the shared-managed workaround remains local and excluded from delivery. **RECOMMENDED** when the workaround is isolated and continuing will produce useful consumer-owned work.
+- `Resolve the upstream fix now` — switch focus to the canonical owner and continue the upstream workflow.
+- `Stop here` — preserve state without further writes.
+
+Use a numbered text list only when native structured choice UI is unavailable.
+
+Selecting the continuation option means:
+
+```text
+PROJECT FORGE DRIFT OVERRIDE ACCEPTED
+```
+
+Record that choice in `.project-forge/UPSTREAM_FIX_HANDOFF.md` and continue normal consumer implementation. Do not repeatedly ask the same override question in the same unchanged session/work-item state.
+
+The override authorizes **continuation only**. It does not authorize:
+
+- staging/committing/pushing shared-managed drift;
+- editing baselines to bless the drift;
+- bypassing required CI, Reviewer, merge, release, or Production gates;
+- destructive cleanup of the workaround;
+- claiming the consumer has adopted the canonical fix.
+
+If consumer-owned implementation genuinely cannot be separated from the modified managed file, report that dependency clearly. The human may still continue exploratory/product work under the override, but normal delivery can only stage consumer-owned paths and required CI/policy may still fail until the upstream fix is distributed.
+
+Unexplained managed drift, suspected secrets, ambiguous ownership, or a staged/shared-managed workaround remains a stop condition until classified or removed from the proposed consumer delivery scope.
+
+## 7. Resolve a safe canonical checkout
 
 For the classified owner consider, in order:
 
@@ -128,7 +214,9 @@ Do not broadly scan the filesystem and do not clone automatically merely to cont
 
 A candidate is safe only when it is the expected repository, has no merge/rebase/cherry-pick in progress, has no unrelated local work, and does not require stash/reset/rebase/force/discard operations.
 
-## 6. Port the bounded fix upstream
+If no safe canonical checkout is available, the handoff plus continuation override is a valid outcome; do not block consumer implementation solely because canonical work cannot start immediately.
+
+## 8. Port the bounded fix upstream
 
 When a safe canonical checkout exists and the equivalent reusable fix is clear:
 
@@ -141,9 +229,9 @@ When a safe canonical checkout exists and the equivalent reusable fix is clear:
 7. run relevant local checks;
 8. show the meaningful canonical diff and observed validation.
 
-If the consumer proof cannot be generalized safely, stop and reclassify rather than forcing it upstream.
+If the consumer proof cannot be generalized safely, reclassify and update the handoff rather than forcing it upstream.
 
-## 7. Handoff to canonical delivery
+## 9. Handoff to canonical delivery
 
 When the upstream implementation is ready:
 
@@ -153,13 +241,16 @@ UPSTREAM FIX READY
 Owner: <canonical repo>
 Branch: <branch>
 Consumer proof: <path/status>
+Portable handoff: .project-forge/UPSTREAM_FIX_HANDOFF.md
 Validation: <observed checks>
 Next: focus the canonical repository and run /deliver
 ```
 
 `/upstream-fix` does not commit/push/open/merge the canonical PR itself.
 
-## 8. Adopt the accepted fix through the right boundary
+If the consumer continuation override was accepted, returning to consumer work does not wait for canonical delivery unless current work truly requires the distributed fix.
+
+## 10. Adopt the accepted fix through the right boundary
 
 After the canonical PR is merged and required default-branch CI is green, re-read the consumer provenance before choosing adoption.
 
@@ -182,7 +273,8 @@ Until that package exists, report:
 
 ```text
 PACKAGE RELEASE REQUIRED
-Consumer adoption is blocked on a Project Forge package that contains the accepted upstream commit.
+Canonical consumer adoption requires a Project Forge package that contains the accepted upstream commit.
+Consumer work may continue under an accepted drift override as long as shared-managed workaround paths remain outside consumer delivery.
 ```
 
 Do not silently patch `PROJECT_FORGE_BASELINE.json`, `CORE_BASELINE.json`, or `DEPLOYMENT_BASELINE.json` to pretend the package contains the new component.
@@ -199,15 +291,40 @@ A Deployment-owned fix may return through the canonical Deployment Kit component
 
 Validate through that platform's canonical regeneration/update path, never by manually editing generated managed files.
 
-Then rerun the original reproduction and baseline checks in the consumer.
+Then rerun the original reproduction and baseline checks in the consumer when adoption actually occurs.
+
+## 11. Consumer delivery guard
+
+Before consumer `/deliver`, distinguish **unexplained managed drift** from **explained/acknowledged temporary upstream proof**.
+
+### Unexplained managed drift
+
+If `/deliver` finds Core-, Deployment-, or Project Forge-package-managed drift with no matching upstream classification/handoff/override, stop before staging/commit/push and route through `/upstream-fix`.
+
+### Explained drift with accepted continuation override
 
-## 9. Consumer delivery guard
+When `.project-forge/UPSTREAM_FIX_HANDOFF.md` records the current managed paths and the human accepted continuation for the unchanged issue:
+
+1. warn prominently that Project Forge managed drift is still present;
+2. keep all shared-managed drift and the handoff file unstaged/uncommitted;
+3. selectively stage only the human-accepted consumer-owned implementation;
+4. disclose in the PR body that local validation may have used an acknowledged Project Forge workaround when that is true;
+5. proceed with normal PR/CI mechanics rather than hard-stopping solely because the local workaround exists.
+
+Use a compact warning such as:
+
+```text
+PROJECT FORGE DRIFT WARNING
+Upstream handoff: .project-forge/UPSTREAM_FIX_HANDOFF.md
+Managed workaround: present locally, excluded from consumer delivery
+Consumer delivery: continuing under accepted override
+```
 
-If `/deliver` is invoked in a consumer with unexplained Core-, Deployment-, or Project Forge-package-managed drift, stop before staging/commit/push. Route reusable managed-file changes through `/upstream-fix` and then through the appropriate accepted update boundary.
+Required CI/policy remains authoritative. Do not waive a failing required check because the failure is caused by the absent upstream fix.
 
-Consumer-owned changes may be delivered normally when managed baselines are clean.
+If any shared-managed path is already staged, appears in the proposed consumer commit/PR, no longer matches the handoff, or ownership becomes ambiguous, stop and re-evaluate before writing.
 
-## 10. Boundaries
+## 12. Boundaries
 
 `/upstream-fix` never:
 
@@ -218,4 +335,6 @@ Consumer-owned changes may be delivered normally when managed baselines are clea
 - auto-stashes, resets, rebases, force-pushes, or discards work;
 - requires ordinary consumer users to clone shared repositories;
 - treats a temporary managed consumer edit as a permanent fork;
-- bypasses `PROJECT_FORGE_BASELINE.json` with component-only sync.
+- bypasses `PROJECT_FORGE_BASELINE.json` with component-only sync;
+- treats the continuation override as authorization to commit shared-managed drift;
+- treats the continuation override as a waiver of required CI or merge policy.

package/assets/generated/deployment/docs/ENVIRONMENT_PROOF.md

@@ -56,6 +56,8 @@ project-forge-deploy environment setup plan <target> \
 
 These commands never perform the proof or authorize a write. They make `TARGET ACCESS READY`, `HOST PLATFORM READY`, and `DEPLOYMENT PATH PROVEN` separate states.
 
+When owner/repository and logical environment context are supplied, setup planning also checks the current workstation for a still-applicable prior proof receipt before recommending another proof run.
+
 ## Commands
 
 Read-only plan:
@@ -120,6 +122,8 @@ mutated
 finalMutationState
 error
 cleanupError
+receipt
+receiptError
 ```
 
 A read-only plan does not claim `mutated: false` as though it were the eventual run result. The run reports whether transfer/runtime mutation actually occurred and whether cleanup completed.
@@ -136,6 +140,28 @@ A loaded Docker image may remain cached after runtime cleanup. That state is rep
 
 The probe must not delete another Project, another application, another logical environment, or shared host platform state.
 
+## Workstation-local proof receipt
+
+Every terminal proof run attempts to write a compact workstation-local proof receipt under the user's Project Forge evidence directory. The receipt is diagnostic/readiness evidence only; it is not deployment authorization and is not repository content.
+
+The receipt records only non-secret evidence needed to decide whether the prior proof is still applicable, including:
+
+- Project owner/repository;
+- exact logical environment;
+- logical target name and Production classification;
+- Deployment Kit/proof contract version;
+- proof/cleanup/final mutation state;
+- immutable probe artifact identities when available;
+- a hash-based signature of the current target profile, configured workstation identity fingerprint, and target trust file.
+
+It never stores private keys, passwords, tokens, known-host contents, or application secrets.
+
+`environment setup plan` treats the receipt as `PROVEN` only when the latest receipt passed with terminal cleanup and still matches the current Project/environment/target context and current workstation target identity/trust. A target/profile/trust change, Production-classification change, proof-contract change, or Deployment Kit version change makes the evidence stale and causes a new proof to be planned.
+
+A **new chat or new assistant session alone does not invalidate proof**. Evidence validity is based on machine/project/environment facts, not conversation history.
+
+A failed proof may also leave a receipt, but that receipt is explicitly `not-proven` and is never promoted to readiness.
+
 ## Relationship to `/setup` and `/deploy`
 
 `/setup remote` or `/setup <environment>` may use deterministic setup status/plan first, then run this proof after the developer selects the named remote environment and the relevant write authorization is granted.

package/assets/generated/deployment/src/project_forge_deployment/environment_probe.py

@@ -14,6 +14,7 @@ from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .box_platform import platform_status
 from .errors import DeploymentKitError
 from .image_transfer import remote_image_present, transfer_image, verify_local_image
+from .proof_receipt import write_environment_proof_receipt
 from .registry_access import normalize_registry_image
 from .teardown import tear_down_project
 
@@ -152,6 +153,8 @@ def _proof_result(plan: dict[str, Any]) -> dict[str, Any]:
         "finalMutationState": "none",
         "error": None,
         "cleanupError": None,
+        "receipt": None,
+        "receiptError": None,
     }
 
 
@@ -298,4 +301,8 @@ def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
         result["error"] = "Environment proof cleanup did not return terminal runtime cleanup evidence."
 
     result["finalMutationState"] = _final_mutation_state(result)
+    try:
+        result["receipt"] = write_environment_proof_receipt(result)
+    except Exception as error:  # proof result stays truthful even if local evidence persistence fails
+        result["receiptError"] = str(error)
     return result