@mriekki/project-forge 4.10.4 → 4.11.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.10.4",
+  "version": "4.11.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "8796fd8dc22df8b64078e5b460e1008a8c7a5f7d",
+      "revision": "7a0c5a3ef42c0d6f38203007c957c3e59cbf4f8b",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",

package/assets/core/distribution.json

@@ -18,6 +18,7 @@
     {"source":"core/skills/progress/SKILL.md","destination":".github/skills/progress/SKILL.md"},
     {"source":"core/skills/next-step/SKILL.md","destination":".github/skills/next-step/SKILL.md"},
     {"source":"core/skills/deliver/SKILL.md","destination":".github/skills/deliver/SKILL.md"},
+    {"source":"core/skills/work-item-status/SKILL.md","destination":".github/skills/work-item-status/SKILL.md"},
     {"source":"core/skills/cleanup-branches/SKILL.md","destination":".github/skills/cleanup-branches/SKILL.md"},
     {"source":"core/skills/pull-latest/SKILL.md","destination":".github/skills/pull-latest/SKILL.md"},
     {"source":"core/skills/project-forge-update/SKILL.md","destination":".github/skills/project-forge-update/SKILL.md"},
@@ -63,6 +64,10 @@
     {"source":"tools/db_lab/sqlite_workbench.py","destination":"tools/project-forge-db-lab/sqlite-workbench.py"},
     {"source":"tools/system_lab/system_workbench.py","destination":"tools/project-forge-system-lab/system-workbench.py"},
     {"source":"tools/docs_site/docs_site.py","destination":"tools/project-forge-docs/docs-site.py"},
