@mriekki/project-forge 4.11.2 → 4.13.0

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

@@ -27,6 +27,8 @@ Read only the minimum relevant context. Do not preload unrelated work items. Do
 
 Never assume `Jira Epic == Feature Brief`.
 
+When review/approval will concern a local artifact, classify it as the PRIMARY review subject. Supporting Feature/Product briefs, ADRs, and design documents are CONTEXT or TRACEABILITY unless they are themselves the decision subject.
+
 ## 2. Decide whether detail is warranted
 
 Detailed refinement is useful for behavior such as:
@@ -124,6 +126,8 @@ Then present only relevant actions as a **single-select structured choice** when
 - `Approve local requirements` `[REQUIREMENTS GATE]` when applicable
 - `Stop` `[NO ACTION]`
 
+When the human selects `Review full requirements/work item`, foreground the PRIMARY review surface when the host supports it. For local Markdown requirements, prefer rendered Markdown preview. In VS Code, use `projectForge.openReviewArtifact` with the exact workspace-relative path when available. For an external-primary work item, use the best available external issue/item surface instead of creating a local surrogate solely for preview.
+
 Make a recommendation only when current requirement evidence or a clear engineering tradeoff supports one. If so, mark exactly one choice with the host's `recommended` indicator when that metadata exists; otherwise append `[RECOMMENDED]` to exactly one option label. Briefly explain why in the option description or surrounding prompt. A default/preselected value may match the recommendation, but a default alone must never communicate advice or approval. If there is no clear basis, show the choices without a recommendation and without a preference-implying default. The selected answer, not the recommendation, controls what the session does or records.
 
 If the host has no structured choice UI, present the same relevant choices as a concise numbered or lettered text fallback, preserve `[RECOMMENDED]` on the evidence-backed option when applicable, and accept the number/letter, label, or free-form intent. Do not use the text fallback as the normal VS Code path.
@@ -193,7 +197,26 @@ APPROVED
 
 Human approval is explicit. Do not infer approval from review/planning/implementation.
 
-Before approval report coverage and open material decisions. Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`. When the host offers structured choices, render this approval gate as a single-select action, not a numbered chat menu.
+Before approval:
+1. report coverage and open material decisions;
+2. identify the exact PRIMARY local requirements artifact;
+3. foreground/open that artifact in the best available review surface when the host supports it;
+4. only then render the `[REQUIREMENTS GATE]` choice.
+
+For Markdown requirements in VS Code, prefer rendered preview; when the Project Forge companion command is available, invoke `projectForge.openReviewArtifact` with the exact workspace-relative requirements path. If automatic opening is unavailable, provide the exact path/link and explicitly tell the human that this is the artifact being approved.
+
+The gate should make the review subject unmistakable, for example:
+
+```text
+HUMAN REVIEW REQUIRED
+
+Gate: REQUIREMENTS APPROVAL
+Primary artifact: docs/work-items/<work-item>/requirements.md
+Opened: Markdown Preview / <fallback surface>
+Open material decisions: NONE / list
+```
+
+Only an explicit `[REQUIREMENTS GATE]` choice may change local status to `APPROVED`. Opening the document, viewing the preview, or selecting a read-only review action never changes approval state. When the host offers structured choices, render this approval gate as a single-select action, not a numbered chat menu.
 
 External work-item status/approval follows the external team's conventions; Project Forge must not fabricate a local approval state.
 
@@ -222,4 +245,4 @@ Then offer review, more grilling/refinement, approval when applicable, or stop u
 
 Do not create implementation plans or production code.
 
-When requirements are ready, recommend `/start-work <ID-or-key>`.
+When requirements are ready, recommend `/start-work <ID-or-key>`. That command may prepare the implementation plan, but STANDARD/ELEVATED implementation still requires the distinct plan-approval gate defined by `/start-work`.

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

@@ -119,4 +119,27 @@ OUTPUT
 PROJECT_BOOTSTRAP.json — REVIEW
 ```
 
