@codyswann/lisa 2.106.2 → 2.106.4

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/scripts/plugin-sync-explain.mjs

@@ -7,7 +7,16 @@
  * diagnostic explains likely causes before an operator mutates the tree.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import process from "node:process";
 
@@ -29,6 +38,7 @@ const GIT_BIN = "/usr/bin/git";
  *   readonly classification: string
  *   readonly path: string
  *   readonly counterpart?: string
+ *   readonly likelyCause: string
  *   readonly nextAction: string
  * }} PluginSyncFinding
  *
@@ -50,8 +60,13 @@ export function explainPluginSync(root = process.cwd()) {
   const repoRoot = path.resolve(root);
   const statusBefore = gitStatus(repoRoot);
   const statusEntries = parseGitStatus(statusBefore);
+  const expectedGeneratedFiles = buildExpectedGeneratedFiles(repoRoot);
   const findings = [
-    ...classifySourceGeneratedDrift(statusEntries),
+    ...classifySourceGeneratedDrift(
+      repoRoot,
+      statusEntries,
+      expectedGeneratedFiles
+    ),
     ...classifyMarketplaceDrift(repoRoot),
   ];
   const statusAfter = gitStatus(repoRoot);
@@ -97,6 +112,7 @@ export function renderPluginSyncReport(report) {
     lines.push(
       `- ${finding.classification}: ${finding.path}`,
       `  Evidence: ${finding.counterpart ? `${finding.path} -> ${finding.counterpart}` : finding.path}`,
+      `  Likely cause: ${finding.likelyCause}`,
       `  Next action: ${finding.nextAction}`
     );
   }
@@ -128,9 +144,10 @@ function highestClassification(findings) {
 
 /**
  * @param {readonly { readonly code: string, readonly file: string }[]} entries
+ * @param {ReadonlyMap<string, Buffer> | undefined} expectedGeneratedFiles
  * @returns {PluginSyncFinding[]}
  */
-function classifySourceGeneratedDrift(entries) {
+function classifySourceGeneratedDrift(root, entries, expectedGeneratedFiles) {
   const changed = new Set(entries.map(entry => entry.file));
   const findings = [];
 
@@ -138,10 +155,24 @@ function classifySourceGeneratedDrift(entries) {
     const sourceCounterpart = sourceToBuilt(entry.file);
     if (sourceCounterpart) {
       const generatedChanged = changed.has(sourceCounterpart);
+      if (expectedGeneratedFiles) {
+        const expected = expectedGeneratedFiles.get(sourceCounterpart);
+        const active = readOptionalFile(root, sourceCounterpart);
+        const generatedMatchesSource =
+          expected !== undefined &&
+          active !== undefined &&
+          expected.equals(active);
+        if (generatedMatchesSource) {
+          continue;
+        }
+      }
       findings.push({
         classification: generatedChanged ? "OUT_OF_SYNC" : "SOURCE_NOT_BUILT",
         path: entry.file,
         counterpart: sourceCounterpart,
+        likelyCause: generatedChanged
+          ? "Both source and generated artifacts changed, but the generated artifact does not match a fresh plugin build."
+          : "A source plugin file changed, but its generated artifact was not rebuilt from plugins/src.",
         nextAction: generatedChanged
           ? "Review both source and generated changes, keep source authoritative, then run `bun run build:plugins && bun run check:plugins`."
           : "Run `bun run build:plugins`, then `bun run check:plugins`, and commit source plus regenerated artifacts.",
@@ -151,10 +182,23 @@ function classifySourceGeneratedDrift(entries) {
 
     const builtCounterpart = builtToSource(entry.file);
     if (builtCounterpart && !changed.has(builtCounterpart)) {
+      if (expectedGeneratedFiles) {
+        const expected = expectedGeneratedFiles.get(entry.file);
+        const active = readOptionalFile(root, entry.file);
+        if (
+          expected !== undefined &&
+          active !== undefined &&
+          expected.equals(active)
+        ) {
+          continue;
+        }
+      }
       findings.push({
         classification: "GENERATED_ONLY",
         path: entry.file,
         counterpart: builtCounterpart,
+        likelyCause:
+          "A generated plugin artifact changed without the matching plugins/src source change.",
         nextAction:
           "Move the edit to the matching plugins/src path, rebuild with `bun run build:plugins`, then run `bun run check:plugins`.",
       });
@@ -198,8 +242,9 @@ function classifyMarketplaceDrift(root) {
         classification: "MARKETPLACE_REGISTRATION_DRIFT",
         path: source.replace(/^\.\//, ""),
         counterpart: MARKETPLACE,
-        nextAction:
-          "Add the built plugin source to `.claude-plugin/marketplace.json`, then run `bun run check:plugins`.",
+        likelyCause:
+          "A built plugin directory exists but is not advertised by the marketplace manifest.",
+        nextAction: `Add marketplace source "${source}" to \`${MARKETPLACE}\`, then run \`bun run check:plugins\`.`,
       });
     }
   }
@@ -210,6 +255,8 @@ function classifyMarketplaceDrift(root) {
         classification: "MARKETPLACE_REGISTRATION_DRIFT",
         path: MARKETPLACE,
         counterpart: source.replace(/^\.\//, ""),
+        likelyCause:
+          "The marketplace manifest points at a built plugin directory that is missing.",
         nextAction:
           "Either restore the built plugin directory or remove the stale marketplace source, then run `bun run check:plugins`.",
       });
@@ -219,6 +266,113 @@ function classifyMarketplaceDrift(root) {
   return findings;
 }
 
+/**
+ * Build plugins in a disposable copy and return the generated bytes that source
+ * changes should produce. If a minimal fixture cannot run the build script,
+ * callers fall back to status-based classification without mutating the repo.
+ * @param {string} root
+ * @returns {ReadonlyMap<string, Buffer> | undefined}
+ */
+function buildExpectedGeneratedFiles(root) {
+  if (!existsSync(path.join(root, "scripts/build-plugins.sh"))) {
+    return undefined;
+  }
+
+  const tempRoot = mkdtempSync(path.join(tmpdir(), "lisa-plugin-sync-"));
+  const scratchRoot = path.join(tempRoot, "repo");
+  try {
+    cpSync(root, scratchRoot, {
+      recursive: true,
+      filter: src => shouldCopyToScratch(root, src),
+    });
+    execFileSync("bash", ["scripts/build-plugins.sh"], {
+      cwd: scratchRoot,
+      encoding: "utf8",
+      env: gitEnv(),
+      stdio: "ignore",
+    });
+    return collectGeneratedFiles(scratchRoot);
+  } catch {
+    return undefined;
+  } finally {
+    rmSync(tempRoot, { force: true, recursive: true });
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} src
+ * @returns {boolean}
+ */
+function shouldCopyToScratch(root, src) {
+  const rel = path.relative(root, src).split(path.sep).join("/");
+  if (rel === "") {
+    return true;
+  }
+  return !(
+    rel === ".git" ||
+    rel.startsWith(".git/") ||
+    rel === "node_modules" ||
+    rel.startsWith("node_modules/") ||
+    rel === "dist" ||
+    rel.startsWith("dist/") ||
+    rel === "coverage" ||
+    rel.startsWith("coverage/")
+  );
+}
+
+/**
+ * @param {string} root
+ * @returns {Map<string, Buffer>}
+ */
+function collectGeneratedFiles(root) {
+  const files = new Map();
+  const pluginsRoot = path.join(root, PLUGINS_DIR);
+  if (!existsSync(pluginsRoot)) {
+    return files;
+  }
+  for (const name of readdirSync(pluginsRoot)) {
+    if (name === "src" || !name.startsWith("lisa")) {
+      continue;
+    }
+    collectFiles(root, path.join(pluginsRoot, name), files);
+  }
+  return files;
+}
+
+/**
+ * @param {string} root
+ * @param {string} current
+ * @param {Map<string, Buffer>} files
+ */
+function collectFiles(root, current, files) {
+  const stats = statSync(current);
+  if (stats.isDirectory()) {
+    for (const child of readdirSync(current)) {
+      collectFiles(root, path.join(current, child), files);
+    }
+    return;
+  }
+  if (stats.isFile()) {
+    files.set(
+      path.relative(root, current).split(path.sep).join("/"),
+      readFileSync(current)
+    );
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} rel
+ * @returns {Buffer | undefined}
+ */
+function readOptionalFile(root, rel) {
+  const abs = path.join(root, rel);
+  return existsSync(abs) && statSync(abs).isFile()
+    ? readFileSync(abs)
+    : undefined;
+}
+
 /**
  * @param {string} root
  * @returns {string}
@@ -230,7 +384,7 @@ function gitStatus(root) {
     {
       cwd: root,
       encoding: "utf8",
-      env: gitEnv(),
+      env: gitEnv(root),
     }
   );
 }
@@ -309,15 +463,41 @@ function dedupeFindings(findings) {
 
 /**
  * Remove parent-hook Git environment so diagnostics inspect the requested repo.
+ * Bare common-dir worktrees in Codex need explicit GIT_DIR/GIT_WORK_TREE.
+ * @param {string} [root] Repository path the nested git command should inspect.
  * @returns {NodeJS.ProcessEnv} Process environment for nested git commands.
  */
-function gitEnv() {
+function gitEnv(root) {
   const env = { ...process.env };
   delete env.GIT_DIR;
   delete env.GIT_WORK_TREE;
+  if (root) {
+    const gitDir = linkedWorktreeGitDir(root);
+    if (gitDir) {
+      env.GIT_DIR = gitDir;
+      env.GIT_WORK_TREE = root;
+    }
+  }
   return env;
 }
 
+/**
+ * @param {string} root
+ * @returns {string | undefined}
+ */
+function linkedWorktreeGitDir(root) {
+  const dotGit = path.join(root, ".git");
+  if (!existsSync(dotGit) || statSync(dotGit).isDirectory()) {
+    return undefined;
+  }
+  const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"));
+  if (!match) {
+    return undefined;
+  }
+  const gitDir = match[1].trim();
+  return path.isAbsolute(gitDir) ? gitDir : path.resolve(root, gitDir);
+}
+
 if (import.meta.url === `file://${process.argv[1]}`) {
   try {
     const report = explainPluginSync(process.argv[2] ?? process.cwd());

package/plugins/lisa-cdk/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-expo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-nestjs/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.106.2",
+  "version": "2.106.4",
   "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/src/base/scripts/plugin-sync-explain.mjs

@@ -7,7 +7,16 @@
  * diagnostic explains likely causes before an operator mutates the tree.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import {
+  cpSync,
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
 import path from "node:path";
 import process from "node:process";
 
@@ -29,6 +38,7 @@ const GIT_BIN = "/usr/bin/git";
  *   readonly classification: string
  *   readonly path: string
  *   readonly counterpart?: string
+ *   readonly likelyCause: string
  *   readonly nextAction: string
  * }} PluginSyncFinding
  *
@@ -50,8 +60,13 @@ export function explainPluginSync(root = process.cwd()) {
   const repoRoot = path.resolve(root);
   const statusBefore = gitStatus(repoRoot);
   const statusEntries = parseGitStatus(statusBefore);
+  const expectedGeneratedFiles = buildExpectedGeneratedFiles(repoRoot);
   const findings = [
-    ...classifySourceGeneratedDrift(statusEntries),
+    ...classifySourceGeneratedDrift(
+      repoRoot,
+      statusEntries,
+      expectedGeneratedFiles
+    ),
     ...classifyMarketplaceDrift(repoRoot),
   ];
   const statusAfter = gitStatus(repoRoot);
@@ -97,6 +112,7 @@ export function renderPluginSyncReport(report) {
     lines.push(
       `- ${finding.classification}: ${finding.path}`,
       `  Evidence: ${finding.counterpart ? `${finding.path} -> ${finding.counterpart}` : finding.path}`,
+      `  Likely cause: ${finding.likelyCause}`,
       `  Next action: ${finding.nextAction}`
     );
   }
@@ -128,9 +144,10 @@ function highestClassification(findings) {
 
 /**
  * @param {readonly { readonly code: string, readonly file: string }[]} entries
+ * @param {ReadonlyMap<string, Buffer> | undefined} expectedGeneratedFiles
  * @returns {PluginSyncFinding[]}
  */
-function classifySourceGeneratedDrift(entries) {
+function classifySourceGeneratedDrift(root, entries, expectedGeneratedFiles) {
   const changed = new Set(entries.map(entry => entry.file));
   const findings = [];
 
@@ -138,10 +155,24 @@ function classifySourceGeneratedDrift(entries) {
     const sourceCounterpart = sourceToBuilt(entry.file);
     if (sourceCounterpart) {
       const generatedChanged = changed.has(sourceCounterpart);
+      if (expectedGeneratedFiles) {
+        const expected = expectedGeneratedFiles.get(sourceCounterpart);
+        const active = readOptionalFile(root, sourceCounterpart);
+        const generatedMatchesSource =
+          expected !== undefined &&
+          active !== undefined &&
+          expected.equals(active);
+        if (generatedMatchesSource) {
+          continue;
+        }
+      }
       findings.push({
         classification: generatedChanged ? "OUT_OF_SYNC" : "SOURCE_NOT_BUILT",
         path: entry.file,
         counterpart: sourceCounterpart,
+        likelyCause: generatedChanged
+          ? "Both source and generated artifacts changed, but the generated artifact does not match a fresh plugin build."
+          : "A source plugin file changed, but its generated artifact was not rebuilt from plugins/src.",
         nextAction: generatedChanged
           ? "Review both source and generated changes, keep source authoritative, then run `bun run build:plugins && bun run check:plugins`."
           : "Run `bun run build:plugins`, then `bun run check:plugins`, and commit source plus regenerated artifacts.",
@@ -151,10 +182,23 @@ function classifySourceGeneratedDrift(entries) {
 
     const builtCounterpart = builtToSource(entry.file);
     if (builtCounterpart && !changed.has(builtCounterpart)) {
+      if (expectedGeneratedFiles) {
+        const expected = expectedGeneratedFiles.get(entry.file);
+        const active = readOptionalFile(root, entry.file);
+        if (
+          expected !== undefined &&
+          active !== undefined &&
+          expected.equals(active)
+        ) {
+          continue;
+        }
+      }
       findings.push({
         classification: "GENERATED_ONLY",
         path: entry.file,
         counterpart: builtCounterpart,
+        likelyCause:
+          "A generated plugin artifact changed without the matching plugins/src source change.",
         nextAction:
           "Move the edit to the matching plugins/src path, rebuild with `bun run build:plugins`, then run `bun run check:plugins`.",
       });
@@ -198,8 +242,9 @@ function classifyMarketplaceDrift(root) {
         classification: "MARKETPLACE_REGISTRATION_DRIFT",
         path: source.replace(/^\.\//, ""),
         counterpart: MARKETPLACE,
-        nextAction:
-          "Add the built plugin source to `.claude-plugin/marketplace.json`, then run `bun run check:plugins`.",
+        likelyCause:
+          "A built plugin directory exists but is not advertised by the marketplace manifest.",
+        nextAction: `Add marketplace source "${source}" to \`${MARKETPLACE}\`, then run \`bun run check:plugins\`.`,
       });
     }
   }
@@ -210,6 +255,8 @@ function classifyMarketplaceDrift(root) {
         classification: "MARKETPLACE_REGISTRATION_DRIFT",
         path: MARKETPLACE,
         counterpart: source.replace(/^\.\//, ""),
+        likelyCause:
+          "The marketplace manifest points at a built plugin directory that is missing.",
         nextAction:
           "Either restore the built plugin directory or remove the stale marketplace source, then run `bun run check:plugins`.",
       });
@@ -219,6 +266,113 @@ function classifyMarketplaceDrift(root) {
   return findings;
 }
 
+/**
+ * Build plugins in a disposable copy and return the generated bytes that source
+ * changes should produce. If a minimal fixture cannot run the build script,
+ * callers fall back to status-based classification without mutating the repo.
+ * @param {string} root
+ * @returns {ReadonlyMap<string, Buffer> | undefined}
+ */
+function buildExpectedGeneratedFiles(root) {
+  if (!existsSync(path.join(root, "scripts/build-plugins.sh"))) {
+    return undefined;
+  }
+
+  const tempRoot = mkdtempSync(path.join(tmpdir(), "lisa-plugin-sync-"));
+  const scratchRoot = path.join(tempRoot, "repo");
+  try {
+    cpSync(root, scratchRoot, {
+      recursive: true,
+      filter: src => shouldCopyToScratch(root, src),
+    });
+    execFileSync("bash", ["scripts/build-plugins.sh"], {
+      cwd: scratchRoot,
+      encoding: "utf8",
+      env: gitEnv(),
+      stdio: "ignore",
+    });
+    return collectGeneratedFiles(scratchRoot);
+  } catch {
+    return undefined;
+  } finally {
+    rmSync(tempRoot, { force: true, recursive: true });
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} src
+ * @returns {boolean}
+ */
+function shouldCopyToScratch(root, src) {
+  const rel = path.relative(root, src).split(path.sep).join("/");
+  if (rel === "") {
+    return true;
+  }
+  return !(
+    rel === ".git" ||
+    rel.startsWith(".git/") ||
+    rel === "node_modules" ||
+    rel.startsWith("node_modules/") ||
+    rel === "dist" ||
+    rel.startsWith("dist/") ||
+    rel === "coverage" ||
+    rel.startsWith("coverage/")
+  );
+}
+
+/**
+ * @param {string} root
+ * @returns {Map<string, Buffer>}
+ */
+function collectGeneratedFiles(root) {
+  const files = new Map();
+  const pluginsRoot = path.join(root, PLUGINS_DIR);
+  if (!existsSync(pluginsRoot)) {
+    return files;
+  }
+  for (const name of readdirSync(pluginsRoot)) {
+    if (name === "src" || !name.startsWith("lisa")) {
+      continue;
+    }
+    collectFiles(root, path.join(pluginsRoot, name), files);
+  }
+  return files;
+}
+
+/**
+ * @param {string} root
+ * @param {string} current
+ * @param {Map<string, Buffer>} files
+ */
+function collectFiles(root, current, files) {
+  const stats = statSync(current);
+  if (stats.isDirectory()) {
+    for (const child of readdirSync(current)) {
+      collectFiles(root, path.join(current, child), files);
+    }
+    return;
+  }
+  if (stats.isFile()) {
+    files.set(
+      path.relative(root, current).split(path.sep).join("/"),
+      readFileSync(current)
+    );
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} rel
+ * @returns {Buffer | undefined}
+ */
+function readOptionalFile(root, rel) {
+  const abs = path.join(root, rel);
+  return existsSync(abs) && statSync(abs).isFile()
+    ? readFileSync(abs)
+    : undefined;
+}
+
 /**
  * @param {string} root
  * @returns {string}
@@ -230,7 +384,7 @@ function gitStatus(root) {
     {
       cwd: root,
       encoding: "utf8",
-      env: gitEnv(),
+      env: gitEnv(root),
     }
   );
 }
@@ -309,15 +463,41 @@ function dedupeFindings(findings) {
 
 /**
  * Remove parent-hook Git environment so diagnostics inspect the requested repo.
+ * Bare common-dir worktrees in Codex need explicit GIT_DIR/GIT_WORK_TREE.
+ * @param {string} [root] Repository path the nested git command should inspect.
  * @returns {NodeJS.ProcessEnv} Process environment for nested git commands.
  */
-function gitEnv() {
+function gitEnv(root) {
   const env = { ...process.env };
   delete env.GIT_DIR;
   delete env.GIT_WORK_TREE;
+  if (root) {
+    const gitDir = linkedWorktreeGitDir(root);
+    if (gitDir) {
+      env.GIT_DIR = gitDir;
+      env.GIT_WORK_TREE = root;
+    }
+  }
   return env;
 }
 
+/**
+ * @param {string} root
+ * @returns {string | undefined}
+ */
+function linkedWorktreeGitDir(root) {
+  const dotGit = path.join(root, ".git");
+  if (!existsSync(dotGit) || statSync(dotGit).isDirectory()) {
+    return undefined;
+  }
+  const match = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, "utf8"));
+  if (!match) {
+    return undefined;
+  }
+  const gitDir = match[1].trim();
+  return path.isAbsolute(gitDir) ? gitDir : path.resolve(root, gitDir);
+}
+
 if (import.meta.url === `file://${process.argv[1]}`) {
   try {
     const report = explainPluginSync(process.argv[2] ?? process.cwd());