@mriekki/project-forge 4.12.0 → 4.13.1

package/README.md

@@ -113,6 +113,8 @@ Generated Projects receive an exact approved package during deterministic genera
 
 That Project workflow resolves the supported exact package version and preserves the managed-baseline, drift, review, and delivery guardrails. Do not use a floating `@latest` package update as the normal Builder path: npm publication can intentionally occur before the stable public contract is advanced to the new version.
 
+Package-managed updates follow the **Exact Managed Set** invariant: after a successful update, every path still managed by the selected package/profile has the package-defined content, and every previously managed path that the new package retires has either been removed or explicitly transferred out of Project Forge ownership. Unmanaged consumer files are not directory-mirrored or pruned. See [`docs/system/PROJECT_FORGE_EXACT_MANAGED_SET.md`](docs/system/PROJECT_FORGE_EXACT_MANAGED_SET.md).
+
 The package CLI remains available for exact-version troubleshooting and maintainer verification. Use the exact version recorded by the Project or selected by the Project Forge workflow rather than a floating tag.
 
 ## Maintainer system reference

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.12.0",
+  "version": "4.13.1",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "ed6a52538a03cb92850cafe0cb8404c39b8e5b89",
+      "revision": "a88c33ec1c93e120c70018a01c018f59dc2f74f2",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "8df115fe5c27fcf6647d7e87258166616e8e2e53",
+      "revision": "1119331414ec53e0c48b864403fabfef7998df60",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/core/distribution.json

@@ -5,6 +5,7 @@
   "mappings": [
     {"source":"core/agents/reviewer.agent.md","destination":".github/agents/reviewer.agent.md"},
     {"source":"core/instructions/project-forge-workflow.instructions.md","destination":".github/instructions/project-forge-workflow.instructions.md"},
+    {"source":"core/instructions/project-forge-local-development.instructions.md","destination":".github/instructions/project-forge-local-development.instructions.md"},
     {"source":"core/instructions/project-forge-docs.instructions.md","destination":".github/instructions/project-forge-docs.instructions.md"},
     {"source":"core/skills/define-feature/SKILL.md","destination":".github/skills/define-feature/SKILL.md"},
     {"source":"core/skills/grill-me/SKILL.md","destination":".github/skills/grill-me/SKILL.md"},
@@ -48,6 +49,7 @@
     {"source":"core/process/OPERATION_JOURNAL.md","destination":"docs/process/OPERATION_JOURNAL.md"},
     {"source":"core/process/PROJECT_REQUIREMENTS_EXPORT.md","destination":"docs/process/PROJECT_REQUIREMENTS_EXPORT.md"},
     {"source":"core/process/APPLICATION_VERSIONING.md","destination":"docs/process/APPLICATION_VERSIONING.md"},
+    {"source":"core/process/LOCAL_DEVELOPMENT_COMMANDS.md","destination":"docs/process/LOCAL_DEVELOPMENT_COMMANDS.md"},
     {"source":"core/templates/PULL_REQUEST_TEMPLATE.md","destination":".github/PULL_REQUEST_TEMPLATE.md"},
     {"source":"core/templates/PRODUCT_BRIEF_TEMPLATE.md","destination":"docs/templates/PRODUCT_BRIEF_TEMPLATE.md"},
     {"source":"core/templates/FEATURE_BRIEF_TEMPLATE.md","destination":"docs/templates/FEATURE_BRIEF_TEMPLATE.md"},

package/assets/deployment/distribution.json

@@ -42,6 +42,7 @@
     {"source": "src/project_forge_deployment/profiles.py", "destination": "tools/project-forge-deployment/project_forge_deployment/profiles.py"},
     {"source": "src/project_forge_deployment/project_topology.py", "destination": "tools/project-forge-deployment/project_forge_deployment/project_topology.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/recovery_scope.py", "destination": "tools/project-forge-deployment/project_forge_deployment/recovery_scope.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"},
@@ -62,6 +63,7 @@
     {"source": "docs/WORKSPACE_INSTANCES.md", "destination": "docs/project-forge/WORKSPACE_INSTANCES.md"},
     {"source": "docs/ENVIRONMENT_PROOF.md", "destination": "docs/project-forge/ENVIRONMENT_PROOF.md"},
     {"source": "docs/PROJECT_TOPOLOGY_BINDING.md", "destination": "docs/project-forge/PROJECT_TOPOLOGY_BINDING.md"},
+    {"source": "docs/RECOVERY_READINESS.md", "destination": "docs/project-forge/RECOVERY_READINESS.md"},
     {"source": "docs/images/developer-environment-journey.svg", "destination": "docs/project-forge/images/developer-environment-journey.svg"},
     {"source": "docs/images/personal-environment-architecture.svg", "destination": "docs/project-forge/images/personal-environment-architecture.svg"},
     {"source": "docs/images/project-environment-model.svg", "destination": "docs/project-forge/images/project-environment-model.svg"}

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.12.0",
+  "version": "4.13.1",
   "components": {
     "core": {
-      "revision": "ed6a52538a03cb92850cafe0cb8404c39b8e5b89",
+      "revision": "a88c33ec1c93e120c70018a01c018f59dc2f74f2",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -21,7 +21,12 @@
         {
           "source": "core/instructions/project-forge-workflow.instructions.md",
           "destination": ".github/instructions/project-forge-workflow.instructions.md",
-          "sha256": "dd440f677c9ed476bb8b7486500d8acbe2f796272582baadd4d6a60c3d1e662c"
+          "sha256": "3bb0abb63dd2e7a151c432d08eca85fe604cb043a865bfa337024ebd1c372301"
+        },
+        {
+          "source": "core/instructions/project-forge-local-development.instructions.md",
+          "destination": ".github/instructions/project-forge-local-development.instructions.md",
+          "sha256": "e7f884f123877b21913af111cde42fc0ff0ac82abe6fd18b8f4584d749fb6c3a"
         },
         {
           "source": "core/instructions/project-forge-docs.instructions.md",
@@ -46,7 +51,7 @@
         {
           "source": "core/skills/start-work/SKILL.md",
           "destination": ".github/skills/start-work/SKILL.md",
-          "sha256": "d7a592e64a4e64da5a9e03ee34bc4be4b1862c0d56ed5c71a657e268b4b8e9e5"
+          "sha256": "8a1213e59c5452feb5c8820530f6131115f88419299e42462ee5d32361d62fb6"
         },
         {
           "source": "core/skills/setup/SKILL.md",
@@ -56,12 +61,12 @@
         {
           "source": "core/skills/build/SKILL.md",
           "destination": ".github/skills/build/SKILL.md",
-          "sha256": "0659ad88cac5ca652eedba648d10a39ca1d51d65db638ce41b392067a3fd6128"
+          "sha256": "e7ba7663a99603f1212930045bec420c71774e56cad963e38867242605afdad4"
         },
         {
           "source": "core/skills/run/SKILL.md",
           "destination": ".github/skills/run/SKILL.md",
-          "sha256": "6bdf23f46609d1b85147347d313d7c4bf13bd8bfc91d4b782fc7a311189ffbe3"
+          "sha256": "3dfc25cff7b03eafe0b8d64cc2102584c7b90793f434313f62c9e61c1b587c9e"
         },
         {
           "source": "core/skills/export-requirements/SKILL.md",
@@ -181,7 +186,7 @@
         {
           "source": "core/process/HUMAN_GATES.md",
           "destination": "docs/process/HUMAN_IN_LOOP_GATES.md",
-          "sha256": "edad6bd5c659a1cbc6960ce76c269547ec616505b320409b6d3152326d4beaae"
+          "sha256": "d884eccd7e9e04d7c81868792adebcdc7f376206786ced37d467f81fca6dbd7f"
         },
         {
           "source": "core/process/GUIDED_NEXT_STEPS.md",
@@ -191,7 +196,7 @@
         {
           "source": "core/process/INTERACTIVE_SESSION_GUIDE.md",
           "destination": "docs/process/INTERACTIVE_SESSION_GUIDE.md",
-          "sha256": "9c4d2ef7eb974faea83dcd1c07c0684aaf351bfebe09186ef7e03cdf1c075c51"
+          "sha256": "f7573b9926878da3db4353db7297b66c9d907844142ae6486c7fd7580f187e3b"
         },
         {
           "source": "core/process/COACHING_GUIDE.md",
@@ -238,6 +243,11 @@
           "destination": "docs/process/APPLICATION_VERSIONING.md",
           "sha256": "846abd1085501bebf3ffd8025f875dcf2bfb3f57e67110e684c605ae11c3246b"
         },
+        {
+          "source": "core/process/LOCAL_DEVELOPMENT_COMMANDS.md",
+          "destination": "docs/process/LOCAL_DEVELOPMENT_COMMANDS.md",
+          "sha256": "44a62a68cbf211658d0e928f595b357fab3993eebbe5228ffeab9336b79e7ba6"
+        },
         {
           "source": "core/templates/PULL_REQUEST_TEMPLATE.md",
           "destination": ".github/PULL_REQUEST_TEMPLATE.md",
@@ -326,17 +336,17 @@
         {
           "source": "tools/vscode_work_item_status/extension/package.json",
           "destination": "tools/project-forge-vscode/work-item-status/extension/package.json",
-          "sha256": "09225a1d9a8a7ceebbba82aafb93a26342da10f1322949cf22061e40196e29df"
+          "sha256": "1dd1f7bba7f6e519ad73f1ee8ad67900cabec2ef475b1b6bc5db931ab9cd615b"
         },
         {
           "source": "tools/vscode_work_item_status/extension/extension.js",
           "destination": "tools/project-forge-vscode/work-item-status/extension/extension.js",
-          "sha256": "b4e70183bb101d879cc0d7834c51ee4cc48683339fca2c390eb3e49a3a3acdac"
+          "sha256": "2688291de42fab15edd3487cc17410bf57d8358e9f606e292dc44c9cb0439009"
         },
         {
           "source": "tools/vscode_work_item_status/extension/README.md",
           "destination": "tools/project-forge-vscode/work-item-status/extension/README.md",
-          "sha256": "b8fc17974024a84ee12f0fe43c38d379916e9e378f7c1efbf9a14da610af60e8"
+          "sha256": "54963b69bef2d9f763a6c92ad2c2b3105d3f10dd69542f72167de7e57db18982"
         },
         {
           "source": "tools/package/check_baseline.py",
@@ -351,7 +361,7 @@
       ]
     },
     "deployment": {
-      "revision": "8df115fe5c27fcf6647d7e87258166616e8e2e53",
+      "revision": "1119331414ec53e0c48b864403fabfef7998df60",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -549,6 +559,11 @@
           "destination": "tools/project-forge-deployment/project_forge_deployment/proof_receipt.py",
           "sha256": "9b4bbb559747fc4ee3ba984a050fc6425e532527ae82f9897c73e04d8d0291b6"
         },
+        {
+          "source": "src/project_forge_deployment/recovery_scope.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/recovery_scope.py",
+          "sha256": "1773369f26dea95795eb971a8433699897db74d6c38223c0d93c8626c3b9f2aa"
+        },
         {
           "source": "src/project_forge_deployment/registry_access.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py",
@@ -577,17 +592,17 @@
         {
           "source": "src/project_forge_deployment/sqlite_adapter.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter.py",
-          "sha256": "011615339f739316fb1350a7d4f1385a841744cf09c66da61c10e46f444c059f"
+          "sha256": "ab0fe2a1009ac1883ee7c9344c84240051648ccd1f05df9166cd81f6a216f893"
         },
         {
           "source": "src/project_forge_deployment/sqlite_adapter_remote.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_adapter_remote.py",
-          "sha256": "a21006aec6bfa235535fdde4441cf658bb1cec32bd27a0b3840babe77440c2fb"
+          "sha256": "6c7ba2c49f8ae97a28927f694df23b7f18de1247aac4bc4dce858859fb2199ed"
         },
         {
           "source": "src/project_forge_deployment/sqlite_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/sqlite_cli.py",
-          "sha256": "abee3a7fbef21f1a02b1511f5d050f90d9ef51afcd6714046c25b786568fb833"
+          "sha256": "37132cc141afe9196a96fd91db55597998886d037b2baded62526c08df148f5d"
         },
         {
           "source": "src/project_forge_deployment/sqlite_import_recovery.py",
@@ -649,6 +664,11 @@
           "destination": "docs/project-forge/PROJECT_TOPOLOGY_BINDING.md",
           "sha256": "50988ac1d797494bcb2d5dd6cece04f6313fb30179ca3132191dea75bcd759cd"
         },
+        {
+          "source": "docs/RECOVERY_READINESS.md",
+          "destination": "docs/project-forge/RECOVERY_READINESS.md",
+          "sha256": "ae94a858c9431ad1f432cb75e76b532d83f69c8ca163707ac12d9ea11c60edc1"
+        },
         {
           "source": "docs/images/developer-environment-journey.svg",
           "destination": "docs/project-forge/images/developer-environment-journey.svg",

package/assets/generated/core/core/instructions/project-forge-local-development.instructions.md

@@ -0,0 +1,28 @@
+---
+applyTo: "**"
+---
+
+# Project Forge Local Development Contract
+
+Keep Core stack-neutral and Projects operationally deterministic. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when it exists.
+
+When an Engineering Enabler or equivalent foundational work item first establishes executable application topology, establish unambiguous repository-owned build and run commands for the normal developer path. Do not require a particular wrapper language or invent placeholder commands before executable topology exists.
+
+For Feature Brief and Engineering Enabler implementation/validation, default application execution and persistence operations to the established Project-owned local developer runtime and its associated persistence unless the developer explicitly selects a supported alternative. When the Project defines a local container/database pair as that topology, do not silently substitute a native process or separate checkout database.
+
+If the established default runtime/persistence is absent, stopped, stale, or blocked by initialization/schema prerequisites, route through `/setup local` or the repository-owned repair workflow. Do not bypass it by selecting another runtime/database. Preserve `/run`'s no-implicit-setup/no-automatic-migration boundary.
+
+When a work item materially changes executable topology, assess and maintain the affected Project-owned engineering interfaces in the same accepted change:
+
+```text
+BUILD CONTRACT IMPACT
+RUN CONTRACT IMPACT
+SETUP CONTRACT IMPACT
+CI CONTRACT IMPACT
+```
+
+Examples include build-system changes, native/container changes, component composition, persistence ownership/location, launch profiles/ports, transport/authentication requirements, readiness checks, and stop/cleanup mechanics.
+
+Prefer the same underlying repository-owned build entry point in CI where practical. Preserve repository-required isolated/disposable test runtimes and databases; never redirect automated tests into mutable developer data merely to reuse the normal developer runtime.
+
+A failing or stale established build/run command is a Project contract problem. Do not silently bypass it with ecosystem-native inference. Framework-native discovery remains a fallback only while no Project-owned command contract exists yet or when the developer explicitly selects a supported alternative.

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

@@ -14,13 +14,15 @@ Use proportional rigor: `LIGHT`, `STANDARD`, `ELEVATED`.
 
 Keep explicit human gates for material requirements, substantive plans, meaningful implementation acceptance, the final merge/delivery decision, and production deployment.
 
-Before any substantive approval gate, identify the exact PRIMARY review subject and put the best available review surface in front of the human when the host supports it. Treat supporting documents as CONTEXT or TRACEABILITY instead of opening everything. For Markdown prefer rendered preview, for structured approval artifacts prefer formatted source plus a concise summary, for implementation acceptance prefer the meaningful diff/Source Control surface, and for plans prefer the native plan surface or durable plan document. Opening or foregrounding a review surface is read-only presentation and never implies approval.
+Before any substantive approval gate, identify the exact PRIMARY review subject for the current work item/scope and put the best available review surface in front of the human when the host supports it. Treat supporting documents as CONTEXT or TRACEABILITY instead of opening everything. For Markdown prefer rendered preview, for structured approval artifacts prefer formatted source plus a concise summary, for implementation acceptance prefer the meaningful diff/Source Control surface, and for plans prefer the native plan surface or durable plan document. Opening or foregrounding a review surface is read-only presentation and never implies approval.
 
-In VS Code, when the Project Forge companion extension is installed and the host can invoke VS Code commands, `projectForge.openReviewArtifact` may be used to foreground an exact workspace-relative repository artifact. Use a stronger native host review/diff surface when available.
+Every artifact-backed approval question must carry its own work-item/scope identity, approval purpose, exact PRIMARY artifact link/path, truthful presentation status, and consequence labels. Do not rely on links in earlier commentary, editor focus, a global plan, or another work item's artifact. The artifact named in the gate must be the same artifact requested/opened for review. If automatic opening is unavailable or fails, say so inside the gate and provide the exact link/path plus a deterministic manual fallback rather than fabricating success.
 
-For STANDARD/ELEVATED work, invoking `/start-work` authorizes context resolution, risk assessment, and planning only. It does **not** authorize substantive implementation or implementation branch setup by itself. Produce the final proposed plan, foreground its review surface, state that implementation has not started, and require an explicit `Approve plan and begin implementation [PLAN APPROVAL + CODE WRITE]` action before code writes or routine implementation branch setup. For ELEVATED work, Reviewer challenges the plan and material findings are reconciled before the human reviews the final proposed plan.
+In VS Code, when the Project Forge companion extension is installed, use the exact-path `projectForge.openReviewArtifact` command or Project Forge language-model review tool when the current host can invoke it. The helper is read-only, workspace-confined, must fail on ambiguous multi-root matches instead of guessing from editor focus, and should report actual presentation mode when available. Use a stronger native host review/diff surface when available.
 
-If implementation later requires a material change to the approved architecture, scope, schema/data handling, security model, externally visible behavior, major dependencies, or verification strategy, reopen the implementation-plan gate with the revised plan before continuing.
+For STANDARD/ELEVATED work, invoking `/start-work` authorizes context resolution, risk assessment, and planning only. It does **not** authorize substantive implementation or implementation branch setup by itself. Produce the final proposed plan, resolve the exact work-item-specific PRIMARY artifact when one exists, foreground that exact review surface, state that implementation has not started, include the same exact artifact link/path and presentation status inside the approval question, and require an explicit `Approve plan and begin implementation [PLAN APPROVAL + CODE WRITE]` action before code writes or routine implementation branch setup. For ELEVATED work, Reviewer challenges the plan and material findings are reconciled before the human reviews the final proposed plan.
+
+If implementation later requires a material change to the approved architecture, scope, schema/data handling, security model, externally visible behavior, major dependencies, or verification strategy, reopen the implementation-plan gate with the revised PRIMARY plan presented and linked before continuing. Stale approval does not authorize a materially changed plan.
 
 Once a bounded action is authorized, routine mechanics inside that scope should proceed without repeated ceremonial confirmation.
 
@@ -32,7 +34,7 @@ During interactive questioning, prefer concise choice-first options for genuinel
 
 When an authorized action requires a developer-owned interactive terminal prompt, follow the interactive-terminal handoff in `INTERACTIVE_SESSION_GUIDE.md`: collect any distinct bounded authorization first through the host-native structured control, then immediately provide the exact command in a standalone fenced code block, state the working directory when relevant, explain the local prompt briefly, keep passphrases/passwords/tokens/private keys local to the terminal, and say what result to report back for deterministic verification. Do not make the inability to inject terminal keystrokes the main response when a copyable command is sufficient. If the host can insert terminal text, insert only the non-secret command for human review/execution rather than silently executing the interactive step.
 
-Make a recommendation only when current evidence, repository policy, or a clear engineering tradeoff supports one. Mark exactly one supported choice with the host's `recommended` indicator when available and give a brief rationale. When the host does not expose recommendation metadata, append `[RECOMMENDED]` to exactly one option label and keep the rationale visible. A default/preselected option may match the recommendation, but a default alone must never communicate advice or human approval. If no option is clearly better, do not mark any option recommended and do not use a default that implies a preference. A recommendation is advice, not approval: record only the human's selected/confirmed answer. If the human asks for no recommendation on one decision, honor that for that decision only; later questions may still include evidence-backed recommendations.
+Make a recommendation only when current evidence, repository policy, or a clear engineering tradeoff supports one. Mark exactly one supported choice with the host's `recommended` indicator when available and give a brief rationale. When the host does not expose recommendation metadata, append `[RECOMMENDED]` to exactly one option label and keep the rationale visible. A default/preselected option may match the recommendation, but a default alone must never communicate advice or human approval. If no option is clearly better, do not mark any option recommended and do not use a default that implies preference. A recommendation is advice, not approval: record only the human's selected/confirmed answer. If the human asks for no recommendation on one decision, honor that for that decision only; later questions may still include evidence-backed recommendations.
 
 Keep factual/environment-specific values and questions intended to elicit the human's own framing, reasoning, debugging approach, design rationale, or understanding open-ended unless options are later useful as scaffolding.
 

package/assets/generated/core/core/process/HUMAN_GATES.md

@@ -41,10 +41,22 @@ When the current host supports opening or foregrounding the PRIMARY review surfa
 
 Do not open every supporting document and steal focus. Open the PRIMARY surface; name CONTEXT and TRACEABILITY material explicitly and make it easy to open when needed.
 
-If the host cannot open the review surface automatically, provide an explicit path/link and enough concise review context that the human knows exactly what to inspect. Never imply that a path reference alone is equivalent to review.
+Every artifact-backed approval question must be self-contained. The gate itself must identify:
+
+- the specific work item or approval scope;
+- the exact approval purpose/subject;
+- the exact PRIMARY artifact path or clickable link that is being approved;
+- presentation status when an automatic open was attempted (`rendered Markdown opened`, `editor fallback opened`, `automatic opening unavailable/failed`, or equivalent truthful evidence);
+- the consequence labels for each action.
+
+Do not rely on an artifact link in earlier commentary, the active editor, a global plan, or another work item's document. The PRIMARY artifact named in the gate must be the same artifact that was requested/opened for presentation.
+
+If the host cannot open the review surface automatically, provide the exact path/link inside the approval question and a deterministic manual fallback. For Markdown in VS Code on Windows, the fallback may say to open that exact file and press `Ctrl+Shift+V`. Never imply that a path reference alone is equivalent to review.
 
 Opening, previewing, foregrounding, or navigating to a review surface is **read-only presentation**. It never communicates approval, authorization, or acceptance. Only the explicit gate choice does that.
 
+If the PRIMARY artifact changes materially after approval, present and link the revised PRIMARY artifact before asking again. Navigation, preview, cancellation, or a `where is it?` question never preserves or creates approval for a materially changed subject.
+
 Do not gate routine mechanics individually after a bounded action is already authorized.
 
 Missing access to GitHub admin policy metadata is not itself a human gate. Use configured workflow/check results, PR mergeability, repository documentation, and any observable enforced policy as evidence. Do not ask the human to open GitHub Settings and transcribe branch-protection/ruleset check names merely to continue; ask only when unavailable policy information creates a material unresolved decision at merge, release, or another consequential action.
@@ -64,13 +76,18 @@ requirements/context ready
 → substantive implementation
 ```
 
-Before the approval choice, state unambiguously that implementation has **not** started. The gate should identify the work item, risk level, review subject, key plan coverage, and any unresolved material decisions.
+Before the approval choice, state unambiguously that implementation has **not** started. The gate should identify the work item, risk level, exact review subject/artifact, presentation status, key plan coverage, and any unresolved material decisions.
 
 Use an explicit action set equivalent to:
 
 ```text
 IMPLEMENTATION PLAN REVIEW REQUIRED
 
+Work item: <ID / key / concise change>
+Approval subject: final proposed implementation plan
+Primary artifact: <exact clickable plan link/path | native plan surface>
+Presentation: <rendered Markdown opened | editor fallback opened | automatic opening unavailable/failed | native plan foregrounded>
+
 Implementation has NOT started.
 
 1. Approve plan and begin implementation [PLAN APPROVAL + CODE WRITE]
@@ -79,11 +96,11 @@ Implementation has NOT started.
 4. Stop [NO ACTION]
 ```
 
-When the host exposes structured choice UI, render these as a single-select decision instead of a numbered menu while preserving the consequence labels.
+When the host exposes structured choice UI, render these as a single-select decision instead of a numbered menu while preserving the consequence labels and the same work-item/artifact context in the question itself.
 
 For ELEVATED work, Reviewer challenges the proposed plan before the human gate. Reconcile material Reviewer findings into the final proposed plan, then put that final plan in front of the human. Do not ask the human to approve an initial plan while separate Reviewer objections remain unresolved.
 
-After approval, routine implementation details may evolve without ceremonial re-approval. Reopen the plan gate when evidence requires a **material** change to approved architecture, scope, schema/data handling, security model, externally visible behavior, major dependencies, or verification strategy. Show what changed, why it changed, and the revised plan before implementation continues.
+After approval, routine implementation details may evolve without ceremonial re-approval. Reopen the plan gate when evidence requires a **material** change to approved architecture, scope, schema/data handling, security model, externally visible behavior, major dependencies, or verification strategy. Show what changed, why it changed, and the revised plan before implementation continues. The renewed gate must link/present the revised PRIMARY artifact rather than relying on the stale approved plan.
 
 ## Implementation branch setup
 

package/assets/generated/core/core/process/INTERACTIVE_SESSION_GUIDE.md

@@ -49,10 +49,11 @@ Presentation rules:
 
 Before a substantive approval gate, follow the review-surface contract in `HUMAN_GATES.md`.
 
-1. Identify the exact PRIMARY review subject.
+1. Identify the exact PRIMARY review subject for the current work item/gate.
 2. Separate supporting CONTEXT and TRACEABILITY material when useful.
 3. Put the best available PRIMARY review surface in front of the human before asking for approval.
-4. Only then render the explicit approval/action choice.
+4. Capture the actual presentation result when the host reports one.
+5. Render the explicit approval/action choice with the same exact work-item/artifact identity inside the question itself.
 
 Use the host's native surface when it is stronger than prose:
 
@@ -62,16 +63,24 @@ Use the host's native surface when it is stronger than prose:
 - implementation acceptance → Source Control / meaningful diff review;
 - PR acceptance → exact PR/diff surface at the observed head.
 
-In VS Code, when the Project Forge companion extension is installed and the host can invoke VS Code commands, `projectForge.openReviewArtifact` is the preferred Project Forge-owned action for repository artifacts. Pass the exact workspace-relative artifact path. The command is presentation-only and must reject targets outside the open workspace. For Markdown it opens rendered preview when available; other supported artifacts open in editor preview.
+In VS Code, when the Project Forge companion extension is installed and the host can invoke VS Code commands, `projectForge.openReviewArtifact` is the preferred Project Forge-owned action for repository artifacts. Pass the exact workspace-relative artifact path. The command is presentation-only and must reject targets outside the open workspace and ambiguous multi-root matches rather than guessing from editor focus.
 
-If the host exposes its own safe resource-opening or diff-opening capability, it may use that directly instead. Do not require the Project Forge command when the host already provides a stronger native review surface.
+On hosts that expose the Project Forge language-model review tool, use it only with the exact already-resolved PRIMARY artifact path. Its result is presentation evidence, not approval. The result should distinguish resolved artifact URI, requested presentation mode, actual opened mode, cancellation, and failure/unavailable state. For Markdown, distinguish rendered Markdown from ordinary editor-preview fallback.
 
-Do not automatically open every supporting document. Foreground only the PRIMARY review subject and list supporting context explicitly. If automatic opening is unavailable, provide a direct path/link and state that the human must open/review it before approving.
+If the host exposes its own safe resource-opening or diff-opening capability, it may use that directly instead. Do not require the Project Forge command/tool when the host already provides a stronger native review surface.
 
-Opening a review surface is never approval. A preview event, editor focus, file read, diff display, or navigation action is read-only presentation and must not advance a gate.
+Do not automatically open every supporting document. Foreground only the PRIMARY review subject and list supporting context explicitly.
+
+For every artifact-backed gate, put the exact artifact path/link inside the approval question itself. Do not make the human hunt through earlier commentary for the link. The question should also identify the work item, approval purpose, and truthful presentation status.
+
+If automatic opening is unavailable or fails, say so briefly in the gate and provide a deterministic fallback. For Markdown in VS Code on Windows, tell the human to open the exact linked file and press `Ctrl+Shift+V`. Do not block planning merely because automatic opening is unavailable, and never fabricate a successful open.
+
+Opening a review surface is never approval. A preview event, editor focus, file read, diff display, navigation action, cancellation, or `where is it?` question is read-only presentation and must not advance a gate.
 
 For an implementation-plan gate, explicitly state that implementation has **not** started before offering approval. The approval action must be distinct from plan revision/read-only review actions.
 
+When the approval subject changes materially, present and link the revised PRIMARY artifact before asking again. Do not reuse stale presentation evidence or stale approval for the revised subject.
+
 ### Recommendations inside choices
 
 A recommendation is optional advice, not a required field and not an accepted decision.

package/assets/generated/core/core/process/LOCAL_DEVELOPMENT_COMMANDS.md

@@ -0,0 +1,103 @@
+# Local Development Command Contract
+
+## Principle
+
+Project Forge Core is generic; each executable Project should become deterministic.
+
+Bootstrap and early discovery do not need to know framework-specific build/run mechanics. Once an Engineering Enabler or equivalent foundational work item establishes executable application topology, the Project should expose unambiguous repository-owned commands for normal developer build and run behavior.
+
+This contract does not require literal `build.ps1` or `run.ps1` files and does not introduce a `PROJECT_COMMANDS.json` registry. A repository-owned command may be a wrapper script, package/task script, Compose command, build-tool target, Make target, or another deterministic command already owned by the Project.
+
+## Establishment
+
+When the first foundational Engineering Enabler makes the application executable, establish the normal local developer contract as applicable:
+
+```text
+Build ........ authoritative Project-owned build command
+Run .......... authoritative Project-owned developer runtime command
+Persistence .. runtime-associated developer persistence, when applicable
+Stop ......... how the normal developer runtime is stopped
+Readiness .... what proves the selected runtime is actually ready
+Transport .... required local HTTP/HTTPS/authentication properties when applicable
+```
+
+If application scaffolding or runtime is intentionally deferred, do not create placeholder commands merely to satisfy this contract. Ecosystem-native inference may remain a temporary fallback until executable topology exists.
+
+## Default runtime and persistence
+
+For Feature Brief and Engineering Enabler implementation/validation, use the established Project-owned local developer runtime and its associated persistence by default unless the developer explicitly selects a supported alternative.
+
+When the Project defines a local container and associated database as its developer topology, that container/database pair is the default. Do not silently substitute a native process or separate checkout database merely because an ecosystem-native command is easier to invoke.
+
+If the default runtime is absent, stopped, stale, or blocked by missing/pending schema prerequisites, route through `/setup local` or the repository-owned repair workflow. Do not bypass the problem by selecting another runtime/database.
+
+An explicit developer selection may authorize a supported alternative within the relevant operation's existing boundaries. Once selected, inspect and operate only against that runtime and its persistence.
+
+Automated tests remain separate: preserve isolated/disposable test databases or runtimes required by the repository's test contract. Never redirect tests into mutable developer data merely to reuse the developer run contract.
+
+## Build command lifecycle
+
+`/build` prefers the established Project-owned build command. Once that command exists, it is authoritative for the normal build target; a failing or stale wrapper is a Project contract problem, not permission to silently bypass it with framework-native fallback.
+
+Where practical, CI should invoke the same underlying repository-owned build entry point so local and CI build semantics do not drift.
+
+A work item that materially changes build topology should assess and update the build contract in the same accepted change. Examples include:
+
+- changing build systems or package managers;
+- splitting/combining application components;
+- changing generated artifacts or build outputs;
+- moving from native build orchestration to containerized build orchestration;
+- changing required build-time configuration or dependency preparation.
+
+## Run command lifecycle
+
+`/run` prefers the established Project-owned runtime and associated persistence. A work item that materially changes local runtime topology should assess and update the run contract in the same accepted change. Examples include:
+
+- native/container topology changes;
+- frontend/backend composition changes;
+- persistence engine/path/volume changes;
+- launch-profile or port changes;
+- HTTP/HTTPS or authentication transport changes;
+- required initialization/migration/readiness behavior;
+- stop/cleanup mechanics.
+
+The run command must not hide setup or destructive repair. `/run` may perform read-only prerequisite checks, but normal installation, forward initialization/migration, container convergence, or repair remain owned by `/setup` or repository-specific setup tooling.
+
+## Readiness semantics
+
+Process startup is not application readiness.
+
+Keep these dimensions distinct:
+
+```text
+Process startup
+Artifact/version identity
+Persistence/schema readiness
+Transport readiness
+Functional checks actually performed
+```
+
+A successful `/version` call, open database connection, or connection-only health endpoint does not prove schema compatibility, authentication usability, OAuth readiness, or another user workflow unless that condition is independently verified.
+
+When safe non-mutating verification is unavailable, report the gap instead of inventing confidence.
+
+## Command resolution fallback
+
+Core remains stack-neutral. `/build` and `/run` may still infer an unambiguous ecosystem-native command when no Project-owned command exists yet. That is a fallback for early/incomplete Projects, not the preferred mature state.
+
+Once a Project-owned command exists, do not silently fall through to a different native command because the authoritative command fails. Fix or explicitly change the Project contract through the relevant accepted work item.
+
+## Work-item maintenance rule
+
+For Feature Brief and Engineering Enabler work that materially changes executable application topology, the implementation/review should assess these impacts before delivery:
+
+```text
+BUILD CONTRACT IMPACT
+RUN CONTRACT IMPACT
+SETUP CONTRACT IMPACT
+CI CONTRACT IMPACT
+```
+
+Update affected Project-owned commands and documentation in the same work item rather than leaving them for rediscovery in a later session.
+
+This is an engineering-interface maintenance rule, not a requirement that every work item touch build/run files.

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

@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 # Build
 
-`/build` is a thin local helper. It hides framework-specific command details while preserving the repository as the authority for how the project builds.
+`/build` is a thin local helper. Core stays stack-neutral; the Project becomes deterministic by exposing a repository-owned build command once executable application topology exists. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when present.
 
 ## Contract
 
@@ -16,12 +16,17 @@ Invoking `/build` authorizes one bounded local build attempt for the requested t
 
 Resolve the build command from current repository evidence in this order:
 
-1. an explicit repository-owned build wrapper or documented build command;
-2. an explicit package/task script whose purpose is build;
-3. an unambiguous ecosystem-native build entry point already present in the repository.
+1. an explicit developer-selected supported build target, when one was supplied;
+2. an explicit repository-owned build wrapper or documented command;
+3. an explicit package/task script whose purpose is build;
+4. an unambiguous ecosystem-native build entry point already present in the repository, but only when the Project has not yet established a repository-owned build contract.
 
 Do not invent a command because a framework is recognizable. If multiple materially different build targets exist and no default is documented, require a target such as `/build web`, `/build api`, or `/build all`.
 
+Once an executable Project has an established repository-owned build command, treat that command as authoritative. If it is missing, stale, or fails because the Project topology changed, report the contract problem; do not silently bypass it with a framework-native fallback. The work item that materially changes build topology should maintain the Project-owned build command in the same accepted change.
+
+During an intentionally deferred or first-scaffold phase, ecosystem-native inference remains a fallback. Repeated inference is not the preferred mature Project state.
+
 ## Preconditions
 
 Before execution:
@@ -40,7 +45,7 @@ If dependencies or workstation tools are missing, recommend `/setup` rather than
 Run the selected build visibly and report:
 
 - target;
-- resolved repository-owned command identity;
+- resolved repository-owned command identity, or clearly labeled inference fallback when no Project-owned command exists yet;
 - success/failure and exit code when available;
 - produced artifact/output locations when the build contract makes them explicit;
 - effective application release/build identity when the build exposes it;