+    {"source":"tools/vscode_work_item_status/install.py","destination":"tools/project-forge-vscode/work-item-status/install.py"},
+    {"source":"tools/vscode_work_item_status/extension/package.json","destination":"tools/project-forge-vscode/work-item-status/extension/package.json"},
+    {"source":"tools/vscode_work_item_status/extension/extension.js","destination":"tools/project-forge-vscode/work-item-status/extension/extension.js"},
+    {"source":"tools/vscode_work_item_status/extension/README.md","destination":"tools/project-forge-vscode/work-item-status/extension/README.md"},
     {"source":"tools/package/check_baseline.py","destination":"tools/project-forge-core/check-core-baseline.py"},
     {"source":"tools/package/check_upstream.py","destination":"tools/project-forge-core/check-core-upstream.py"}
   ]

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.10.4",
+  "version": "4.11.0",
   "components": {
     "core": {
-      "revision": "8796fd8dc22df8b64078e5b460e1008a8c7a5f7d",
+      "revision": "7a0c5a3ef42c0d6f38203007c957c3e59cbf4f8b",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -51,7 +51,7 @@
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "27419e0d330abf2b6b03a696eba352ab2ece13a616c41fc0ade9aed85e8834f1"
+          "sha256": "9b3dee1d965f1999490d0e3c58925c341ac5f3f5b228ccfe6a0ac53d64b19a64"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -86,7 +86,12 @@
         {
           "source": "core/skills/deliver/SKILL.md",
           "destination": ".github/skills/deliver/SKILL.md",
-          "sha256": "238d6c81a7253c4241e4cf8588be5a5986b406b7e3a56cac115fc47a46071c71"
+          "sha256": "6a3886493e9b59725ff53652972c1830478176a8c8da648448401d9051820db4"
+        },
+        {
+          "source": "core/skills/work-item-status/SKILL.md",
+          "destination": ".github/skills/work-item-status/SKILL.md",
+          "sha256": "7235ceebebc61519f2aa6c903ab8e814ba33cb029db4b7e5626852f935038c3c"
         },
         {
           "source": "core/skills/cleanup-branches/SKILL.md",
@@ -161,7 +166,7 @@
         {
           "source": "core/process/WORK_ITEM_MODEL.md",
           "destination": "docs/process/WORK_ITEM_MODEL.md",
-          "sha256": "20a8dcc6ead4fe9b491917766ae402265bc84daa5ba1445d3628900044e9a1ab"
+          "sha256": "8d891d41691324b0552f94fe79b9f6f33ec3c50aaed96bef69a86c2fef3d93e3"
         },
         {
           "source": "core/process/PR_WORKFLOW.md",
@@ -313,6 +318,26 @@
           "destination": "tools/project-forge-docs/docs-site.py",
           "sha256": "8b0fe9a63a84a09ceeb71db0265186e427e92c8ce61e925b98f3be66682078ec"
         },
+        {
+          "source": "tools/vscode_work_item_status/install.py",
+          "destination": "tools/project-forge-vscode/work-item-status/install.py",
+          "sha256": "190015b44611b5b6f0f21bff05923262abd9d9e16e9916dbe71755fb753d8fbc"
+        },
+        {
+          "source": "tools/vscode_work_item_status/extension/package.json",
+          "destination": "tools/project-forge-vscode/work-item-status/extension/package.json",
+          "sha256": "3ae6351df5aa0fa4908e0e4456c84ac6e9477fde0074226d1aac0316f23b9116"
+        },
+        {
+          "source": "tools/vscode_work_item_status/extension/extension.js",
+          "destination": "tools/project-forge-vscode/work-item-status/extension/extension.js",
+          "sha256": "50b7551c1abc1c30552945dedaf602569dfdf770cad0b2d4652e46f2910231d8"
+        },
+        {
+          "source": "tools/vscode_work_item_status/extension/README.md",
+          "destination": "tools/project-forge-vscode/work-item-status/extension/README.md",
+          "sha256": "9e1d1e8b53d27c07e8de72d38db420740d7e1b3301ab146531d89882cd088418"
+        },
         {
           "source": "tools/package/check_baseline.py",
           "destination": "tools/project-forge-core/check-core-baseline.py",

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

@@ -54,3 +54,11 @@ Jira Epic == Feature Brief
 Possible relationships vary by team: an Epic may be a feature, initiative, technical workstream, or delivery container; one Epic may have no Feature Brief, one brief, or several.
 
 Existing team conventions outrank Project Forge defaults. Do not create a competing local source of truth merely because Project Forge has a template.
+
+## Execution-state views
+
+Editor badges, dashboards, and `/progress` may summarize work-item execution state from current repository evidence, but those views are not additional workflow authorities.
+
+Keep stable work-item IDs and paths unchanged merely to display status. In particular, do not prefix or rename work-item folders with status text or emoji, and do not reuse a brief/requirements `Status:` field for implementation progress when that field already represents requirement maturity or approval.
+
+Prefer derived views over a second tracked status database. When evidence is incomplete, show no status or `NOT EVIDENCED` rather than inventing completion.

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

@@ -137,6 +137,16 @@ PR evidence may include:
 
 Do not claim evidence that was not observed.
 
+For work with a stable work-item ID, keep one hidden Project Forge navigation marker in the PR body using the exact resolved ID:
+
+```html
+<!-- project-forge-work-item: <ID> -->
+```
+
+The marker is navigation metadata only. It does not prove requirement approval, implementation acceptance, review, CI, merge readiness, delivery completion, deployment, or any other lifecycle state. Never use the marker alone to satisfy a gate.
+
+When `/deliver` resumes an existing PR that clearly corresponds to the same ID-backed work item and the marker is absent, adding the marker is routine PR-body maintenance within the existing `/deliver` authorization. Preserve the rest of the existing PR body and do not add or rewrite the marker when the work-item identity is ambiguous. For ad hoc work without a stable work-item ID, omit the marker rather than inventing one.
+
 ## 6. Stop conditions during routine delivery
 
 Stop before/during routine writes for:
@@ -398,4 +408,4 @@ The optional learning handoff does not block or replace deployment readiness whe
 
 `/deliver` takes reviewed/accepted work through routine branch/commit/push/PR/CI mechanics automatically, then stops once for the merge-and-finalize decision. After successful engineering completion it may prepare disposable learning workbenches and shows an optional learning handoff without creating another gate.
 
-`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.
+`/cleanup-branches` is the standalone preview-first path for accumulated, previously retained, unrelated, or otherwise out-of-band branch housekeeping.

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

@@ -214,6 +214,28 @@ Rules:
 - the recorded setup scope comes from the developer's actual selections;
 - later environment changes belong in mutable project topology, not casual rewrites of Bootstrap provenance.
 
+### Builder-owned target namespace
+
+Treat reusable remote target definitions as Builder-owned personal state. The Project owns logical environment roles and a logical `targetProfile` binding; it does not own another Builder's physical machine, SSH identity, trust, current address, or readiness.
+
+The same logical target name may resolve to a different physical machine for another developer. For example, Project topology may bind `Production -> production`; each Builder may define their own personal `production` target with their own hostname, SSH account, identity, and trust. Do not treat another Builder's target profile, hostname, SSH identity/trust, address, or readiness as authoritative for this workstation.
+
+When an already-bound remote environment references `<target>` but this Builder's personal/local profile has no such target, do not describe the Project as broken and do not ask the Builder to gain access to another person's box. Surface the condition explicitly:
+
+```text
+<ENVIRONMENT> TARGET NOT CONFIGURED FOR THIS BUILDER
+
+This Project binds <environment> to logical target <target>, but this
+Builder has not defined that target in their personal Project Forge profile.
+
+CHOICES
+Define my target `<target>` [RECOMMENDED]
+Sync/import my personal target `<target>` if I already defined it elsewhere
+Keep `<environment>` unavailable on this Builder
+```
+
+`Define my target` uses the supported personal target-profile flow and preserves the Project's existing logical `targetProfile` name. Do not silently substitute a differently named personal target merely because it is reachable; selecting a different logical target is a Project topology rebind and requires its separate explicit decision. Production-class configuration/access remains distinct from Production proof and application-deployment authorization.
+
 ### Define another environment
 
 For `Other / define another environment`, collect only material durable facts, normally:
@@ -482,4 +504,4 @@ Useful next actions include:
 - `/deploy <environment>` — only after readiness and its own authorization contract;
 - `/tear-down <scope>` — destructive cleanup under its separate gate.
 
-Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.
+Do not create a second top-level developer-environment-mode workflow. Local/remote workstation convergence belongs here.

package/assets/generated/core/core/skills/work-item-status/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: work-item-status
+description: "Inspect or manage the optional VS Code Explorer decoration that shows evidence-backed Project Forge work-item progress without renaming or editing work-item tickets."
+argument-hint: "[status|enable|disable]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Work Item Status
+
+Purpose: make local `docs/work-items/<ID>-...` folders easier to scan in VS Code without changing work-item paths, ticket content, or Project Forge workflow authority.
+
+Normal use is read-only:
+
+```text
+/work-item-status
+/work-item-status status
+```
+
+The optional editor decoration uses the existing Project Forge progress vocabulary:
+
+```text
+● IN PROGRESS
+✓ COMPLETE
+```
+
+No badge means Project Forge is not asserting an execution state for that folder.
+
+## 1. Authority boundary
+
+The Explorer badge is a **view of repository evidence**, not a source of truth.
+
+Never:
+- rename a work-item folder to add status text or emoji;
+- rewrite the work item's requirements/brief `Status:` field to represent execution progress;
+- create a second tracked work-item status database merely for the badge;
+- infer completion from an expected lifecycle step that was not observed.
+
+Normal work-item docs, Git branches, pull requests, CI/review/default-branch evidence, and `/progress` remain authoritative.
+
+## 2. Status evidence
+
+The local VS Code extension is deliberately conservative.
+
+`● IN PROGRESS` may be shown when the work-item ID is supported by:
+- this checkout's current work branch; or
+- an open pull request whose hidden Project Forge marker or work-item branch identifies the folder ID.
+
+`✓ COMPLETE` may be shown when a merged pull request to the repository default branch identifies the work-item ID. New Project Forge delivery PRs should carry the hidden marker:
+
+```html
+<!-- project-forge-work-item: <ID> -->
+```
+
+At runtime, `<ID>` is replaced by the exact stable work-item ID already resolved for delivery. The marker is navigation metadata only. It does not prove acceptance, CI, deployment, or any other lifecycle gate. For older Project Forge PRs, the extension may use the repository's normal ID-backed branch naming as compatibility evidence.
+
+When GitHub CLI evidence is unavailable, the extension may still show current-branch `IN PROGRESS` state but must not invent merged/completed state.
+
+## 3. Inspect status
+
+Locate the Core-managed installer when present:
+
+```text
+tools/project-forge-vscode/work-item-status/install.py
+```
+
+For `status`, run it read-only:
+
+```text
+python tools/project-forge-vscode/work-item-status/install.py status --json
+```
+
+Also check whether `docs/work-items` exists. If the Project uses an external-only work-item source with no local work-item folders, report the Explorer decoration as not applicable rather than creating a competing local hierarchy.
+
+A useful result is:
+
+```text
+WORK-ITEM EXPLORER STATUS
+
+Local work-item folders .... PRESENT / NOT PRESENT
+VS Code decorator .......... READY / NOT INSTALLED / ERROR
+Project workflow authority . UNCHANGED
+```
+
+## 4. Enable
+
+`/work-item-status enable` is explicit authorization for one bounded local editor change: install/update the Project Forge-owned extension in this developer's VS Code extensions directory.
+
+Run:
+
+```text
+python tools/project-forge-vscode/work-item-status/install.py install --json
+```
+
+The installer may replace older versions of **this same Project Forge extension only**. It must not install unrelated extensions, alter Project files, change work-item docs, or change Git/GitHub state.
+
+If installation changes the extension, tell the developer to reload VS Code once. The decorator then refreshes automatically and also exposes:
+
+```text
+Project Forge: Refresh Work Item Status
+```
+
+through the VS Code Command Palette.
+
+Failure to install this optional decoration does **not** make Project setup, implementation, review, delivery, or deployment unready.
+
+## 5. Disable
+
+`/work-item-status disable` is explicit authorization to remove only Project Forge's own work-item-status extension from this developer's local VS Code extensions directory.
+
+Run:
+
+```text
+python tools/project-forge-vscode/work-item-status/install.py uninstall --json
+```
+
+Do not remove any other extension. If files were removed, tell the developer to reload VS Code once.
+
+## 6. Guided ending
+
+Return:
+- decorator installation state;
+- whether local `docs/work-items` folders are present;
+- a reminder that badges are evidence-derived and non-authoritative;
+- the smallest relevant next action.
+
+Do not turn this optional convenience into a required Project Forge gate.

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

@@ -0,0 +1,11 @@
+# Project Forge Work Item Status
+
+This optional local VS Code extension decorates Project Forge work-item folders in the Explorer from repository evidence.
+
+- `●` — 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.
+
+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.

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

@@ -0,0 +1,274 @@
+'use strict';
+
+const vscode = require('vscode');
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+
+const execFileAsync = promisify(execFile);
+const WORK_ITEMS_RELATIVE = path.join('docs', 'work-items');
+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;
+
+function normalizeId(value) {
+  return value ? value.toUpperCase() : undefined;
+}
+
+function workItemIdFromFolderName(name) {
+  const match = ID_FROM_NAME.exec(name);
+  return match ? normalizeId(match[1]) : undefined;
+}
+
+function workItemIdFromBranch(name) {
+  const match = ID_FROM_BRANCH.exec(name || '');
+  return match ? normalizeId(match[1]) : undefined;
+}
+
+function workItemIdsFromPr(pr) {
+  const ids = new Set();
+  const body = typeof pr.body === 'string' ? pr.body : '';
+  MARKER.lastIndex = 0;
+  for (let match = MARKER.exec(body); match; match = MARKER.exec(body)) {
+    ids.add(normalizeId(match[1]));
+  }
+  const branchId = workItemIdFromBranch(pr.headRefName);
+  if (branchId) {
+    ids.add(branchId);
+  }
+  return ids;
+}
+
+async function run(command, args, cwd) {
+  try {
+    const result = await execFileAsync(command, args, {
+      cwd,
+      encoding: 'utf8',
+      timeout: 6000,
+      windowsHide: true,
+      maxBuffer: 1024 * 1024,
+    });
+    return (result.stdout || '').trim();
+  } catch {
+    return undefined;
+  }
+}
+
+async function readJsonCommand(command, args, cwd) {
+  const output = await run(command, args, cwd);
+  if (!output) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(output);
+  } catch {
+    return undefined;
+  }
+}
+
+async function defaultBranch(root) {
+  const repo = await readJsonCommand('gh', ['repo', 'view', '--json', 'defaultBranchRef'], root);
+  const fromGh = repo && repo.defaultBranchRef && repo.defaultBranchRef.name;
+  if (fromGh) {
+    return fromGh;
+  }
+  const remoteHead = await run('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], root);
+  if (remoteHead && remoteHead.includes('/')) {
+    return remoteHead.slice(remoteHead.lastIndexOf('/') + 1);
+  }
+  return 'main';
+}
+
+async function listWorkItemFolders(root) {
+  const directory = path.join(root, WORK_ITEMS_RELATIVE);
+  try {
+    const entries = await fsp.readdir(directory, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => ({
+        id: workItemIdFromFolderName(entry.name),
+        uri: vscode.Uri.file(path.join(directory, entry.name)),
+      }))
+      .filter((entry) => entry.id);
+  } catch {
+    return [];
+  }
+}
+
+async function githubPrEvidence(root) {
+  const [openPrs, mergedPrs, base] = await Promise.all([
+    readJsonCommand('gh', ['pr', 'list', '--state', 'open', '--limit', '100', '--json', 'number,body,headRefName,baseRefName,url'], root),
+    readJsonCommand('gh', ['pr', 'list', '--state', 'merged', '--limit', '200', '--json', 'number,body,headRefName,baseRefName,mergedAt,url'], root),
+    defaultBranch(root),
+  ]);
+  return {
+    openPrs: Array.isArray(openPrs) ? openPrs : [],
+    mergedPrs: Array.isArray(mergedPrs) ? mergedPrs : [],
+    defaultBranch: base,
+  };
+}
+
+async function computeRootStatus(root) {
+  const folders = await listWorkItemFolders(root);
+  if (!folders.length) {
+    return { folders, statusById: new Map() };
+  }
+
+  const statusById = new Map();
+  const evidence = await githubPrEvidence(root);
+
+  for (const pr of evidence.mergedPrs) {
+    if (pr.baseRefName !== evidence.defaultBranch) {
+      continue;
+    }
+    for (const id of workItemIdsFromPr(pr)) {
+      statusById.set(id, {
+        state: 'complete',
+        detail: `merged PR #${pr.number}`,
+      });
+    }
+  }
+
+  for (const pr of evidence.openPrs) {
+    for (const id of workItemIdsFromPr(pr)) {
+      statusById.set(id, {
+        state: 'in-progress',
+        detail: `open PR #${pr.number}`,
+      });
+    }
+  }
+
+  const branch = await run('git', ['branch', '--show-current'], root);
+  const currentId = workItemIdFromBranch(branch);
+  if (currentId) {
+    statusById.set(currentId, {
+      state: 'in-progress',
+      detail: `current branch ${branch}`,
+    });
+  }
+
+  return { folders, statusById };
+}
+
+class WorkItemDecorationProvider {
+  constructor() {
+    this._onDidChangeFileDecorations = new vscode.EventEmitter();
+    this.onDidChangeFileDecorations = this._onDidChangeFileDecorations.event;
+    this.byPath = new Map();
+    this.uris = [];
+  }
+
+  provideFileDecoration(uri) {
+    const entry = this.byPath.get(path.normalize(uri.fsPath));
+    if (!entry) {
+      return undefined;
+    }
+    if (entry.state === 'complete') {
+      return {
+        badge: '✓',
+        color: new vscode.ThemeColor('gitDecoration.addedResourceForeground'),
+        tooltip: `Project Forge: COMPLETE — ${entry.detail}`,
+        propagate: false,
+      };
+    }
+    if (entry.state === 'in-progress') {
+      return {
+        badge: '●',
+        color: new vscode.ThemeColor('gitDecoration.modifiedResourceForeground'),
+        tooltip: `Project Forge: IN PROGRESS — ${entry.detail}`,
+        propagate: false,
+      };
+    }
+    return undefined;
+  }
+
+  async refresh() {
+    const next = new Map();
+    const nextUris = [];
+    const roots = (vscode.workspace.workspaceFolders || []).map((folder) => folder.uri.fsPath);
+
+    for (const root of roots) {
+      if (!fs.existsSync(path.join(root, WORK_ITEMS_RELATIVE))) {
+        continue;
+      }
+      const result = await computeRootStatus(root);
+      for (const folder of result.folders) {
+        nextUris.push(folder.uri);
+        const status = result.statusById.get(folder.id);
+        if (status) {
+          next.set(path.normalize(folder.uri.fsPath), status);
+        }
+      }
+    }
+
+    const changed = [...this.uris, ...nextUris];
+    this.byPath = next;
+    this.uris = nextUris;
+    if (changed.length) {
+      this._onDidChangeFileDecorations.fire(changed);
+    }
+  }
+
+  dispose() {
+    this._onDidChangeFileDecorations.dispose();
+  }
+}
+
+function activate(context) {
+  const provider = new WorkItemDecorationProvider();
+  context.subscriptions.push(provider);
+  context.subscriptions.push(vscode.window.registerFileDecorationProvider(provider));
+
+  let refreshing = false;
+  const refresh = async () => {
+    if (refreshing) {
+      return;
+    }
+    refreshing = true;
+    try {
+      await provider.refresh();
+    } finally {
+      refreshing = false;
+    }
+  };
+
+  context.subscriptions.push(
+    vscode.commands.registerCommand('projectForge.refreshWorkItemStatus', refresh),
+  );
+  context.subscriptions.push(
+    vscode.window.onDidChangeWindowState((event) => {
+      if (event.focused) {
+        void refresh();
+      }
+    }),
+  );
+
+  for (const folder of vscode.workspace.workspaceFolders || []) {
+    const head = vscode.workspace.createFileSystemWatcher(
+      new vscode.RelativePattern(folder, '.git/HEAD'),
+    );
+    const refs = vscode.workspace.createFileSystemWatcher(
+      new vscode.RelativePattern(folder, '.git/refs/heads/**'),
+    );
+    const workItems = vscode.workspace.createFileSystemWatcher(
+      new vscode.RelativePattern(folder, 'docs/work-items/*'),
+    );
+    for (const watcher of [head, refs, workItems]) {
+      watcher.onDidChange(() => void refresh());
+      watcher.onDidCreate(() => void refresh());
+      watcher.onDidDelete(() => void refresh());
+      context.subscriptions.push(watcher);
+    }
+  }
+
+  const timer = setInterval(() => void refresh(), REFRESH_INTERVAL_MS);
+  context.subscriptions.push({ dispose: () => clearInterval(timer) });
+  void refresh();
+}
+
+function deactivate() {}
+
+module.exports = { activate, deactivate };

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

@@ -0,0 +1,40 @@
+{
+  "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",
+  "publisher": "project-forge",
+  "license": "UNLICENSED",
+  "engines": {
+    "vscode": "^1.90.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "keywords": [
+    "project-forge",
+    "work-items",
+    "explorer"
+  ],
+  "activationEvents": [
+    "workspaceContains:docs/work-items/*"
+  ],
+  "main": "./extension.js",
+  "extensionKind": [
+    "workspace"
+  ],
+  "capabilities": {
+    "untrustedWorkspaces": {
+      "supported": false,
+      "description": "The extension reads local Git state and optional GitHub CLI pull-request evidence."
+    }
+  },
+  "contributes": {
+    "commands": [
+      {
+        "command": "projectForge.refreshWorkItemStatus",
+        "title": "Project Forge: Refresh Work Item Status"
+      }
+    ]
+  }
+}

package/assets/generated/core/tools/vscode_work_item_status/install.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+HERE = Path(__file__).resolve().parent
+SOURCE = HERE / "extension"
+MANIFEST = SOURCE / "package.json"
+
+
+def load_manifest() -> dict[str, Any]:
+    return json.loads(MANIFEST.read_text(encoding="utf-8"))
+
+
+def extension_identity() -> tuple[str, str]:
+    manifest = load_manifest()
+    publisher = str(manifest["publisher"]).strip()
+    name = str(manifest["name"]).strip()
+    version = str(manifest["version"]).strip()
+    if not publisher or not name or not version:
+        raise RuntimeError("Project Forge VS Code extension manifest is incomplete")
+    return f"{publisher}.{name}", version
+
+
+def default_extensions_root() -> Path:
+    override = os.environ.get("VSCODE_EXTENSIONS")
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".vscode" / "extensions"
+
+
+def extension_target(root: Path) -> Path:
+    extension_id, version = extension_identity()
+    return root / f"{extension_id}-{version}"
+
+
+def status(root: Path) -> dict[str, Any]:
+    extension_id, version = extension_identity()
+    target = extension_target(root)
+    ready = target.is_dir() and all(
+        (target / name).is_file() for name in ("package.json", "extension.js", "README.md")
+    )
+    return {
+        "extensionId": extension_id,
+        "version": version,
+        "status": "ready" if ready else "not-installed",
+        "path": str(target),
+        "reloadRequired": False,
+    }
+
+
+def install(root: Path) -> dict[str, Any]:
+    extension_id, version = extension_identity()
+    root.mkdir(parents=True, exist_ok=True)
+    target = extension_target(root)
+
+    if not SOURCE.is_dir():
+        raise RuntimeError(f"Missing Project Forge VS Code extension source: {SOURCE}")
+
+    existing = status(root)
+    if existing["status"] == "ready":
+        return existing
+
+    with tempfile.TemporaryDirectory(prefix="project-forge-vscode-", dir=str(root)) as tmp:
+        staged = Path(tmp) / target.name
+        shutil.copytree(SOURCE, staged)
+        if target.exists():
+            shutil.rmtree(target)
+        staged.rename(target)
+
+    prefix = f"{extension_id}-"
+    for candidate in root.iterdir():
+        if candidate == target or not candidate.is_dir() or not candidate.name.startswith(prefix):
+            continue
+        shutil.rmtree(candidate)
+
+    result = status(root)
+    result["reloadRequired"] = True
+    return result
+
+
+def uninstall(root: Path) -> dict[str, Any]:
+    extension_id, version = extension_identity()
+    prefix = f"{extension_id}-"
+    removed: list[str] = []
+    if root.exists():
+        for candidate in root.iterdir():
+            if candidate.is_dir() and candidate.name.startswith(prefix):
+                shutil.rmtree(candidate)
+                removed.append(str(candidate))
+    return {
+        "extensionId": extension_id,
+        "version": version,
+        "status": "not-installed",
+        "removed": removed,
+        "reloadRequired": bool(removed),
+    }
+
+
+def emit(result: dict[str, Any], as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(result, sort_keys=True))
+        return
+    print(f"Project Forge Work Item Status: {result['status'].upper()}")
+    print(f"Extension: {result['extensionId']}@{result['version']}")
+    if result.get("path"):
+        print(f"Path: {result['path']}")
+    if result.get("removed"):
+        print(f"Removed: {len(result['removed'])}")
+    if result.get("reloadRequired"):
+        print("Reload VS Code to activate the changed extension installation.")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Install or inspect the optional Project Forge VS Code work-item status decorator."
+    )
+    parser.add_argument("action", choices=["status", "install", "uninstall"])
+    parser.add_argument("--extensions-dir", type=Path, help="Override the VS Code extensions directory.")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    root = (args.extensions_dir or default_extensions_root()).expanduser().resolve()
+    try:
+        if args.action == "install":
+            result = install(root)
+        elif args.action == "uninstall":
+            result = uninstall(root)
+        else:
+            result = status(root)
+    except (OSError, RuntimeError, ValueError, json.JSONDecodeError) as exc:
+        if args.json:
+            print(json.dumps({"status": "error", "error": str(exc)}, sort_keys=True))
+        else:
+            print(f"Project Forge Work Item Status: ERROR — {exc}", file=sys.stderr)
+        return 1
+
+    emit(result, args.json)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

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