-Then use the normal material Bootstrap manifest approval gate. Approval of replatform intent is not approval to merge, release, or deploy the resulting implementation.
+Then make `PROJECT_BOOTSTRAP.json` the PRIMARY review subject. Before asking for Bootstrap approval:
+
+1. identify the exact manifest path and target repository identity;
+2. foreground/open the formatted manifest in the best available review/editor surface when the host supports it;
+3. keep source requirements/catalog evidence as CONTEXT/TRACEABILITY rather than opening everything;
+4. only then render the normal material Bootstrap manifest approval gate.
+
+In VS Code, when available, use `projectForge.openReviewArtifact` with the exact workspace-relative `PROJECT_BOOTSTRAP.json` path. Opening the manifest is read-only presentation and never authorizes generation.
+
+Present an explicit surface summary such as:
+
+```text
+HUMAN REVIEW REQUIRED
+
+Gate: BOOTSTRAP MANIFEST APPROVAL
+Primary artifact: PROJECT_BOOTSTRAP.json
+State: REVIEW
+Opened: formatted editor preview / <fallback surface>
+Target: <owner/repository>
+```
+
+If the manifest changes materially after review, foreground the changed manifest and reopen approval rather than reusing stale authorization.
+
+Approval of replatform intent or manifest review is not approval to merge, release, or deploy the resulting implementation.

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

@@ -8,47 +8,72 @@ disable-model-invocation: true
 
 # Run
 
-`/run` is the normal convenience entry point for starting the project locally. It resolves and delegates to repository-owned runtime commands rather than requiring the developer to remember framework-specific launch syntax.
+`/run` is the normal convenience entry point for starting the project locally. Core stays stack-neutral; the Project becomes deterministic by exposing a repository-owned local runtime command and runtime/persistence pairing once executable application topology exists. Follow `docs/process/LOCAL_DEVELOPMENT_COMMANDS.md` when present.
 
 ## Contract
 
-Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, deployment, release publication, Production access, or persistent background services outside the repository's normal local-development contract.
+Invoking `/run` authorizes one bounded local start attempt for the requested target. It does not authorize setup, source edits, migrations, database reset/replacement, deployment, release publication, Production access, or persistent background services outside the repository's normal local-development contract.
 
-Resolve the local runtime command from current repository evidence in this order:
+Resolve the local runtime from current repository evidence in this order:
 
-1. an explicit repository-owned run/dev wrapper or documented command;
-2. an explicit package/task script whose purpose is local run/dev;
-3. an unambiguous ecosystem-native local entry point already present in the repository.
+1. an explicit developer-selected supported runtime/target, when one was supplied;
+2. the established Project-owned default local runtime and its associated persistence, including a project-owned local container/database when the repository defines that as the developer topology;
+3. an explicit repository-owned run/dev wrapper or documented command for that selected runtime;
+4. an explicit package/task script whose purpose is local run/dev;
+5. an unambiguous ecosystem-native local entry point already present in the repository, but only when the Project has not yet established a repository-owned runtime contract.
 
 Do not guess. If the repository has multiple independent runtimes and no documented default, require a target such as `/run web`, `/run api`, or `/run all`.
 
+For normal Feature Brief and Engineering Enabler development/validation, default to the established Project-owned local runtime and associated persistence unless the developer explicitly selects an alternative. Do not silently start a native process or use a separate checkout database merely because an ecosystem-native command is convenient.
+
+Once a repository-owned runtime command exists, treat it as authoritative for that runtime. If it is stale or fails because topology changed, report the contract problem; do not silently bypass it with another runtime/database.
+
 ## Preconditions
 
 Before starting:
 
 - identify repository root and current Git state;
 - inspect `PROJECT_BOOTSTRAP.json` and scaffold/readiness evidence when present;
+- resolve the exact selected runtime and, when applicable, the persistence instance it owns or uses;
 - verify the selected runtime entry point exists;
-- inspect any documented local ports/health endpoints;
+- inspect documented local ports, health endpoints, launch profiles, and transport/authentication requirements;
 - do not create an intentionally deferred scaffold merely to make `/run` succeed.
 
 If runtime source is intentionally deferred or absent, return `RUN NOT AVAILABLE` and identify the owning work item or missing marker when repository evidence provides it.
 
 If workstation tools or dependencies are missing, recommend `/setup` instead of silently installing them.
 
