@dadado/agent-kit-cli 4.8.0 → 4.8.2

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { defineCommand as defineCommand14, runMain } from "citty";
+import { defineCommand as defineCommand18, runMain } from "citty";
 
 // src/commands/add.ts
 import { defineCommand } from "citty";
@@ -1093,18 +1093,34 @@ var L0_ARTIFACTS = [
     source: ".cursor/hooks/pre-commit/check-secrets.sh",
     target: ".cursor/hooks/pre-commit/check-secrets.sh"
   },
-  // Native Cursor agent hooks (session context + handoff on compact)
+  // Native Cursor agent hooks (thin adapters -> agent-kit CLI)
   {
     source: ".cursor/hooks.json",
     target: ".cursor/hooks.json"
   },
   {
-    source: ".cursor/hooks/agent/session-plan-guard.py",
-    target: ".cursor/hooks/agent/session-plan-guard.py"
+    source: ".cursor/hooks/agent/resolve-agent-kit.sh",
+    target: ".cursor/hooks/agent/resolve-agent-kit.sh"
   },
   {
-    source: ".cursor/hooks/agent/precompact-handoff.py",
-    target: ".cursor/hooks/agent/precompact-handoff.py"
+    source: ".cursor/hooks/agent/session-start.sh",
+    target: ".cursor/hooks/agent/session-start.sh"
+  },
+  {
+    source: ".cursor/hooks/agent/pre-compact.sh",
+    target: ".cursor/hooks/agent/pre-compact.sh"
+  },
+  {
+    source: ".cursor/hooks/agent/guard-shell.sh",
+    target: ".cursor/hooks/agent/guard-shell.sh"
+  },
+  {
+    source: ".cursor/hooks/agent/after-edit-schema.sh",
+    target: ".cursor/hooks/agent/after-edit-schema.sh"
+  },
+  {
+    source: ".cursor/hooks/agent/secrets-prompt.sh",
+    target: ".cursor/hooks/agent/secrets-prompt.sh"
   },
   // Git spine docs at project root (not a nested agent-kit/ copy)
   {
@@ -1397,11 +1413,33 @@ import path10 from "path";
 import { defineCommand as defineCommand4 } from "citty";
 
 // src/commands/dashboard.ts
-import { spawn } from "child_process";
+import { execFileSync, spawn } from "child_process";
 import { access as access2 } from "fs/promises";
 import path9 from "path";
+import { fileURLToPath } from "url";
 import { defineCommand as defineCommand3 } from "citty";
-async function findDashboardStart(cwd) {
+function bundledDashboardCandidates(filename, moduleUrl = import.meta.url) {
+  const here = path9.dirname(fileURLToPath(moduleUrl));
+  return [
+    // Published / built: <pkg>/dist/index.js -> <pkg>/dashboard/
+    path9.join(here, "..", "dashboard", filename),
+    // Dev source: packages/cli/src/commands/*.ts -> packages/cli/dashboard/ (sync copy)
+    path9.join(here, "..", "..", "dashboard", filename),
+    // From src/commands: packages/dashboard/ (unused layout); from dist: two levels above package
+    path9.join(here, "..", "..", "..", "dashboard", filename)
+  ];
+}
+async function firstExisting(candidates) {
+  for (const candidate2 of candidates) {
+    try {
+      await access2(candidate2);
+      return path9.resolve(candidate2);
+    } catch {
+    }
+  }
+  return null;
+}
+async function findDashboardStart(cwd, env = process.env, options = {}) {
   let dir = path9.resolve(cwd);
   for (; ; ) {
     const candidate2 = path9.join(dir, "dashboard", "start.mjs");
@@ -1411,9 +1449,40 @@ async function findDashboardStart(cwd) {
     } catch {
     }
     const parent = path9.dirname(dir);
-    if (parent === dir) return null;
+    if (parent === dir) break;
     dir = parent;
   }
+  for (const key of ["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]) {
+    const base = env[key];
+    if (!base || typeof base !== "string" || !base.trim()) continue;
+    const candidate2 = path9.join(path9.resolve(base.trim()), "dashboard", "start.mjs");
+    try {
+      await access2(candidate2);
+      return candidate2;
+    } catch {
+    }
+  }
+  const sibling = path9.join(path9.resolve(cwd), "..", "agent-kit", "dashboard", "start.mjs");
+  try {
+    await access2(sibling);
+    return path9.resolve(sibling);
+  } catch {
+  }
+  return firstExisting(
+    bundledDashboardCandidates("start.mjs", options.moduleUrl ?? import.meta.url)
+  );
+}
+function resolveDashboardSnapshotRoot(cwd) {
+  const abs = path9.resolve(cwd);
+  try {
+    const top = execFileSync("git", ["-C", abs, "rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      timeout: 5e3
+    }).trim();
+    if (top) return path9.resolve(top);
+  } catch {
+  }
+  return abs;
 }
 function runStartScript(startPath, env) {
   return new Promise((resolve, reject) => {
@@ -1429,13 +1498,13 @@ function runStartScript(startPath, env) {
 var dashboardCommand = defineCommand3({
   meta: {
     name: "dashboard",
-    description: "Start Mission Control if needed and open http://localhost:3333 (terminal counterpart to /dashboard)."
+    description: "Start Mission Control for this workspace (stable per-root port) and open the panel URL."
   },
   args: {
     cwd: {
       type: "string",
       default: process.cwd(),
-      description: "Directory to search upward for dashboard/start.mjs"
+      description: "Workspace to snapshot (git root preferred); also searched upward for dashboard/start.mjs"
     },
     "no-open": {
       type: "boolean",
@@ -1444,15 +1513,17 @@ var dashboardCommand = defineCommand3({
     }
   },
   async run({ args }) {
+    const snapshotRoot = resolveDashboardSnapshotRoot(args.cwd);
     const startPath = await findDashboardStart(args.cwd);
     if (!startPath) {
       logger.error(
-        "No dashboard/start.mjs found. Mission Control ships with the agent-kit repo; run from that tree, or use npm run dashboard there."
+        "No dashboard/start.mjs found. After a CLI publish that ships dashboard/ (Path C), reinstall @dadado/agent-kit-cli. Or set MISSION_CONTROL_KIT_ROOT / AGENT_KIT_HOME to an agent-kit checkout, place a sibling ../agent-kit tree, or run from that kit tree."
       );
       process.exitCode = 1;
       return;
     }
     const env = { ...process.env };
+    env.MISSION_CONTROL_REPO_ROOT = snapshotRoot;
     if (args["no-open"]) env.MISSION_CONTROL_NO_OPEN = "1";
     const code = await runStartScript(startPath, env);
     if (code !== 0) process.exitCode = code;
@@ -1460,7 +1531,7 @@ var dashboardCommand = defineCommand3({
 });
 
 // src/commands/dashboard-broadcast.ts
-async function findDashboardBroadcastStart(cwd) {
+async function findDashboardBroadcastStart(cwd, env = process.env, options = {}) {
   let dir = path10.resolve(cwd);
   for (; ; ) {
     const candidate2 = path10.join(dir, "dashboard", "start-broadcast.mjs");
@@ -1470,9 +1541,42 @@ async function findDashboardBroadcastStart(cwd) {
     } catch {
     }
     const parent = path10.dirname(dir);
-    if (parent === dir) return null;
+    if (parent === dir) break;
     dir = parent;
   }
+  for (const key of ["MISSION_CONTROL_KIT_ROOT", "AGENT_KIT_HOME"]) {
+    const base = env[key];
+    if (!base || typeof base !== "string" || !base.trim()) continue;
+    const candidate2 = path10.join(path10.resolve(base.trim()), "dashboard", "start-broadcast.mjs");
+    try {
+      await access3(candidate2);
+      return candidate2;
+    } catch {
+    }
+  }
+  const sibling = path10.join(
+    path10.resolve(cwd),
+    "..",
+    "agent-kit",
+    "dashboard",
+    "start-broadcast.mjs"
+  );
+  try {
+    await access3(sibling);
+    return path10.resolve(sibling);
+  } catch {
+  }
+  for (const candidate2 of bundledDashboardCandidates(
+    "start-broadcast.mjs",
+    options.moduleUrl ?? import.meta.url
+  )) {
+    try {
+      await access3(candidate2);
+      return path10.resolve(candidate2);
+    } catch {
+    }
+  }
+  return null;
 }
 function runStartScript2(startPath, env) {
   return new Promise((resolve, reject) => {
@@ -1507,7 +1611,7 @@ var dashboardBroadcastCommand = defineCommand4({
     if (!startPath) {
       const loopback = await findDashboardStart(args.cwd);
       logger.error(
-        loopback ? "No dashboard/start-broadcast.mjs found beside dashboard/start.mjs. Update the agent-kit tree, then retry." : "No dashboard/start-broadcast.mjs found. Mission Control ships with the agent-kit repo; run from that tree."
+        loopback ? "No dashboard/start-broadcast.mjs found beside dashboard/start.mjs. Update the agent-kit tree or reinstall a CLI that ships dashboard/, then retry." : "No dashboard/start-broadcast.mjs found. After a CLI publish that ships dashboard/ (Path C), reinstall @dadado/agent-kit-cli. Or run from an agent-kit tree that includes dashboard/."
       );
       process.exitCode = 1;
       return;
@@ -1659,9 +1763,87 @@ var diffCommand = defineCommand5({
 });
 
 // src/commands/doctor.ts
-import path21 from "path";
+import path22 from "path";
 import { defineCommand as defineCommand6 } from "citty";
 
+// src/invariants/hooks-health.ts
+import { access as access4, readFile as readFile6 } from "fs/promises";
+import path12 from "path";
+var EXPECTED_EVENTS = [
+  "sessionStart",
+  "preCompact",
+  "beforeShellExecution",
+  "afterFileEdit",
+  "beforeSubmitPrompt"
+];
+async function exists(p) {
+  try {
+    await access4(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function assessHooksHealth(rootDir) {
+  const root = path12.resolve(rootDir);
+  const hooksJsonPath = ".cursor/hooks.json";
+  const hooksJsonAbs = path12.join(root, hooksJsonPath);
+  const reasons = [];
+  const wiredEvents = [];
+  if (!await exists(hooksJsonAbs)) {
+    return {
+      status: "missing",
+      reasons: ["`.cursor/hooks.json` not found"],
+      hooksJsonPath,
+      expectedEvents: [...EXPECTED_EVENTS],
+      wiredEvents
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile6(hooksJsonAbs, "utf8"));
+  } catch {
+    return {
+      status: "degraded",
+      reasons: ["`.cursor/hooks.json` is not valid JSON"],
+      hooksJsonPath,
+      expectedEvents: [...EXPECTED_EVENTS],
+      wiredEvents
+    };
+  }
+  const hooks = parsed.hooks ?? {};
+  for (const event of EXPECTED_EVENTS) {
+    const list = hooks[event];
+    if (Array.isArray(list) && list.length > 0) {
+      wiredEvents.push(event);
+      for (const entry of list) {
+        if (!entry || typeof entry !== "object") continue;
+        const command = String(entry.command ?? "");
+        if (command.endsWith(".py") || command.includes("python")) {
+          reasons.push(`${event} still points at a Python script (${command})`);
+        }
+      }
+    } else {
+      reasons.push(`missing hook event: ${event}`);
+    }
+  }
+  const resolveLib = path12.join(root, ".cursor", "hooks", "agent", "resolve-agent-kit.sh");
+  if (!await exists(resolveLib)) {
+    reasons.push("missing `.cursor/hooks/agent/resolve-agent-kit.sh` (thin adapter resolver)");
+  }
+  if (Array.isArray(hooks.stop) && hooks.stop.length > 0) {
+    reasons.push("`stop` hook is registered (forbidden; remove it)");
+  }
+  const status = reasons.length === 0 && wiredEvents.length === EXPECTED_EVENTS.length ? "active" : "degraded";
+  return {
+    status,
+    reasons,
+    hooksJsonPath,
+    expectedEvents: [...EXPECTED_EVENTS],
+    wiredEvents
+  };
+}
+
 // src/scanner/readiness.ts
 import { createHash as createHash2 } from "crypto";
 function action(id, status, recommendation, owner) {
@@ -1909,12 +2091,12 @@ function createReadinessReport(scan, options) {
 }
 
 // src/scanner/safe-fixes.ts
-import { readFile as readFile8, writeFile as writeFile3 } from "fs/promises";
-import path19 from "path";
+import { readFile as readFile9, writeFile as writeFile3 } from "fs/promises";
+import path20 from "path";
 
 // src/scanner/detect-repository.ts
-import { readFile as readFile6 } from "fs/promises";
-import path12 from "path";
+import { readFile as readFile7 } from "fs/promises";
+import path13 from "path";
 var CONTEXT_PATHS = [
   ["README.md", "README"],
   ["README", "README"],
@@ -1933,7 +2115,7 @@ var CONTEXT_PATHS = [
 async function existingEvidence(rootDir, candidates) {
   const evidence = await Promise.all(
     candidates.map(
-      async ([relativePath, label]) => await fileExists(path12.join(rootDir, relativePath)) ? { source: "file", value: `${relativePath}:${label}` } : void 0
+      async ([relativePath, label]) => await fileExists(path13.join(rootDir, relativePath)) ? { source: "file", value: `${relativePath}:${label}` } : void 0
     )
   );
   return evidence.flatMap((item) => item ? [item] : []);
@@ -1954,7 +2136,7 @@ async function detectContext(rootDir) {
 async function detectPurpose(rootDir, stack) {
   const entries = await listDirectory(rootDir);
   const lowerEntries = entries.map((entry) => entry.toLowerCase());
-  const packageJson = await readJson(path12.join(rootDir, "package.json"));
+  const packageJson = await readJson(path13.join(rootDir, "package.json"));
   const categories = [];
   const evidence = [];
   const add = (category, value2) => {
@@ -1994,16 +2176,16 @@ async function detectPurpose(rootDir, stack) {
 }
 async function detectAgentKit(rootDir) {
   const manifestRelativePath = ".cursor/agent-kit.json";
-  const manifestPath = path12.join(rootDir, manifestRelativePath);
+  const manifestPath = path13.join(rootDir, manifestRelativePath);
   const installed = await fileExists(manifestPath);
   const manifest = installed ? await readJson(manifestPath) : null;
   return {
     installed,
     manifestPath: installed ? manifestRelativePath : void 0,
     version: manifest?.version,
-    hasPlans: await fileExists(path12.join(rootDir, ".cursor/plans")),
-    hasHandoff: await fileExists(path12.join(rootDir, ".cursor/HANDOFF.md")),
-    hasMemory: await fileExists(path12.join(rootDir, ".cursor/memory"))
+    hasPlans: await fileExists(path13.join(rootDir, ".cursor/plans")),
+    hasHandoff: await fileExists(path13.join(rootDir, ".cursor/HANDOFF.md")),
+    hasMemory: await fileExists(path13.join(rootDir, ".cursor/memory"))
   };
 }
 var REQUIRED_SECRET_PATTERNS = [
@@ -2017,9 +2199,9 @@ var REQUIRED_SECRET_PATTERNS = [
   "*service-account*.json"
 ];
 async function detectSafety(rootDir, trackedFiles) {
-  const gitignorePath = path12.join(rootDir, ".gitignore");
+  const gitignorePath = path13.join(rootDir, ".gitignore");
   const hasGitignore = await fileExists(gitignorePath);
-  const gitignore = hasGitignore ? await readFile6(gitignorePath, "utf8") : "";
+  const gitignore = hasGitignore ? await readFile7(gitignorePath, "utf8") : "";
   const lines = gitignore.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith("#"));
   const ignoredSecretPatterns = REQUIRED_SECRET_PATTERNS.filter(
     (pattern) => lines.includes(pattern)
@@ -2028,7 +2210,7 @@ async function detectSafety(rootDir, trackedFiles) {
     (file) => /(^|\/)(\.env(\..+)?|.*\.(key|pem|p12|pfx)|.*credentials.*\.json)$/i.test(file)
   );
   const hookPaths = [".husky", ".git/hooks/pre-commit", "git-hooks/pre-commit"];
-  const hasHooks = (await Promise.all(hookPaths.map((item) => fileExists(path12.join(rootDir, item))))).some(Boolean);
+  const hasHooks = (await Promise.all(hookPaths.map((item) => fileExists(path13.join(rootDir, item))))).some(Boolean);
   const guardCandidates = [
     ".husky/pre-commit",
     ".husky/pre-push",
@@ -2037,7 +2219,7 @@ async function detectSafety(rootDir, trackedFiles) {
   ];
   const guardContents = await Promise.all(
     guardCandidates.map(
-      async (item) => await fileExists(path12.join(rootDir, item)) ? readFile6(path12.join(rootDir, item), "utf8") : ""
+      async (item) => await fileExists(path13.join(rootDir, item)) ? readFile7(path13.join(rootDir, item), "utf8") : ""
     )
   );
   return {
@@ -2055,11 +2237,11 @@ async function detectSafety(rootDir, trackedFiles) {
 }
 
 // src/scanner/scan.ts
-import path18 from "path";
+import path19 from "path";
 
 // src/scanner/detect-git.ts
 import { execFile as execFile2 } from "child_process";
-import path13 from "path";
+import path14 from "path";
 import { promisify as promisify2 } from "util";
 var exec = promisify2(execFile2);
 function remoteHostname(remoteUrl) {
@@ -2083,7 +2265,7 @@ function sanitizeRemoteUrl(remoteUrl) {
 }
 async function detectProvider(rootDir, remoteUrl) {
   const configuration = await readJson(
-    path13.join(rootDir, ".cursor", "agent-kit.config.json")
+    path14.join(rootDir, ".cursor", "agent-kit.config.json")
   );
   const configuredProvider = configuration?.git?.provider;
   if (configuredProvider) {
@@ -2140,7 +2322,7 @@ async function detectProvider(rootDir, remoteUrl) {
       evidence: remoteEvidence
     };
   }
-  if (await fileExists(path13.join(rootDir, ".gitlab-ci.yml"))) {
+  if (await fileExists(path14.join(rootDir, ".gitlab-ci.yml"))) {
     return {
       provider: "gitlab",
       providerKind: "gitlab-self-hosted",
@@ -2229,11 +2411,11 @@ async function detectGit(rootDir) {
 }
 
 // src/scanner/detect-ide.ts
-import path14 from "path";
+import path15 from "path";
 async function detectIde(rootDir) {
-  const hasCursor = await fileExists(path14.join(rootDir, ".cursor"));
-  const hasVSCode = await fileExists(path14.join(rootDir, ".vscode"));
-  const hasWindsurf = await fileExists(path14.join(rootDir, ".windsurfrules"));
+  const hasCursor = await fileExists(path15.join(rootDir, ".cursor"));
+  const hasVSCode = await fileExists(path15.join(rootDir, ".vscode"));
+  const hasWindsurf = await fileExists(path15.join(rootDir, ".windsurfrules"));
   if (hasCursor) return { ide: "cursor", plan: "cursor-pro" };
   if (hasVSCode) return { ide: "vscode", plan: "vscode-pro" };
   if (hasWindsurf) return { ide: "windsurf", plan: "windsurf" };
@@ -2241,7 +2423,7 @@ async function detectIde(rootDir) {
 }
 
 // src/scanner/detect-infra.ts
-import path15 from "path";
+import path16 from "path";
 
 // src/types.ts
 var CI_PLATFORM_FILES = {
@@ -2270,12 +2452,12 @@ var PM_TOOL_LABELS = {
 
 // src/scanner/detect-infra.ts
 async function detectInfra(rootDir) {
-  const docker = await fileExists(path15.join(rootDir, "Dockerfile")) || await fileExists(path15.join(rootDir, "docker-compose.yml")) || await fileExists(path15.join(rootDir, "docker-compose.yaml"));
-  const kubernetes = await fileExists(path15.join(rootDir, "k8s")) || await fileExists(path15.join(rootDir, "kubernetes"));
+  const docker = await fileExists(path16.join(rootDir, "Dockerfile")) || await fileExists(path16.join(rootDir, "docker-compose.yml")) || await fileExists(path16.join(rootDir, "docker-compose.yaml"));
+  const kubernetes = await fileExists(path16.join(rootDir, "k8s")) || await fileExists(path16.join(rootDir, "kubernetes"));
   let ci = "none";
   const ciFiles = [];
   for (const [platform, filePath] of Object.entries(CI_PLATFORM_FILES)) {
-    if (await fileExists(path15.join(rootDir, filePath))) {
+    if (await fileExists(path16.join(rootDir, filePath))) {
       if (ci === "none") ci = platform;
       ciFiles.push(filePath);
     }
@@ -2300,30 +2482,30 @@ async function detectInfra(rootDir) {
   ];
   const infrastructureFiles = (await Promise.all(
     infrastructureCandidates.map(
-      async (file) => await fileExists(path15.join(rootDir, file)) ? file : void 0
+      async (file) => await fileExists(path16.join(rootDir, file)) ? file : void 0
     )
   )).filter((file) => file !== void 0);
   const deploymentFiles = (await Promise.all(
     deploymentCandidates.map(
-      async (file) => await fileExists(path15.join(rootDir, file)) ? file : void 0
+      async (file) => await fileExists(path16.join(rootDir, file)) ? file : void 0
     )
   )).filter((file) => file !== void 0);
   return { docker, kubernetes, ci, ciFiles, infrastructureFiles, deploymentFiles };
 }
 
 // src/scanner/detect-services.ts
-import { readFile as readFile7 } from "fs/promises";
-import path16 from "path";
+import { readFile as readFile8 } from "fs/promises";
+import path17 from "path";
 async function detectProjectManagement(rootDir) {
   const tools = [];
   const mcpConfigPaths = [
-    path16.join(rootDir, ".cursor", "mcp.json"),
-    path16.join(rootDir, "mcp.json")
+    path17.join(rootDir, ".cursor", "mcp.json"),
+    path17.join(rootDir, "mcp.json")
   ];
   for (const configPath of mcpConfigPaths) {
     if (!await fileExists(configPath)) continue;
     try {
-      const raw = await readFile7(configPath, "utf8");
+      const raw = await readFile8(configPath, "utf8");
       const lower = raw.toLowerCase();
       if (lower.includes("clickup")) tools.push("clickup");
       if (lower.includes("jira") || lower.includes("atlassian")) tools.push("jira");
@@ -2334,20 +2516,20 @@ async function detectProjectManagement(rootDir) {
     } catch {
     }
   }
-  if (await fileExists(path16.join(rootDir, ".github", "ISSUE_TEMPLATE"))) {
+  if (await fileExists(path17.join(rootDir, ".github", "ISSUE_TEMPLATE"))) {
     tools.push("github-issues");
   }
-  if (await fileExists(path16.join(rootDir, ".github", "projects"))) {
+  if (await fileExists(path17.join(rootDir, ".github", "projects"))) {
     tools.push("github-projects");
   }
   return [...new Set(tools)];
 }
 async function detectServices(rootDir) {
-  const hasPrisma = await fileExists(path16.join(rootDir, "prisma/schema.prisma"));
-  const hasSequelize = await fileExists(path16.join(rootDir, "sequelize"));
-  const hasDrizzle = await fileExists(path16.join(rootDir, "drizzle.config.ts"));
-  const hasKnex = await fileExists(path16.join(rootDir, "knexfile.ts"));
-  const hasTypeorm = await fileExists(path16.join(rootDir, "ormconfig.json"));
+  const hasPrisma = await fileExists(path17.join(rootDir, "prisma/schema.prisma"));
+  const hasSequelize = await fileExists(path17.join(rootDir, "sequelize"));
+  const hasDrizzle = await fileExists(path17.join(rootDir, "drizzle.config.ts"));
+  const hasKnex = await fileExists(path17.join(rootDir, "knexfile.ts"));
+  const hasTypeorm = await fileExists(path17.join(rootDir, "ormconfig.json"));
   const database = hasPrisma || hasSequelize || hasDrizzle || hasKnex || hasTypeorm ? "postgresql" : void 0;
   const orm = hasPrisma ? "prisma" : hasDrizzle ? "drizzle" : hasSequelize ? "sequelize" : hasKnex ? "knex" : hasTypeorm ? "typeorm" : void 0;
   const projectManagement = await detectProjectManagement(rootDir);
@@ -2359,7 +2541,7 @@ async function detectServices(rootDir) {
 }
 
 // src/scanner/detect-stack.ts
-import path17 from "path";
+import path18 from "path";
 var PROJECT_MARKERS = [
   "package.json",
   "requirements.txt",
@@ -2388,7 +2570,7 @@ async function detectPackageManager(rootDir, packageJson) {
     };
   }
   for (const [lockfile, packageManager] of LOCKFILES) {
-    if (await fileExists(path17.join(rootDir, lockfile))) {
+    if (await fileExists(path18.join(rootDir, lockfile))) {
       return {
         packageManager,
         evidence: [{ source: "file", value: lockfile }]
@@ -2405,27 +2587,27 @@ function commandsForScripts(scripts, packageManager) {
   return { testCommands, validationCommands };
 }
 async function detectStack(rootDir) {
-  const hasAnyProjectMarker = (await Promise.all(PROJECT_MARKERS.map((item) => fileExists(path17.join(rootDir, item))))).some(Boolean);
-  const hasPackageJson = await fileExists(path17.join(rootDir, "package.json"));
+  const hasAnyProjectMarker = (await Promise.all(PROJECT_MARKERS.map((item) => fileExists(path18.join(rootDir, item))))).some(Boolean);
+  const hasPackageJson = await fileExists(path18.join(rootDir, "package.json"));
   if (hasPackageJson) {
-    const packageJson = await readJson(path17.join(rootDir, "package.json")) ?? {};
+    const packageJson = await readJson(path18.join(rootDir, "package.json")) ?? {};
     const scripts = packageJson.scripts ?? {};
     const packageManager = await detectPackageManager(rootDir, packageJson);
     const commands = commandsForScripts(scripts, packageManager.packageManager);
-    const hasNextConfig = await fileExists(path17.join(rootDir, "next.config.js")) || await fileExists(path17.join(rootDir, "next.config.mjs")) || await fileExists(path17.join(rootDir, "next.config.ts"));
-    const hasNestConfig = await fileExists(path17.join(rootDir, "nest-cli.json"));
+    const hasNextConfig = await fileExists(path18.join(rootDir, "next.config.js")) || await fileExists(path18.join(rootDir, "next.config.mjs")) || await fileExists(path18.join(rootDir, "next.config.ts"));
+    const hasNestConfig = await fileExists(path18.join(rootDir, "nest-cli.json"));
     return {
       language: "node",
       framework: hasNextConfig ? "nextjs" : hasNestConfig ? "nestjs" : "node",
       packageManager: packageManager.packageManager,
       packageManagerEvidence: packageManager.evidence,
       scripts,
-      workspaces: packageJson.workspaces !== void 0 || await fileExists(path17.join(rootDir, "pnpm-workspace.yaml")),
+      workspaces: packageJson.workspaces !== void 0 || await fileExists(path18.join(rootDir, "pnpm-workspace.yaml")),
       ...commands,
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path17.join(rootDir, "pyproject.toml"))) {
+  if (await fileExists(path18.join(rootDir, "pyproject.toml"))) {
     return {
       language: "python",
       framework: "python",
@@ -2435,7 +2617,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path17.join(rootDir, "go.mod"))) {
+  if (await fileExists(path18.join(rootDir, "go.mod"))) {
     return {
       language: "go",
       framework: "go",
@@ -2445,7 +2627,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path17.join(rootDir, "Cargo.toml"))) {
+  if (await fileExists(path18.join(rootDir, "Cargo.toml"))) {
     return {
       language: "rust",
       framework: "rust",
@@ -2455,7 +2637,7 @@ async function detectStack(rootDir) {
       hasProjectFiles: hasAnyProjectMarker
     };
   }
-  if (await fileExists(path17.join(rootDir, "composer.json"))) {
+  if (await fileExists(path18.join(rootDir, "composer.json"))) {
     return {
       language: "php",
       framework: "php",
@@ -2488,7 +2670,7 @@ function isGreenfieldByEntries(entries) {
   return meaningful.length === 0;
 }
 async function runScanner(rootDir) {
-  const normalizedRoot = path18.resolve(rootDir);
+  const normalizedRoot = path19.resolve(rootDir);
   const entries = await listDirectory(normalizedRoot);
   const stack = await detectStack(normalizedRoot);
   const purpose = await detectPurpose(normalizedRoot, stack);
@@ -2692,21 +2874,21 @@ async function executeSafeReadinessFixes(rootDir, options) {
   });
   const changes = [];
   for (const relativePath of ESSENTIAL_DIRECTORIES) {
-    const absolutePath = path19.join(beforeScan.rootDir, relativePath);
-    const exists = await fileExists(absolutePath);
-    if (!exists && !dryRun) await ensureDir(absolutePath);
+    const absolutePath = path20.join(beforeScan.rootDir, relativePath);
+    const exists2 = await fileExists(absolutePath);
+    if (!exists2 && !dryRun) await ensureDir(absolutePath);
     recordChange(
       changes,
       "ensure-agent-kit-directory",
       relativePath,
-      !exists,
+      !exists2,
       dryRun,
-      relativeEvidence(relativePath, exists ? "already exists" : "missing directory")
+      relativeEvidence(relativePath, exists2 ? "already exists" : "missing directory")
     );
   }
   const gitignoreRelativePath = ".gitignore";
-  const gitignorePath = path19.join(beforeScan.rootDir, gitignoreRelativePath);
-  const existingGitignore = await fileExists(gitignorePath) ? await readFile8(gitignorePath, "utf8") : "";
+  const gitignorePath = path20.join(beforeScan.rootDir, gitignoreRelativePath);
+  const existingGitignore = await fileExists(gitignorePath) ? await readFile9(gitignorePath, "utf8") : "";
   const mergedGitignore = mergeSecretIgnores(existingGitignore);
   const gitignoreChanged = mergedGitignore !== existingGitignore;
   if (gitignoreChanged && !dryRun) await writeFile3(gitignorePath, mergedGitignore, "utf8");
@@ -2721,7 +2903,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
       gitignoreChanged ? "required secret patterns are missing" : "required patterns are present"
     )
   );
-  const profilePath = path19.join(beforeScan.rootDir, PROFILE_RELATIVE_PATH);
+  const profilePath = path20.join(beforeScan.rootDir, PROFILE_RELATIVE_PATH);
   const existingProfile = await readJson(profilePath) ?? {};
   const desiredProfile = createProfile(beforeScan, before, generatedAt);
   const mergedProfile = mergeMissing(existingProfile, desiredProfile);
@@ -2743,7 +2925,7 @@ async function executeSafeReadinessFixes(rootDir, options) {
     generatorVersion: options.generatorVersion,
     generatedAt
   });
-  const contextConfigPath = path19.join(beforeScan.rootDir, CONTEXT_CONFIG_RELATIVE_PATH);
+  const contextConfigPath = path20.join(beforeScan.rootDir, CONTEXT_CONFIG_RELATIVE_PATH);
   const existingContextConfig = await readJson(contextConfigPath) ?? {};
   const onboarding = reconcileOnboardingState(evidenceReport, existingContextConfig, generatedAt);
   const defaults = preferenceDefaults(onboarding, existingContextConfig.onboarded);
@@ -2772,24 +2954,25 @@ async function executeSafeReadinessFixes(rootDir, options) {
 }
 
 // src/scanner/snapshot.ts
-import path20 from "path";
+import path21 from "path";
 var READINESS_SNAPSHOT_RELATIVE_PATH = ".cursor/context/readiness.json";
 async function writeReadinessSnapshot(rootDir, report) {
-  const snapshotPath = path20.join(rootDir, READINESS_SNAPSHOT_RELATIVE_PATH);
+  const snapshotPath = path21.join(rootDir, READINESS_SNAPSHOT_RELATIVE_PATH);
   await writeJson(snapshotPath, report);
   return snapshotPath;
 }
 
 // src/commands/doctor.ts
 async function runDoctor(cwd, options = {}) {
-  const rootDir = path21.resolve(cwd);
+  const rootDir = path22.resolve(cwd);
+  const hooks = await assessHooksHealth(rootDir);
   if (options.fixSafe) {
     const execution = await executeSafeReadinessFixes(rootDir, {
       generatorVersion: KIT_VERSION,
       generatedAt: options.generatedAt
     });
     await writeReadinessSnapshot(rootDir, execution.after);
-    return { report: execution.after, safeChanges: execution.changes };
+    return { report: execution.after, safeChanges: execution.changes, hooks };
   }
   const scan = await runScanner(rootDir);
   const report = createReadinessReport(scan, {
@@ -2797,7 +2980,7 @@ async function runDoctor(cwd, options = {}) {
     generatedAt: options.generatedAt
   });
   await writeReadinessSnapshot(rootDir, report);
-  return { report, safeChanges: [] };
+  return { report, safeChanges: [], hooks };
 }
 function printDoctorSummary(result) {
   const { summary, pendingActions } = result.report;
@@ -2809,6 +2992,12 @@ function printDoctorSummary(result) {
   );
   console.log(`  safe fixes applied: ${fixed}`);
   console.log(`  pending actions: ${pendingActions.length}`);
+  console.log(`hooks: ${result.hooks.status}`);
+  if (result.hooks.reasons.length > 0) {
+    for (const reason of result.hooks.reasons.slice(0, 5)) {
+      console.log(`  - ${reason}`);
+    }
+  }
   console.log(
     nextAction ? `Next: ${nextAction.recommendation}` : "Next: repository readiness checks are complete"
   );
@@ -2844,11 +3033,210 @@ var doctorCommand = defineCommand6({
   }
 });
 
+// src/commands/guard.ts
+import { defineCommand as defineCommand7 } from "citty";
+
+// src/hooks/read-stdin-json.ts
+async function readStdinJson() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+  }
+  const raw = Buffer.concat(chunks).toString("utf8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+// src/invariants/secrets-scan.ts
+var CITE = "agent-kit guard prompt (docs/cursor-native-audit.md)";
+var SECRET_PATTERNS2 = [
+  {
+    id: "json-secret-kv",
+    re: /"(password|apiKey|api_key|secret|token|auth)"\s*:\s*"[^"]{12,}"/i
+  },
+  {
+    id: "env-assignment",
+    re: /\b(?:API_KEY|SECRET|PASSWORD|TOKEN|ACCESS_KEY|PRIVATE_KEY)\s*=\s*['"]?[^\s'"]{12,}/i
+  },
+  {
+    id: "aws-access-key",
+    re: /\bAKIA[0-9A-Z]{16}\b/
+  },
+  {
+    id: "github-pat",
+    re: /\bghp_[A-Za-z0-9_]{36,}\b/
+  },
+  {
+    id: "openai-sk",
+    re: /\bsk-[A-Za-z0-9]{20,}\b/
+  }
+];
+function excerptAround(text, index, len) {
+  const start = Math.max(0, index - 8);
+  const end = Math.min(text.length, index + len + 8);
+  return text.slice(start, end).replace(/\s+/g, " ");
+}
+function scanTextForSecrets(text) {
+  if (!text) return [];
+  const hits = [];
+  for (const { id, re } of SECRET_PATTERNS2) {
+    const flags = re.flags.includes("g") ? re.flags : `${re.flags}g`;
+    const global = new RegExp(re.source, flags);
+    let match = global.exec(text);
+    while (match) {
+      hits.push({
+        patternId: id,
+        excerpt: excerptAround(text, match.index, match[0].length)
+      });
+      if (!global.global) break;
+      match = global.exec(text);
+    }
+  }
+  return hits;
+}
+function secretsAdviseMessage(hits) {
+  const ids = [...new Set(hits.map((h) => h.patternId))].join(", ");
+  return `Possible secret pattern(s) in prompt (${ids}). Cite: ${CITE}. Remove live credentials before submitting; use env vars or a secrets store.`;
+}
+
+// src/invariants/shell-guard.ts
+var CITE2 = "agent-kit guard shell (ADR 2026-07-29_cli-invariants-thin-hook-adapters)";
+function normalizeShellCommand(command) {
+  return command.replace(/\s+/g, " ").trim();
+}
+function shellInvocationHeads(command) {
+  const normalized = normalizeShellCommand(command);
+  if (!normalized) return [];
+  return normalized.split(/(?:&&|\|\||[;|])/).map((part) => part.trim().replace(/^(?:\w+=\S+\s+)*/, "")).filter(Boolean);
+}
+function anyHeadMatches(command, re) {
+  return shellInvocationHeads(command).some((head) => re.test(head));
+}
+var SHELL_DENY_RULES = [
+  {
+    id: "git-checkout-path",
+    description: "git checkout -- <paths> discards working-tree edits",
+    test: (cmd) => anyHeadMatches(cmd, /^(?:[\w./-]+\/)?git\s+checkout\s+--(?:\s|$)/)
+  },
+  {
+    id: "git-restore",
+    description: "git restore discards working-tree edits",
+    test: (cmd) => anyHeadMatches(cmd, /^(?:[\w./-]+\/)?git\s+restore\b/)
+  },
+  {
+    id: "git-reset-hard",
+    description: "git reset --hard destroys uncommitted work",
+    test: (cmd) => anyHeadMatches(cmd, /^(?:[\w./-]+\/)?git\s+reset\b.*--hard\b/)
+  },
+  {
+    id: "git-clean-fd",
+    description: "git clean -fd removes untracked files",
+    test: (cmd) => shellInvocationHeads(cmd).some(
+      (head) => /^(?:[\w./-]+\/)?git\s+clean\b/.test(head) && /(?:^|\s)-(?:[a-z]*f[a-z]*d|[a-z]*d[a-z]*f)(?:\s|$)/.test(head)
+    )
+  },
+  {
+    id: "git-push-main",
+    description: "direct push to main/master/prod bypasses staging",
+    test: (cmd) => shellInvocationHeads(cmd).some((head) => {
+      if (!/^(?:[\w./-]+\/)?git\s+push\b/.test(head)) return false;
+      return /(?:^|\s)(?:origin\/)?(?:main|master|prod)(?:\s|$|:)/.test(head) || /HEAD:(?:refs\/heads\/)?(?:main|master|prod)\b/.test(head) || /(?:^|\s)-(?:u|--set-upstream)\s+\S+\s+(?:main|master|prod)(?:\s|$)/.test(head);
+    })
+  }
+];
+function evaluateShellCommand(command) {
+  const normalized = normalizeShellCommand(command);
+  if (!normalized) {
+    return { permission: "allow" };
+  }
+  for (const rule of SHELL_DENY_RULES) {
+    if (rule.test(normalized)) {
+      const agent_message = `Denied by ${CITE2}: ${rule.description} (rule \`${rule.id}\`). Use /git-staging; never discard human hunks or push protected branches from the agent.`;
+      return {
+        permission: "deny",
+        rule: rule.id,
+        agent_message,
+        user_message: agent_message
+      };
+    }
+  }
+  return { permission: "allow" };
+}
+
+// src/commands/guard.ts
+var guardCommand = defineCommand7({
+  meta: {
+    name: "guard",
+    description: "Mechanizable deny/annotate guards (shell, prompt). Hooks are thin adapters."
+  },
+  subCommands: {
+    shell: defineCommand7({
+      meta: {
+        name: "shell",
+        description: "Evaluate a shell command against the destructive deny-list"
+      },
+      args: {
+        json: {
+          type: "boolean",
+          default: true,
+          description: "Print Cursor beforeShellExecution JSON (default)"
+        },
+        command: {
+          type: "string",
+          description: "Command string (otherwise read from stdin JSON.command)"
+        }
+      },
+      async run({ args }) {
+        let command = typeof args.command === "string" ? args.command : "";
+        if (!command) {
+          const payload = await readStdinJson();
+          command = typeof payload.command === "string" ? payload.command : "";
+        }
+        const result = evaluateShellCommand(command);
+        console.log(JSON.stringify(result));
+      }
+    }),
+    prompt: defineCommand7({
+      meta: {
+        name: "prompt",
+        description: "Scan prompt text for secret patterns (advisory; fail-open at hook)"
+      },
+      args: {
+        json: {
+          type: "boolean",
+          default: true
+        }
+      },
+      async run() {
+        const payload = await readStdinJson();
+        const text = typeof payload.prompt === "string" && payload.prompt || typeof payload.text === "string" && payload.text || "";
+        const hits = scanTextForSecrets(text);
+        if (hits.length === 0) {
+          console.log(JSON.stringify({ continue: true, hits: [] }));
+          return;
+        }
+        console.log(
+          JSON.stringify({
+            continue: true,
+            user_message: secretsAdviseMessage(hits),
+            agent_message: secretsAdviseMessage(hits),
+            hits
+          })
+        );
+      }
+    })
+  }
+});
+
 // src/commands/handoff.ts
 import { spawn as spawn3 } from "child_process";
-import { readFile as readFile9, readdir as readdir2, writeFile as writeFile4 } from "fs/promises";
-import path22 from "path";
-import { defineCommand as defineCommand7 } from "citty";
+import { readFile as readFile10, readdir as readdir2, writeFile as writeFile4 } from "fs/promises";
+import path23 from "path";
+import { defineCommand as defineCommand8 } from "citty";
 function parsePlanFrontmatter(raw) {
   const match = raw.match(/^---\n([\s\S]*?)\n---/);
   if (!match?.[1]) return null;
@@ -2867,19 +3255,19 @@ async function findActivePlan(plansDir) {
   if (!await fileExists(plansDir)) return null;
   const files = (await readdir2(plansDir)).filter((f) => f.endsWith(".plan.md")).sort().reverse();
   for (const file of files) {
-    const raw = await readFile9(path22.join(plansDir, file), "utf8");
+    const raw = await readFile10(path23.join(plansDir, file), "utf8");
     const fm = parsePlanFrontmatter(raw);
     if (fm?.todos?.some((t) => t.status !== "completed" && t.status !== "cancelled")) {
       return { file, raw };
     }
   }
-  return files[0] ? { file: files[0], raw: await readFile9(path22.join(plansDir, files[0]), "utf8") } : null;
+  return files[0] ? { file: files[0], raw: await readFile10(path23.join(plansDir, files[0]), "utf8") } : null;
 }
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString().replace("T", " ").slice(0, 16);
 }
 async function loadProfile(rootDir) {
-  const configPath = path22.join(rootDir, ".cursor", "agent-kit.config.json");
+  const configPath = path23.join(rootDir, ".cursor", "agent-kit.config.json");
   try {
     return await readJson(configPath);
   } catch {
@@ -2965,7 +3353,7 @@ function runCursorHandoff(scriptPath, cwd) {
     child.on("close", (code) => resolve(code ?? 1));
   });
 }
-var handoffCommand = defineCommand7({
+var handoffCommand = defineCommand8({
   meta: {
     name: "handoff",
     description: "Write .cursor/HANDOFF.md from the active Cursor plan, or run ./cursor-handoff handoff when no plan exists."
@@ -2979,13 +3367,13 @@ var handoffCommand = defineCommand7({
   },
   async run({ args }) {
     const profile = await loadProfile(args.cwd);
-    const plansDir = path22.join(args.cwd, ".cursor", "plans");
-    const handoffPath = path22.join(args.cwd, ".cursor", "HANDOFF.md");
+    const plansDir = path23.join(args.cwd, ".cursor", "plans");
+    const handoffPath = path23.join(args.cwd, ".cursor", "HANDOFF.md");
     const plan = await findActivePlan(plansDir);
     if (plan) {
       const fm = parsePlanFrontmatter(plan.raw);
       if (fm) {
-        await ensureDir(path22.join(args.cwd, ".cursor"));
+        await ensureDir(path23.join(args.cwd, ".cursor"));
         const content = buildHandoff(plan.file, fm, profile);
         await writeFile4(handoffPath, content, "utf8");
         logger.success("HANDOFF.md updated: .cursor/HANDOFF.md");
@@ -3005,7 +3393,7 @@ var handoffCommand = defineCommand7({
       }
       logger.warn(`Plan ${plan.file} without valid frontmatter; trying legacy flow.`);
     }
-    const scriptPath = path22.join(args.cwd, "cursor-handoff");
+    const scriptPath = path23.join(args.cwd, "cursor-handoff");
     if (!await fileExists(scriptPath)) {
       printV3Guidance();
       return;
@@ -3029,17 +3417,388 @@ var handoffCommand = defineCommand7({
   }
 });
 
+// src/commands/hook.ts
+import path25 from "path";
+import { defineCommand as defineCommand9 } from "citty";
+
+// src/hooks/pre-compact.ts
+function buildPreCompactUserMessage(payload = {}) {
+  const pct = payload.context_usage_percent;
+  const trigger = payload.trigger || "auto";
+  const pctTxt = pct !== void 0 && pct !== null ? `~${pct}%` : "high";
+  const msg = `Context compacting (${trigger}, usage ${pctTxt}). Update \`.cursor/HANDOFF.md\` and open a new chat with \`/continue-plan\` so the next agent starts fresh.`;
+  return { user_message: msg };
+}
+
+// src/hooks/session-start.ts
+import { spawn as spawn4 } from "child_process";
+import { access as access5, readFile as readFile11 } from "fs/promises";
+import path24 from "path";
+
+// src/invariants/handoff-schema.ts
+var MACHINE_LIST_CHECKS = [
+  {
+    heading: "Backlog plans",
+    fieldLabels: ["Backlog plans", "Backlog"],
+    code: "heading-without-field-backlog"
+  },
+  {
+    heading: "Parked plans",
+    fieldLabels: ["Parked plans"],
+    code: "heading-without-field-parked"
+  },
+  {
+    heading: "Run queue",
+    fieldLabels: ["Run queue"],
+    code: "heading-without-field-run-queue"
+  }
+];
+var CITE3 = "agent-kit validate handoff (see .cursor/context/templates/handoff.md)";
+function validateHandoffText(text) {
+  if (!text.trim()) return [];
+  const warnings = [];
+  for (const check2 of MACHINE_LIST_CHECKS) {
+    const headingRe = new RegExp(`^##\\s+${check2.heading}\\s*$`, "m");
+    if (!headingRe.test(text)) continue;
+    const hasField = check2.fieldLabels.some(
+      (label) => new RegExp(`^- \\*\\*${label}:\\*\\*`, "m").test(text)
+    );
+    if (!hasField) {
+      warnings.push({
+        code: check2.code,
+        message: `\`## ${check2.heading}\` found without \`- **${check2.fieldLabels[0]}:**\` (Mission Control will miss this list; rewrite as a field bullet).`,
+        cite: CITE3
+      });
+    }
+  }
+  return warnings;
+}
+
+// src/hooks/hard-rules.ts
+var HARD_RULES = `# Agent Kit session hard rules (manual mode default)
+
+1. **One phase per chat.** Finish the current phase (or one to-do if the phase is huge), update \`.cursor/HANDOFF.md\`, then STOP and ask the user before starting the next phase.
+2. **Do not burn the window.** Never run an entire multi-phase plan in one conversation unless the user explicitly ran \`/run-plan\` (or a deprecated alias \`/run-plan-loop\` / \`/run-plan-orchestrated\`).
+3. **Context questions are not optional.** If the user asks about context / contexto / window size, run the context-guardian protocol: warn, offer handoff, do NOT dismiss with "it's fine" and keep coding.
+4. **Read HANDOFF first** when resuming. Do not restart the plan from scratch.
+5. **Git:** suggest \`/git-staging\` after a phase with a diff; never \`/git-prod\` without explicit confirmation.
+6. **HITL slash commands win.** When waiting for confirmation on \`/git-staging\` or \`/git-prod\` (or similar), do not divert to continue-plan / phase-boundary chatter; stay on that routine until the user answers.
+7. **\`/start-project\` is plan bootstrap, not execute.** Broad Intake Review first, then two gates: (A) single composite question (with active plan: backlog+write / park+write / modify / cancel; without: write / modify / cancel) \u2014 approve/write the plan file only, (B) approve the first unit. Goal text in the same message is NOT permission to edit product files. Never "create plan and start Phase 1" in one turn. If HANDOFF already has an active plan, disposition is merged into Gate A composite options; never park silently. Gates use Ask questions per \`.cursor/rules/hitl-ask-questions.mdc\`. Fallback: one numbered list per message.
+8. **\`/continue-plan\` waits for yes.** Summarize next \`[to-do-id]\`, then stop until the user confirms before editing.
+9. **\`/run-plan-all\` is a pure orchestrator.** After the confirm queue Ask, dispatch one Task subagent per plan (run the \`/run-plan\` tick contract inside it); never implement to-dos, run tests, or write changelogs in the orchestrator window.
+10. **Backlog CRUD never activates.** \`/backlog-add\` enqueues (Broad Intake + write Ask + plan file + HANDOFF Backlog) without park, activate, or Gate B. \`/backlog-edit\` / \`/backlog-delete\` / \`/backlog-cancel\` require Ask confirm before mutate; delete archives from Backlog, cancel is soft in place. No Field Report cards for routine backlog CRUD.
+11. **HANDOFF machine fields are bullet fields, not \`##\` headings.** Mission Control parses \`- **Plan:**\`, \`- **Backlog plans:**\`, \`- **Parked plans:**\`, \`- **Run queue:**\` (etc.). Canonical Plan: \`- **Plan:** \\\`name.plan.md\\\`\` or \`none\`. Nested backlog/parked rows: \`- \\\`other.plan.md\\\`\`. Never invent \`## Backlog plans\` / \`## Parked plans\` / \`## Run queue\` headings in place of those fields (Checklist / Current mission go empty or idle).`;
+var DOGFOOD_INBOX_HINT = `## Dogfood inbox
+
+Unprocessed files are listed under \`dogfood/README.md\` (### Unprocessed Files). Follow the ingest ritual there (detect \u2192 analyze \u2192 memory WRITE \u2192 triage). Do not auto-start analysis unless the user asks.`;
+var UPDATE_CHECK_NUDGE = `## Agent Kit update available
+
+Installed **v{installed}**; latest public **v{latest}**.
+
+This is an advisory only (no files were changed). To apply, run \`/update\` and confirm via Ask questions. Bare \`agent-kit update\` is an explicit operator invoke, not a background job.`;
+
+// src/hooks/session-start.ts
+var NONE_PLACEHOLDERS = /* @__PURE__ */ new Set(["none", "n/a", "empty", "nil"]);
+async function readTextLimited(filePath, limit = 60) {
+  try {
+    const lines = (await readFile11(filePath, "utf8")).split(/\r?\n/);
+    return lines.slice(0, limit).join("\n").trim();
+  } catch {
+    return "";
+  }
+}
+async function readFull(filePath) {
+  try {
+    return await readFile11(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+async function fileExists2(p) {
+  try {
+    await access5(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function parseUnprocessedDogfoodItems(readmeText) {
+  const items = [];
+  let inSection = false;
+  for (const line of readmeText.split(/\r?\n/)) {
+    if (line.startsWith("### Unprocessed Files")) {
+      inSection = true;
+      continue;
+    }
+    if (!inSection) continue;
+    if (line.startsWith("### ")) break;
+    const stripped = line.trim();
+    if (!stripped.startsWith("- ")) continue;
+    const body = stripped.slice(2).trim();
+    const normalized = body.toLowerCase().replace(/[*_]/g, "").trim();
+    if (!normalized || NONE_PLACEHOLDERS.has(normalized)) continue;
+    items.push(body);
+  }
+  return items;
+}
+async function l0Present(root) {
+  const cursor = path24.join(root, ".cursor");
+  return await fileExists2(path24.join(cursor, "agent-kit.json")) || await fileExists2(path24.join(cursor, "commands", "agent-kit-onboard.md")) || await fileExists2(path24.join(cursor, "commands", "start-project.md"));
+}
+function checkLabelAndRecommendation(check2) {
+  const checkId = check2.id;
+  if (typeof checkId !== "string" || !checkId) return null;
+  const actions = check2.actions;
+  if (Array.isArray(actions)) {
+    for (const action2 of actions) {
+      if (!action2 || typeof action2 !== "object") continue;
+      const a = action2;
+      if (typeof a.id === "string" && typeof a.recommendation === "string") {
+        return [a.id, a.recommendation];
+      }
+    }
+  }
+  const title = check2.title;
+  if (typeof title === "string" && title) return [checkId, title];
+  return [checkId, "Resolve this readiness check"];
+}
+function unresolvedReadinessChecks(data) {
+  const essential = [];
+  const nonessential = [];
+  const pillars = data.pillars;
+  if (!Array.isArray(pillars)) return { essential, nonessential };
+  for (const pillar2 of pillars) {
+    if (!pillar2 || typeof pillar2 !== "object") continue;
+    const checks = pillar2.checks;
+    if (!Array.isArray(checks)) continue;
+    for (const check2 of checks) {
+      if (!check2 || typeof check2 !== "object") continue;
+      const c = check2;
+      if (c.status === "ready") continue;
+      if (c.essential === true) essential.push(c);
+      else nonessential.push(c);
+    }
+  }
+  return { essential, nonessential };
+}
+async function readinessSection(root) {
+  const snapshotPath = path24.join(root, ".cursor", "context", "readiness.json");
+  let data;
+  try {
+    data = JSON.parse(await readFile11(snapshotPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const { essential, nonessential } = unresolvedReadinessChecks(data);
+  if (essential[0]) {
+    const labeled = checkLabelAndRecommendation(essential[0]);
+    if (!labeled) return null;
+    const [actionId, recommendation] = labeled;
+    return `## Repository readiness
+
+Unresolved essential check: \`${actionId}\`. ${recommendation} Run \`/agent-kit-onboard\` before \`/start-project\`. An active plan or HANDOFF remains the current work and is not replaced.`;
+  }
+  if (nonessential[0]) {
+    const labeled = checkLabelAndRecommendation(nonessential[0]);
+    if (!labeled) return null;
+    const [actionId, recommendation] = labeled;
+    return `## Repository readiness
+
+Optional readiness item: \`${actionId}\`. ${recommendation} This does not block \`/start-project\` or active plan work. Resume later with \`/agent-kit-onboard\` if useful.`;
+  }
+  const actions = data.pendingActions;
+  if (!Array.isArray(actions) || !actions[0] || typeof actions[0] !== "object") return null;
+  const first = actions[0];
+  if (typeof first.id !== "string" || typeof first.recommendation !== "string") return null;
+  return `## Repository readiness
+
+Optional readiness item: \`${first.id}\`. ${first.recommendation} This does not block \`/start-project\` or active plan work. Resume later with \`/agent-kit-onboard\` if useful.`;
+}
+async function dogfoodInboxSection(root) {
+  const dogfoodDir = path24.join(root, "dogfood");
+  if (!await fileExists2(dogfoodDir)) return null;
+  const readme = path24.join(dogfoodDir, "README.md");
+  if (!await fileExists2(readme)) return null;
+  try {
+    const text = await readFile11(readme, "utf8");
+    if (!parseUnprocessedDogfoodItems(text).length) return null;
+    return DOGFOOD_INBOX_HINT;
+  } catch {
+    return null;
+  }
+}
+async function loadUpdateCheckPrefs(root) {
+  try {
+    const data = JSON.parse(
+      await readFile11(path24.join(root, ".cursor", "context", "config.json"), "utf8")
+    );
+    const uc = data.updateCheck;
+    if (!uc || typeof uc !== "object" || uc.enabled !== true) {
+      return null;
+    }
+    return uc;
+  } catch {
+    return null;
+  }
+}
+function runUpdateCheckJson(root) {
+  return new Promise((resolve) => {
+    const child = spawn4(
+      process.execPath,
+      [
+        process.argv[1] ?? "",
+        "update",
+        "--check",
+        "--json",
+        "--respect-prefs",
+        "--stamp",
+        "--cwd",
+        root
+      ],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: 12e3 }
+    );
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", () => {
+      try {
+        const parsed = JSON.parse(out.trim());
+        resolve(parsed && typeof parsed === "object" ? parsed : null);
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+async function updateCheckSection(root) {
+  if (await loadUpdateCheckPrefs(root) === null) return null;
+  const result = await new Promise((resolve) => {
+    const child = spawn4(
+      "agent-kit",
+      ["update", "--check", "--json", "--respect-prefs", "--stamp", "--cwd", root],
+      { stdio: ["ignore", "pipe", "ignore"], timeout: 12e3, shell: false }
+    );
+    let out = "";
+    child.stdout?.on("data", (chunk) => {
+      out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      void runUpdateCheckJson(root).then(resolve);
+    });
+    child.on("close", (code) => {
+      if (code !== 0 && !out.trim()) {
+        void runUpdateCheckJson(root).then(resolve);
+        return;
+      }
+      try {
+        resolve(JSON.parse(out.trim()));
+      } catch {
+        void runUpdateCheckJson(root).then(resolve);
+      }
+    });
+  });
+  if (!result || result.status !== "update-available") return null;
+  if (result.applyRecommended === true) return null;
+  const installed = String(result.installedVersion ?? "?");
+  const latest = String(result.latestVersion ?? "?");
+  return UPDATE_CHECK_NUDGE.replace("{installed}", installed).replace("{latest}", latest);
+}
+async function buildSessionStartAdditionalContext(rootDir, _payload = {}) {
+  const root = path24.resolve(rootDir);
+  const handoffPath = path24.join(root, ".cursor", "HANDOFF.md");
+  const handoffFull = await readFull(handoffPath);
+  const handoff = await readTextLimited(handoffPath);
+  const parts = [HARD_RULES];
+  if (await l0Present(root)) {
+    const readiness = await readinessSection(root);
+    if (readiness) parts.push(readiness);
+  }
+  const dogfood = await dogfoodInboxSection(root);
+  if (dogfood) parts.push(dogfood);
+  const updateNudge = await updateCheckSection(root);
+  if (updateNudge) parts.push(updateNudge);
+  const formatWarnings = validateHandoffText(handoffFull);
+  if (formatWarnings.length) {
+    const bullet = formatWarnings.map((w) => `- ${w.message}`).join("\n");
+    parts.push(
+      `## HANDOFF format warning (Mission Control)
+
+${bullet}
+
+Rewrite machine lists as \`- **Field:**\` bullets before trusting Checklist / Current mission.`
+    );
+  }
+  if (handoff) {
+    parts.push(`## Current HANDOFF.md (excerpt)
+
+${handoff}`);
+  } else {
+    parts.push(
+      "## HANDOFF.md\n\nNo handoff file yet. If starting work, create a plan with to-dos first (`/start-project`)."
+    );
+  }
+  return { additional_context: parts.join("\n\n") };
+}
+function resolveSessionRoot(payload, cwd = process.cwd()) {
+  const roots = payload.workspace_roots;
+  if (Array.isArray(roots) && typeof roots[0] === "string" && roots[0]) {
+    return roots[0];
+  }
+  return cwd;
+}
+
+// src/commands/hook.ts
+var hookCommand = defineCommand9({
+  meta: {
+    name: "hook",
+    description: "Cursor hook adapters (session-start, pre-compact). CLI is SoT; thin hooks shell out here."
+  },
+  subCommands: {
+    "session-start": defineCommand9({
+      meta: {
+        name: "session-start",
+        description: "Emit sessionStart additional_context JSON (stdin: Cursor payload)"
+      },
+      args: {
+        cwd: {
+          type: "string",
+          default: process.cwd()
+        }
+      },
+      async run({ args }) {
+        const payload = await readStdinJson();
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const root = resolveSessionRoot(payload, path25.resolve(cwd));
+        const out = await buildSessionStartAdditionalContext(root, payload);
+        console.log(JSON.stringify(out));
+      }
+    }),
+    "pre-compact": defineCommand9({
+      meta: {
+        name: "pre-compact",
+        description: "Emit preCompact user_message JSON (stdin: Cursor payload)"
+      },
+      async run() {
+        const payload = await readStdinJson();
+        console.log(JSON.stringify(buildPreCompactUserMessage(payload)));
+      }
+    })
+  }
+});
+
 // src/commands/init.ts
 import { intro, outro } from "@clack/prompts";
-import { defineCommand as defineCommand9 } from "citty";
+import { defineCommand as defineCommand11 } from "citty";
 
 // src/commands/install.ts
-import path25 from "path";
-import { defineCommand as defineCommand8 } from "citty";
+import path28 from "path";
+import { defineCommand as defineCommand10 } from "citty";
 
 // src/generator/personalization.ts
-import { readFile as readFile10, writeFile as writeFile5 } from "fs/promises";
-import path23 from "path";
+import { readFile as readFile12, writeFile as writeFile5 } from "fs/promises";
+import path26 from "path";
 var PERSONALIZATION_CONTRACT_VERSION = 1;
 var CONTEXT_PATH = ".cursor/project-context.md";
 var AGENTS_PATH = "AGENTS.md";
@@ -3190,7 +3949,7 @@ function renderProjectContext(profile) {
 `;
 }
 async function createOwnedFile(rootDir, relativePath, content, evidence) {
-  const target = path23.join(rootDir, relativePath);
+  const target = path26.join(rootDir, relativePath);
   if (await fileExists(target)) {
     return {
       kind: "file",
@@ -3200,7 +3959,7 @@ async function createOwnedFile(rootDir, relativePath, content, evidence) {
       evidence
     };
   }
-  await ensureDir(path23.dirname(target));
+  await ensureDir(path26.dirname(target));
   await writeFile5(target, content, "utf8");
   return {
     kind: "file",
@@ -3217,7 +3976,7 @@ async function packTargets(registryRoot, packId) {
 async function existingTargets(projectRoot, targets) {
   const checks = await Promise.all(
     targets.map(
-      async (target) => await fileExists(path23.join(projectRoot, target)) ? target : null
+      async (target) => await fileExists(path26.join(projectRoot, target)) ? target : null
     )
   );
   return checks.filter((target) => target !== null);
@@ -3239,14 +3998,14 @@ async function applyPersonalization(input) {
         componentResults.push({ ...item, status: "unavailable" });
         continue;
       }
-      const target = path23.posix.join(
+      const target = path26.posix.join(
         ".cursor",
         "skills",
         skill.path.includes("/core/") ? "core" : "community",
         skill.id,
         "SKILL.md"
       );
-      if (await fileExists(path23.join(input.rootDir, target))) {
+      if (await fileExists(path26.join(input.rootDir, target))) {
         componentResults.push({ ...item, status: "skipped-customized", path: target });
         protectedPaths.add(target);
         continue;
@@ -3301,7 +4060,7 @@ async function applyPersonalization(input) {
     items: [...fileResults, ...componentResults],
     protectedPaths: [...protectedPaths].sort()
   };
-  await writeJson(path23.join(input.rootDir, RESULT_PATH), result);
+  await writeJson(path26.join(input.rootDir, RESULT_PATH), result);
   return {
     result,
     manifest: {
@@ -3319,26 +4078,26 @@ async function applyPersonalization(input) {
   };
 }
 async function readRepositoryProfile(rootDir) {
-  const target = path23.join(rootDir, ".cursor/agent-kit.config.json");
+  const target = path26.join(rootDir, ".cursor/agent-kit.config.json");
   if (!await fileExists(target)) return null;
-  return JSON.parse(await readFile10(target, "utf8"));
+  return JSON.parse(await readFile12(target, "utf8"));
 }
 
 // src/lifecycle/onboard-migration.ts
 import { createHash as createHash3 } from "crypto";
-import { readFile as readFile11, unlink } from "fs/promises";
-import path24 from "path";
+import { readFile as readFile13, unlink } from "fs/promises";
+import path27 from "path";
 var LEGACY_ONBOARD_PATH = ".cursor/commands/onboard.md";
 var NAMESPACED_ONBOARD_PATH = ".cursor/commands/agent-kit-onboard.md";
 var MANAGED_LEGACY_HASHES = /* @__PURE__ */ new Set([
   "b274a68941813f19b185893cb7c5561dff027f53270890029992f208e24992fe"
 ]);
 async function migrateLegacyOnboardCommand(projectRoot, managedHashes = MANAGED_LEGACY_HASHES) {
-  const legacyPath = path24.join(projectRoot, LEGACY_ONBOARD_PATH);
+  const legacyPath = path27.join(projectRoot, LEGACY_ONBOARD_PATH);
   if (!await fileExists(legacyPath)) return "absent";
-  const namespacedPath = path24.join(projectRoot, NAMESPACED_ONBOARD_PATH);
+  const namespacedPath = path27.join(projectRoot, NAMESPACED_ONBOARD_PATH);
   if (!await fileExists(namespacedPath)) return "preserved-customized";
-  const content = await readFile11(legacyPath);
+  const content = await readFile13(legacyPath);
   const hash = createHash3("sha256").update(content).digest("hex");
   if (!managedHashes.has(hash)) return "preserved-customized";
   await unlink(legacyPath);
@@ -3407,7 +4166,7 @@ function printReadinessNarrative(result) {
   );
 }
 async function performInstall(options) {
-  const projectRoot = path25.resolve(options.cwd);
+  const projectRoot = path28.resolve(options.cwd);
   const packs = parsePackList(options.pack);
   const existing = await loadAgentKitManifest(projectRoot);
   const registry = await resolveRegistryFromCli({
@@ -3461,7 +4220,7 @@ async function performInstall(options) {
     safeChanges: readinessExecution.changes
   };
 }
-var installCommand = defineCommand8({
+var installCommand = defineCommand10({
   meta: {
     name: "install",
     description: "Bootstrap L0 (+ optional packs) from the registry and write agent-kit.json."
@@ -3483,7 +4242,7 @@ var installCommand = defineCommand8({
     ...REGISTRY_CLI_ARGS
   },
   async run({ args }) {
-    const projectRoot = path25.resolve(args.cwd);
+    const projectRoot = path28.resolve(args.cwd);
     logger.info(`Installing into: ${projectRoot}`);
     const packs = parsePackList(args.pack);
     for (const id of packs) {
@@ -3511,7 +4270,7 @@ var installCommand = defineCommand8({
 async function runInitCompatibility(cwd, installer = performInstall) {
   return installer({ cwd });
 }
-var initCommand = defineCommand9({
+var initCommand = defineCommand11({
   meta: {
     name: "init",
     description: "Guided compatibility entry point for install and repository readiness."
@@ -3535,16 +4294,186 @@ var initCommand = defineCommand9({
   }
 });
 
-// src/commands/run-plan.ts
+// src/commands/monitors.ts
 import path30 from "path";
-import { defineCommand as defineCommand10 } from "citty";
+import { defineCommand as defineCommand12 } from "citty";
+
+// src/invariants/monitors-untriaged.ts
+import { execFile as execFile3 } from "child_process";
+import { readFile as readFile14, readdir as readdir3, stat } from "fs/promises";
+import path29 from "path";
+import { promisify as promisify3 } from "util";
+var execFileAsync2 = promisify3(execFile3);
+var TRIAGE_HEADING_RE = /^#{2,6}\s+.*\b(triage|follow-?up plan|residuals plan)\b/im;
+var CITE4 = "agent-kit monitors --untriaged (ADR 2026-07-27_plan-review-triage-untriaged-not-mtime; never newest-mtime-wins)";
+function hasOpenGaps(content) {
+  if (/###\s+Still open[^\n]*\n+(?:\s*\n)*(?:None\.|none\.|\*None\*)/i.test(content)) {
+    return false;
+  }
+  if (/###\s+Still open/i.test(content) && !/###\s+Still open[^\n]*\n+(?:\s*\n)*(?:None\.|none\.)/i.test(content)) {
+    const m = content.match(/###\s+Still open[^\n]*\n([\s\S]*?)(?=\n### |\n## |$)/i);
+    if (m?.[1]?.trim() && !/^(none\.?|\*none\*)$/i.test(m[1].trim())) {
+      return true;
+    }
+  }
+  if (/^#{2,6}\s+.*\bResidual items?\b/im.test(content)) return true;
+  return false;
+}
+async function listMonitorFiles(memoryDir) {
+  try {
+    const names = await readdir3(memoryDir);
+    return names.filter((n) => n.startsWith("plan-monitor-") && n.endsWith(".md")).sort();
+  } catch {
+    return [];
+  }
+}
+async function gitFreshMonitorNames(rootDir) {
+  const names = /* @__PURE__ */ new Set();
+  try {
+    const { stdout } = await execFileAsync2(
+      "git",
+      ["status", "--porcelain", "--", ".cursor/memory"],
+      { cwd: rootDir, maxBuffer: 2 * 1024 * 1024 }
+    );
+    for (const line of stdout.split("\n")) {
+      if (!line.trim()) continue;
+      const file = line.slice(3).trim().replace(/^.* -> /, "");
+      const base = path29.basename(file);
+      if (base.startsWith("plan-monitor-") && base.endsWith(".md")) {
+        names.add(base);
+      }
+    }
+  } catch {
+  }
+  return names;
+}
+function extractHandoffPlanSlugs(handoff) {
+  const slugs = /* @__PURE__ */ new Set();
+  for (const m of handoff.matchAll(/`([a-z0-9][a-z0-9._-]*)\.plan\.md`/gi)) {
+    if (m[1]) slugs.add(m[1].toLowerCase());
+  }
+  for (const m of handoff.matchAll(/plan-monitor-([a-z0-9][a-z0-9._-]*)\.md/gi)) {
+    if (m[1]) slugs.add(m[1].toLowerCase());
+  }
+  return slugs;
+}
+function monitorSlugFromName(fileName) {
+  return fileName.replace(/^plan-monitor-/, "").replace(/\.md$/, "").toLowerCase();
+}
+async function selectUntriagedMonitors(rootDir) {
+  const root = path29.resolve(rootDir);
+  const memoryDir = path29.join(root, ".cursor", "memory");
+  const allNames = await listMonitorFiles(memoryDir);
+  const selectionOrder = ["git-fresh", "handoff-aligned", "untriaged-scan"];
+  const byName = /* @__PURE__ */ new Map();
+  for (const name of allNames) {
+    const abs = path29.join(memoryDir, name);
+    try {
+      const [content, st] = await Promise.all([readFile14(abs, "utf8"), stat(abs)]);
+      byName.set(name, { content, mtimeMs: st.mtimeMs });
+    } catch {
+    }
+  }
+  const untriaged = (name) => {
+    const row = byName.get(name);
+    return !!row && !TRIAGE_HEADING_RE.test(row.content);
+  };
+  const gitFresh = await gitFreshMonitorNames(root);
+  const gitFreshSet = [...gitFresh].filter(untriaged).sort();
+  let handoff = "";
+  try {
+    handoff = await readFile14(path29.join(root, ".cursor", "HANDOFF.md"), "utf8");
+  } catch {
+    handoff = "";
+  }
+  const handoffSlugs = extractHandoffPlanSlugs(handoff);
+  const handoffAligned = allNames.filter((n) => untriaged(n) && handoffSlugs.has(monitorSlugFromName(n))).sort();
+  const scanAll = allNames.filter(untriaged);
+  let chosen;
+  if (gitFreshSet.length > 0) {
+    chosen = { names: gitFreshSet, bucket: "git-fresh" };
+  } else if (handoffAligned.length > 0) {
+    chosen = { names: handoffAligned, bucket: "handoff-aligned" };
+  } else {
+    chosen = { names: scanAll, bucket: "untriaged-scan" };
+  }
+  const entries = [];
+  for (const name of chosen.names) {
+    const row = byName.get(name);
+    if (!row) continue;
+    entries.push({
+      path: path29.join(memoryDir, name),
+      relativePath: path29.relative(root, path29.join(memoryDir, name)).split(path29.sep).join("/"),
+      mtimeMs: row.mtimeMs,
+      hasTriageHeading: false,
+      hasOpenGaps: hasOpenGaps(row.content),
+      selectionBucket: chosen.bucket
+    });
+  }
+  entries.sort((a, b) => {
+    if (a.hasOpenGaps !== b.hasOpenGaps) return a.hasOpenGaps ? -1 : 1;
+    return b.mtimeMs - a.mtimeMs;
+  });
+  return {
+    selectionOrder: [...selectionOrder],
+    monitors: entries,
+    cite: CITE4
+  };
+}
+
+// src/commands/monitors.ts
+var monitorsCommand = defineCommand12({
+  meta: {
+    name: "monitors",
+    description: "Plan-monitor selection helpers (untriaged SoT for /plan-review-triage)"
+  },
+  args: {
+    cwd: {
+      type: "string",
+      default: process.cwd()
+    },
+    untriaged: {
+      type: "boolean",
+      default: false,
+      description: "Select untriaged monitors (never newest-mtime-wins alone)"
+    },
+    json: {
+      type: "boolean",
+      default: false,
+      description: "Machine-readable JSON"
+    }
+  },
+  async run({ args }) {
+    if (!args.untriaged) {
+      console.error("Usage: agent-kit monitors --untriaged [--json] [--cwd <dir>]");
+      process.exitCode = 2;
+      return;
+    }
+    const result = await selectUntriagedMonitors(path30.resolve(args.cwd));
+    if (args.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    if (result.monitors.length === 0) {
+      console.log("No untriaged plan-monitor files.");
+      return;
+    }
+    for (const m of result.monitors) {
+      console.log(m.relativePath);
+    }
+  }
+});
+
+// src/commands/run-plan.ts
+import path35 from "path";
+import { defineCommand as defineCommand13 } from "citty";
 
 // src/plan-loop/backends.ts
-import { execFileSync, spawn as spawn4 } from "child_process";
+import { execFileSync as execFileSync2, spawn as spawn5 } from "child_process";
 import { createWriteStream } from "fs";
 async function which(bin) {
   try {
-    const out = execFileSync("which", [bin], { encoding: "utf8" }).trim();
+    const out = execFileSync2("which", [bin], { encoding: "utf8" }).trim();
     return out || null;
   } catch {
     return null;
@@ -3553,7 +4482,7 @@ async function which(bin) {
 function spawnLogged(command, args, logPath) {
   return new Promise((resolve, reject) => {
     const out = createWriteStream(logPath, { flags: "w" });
-    const child = spawn4(command, args, {
+    const child = spawn5(command, args, {
       stdio: ["ignore", "pipe", "pipe"]
     });
     const onData = (chunk) => {
@@ -3621,14 +4550,14 @@ function listBackendIds() {
 }
 
 // src/plan-loop/run-loop.ts
-import { mkdir as mkdir4, readFile as readFile14, rm, unlink as unlink2 } from "fs/promises";
-import path29 from "path";
+import { mkdir as mkdir4, readFile as readFile17, rm, unlink as unlink2 } from "fs/promises";
+import path34 from "path";
 
 // src/plan-loop/external-review.ts
-import { spawn as spawn5 } from "child_process";
-import path26 from "path";
-var CANONICAL_REL = path26.join(".cursor", "scripts", "plan-external-review.sh");
-var FALLBACK_REL = path26.join("scripts", "plan-external-review.sh");
+import { spawn as spawn6 } from "child_process";
+import path31 from "path";
+var CANONICAL_REL = path31.join(".cursor", "scripts", "plan-external-review.sh");
+var FALLBACK_REL = path31.join("scripts", "plan-external-review.sh");
 function isPlanExhaustedReason(reason) {
   const r = reason.trim().toLowerCase();
   if (!r) return false;
@@ -3646,12 +4575,12 @@ function shouldArmExternalPlanReview(input) {
   return false;
 }
 async function armExternalPlanReview(root, options = {}) {
-  const spawnFn = options.spawnFn ?? spawn5;
+  const spawnFn = options.spawnFn ?? spawn6;
   const existsFn = options.existsFn ?? fileExists;
   const log = options.log ?? ((line) => console.log(line));
   const force = options.force === true;
-  const canonicalPath = path26.join(root, CANONICAL_REL);
-  const fallbackPath = path26.join(root, FALLBACK_REL);
+  const canonicalPath = path31.join(root, CANONICAL_REL);
+  const fallbackPath = path31.join(root, FALLBACK_REL);
   let scriptPath = null;
   let scriptRel = CANONICAL_REL;
   if (await existsFn(canonicalPath)) {
@@ -3704,7 +4633,7 @@ async function armExternalPlanReview(root, options = {}) {
 }
 
 // src/plan-loop/persona-banners.ts
-import path27 from "path";
+import path32 from "path";
 import {
   blue,
   cyan as cyan2,
@@ -3740,7 +4669,7 @@ function resolveColor(name, fallback) {
 async function resolveCliPersonaId(root) {
   try {
     const cfg = await readJson(
-      path27.join(root, ".cursor", "context", "config.json")
+      path32.join(root, ".cursor", "context", "config.json")
     );
     const modes = cfg?.agentPersona?.modes ?? cfg?.workspaceSkin?.modes;
     const id = modes?.[CLI_RUN_PLAN_MODE];
@@ -3751,7 +4680,7 @@ async function resolveCliPersonaId(root) {
 }
 async function loadPersonaPack(root, personaId) {
   try {
-    const personaPath = path27.join(root, "registry", "personas", "core", personaId, "persona.json");
+    const personaPath = path32.join(root, "registry", "personas", "core", personaId, "persona.json");
     const pack = await readJson(personaPath);
     if (!pack || typeof pack.id !== "string") return null;
     return pack;
@@ -3800,8 +4729,8 @@ function createPersonaBannerPrinter(persona) {
 }
 
 // src/plan-loop/plan-state.ts
-import { readFile as readFile12, readdir as readdir3 } from "fs/promises";
-import path28 from "path";
+import { readFile as readFile15, readdir as readdir4 } from "fs/promises";
+import path33 from "path";
 function countPendingTodos(raw) {
   const lines = raw.split(/\r?\n/);
   let inFront = 0;
@@ -3828,15 +4757,15 @@ function countPendingTodos(raw) {
 }
 async function findActivePlanFile(plansDir) {
   if (!await fileExists(plansDir)) return null;
-  const files = (await readdir3(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
-  return files[0] ? path28.join(plansDir, files[0]) : null;
+  const files = (await readdir4(plansDir)).filter((f) => f.endsWith(".plan.md")).sort();
+  return files[0] ? path33.join(plansDir, files[0]) : null;
 }
 async function readPlan(planPath) {
-  return readFile12(planPath, "utf8");
+  return readFile15(planPath, "utf8");
 }
 
 // src/plan-loop/sentinel.ts
-import { readFile as readFile13 } from "fs/promises";
+import { readFile as readFile16 } from "fs/promises";
 var SENTINEL_RE = /LOOP_TICK_RESULT:\s*(continue|stop(?:\s*[—\-].*)?)/i;
 function takeFromText(text) {
   if (!text) return null;
@@ -3883,7 +4812,7 @@ function parseSentinelFromLog(content) {
 }
 async function parseSentinelFromLogFile(logPath) {
   try {
-    const content = await readFile13(logPath, "utf8");
+    const content = await readFile16(logPath, "utf8");
     return parseSentinelFromLog(content);
   } catch {
     return { kind: "missing" };
@@ -3906,9 +4835,9 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 async function runPlanLoop(opts) {
-  const plansDir = path29.join(opts.root, ".cursor", "plans");
-  const stopFile = path29.join(opts.root, ".cursor", "loop.stop");
-  const logDir = path29.join(opts.root, ".cursor", "loop-logs");
+  const plansDir = path34.join(opts.root, ".cursor", "plans");
+  const stopFile = path34.join(opts.root, ".cursor", "loop.stop");
+  const logDir = path34.join(opts.root, ".cursor", "loop-logs");
   const planPath = await findActivePlanFile(plansDir);
   if (!planPath) {
     logger.error("No active plan in .cursor/plans/");
@@ -3929,7 +4858,7 @@ async function runPlanLoop(opts) {
   try {
     const persona = await loadCliRunPlanPersona(opts.root);
     const banners = createPersonaBannerPrinter(persona);
-    console.log(`Active plan: ${path29.basename(planPath)}`);
+    console.log(`Active plan: ${path34.basename(planPath)}`);
     console.log(`Pending to-dos: ${await pending()} | max ticks: ${opts.maxTicks}`);
     console.log(`Backend: ${opts.backend.id}`);
     if (persona) {
@@ -3972,8 +4901,8 @@ async function runPlanLoop(opts) {
         planExhausted = true;
         break;
       }
-      const logPath = path29.join(logDir, `tick-${stamp()}.log`);
-      const relLog = path29.relative(opts.root, logPath);
+      const logPath = path34.join(logDir, `tick-${stamp()}.log`);
+      const relLog = path34.relative(opts.root, logPath);
       console.log("");
       const tickLine = `=== tick ${tick}/${opts.maxTicks} - pending: ${before} - log: ${relLog} ===`;
       if (banners) banners.tickStart(tickLine);
@@ -3992,7 +4921,7 @@ async function runPlanLoop(opts) {
         return 1;
       }
       try {
-        const logText = await readFile14(logPath, "utf8");
+        const logText = await readFile17(logPath, "utf8");
         if (logText.includes("Too many MCP tools")) {
           const msg = "Too many MCP tools for the headless model - disable servers (cursor-agent mcp disable <id>) and run again.";
           if (banners) banners.stop(msg);
@@ -4049,7 +4978,7 @@ async function runPlanLoop(opts) {
     const finishDetail = `after ${tick} tick(s); pending: ${pendingNow}`;
     if (banners) banners.phaseComplete(finishDetail);
     console.log(
-      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path29.relative(opts.root, logDir)}/`
+      `Loop finished after ${tick} tick(s). Pending now: ${pendingNow}. Logs in ${path34.relative(opts.root, logDir)}/`
     );
     if (planExhausted || shouldArmExternalPlanReview({ pending: pendingNow, stopReason })) {
       await armExternalPlanReview(opts.root);
@@ -4061,7 +4990,7 @@ async function runPlanLoop(opts) {
 }
 
 // src/commands/run-plan.ts
-var runPlanCommand = defineCommand10({
+var runPlanCommand = defineCommand13({
   meta: {
     name: "run-plan",
     description: "Headless continuous plan runner: one fresh agent per tick (LOOP_TICK_RESULT contract). Never git-prod."
@@ -4120,7 +5049,7 @@ var runPlanCommand = defineCommand10({
       return;
     }
     const code = await runPlanLoop({
-      root: path30.resolve(args.cwd),
+      root: path35.resolve(args.cwd),
       maxTicks,
       sleepSeconds,
       model: args.model ? String(args.model) : void 0,
@@ -4132,8 +5061,8 @@ var runPlanCommand = defineCommand10({
 });
 
 // src/commands/scan.ts
-import { defineCommand as defineCommand11 } from "citty";
-var scanCommand = defineCommand11({
+import { defineCommand as defineCommand14 } from "citty";
+var scanCommand = defineCommand14({
   meta: {
     name: "scan",
     description: "Scan the current repository and print detected profile."
@@ -4154,8 +5083,8 @@ var scanCommand = defineCommand11({
 });
 
 // src/commands/status.ts
-import path31 from "path";
-import { defineCommand as defineCommand12 } from "citty";
+import path36 from "path";
+import { defineCommand as defineCommand15 } from "citty";
 function profileStatus(profile) {
   if (!profile) return { origin: "none", evidence: [], profile: null };
   if ("detection" in profile && profile.detection && typeof profile.detection === "object") {
@@ -4168,7 +5097,7 @@ function profileStatus(profile) {
   }
   return { origin: "legacy-wizard", evidence: [], profile };
 }
-var statusCommand = defineCommand12({
+var statusCommand = defineCommand15({
   meta: {
     name: "status",
     description: "Show Agent Kit distribution status (manifest + optional wizard profile)."
@@ -4185,11 +5114,11 @@ var statusCommand = defineCommand12({
     }
   },
   async run({ args }) {
-    const rootDir = path31.resolve(args.cwd);
+    const rootDir = path36.resolve(args.cwd);
     const [manifest, rawProfile, scan] = await Promise.all([
       loadAgentKitManifest(rootDir),
       readJson(
-        path31.join(rootDir, ".cursor", "agent-kit.config.json")
+        path36.join(rootDir, ".cursor", "agent-kit.config.json")
       ),
       runScanner(rootDir)
     ]);
@@ -4244,13 +5173,13 @@ var statusCommand = defineCommand12({
 });
 
 // src/commands/update.ts
-import { defineCommand as defineCommand13 } from "citty";
+import { defineCommand as defineCommand16 } from "citty";
 
 // src/lifecycle/check-updates.ts
-import { execFile as execFile3 } from "child_process";
-import path32 from "path";
-import { promisify as promisify3 } from "util";
-var execFileAsync2 = promisify3(execFile3);
+import { execFile as execFile4 } from "child_process";
+import path37 from "path";
+import { promisify as promisify4 } from "util";
+var execFileAsync3 = promisify4(execFile4);
 var SEMVER_CORE = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/i;
 var FACTORY_URL_MARKERS = ["agent-kit-dev"];
 var FACTORY_REFS = /* @__PURE__ */ new Set(["staging", "homologacao", "develop", "dev"]);
@@ -4309,7 +5238,7 @@ function pickLatestSemverTag(lsRemoteStdout) {
 }
 async function fetchLatestPublicVersion(registryUrl = DEFAULT_REGISTRY_URL) {
   assertSafeRegistrySource(registryUrl, "main");
-  const { stdout } = await execFileAsync2("git", ["ls-remote", "--tags", "--", registryUrl], {
+  const { stdout } = await execFileAsync3("git", ["ls-remote", "--tags", "--", registryUrl], {
     env: gitEnv2(),
     timeout: 2e4
   });
@@ -4339,11 +5268,11 @@ function intervalElapsed(lastCheckedAt, intervalDays) {
   return Date.now() - last >= ms;
 }
 async function loadContextConfig(cwd) {
-  const configPath = path32.join(cwd, ".cursor", "context", "config.json");
+  const configPath = path37.join(cwd, ".cursor", "context", "config.json");
   return readJson(configPath);
 }
 async function stampLastCheckedAt(cwd) {
-  const configPath = path32.join(cwd, ".cursor", "context", "config.json");
+  const configPath = path37.join(cwd, ".cursor", "context", "config.json");
   const existing = await loadContextConfig(cwd) ?? {};
   const prev = existing.updateCheck && typeof existing.updateCheck === "object" ? { ...existing.updateCheck } : {};
   existing.updateCheck = {
@@ -4484,7 +5413,7 @@ async function checkForUpdates(cwd, options = {}) {
 }
 
 // src/commands/update.ts
-var updateCommand = defineCommand13({
+var updateCommand = defineCommand16({
   meta: {
     name: "update",
     description: "Re-apply L0/packs/skills from the registry; never overwrites L3 protected paths. Use --check for notify-only."
@@ -4566,8 +5495,188 @@ var updateCommand = defineCommand13({
   }
 });
 
+// src/commands/validate.ts
+import { readFile as readFile18 } from "fs/promises";
+import path38 from "path";
+import { defineCommand as defineCommand17 } from "citty";
+
+// src/invariants/plan-schema.ts
+var CITE5 = "agent-kit validate plan (.cursor/context/templates/plan.md)";
+function validatePlanFrontmatterText(text) {
+  const warnings = [];
+  const match = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!match?.[1]) {
+    warnings.push({
+      code: "missing-frontmatter",
+      message: "Plan file has no YAML frontmatter block.",
+      cite: CITE5
+    });
+    return warnings;
+  }
+  const block = match[1];
+  if (!/^todos:\s*$/m.test(block) && !/^todos:\s*\[/m.test(block)) {
+    if (!/^todos:/m.test(block)) {
+      warnings.push({
+        code: "missing-todos",
+        message: "Plan frontmatter has no `todos:` key.",
+        cite: CITE5
+      });
+    }
+  }
+  if (!/^name:\s*\S+/m.test(block)) {
+    warnings.push({
+      code: "missing-name",
+      message: "Plan frontmatter has no `name:` key.",
+      cite: CITE5
+    });
+  }
+  const hasTodoItem = /^- id:\s*\S+/m.test(block);
+  if (/^todos:/m.test(block) && !hasTodoItem && !/^todos:\s*\[\s*\]/m.test(block)) {
+    warnings.push({
+      code: "empty-todos",
+      message: "Plan frontmatter `todos:` has no `- id:` items.",
+      cite: CITE5
+    });
+  }
+  return warnings;
+}
+
+// src/commands/validate.ts
+async function resolveEditedPath(cwd, explicit) {
+  if (explicit) {
+    const filePath2 = path38.resolve(cwd, explicit);
+    try {
+      return { filePath: filePath2, content: await readFile18(filePath2, "utf8") };
+    } catch {
+      return null;
+    }
+  }
+  const payload = await readStdinJson();
+  const rel = typeof payload.file_path === "string" && payload.file_path || typeof payload.path === "string" && payload.path || typeof payload.file === "string" && payload.file || "";
+  if (!rel) return null;
+  const filePath = path38.isAbsolute(rel) ? rel : path38.resolve(cwd, rel);
+  try {
+    return { filePath, content: await readFile18(filePath, "utf8") };
+  } catch {
+    return null;
+  }
+}
+function isHandoffPath(filePath) {
+  return filePath.replace(/\\/g, "/").endsWith(".cursor/HANDOFF.md");
+}
+function isPlanPath(filePath) {
+  const norm = filePath.replace(/\\/g, "/");
+  return norm.includes("/.cursor/plans/") && norm.endsWith(".plan.md");
+}
+var validateCommand = defineCommand17({
+  meta: {
+    name: "validate",
+    description: "Advisory validators for HANDOFF / plan frontmatter (afterFileEdit adapter)"
+  },
+  subCommands: {
+    handoff: defineCommand17({
+      meta: { name: "handoff", description: "Validate HANDOFF machine fields" },
+      args: {
+        cwd: { type: "string", default: process.cwd() },
+        file: { type: "string", description: "Path to HANDOFF.md" },
+        json: { type: "boolean", default: true }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const fileArg = typeof args.file === "string" ? args.file : void 0;
+        const filePath = fileArg ? path38.resolve(cwd, fileArg) : path38.join(path38.resolve(cwd), ".cursor", "HANDOFF.md");
+        let content = "";
+        try {
+          content = await readFile18(filePath, "utf8");
+        } catch {
+          console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
+          return;
+        }
+        const warnings = validateHandoffText(content);
+        console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
+      }
+    }),
+    plan: defineCommand17({
+      meta: { name: "plan", description: "Validate plan frontmatter" },
+      args: {
+        cwd: { type: "string", default: process.cwd() },
+        file: { type: "string", description: "Path to *.plan.md" },
+        json: { type: "boolean", default: true }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const fileArg = typeof args.file === "string" ? args.file : void 0;
+        if (!fileArg) {
+          console.log(JSON.stringify({ ok: false, warnings: [{ message: "file required" }] }));
+          process.exitCode = 2;
+          return;
+        }
+        const filePath = path38.resolve(cwd, fileArg);
+        let content = "";
+        try {
+          content = await readFile18(filePath, "utf8");
+        } catch {
+          console.log(JSON.stringify({ ok: true, warnings: [], note: "file missing" }));
+          return;
+        }
+        const warnings = validatePlanFrontmatterText(content);
+        console.log(JSON.stringify({ ok: warnings.length === 0, warnings }));
+      }
+    }),
+    "after-edit": defineCommand17({
+      meta: {
+        name: "after-edit",
+        description: "Advisory afterFileEdit: annotate HANDOFF/plan issues (never block)"
+      },
+      args: {
+        cwd: { type: "string", default: process.cwd() }
+      },
+      async run({ args }) {
+        const cwd = typeof args.cwd === "string" ? args.cwd : process.cwd();
+        const resolved = await resolveEditedPath(path38.resolve(cwd));
+        if (!resolved) {
+          console.log(JSON.stringify({}));
+          return;
+        }
+        const { filePath, content } = resolved;
+        if (isHandoffPath(filePath)) {
+          const warnings = validateHandoffText(content);
+          if (!warnings.length) {
+            console.log(JSON.stringify({}));
+            return;
+          }
+          const msg = warnings.map((w) => w.message).join(" ");
+          console.log(
+            JSON.stringify({
+              user_message: msg,
+              agent_message: `${msg} Cite: agent-kit validate handoff.`
+            })
+          );
+          return;
+        }
+        if (isPlanPath(filePath)) {
+          const warnings = validatePlanFrontmatterText(content);
+          if (!warnings.length) {
+            console.log(JSON.stringify({}));
+            return;
+          }
+          const msg = warnings.map((w) => w.message).join(" ");
+          console.log(
+            JSON.stringify({
+              user_message: msg,
+              agent_message: `${msg} Cite: agent-kit validate plan.`
+            })
+          );
+          return;
+        }
+        console.log(JSON.stringify({}));
+      }
+    })
+  }
+});
+
 // src/index.ts
-var main = defineCommand14({
+var main = defineCommand18({
   meta: {
     name: "agent-kit",
     description: "HITL framework for AI-assisted IDEs"
@@ -4585,7 +5694,11 @@ var main = defineCommand14({
     handoff: handoffCommand,
     "run-plan": runPlanCommand,
     dashboard: dashboardCommand,
-    "dashboard-broadcast": dashboardBroadcastCommand
+    "dashboard-broadcast": dashboardBroadcastCommand,
+    hook: hookCommand,
+    guard: guardCommand,
+    monitors: monitorsCommand,
+    validate: validateCommand
   }
 });
 runMain(main);