@codyswann/lisa 2.106.1 → 2.106.2

package/package.json

@@ -82,7 +82,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.106.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/commands/plugin-sync-explain.md

@@ -0,0 +1,8 @@
+---
+description: "Explain plugin source/generated drift and marketplace registration gaps without modifying the working tree."
+argument-hint: "[path]"
+---
+
+Use the /lisa:plugin-sync-explain skill to inspect plugin source/generated synchronization for the current Lisa repo. $ARGUMENTS
+
+This command is read-only. It reports source-not-built edits, generated-only edits, marketplace registration drift, and the next source-first remediation step before an operator runs `bun run build:plugins` or `bun run check:plugins`.

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

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/**
+ * Read-only plugin sync drift classifier.
+ *
+ * This helper intentionally uses committed git status as evidence instead of
+ * rebuilding plugins. Rebuilding is the job of `bun run build:plugins`; this
+ * 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 path from "node:path";
+import process from "node:process";
+
+export const PLUGIN_SYNC_CLASSIFICATIONS = [
+  "SOURCE_NOT_BUILT",
+  "GENERATED_ONLY",
+  "MARKETPLACE_REGISTRATION_DRIFT",
+  "OUT_OF_SYNC",
+  "IN_SYNC",
+];
+
+const PLUGINS_DIR = "plugins";
+const SOURCE_ROOT = "plugins/src";
+const MARKETPLACE = ".claude-plugin/marketplace.json";
+const GIT_BIN = "/usr/bin/git";
+
+/**
+ * @typedef {{
+ *   readonly classification: string
+ *   readonly path: string
+ *   readonly counterpart?: string
+ *   readonly nextAction: string
+ * }} PluginSyncFinding
+ *
+ * @typedef {{
+ *   readonly root: string
+ *   readonly findings: readonly PluginSyncFinding[]
+ *   readonly statusBefore: string
+ *   readonly statusAfter: string
+ *   readonly readOnly: boolean
+ *   readonly text: string
+ * }} PluginSyncReport
+ */
+
+/**
+ * @param {string} root
+ * @returns {PluginSyncReport}
+ */
+export function explainPluginSync(root = process.cwd()) {
+  const repoRoot = path.resolve(root);
+  const statusBefore = gitStatus(repoRoot);
+  const statusEntries = parseGitStatus(statusBefore);
+  const findings = [
+    ...classifySourceGeneratedDrift(statusEntries),
+    ...classifyMarketplaceDrift(repoRoot),
+  ];
+  const statusAfter = gitStatus(repoRoot);
+  const readOnly = statusAfter === statusBefore;
+
+  return {
+    root: repoRoot,
+    findings,
+    statusBefore,
+    statusAfter,
+    readOnly,
+    text: renderPluginSyncReport({
+      root: repoRoot,
+      findings,
+      statusBefore,
+      statusAfter,
+      readOnly,
+    }),
+  };
+}
+
+/**
+ * @param {PluginSyncReport} report
+ * @returns {string}
+ */
+export function renderPluginSyncReport(report) {
+  const lines = [
+    "Plugin sync explain",
+    `Repo: ${report.root}`,
+    `Read-only: ${report.readOnly ? "yes" : "no"}`,
+  ];
+
+  if (report.findings.length === 0) {
+    lines.push(
+      "Verdict: IN_SYNC",
+      "No plugin source/generated or marketplace registration drift detected."
+    );
+    return `${lines.join("\n")}\n`;
+  }
+
+  lines.push(`Verdict: ${highestClassification(report.findings)}`, "Findings:");
+  for (const finding of report.findings) {
+    lines.push(
+      `- ${finding.classification}: ${finding.path}`,
+      `  Evidence: ${finding.counterpart ? `${finding.path} -> ${finding.counterpart}` : finding.path}`,
+      `  Next action: ${finding.nextAction}`
+    );
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {readonly PluginSyncFinding[]} findings
+ * @returns {string}
+ */
+function highestClassification(findings) {
+  if (findings.some(f => f.classification === "OUT_OF_SYNC")) {
+    return "OUT_OF_SYNC";
+  }
+  if (
+    findings.some(f => f.classification === "MARKETPLACE_REGISTRATION_DRIFT")
+  ) {
+    return "MARKETPLACE_REGISTRATION_DRIFT";
+  }
+  if (findings.some(f => f.classification === "GENERATED_ONLY")) {
+    return "GENERATED_ONLY";
+  }
+  if (findings.some(f => f.classification === "SOURCE_NOT_BUILT")) {
+    return "SOURCE_NOT_BUILT";
+  }
+  return "IN_SYNC";
+}
+
+/**
+ * @param {readonly { readonly code: string, readonly file: string }[]} entries
+ * @returns {PluginSyncFinding[]}
+ */
+function classifySourceGeneratedDrift(entries) {
+  const changed = new Set(entries.map(entry => entry.file));
+  const findings = [];
+
+  for (const entry of entries) {
+    const sourceCounterpart = sourceToBuilt(entry.file);
+    if (sourceCounterpart) {
+      const generatedChanged = changed.has(sourceCounterpart);
+      findings.push({
+        classification: generatedChanged ? "OUT_OF_SYNC" : "SOURCE_NOT_BUILT",
+        path: entry.file,
+        counterpart: sourceCounterpart,
+        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.",
+      });
+      continue;
+    }
+
+    const builtCounterpart = builtToSource(entry.file);
+    if (builtCounterpart && !changed.has(builtCounterpart)) {
+      findings.push({
+        classification: "GENERATED_ONLY",
+        path: entry.file,
+        counterpart: builtCounterpart,
+        nextAction:
+          "Move the edit to the matching plugins/src path, rebuild with `bun run build:plugins`, then run `bun run check:plugins`.",
+      });
+    }
+  }
+
+  return dedupeFindings(findings);
+}
+
+/**
+ * @param {string} root
+ * @returns {PluginSyncFinding[]}
+ */
+function classifyMarketplaceDrift(root) {
+  const marketplacePath = path.join(root, MARKETPLACE);
+  if (!existsSync(marketplacePath)) {
+    return [];
+  }
+
+  const marketplace = JSON.parse(readFileSync(marketplacePath, "utf8"));
+  const sources = new Set(
+    (marketplace.plugins ?? [])
+      .map(plugin => plugin.source)
+      .filter(source => typeof source === "string")
+  );
+  const pluginsRoot = path.join(root, PLUGINS_DIR);
+  if (!existsSync(pluginsRoot)) {
+    return [];
+  }
+
+  const builtSources = readdirSync(pluginsRoot)
+    .filter(name => name !== "src")
+    .map(name => path.join(pluginsRoot, name))
+    .filter(abs => statSync(abs).isDirectory())
+    .map(abs => `./${path.relative(root, abs).split(path.sep).join("/")}`);
+
+  const findings = [];
+  for (const source of builtSources) {
+    if (!sources.has(source)) {
+      findings.push({
+        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`.",
+      });
+    }
+  }
+
+  for (const source of sources) {
+    if (!existsSync(path.join(root, source))) {
+      findings.push({
+        classification: "MARKETPLACE_REGISTRATION_DRIFT",
+        path: MARKETPLACE,
+        counterpart: source.replace(/^\.\//, ""),
+        nextAction:
+          "Either restore the built plugin directory or remove the stale marketplace source, then run `bun run check:plugins`.",
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * @param {string} root
+ * @returns {string}
+ */
+function gitStatus(root) {
+  return execFileSync(
+    GIT_BIN,
+    ["status", "--porcelain", "--", PLUGINS_DIR, MARKETPLACE],
+    {
+      cwd: root,
+      encoding: "utf8",
+      env: gitEnv(),
+    }
+  );
+}
+
+/**
+ * @param {string} status
+ * @returns {{ readonly code: string, readonly file: string }[]}
+ */
+function parseGitStatus(status) {
+  return status
+    .split("\n")
+    .filter(Boolean)
+    .map(line => ({
+      code: line.slice(0, 2),
+      file: normalizeStatusPath(line.slice(3)),
+    }));
+}
+
+/**
+ * @param {string} file
+ * @returns {string}
+ */
+function normalizeStatusPath(file) {
+  const renamedPath = file.includes(" -> ") ? file.split(" -> ").at(-1) : file;
+  return renamedPath.replace(/^"|"$/g, "");
+}
+
+/**
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function sourceToBuilt(file) {
+  if (!file.startsWith(`${SOURCE_ROOT}/`)) {
+    return undefined;
+  }
+  const [, , sourceName, ...rest] = file.split("/");
+  if (!sourceName || rest.length === 0) {
+    return undefined;
+  }
+  const builtName = sourceName === "base" ? "lisa" : `lisa-${sourceName}`;
+  return [PLUGINS_DIR, builtName, ...rest].join("/");
+}
+
+/**
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function builtToSource(file) {
+  if (!file.startsWith(`${PLUGINS_DIR}/lisa`)) {
+    return undefined;
+  }
+  const [, builtName, ...rest] = file.split("/");
+  if (!builtName || rest.length === 0) {
+    return undefined;
+  }
+  const sourceName =
+    builtName === "lisa" ? "base" : builtName.replace(/^lisa-/, "");
+  return [SOURCE_ROOT, sourceName, ...rest].join("/");
+}
+
+/**
+ * @param {PluginSyncFinding[]} findings
+ * @returns {PluginSyncFinding[]}
+ */
+function dedupeFindings(findings) {
+  const seen = new Set();
+  return findings.filter(finding => {
+    const key = `${finding.classification}:${finding.path}:${finding.counterpart ?? ""}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Remove parent-hook Git environment so diagnostics inspect the requested repo.
+ * @returns {NodeJS.ProcessEnv} Process environment for nested git commands.
+ */
+function gitEnv() {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  return env;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const report = explainPluginSync(process.argv[2] ?? process.cwd());
+    process.stdout.write(report.text);
+    process.exitCode = report.findings.length === 0 ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(
+      `plugin-sync-explain failed: ${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = 2;
+  }
+}

package/plugins/lisa/skills/plugin-sync-explain/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: plugin-sync-explain
+description: "Read-only diagnostic for Lisa plugin source/generated drift. Compares plugins/src against generated plugins/lisa* status, reports source-not-built, generated-only, and marketplace registration drift, and preserves the working tree."
+allowed-tools: ["Bash", "Read"]
+---
+
+# Plugin Sync Explain: $ARGUMENTS
+
+`/lisa:plugin-sync-explain` explains why the plugin sync gate would need attention without mutating the working tree.
+
+## Scope
+
+Inspect the current Lisa repository, or an optional path passed as `$ARGUMENTS`, using `scripts/plugin-sync-explain.mjs`.
+
+The diagnostic is **read-only**:
+
+- Do not run `bun run build:plugins`.
+- Do not run `bun run check:plugins`.
+- Do not edit source files, generated plugin artifacts, or `.claude-plugin/marketplace.json`.
+- Do not stash, commit, reset, or clean local changes.
+
+## What to Report
+
+Report a concise terminal-first summary with stable classifications:
+
+- `SOURCE_NOT_BUILT`: files under `plugins/src/**` changed without their generated `plugins/lisa*` counterpart.
+- `GENERATED_ONLY`: files under `plugins/lisa*` changed without their `plugins/src/**` source counterpart.
+- `MARKETPLACE_REGISTRATION_DRIFT`: a built plugin directory is missing from `.claude-plugin/marketplace.json`, or a marketplace source points at a missing built directory.
+- `OUT_OF_SYNC`: source and generated counterparts both changed and need human review.
+- `IN_SYNC`: no plugin source/generated or marketplace registration drift was detected.
+
+For every finding, include the evidence path and the smallest source-first next action. Prefer `bun run build:plugins` only after source edits are in the right place, and preserve `bun run check:plugins` as the final reproducibility gate.
+
+## Process
+
+1. Resolve the repo path from `$ARGUMENTS` or the current directory.
+2. Capture `git status --porcelain` before the diagnostic.
+3. Run:
+   ```bash
+   node plugins/lisa/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+   If running from the source tree before generated artifacts are rebuilt, use:
+   ```bash
+   node plugins/src/base/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+4. Capture `git status --porcelain` after the diagnostic and confirm it is unchanged.
+5. Surface the script output plus the read-only confirmation.
+
+## Rules
+
+- Keep this surface aligned with `scripts/check-plugins-sync.sh`; it explains the gate but does not replace it.
+- Treat `plugins/src/**` as the source of truth and `plugins/lisa*` as generated artifacts.
+- If the diagnostic cannot inspect git status or marketplace JSON, report the error plainly and do not guess.

package/plugins/lisa/skills/plugin-sync-explain/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Plugin Sync Explain"
+short_description: "Read-only diagnostic for Lisa plugin source/generated drift"
+default_prompt:
+  - "Use $plugin-sync-explain: Read-only diagnostic for Lisa plugin source/generated drift."

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.106.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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.1",
+  "version": "2.106.2",
   "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/commands/plugin-sync-explain.md

@@ -0,0 +1,8 @@
+---
+description: "Explain plugin source/generated drift and marketplace registration gaps without modifying the working tree."
+argument-hint: "[path]"
+---
+
+Use the /lisa:plugin-sync-explain skill to inspect plugin source/generated synchronization for the current Lisa repo. $ARGUMENTS
+
+This command is read-only. It reports source-not-built edits, generated-only edits, marketplace registration drift, and the next source-first remediation step before an operator runs `bun run build:plugins` or `bun run check:plugins`.

package/plugins/src/base/scripts/plugin-sync-explain.mjs

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+/**
+ * Read-only plugin sync drift classifier.
+ *
+ * This helper intentionally uses committed git status as evidence instead of
+ * rebuilding plugins. Rebuilding is the job of `bun run build:plugins`; this
+ * 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 path from "node:path";
+import process from "node:process";
+
+export const PLUGIN_SYNC_CLASSIFICATIONS = [
+  "SOURCE_NOT_BUILT",
+  "GENERATED_ONLY",
+  "MARKETPLACE_REGISTRATION_DRIFT",
+  "OUT_OF_SYNC",
+  "IN_SYNC",
+];
+
+const PLUGINS_DIR = "plugins";
+const SOURCE_ROOT = "plugins/src";
+const MARKETPLACE = ".claude-plugin/marketplace.json";
+const GIT_BIN = "/usr/bin/git";
+
+/**
+ * @typedef {{
+ *   readonly classification: string
+ *   readonly path: string
+ *   readonly counterpart?: string
+ *   readonly nextAction: string
+ * }} PluginSyncFinding
+ *
+ * @typedef {{
+ *   readonly root: string
+ *   readonly findings: readonly PluginSyncFinding[]
+ *   readonly statusBefore: string
+ *   readonly statusAfter: string
+ *   readonly readOnly: boolean
+ *   readonly text: string
+ * }} PluginSyncReport
+ */
+
+/**
+ * @param {string} root
+ * @returns {PluginSyncReport}
+ */
+export function explainPluginSync(root = process.cwd()) {
+  const repoRoot = path.resolve(root);
+  const statusBefore = gitStatus(repoRoot);
+  const statusEntries = parseGitStatus(statusBefore);
+  const findings = [
+    ...classifySourceGeneratedDrift(statusEntries),
+    ...classifyMarketplaceDrift(repoRoot),
+  ];
+  const statusAfter = gitStatus(repoRoot);
+  const readOnly = statusAfter === statusBefore;
+
+  return {
+    root: repoRoot,
+    findings,
+    statusBefore,
+    statusAfter,
+    readOnly,
+    text: renderPluginSyncReport({
+      root: repoRoot,
+      findings,
+      statusBefore,
+      statusAfter,
+      readOnly,
+    }),
+  };
+}
+
+/**
+ * @param {PluginSyncReport} report
+ * @returns {string}
+ */
+export function renderPluginSyncReport(report) {
+  const lines = [
+    "Plugin sync explain",
+    `Repo: ${report.root}`,
+    `Read-only: ${report.readOnly ? "yes" : "no"}`,
+  ];
+
+  if (report.findings.length === 0) {
+    lines.push(
+      "Verdict: IN_SYNC",
+      "No plugin source/generated or marketplace registration drift detected."
+    );
+    return `${lines.join("\n")}\n`;
+  }
+
+  lines.push(`Verdict: ${highestClassification(report.findings)}`, "Findings:");
+  for (const finding of report.findings) {
+    lines.push(
+      `- ${finding.classification}: ${finding.path}`,
+      `  Evidence: ${finding.counterpart ? `${finding.path} -> ${finding.counterpart}` : finding.path}`,
+      `  Next action: ${finding.nextAction}`
+    );
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * @param {readonly PluginSyncFinding[]} findings
+ * @returns {string}
+ */
+function highestClassification(findings) {
+  if (findings.some(f => f.classification === "OUT_OF_SYNC")) {
+    return "OUT_OF_SYNC";
+  }
+  if (
+    findings.some(f => f.classification === "MARKETPLACE_REGISTRATION_DRIFT")
+  ) {
+    return "MARKETPLACE_REGISTRATION_DRIFT";
+  }
+  if (findings.some(f => f.classification === "GENERATED_ONLY")) {
+    return "GENERATED_ONLY";
+  }
+  if (findings.some(f => f.classification === "SOURCE_NOT_BUILT")) {
+    return "SOURCE_NOT_BUILT";
+  }
+  return "IN_SYNC";
+}
+
+/**
+ * @param {readonly { readonly code: string, readonly file: string }[]} entries
+ * @returns {PluginSyncFinding[]}
+ */
+function classifySourceGeneratedDrift(entries) {
+  const changed = new Set(entries.map(entry => entry.file));
+  const findings = [];
+
+  for (const entry of entries) {
+    const sourceCounterpart = sourceToBuilt(entry.file);
+    if (sourceCounterpart) {
+      const generatedChanged = changed.has(sourceCounterpart);
+      findings.push({
+        classification: generatedChanged ? "OUT_OF_SYNC" : "SOURCE_NOT_BUILT",
+        path: entry.file,
+        counterpart: sourceCounterpart,
+        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.",
+      });
+      continue;
+    }
+
+    const builtCounterpart = builtToSource(entry.file);
+    if (builtCounterpart && !changed.has(builtCounterpart)) {
+      findings.push({
+        classification: "GENERATED_ONLY",
+        path: entry.file,
+        counterpart: builtCounterpart,
+        nextAction:
+          "Move the edit to the matching plugins/src path, rebuild with `bun run build:plugins`, then run `bun run check:plugins`.",
+      });
+    }
+  }
+
+  return dedupeFindings(findings);
+}
+
+/**
+ * @param {string} root
+ * @returns {PluginSyncFinding[]}
+ */
+function classifyMarketplaceDrift(root) {
+  const marketplacePath = path.join(root, MARKETPLACE);
+  if (!existsSync(marketplacePath)) {
+    return [];
+  }
+
+  const marketplace = JSON.parse(readFileSync(marketplacePath, "utf8"));
+  const sources = new Set(
+    (marketplace.plugins ?? [])
+      .map(plugin => plugin.source)
+      .filter(source => typeof source === "string")
+  );
+  const pluginsRoot = path.join(root, PLUGINS_DIR);
+  if (!existsSync(pluginsRoot)) {
+    return [];
+  }
+
+  const builtSources = readdirSync(pluginsRoot)
+    .filter(name => name !== "src")
+    .map(name => path.join(pluginsRoot, name))
+    .filter(abs => statSync(abs).isDirectory())
+    .map(abs => `./${path.relative(root, abs).split(path.sep).join("/")}`);
+
+  const findings = [];
+  for (const source of builtSources) {
+    if (!sources.has(source)) {
+      findings.push({
+        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`.",
+      });
+    }
+  }
+
+  for (const source of sources) {
+    if (!existsSync(path.join(root, source))) {
+      findings.push({
+        classification: "MARKETPLACE_REGISTRATION_DRIFT",
+        path: MARKETPLACE,
+        counterpart: source.replace(/^\.\//, ""),
+        nextAction:
+          "Either restore the built plugin directory or remove the stale marketplace source, then run `bun run check:plugins`.",
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * @param {string} root
+ * @returns {string}
+ */
+function gitStatus(root) {
+  return execFileSync(
+    GIT_BIN,
+    ["status", "--porcelain", "--", PLUGINS_DIR, MARKETPLACE],
+    {
+      cwd: root,
+      encoding: "utf8",
+      env: gitEnv(),
+    }
+  );
+}
+
+/**
+ * @param {string} status
+ * @returns {{ readonly code: string, readonly file: string }[]}
+ */
+function parseGitStatus(status) {
+  return status
+    .split("\n")
+    .filter(Boolean)
+    .map(line => ({
+      code: line.slice(0, 2),
+      file: normalizeStatusPath(line.slice(3)),
+    }));
+}
+
+/**
+ * @param {string} file
+ * @returns {string}
+ */
+function normalizeStatusPath(file) {
+  const renamedPath = file.includes(" -> ") ? file.split(" -> ").at(-1) : file;
+  return renamedPath.replace(/^"|"$/g, "");
+}
+
+/**
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function sourceToBuilt(file) {
+  if (!file.startsWith(`${SOURCE_ROOT}/`)) {
+    return undefined;
+  }
+  const [, , sourceName, ...rest] = file.split("/");
+  if (!sourceName || rest.length === 0) {
+    return undefined;
+  }
+  const builtName = sourceName === "base" ? "lisa" : `lisa-${sourceName}`;
+  return [PLUGINS_DIR, builtName, ...rest].join("/");
+}
+
+/**
+ * @param {string} file
+ * @returns {string | undefined}
+ */
+function builtToSource(file) {
+  if (!file.startsWith(`${PLUGINS_DIR}/lisa`)) {
+    return undefined;
+  }
+  const [, builtName, ...rest] = file.split("/");
+  if (!builtName || rest.length === 0) {
+    return undefined;
+  }
+  const sourceName =
+    builtName === "lisa" ? "base" : builtName.replace(/^lisa-/, "");
+  return [SOURCE_ROOT, sourceName, ...rest].join("/");
+}
+
+/**
+ * @param {PluginSyncFinding[]} findings
+ * @returns {PluginSyncFinding[]}
+ */
+function dedupeFindings(findings) {
+  const seen = new Set();
+  return findings.filter(finding => {
+    const key = `${finding.classification}:${finding.path}:${finding.counterpart ?? ""}`;
+    if (seen.has(key)) {
+      return false;
+    }
+    seen.add(key);
+    return true;
+  });
+}
+
+/**
+ * Remove parent-hook Git environment so diagnostics inspect the requested repo.
+ * @returns {NodeJS.ProcessEnv} Process environment for nested git commands.
+ */
+function gitEnv() {
+  const env = { ...process.env };
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  return env;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  try {
+    const report = explainPluginSync(process.argv[2] ?? process.cwd());
+    process.stdout.write(report.text);
+    process.exitCode = report.findings.length === 0 ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(
+      `plugin-sync-explain failed: ${error instanceof Error ? error.message : String(error)}\n`
+    );
+    process.exitCode = 2;
+  }
+}

package/plugins/src/base/skills/plugin-sync-explain/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: plugin-sync-explain
+description: "Read-only diagnostic for Lisa plugin source/generated drift. Compares plugins/src against generated plugins/lisa* status, reports source-not-built, generated-only, and marketplace registration drift, and preserves the working tree."
+allowed-tools: ["Bash", "Read"]
+---
+
+# Plugin Sync Explain: $ARGUMENTS
+
+`/lisa:plugin-sync-explain` explains why the plugin sync gate would need attention without mutating the working tree.
+
+## Scope
+
+Inspect the current Lisa repository, or an optional path passed as `$ARGUMENTS`, using `scripts/plugin-sync-explain.mjs`.
+
+The diagnostic is **read-only**:
+
+- Do not run `bun run build:plugins`.
+- Do not run `bun run check:plugins`.
+- Do not edit source files, generated plugin artifacts, or `.claude-plugin/marketplace.json`.
+- Do not stash, commit, reset, or clean local changes.
+
+## What to Report
+
+Report a concise terminal-first summary with stable classifications:
+
+- `SOURCE_NOT_BUILT`: files under `plugins/src/**` changed without their generated `plugins/lisa*` counterpart.
+- `GENERATED_ONLY`: files under `plugins/lisa*` changed without their `plugins/src/**` source counterpart.
+- `MARKETPLACE_REGISTRATION_DRIFT`: a built plugin directory is missing from `.claude-plugin/marketplace.json`, or a marketplace source points at a missing built directory.
+- `OUT_OF_SYNC`: source and generated counterparts both changed and need human review.
+- `IN_SYNC`: no plugin source/generated or marketplace registration drift was detected.
+
+For every finding, include the evidence path and the smallest source-first next action. Prefer `bun run build:plugins` only after source edits are in the right place, and preserve `bun run check:plugins` as the final reproducibility gate.
+
+## Process
+
+1. Resolve the repo path from `$ARGUMENTS` or the current directory.
+2. Capture `git status --porcelain` before the diagnostic.
+3. Run:
+   ```bash
+   node plugins/lisa/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+   If running from the source tree before generated artifacts are rebuilt, use:
+   ```bash
+   node plugins/src/base/scripts/plugin-sync-explain.mjs "$REPO_PATH"
+   ```
+4. Capture `git status --porcelain` after the diagnostic and confirm it is unchanged.
+5. Surface the script output plus the read-only confirmation.
+
+## Rules
+
+- Keep this surface aligned with `scripts/check-plugins-sync.sh`; it explains the gate but does not replace it.
+- Treat `plugins/src/**` as the source of truth and `plugins/lisa*` as generated artifacts.
+- If the diagnostic cannot inspect git status or marketplace JSON, report the error plainly and do not guess.