@mriekki/project-forge 4.13.0 → 4.13.2

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.13.0",
+  "version": "4.13.2",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
+      "revision": "51fc0332a7908cf8e3ebe5594e864feb5025e853",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.13.0",
+  "version": "4.13.2",
   "components": {
     "core": {
-      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
+      "revision": "51fc0332a7908cf8e3ebe5594e864feb5025e853",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -21,7 +21,7 @@
         {
           "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",
@@ -51,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",
@@ -71,12 +71,12 @@
         {
           "source": "core/skills/export-requirements/SKILL.md",
           "destination": ".github/skills/export-requirements/SKILL.md",
-          "sha256": "dd82f05b6e2ec7ecf8e7a8592066fd8c6d623c1f184f49838b1e95eb5b53320a"
+          "sha256": "0206e6c754158e46aaacb9f83a7bf2af85827fe6d60fc90a4874d5633946192a"
         },
         {
           "source": "core/skills/replatform/SKILL.md",
           "destination": ".github/skills/replatform/SKILL.md",
-          "sha256": "561796a829b9c12f8bd2e526f8fe86cbd33d258a5c6b04ca581721e07d984ca7"
+          "sha256": "b663ec40bb9b48f5737d8d2141a60c131196d4c496605d0a8c65285a0e7deb8f"
         },
         {
           "source": "core/skills/progress/SKILL.md",
@@ -186,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",
@@ -196,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",
@@ -236,7 +236,7 @@
         {
           "source": "core/process/PROJECT_REQUIREMENTS_EXPORT.md",
           "destination": "docs/process/PROJECT_REQUIREMENTS_EXPORT.md",
-          "sha256": "6ef9ecf1bb7c86b5f445554f5e630db36beee34bead2db8ff2597c148fba9c30"
+          "sha256": "f3e171cf466db69f46798859d9c174c177f5a1cb02bf19a3f02a66a16f5c43df"
         },
         {
           "source": "core/process/APPLICATION_VERSIONING.md",
@@ -336,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",

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/PROJECT_REQUIREMENTS_EXPORT.md

@@ -20,6 +20,33 @@ Additional product/domain authorities may include roadmap, system-design/domain
 
 The export must retain source paths/authority/provenance so a consumer can trace normalized facts back to their repository authorities.
 
+## Canonical contract authority
+
+Core owns the `/export-requirements` workflow and Human-in-the-Loop gate. Bootstrap owns the accepted portable-requirements schema and validator.
+
+At the start of an export session, resolve the current stable Project Forge descriptor:
+
+```text
+https://raw.githubusercontent.com/mriekki/project-forge-platform/main/chatgpt/current.json
+```
+
+Use the exact immutable `generation.bootstrap.revision` selected there. Through authorized Project Forge/GitHub access, inspect that revision's canonical:
+
+```text
+schemas/project-requirements.schema.json
+tools/project_requirements.py
+```
+
+Do not maintain a competing schema in Core and do not use remembered field shapes, generated examples, or a legacy export as structural authority.
+
+If the stable descriptor, exact Bootstrap revision, schema, or validator cannot be resolved, stop before portable-requirements approval with:
+
+```text
+PORTABLE REQUIREMENTS VALIDATION REQUIRED
+```
+
+Unavailability of canonical validation is not permission to infer a compatible shape.
+
 ## Canonical filename and state
 
 Only this filename is canonical:
@@ -42,7 +69,7 @@ Only `approved` may be consumed as replatform input.
 
 ## Portable content model
 
-The export should represent, when present:
+The exact JSON structure comes from the current Bootstrap schema. Within that structure, the export should represent, when present:
 
 - project/product identity;
 - problem, users/stakeholders, desired outcomes, scope/non-scope;
@@ -107,7 +134,7 @@ Examples:
 
 - a Project Blueprint may contain product/domain facts plus current technology baseline;
 - a System Design may contain portable domain invariants plus React/.NET/SQLite topology;
-- a UX pattern may contain portable interaction behavior plus component-library details;
+- a UX pattern may contain portable interaction behavior plus component-library detail;
 - an ADR may establish both a product/security consequence and a stack-specific mechanism.
 
 Extract the portable fact, retain source traceability, and exclude/reconcile the mechanism.
@@ -128,6 +155,23 @@ Do not export as portable requirements unless the repository explicitly makes th
 - Git/PR/CI evidence;
 - Project Forge/Core/Bootstrap baseline state.
 
+## Validation and approval boundary
+
+Create or refresh the derived artifact in `state: "review"`, then validate the exact file with the canonical Bootstrap validator from the exact revision resolved for the session.
+
+Equivalent validation commands are:
+
+```text
+python tools/project_requirements.py PROJECT_REQUIREMENTS.json
+python tools/project_requirements.py PROJECT_REQUIREMENTS.json --require-approved
+```
+
+The first is required before the human review/approval gate. The second is required after the bounded approval-state transition.
+
+If review-state validation fails, repair only the derived export from existing authorities and the canonical schema, then rerun validation. Do not ask for approval until it passes.
+
+If an older or malformed export was previously approved but does not validate now, that earlier approval does not automatically authorize a normalized replacement. Preserve the underlying source authority/maturity/provenance, produce a valid `state: "review"` artifact, and obtain a fresh human approval of that exact artifact.
+
 ## Replatform relationship
 
 The canonical flow is:
@@ -135,9 +179,12 @@ The canonical flow is:
 ```text
 project authorities
 → /export-requirements
+→ current stable Bootstrap contract resolution
 → PROJECT_REQUIREMENTS.json state=review
+→ canonical Bootstrap validation PASS
 → human approval
 → PROJECT_REQUIREMENTS.json state=approved
+→ canonical Bootstrap validation --require-approved PASS
 → /replatform <target-stack>
 → current Bootstrap catalog reconciliation
 → PROJECT_BOOTSTRAP.json state=review

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

@@ -28,6 +28,33 @@ It must not answer:
 
 > Which framework, language, ORM, build tool, folder layout, or CI implementation should the next repository use?
 
+## Canonical Bootstrap contract preflight
+
+Before constructing or refreshing `PROJECT_REQUIREMENTS.json`, resolve the current stable Project Forge descriptor from:
+
+```text
+https://raw.githubusercontent.com/mriekki/project-forge-platform/main/chatgpt/current.json
+```
+
+Use the exact `generation.bootstrap.revision` from that descriptor as the Bootstrap contract authority for this export session. Do not use a remembered schema, an older generated example, or this skill's prose as a substitute for the current Bootstrap-owned portable-requirements contract.
+
+Through the authorized Project Forge/GitHub access available in the current host, inspect the canonical Bootstrap portable-requirements schema and validator from that exact immutable revision, including:
+
+```text
+schemas/project-requirements.schema.json
+tools/project_requirements.py
+```
+
+Bootstrap owns the schema/validator. Core owns this orchestration. Do not copy the Bootstrap schema into Core, invent a parallel validator, or infer a compatibility transform for a shape that the canonical validator rejects.
+
+If the stable descriptor, exact Bootstrap revision, canonical schema, or canonical validator cannot be resolved and inspected, stop with:
+
+```text
+PORTABLE REQUIREMENTS VALIDATION REQUIRED
+```
+
+Do not create an approval-ready export and do not ask for portable-requirements approval while canonical validation is unavailable.
+
 ## Source model
 
 Start from the workspace's declared authority model. In a normal generated Project Forge workspace, inspect as applicable:
@@ -100,15 +127,35 @@ Do not export as portable requirements:
 - implementation plans, code, review history, branch/PR/CI evidence;
 - generated Project Forge/Core provenance.
 
-## Artifact state and human gate
+## Canonical validation before human review
+
+Default `/export-requirements` writes or refreshes `PROJECT_REQUIREMENTS.json` with `state: "review"` and exact source repository/commit provenance, using the current Bootstrap schema as the structural contract.
+
+Before presenting any approval question, validate that exact file with the canonical Bootstrap validator from the exact revision resolved during preflight. The equivalent canonical invocation is:
+
+```text
+python tools/project_requirements.py <path-to-PROJECT_REQUIREMENTS.json>
+```
+
+The actual invocation path may differ by host, but the validator implementation and Bootstrap revision must be the same canonical ones resolved during preflight.
+
+If validation fails:
 
-Default `/export-requirements` writes or refreshes `PROJECT_REQUIREMENTS.json` with `state: "review"` and exact source repository/commit provenance.
+1. report the validator errors;
+2. repair only the derived export using existing source authorities and the canonical schema;
+3. preserve source authority, maturity, provenance, open decisions, and non-authorizing roadmap intent;
+4. rerun canonical validation;
+5. do not ask for approval until validation passes.
 
-Before calling it approved, present a compact reconciliation summary:
+Do not silently reinterpret a rejected legacy/export shape, rename fields from memory, promote unresolved decisions, or treat prior human approval of structurally different JSON as approval of a normalized replacement.
+
+Before calling a valid export approved, present a compact reconciliation summary:
 
 ```text
 PROJECT REQUIREMENTS EXPORT
 
+Bootstrap revision: <exact revision>
+Canonical validation: PASS
 Preserved product/features: ...
 Preserved domain rules: ...
 Preserved UX/cross-cutting constraints: ...
@@ -120,7 +167,7 @@ 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;
+3. keep source authorities and Bootstrap validation evidence 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.
@@ -133,6 +180,7 @@ HUMAN REVIEW REQUIRED
 Gate: PORTABLE REQUIREMENTS APPROVAL
 Primary artifact: PROJECT_REQUIREMENTS.json
 Opened: formatted editor preview / <fallback surface>
+Canonical Bootstrap validation: PASS @ <exact revision>
 Items requiring reconciliation: NONE / list
 
 Approve PROJECT_REQUIREMENTS.json as the portable requirements baseline?
@@ -140,7 +188,13 @@ 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. If the artifact changed materially since review, reopen the review surface and require approval again.
+`/export-requirements approve` may perform only that bounded finalization after confirming the reviewed content/evidence has not materially changed. After changing `state` to `approved`, rerun the same canonical Bootstrap validator with the equivalent of:
+
+```text
+python tools/project_requirements.py <path-to-PROJECT_REQUIREMENTS.json> --require-approved
+```
+
+If final validation fails, restore/report review state as applicable and do not claim the portable baseline is approved. If the artifact changed materially since review for any reason beyond the bounded approval-state transition, reopen the review surface and require approval again.
 
 ## Safety and scope
 

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

@@ -22,6 +22,10 @@ PROJECT_REQUIREMENTS.json
 
 The file must be `state: "approved"`. Do not accept alternate/legacy requirements-export filenames or infer approval from file existence.
 
+Before consuming the export, validate it with the canonical Bootstrap portable-requirements validator from the exact current stable Bootstrap revision. If it fails canonical validation, stop and route back through `/export-requirements`; do not normalize, translate, alias, or repair the input inside `/replatform`.
+
+A previously human-approved file that does not validate against the canonical portable contract is not valid replatform input until a canonical `state: "review"` export is produced and explicitly approved again.
+
 If the export is missing or stale relative to material source-requirement changes, use `/export-requirements` first.
 
 ## Target
@@ -88,7 +92,7 @@ Never:
 Use the current canonical Bootstrap replatform tooling when available. The expected deterministic boundary is:
 
 ```text
-approved PROJECT_REQUIREMENTS.json
+approved + canonically valid PROJECT_REQUIREMENTS.json
 + requested current catalog recipe/stack
 + target repository identity
 → PROJECT_BOOTSTRAP.json state=review
@@ -104,6 +108,7 @@ Before generation, summarize at minimum:
 SOURCE REQUIREMENTS
 source repository/commit
 portable requirements export provenance
+canonical Bootstrap validation evidence
 
 PRESERVED
 product/features/domain/UX/cross-cutting intent

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -165,7 +165,11 @@ PRIMARY review subject is the final proposed implementation plan. Prefer:
 2. a durable plan document when one exists and is useful;
 3. otherwise the full substantive plan in the conversation.
 
-If a durable plan is a repository artifact and VS Code can invoke the Project Forge companion extension, use `projectForge.openReviewArtifact` with the exact workspace-relative path. If the host exposes a stronger native plan/review surface, use that instead.
+If a durable plan is a repository artifact, resolve its exact work-item-specific path from the current work-item authority/gate state before opening it. Do not select a global plan, another work item's artifact, or a focus-derived file.
+
+In VS Code, when the Project Forge companion review command/tool is available, request presentation of that exact artifact. Record the actual presentation outcome when the host reports one, including rendered Markdown vs editor fallback vs unavailable/failed. If the host exposes a stronger native plan/review surface, use that instead.
+
+If automatic opening is unavailable or fails, keep the gate usable: include the exact plan link/path inside the question and provide a deterministic manual fallback. For Markdown in VS Code on Windows, tell the human to open the exact linked file and press `Ctrl+Shift+V`.
 
 Before rendering the gate, state explicitly:
 
@@ -180,7 +184,9 @@ IMPLEMENTATION PLAN REVIEW REQUIRED
 
 Work item: <ID / key / concise change>
 Risk: <STANDARD | ELEVATED>
-Review subject: <native plan / exact plan path>
+Approval subject: final proposed implementation plan
+Primary artifact: <exact clickable work-item plan link/path | native plan surface>
+Presentation: <rendered Markdown opened | editor fallback opened | automatic opening unavailable/failed | native plan foregrounded>
 
 Plan covers:
 - approach
@@ -200,9 +206,11 @@ Implementation has NOT started.
 4. Stop [NO ACTION]
 ```
 
-When the host exposes structured choice UI, render the actions as a single-select control rather than a numbered menu while preserving the consequence labels. Do not preselect or infer `Approve plan and begin implementation` merely because the plan exists or the human invoked `/start-work`.
+The exact PRIMARY artifact link/path must be present in the approval question itself; do not rely on a link in earlier commentary. The artifact named in the gate must be the same artifact requested/opened for presentation.
+
+When the host exposes structured choice UI, render the actions as a single-select control rather than a numbered menu while preserving the consequence labels and the same work-item/artifact context in the question. Do not preselect or infer `Approve plan and begin implementation` merely because the plan exists, was opened, or the human invoked `/start-work`.
 
-Only option 1 (or equivalent explicit free-text authorization) authorizes substantive implementation. Options 2-4 do not.
+Only option 1 (or equivalent explicit free-text authorization) authorizes substantive implementation. Options 2-4 do not. Preview, navigation, cancellation, or a question asking where the plan is never counts as approval.
 
 ### Material plan changes after approval
 
@@ -222,10 +230,11 @@ APPROVED PLAN CHANGED
 
 Material change: ...
 Reason: ...
-Revised plan: ...
+Revised PRIMARY artifact: <exact revised plan link/path | native plan surface>
+Presentation: <actual presentation evidence>
 ```
 
-Foreground the revised PRIMARY plan review surface when supported, then require renewed plan approval. Do not silently continue implementation under stale authorization.
+Foreground the revised PRIMARY plan review surface when supported, then require renewed plan approval using the revised exact link/path inside the question. Do not silently continue implementation under stale authorization or reuse stale presentation evidence.
 
 ## 6. Working branch setup
 

package/assets/generated/core/tools/vscode_work_item_status/extension/README.md

@@ -1,6 +1,6 @@
 # Project Forge Work Item Status
 
-This optional local VS Code extension decorates Project Forge work-item folders in the Explorer from repository evidence and provides a read-only helper for Project Forge human-review surfaces.
+This optional local VS Code extension decorates Project Forge work-item folders in the Explorer from repository evidence and provides read-only helpers for Project Forge human-review surfaces.
 
 ## Work-item status
 
@@ -18,12 +18,16 @@ Project Forge workflows may use **Project Forge: Open Review Artifact** immediat
 
 The command accepts an exact workspace-relative repository artifact path when invoked programmatically. When run manually from the Command Palette without a path, it asks for the workspace-relative path.
 
+On VS Code hosts that support the Language Model Tool API, the extension also contributes the read-only `projectForge_openReviewArtifact` tool so an agent can request the same exact presentation operation without arbitrary command execution. Older supported VS Code hosts keep the command/manual fallback.
+
 Behavior:
 
-- Markdown files open in rendered Markdown Preview when available;
+- Markdown files request rendered Markdown Preview first;
+- when Markdown Preview is unavailable, the helper reports that fact and falls back to normal editor preview;
 - other repository artifacts open in the normal VS Code editor preview;
 - targets outside the currently open workspace are rejected;
-- missing or ambiguous multi-root targets are reported rather than guessed;
+- missing or ambiguous multi-root targets are reported rather than guessed from active editor focus;
+- the presentation result distinguishes the resolved URI, requested mode, actual opened mode, cancellation, and failure;
 - opening/previewing an artifact is read-only presentation and never records approval.
 
-Project Forge should foreground only the PRIMARY review subject automatically. Supporting CONTEXT and TRACEABILITY documents remain available without stealing focus unless the human chooses to open them.
+Project Forge should foreground only the exact PRIMARY review subject automatically. Supporting CONTEXT and TRACEABILITY documents remain available without stealing focus unless the human chooses to open them. The approval question itself must still identify and link the same artifact; a successful open is presentation evidence only.

package/assets/generated/core/tools/vscode_work_item_status/extension/extension.js

@@ -13,6 +13,7 @@ const ID_FROM_NAME = /^([A-Za-z][A-Za-z0-9]*-\d+)(?:-|$)/;
 const ID_FROM_BRANCH = /(?:^|\/)([A-Za-z][A-Za-z0-9]*-\d+)(?:-|\/|$)/i;
 const MARKER = /<!--\s*project-forge-work-item:\s*([A-Za-z][A-Za-z0-9]*-\d+)\s*-->/gi;
 const REFRESH_INTERVAL_MS = 120000;
+const REVIEW_TOOL_NAME = 'projectForge_openReviewArtifact';
 
 function normalizeId(value) {
   return value ? value.toUpperCase() : undefined;
@@ -242,32 +243,42 @@ async function resolveReviewUri(target) {
     throw new Error(`Review artifact was not found in the open workspace: ${requested}`);
   }
 
-  const activeEditor = vscode.window.activeTextEditor;
-  const activeFolder = activeEditor
-    ? vscode.workspace.getWorkspaceFolder(activeEditor.document.uri)
-    : undefined;
-  const activeMatch = activeFolder
-    ? matches.find((entry) => entry.folder.uri.fsPath === activeFolder.uri.fsPath)
-    : undefined;
-  if (activeMatch) {
-    return activeMatch.uri;
-  }
-
   throw new Error(`Review artifact path is ambiguous across workspace folders: ${requested}`);
 }
 
-async function openReviewArtifact(target) {
+function requestedReviewMode(uri) {
+  const extension = path.extname(uri.fsPath).toLowerCase();
+  return extension === '.md' || extension === '.markdown'
+    ? 'markdown-preview'
+    : 'editor-preview';
+}
+
+async function presentReviewArtifact(target, options = {}) {
+  const notify = options.notify !== false;
+  let uri;
   try {
-    const uri = await resolveReviewUri(target);
+    uri = await resolveReviewUri(target);
     if (!uri) {
-      return undefined;
+      return {
+        status: 'cancelled',
+        uri: null,
+        requestedMode: null,
+        openedMode: null,
+        message: 'No review artifact was selected.',
+      };
     }
 
-    const extension = path.extname(uri.fsPath).toLowerCase();
-    if (extension === '.md' || extension === '.markdown') {
+    const requestedMode = requestedReviewMode(uri);
+    if (requestedMode === 'markdown-preview') {
       try {
         await vscode.commands.executeCommand('markdown.showPreview', uri);
-        return uri.toString();
+        return {
+          status: 'opened',
+          uri: uri.toString(),
+          requestedMode,
+          openedMode: 'rendered-markdown',
+          message: 'Rendered Markdown preview opened.',
+        };
       } catch {
         // Fall back to the normal editor preview surface when Markdown preview is unavailable.
       }
@@ -277,11 +288,40 @@ async function openReviewArtifact(target) {
       preview: true,
       preserveFocus: false,
     });
-    return uri.toString();
+    return {
+      status: 'opened',
+      uri: uri.toString(),
+      requestedMode,
+      openedMode: 'editor-preview',
+      message: requestedMode === 'markdown-preview'
+        ? 'Rendered Markdown preview was unavailable; editor preview opened instead.'
+        : 'Editor preview opened.',
+    };
   } catch (error) {
     const message = error && error.message ? error.message : String(error);
-    await vscode.window.showWarningMessage(`Project Forge review artifact: ${message}`);
-    return undefined;
+    if (notify) {
+      await vscode.window.showWarningMessage(`Project Forge review artifact: ${message}`);
+    }
+    return {
+      status: 'failed',
+      uri: uri ? uri.toString() : null,
+      requestedMode: uri ? requestedReviewMode(uri) : null,
+      openedMode: null,
+      message,
+    };
+  }
+}
+
+async function openReviewArtifact(target) {
+  return presentReviewArtifact(target, { notify: true });
+}
+
+class OpenReviewArtifactTool {
+  async invoke(options) {
+    const result = await presentReviewArtifact(options && options.input, { notify: false });
+    return new vscode.LanguageModelToolResult([
+      new vscode.LanguageModelTextPart(JSON.stringify(result)),
+    ]);
   }
 }
 
@@ -373,6 +413,18 @@ function activate(context) {
   context.subscriptions.push(
     vscode.commands.registerCommand('projectForge.openReviewArtifact', openReviewArtifact),
   );
+
+  if (
+    vscode.lm &&
+    typeof vscode.lm.registerTool === 'function' &&
+    typeof vscode.LanguageModelToolResult === 'function' &&
+    typeof vscode.LanguageModelTextPart === 'function'
+  ) {
+    context.subscriptions.push(
+      vscode.lm.registerTool(REVIEW_TOOL_NAME, new OpenReviewArtifactTool()),
+    );
+  }
+
   context.subscriptions.push(
     vscode.window.onDidChangeWindowState((event) => {
       if (event.focused) {
@@ -406,4 +458,10 @@ function activate(context) {
 
 function deactivate() {}
 
-module.exports = { activate, deactivate, openReviewArtifact, resolveReviewUri };
+module.exports = {
+  activate,
+  deactivate,
+  openReviewArtifact,
+  presentReviewArtifact,
+  resolveReviewUri,
+};

package/assets/generated/core/tools/vscode_work_item_status/extension/package.json

@@ -2,7 +2,7 @@
   "name": "project-forge-work-item-status",
   "displayName": "Project Forge Work Item Status",
   "description": "Shows evidence-backed Project Forge work-item status badges and provides read-only review-surface helpers in VS Code.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "publisher": "project-forge",
   "license": "UNLICENSED",
   "engines": {
@@ -19,7 +19,8 @@
   ],
   "activationEvents": [
     "workspaceContains:docs/work-items/*",
-    "onCommand:projectForge.openReviewArtifact"
+    "onCommand:projectForge.openReviewArtifact",
+    "onLanguageModelTool:projectForge_openReviewArtifact"
   ],
   "main": "./extension.js",
   "extensionKind": [
@@ -41,6 +42,29 @@
         "command": "projectForge.openReviewArtifact",
         "title": "Project Forge: Open Review Artifact"
       }
+    ],
+    "languageModelTools": [
+      {
+        "name": "projectForge_openReviewArtifact",
+        "displayName": "Open Project Forge Review Artifact",
+        "canBeReferencedInPrompt": true,
+        "toolReferenceName": "projectForgeReviewArtifact",
+        "userDescription": "Open an exact workspace review artifact using the safest read-only review surface available.",
+        "modelDescription": "Use immediately before a Project Forge artifact-based human approval gate when the exact review artifact path is already known. Opens only that exact workspace-contained file and returns structured presentation evidence. It never approves, edits, commits, or guesses an ambiguous target.",
+        "inputSchema": {
+          "type": "object",
+          "properties": {
+            "path": {
+              "type": "string",
+              "description": "Exact workspace-relative or absolute workspace-contained path of the PRIMARY review artifact. Do not infer it from editor focus."
+            }
+          },
+          "required": [
+            "path"
+          ],
+          "additionalProperties": false
+        }
+      }
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.13.0",
+  "version": "4.13.2",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {