@mriekki/project-forge 4.0.0 → 4.2.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "e20e9b0e7102477a30bc15a771d62ba537efe60c",
+      "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": "0974f36bcb5062c4becb7c5c4e0fbc3e629ad4a9",
+      "commit": "e974c227d9d0768e64605550709db89ccaf93434",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -18,6 +18,7 @@
     {"source": "src/project_forge_deployment/entrypoint.py", "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py"},
     {"source": "src/project_forge_deployment/environment_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_cli.py"},
     {"source": "src/project_forge_deployment/environment_probe.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py"},
+    {"source": "src/project_forge_deployment/environment_setup.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_setup.py"},
     {"source": "src/project_forge_deployment/errors.py", "destination": "tools/project-forge-deployment/project_forge_deployment/errors.py"},
     {"source": "src/project_forge_deployment/home_lab.py", "destination": "tools/project-forge-deployment/project_forge_deployment/home_lab.py"},
     {"source": "src/project_forge_deployment/image_transfer.py", "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py"},
@@ -30,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.0.0",
+  "version": "4.2.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "e20e9b0e7102477a30bc15a771d62ba537efe60c",
+      "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",
@@ -102,12 +102,12 @@
         {
           "source": "core/skills/project-forge-update/SKILL.md",
           "destination": ".github/skills/project-forge-update/SKILL.md",
-          "sha256": "3463a68171fa30ef10f1ca514424236317ec364f015c5446f49911a1a3c9bb12"
+          "sha256": "510d60fab8d91e54abbc49dbc963a93b132ac5cdfd97ec87f64128ca138d2b1a"
         },
         {
           "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": "0974f36bcb5062c4becb7c5c4e0fbc3e629ad4a9",
+      "commit": "e974c227d9d0768e64605550709db89ccaf93434",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -364,7 +364,7 @@
         {
           "source": "src/project_forge_deployment/app_runtime_workstation.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_workstation.py",
-          "sha256": "a176074fc7948b802f22adb03730d53b12aac520ba476604a2a9c1e8e29a52b4"
+          "sha256": "17723294fffce40433343df5fd26817df037a8029d473acefa6b767a56c9f725"
         },
         {
           "source": "src/project_forge_deployment/box_platform.py",
@@ -399,12 +399,17 @@
         {
           "source": "src/project_forge_deployment/environment_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_cli.py",
-          "sha256": "ccb38228bd8bf975f9ca9c9298b172b23bec4af7192da0c1cf3aa39bde4dce2d"
+          "sha256": "3c8a0c67c8b75fed7374d1b7b013f95392f84661b6ea182187d07a2b48f206ae"
         },
         {
           "source": "src/project_forge_deployment/environment_probe.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py",
-          "sha256": "3971264b425c9eb49845a48a54aea849ef35b36b86b13017c0946d3b90e9d707"
+          "sha256": "4e9a49a7cf0427dcdef1e28f955297569ec8cd0ee9d071404ef876e3ce036313"
+        },
+        {
+          "source": "src/project_forge_deployment/environment_setup.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/environment_setup.py",
+          "sha256": "a79919da8655a6c42fded3224373f6381d15c8c68869b70c31d6edb7702fd348"
         },
         {
           "source": "src/project_forge_deployment/errors.py",
@@ -414,12 +419,12 @@
         {
           "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",
           "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py",
-          "sha256": "de8666d8687e1544603fa259c6b302f2f29ab699e6d01b8795b9fce28821c7ed"
+          "sha256": "dadd1fe7724372a4ca0e04ab2280769b6c2381f0f9ae75a096f6c5a5f5add755"
         },
         {
           "source": "src/project_forge_deployment/keys.py",
@@ -466,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",
@@ -514,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",
@@ -539,7 +549,7 @@
         {
           "source": "docs/DEVELOPER_ENVIRONMENTS.md",
           "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md",
-          "sha256": "e818931055044f6158ffe321303a5cbcd2f58724430d51e87c1688e1f71a8fbc"
+          "sha256": "cac10b7e30db24992225a88b43e16aa55404317c87a2ef136f21a2589ee4dc5f"
         },
         {
           "source": "docs/WORKSPACE_INSTANCES.md",
@@ -549,7 +559,7 @@
         {
           "source": "docs/ENVIRONMENT_PROOF.md",
           "destination": "docs/project-forge/ENVIRONMENT_PROOF.md",
-          "sha256": "d139ec1691d073e845a679edf45cb01c971a40b3ccc31404efb8c1e81e481ea5"
+          "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/project-forge-update/SKILL.md

@@ -49,7 +49,7 @@ Do not synthesize or repair missing umbrella provenance by hand.
 
 If `PROJECT_BOOTSTRAP.json` exists, treat it as approved generated-consumer provenance, not unrelated product data.
 
-Before planning an update, require `generation.projectForge.package`, `generation.projectForge.version`, and `generation.projectForge.profile` to agree exactly with the installed `PROJECT_FORGE_BASELINE.json`. Require `generation.projectForge.integrity` to be a non-empty exact registry integrity value for that installed package/version. Verify that integrity read-only from the registry when registry access is available.
+Before planning an update, require `generation["project-forge"].package`, `generation["project-forge"].version`, and `generation["project-forge"].profile` to agree exactly with the installed `PROJECT_FORGE_BASELINE.json`. Require `generation["project-forge"].integrity` to be a non-empty exact registry integrity value for that installed package/version. Verify that integrity read-only from the registry when registry access is available.
 
 If those values disagree before the update, report `GENERATED PROJECT FORGE METADATA DRIFT` and stop. Do not use `/project-forge-update` to silently reconcile an already-incoherent generated consumer.
 
@@ -117,7 +117,7 @@ A modified retired Core path is different: never auto-add `--accept-retired core
 
 For a Bootstrap-generated consumer, also preview the companion generated-consumer changes:
 
-- `PROJECT_BOOTSTRAP.json` keeps the same package/profile but changes `generation.projectForge.version` and `generation.projectForge.integrity` to the exact reviewed target;
+- `PROJECT_BOOTSTRAP.json` keeps the same package/profile but changes `generation["project-forge"].version` and `generation["project-forge"].integrity` to the exact reviewed target;
 - generated package-verification surfaces should consume `PROJECT_BOOTSTRAP.json` dynamically when the accepted Bootstrap contract supports that form;
 - a recognized older Bootstrap-generated verification block may be migrated only when its embedded old package/version/integrity exactly match the currently approved manifest metadata;
 - an unrecognized or locally modified generated verification surface is a stop condition, not permission to reconstruct Bootstrap output by hand.
@@ -152,7 +152,7 @@ Choosing `Apply the exact Project Forge package update` authorizes only:
 - creation/switch to one repository-appropriate short-lived update branch when needed;
 - exact target package apply;
 - removal of unchanged retired package-managed files that the reviewed preview classified as `REMOVE`;
-- when `PROJECT_BOOTSTRAP.json` is present, update of its exact `generation.projectForge.version` and `generation.projectForge.integrity` to the reviewed target while preserving package/profile;
+- when `PROJECT_BOOTSTRAP.json` is present, update of its exact `generation["project-forge"].version` and `generation["project-forge"].integrity` to the reviewed target while preserving package/profile;
 - migration of a recognized Bootstrap-generated package-verification block from duplicated current literals to the accepted manifest-driven form, only when the existing block still exactly matches the current approved metadata;
 - package/baseline/generated-consumer verification;
 - inspection of the resulting meaningful diff.

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.