+### Persistence and schema readiness
+
+When the selected runtime requires persistence, inspect repository-owned non-mutating readiness evidence for the **exact selected persistence instance** before claiming functional readiness. This may include installed Project Forge/Deployment Kit status primitives, migration status commands, repository health/doctor commands, or other documented read-only checks.
+
+- If initialization or required schema is known to be missing/stale, do not automatically migrate, reset, delete, replace, or switch databases. Report `PERSISTENCE BLOCKED` and route to `/setup local` or the repository-owned repair workflow.
+- If the repository does not expose a safe way to establish schema compatibility, report `PERSISTENCE UNVERIFIED`. Do not turn a successful connection, process start, `/version`, or connection-only health check into an application-readiness claim.
+- If the application has no persistence requirement for the selected runtime, report persistence as `N/A`; do not invent a database gate.
+
+A stopped, absent, stale, or migration-pending Project-owned default container/database is a prerequisite problem, not permission to select a different runtime. An explicit developer selection may authorize a supported alternative within the existing `/run` boundary; inspect only that selected runtime and persistence.
+
+### Transport/authentication readiness
+
+Resolve documented transport prerequisites before choosing a launch profile. If normal authentication development requires HTTPS, secure cookies, or another repository-declared transport property, use the supported Project-owned profile/runtime when available or report the unresolved prerequisite. Do not disable secure-cookie policy, invent TLS/provider settings, or weaken authentication configuration to make `/run` succeed.
+
 ## Execution
 
-Start the process in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
+Start the selected process/runtime in an observable developer-controlled terminal/process surface. Do not hide a long-running application in an unexplained background process.
 
-Report:
+Report these evidence dimensions separately:
 
-- target;
+- target and selected runtime identity;
 - resolved command identity;
 - process/startup result;
 - effective application release/build identity when the running application exposes it;
-- local URL/port or health evidence only when repository/runtime evidence establishes it;
+- persistence readiness: `READY`, `BLOCKED`, `UNVERIFIED`, or `N/A`;
+- local URL/port and transport evidence only when repository/runtime evidence establishes it;
+- functional checks actually performed and their result;
 - how to stop the process.
 
+Do not equate startup, artifact identity, `/version`, or connection-only health with successful user workflows. Do not claim login, OAuth callback/provider readiness, or another functional path was verified unless that exact path was exercised successfully.
+
 When `/run all` is explicitly supported, start only the repository-defined set of local components and make each process/endpoint visible.
 
 When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer runtime-observed version evidence over a source-file guess. Do not synthesize a build number or claim that a static source label proves the running artifact's identity.
@@ -57,7 +82,7 @@ When the project implements `docs/process/APPLICATION_VERSIONING.md`, prefer run
 
 `/run` may write a concise sanitized startup receipt under `.project-forge/logs/run/` following `docs/process/OPERATION_JOURNAL.md`.
 
-Record startup command identity, target, timestamps, startup/health result, observed application version/build identity, and endpoint when established. Do not duplicate or continuously capture unbounded application stdout/stderr into the Project Forge journal.
+Record selected runtime/persistence identity (without secrets), startup command identity, target, timestamps, process/startup result, persistence readiness, functional checks actually performed, observed application version/build identity, and endpoint when established. Do not duplicate or continuously capture unbounded application stdout/stderr into the Project Forge journal.
 
 ## Deployment boundary
 
@@ -66,10 +91,11 @@ Record startup command identity, target, timestamps, startup/health result, obse
 It must not:
 
 - mutate remote environments;
+- perform setup or migration writes implicitly;
 - publish images/packages/releases;
 - change deployment bindings;
 - infer Production configuration;
 - bump or rewrite release version state;
 - stage, commit, push, merge, or clean branches.
 
-A successful `/run` proves only that the requested local runtime started with the evidence observed in that session.
+A successful `/run` proves only the evidence dimensions actually observed for the selected local runtime in that session.

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

@@ -1,6 +1,6 @@
 ---
 name: start-work
-description: Assess requirement readiness and implementation risk, then guide direct Agent work or native planning for the configured work item.
+description: Assess requirement readiness and implementation risk, prepare and review the implementation plan when warranted, then begin bounded implementation only after the required human authorization.
 argument-hint: "<work-item ID, external key, or concise change>"
 user-invocable: true
 disable-model-invocation: true
@@ -8,6 +8,22 @@ disable-model-invocation: true
 
 # Start Work
 
+## 0. Invocation and implementation boundary
+
+`/start-work` is the orchestration entry point for preparing a work item to be implemented. Its invocation authorizes read-only context resolution, requirement-readiness assessment, risk classification, and implementation planning.
+
+For **STANDARD** and **ELEVATED** work, invoking `/start-work` does **not** by itself authorize substantive implementation, code writes, or implementation branch setup. Those begin only after the human explicitly approves the final proposed implementation plan at the plan gate defined below.
+
+For **LIGHT** work, there is no mandatory formal plan. The human-selected implementation action may authorize bounded implementation directly when the scope is tiny, obvious, and low-risk.
+
+Never blur these states:
+
+```text
+/start-work invoked
+≠ plan approved
+≠ implementation authorized
+```
+
 ## 1. Resolve the requested work
 
 Read `.github/project-forge-workspace.json` when present.
@@ -22,6 +38,8 @@ Resolve only the context needed:
 
 Do not require local briefs when the repository uses Jira/Issues. Do not invent external content.
 
+When the host can open repository review surfaces, foreground the PRIMARY authoritative requirement/work-item artifact when human review is needed. Treat additional briefs/ADRs/design documents as CONTEXT or TRACEABILITY unless they are themselves the approval subject.
+
 ## 2. Check requirement readiness before planning
 
 Assess:
@@ -43,7 +61,7 @@ Are material decisions unresolved?
 
 If detailed precision is warranted but incomplete, recommend `/refine-requirements` or `/grill-me` rather than silently inventing behavior. `/grill-me` may remain read-only or, when the human selects its session-level reconciliation option, write resolved decisions into permitted authorities.
 
-If local requirements are DRAFT and carry material behavior, human approval is the gate before substantive planning/implementation.
+If local requirements are DRAFT and carry material behavior, human approval is the gate before substantive planning/implementation. Before that approval, follow `HUMAN_GATES.md`: identify and foreground the PRIMARY requirements review surface when the host supports it.
 
 If requirements are already sufficient/approved under the configured model, do not force another refinement cycle.
 
@@ -62,7 +80,9 @@ Do not ask the human to open GitHub Settings and transcribe required-check names
 Tiny, obvious, low-risk; no meaningful schema/security/concurrency/deployment/major-UX implications.
 
 ```text
-Agent
+human selects bounded implementation action
+→ short-lived branch setup when appropriate
+→ Agent
 → relevant checks
 → human meaningful-diff review
 ```
@@ -76,7 +96,8 @@ Meaningful multi-file work.
 ```text
 requirements ready as needed
 → native plan
-→ HUMAN PLAN APPROVAL
+→ plan review surface foregrounded
+→ HUMAN IMPLEMENTATION-PLAN APPROVAL
 → short-lived work branch setup
 → Agent implementation
 → checks
@@ -99,7 +120,9 @@ Use for:
 detailed approved requirements / ADR as needed
 → native plan
 → Reviewer challenges plan
-→ HUMAN PLAN APPROVAL
+→ Reviewer findings reconciled into final proposed plan
+→ final plan review surface foregrounded
+→ HUMAN IMPLEMENTATION-PLAN APPROVAL
 → short-lived work branch setup
 → implementation in small slices
 → stronger verification
@@ -121,24 +144,100 @@ Relevant choices are:
 
 Use a numbered text list only when structured choice UI is unavailable. For LIGHT work, do not interrupt with coaching unless requested.
 
-## 5. Planning rules
+## 5. Planning rules and mandatory plan gate
 
 For STANDARD/ELEVATED work:
-- use the editor's current native planning capability,
-- plan approach, affected areas, key decisions, risks, and verification,
-- require human plan approval before implementation,
-- do not auto-launch subagents,
-- do not create mandatory `spec.md` or `tasks.md`,
-- save a durable plan only when it is useful across sessions or for genuinely complex/risky work.
+- use the editor's current native planning capability;
+- plan approach, affected areas, key decisions, risks, non-scope, and verification;
+- do not auto-launch implementation subagents while planning;
+- do not create mandatory `spec.md` or `tasks.md`;
+- save a durable plan only when it is useful across sessions or for genuinely complex/risky work;
+- require explicit human plan approval before implementation or implementation branch setup.
+
+For ELEVATED work, Reviewer challenges the proposed plan before the human approval gate. Reconcile material Reviewer findings into the final proposed plan first. The human reviews that final plan, not an earlier plan plus unresolved reviewer objections.
+
+### Present the review surface before asking for approval
+
+Follow the human-review-surface contract from `HUMAN_GATES.md` and `INTERACTIVE_SESSION_GUIDE.md`.
+
+PRIMARY review subject is the final proposed implementation plan. Prefer:
+1. the host's native plan surface when it can be foregrounded;
+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.
+
+Before rendering the gate, state explicitly:
+
+```text
+Implementation has NOT started.
+```
+
+Then present a gate equivalent to:
+
+```text
+IMPLEMENTATION PLAN REVIEW REQUIRED
+
+Work item: <ID / key / concise change>
+Risk: <STANDARD | ELEVATED>
+Review subject: <native plan / exact plan path>
+
+Plan covers:
+- approach
+- affected areas
+- key technical decisions
+- risks / mitigations
+- verification strategy
+- explicit non-scope
+
+Open material decisions: <NONE | list>
+
+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 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`.
+
+Only option 1 (or equivalent explicit free-text authorization) authorizes substantive implementation. Options 2-4 do not.
+
+### Material plan changes after approval
+
+Routine implementation details may evolve inside the approved approach. Reopen the implementation-plan gate when new evidence requires a material change to any of:
+- architecture or major component boundaries,
+- approved scope/non-scope,
+- schema/data handling or migration behavior,
+- authentication/security/authorization model,
+- externally visible behavior or contract,
+- major dependencies/integration strategy,
+- verification strategy when the change materially weakens or alters the approved proof.
+
+Before continuing, show:
+
+```text
+APPROVED PLAN CHANGED
+
+Material change: ...
+Reason: ...
+Revised plan: ...
+```
+
+Foreground the revised PRIMARY plan review surface when supported, then require renewed plan approval. Do not silently continue implementation under stale authorization.
 
 ## 6. Working branch setup
 
 Once implementation is authorized to begin, establish the repository-appropriate short-lived work branch as routine setup before substantive edits.
 
+For STANDARD/ELEVATED work, **plan approval is the implementation authorization boundary**. Do not create/switch the implementation branch merely because `/start-work` was invoked or a plan was produced.
+
 Do not ask a separate branch-creation permission when all of the following are true:
-- the current branch is the default/integration branch and repository policy expects short-lived work branches,
-- the work-item boundary is clear,
-- the target branch name is unambiguous under repository convention or the Project Forge fallback below,
+- implementation is already authorized under the applicable gate;
+- the current branch is the default/integration branch and repository policy expects short-lived work branches;
+- the work-item boundary is clear;
+- the target branch name is unambiguous under repository convention or the Project Forge fallback below;
 - creating/switching branches does not require history rewriting or discarding work.
 
 Branch naming order:
@@ -152,7 +251,7 @@ If scoped uncommitted changes already exist on the default branch and clearly be
 
 Stop and ask only when branch policy/naming is materially ambiguous, the intended branch already exists with divergent work, unrelated changes are present, or the operation would require stash/reset/rebase/force/history rewriting.
 
-For LIGHT work, branch setup is part of the human-selected implementation action. For STANDARD/ELEVATED work, it is part of the approved implementation start after plan approval. Merely inspecting `/start-work` does not authorize implementation before its required gate.
+For LIGHT work, branch setup is part of the human-selected implementation action. For STANDARD/ELEVATED work, it is part of the explicit approved implementation start after plan approval.
 
 ## 7. Deployment enabler
 
@@ -182,10 +281,13 @@ Return:
 - CURRENT STATE,
 - risk level and why,
 - requirement readiness,
-- branch state / expected short-lived branch when implementation is about to begin,
+- current review subject when a human gate is pending,
+- branch state / expected short-lived branch only after implementation is authorized or about to begin,
 - RECOMMENDED NEXT STEP,
 - a small set of relevant action choices.
 
 Render mutually exclusive next actions through the host's **single-select structured choice UI** when available, following `INTERACTIVE_SESSION_GUIDE.md`. In VS Code, use the native question surface such as `vscode_askQuestions`. Make the recommended action visible when evidence supports one, include `Other / specify` or free-text only when the action set may be incomplete, and use a numbered text menu only as the no-structured-UI fallback.
 
-Do not skip an unresolved requirement/plan gate merely because implementation is technically possible. Once implementation is selected/approved, do not insert a separate ceremonial branch-creation gate when the branch setup is safe and deterministic.
+If the workflow has reached the STANDARD/ELEVATED plan gate, stop there until the human selects an explicit plan action. Do not include an alternate implementation action that bypasses the plan gate.
+
+Do not skip an unresolved requirement/plan gate merely because implementation is technically possible. Once implementation is explicitly approved, do not insert a separate ceremonial branch-creation gate when the branch setup is safe and deterministic.

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

@@ -1,11 +1,29 @@
 # Project Forge Work Item Status
 
-This optional local VS Code extension decorates Project Forge work-item folders in the Explorer from repository evidence.
+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.
+
+## Work-item status
 
 - `●` — in progress, supported by the current work-item branch or an open pull request.
 - `✓` — complete, supported by a merged pull request to the repository default branch.
 - no badge — no status is asserted.
 
-The extension is read-only. It does not rename or edit work-item folders/documents and does not maintain a second status database. It reads local Git state and, when available, GitHub CLI pull-request metadata. Project Forge's normal repository/PR/CI evidence remains authoritative.
+The status decoration is evidence-derived and non-authoritative. It does not rename or edit work-item folders/documents and does not maintain a second status database. It reads local Git state and, when available, GitHub CLI pull-request metadata. Project Forge's normal repository/PR/CI evidence remains authoritative.
 
 Use **Project Forge: Refresh Work Item Status** from the Command Palette to refresh immediately. The extension also refreshes periodically and when common local Git/work-item evidence changes.
+
+## Human review artifact helper
+
+Project Forge workflows may use **Project Forge: Open Review Artifact** immediately before a human approval gate.
+
+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.
+
+Behavior:
+
+- Markdown files open in rendered Markdown Preview when available;
+- 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;
+- 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.

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

@@ -153,6 +153,138 @@ async function computeRootStatus(root) {
   return { folders, statusById };
 }
 
+function canonicalExistingPath(value) {
+  try {
+    return fs.realpathSync.native
+      ? fs.realpathSync.native(value)
+      : fs.realpathSync(value);
+  } catch {
+    return path.resolve(value);
+  }
+}
+
+function isPathInside(root, candidate) {
+  const canonicalRoot = canonicalExistingPath(root);
+  const canonicalCandidate = canonicalExistingPath(candidate);
+  const relative = path.relative(canonicalRoot, canonicalCandidate);
+  return relative === '' || (
+    relative !== '..' &&
+    !relative.startsWith(`..${path.sep}`) &&
+    !path.isAbsolute(relative)
+  );
+}
+
+function reviewTargetPath(target) {
+  if (typeof target === 'string') {
+    return target.trim();
+  }
+  if (target && typeof target.fsPath === 'string') {
+    return target.fsPath;
+  }
+  if (target && typeof target.path === 'string') {
+    return target.path.trim();
+  }
+  return '';
+}
+
+function isRegularFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function resolveReviewUri(target) {
+  let requested = reviewTargetPath(target);
+  if (!requested) {
+    requested = (await vscode.window.showInputBox({
+      prompt: 'Workspace-relative Project Forge review artifact path',
+      placeHolder: 'docs/work-items/.../requirements.md',
+      ignoreFocusOut: true,
+    })) || '';
+  }
+  requested = requested.trim();
+  if (!requested) {
+    return undefined;
+  }
+
+  const folders = vscode.workspace.workspaceFolders || [];
+  if (!folders.length) {
+    throw new Error('No VS Code workspace is open.');
+  }
+
+  if (path.isAbsolute(requested)) {
+    const candidate = canonicalExistingPath(requested);
+    const owner = folders.find((folder) => isPathInside(folder.uri.fsPath, candidate));
+    if (!owner) {
+      throw new Error('Review artifact must be inside the open workspace.');
+    }
+    if (!isRegularFile(candidate)) {
+      throw new Error(`Review artifact was not found: ${requested}`);
+    }
+    return vscode.Uri.file(candidate);
+  }
+
+  const matches = [];
+  for (const folder of folders) {
+    const candidate = canonicalExistingPath(path.resolve(folder.uri.fsPath, requested));
+    if (!isPathInside(folder.uri.fsPath, candidate) || !isRegularFile(candidate)) {
+      continue;
+    }
+    matches.push({ folder, uri: vscode.Uri.file(candidate) });
+  }
+
+  if (matches.length === 1) {
+    return matches[0].uri;
+  }
+  if (!matches.length) {
+    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) {
+  try {
+    const uri = await resolveReviewUri(target);
+    if (!uri) {
+      return undefined;
+    }
+
+    const extension = path.extname(uri.fsPath).toLowerCase();
+    if (extension === '.md' || extension === '.markdown') {
+      try {
+        await vscode.commands.executeCommand('markdown.showPreview', uri);
+        return uri.toString();
+      } catch {
+        // Fall back to the normal editor preview surface when Markdown preview is unavailable.
+      }
+    }
+
+    await vscode.commands.executeCommand('vscode.open', uri, {
+      preview: true,
+      preserveFocus: false,
+    });
+    return uri.toString();
+  } catch (error) {
+    const message = error && error.message ? error.message : String(error);
+    await vscode.window.showWarningMessage(`Project Forge review artifact: ${message}`);
+    return undefined;
+  }
+}
+
 class WorkItemDecorationProvider {
   constructor() {
     this._onDidChangeFileDecorations = new vscode.EventEmitter();
@@ -238,6 +370,9 @@ function activate(context) {
   context.subscriptions.push(
     vscode.commands.registerCommand('projectForge.refreshWorkItemStatus', refresh),
   );
+  context.subscriptions.push(
+    vscode.commands.registerCommand('projectForge.openReviewArtifact', openReviewArtifact),
+  );
   context.subscriptions.push(
     vscode.window.onDidChangeWindowState((event) => {
       if (event.focused) {
@@ -271,4 +406,4 @@ function activate(context) {
 
 function deactivate() {}
 
-module.exports = { activate, deactivate };
+module.exports = { activate, deactivate, openReviewArtifact, resolveReviewUri };

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

@@ -1,8 +1,8 @@
 {
   "name": "project-forge-work-item-status",
   "displayName": "Project Forge Work Item Status",
-  "description": "Shows evidence-backed Project Forge work-item status badges in the VS Code Explorer.",
-  "version": "0.1.0",
+  "description": "Shows evidence-backed Project Forge work-item status badges and provides read-only review-surface helpers in VS Code.",
+  "version": "0.2.0",
   "publisher": "project-forge",
   "license": "UNLICENSED",
   "engines": {
@@ -14,10 +14,12 @@
   "keywords": [
     "project-forge",
     "work-items",
-    "explorer"
+    "explorer",
+    "review"
   ],
   "activationEvents": [
-    "workspaceContains:docs/work-items/*"
+    "workspaceContains:docs/work-items/*",
+    "onCommand:projectForge.openReviewArtifact"
   ],
   "main": "./extension.js",
   "extensionKind": [
@@ -26,7 +28,7 @@
   "capabilities": {
     "untrustedWorkspaces": {
       "supported": false,
-      "description": "The extension reads local Git state and optional GitHub CLI pull-request evidence."
+      "description": "The extension reads local Git state and optional GitHub CLI pull-request evidence, and may open workspace review artifacts on explicit Project Forge commands."
     }
   },
   "contributes": {
@@ -34,6 +36,10 @@
       {
         "command": "projectForge.refreshWorkItemStatus",
         "title": "Project Forge: Refresh Work Item Status"
+      },
+      {
+        "command": "projectForge.openReviewArtifact",
+        "title": "Project Forge: Open Review Artifact"
       }
     ]
   }