@mriekki/project-forge 4.11.2 → 4.13.0

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.11.2",
+  "version": "4.13.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "78a3fbe722ea277eaad4d2082d239cd7afd3d064",
+      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
       "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.11.2",
+  "version": "4.13.0",
   "components": {
     "core": {
-      "revision": "78a3fbe722ea277eaad4d2082d239cd7afd3d064",
+      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
       "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": "5b1fffa81451f92f29c839d1219168a72ce625a1d8eed952a9946adf0a66b84b"
+          "sha256": "dd440f677c9ed476bb8b7486500d8acbe2f796272582baadd4d6a60c3d1e662c"
+        },
+        {
+          "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",
@@ -41,12 +46,12 @@
         {
           "source": "core/skills/refine-requirements/SKILL.md",
           "destination": ".github/skills/refine-requirements/SKILL.md",
-          "sha256": "9e76b9c3700a00af8852928d4e6bf1aeca9a24c6cc8fc9b2f1873e0198b63962"
+          "sha256": "5787cd7f70231355b951d58f792665a79da336d6f17ea9f4d6634928ab452623"
         },
         {
           "source": "core/skills/start-work/SKILL.md",
           "destination": ".github/skills/start-work/SKILL.md",
-          "sha256": "f054edd5a745489623579d25e334f5fcd6cebd6e73b86970074e7c2444f9af40"
+          "sha256": "d7a592e64a4e64da5a9e03ee34bc4be4b1862c0d56ed5c71a657e268b4b8e9e5"
         },
         {
           "source": "core/skills/setup/SKILL.md",
@@ -56,22 +61,22 @@
         {
           "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",
           "destination": ".github/skills/export-requirements/SKILL.md",
-          "sha256": "6ef2675eafdbcc809f6fb9533ab41ff032a1f3ff4789b1d5825d27cf696d0715"
+          "sha256": "dd82f05b6e2ec7ecf8e7a8592066fd8c6d623c1f184f49838b1e95eb5b53320a"
         },
         {
           "source": "core/skills/replatform/SKILL.md",
           "destination": ".github/skills/replatform/SKILL.md",
-          "sha256": "86e17bf376f395e5f5f018d8def7f5d99b9f4baef30c0b1d20f5caaac5c993c8"
+          "sha256": "561796a829b9c12f8bd2e526f8fe86cbd33d258a5c6b04ca581721e07d984ca7"
         },
         {
           "source": "core/skills/progress/SKILL.md",
@@ -181,7 +186,7 @@
         {
           "source": "core/process/HUMAN_GATES.md",
           "destination": "docs/process/HUMAN_IN_LOOP_GATES.md",
-          "sha256": "ac6ab2343728679d2ae50e9872b4b2f52a49605a2ea7ed17d806a839da4376c1"
+          "sha256": "edad6bd5c659a1cbc6960ce76c269547ec616505b320409b6d3152326d4beaae"
         },
         {
           "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": "159bd76122f49be9f2a31d5766fb8a06e9179caef8c6c3eb03bc750685fe73f6"
+          "sha256": "9c4d2ef7eb974faea83dcd1c07c0684aaf351bfebe09186ef7e03cdf1c075c51"
         },
         {
           "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": "3ae6351df5aa0fa4908e0e4456c84ac6e9477fde0074226d1aac0316f23b9116"
+          "sha256": "09225a1d9a8a7ceebbba82aafb93a26342da10f1322949cf22061e40196e29df"
         },
         {
           "source": "tools/vscode_work_item_status/extension/extension.js",
           "destination": "tools/project-forge-vscode/work-item-status/extension/extension.js",
-          "sha256": "50b7551c1abc1c30552945dedaf602569dfdf770cad0b2d4652e46f2910231d8"
+          "sha256": "b4e70183bb101d879cc0d7834c51ee4cc48683339fca2c390eb3e49a3a3acdac"
         },
         {
           "source": "tools/vscode_work_item_status/extension/README.md",
           "destination": "tools/project-forge-vscode/work-item-status/extension/README.md",
-          "sha256": "9e1d1e8b53d27c07e8de72d38db420740d7e1b3301ab146531d89882cd088418"
+          "sha256": "b8fc17974024a84ee12f0fe43c38d379916e9e378f7c1efbf9a14da610af60e8"
         },
         {
           "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,6 +14,14 @@ 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.
+
+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.
+
+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.
+
+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.
+
 Once a bounded action is authorized, routine mechanics inside that scope should proceed without repeated ceremonial confirmation.
 
 For implementation, establish the repository-appropriate short-lived work branch as routine setup once implementation itself is authorized; do not add a separate branch-creation gate when branch policy/naming and scope are clear.

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

@@ -18,10 +18,73 @@ Workspace/setup acceptance is distinct from generation or installation. Generate
 
 A human gate is meaningful only when the human understands what is being approved. If the explanation immediately before a gate did not land, re-explain it before asking for approval again. `/wait-what` is the standard read-only communication-repair path when available; invoking it never implies approval of the pending action.
 
+## Human review surface contract
+
+Before asking for any substantive human approval, identify the exact **review subject** and put the best available review surface in front of the human.
+
+Classify review material when more than one artifact is relevant:
+
+```text
+PRIMARY — the artifact/diff/plan the human is deciding on
+CONTEXT — supporting material that may help review
+TRACEABILITY — provenance/reference material that is not itself being approved
+```
+
+When the current host supports opening or foregrounding the PRIMARY review surface, do so automatically immediately before the gate. Prefer the surface that best matches the decision:
+
+- Markdown requirements, briefs, ADRs, and design documents → rendered Markdown preview when available;
+- structured JSON approval artifacts → formatted source/editor preview plus a concise human-readable summary;
+- implementation plans → the host's native plan surface, or a durable plan document when one exists;
+- implementation acceptance → the meaningful local diff / Source Control review rather than a prose-only file list;
+- final PR acceptance → the observed PR/diff at the exact reviewed head;
+- other repository artifacts → the host's safest read-only preview/editor surface.
+
+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.
+
+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.
+
 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.
 
+## Implementation-plan review gate
+
+For STANDARD/ELEVATED work, invoking `/start-work` authorizes requirement/context inspection, risk assessment, and implementation planning. It does **not** authorize substantive implementation by itself.
+
+The required boundary is:
+
+```text
+requirements/context ready
+→ implementation plan produced
+→ PRIMARY plan review surface opened/foregrounded when supported
+→ HUMAN IMPLEMENTATION-PLAN APPROVAL
+→ short-lived work branch setup
+→ 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.
+
+Use an explicit action set equivalent to:
+
+```text
+IMPLEMENTATION PLAN REVIEW REQUIRED
+
+Implementation has NOT started.
+
+1. Approve plan and begin implementation [PLAN APPROVAL + CODE WRITE]
+2. Request changes to the plan [PLAN ONLY]
+3. Review assumptions / risks [READ ONLY]
+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.
+
+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.
+
 ## Implementation branch setup
 
 Once implementation itself is authorized, creating/switching to the repository-appropriate short-lived work branch is routine setup, not a separate decision gate, when branch policy/naming and work-item scope are clear and the operation preserves the worktree without history rewriting.

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

@@ -40,11 +40,38 @@ Presentation rules:
 - use **single-select** when the choices are mutually exclusive or one action is being authorized;
 - use **multi-select** only when selecting several choices at the same time is semantically valid;
 - preserve one-material-question-at-a-time cadence whenever practical even if the host can batch questions;
-- keep consequence/action labels such as `[READ ONLY]`, `[REQUIREMENTS GATE]`, or `[GIT + GITHUB WRITE]` visible when they matter to authorization;
+- keep consequence/action labels such as `[READ ONLY]`, `[REQUIREMENTS GATE]`, `[PLAN APPROVAL + CODE WRITE]`, or `[GIT + GITHUB WRITE]` visible when they matter to authorization;
 - include `Other / specify` or host-supported free-text input when the option set may be incomplete; after `Other / specify`, collect the missing value without forcing another invented menu;
 - accept equivalent free-text answers even when a structured selector is shown, unless the host UI itself requires a selection;
 - map the returned structured value to the same semantic choice the workflow would have accepted by label/text.
 
+### Human review surface presentation
+
+Before a substantive approval gate, follow the review-surface contract in `HUMAN_GATES.md`.
+
+1. Identify the exact PRIMARY review subject.
+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.
+
+Use the host's native surface when it is stronger than prose:
+
+- Markdown artifact → rendered Markdown preview when supported;
+- JSON approval artifact → formatted editor/preview plus a concise summary;
+- implementation plan → native plan surface or durable plan document;
+- 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.
+
+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.
+
+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.
+
+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.
+
+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.
+
 ### 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;

package/assets/generated/core/core/skills/export-requirements/SKILL.md

@@ -115,13 +115,32 @@ Preserved UX/cross-cutting constraints: ...
 Roadmap maturity retained: ...
 Implementation-specific material excluded: ...
 Items requiring reconciliation: ...
+```
+
+Then make the artifact itself the PRIMARY review subject. Before asking for approval:
+1. identify `PROJECT_REQUIREMENTS.json` explicitly;
+2. foreground/open the formatted JSON in the best available editor/preview surface when the host supports it;
+3. keep source authorities as CONTEXT/TRACEABILITY rather than opening them all;
+4. only then ask the approval question.
+
+In VS Code, when available, use `projectForge.openReviewArtifact` with `PROJECT_REQUIREMENTS.json`. Opening the file is read-only presentation and never changes its state.
+
+Present a gate equivalent to:
+
+```text
+HUMAN REVIEW REQUIRED
+
+Gate: PORTABLE REQUIREMENTS APPROVAL
+Primary artifact: PROJECT_REQUIREMENTS.json
+Opened: formatted editor preview / <fallback surface>
+Items requiring reconciliation: NONE / list
 
 Approve PROJECT_REQUIREMENTS.json as the portable requirements baseline?
 ```
 
 Only explicit human approval may set `state: "approved"`.
 
-`/export-requirements approve` may perform only that bounded finalization after confirming the reviewed content/evidence has not materially changed.
+`/export-requirements approve` may perform only that bounded finalization after confirming the reviewed content/evidence has not materially changed. If the artifact changed materially since review, reopen the review surface and require approval again.
 
 ## Safety and scope