@mriekki/project-forge 4.13.0 → 4.13.1

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.13.0",
+  "version": "4.13.1",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
+      "revision": "a88c33ec1c93e120c70018a01c018f59dc2f74f2",
       "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.1",
   "components": {
     "core": {
-      "revision": "27f6824d1a53daa7e0c51bf286cce6767ddca3f7",
+      "revision": "a88c33ec1c93e120c70018a01c018f59dc2f74f2",
       "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",
@@ -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",
@@ -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/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.1",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {