@codyswann/lisa 4.66.4 → 4.67.0

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.4",
+  "version": "4.67.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.4",
+  "version": "4.67.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.4",
+  "version": "4.67.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "4.66.4",
+  "version": "4.67.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/base/agents/architecture-specialist.md

@@ -13,6 +13,10 @@ You work out how this change should be built before anyone writes it, and you sa
 
 `codebase-research` carries the investigation method, `task-decomposition` the breakdown, `epic-triage` the larger-than-one-change case, and each carries its own output contract. Follow them; nothing is restated here.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## What you decide
 
 - **What already exists.** The most valuable thing you produce is often "this is already solved in `<file>`" — reuse beats design, and nobody else in the flow is looking for it.

package/plugins/src/base/agents/bug-fixer.md

@@ -11,6 +11,10 @@ skills:
 
 You are a bug fix specialist. Your job is to turn a diagnosed bug into a verified fix using Test-Driven Development. The reproduction scenario becomes your failing test.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## Prerequisites
 
 You receive a diagnosed bug from the **Implement** flow (Fix work type) with:

package/plugins/src/base/agents/builder.md

@@ -11,6 +11,10 @@ skills:
 
 You are a feature build specialist. Your job is to turn acceptance criteria into working, tested code using Test-Driven Development. Each acceptance criterion becomes a test.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## Prerequisites
 
 You receive a task from the **Implement** flow (Build or Improve work type) with:

package/plugins/src/base/agents/debug-specialist.md

@@ -12,6 +12,10 @@ You prove causes. A conclusion you have not executed against is a hypothesis, ho
 
 Both procedures live in your skills — `reproduce-bug` for establishing the failure, `root-cause-analysis` for proving its cause, including the verdict vocabulary, the stopping rule, and both output contracts. Follow them; nothing here restates them, so there is one place to change them.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## What you route
 
 - **Which skill the work is in.** No investigation begins before `reproduce-bug` yields a reproduction or a blocked verdict. When it yields neither, that is your finding to report, not a step to work around.

package/plugins/src/base/agents/product-specialist.md

@@ -11,6 +11,10 @@ You represent the person who will use this, and you write down what "working" me
 
 `acceptance-criteria` carries the Gherkin conventions and the output contract. Follow it; nothing is restated here.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## What you decide
 
 - **What the user is actually trying to achieve**, as distinct from what the ticket asks for. Those differ often enough that naming the goal is most of your value.

package/plugins/src/base/agents/quality-specialist.md

@@ -11,6 +11,10 @@ You read the change the way the next person to touch it will, and you say plainl
 
 `quality-review` carries the checklist, the severity bands, and the finding format. Follow it; nothing is restated here.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## What you decide
 
 - **Severity, honestly.** Everything marked critical means nothing is. Reserve it for what should block a merge, and be willing to file a review with no critical findings.

package/plugins/src/base/agents/spec-conformance-specialist.md

@@ -10,6 +10,10 @@ skills:
 
 You are a spec conformance specialist. Your job is to prove that the shipped work matches its spec **exactly** — nothing more, nothing less.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## Scope
 
 You answer one question: **Does what shipped match what was asked?**

package/plugins/src/base/agents/test-specialist.md

@@ -11,6 +11,10 @@ You decide what has to be true for this change to be trusted, and design the tes
 
 `test-strategy` carries the matrix format, the coverage discipline, and the output contract. Follow it; nothing is restated here.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## What you decide
 
 - **What could break that nobody has asked about.** The acceptance criteria are the floor. Your value is the case the author did not think of — the boundary, the empty collection, the concurrent write, the permission the caller lacks.

package/plugins/src/base/agents/verification-specialist.md

@@ -14,6 +14,10 @@ You are a verification specialist. Your job is to **prove empirically** that wor
 
 Read `.claude/rules/verification.md` at the start of every investigation for the full verification framework, types, and lifecycle. Read `.claude/rules/falsifiable-checks.md` alongside it: every check YOU author — probe, script, codified spec, sweep — is subject to it, and a check that has not been shown capable of failing is reported as *unvalidated*, never as passing. Read `.claude/rules/claim-evidence-mapping.md` too: it binds every claim to the **boundary** it asserts and every boundary to the evidence **kinds** that reach it. The verdict you write is what `spec-conformance-specialist` cross-checks — record each claim's `boundary`, its `required_evidence_kinds`, its `evidence_refs`, and its `not_established` list so a boundary mismatch is catchable rather than invisible.
 
+## Work-item context
+
+When your task belongs to a tracked work item — it names `work_item_context` or a work-item ref — read the work-item context file in full before you plan, build, review, or verify anything. Use the absolute path your task gives as `work_item_context`; if it gives only the work-item ref, use `.lisa/work-item-context.md` at the root of the bound worktree. If the task concerns a tracker work item but names neither, check for `.lisa/work-item-context.md` at the bound worktree root, or for a bound work item via `node scripts/lisa-work-item.mjs current`; read the file if it is present. It is the verbatim tracker bundle for this work item — description, every comment, related items — saved by the input-resolver; a summary in your prompt indexes it but never stands in for it. Its trailing `## Comment inventory` section lists each comment with its flags. Treat each flagged comment as an obligation: a decision, constraint, credential or access note, or reproduction step that your work must honour and your report must account for. A secret quoted in a credential-flagged comment never leaves that file: cite it by what it is and which comment holds it, and keep the value or identifier out of code, commits, task notes, prompts, plan or roster files, tracker comments, and PR text. If a work item is named or bound and its context file is missing or unreadable, report that to the team lead and stop — never proceed from memory or a summary. Only a task whose source is a plan file, a PRD, a raw error, or a log, with no work item bound to the worktree, proceeds from the source the task supplies; no context file is expected there.
+
 ## Core Philosophy
 
 **"If you didn't run it, you didn't verify it."** Code review is not verification. Reading a test file is not verification. **Running tests, typecheck, and lint is not verification either — those are quality gates (prerequisites).** Only executing the actual system and observing output counts as proof. Verification means making HTTP requests, clicking through the UI, running CLI commands, querying the database, or otherwise interacting with the running software as an end user would.

package/plugins/src/base/hooks/enforcement-vintage-npm.mjs

@@ -0,0 +1,320 @@
+/**
+ * The two rows `enforcement-vintage` could not show before: the Lisa version the
+ * PROJECT installed, and the newest Lisa PUBLISHED (CodySwannGT/lisa#4325).
+ *
+ * Why these two. The session-copy rows answer "is this session running the
+ * newest Lisa on this disk?" — and a whole host can be current by that measure
+ * while sitting many releases behind npm, because nothing on the disk is newer
+ * than the version the project last installed. A host only moves when something
+ * opens an update PR for it. The agent standing in that host is the party most
+ * able to notice and least likely to be told, so the comparison goes where the
+ * agent reads: the injected context.
+ *
+ * NO NETWORK ON THE STARTUP PATH. A session start must never wait on npm. The
+ * row is read from the cache the `lisa` CLI's own update check already writes
+ * (`node_modules/.cache/@codyswann/lisa/update-check.json`, same shape, same
+ * 6-hour freshness), so the two surfaces cannot disagree about "latest". When
+ * that cache is missing or stale, a DETACHED child refreshes it for the next
+ * session and this session reports what it has — a stale reading named as
+ * stale, never a guess.
+ *
+ * FAIL SOFT, ALWAYS. Every function here returns a neutral value on any error.
+ * @module plugins/src/base/hooks/enforcement-vintage-npm
+ */
+import { spawn } from "child_process";
+import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+/** The package whose versions are compared. */
+export const LISA_PACKAGE = "@codyswann/lisa";
+
+/** Same freshness window as the CLI update check (`src/cli/update-check.ts`). */
+export const NPM_LATEST_TTL_MS = 6 * 60 * 60 * 1000;
+
+/** Budget for the detached refresh; it runs after the session has started. */
+const REFRESH_TIMEOUT_MS = 5000;
+
+/**
+ * Registry endpoint for the latest dist-tag.
+ *
+ * The cached mutable pointer lags a publish by minutes (CodySwannGT/lisa#3685).
+ * That is fine here for the same reason it is fine in the CLI nag: nothing
+ * downstream of this value chooses, publishes or gates — it is advice.
+ */
+const NPM_LATEST_URL = "https://registry.npmjs.org/@codyswann/lisa/latest";
+
+/** A plain `x.y.z` release, optionally with a prerelease or build suffix. */
+const VERSION_SHAPE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.+-]+)?$/u;
+
+/**
+ * Compare two prerelease identifier lists by semver precedence.
+ * @param {string[]} a Identifiers of the first prerelease.
+ * @param {string[]} b Identifiers of the second prerelease.
+ * @returns {number} Negative when `a` precedes `b`, positive when it follows.
+ */
+function comparePrerelease(a, b) {
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    if (a[index] === undefined) return -1;
+    if (b[index] === undefined) return 1;
+    if (a[index] === b[index]) continue;
+    const numeric = /^\d+$/u;
+    if (numeric.test(a[index]) && numeric.test(b[index])) {
+      return Number(a[index]) - Number(b[index]);
+    }
+    if (numeric.test(a[index])) return -1;
+    if (numeric.test(b[index])) return 1;
+    return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * Whether version `a` has lower semver precedence than `b`.
+ *
+ * Prerelease-aware on purpose: a project pinned to `4.66.5-rc.1` is BEHIND a
+ * published `4.66.5`, and comparing release fields alone would call it current.
+ * Build metadata is ignored, as semver requires.
+ * @param {string} a Candidate older version.
+ * @param {string} b Candidate newer version.
+ * @returns {boolean} True when `a` precedes `b`.
+ */
+export function precedes(a, b) {
+  const split = version => {
+    const [core, pre] = String(version).split("+")[0].split(/-(.*)/su);
+    const fields = core.split(".").map(field => Number(field) || 0);
+    return { fields, pre: pre ? pre.split(".") : [] };
+  };
+  const left = split(a);
+  const right = split(b);
+  for (let index = 0; index < 3; index += 1) {
+    const l = left.fields[index] ?? 0;
+    const r = right.fields[index] ?? 0;
+    if (l !== r) return l < r;
+  }
+  if (left.pre.length === 0) return false;
+  if (right.pre.length === 0) return true;
+  return comparePrerelease(left.pre, right.pre) < 0;
+}
+
+/**
+ * Parse a JSON file, or return null.
+ * @param {string} file Absolute path.
+ * @returns {any} Parsed JSON, or null when unreadable or malformed.
+ */
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The update-check cache path for a project — the CLI's own path.
+ * @param {string} projectDir Project root.
+ * @returns {string} Absolute cache path.
+ */
+export function npmLatestCachePath(projectDir) {
+  return path.join(
+    projectDir,
+    "node_modules",
+    ".cache",
+    "@codyswann",
+    "lisa",
+    "update-check.json"
+  );
+}
+
+/**
+ * The Lisa version this project installed, or null when it has none to show.
+ *
+ * Null inside the Lisa monorepo itself: there `node_modules/@codyswann/lisa` is
+ * a fixture pinned majors behind the repository, and reporting it as the
+ * project's pin would tell every Lisa session its project is stale.
+ * @param {string} projectDir Project root.
+ * @returns {{version: string, source: string} | null} The installed copy.
+ */
+export function projectPin(projectDir) {
+  const own = readJson(path.join(projectDir, "package.json"));
+  if (own?.name === LISA_PACKAGE) return null;
+  const source = path.join(
+    projectDir,
+    "node_modules",
+    "@codyswann",
+    "lisa",
+    "package.json"
+  );
+  const version = readJson(source)?.version;
+  return typeof version === "string" && VERSION_SHAPE.test(version)
+    ? { version, source }
+    : null;
+}
+
+/**
+ * Read the cached npm latest.
+ * @param {string} cachePath Absolute cache path.
+ * @param {number} nowMs Current time in ms.
+ * @param {number} [ttlMs] Freshness window.
+ * @returns {{version: string, fetchedAt: string, fresh: boolean} | null} Cached value.
+ */
+export function cachedNpmLatest(cachePath, nowMs, ttlMs = NPM_LATEST_TTL_MS) {
+  const cache = readJson(cachePath);
+  const version = cache?.latest;
+  const fetchedAt = cache?.fetchedAt;
+  if (typeof version !== "string" || !VERSION_SHAPE.test(version)) return null;
+  if (typeof fetchedAt !== "string") return null;
+  const fetchedMs = Date.parse(fetchedAt);
+  if (!Number.isFinite(fetchedMs)) return null;
+  return { version, fetchedAt, fresh: nowMs - fetchedMs <= ttlMs };
+}
+
+/**
+ * Whether a refresh should be started for this session.
+ * @param {{version: string, fresh: boolean} | null} cached Cached value.
+ * @param {NodeJS.ProcessEnv} env Environment.
+ * @returns {boolean} True when the cache is missing or stale and checks are on.
+ */
+export function needsRefresh(cached, env) {
+  if (env.LISA_SKIP_UPDATE_CHECK === "1") return false;
+  return cached === null || !cached.fresh;
+}
+
+/**
+ * Start a detached refresh of the cache and return immediately.
+ * @param {string} script Absolute path of this module.
+ * @param {string} cachePath Absolute cache path.
+ * @param {typeof spawn} [spawnImpl] Injected for tests.
+ * @returns {boolean} Whether a child was started.
+ */
+export function startDetachedRefresh(script, cachePath, spawnImpl = spawn) {
+  try {
+    const child = spawnImpl(
+      process.execPath,
+      [script, "--refresh-npm-latest", cachePath],
+      { detached: true, stdio: "ignore" }
+    );
+    child.on?.("error", () => {});
+    child.unref?.();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Fetch npm latest and write it to the cache in the CLI's shape.
+ *
+ * probe-direction: neutral — a failed fetch writes nothing, so the next
+ * session reports "npm latest: unknown" (or the older cached value, labelled
+ * stale); no gate reads this value, it only shapes advisory context.
+ * @param {string} cachePath Absolute cache path.
+ * @param {{fetchImpl?: typeof fetch, now?: () => Date}} [deps] Injected for tests.
+ * @returns {Promise<string | null>} The version written, or null.
+ */
+export async function refreshNpmLatest(cachePath, deps = {}) {
+  const fetchImpl = deps.fetchImpl ?? globalThis.fetch;
+  const now = deps.now ?? (() => new Date());
+  try {
+    const response = await fetchImpl(NPM_LATEST_URL, {
+      signal: AbortSignal.timeout(REFRESH_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    const body = await response.json();
+    const version = body?.version;
+    if (typeof version !== "string" || !VERSION_SHAPE.test(version)) {
+      return null;
+    }
+    mkdirSync(path.dirname(cachePath), { recursive: true });
+    writeFileSync(
+      cachePath,
+      `${JSON.stringify({ latest: version, fetchedAt: now().toISOString() }, null, 2)}\n`,
+      "utf8"
+    );
+    return version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render the project and npm rows, plus the guidance when the project is behind.
+ * @param {{pin: {version: string, source: string} | null, latest: {version: string, fetchedAt: string, fresh: boolean} | null, refreshing: boolean, projectBehind: boolean}} state Resolved rows.
+ * @returns {{rows: string[], guidance: string[]}} Lines to splice into the block.
+ */
+export function renderNpmRows(state) {
+  const rows = [];
+  if (state.pin) {
+    rows.push(`project pin: lisa ${state.pin.version} at ${state.pin.source}`);
+  }
+  if (state.latest) {
+    rows.push(
+      `npm latest: lisa ${state.latest.version} (checked ${state.latest.fetchedAt}${state.latest.fresh ? "" : "; stale"}${state.refreshing ? ", refreshing for the next session" : ""})`
+    );
+  } else if (state.pin) {
+    rows.push(
+      `npm latest: unknown${state.refreshing ? " (checking in the background for the next session)" : ""}`
+    );
+  }
+  const guidance = state.projectBehind
+    ? [
+        `PROJECT BEHIND — this project installs lisa ${state.pin?.version} while lisa ${state.latest?.version} is published.`,
+        "- Do NOT upgrade Lisa inside the current task: a version bump plus its template apply belongs in its own pull request, never mixed into feature work.",
+        "- Check for an open pull request on a `lisa/update-*` branch. If none is open, the project's Lisa Update workflow (`.github/workflows/lisa-update.yml`) opens one on its schedule; say so in your report, and if that workflow is missing, recommend running `lisa apply` once so the project receives it.",
+      ]
+    : [];
+  return { rows, guidance };
+}
+
+/**
+ * Resolve everything the npm rows need, starting a refresh when warranted.
+ * @param {{projectDir: string, script?: string, env: NodeJS.ProcessEnv, nowMs: number, spawnImpl?: typeof spawn}} input Inputs.
+ * @returns {{pin: {version: string, source: string} | null, latest: {version: string, fetchedAt: string, fresh: boolean} | null, refreshing: boolean, projectBehind: boolean}} Resolved rows.
+ */
+export function resolveNpmState(input) {
+  try {
+    const pin = projectPin(input.projectDir);
+    if (pin === null) {
+      return { pin, latest: null, refreshing: false, projectBehind: false };
+    }
+    const cachePath = npmLatestCachePath(input.projectDir);
+    const latest = cachedNpmLatest(cachePath, input.nowMs);
+    const refreshing =
+      needsRefresh(latest, input.env) &&
+      startDetachedRefresh(
+        input.script ?? fileURLToPath(import.meta.url),
+        cachePath,
+        input.spawnImpl
+      );
+    const projectBehind = Boolean(
+      latest && precedes(pin.version, latest.version)
+    );
+    return { pin, latest, refreshing, projectBehind };
+  } catch {
+    return { pin: null, latest: null, refreshing: false, projectBehind: false };
+  }
+}
+
+/**
+ * Whether this module is the process entry point (the detached refresh child).
+ * Realpaths both sides for the reason `enforcement-vintage.mjs` gives.
+ * @param {string} moduleUrl This module's `import.meta.url`.
+ * @param {string | undefined} [argv1] Entry path.
+ * @returns {boolean} True when run directly.
+ */
+function invokedDirectly(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (
+  invokedDirectly(import.meta.url) &&
+  process.argv[2] === "--refresh-npm-latest" &&
+  process.argv[3]
+) {
+  refreshNpmLatest(process.argv[3]).catch(() => {});
+}

package/plugins/src/base/hooks/enforcement-vintage.mjs

@@ -52,6 +52,7 @@ import { readFileSync, existsSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 import { realpathSync } from "fs";
+import { renderNpmRows, resolveNpmState } from "./enforcement-vintage-npm.mjs";
 
 /** Marker the block is wrapped in, so an agent can cite it by name. */
 const BLOCK_TAG = "lisa-enforcement-vintage";
@@ -336,6 +337,15 @@ export function renderBlock(state) {
       `newest on this disk: lisa ${state.newest.version} at ${state.newest.source}`
     );
   }
+  const npm = renderNpmRows(
+    state.npm ?? {
+      pin: null,
+      latest: null,
+      refreshing: false,
+      projectBehind: false,
+    }
+  );
+  npm.rows.forEach(row => lines.push(row));
   lines.push("");
   if (state.behind || !state.running.version || state.treeBehind) {
     lines.push(
@@ -363,6 +373,10 @@ export function renderBlock(state) {
         "when you report on guard or contract behaviour; it is only current until the next release."
     );
   }
+  if (npm.guidance.length > 0) {
+    lines.push("");
+    npm.guidance.forEach(line => lines.push(line));
+  }
   lines.push(`</${BLOCK_TAG}>`);
   return lines.join("\n");
 }
@@ -405,9 +419,14 @@ export function run(argv, stdin, env = process.env) {
   return JSON.stringify({
     hookSpecificOutput: {
       hookEventName: eventName(stdin),
-      additionalContext: renderBlock(
-        resolveState({ hooksDir, projectDir, configDir })
-      ),
+      additionalContext: renderBlock({
+        ...resolveState({ hooksDir, projectDir, configDir }),
+        npm: resolveNpmState({
+          projectDir,
+          env,
+          nowMs: Date.now(),
+        }),
+      }),
     },
   });
 }

package/plugins/src/base/skills/lisa-atlassian-access/SKILL.md

@@ -367,6 +367,7 @@ Substrate column meanings (ordering per `credential-substrate-precedence`):
 | `transition key:<K> to:<S>` | guarded fallback only: `acli jira workitem transition --key <K> --status "<S>" --yes` + post-read tenant assertion | `mcp__plugin_atlassian_atlassian__transitionJiraIssue` | resolve transition id then `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issue/<K>/transitions` |
 | `transitions key:<K>` — **false friend:** available transitions from current status, **NOT** past history; for history use `changelog` | (not exposed) | `mcp__plugin_atlassian_atlassian__getTransitionsForJiraIssue` | `GET https://<SITE>/rest/api/3/issue/<K>/transitions` |
 | `changelog key:<K>` (read; ordered past status transitions) | (not exposed) | (not exposed) | `GET https://<SITE>/rest/api/3/issue/<K>?expand=changelog` |
+| `comments key:<K>` (read; all comments, paginated) — **not** `comment`, which is the write | (not exposed) | `mcp__plugin_atlassian_atlassian__getJiraIssue` (comment field only; may be capped — page via curl when `total` exceeds what it returned) | `GET https://<SITE>/rest/api/3/issue/<K>/comment?startAt=<n>&maxResults=100&orderBy=created` |
 | `comment key:<K> body:<B>` | guarded fallback only: `acli jira workitem comment add --key <K> --body "<B>"` + post-read tenant assertion | `mcp__plugin_atlassian_atlassian__addCommentToJiraIssue` | `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issue/<K>/comment` |
 | `link from:<K> to:<K2> type:<T>` | guarded fallback only: `acli jira workitem link create --in <K> --out <K2> --type "<T>" --yes` + direction and tenant assertion (see direction note) | `mcp__plugin_atlassian_atlassian__createJiraIssueLink` | `POST https://api.atlassian.com/ex/jira/<CLOUDID>/rest/api/3/issueLink` |
 | `remote-links key:<K>` | (not exposed) | `mcp__plugin_atlassian_atlassian__getJiraIssueRemoteIssueLinks` | `GET https://<SITE>/rest/api/3/issue/<K>/remotelink` |
@@ -423,6 +424,17 @@ Operations not in this table are unsupported — add an adapter row before using
 - **Pagination / truncation.** The issue-resource changelog (`?expand=changelog`) truncates busy issues (`changelog.maxResults`/`total`/`startAt`). When `total` exceeds what the issue resource returned, page the dedicated endpoint `GET https://<SITE>/rest/api/3/issue/<K>/changelog?startAt=<n>` until `startAt + maxResults >= total`, preserving order across pages. A silently truncated history is a correctness bug for detection.
 - **Graceful degrade — never block the build.** A failed changelog fetch (network, auth, missing substrate) returns the substrate contract's `Error:` result. Callers MUST treat that as **unknown** history and proceed — a history read failure never blocks the build.
 
+### `comments` — every comment on one issue
+
+`comments key:<K>` returns every comment on a JIRA issue, oldest first. `read-ticket` embeds only the first page of comments in the issue resource (`fields.comment` carries its own `startAt`/`maxResults`/`total`), so a busy ticket's later comments — often the decisions and constraints — are missing from it.
+
+- **Substrate.** JIRA REST `GET https://<SITE>/rest/api/3/issue/<K>/comment?startAt=<n>&maxResults=100&orderBy=created` (a read, so the `<SITE>` gateway is allowed after the token account check). acli exposes no paginated comment list; the MCP `getJiraIssue` comment field is used only when no token is available and is subject to the same first-page cap.
+- **Shape.** For each entry in `comments[]` emit `{ id, author, created, body }` — `author.displayName`/`accountId`, `created` (ISO timestamp), and `body` converted from ADF to plain text with headings, lists, code, and links preserved.
+- **Pagination.** Start at `startAt=0` and request the next page until `startAt + maxResults >= total`, preserving order across pages. Never stop at the first page.
+- **Empty is valid.** An issue with no comments returns `total: 0`; that is a result, not an error.
+- **Completeness fields.** Every result carries `comments_complete`, `comments_fetched`, and `comments_total`; `comments_complete: true` only when `comments_fetched == comments_total`. When only the MCP substrate is available and it cannot page past its first batch, return what it gave with `comments_complete: false` and the fetched-versus-total counts — never present a capped set as the whole.
+- **Graceful degrade.** A failed page (network, auth, missing substrate) returns the substrate contract's `Error:` result for that page. Callers record the issue's comments as **incomplete** — naming how many of `total` were read — so a partial set is never silently truncated into looking complete.
+
 ### Step 4 — Return result
 
 Emit either:

package/plugins/src/base/skills/lisa-git-commit/SKILL.md

@@ -18,10 +18,10 @@ Create conventional commits for current changes. Optional hint: $ARGUMENTS
 ### Apply these requirements
 
 1. **Branch Check**: If on `dev`, `staging`, or `main`, create a feature branch named after the changes
-2. **Commit Strategy**: Group related changes into logical conventional commits (feat, fix, chore, docs, etc.)
-3. **Commit ALL Files**: Every file must be assigned to a commit group - no file gets left out or unstaged
+2. **Commit Strategy**: Group related changes into logical conventional commits (feat, fix, chore, docs, etc.). Every rule below that says "all" or "everything" excludes the local-only `.lisa/work-item-context.md` described in rule 3.
+3. **Commit ALL Files**: Every file must be assigned to a commit group - no file gets left out or unstaged. **Local-only exception:** never stage `.lisa/work-item-context.md`, or any other file the work-item context contract marks local-only, even when it is untracked and not ignored — it can quote credentials from tracker comments. Leave it untracked, and say in your report that it was left out and why.
 4. **Commit Creation**: Stage and commit each group with clear messages
-5. **Verification**: Run `git status` to confirm working directory is clean - must show "nothing to commit"
+5. **Verification**: Run `git status` to confirm working directory is clean - must show "nothing to commit" (apart from a local-only file left untracked under rule 3)
 
 ### Use conventional commit format
 
@@ -43,10 +43,10 @@ the original authored line may remain in the message.
 - use `--no-verify` flag
 - attempt to bypass tests or quality checks
 - skip tests or quality checks
-- stash changes - ALL changes must be committed
-- skip or exclude any files from the commit - even if they're unrelated
-- leave uncommitted changes in the working directory
-- ask the user which files to commit - commit everything
+- stash changes - ALL changes must be committed, except the local-only `.lisa/work-item-context.md`
+- skip or exclude any files from the commit - even if they're unrelated (the local-only `.lisa/work-item-context.md` is the one exclusion, and it is mandatory)
+- leave uncommitted changes in the working directory, other than the local-only `.lisa/work-item-context.md`
+- ask the user which files to commit - commit everything except the local-only `.lisa/work-item-context.md`
 
 ## Execute
 

package/plugins/src/base/skills/lisa-git-submit-pr/SKILL.md

@@ -27,7 +27,7 @@ Recognized optional hints:
 ### Apply these requirements
 
 1. **Branch Check**: Verify not on `dev`, `staging`, or `main` (cannot create PR from protected branches)
-2. **Commit Check**: Ensure all changes are committed before pushing
+2. **Commit Check**: Ensure all changes are committed before pushing — except the local-only `.lisa/work-item-context.md`, which is never staged even when untracked and not ignored; an untracked copy of it does not fail this check.
 2a. **Local review before push**: Unless `local_review=done` has current evidence, run `lisa-review-local` over the branch diff, address findings through `convergent-review`, and commit any fixes before step 3. This applies regardless of third-party reviewer availability. Reuse an applicable completed review instead of repeating it.
 
    Report the result as *self-reviewed*; it does not satisfy the ruleset-required third-party review check. If the runtime cannot delegate review, record **local review unavailable**, continue under the existing merge policy, and do not pass `local_review=done`. An unavailable review is not a passing review.

package/plugins/src/base/skills/lisa-github-build-intake/SKILL.md

@@ -517,7 +517,7 @@ After the claim succeeds, run the per-issue lifecycle defined by the `github-age
    - `lisa-github-verify` — pre-flight quality gate, including the draft-then-block procedure on FAIL
    - `lisa-ticket-triage` — analytical triage gate (a `BLOCKED` verdict stops the cycle with findings posted)
    - Intent determination from the `type:` label
-2. **Dispatch the flow in-session:** when the gates pass, invoke the lifecycle skill via the Skill tool — `lisa-implement <org>/<repo>#<number>` for Build / Fix / Improve / Investigate-Only (or `lisa-plan` for an Epic) — passing the full context bundle from the read step. **When 3b classified this item `rejection-reclaim`, the context bundle passed to `lisa-implement` MUST include the rejection evidence summary** (what was rejected, the defect the QA comment named, the approach named as wrong) — reuse the evidence already read in 3b, do not fetch it twice — so the plan can address it per `rejection-detection`; absence of evidence never blocks. `lisa-implement`'s own orchestration preamble then creates the per-item agent team (input-resolver, Roster Decision, specialist fanout) exactly as a direct invocation would.
+2. **Dispatch the flow in-session:** when the gates pass, invoke the lifecycle skill via the Skill tool — `lisa-implement <org>/<repo>#<number>` for Build / Fix / Improve / Investigate-Only (or `lisa-plan` for an Epic) — passing the full context bundle from the read step. Hand that bundle over by file, not by text: before invoking `lisa-implement`, run the ignore guard below, then write the bundle verbatim to persist it at the git-ignored `.lisa/work-item-context.md` of this worktree — always overwriting the file with this cycle's bundle, never reusing one an earlier item left behind — and pass only `caller_bundle_path=<absolute path>` in the invocation. `lisa-implement`'s input-resolver keeps that file as the base instead of re-summarizing it, so every comment reaches the agents doing the work. Bundle text, and any credential value in it, never appears in a spawn prompt, task description, or Skill argument — only its path. **Ignore guard before any write.** A host can receive these skills before its shipped `.gitignore` entry, so prove the path is ignored first, from the worktree root: `git check-ignore -q .lisa/work-item-context.md || printf '%s\n' '.lisa/work-item-context.md' >> "$(git rev-parse --git-common-dir)/info/exclude"`, then re-run `git check-ignore -q .lisa/work-item-context.md`. If it is still not ignored, stop and report — do not write the bundle. If an `.easignore` exists and `grep -qxF '.lisa/work-item-context.md' .easignore` fails, stop and report instead of writing: EAS uploads read `.easignore`, which is derived from `.gitignore`, not from `info/exclude`. **When 3b classified this item `rejection-reclaim`, the context bundle passed to `lisa-implement` MUST include the rejection evidence summary** (what was rejected, the defect the QA comment named, the approach named as wrong) — reuse the evidence already read in 3b, do not fetch it twice — so the plan can address it per `rejection-detection`; absence of evidence never blocks. `lisa-implement`'s own orchestration preamble then creates the per-item agent team (input-resolver, Roster Decision, specialist fanout) exactly as a direct invocation would.
 3. **Milestone sync and evidence** (`lisa-github-sync`, `lisa-github-evidence`) happen at the milestones the `github-agent` workflow defines, within the dispatched flow.
 
 If you are somehow running this skill as a spawned teammate inside an existing team (nested misrouting — Intake keeps this chain in the lead session), do NOT run the lifecycle inline and do NOT spawn named peers. Return this payload to the lead so the lead session can run this Phase 3c in-session: