agentloopkit 0.1.1 → 0.24.0

package/dist/cli/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/index.ts
-import { Command as Command9 } from "commander";
+import { Command as Command20 } from "commander";
 
 // src/cli/commands/init.ts
 import { Command } from "commander";
@@ -11,8 +11,11 @@ import path6 from "path";
 import { readdir as readdir3 } from "fs/promises";
 
 // src/core/constants.ts
+var PACKAGE_NAME = "agentloopkit";
 var CONFIG_FILE = "agentloop.config.json";
 var AGENTLOOP_DIR = ".agentloop";
+var AGENTLOOP_MANIFEST_FILE = ".agentloop/manifest.json";
+var CURRENT_TEMPLATE_VERSION = 1;
 var AGENTS_FILE = "AGENTS.md";
 var AGENTLOOP_FILE = "AGENTLOOP.md";
 var TEMPLATE_GROUPS = [
@@ -116,9 +119,10 @@ var AgentLoopConfigSchema = z.object({
     includeRollback: z.boolean()
   })
 });
+var CONFIG_SCHEMA_URL = "https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/schema/agentloop.config.schema.json";
 function createDefaultConfig(input = {}) {
   return {
-    $schema: "https://agentloopkit.dev/schema/agentloop.config.schema.json",
+    $schema: CONFIG_SCHEMA_URL,
     version: 1,
     project: {
       name: input.name ?? "",
@@ -236,6 +240,13 @@ function packageManagerRunCommand(manager, scriptName) {
 // src/core/project-detection.ts
 import { readFile as readFile4 } from "fs/promises";
 import path4 from "path";
+var MONOREPO_FILE_MARKERS = [
+  "pnpm-workspace.yaml",
+  "turbo.json",
+  "nx.json",
+  "lerna.json",
+  "rush.json"
+];
 async function readPackageJson(cwd) {
   const filePath = path4.join(cwd, "package.json");
   if (!await pathExists(filePath)) return void 0;
@@ -265,6 +276,19 @@ async function detectProjectType(cwd) {
   if (hasDocs && !hasCode) return "docs-only";
   return "generic";
 }
+async function detectMonorepo(cwd) {
+  const markers = [];
+  const packageJson = await readPackageJson(cwd);
+  if (packageJson?.workspaces) {
+    markers.push("package.json workspaces");
+  }
+  for (const marker of MONOREPO_FILE_MARKERS) {
+    if (await pathExists(path4.join(cwd, marker))) {
+      markers.push(marker);
+    }
+  }
+  return { detected: markers.length > 0, markers };
+}
 async function detectPackageScripts(cwd, packageManager) {
   const packageJson = await readPackageJson(cwd);
   const commands = { test: "", lint: "", typecheck: "", build: "", format: "" };
@@ -289,8 +313,8 @@ function renderTemplateString(template, values) {
 function getTemplateRoot() {
   return fileURLToPath(new URL("../templates", import.meta.url));
 }
-async function readTemplate(relativePath, values = {}) {
-  const raw = await readFile5(path5.join(getTemplateRoot(), relativePath), "utf8");
+async function readTemplate(relativePath2, values = {}) {
+  const raw = await readFile5(path5.join(getTemplateRoot(), relativePath2), "utf8");
   return renderTemplateString(raw, values);
 }
 async function listTemplateFiles() {
@@ -396,6 +420,20 @@ async function initializeAgentLoop(options) {
     await readTemplate("root/agentloop-directory-readme.md", values),
     result
   );
+  await writeGeneratedFile(
+    path6.join(cwd, AGENTLOOP_MANIFEST_FILE),
+    `${JSON.stringify(
+      {
+        version: 1,
+        templateVersion: CURRENT_TEMPLATE_VERSION,
+        generatedBy: PACKAGE_NAME
+      },
+      null,
+      2
+    )}
+`,
+    result
+  );
   await writeGeneratedFile(
     path6.join(cwd, AGENTLOOP_DIR, "tasks", "README.md"),
     await readTemplate("tasks/README.md", values),
@@ -500,14 +538,25 @@ import path7 from "path";
 function relative(cwd, file) {
   return path7.relative(cwd, file).replaceAll(path7.sep, "/");
 }
+function isSemanticRiskCandidate(file) {
+  const extension = path7.extname(file).toLowerCase();
+  if ([".md", ".mdx", ".txt", ".rst", ".adoc"].includes(extension)) return false;
+  return true;
+}
 async function detectRiskFiles(cwd) {
   const files = (await listFilesRecursive(cwd)).map((file) => relative(cwd, file));
-  const includes = (needles) => files.filter((file) => needles.some((needle) => file.toLowerCase().includes(needle)));
+  const semanticIncludes = (needles) => files.filter(
+    (file) => isSemanticRiskCandidate(file) && needles.some((needle) => file.toLowerCase().includes(needle))
+  );
+  const migrationFiles = files.filter((file) => {
+    const normalized = file.toLowerCase();
+    return isSemanticRiskCandidate(file) && (normalized.includes("migrations/") || normalized.includes("/migration/") || path7.basename(normalized).includes("migration"));
+  });
   return {
-    migrations: includes(["migration", "migrations/"]),
-    auth: includes(["auth", "oauth", "session", "passport"]),
-    security: includes(["security", "crypto", "secret", "permission", "policy"]),
-    billing: includes(["billing", "stripe", "payment", "invoice"]),
+    migrations: migrationFiles,
+    auth: semanticIncludes(["auth", "oauth", "session", "passport"]),
+    security: semanticIncludes(["security", "crypto", "secret", "permission", "policy"]),
+    billing: semanticIncludes(["billing", "stripe", "payment", "invoice"]),
     deployment: files.filter(
       (file) => /(^|\/)(Dockerfile|docker-compose|vercel\.json|netlify\.toml|fly\.toml|render\.yaml|\.github\/workflows\/)/i.test(
         file
@@ -523,9 +572,57 @@ async function detectRiskFiles(cwd) {
 }
 
 // src/core/doctor.ts
+var MONOREPO_VERIFICATION_GUIDANCE = "Root checks may not cover every package; add package-specific verification commands to the task contract, such as pnpm --filter <package> test, npm --workspace <package> test, or cd packages/<name> && npm test. AgentLoopKit does not run workspace commands automatically.";
+var MISSING_MANIFEST_MESSAGE = "missing .agentloop/manifest.json; run agentloop init with the current CLI to add missing files without overwriting existing harness files";
+var INVALID_MANIFEST_MESSAGE = "invalid .agentloop/manifest.json; review docs/template-migrations.md and recreate the manifest with agentloop init if needed";
 function check(name, status, message) {
   return { name, status, message };
 }
+var RISK_CATEGORY_LABELS = {
+  migrations: "migrations",
+  auth: "auth",
+  security: "security",
+  billing: "billing",
+  deployment: "deployment",
+  lockfiles: "lockfiles",
+  envFiles: "env files"
+};
+function formatRiskFiles(files) {
+  const preview = files.slice(0, 3).join(", ");
+  const remaining = files.length - 3;
+  return `${files.length} detected: ${preview}${remaining > 0 ? ` (+${remaining} more)` : ""}`;
+}
+async function checkTemplateManifest(cwd) {
+  const manifest = await readTextIfExists(path8.join(cwd, AGENTLOOP_MANIFEST_FILE));
+  if (!manifest) return check("Template manifest", "warn", MISSING_MANIFEST_MESSAGE);
+  try {
+    const parsed = JSON.parse(manifest);
+    if (parsed.version !== 1 || typeof parsed.templateVersion !== "number" || parsed.generatedBy !== "agentloopkit") {
+      return check("Template manifest", "warn", INVALID_MANIFEST_MESSAGE);
+    }
+    if (parsed.templateVersion < CURRENT_TEMPLATE_VERSION) {
+      return check(
+        "Template manifest",
+        "warn",
+        `template version ${parsed.templateVersion} is older than current version ${CURRENT_TEMPLATE_VERSION}; review docs/template-migrations.md and rerun agentloop init to add missing files`
+      );
+    }
+    if (parsed.templateVersion > CURRENT_TEMPLATE_VERSION) {
+      return check(
+        "Template manifest",
+        "warn",
+        `template version ${parsed.templateVersion} is newer than this CLI supports; upgrade AgentLoopKit before changing generated harness files`
+      );
+    }
+    return check(
+      "Template manifest",
+      "pass",
+      `template version ${CURRENT_TEMPLATE_VERSION} is current`
+    );
+  } catch {
+    return check("Template manifest", "warn", INVALID_MANIFEST_MESSAGE);
+  }
+}
 async function runDoctor(options) {
   const cwd = options.cwd;
   const checks = [];
@@ -558,6 +655,7 @@ async function runDoctor(options) {
     const exists = await pathExists(path8.join(cwd, file));
     checks.push(check(file, exists ? "pass" : "warn", exists ? "found" : "missing"));
   }
+  checks.push(await checkTemplateManifest(cwd));
   try {
     await loadAgentLoopConfig(cwd);
     checks.push(check(CONFIG_FILE, "pass", "valid"));
@@ -574,9 +672,17 @@ async function runDoctor(options) {
   }
   const packageManager = await detectPackageManager(cwd);
   const projectType = await detectProjectType(cwd);
+  const monorepo = await detectMonorepo(cwd);
   const commands = await detectPackageScripts(cwd, packageManager);
   checks.push(check("Package manager", "pass", packageManager));
   checks.push(check("Project type", "pass", projectType));
+  checks.push(
+    check(
+      "Monorepo",
+      monorepo.detected ? "warn" : "pass",
+      monorepo.detected ? `workspace markers detected: ${monorepo.markers.join(", ")}. ${MONOREPO_VERIFICATION_GUIDANCE}` : "not detected"
+    )
+  );
   for (const key of ["test", "lint", "typecheck", "build"]) {
     checks.push(
       check(`${key} command`, commands[key] ? "pass" : "warn", commands[key] || "not detected")
@@ -591,6 +697,16 @@ async function runDoctor(options) {
       riskCount ? `${riskCount} risk file(s) detected` : "none detected"
     )
   );
+  for (const [category, files] of Object.entries(risks)) {
+    if (files.length === 0) continue;
+    checks.push(
+      check(
+        `Risk files: ${RISK_CATEGORY_LABELS[category]}`,
+        "warn",
+        formatRiskFiles(files)
+      )
+    );
+  }
   if (!commands.test) {
     checks.push(check("Tests", "warn", "no test command detected"));
   }
@@ -704,16 +820,26 @@ ${input.rollbackNotes || "Document how to revert or disable this change."}
 }
 async function createTaskContractFile(options) {
   const createdDate = options.input.createdDate ?? formatDate();
-  const relativePath = options.out ?? path9.join(options.config.paths.tasksDir, `${createdDate}-${slugify(options.input.title)}.md`);
-  const absolutePath = path9.isAbsolute(relativePath) ? relativePath : path9.join(options.cwd, relativePath);
+  const relativePath2 = options.out ?? path9.join(options.config.paths.tasksDir, `${createdDate}-${slugify(options.input.title)}.md`);
+  const absolutePath = path9.isAbsolute(relativePath2) ? relativePath2 : path9.join(options.cwd, relativePath2);
   const markdown = generateTaskContract({ ...options.input, createdDate });
   await writeTextFile(absolutePath, markdown);
   return { path: absolutePath, markdown };
 }
 
 // src/cli/commands/create-task.ts
-function lines(value) {
-  return value ? value.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+function lines(value, previous) {
+  const current = value ? value.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+  return [...previous, ...current];
+}
+function stringOption(options, ...keys) {
+  for (const key of keys) {
+    if (typeof options[key] === "string") return options[key];
+  }
+  return "";
+}
+function listOption(options, ...keys) {
+  return keys.flatMap((key) => Array.isArray(options[key]) ? options[key] : []);
 }
 async function collectInteractive(initial) {
   const answers = await prompts([
@@ -769,19 +895,28 @@ async function collectInteractive(initial) {
   };
 }
 function createTaskCommand() {
-  return new Command3("create-task").description("Create a task contract for an agentic coding session").option("--title <title>", "task title").option("--type <type>", "task type").option("--out <path>", "output file path").option("--problem <text>", "problem statement").option("--outcome <text>", "desired outcome").option("--constraint <text>", "constraint; repeat or use newlines", lines, []).option("--non-goal <text>", "non-goal; repeat or use newlines", lines, []).option("--acceptance <text>", "acceptance criterion; repeat or use newlines", lines, []).option("--verify-command <command>", "verification command; repeat or use newlines", lines, []).action(async (options) => {
+  return new Command3("create-task").description("Create a task contract for an agentic coding session").option("--title <title>", "task title").option("--type <type>", "task type").option("--out <path>", "output file path").option("--problem <text>", "problem statement").option("--problem-statement <text>", "problem statement").option("--outcome <text>", "desired outcome").option("--desired-outcome <text>", "desired outcome").option("--constraint <text>", "constraint; repeat or use newlines", lines, []).option("--non-goal <text>", "non-goal; repeat or use newlines", lines, []).option("--assumption <text>", "assumption; repeat or use newlines", lines, []).option("--likely-file <path>", "likely file or area; repeat or use newlines", lines, []).option(
+    "--forbidden-file <path>",
+    "file or area not to touch; repeat or use newlines",
+    lines,
+    []
+  ).option("--acceptance <text>", "acceptance criterion; repeat or use newlines", lines, []).option("--verify-command <command>", "verification command; repeat or use newlines", lines, []).option("--verification <command>", "verification command; repeat or use newlines", lines, []).option("--rollback <text>", "rollback notes").option("--json", "print machine-readable output").action(async (options) => {
     const type = typeof options.type === "string" && TASK_TYPES.includes(options.type) ? options.type : void 0;
     const title = typeof options.title === "string" ? options.title : void 0;
     const config = await loadAgentLoopConfig(process.cwd());
     const input = title && type ? {
       title,
       type,
-      problemStatement: String(options.problem ?? ""),
-      desiredOutcome: String(options.outcome ?? ""),
-      constraints: options.constraint,
-      nonGoals: options.nonGoal,
-      acceptanceCriteria: options.acceptance,
-      verificationCommands: options.verifyCommand
+      problemStatement: stringOption(options, "problemStatement", "problem"),
+      desiredOutcome: stringOption(options, "desiredOutcome", "outcome"),
+      constraints: listOption(options, "constraint"),
+      nonGoals: listOption(options, "nonGoal"),
+      assumptions: listOption(options, "assumption"),
+      likelyFiles: listOption(options, "likelyFile"),
+      forbiddenFiles: listOption(options, "forbiddenFile"),
+      acceptanceCriteria: listOption(options, "acceptance"),
+      verificationCommands: listOption(options, "verifyCommand", "verification"),
+      rollbackNotes: stringOption(options, "rollback")
     } : await collectInteractive({ title, type });
     const result = await createTaskContractFile({
       cwd: process.cwd(),
@@ -789,6 +924,10 @@ function createTaskCommand() {
       input,
       out: typeof options.out === "string" ? options.out : void 0
     });
+    if (options.json) {
+      console.log(JSON.stringify({ task: result }, null, 2));
+      return;
+    }
     console.log(`Task contract created: ${result.path}`);
   });
 }
@@ -798,12 +937,40 @@ import { Command as Command4 } from "commander";
 
 // src/core/verification.ts
 import path10 from "path";
+import { readFile as readFile6 } from "fs/promises";
 import { execa as execa2 } from "execa";
 function excerpt(output, limit = 5e3) {
   if (output.length <= limit) return output;
-  return `${output.slice(0, limit)}
+  const headLimit = Math.ceil(limit / 2);
+  const tailLimit = Math.floor(limit / 2);
+  return `${output.slice(0, headLimit)}
+
+[output truncated: showing first ${headLimit} and last ${tailLimit} characters of ${output.length} total]
+
+${output.slice(-tailLimit)}`;
+}
+function failureSnippet(output, maxLines = 12, maxChars = 2e3) {
+  const lines2 = output.split(/\r?\n/).map((line) => line.trimEnd()).filter((line) => line.trim());
+  const tail = lines2.slice(-maxLines).join("\n") || "(no output)";
+  if (tail.length <= maxChars) return tail;
+  return `${tail.slice(0, maxChars)}
+[failure summary truncated]`;
+}
+function renderFailureSummary(results) {
+  const failures = results.filter((result) => !result.passed);
+  if (!failures.length) return "";
+  return `## Failure Summary
+${failures.map(
+    (result) => `### ${result.key}: \`${result.command}\`
+
+- Exit code: ${result.exitCode}
+
+\`\`\`text
+${failureSnippet(result.output)}
+\`\`\``
+  ).join("\n\n")}
 
-[output truncated to ${limit} characters]`;
+`;
 }
 function commandEntries(config, options) {
   const configured = [
@@ -821,9 +988,131 @@ function commandEntries(config, options) {
   }
   return active;
 }
+function singleLine(value, limit = 300) {
+  const clean = value?.replace(/\s+/g, " ").trim();
+  if (!clean) return void 0;
+  return clean.length > limit ? `${clean.slice(0, limit)}...` : clean;
+}
+function withoutTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function isEnabledCi(value) {
+  const clean = value?.trim().toLowerCase();
+  return clean === "true" || clean === "1";
+}
+function detectCiContext(env) {
+  if (env.GITHUB_ACTIONS === "true") {
+    const serverUrl = withoutTrailingSlash(
+      singleLine(env.GITHUB_SERVER_URL) ?? "https://github.com"
+    );
+    const repository = singleLine(env.GITHUB_REPOSITORY);
+    const runId = singleLine(env.GITHUB_RUN_ID);
+    const runUrl = repository && runId ? `${serverUrl}/${repository}/actions/runs/${runId}` : void 0;
+    return {
+      provider: "github-actions",
+      providerName: "GitHub Actions",
+      workflow: singleLine(env.GITHUB_WORKFLOW),
+      event: singleLine(env.GITHUB_EVENT_NAME),
+      ref: singleLine(env.GITHUB_REF),
+      commit: singleLine(env.GITHUB_SHA),
+      runUrl,
+      runAttempt: singleLine(env.GITHUB_RUN_ATTEMPT)
+    };
+  }
+  if (env.GITLAB_CI === "true") {
+    return {
+      provider: "gitlab-ci",
+      providerName: "GitLab CI",
+      workflow: singleLine(env.CI_PROJECT_PATH),
+      event: singleLine(env.CI_PIPELINE_SOURCE),
+      ref: singleLine(env.CI_COMMIT_REF_NAME),
+      commit: singleLine(env.CI_COMMIT_SHA),
+      runUrl: singleLine(env.CI_PIPELINE_URL)
+    };
+  }
+  if (env.BUILDKITE === "true") {
+    return {
+      provider: "buildkite",
+      providerName: "Buildkite",
+      workflow: singleLine(env.BUILDKITE_PIPELINE_SLUG),
+      event: singleLine(env.BUILDKITE_SOURCE),
+      ref: singleLine(env.BUILDKITE_BRANCH),
+      commit: singleLine(env.BUILDKITE_COMMIT),
+      runUrl: singleLine(env.BUILDKITE_BUILD_URL)
+    };
+  }
+  if (isEnabledCi(env.CI)) {
+    return {
+      provider: "generic-ci",
+      providerName: "Generic CI"
+    };
+  }
+  return void 0;
+}
+function renderCiContext(ciContext) {
+  if (!ciContext) return "";
+  const lines2 = [`- Provider: ${ciContext.providerName}`];
+  if (ciContext.workflow) lines2.push(`- Workflow: ${ciContext.workflow}`);
+  if (ciContext.event) lines2.push(`- Event: ${ciContext.event}`);
+  if (ciContext.ref) lines2.push(`- Ref: ${ciContext.ref}`);
+  if (ciContext.commit) lines2.push(`- Commit: ${ciContext.commit}`);
+  if (ciContext.runUrl) lines2.push(`- Run URL: ${ciContext.runUrl}`);
+  if (ciContext.runAttempt) lines2.push(`- Run attempt: ${ciContext.runAttempt}`);
+  return `## CI Context
+${lines2.join("\n")}
+
+`;
+}
+function parseTaskMetadata(markdown) {
+  const lines2 = markdown.split(/\r?\n/);
+  return {
+    title: lines2.find((line) => line.startsWith("# "))?.replace(/^#\s+/, "").trim(),
+    type: lines2.find((line) => line.startsWith("- Task type:"))?.replace("- Task type:", "").trim(),
+    status: lines2.find((line) => line.startsWith("- Status:"))?.replace("- Status:", "").trim()
+  };
+}
+function isMarkdownTaskPath(taskPath) {
+  const normalized = taskPath.replace(/\\/g, "/").toLowerCase();
+  const segments = normalized.split("/").filter(Boolean);
+  return normalized.endsWith(".md") && !segments.some((segment) => segment === ".env" || segment.startsWith(".env."));
+}
+async function renderTaskContext(cwd, taskPath) {
+  if (!taskPath?.trim()) return "";
+  const cleanPath = taskPath.trim();
+  if (!isMarkdownTaskPath(cleanPath)) {
+    return `## Task Context
+- Path: ${cleanPath}
+- Status: unavailable
+- Note: Task path must point to a Markdown task contract.
+
+`;
+  }
+  const absolutePath = path10.isAbsolute(cleanPath) ? cleanPath : path10.join(cwd, cleanPath);
+  try {
+    const markdown = await readFile6(absolutePath, "utf8");
+    const metadata = parseTaskMetadata(markdown);
+    const lines2 = [`- Path: ${cleanPath}`];
+    if (metadata.title) lines2.push(`- Title: ${metadata.title}`);
+    if (metadata.type) lines2.push(`- Task type: ${metadata.type}`);
+    if (metadata.status) lines2.push(`- Status: ${metadata.status}`);
+    return `## Task Context
+${lines2.join("\n")}
+
+`;
+  } catch {
+    return `## Task Context
+- Path: ${cleanPath}
+- Status: unavailable
+- Note: Task file could not be read.
+
+`;
+  }
+}
 async function runVerification(options) {
   const timestamp = options.reportTimestamp ?? formatTimestamp();
   const nowIso = options.nowIso ?? (/* @__PURE__ */ new Date()).toISOString();
+  const env = options.env ?? process.env;
+  const ciContext = detectCiContext(env);
   const commands = commandEntries(options.config, options);
   const notRun = [
     ...["test", "lint", "typecheck", "build"].filter((key) => {
@@ -838,7 +1127,7 @@ async function runVerification(options) {
       shell: true,
       all: true,
       reject: false,
-      env: { ...process.env, FORCE_COLOR: "0" }
+      env: { ...env, FORCE_COLOR: "0" }
     });
     results.push({
       key,
@@ -848,7 +1137,7 @@ async function runVerification(options) {
       output: result.all ?? result.stdout ?? result.stderr ?? ""
     });
   }
-  const overallStatus = results.length === 0 ? "not-run" : results.every((result) => result.passed) ? "pass" : "fail";
+  const overallStatus2 = results.length === 0 ? "not-run" : results.every((result) => result.passed) ? "pass" : "fail";
   const reportPath = path10.join(
     options.cwd,
     options.config.paths.reportsDir,
@@ -857,6 +1146,7 @@ async function runVerification(options) {
   const branch = await getGitBranch(options.cwd);
   const commit = await getGitCommit(options.cwd);
   const status = await getGitStatus(options.cwd);
+  const taskContext = await renderTaskContext(options.cwd, options.taskPath);
   const markdown = `# Verification Report
 
 - Timestamp: ${nowIso}
@@ -864,8 +1154,11 @@ async function runVerification(options) {
 - Git branch: ${branch || "not available"}
 - Git commit: ${commit || "not available"}
 - Working tree: ${status.trim() ? "dirty" : "clean or unavailable"}
-- Overall status: ${overallStatus}
+- Overall status: ${overallStatus2}
 
+${renderCiContext(ciContext)}
+${taskContext}
+${renderFailureSummary(results)}
 ## Commands Run
 ${results.length === 0 ? "No verification commands were configured or selected." : results.map(
     (result) => `### ${result.key}: \`${result.command}\`
@@ -882,10 +1175,10 @@ ${excerpt(result.output || "(no output)")}
 ${notRun.length ? notRun.map((item) => `- ${item}`).join("\n") : "- Nothing skipped."}
 
 ## Recommended Next Actions
-${overallStatus === "pass" ? "- Review the diff and prepare a handoff summary." : overallStatus === "fail" ? "- Fix failing commands before claiming completion." : "- Add test, lint, typecheck, or build commands to agentloop.config.json."}
+${overallStatus2 === "pass" ? "- Review the diff and prepare a handoff summary." : overallStatus2 === "fail" ? "- Fix failing commands before claiming completion." : "- Add test, lint, typecheck, or build commands to agentloop.config.json."}
 `;
   await writeTextFile(reportPath, markdown);
-  return { overallStatus, commands: results, notRun, markdown, reportPath };
+  return { overallStatus: overallStatus2, commands: results, notRun, ciContext, markdown, reportPath };
 }
 
 // src/cli/commands/verify.ts
@@ -899,6 +1192,7 @@ function verifyCommand() {
     const result = await runVerification({
       cwd: process.cwd(),
       config,
+      taskPath: typeof options.task === "string" ? options.task : void 0,
       skip: {
         build: options.build === false,
         test: options.test === false,
@@ -921,13 +1215,302 @@ Overall status: ${result.overallStatus}`
 import { Command as Command5 } from "commander";
 
 // src/core/pr-summary.ts
+import path13 from "path";
+import { readFile as readFile8 } from "fs/promises";
+
+// src/core/artifacts.ts
 import path11 from "path";
-import { readdir as readdir4, readFile as readFile6 } from "fs/promises";
+import { readdir as readdir4, stat as stat2 } from "fs/promises";
+var verificationReportPattern = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-verification-report\.md$/;
+var prSummaryPattern = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-pr-summary\.md$/;
+var ciSummaryPattern = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-ci-summary\.md$/;
+async function latestMarkdownFile(dir, options = {}) {
+  if (!await pathExists(dir)) return void 0;
+  const entries = await Promise.all(
+    (await readdir4(dir, { withFileTypes: true })).filter(
+      (entry) => entry.isFile() && entry.name.endsWith(".md") && entry.name.toLowerCase() !== "readme.md"
+    ).filter((entry) => !options.pattern || options.pattern.test(entry.name)).map(async (entry) => {
+      const filePath = path11.join(dir, entry.name);
+      const fileStat = await stat2(filePath);
+      return { filePath, name: entry.name, mtimeMs: fileStat.mtimeMs };
+    })
+  );
+  entries.sort((left, right) => {
+    if (left.mtimeMs !== right.mtimeMs) return left.mtimeMs - right.mtimeMs;
+    return left.name.localeCompare(right.name);
+  });
+  return entries.at(-1)?.filePath;
+}
+
+// src/core/task-state.ts
+import path12 from "path";
+import { mkdir as mkdir2, readdir as readdir5, readFile as readFile7, rename, rm, stat as stat3 } from "fs/promises";
+var TASK_STATUSES = ["proposed", "in-progress", "blocked", "review", "done"];
+function statePath(cwd, config) {
+  return path12.join(cwd, config.paths.agentloopDir, "state.json");
+}
+function toStoredPath(cwd, absolutePath) {
+  return path12.relative(cwd, absolutePath).split(path12.sep).join("/");
+}
+function isInside(parent, child) {
+  const relative2 = path12.relative(parent, child);
+  return relative2 === "" || !relative2.startsWith("..") && !path12.isAbsolute(relative2);
+}
+function tasksRoot(cwd, config) {
+  return path12.resolve(cwd, config.paths.tasksDir);
+}
+async function readState(cwd, config) {
+  const filePath = statePath(cwd, config);
+  if (!await pathExists(filePath)) return { version: 1 };
+  const raw = await readFile7(filePath, "utf8");
+  try {
+    const parsed = JSON.parse(raw);
+    return {
+      version: 1,
+      activeTaskPath: typeof parsed.activeTaskPath === "string" && parsed.activeTaskPath.trim() ? parsed.activeTaskPath : void 0
+    };
+  } catch {
+    return { version: 1 };
+  }
+}
+async function writeState(cwd, config, state) {
+  await writeTextFile(statePath(cwd, config), `${JSON.stringify(state, null, 2)}
+`);
+}
+async function resolveTaskPath(options) {
+  const absolutePath = path12.isAbsolute(options.taskPath) ? path12.resolve(options.taskPath) : path12.resolve(options.cwd, options.taskPath);
+  const root = tasksRoot(options.cwd, options.config);
+  const displayRoot = options.config.paths.tasksDir;
+  if (!isInside(root, absolutePath)) {
+    if (!options.strict) return void 0;
+    throw new AgentLoopError(`Active task must be inside ${displayRoot}.`);
+  }
+  if (!absolutePath.endsWith(".md")) {
+    if (!options.strict) return void 0;
+    throw new AgentLoopError("Active task must be a Markdown file.");
+  }
+  const fileStat = await stat3(absolutePath).catch(() => void 0);
+  if (!fileStat?.isFile()) {
+    if (!options.strict) return void 0;
+    throw new AgentLoopError(`Task contract not found: ${options.taskPath}`);
+  }
+  return absolutePath;
+}
+function extractHeading(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function extractTaskStatus(markdown) {
+  return markdown.match(/^- Status:\s*(.+)$/im)?.[1]?.trim() || "unknown";
+}
+function parseTaskStatus(status) {
+  const clean = status.trim().toLowerCase();
+  if (TASK_STATUSES.includes(clean)) return clean;
+  throw new AgentLoopError(
+    `Unsupported task status "${status}". Use one of: ${TASK_STATUSES.join(", ")}.`
+  );
+}
+async function readTaskMetadata(cwd, filePath) {
+  const markdown = await readFile7(filePath, "utf8");
+  return {
+    path: toStoredPath(cwd, filePath),
+    title: extractHeading(markdown, path12.basename(filePath, ".md")),
+    status: extractTaskStatus(markdown)
+  };
+}
+async function readTaskContract(options) {
+  const absolutePath = await resolveTaskPath({ ...options, strict: true });
+  if (!absolutePath) throw new AgentLoopError(`Task contract not found: ${options.taskPath}`);
+  const content = await readFile7(absolutePath, "utf8");
+  return {
+    ...await readTaskMetadata(options.cwd, absolutePath),
+    content
+  };
+}
+async function setActiveTask(options) {
+  const absolutePath = await resolveTaskPath({ ...options, strict: true });
+  if (!absolutePath) throw new AgentLoopError(`Task contract not found: ${options.taskPath}`);
+  const activeTaskPath = toStoredPath(options.cwd, absolutePath);
+  await writeState(options.cwd, options.config, { version: 1, activeTaskPath });
+  return readTaskMetadata(options.cwd, absolutePath);
+}
+async function updateTaskStatus(options) {
+  const absolutePath = await resolveTaskPath({ ...options, strict: true });
+  if (!absolutePath) throw new AgentLoopError(`Task contract not found: ${options.taskPath}`);
+  const status = parseTaskStatus(options.status);
+  const content = await readFile7(absolutePath, "utf8");
+  if (!/^- Status:\s*.+$/im.test(content)) {
+    throw new AgentLoopError(`Task contract does not contain a Status line: ${options.taskPath}`);
+  }
+  await writeTextFile(absolutePath, content.replace(/^(- Status:\s*).+$/im, `$1${status}`));
+  return readTaskMetadata(options.cwd, absolutePath);
+}
+async function archiveTask(options) {
+  const absolutePath = await resolveTaskPath({ ...options, strict: true });
+  if (!absolutePath) throw new AgentLoopError(`Task contract not found: ${options.taskPath}`);
+  const root = tasksRoot(options.cwd, options.config);
+  const archiveRoot = path12.join(root, "archive");
+  if (path12.dirname(absolutePath) === archiveRoot) {
+    throw new AgentLoopError(`Task contract is already archived: ${options.taskPath}`);
+  }
+  const destinationPath = path12.join(archiveRoot, path12.basename(absolutePath));
+  if (await pathExists(destinationPath)) {
+    throw new AgentLoopError(
+      `Archived task already exists: ${toStoredPath(options.cwd, destinationPath)}`
+    );
+  }
+  const previousPath = toStoredPath(options.cwd, absolutePath);
+  const activeTaskPath = await getActiveTaskPath(options);
+  await mkdir2(archiveRoot, { recursive: true });
+  await rename(absolutePath, destinationPath);
+  if (activeTaskPath === absolutePath) {
+    await clearActiveTask(options);
+  }
+  return {
+    ...await readTaskMetadata(options.cwd, destinationPath),
+    previousPath
+  };
+}
+async function getActiveTaskPath(options) {
+  const state = await readState(options.cwd, options.config);
+  if (!state.activeTaskPath) return void 0;
+  return resolveTaskPath({
+    cwd: options.cwd,
+    config: options.config,
+    taskPath: state.activeTaskPath,
+    strict: false
+  });
+}
+async function getActiveTask(options) {
+  const activeTaskPath = await getActiveTaskPath(options);
+  return activeTaskPath ? readTaskMetadata(options.cwd, activeTaskPath) : void 0;
+}
+async function clearActiveTask(options) {
+  await rm(statePath(options.cwd, options.config), { force: true });
+}
+async function listTasks(options) {
+  const root = tasksRoot(options.cwd, options.config);
+  const entries = await readdir5(root, { withFileTypes: true }).catch(() => []);
+  const activeTaskPath = await getActiveTaskPath(options);
+  const tasks = await Promise.all(
+    entries.filter((entry) => entry.isFile()).filter((entry) => entry.name.endsWith(".md") && entry.name !== "README.md").map(async (entry) => {
+      const filePath = path12.join(root, entry.name);
+      const [metadata, fileStat] = await Promise.all([
+        readTaskMetadata(options.cwd, filePath),
+        stat3(filePath)
+      ]);
+      return {
+        ...metadata,
+        active: activeTaskPath === filePath,
+        modifiedAt: fileStat.mtime.toISOString(),
+        modifiedMs: fileStat.mtimeMs
+      };
+    })
+  );
+  return tasks.sort((left, right) => {
+    if (left.active !== right.active) return left.active ? -1 : 1;
+    if (left.modifiedMs !== right.modifiedMs) return right.modifiedMs - left.modifiedMs;
+    return left.path.localeCompare(right.path);
+  }).map((task) => ({
+    path: task.path,
+    title: task.title,
+    status: task.status,
+    active: task.active,
+    modifiedAt: task.modifiedAt
+  }));
+}
+
+// src/core/pr-summary.ts
+var CHANGE_AREAS = [
+  {
+    key: "risk",
+    title: "Risk-Sensitive",
+    matches: (filePath) => /(^|\/)(migrations?|migration|auth|security|billing|deploy|deployment)(\/|\.|-|_|$)/.test(
+      filePath
+    ) || /(^|\/)\.env(\.|$)/.test(filePath) || /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|Cargo\.lock|poetry\.lock)$/.test(
+      filePath
+    )
+  },
+  { key: "source", title: "Source", matches: (filePath) => /^src\//.test(filePath) },
+  {
+    key: "tests",
+    title: "Tests",
+    matches: (filePath) => /(^|\/)(tests?|__tests__)\//.test(filePath) || /\.(test|spec)\.[cm]?[jt]sx?$/.test(filePath)
+  },
+  {
+    key: "agentloop",
+    title: "AgentLoop",
+    matches: (filePath) => /^\.agentloop\//.test(filePath) || /(^|\/)(AGENTS\.md|AGENTLOOP\.md|agentloop\.config\.json)$/.test(filePath)
+  },
+  {
+    key: "docs",
+    title: "Documentation",
+    matches: (filePath) => /(^|\/)docs\//.test(filePath) || /(^|\/)(README|CHANGELOG|CONTRIBUTING|CODE_OF_CONDUCT|SECURITY|ROADMAP|DECISIONS)\.md$/i.test(
+      filePath
+    ) || /\.mdx?$/.test(filePath)
+  },
+  {
+    key: "ci",
+    title: "CI / Automation",
+    matches: (filePath) => /^\.github\//.test(filePath) || /^scripts\//.test(filePath) || /(^|\/)(Dockerfile|Makefile)$/.test(filePath)
+  },
+  {
+    key: "config",
+    title: "Config / Package",
+    matches: (filePath) => /(^|\/)(package\.json|tsconfig\.json|tsup\.config\.ts|vitest\.config\.ts|eslint\.config\.js|prettier\.config\.[cm]?js|pnpm-workspace\.yaml)$/.test(
+      filePath
+    ) || /^schema\//.test(filePath)
+  }
+];
 function extractLine(markdown, pattern, fallback) {
   if (!markdown) return fallback;
   const match = markdown.match(pattern);
   return match?.[1]?.trim() || fallback;
 }
+function classifyChangedFiles(changedFiles) {
+  const areas = CHANGE_AREAS.map((area) => ({
+    key: area.key,
+    title: area.title,
+    files: []
+  }));
+  const other = { key: "other", title: "Other", files: [] };
+  for (const file of changedFiles) {
+    const normalizedPath = file.path.replace(/\\/g, "/");
+    const areaIndex = CHANGE_AREAS.findIndex((area) => area.matches(normalizedPath));
+    if (areaIndex === -1) other.files.push(file);
+    else areas[areaIndex]?.files.push(file);
+  }
+  return [...areas.filter((area) => area.files.length), ...other.files.length ? [other] : []];
+}
+function renderChangeAreas(changedFiles) {
+  if (!changedFiles.length) return "- No changed files detected.";
+  const areas = classifyChangedFiles(changedFiles);
+  return areas.map((area) => {
+    return `### ${area.title}
+${area.files.map((file) => `- ${file.status} \`${file.path}\``).join("\n")}`;
+  }).join("\n\n");
+}
+function renderReviewFocus(changedFiles) {
+  if (!changedFiles.length) return "- No changed files detected.";
+  const keys = new Set(classifyChangedFiles(changedFiles).map((area) => area.key));
+  const lines2 = [];
+  if (keys.has("source")) lines2.push("- Review source changes for behavior and public API impact.");
+  if (keys.has("tests")) lines2.push("- Check tests cover the changed behavior.");
+  if (keys.has("docs")) lines2.push("- Check docs match the implemented command behavior.");
+  if (keys.has("ci"))
+    lines2.push("- Review CI or automation changes for permissions and secret handling.");
+  if (keys.has("config"))
+    lines2.push("- Review package and config changes for install, build, and publish impact.");
+  if (keys.has("agentloop"))
+    lines2.push(
+      "- Review AgentLoop artifacts for accurate task, verification, and handoff evidence."
+    );
+  if (keys.has("risk"))
+    lines2.push(
+      "- Review risk-sensitive paths such as migrations, auth, security, billing, env, deployment, and lockfiles with extra care."
+    );
+  if (keys.has("other")) lines2.push("- Review uncategorized files for ownership and scope.");
+  return lines2.join("\n");
+}
 function generatePrSummary(input) {
   const taskTitle = extractLine(input.taskMarkdown, /^#\s+(.+)$/m, "No task contract found.");
   const verification = extractLine(
@@ -948,12 +1531,18 @@ This summary was generated deterministically from git status, the latest task co
 ## Changed Files
 ${input.changedFiles.length ? input.changedFiles.map((file) => `- ${file.status} \`${file.path}\``).join("\n") : "- No changed files detected."}
 
+## Change Areas
+${renderChangeAreas(input.changedFiles)}
+
 ## Diff Stats
 ${input.diffStat?.trim() || "No diff stats available."}
 
 ## Behaviour Changed
 - Review changed files and task contract to confirm intended behavior.
 
+## Review Focus
+${renderReviewFocus(input.changedFiles)}
+
 ## Verification Performed
 - ${verificationLine}
 
@@ -977,23 +1566,17 @@ ${input.diffStat?.trim() || "No diff stats available."}
 `;
   return { markdown };
 }
-async function latestMarkdownFile(dir) {
-  if (!await pathExists(dir)) return void 0;
-  const entries = (await readdir4(dir, { withFileTypes: true })).filter(
-    (entry) => entry.isFile() && entry.name.endsWith(".md") && entry.name.toLowerCase() !== "readme.md"
-  ).map((entry) => entry.name).sort();
-  const latest = entries.at(-1);
-  return latest ? path11.join(dir, latest) : void 0;
-}
 async function summarizeRepository(options) {
   const timestamp = options.timestamp ?? formatTimestamp();
   const status = await getGitStatus(options.cwd);
   const changedFiles = await parseGitStatus(status);
   const diffStat = await getGitDiffStat(options.cwd);
-  const taskPath = options.taskPath ?? await latestMarkdownFile(path11.join(options.cwd, options.config.paths.tasksDir));
-  const reportPath = options.reportPath ?? await latestMarkdownFile(path11.join(options.cwd, options.config.paths.reportsDir));
-  const taskMarkdown = taskPath && await pathExists(taskPath) ? await readFile6(taskPath, "utf8") : void 0;
-  const verificationMarkdown = reportPath && await pathExists(reportPath) ? await readFile6(reportPath, "utf8") : void 0;
+  const taskPath = options.taskPath ?? await getActiveTaskPath({ cwd: options.cwd, config: options.config }) ?? await latestMarkdownFile(path13.join(options.cwd, options.config.paths.tasksDir));
+  const reportPath = options.reportPath ?? await latestMarkdownFile(path13.join(options.cwd, options.config.paths.reportsDir), {
+    pattern: verificationReportPattern
+  });
+  const taskMarkdown = taskPath && await pathExists(taskPath) ? await readFile8(taskPath, "utf8") : void 0;
+  const verificationMarkdown = reportPath && await pathExists(reportPath) ? await readFile8(reportPath, "utf8") : void 0;
   const summary = generatePrSummary({
     timestamp,
     status,
@@ -1002,7 +1585,7 @@ async function summarizeRepository(options) {
     verificationMarkdown,
     diffStat
   });
-  const outPath = path11.join(
+  const outPath = path13.join(
     options.cwd,
     options.config.paths.handoffsDir,
     `${timestamp}-pr-summary.md`
@@ -1012,31 +1595,36 @@ async function summarizeRepository(options) {
 }
 
 // src/cli/commands/summarize.ts
-function summarizeCommand() {
-  return new Command5("summarize").description("Generate a deterministic PR/reviewer summary").option("--task <path>", "task contract path").option("--report <path>", "verification report path").option("--format <format>", "markdown or json", "markdown").option("--write", "write summary to .agentloop/handoffs").option("--json", "print JSON output").action(async (options) => {
-    const config = await loadAgentLoopConfig(process.cwd());
-    const result = await summarizeRepository({
-      cwd: process.cwd(),
-      config,
-      taskPath: typeof options.task === "string" ? options.task : void 0,
-      reportPath: typeof options.report === "string" ? options.report : void 0,
-      write: Boolean(options.write)
-    });
-    if (options.json || options.format === "json") {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      console.log(result.markdown);
-      if (options.write) console.log(`
-Summary written: ${result.outPath}`);
-    }
+async function runSummaryCommand(options, defaultWrite) {
+  const config = await loadAgentLoopConfig(process.cwd());
+  const writeOption = typeof options.write === "boolean" ? options.write : defaultWrite;
+  const result = await summarizeRepository({
+    cwd: process.cwd(),
+    config,
+    taskPath: typeof options.task === "string" ? options.task : void 0,
+    reportPath: typeof options.report === "string" ? options.report : void 0,
+    write: writeOption
   });
+  if (options.json || options.format === "json") {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(result.markdown);
+    if (writeOption) console.log(`
+Summary written: ${result.outPath}`);
+  }
+}
+function summarizeCommand() {
+  return new Command5("summarize").description("Generate a deterministic PR/reviewer summary").option("--task <path>", "task contract path").option("--report <path>", "verification report path").option("--format <format>", "markdown or json", "markdown").option("--write", "write summary to .agentloop/handoffs").option("--json", "print JSON output").action((options) => runSummaryCommand(options, false));
+}
+function handoffCommand() {
+  return new Command5("handoff").description("Generate and write a deterministic reviewer handoff").option("--task <path>", "task contract path").option("--report <path>", "verification report path").option("--format <format>", "markdown or json", "markdown").option("--no-write", "print handoff without writing a file").option("--json", "print JSON output").action((options) => runSummaryCommand(options, true));
 }
 
 // src/cli/commands/install-agent.ts
 import { Command as Command6 } from "commander";
 
 // src/core/agent-installation.ts
-import path12 from "path";
+import path14 from "path";
 function isSupportedAgent(value) {
   return SUPPORTED_AGENTS.includes(value);
 }
@@ -1050,12 +1638,12 @@ var displayNames = {
   generic: "Generic Coding Agent"
 };
 async function installAgentInstructions(options) {
-  const agentFilePath = path12.join(options.cwd, ".agentloop", "agents", `${options.agent}.md`);
+  const agentFilePath = path14.join(options.cwd, ".agentloop", "agents", `${options.agent}.md`);
   const content = await readTemplate(`agents/${options.agent}.md`, {
     agentName: displayNames[options.agent]
   });
   await writeTextFile(agentFilePath, content);
-  const agentsPath = path12.join(options.cwd, "AGENTS.md");
+  const agentsPath = path14.join(options.cwd, "AGENTS.md");
   const existing = await readTextIfExists(agentsPath);
   const marker = `<!-- agentloopkit-agent:${options.agent} -->`;
   if (!existing.includes(marker)) {
@@ -1119,22 +1707,2079 @@ function listTemplatesCommand() {
 
 // src/cli/commands/version.ts
 import { Command as Command8 } from "commander";
+
+// src/core/version.ts
+import { readFileSync } from "fs";
+function getPackageVersion() {
+  const packageJsonUrl = new URL("../../package.json", import.meta.url);
+  const packageJson = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+  return packageJson.version;
+}
+
+// src/cli/commands/version.ts
 function versionCommand() {
   return new Command8("version").description("Print CLI version").action(() => {
-    console.log("0.1.0");
+    console.log(getPackageVersion());
+  });
+}
+
+// src/cli/commands/status.ts
+import { Command as Command9 } from "commander";
+
+// src/core/status.ts
+import path15 from "path";
+import { readFile as readFile9, stat as stat4 } from "fs/promises";
+function extractHeading2(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function extractTaskStatus2(markdown) {
+  return markdown.match(/^- Status:\s*(.+)$/im)?.[1]?.trim() || "unknown";
+}
+function extractOverallStatus(markdown) {
+  return markdown.match(/Overall status:\s*([a-z-]+)/i)?.[1]?.trim() || "unknown";
+}
+async function readTask(cwd, filePath) {
+  if (!filePath) return void 0;
+  const markdown = await readFile9(filePath, "utf8");
+  const fileStat = await stat4(filePath);
+  return {
+    path: path15.relative(cwd, filePath),
+    title: extractHeading2(markdown, path15.basename(filePath, ".md")),
+    status: extractTaskStatus2(markdown),
+    modifiedAtMs: fileStat.mtimeMs
+  };
+}
+async function readReport(cwd, filePath) {
+  if (!filePath) return void 0;
+  const markdown = await readFile9(filePath, "utf8");
+  const fileStat = await stat4(filePath);
+  return {
+    path: path15.relative(cwd, filePath),
+    title: extractHeading2(markdown, path15.basename(filePath, ".md")),
+    overallStatus: extractOverallStatus(markdown),
+    modifiedAtMs: fileStat.mtimeMs
+  };
+}
+function stripTaskTimestamp(task) {
+  if (!task) return void 0;
+  return {
+    path: task.path,
+    title: task.title,
+    status: task.status
+  };
+}
+function stripReportTimestamp(report) {
+  if (!report) return void 0;
+  return {
+    path: report.path,
+    title: report.title,
+    overallStatus: report.overallStatus
+  };
+}
+function isPostVerificationTaskState(task) {
+  const status = task?.status.trim().toLowerCase();
+  return status === "review" || status === "done";
+}
+function chooseNextAction(input) {
+  if (!input.activeTask) {
+    return {
+      command: "agentloop create-task",
+      reason: "No task contract was found."
+    };
+  }
+  if (!input.latestReport) {
+    return {
+      command: "agentloop verify",
+      reason: "A task exists, but no verification report was found."
+    };
+  }
+  if (input.latestReport.overallStatus === "fail") {
+    return {
+      command: "agentloop verify",
+      reason: "The latest verification report failed. Fix the failures and rerun verification."
+    };
+  }
+  if (input.dirty) {
+    return {
+      command: "agentloop handoff",
+      reason: "Task and verification evidence exist, and the working tree has changes."
+    };
+  }
+  return {
+    command: "agentloop create-task",
+    reason: "The repo is clean. Start the next task contract when ready."
+  };
+}
+function formatList(values) {
+  return values.length ? values.join(", ") : "none";
+}
+function renderMarkdown(result) {
+  const gitLine = result.git.isRepository ? `${result.git.branch || "unknown branch"}${result.git.commit ? ` @ ${result.git.commit}` : ""}` : "not inside a git repository";
+  const workingTree = result.workingTree.dirty ? `dirty (${result.workingTree.changedFileCount} changed file(s))` : "clean";
+  const activeTask = result.activeTask ? `${result.activeTask.title} (${result.activeTask.status}) - ${result.activeTask.path}` : "No task contract found.";
+  const latestReport = result.latestReport ? `${result.latestReport.overallStatus} - ${result.latestReport.path}` : "No verification report found.";
+  return `# AgentLoopKit Status
+
+- Project: ${result.project.name || "unnamed"} (${result.project.type})
+- Package manager: ${result.project.packageManager}
+- Git: ${gitLine}
+- Working tree: ${workingTree}
+- Active task: ${activeTask}
+- Latest verification: ${latestReport}
+- Configured commands: ${formatList(result.commands.configured)}
+- Missing commands: ${formatList(result.commands.missing)}
+
+## Next Action
+
+Run \`${result.nextAction.command}\`.
+
+${result.nextAction.reason}
+`;
+}
+async function getAgentLoopStatus(options) {
+  const inGit = await isInsideGitRepo(options.cwd);
+  const rawStatus = inGit ? await getGitStatus(options.cwd) : "";
+  const changedFiles = await parseGitStatus(rawStatus);
+  const timestampedTask = await readTask(
+    options.cwd,
+    await getActiveTaskPath(options) ?? await latestMarkdownFile(path15.join(options.cwd, options.config.paths.tasksDir))
+  );
+  const timestampedReport = await readReport(
+    options.cwd,
+    await latestMarkdownFile(path15.join(options.cwd, options.config.paths.reportsDir), {
+      pattern: verificationReportPattern
+    })
+  );
+  const currentReport = timestampedTask && timestampedReport && timestampedReport.modifiedAtMs < timestampedTask.modifiedAtMs && !isPostVerificationTaskState(timestampedTask) ? void 0 : timestampedReport;
+  const activeTask = stripTaskTimestamp(timestampedTask);
+  const latestReport = stripReportTimestamp(currentReport);
+  const configured = DEFAULT_COMMAND_KEYS.filter((key) => options.config.commands[key]);
+  const missing = DEFAULT_COMMAND_KEYS.filter((key) => !options.config.commands[key]);
+  const nextAction = chooseNextAction({
+    activeTask,
+    latestReport,
+    dirty: changedFiles.length > 0
+  });
+  const withoutMarkdown = {
+    project: options.config.project,
+    git: {
+      isRepository: inGit,
+      branch: inGit ? await getGitBranch(options.cwd) : "",
+      commit: inGit ? await getGitCommit(options.cwd) : ""
+    },
+    workingTree: {
+      dirty: changedFiles.length > 0,
+      changedFileCount: changedFiles.length,
+      changedFiles
+    },
+    activeTask,
+    latestReport,
+    commands: {
+      configured,
+      missing
+    },
+    nextAction
+  };
+  return {
+    ...withoutMarkdown,
+    markdown: renderMarkdown(withoutMarkdown)
+  };
+}
+
+// src/cli/commands/status.ts
+function statusCommand() {
+  return new Command9("status").description("Show active task, latest verification, dirty files, and next action").option("--json", "print machine-readable output").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const result = await getAgentLoopStatus({ cwd: process.cwd(), config });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(result.markdown);
+    }
+  });
+}
+
+// src/cli/commands/next.ts
+import { Command as Command10 } from "commander";
+function formatTask(result) {
+  if (!result.activeTask) return "none";
+  return `${result.activeTask.title} (${result.activeTask.status}) - ${result.activeTask.path}`;
+}
+function formatReport(result) {
+  if (!result.latestReport) return "none";
+  return `${result.latestReport.overallStatus} - ${result.latestReport.path}`;
+}
+function toNextActionResult(status) {
+  return {
+    command: status.nextAction.command,
+    reason: status.nextAction.reason,
+    activeTask: status.activeTask ?? null,
+    latestReport: status.latestReport ?? null,
+    workingTree: {
+      dirty: status.workingTree.dirty,
+      changedFileCount: status.workingTree.changedFileCount
+    },
+    commands: status.commands
+  };
+}
+function renderNextAction(result) {
+  const workingTree = result.workingTree.dirty ? `dirty (${result.workingTree.changedFileCount} changed file(s))` : "clean";
+  return `# AgentLoopKit Next Action
+
+Run \`${result.command}\`.
+
+${result.reason}
+
+- Active task: ${formatTask(result)}
+- Latest verification: ${formatReport(result)}
+- Working tree: ${workingTree}
+`;
+}
+function nextCommand() {
+  return new Command10("next").description("Show the next recommended loop action").option("--json", "print machine-readable output").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const status = await getAgentLoopStatus({ cwd: process.cwd(), config });
+    const result = toNextActionResult(status);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(renderNextAction(result));
+    }
   });
 }
 
+// src/cli/commands/task.ts
+import { Command as Command11 } from "commander";
+function printTask(task, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ activeTask: task ?? null }, null, 2));
+    return;
+  }
+  if (!task) {
+    console.log("No active task set.");
+    console.log("Run `agentloop task set <path>` to pin one.");
+    return;
+  }
+  console.log(`Active task: ${task.title} (${task.status})`);
+  console.log(task.path);
+}
+function printTasks(tasks, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ tasks }, null, 2));
+    return;
+  }
+  if (tasks.length === 0) {
+    console.log("No task contracts found.");
+    console.log('Run `agentloop create-task --title "Your task"` to create one.');
+    return;
+  }
+  console.log("Task contracts:");
+  for (const task of tasks) {
+    const marker = task.active ? "*" : "-";
+    const activeLabel = task.active ? " active" : "";
+    console.log(`${marker} ${task.title} (${task.status})${activeLabel}`);
+    console.log(`  ${task.path}`);
+  }
+}
+function printTaskContract(task, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ task }, null, 2));
+    return;
+  }
+  process.stdout.write(task.content);
+}
+function printUpdatedTask(task, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ task }, null, 2));
+    return;
+  }
+  console.log(`Updated task status: ${task.title} (${task.status})`);
+  console.log(task.path);
+}
+function printArchivedTask(task, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ task }, null, 2));
+    return;
+  }
+  console.log(`Archived task: ${task.title} (${task.status})`);
+  console.log(`${task.previousPath} -> ${task.path}`);
+}
+function taskCommand() {
+  const command = new Command11("task").description(
+    "List, inspect, update, or archive task contracts"
+  );
+  command.command("list").option("--json", "print machine-readable output").description("List task contracts").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const tasks = await listTasks({ cwd: process.cwd(), config });
+    printTasks(tasks, options);
+  });
+  command.command("show").argument("<path>", "task contract path under .agentloop/tasks").option("--json", "print machine-readable output").description("Show a task contract").action(async (taskPath, options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const task = await readTaskContract({ cwd: process.cwd(), config, taskPath });
+    printTaskContract(task, options);
+  });
+  command.command("set").argument("<path>", "task contract path under .agentloop/tasks").option("--json", "print machine-readable output").description("Set the active task contract").action(async (taskPath, options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const activeTask = await setActiveTask({ cwd: process.cwd(), config, taskPath });
+    printTask(activeTask, options);
+  });
+  command.command("status").argument("<path>", "task contract path under .agentloop/tasks").argument("<status>", "one of: proposed, in-progress, blocked, review, done").option("--json", "print machine-readable output").description("Update a task contract status").action(async (taskPath, status, options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const task = await updateTaskStatus({ cwd: process.cwd(), config, taskPath, status });
+    printUpdatedTask(task, options);
+  });
+  command.command("archive").argument("<path>", "task contract path under .agentloop/tasks").option("--json", "print machine-readable output").description("Archive a task contract").action(async (taskPath, options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const task = await archiveTask({ cwd: process.cwd(), config, taskPath });
+    printArchivedTask(task, options);
+  });
+  command.command("current").option("--json", "print machine-readable output").description("Print the active task contract").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const activeTask = await getActiveTask({ cwd: process.cwd(), config });
+    printTask(activeTask ?? null, options);
+  });
+  command.command("clear").option("--json", "print machine-readable output").description("Clear the active task pointer").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    await clearActiveTask({ cwd: process.cwd(), config });
+    printTask(null, options);
+  });
+  return command;
+}
+
+// src/cli/commands/completion.ts
+import { Command as Command12 } from "commander";
+
+// src/core/completions.ts
+var COMPLETION_SHELLS = ["bash", "zsh", "fish", "powershell", "pwsh"];
+var topLevelCommands = [
+  ["init", "Generate the repo harness and config"],
+  ["doctor", "Check setup health"],
+  ["create-task", "Create a task contract"],
+  ["verify", "Run configured verification commands"],
+  ["summarize", "Preview a reviewer summary"],
+  ["handoff", "Write a reviewer handoff"],
+  ["status", "Show current loop state"],
+  ["next", "Show the next recommended loop action"],
+  ["check-gates", "Check review gate evidence"],
+  ["report", "Write a local HTML evidence report"],
+  ["badge", "Write a local SVG evidence badge"],
+  ["ci-summary", "Summarize CI context and AgentLoop evidence"],
+  ["release-notes", "Generate deterministic release notes"],
+  ["npm-status", "Check npm registry catch-up status"],
+  ["policy", "List or inspect local AgentLoopKit policies"],
+  ["task", "List, inspect, update, or archive task contracts"],
+  ["install-agent", "Install agent-specific instructions"],
+  ["list-templates", "List bundled templates"],
+  ["completion", "Print shell completion scripts"],
+  ["version", "Print the CLI version"]
+];
+var taskCommandSpecs = [
+  ["list", "List task contracts"],
+  ["show", "Show a task contract"],
+  ["set", "Set the active task contract"],
+  ["status", "Update a task contract status"],
+  ["archive", "Archive a task contract"],
+  ["current", "Print the active task contract"],
+  ["clear", "Clear the active task pointer"]
+];
+var taskCommands = taskCommandSpecs.map(([name]) => name);
+var policyCommandSpecs = [
+  ["list", "List local policies"],
+  ["show", "Show a local policy"],
+  ["status", "Show local policy template status"]
+];
+var policyCommands = policyCommandSpecs.map(([name]) => name);
+var taskStatuses = ["proposed", "in-progress", "blocked", "review", "done"];
+var agentNames = [
+  "codex",
+  "claude-code",
+  "cursor",
+  "opencode",
+  "gemini-cli",
+  "github-copilot-cli",
+  "generic",
+  "all"
+];
+function parseShell(shell) {
+  const clean = shell.trim().toLowerCase();
+  if (COMPLETION_SHELLS.includes(clean)) return clean;
+  throw new AgentLoopError(
+    `Unsupported shell "${shell}". Use one of: ${COMPLETION_SHELLS.join(", ")}.`
+  );
+}
+function renderBash() {
+  const commands = topLevelCommands.map(([name]) => name).join(" ");
+  return `# AgentLoopKit bash completion
+# Save with: agentloop completion bash > ~/.agentloop-completion.bash
+# Then source it from your shell profile.
+_agentloop_completion() {
+  local current previous
+  COMPREPLY=()
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  previous="\${COMP_WORDS[COMP_CWORD-1]}"
+
+  case "\${COMP_WORDS[1]}" in
+    task)
+      case "\${COMP_WORDS[2]}" in
+        status)
+          if [[ \${COMP_CWORD} -eq 4 ]]; then
+            COMPREPLY=( $(compgen -W "${taskStatuses.join(" ")}" -- "$current") )
+            return 0
+          fi
+          ;;
+        *)
+          if [[ \${COMP_CWORD} -eq 2 ]]; then
+            COMPREPLY=( $(compgen -W "${taskCommands.join(" ")}" -- "$current") )
+            return 0
+          fi
+          ;;
+      esac
+      ;;
+    policy)
+      if [[ \${COMP_CWORD} -eq 2 ]]; then
+        COMPREPLY=( $(compgen -W "${policyCommands.join(" ")}" -- "$current") )
+        return 0
+      fi
+      ;;
+    install-agent)
+      COMPREPLY=( $(compgen -W "${agentNames.join(" ")}" -- "$current") )
+      return 0
+      ;;
+    completion)
+      COMPREPLY=( $(compgen -W "${COMPLETION_SHELLS.join(" ")}" -- "$current") )
+      return 0
+      ;;
+  esac
+
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${commands}" -- "$current") )
+  fi
+}
+
+complete -F _agentloop_completion agentloop
+complete -F _agentloop_completion agentloopkit
+`;
+}
+function renderZsh() {
+  const commandSpecs = topLevelCommands.map(([name, description]) => `${name}:${description}`);
+  return `#compdef agentloop agentloopkit
+# AgentLoopKit zsh completion
+# Save with: agentloop completion zsh > ~/.zsh/completions/_agentloop
+
+_agentloop() {
+  local context state line
+  typeset -A opt_args
+
+  _arguments -C \\
+    '1:command:->commands' \\
+    '*::arg:->args'
+
+  case "$state" in
+    commands)
+      _describe 'agentloop command' commandSpecs
+      ;;
+    args)
+      case "$words[2]" in
+        task)
+          if [[ "$words[3]" == "status" && CURRENT -eq 5 ]]; then
+            _values 'task status' ${taskStatuses.map((status) => `"${status}"`).join(" ")}
+          else
+            _describe 'task command' taskCommandSpecs
+          fi
+          ;;
+        policy)
+          _describe 'policy command' policyCommandSpecs
+          ;;
+        install-agent)
+          _values 'agent' ${agentNames.map((agent) => `"${agent}"`).join(" ")}
+          ;;
+        completion)
+          _values 'shell' ${COMPLETION_SHELLS.map((shell) => `"${shell}"`).join(" ")}
+          ;;
+      esac
+      ;;
+  esac
+}
+
+commandSpecs=(
+${commandSpecs.map((spec) => `  '${spec}'`).join("\n")}
+)
+
+taskCommandSpecs=(
+${taskCommandSpecs.map(([name, description]) => `  '${name}:${description}'`).join("\n")}
+)
+
+policyCommandSpecs=(
+${policyCommandSpecs.map(([name, description]) => `  '${name}:${description}'`).join("\n")}
+)
+
+_agentloop "$@"
+`;
+}
+function fishLine(command, args, description) {
+  return `complete -c agentloop -n '${command}' -a '${args.join(" ")}' -d '${description}'`;
+}
+function renderFish() {
+  const topCommands = topLevelCommands.map(([name]) => name);
+  return `# AgentLoopKit fish completion
+# Save with: agentloop completion fish > ~/.config/fish/completions/agentloop.fish
+
+complete -c agentloop -f
+complete -c agentloopkit -f
+${fishLine("__fish_use_subcommand", topCommands, "AgentLoopKit command")}
+complete -c agentloop -n '__fish_seen_subcommand_from task' -a '${taskCommands.join(" ")}' -d 'Task command'
+complete -c agentloop -n '__fish_seen_subcommand_from policy' -a '${policyCommands.join(" ")}' -d 'Policy command'
+complete -c agentloop -n '__fish_seen_subcommand_from status' -a '${taskStatuses.join(" ")}' -d 'Task status'
+complete -c agentloop -n '__fish_seen_subcommand_from install-agent' -a '${agentNames.join(" ")}' -d 'Agent name'
+complete -c agentloop -n '__fish_seen_subcommand_from completion' -a '${COMPLETION_SHELLS.join(" ")}' -d 'Shell'
+complete -c agentloopkit -n '__fish_use_subcommand' -a '${topCommands.join(" ")}' -d 'AgentLoopKit command'
+complete -c agentloopkit -n '__fish_seen_subcommand_from task' -a '${taskCommands.join(" ")}' -d 'Task command'
+complete -c agentloopkit -n '__fish_seen_subcommand_from policy' -a '${policyCommands.join(" ")}' -d 'Policy command'
+complete -c agentloopkit -n '__fish_seen_subcommand_from status' -a '${taskStatuses.join(" ")}' -d 'Task status'
+complete -c agentloopkit -n '__fish_seen_subcommand_from install-agent' -a '${agentNames.join(" ")}' -d 'Agent name'
+complete -c agentloopkit -n '__fish_seen_subcommand_from completion' -a '${COMPLETION_SHELLS.join(" ")}' -d 'Shell'
+`;
+}
+function powerShellArray(values) {
+  return `@(${values.map((value) => `'${value}'`).join(", ")})`;
+}
+function renderPowerShell() {
+  const topCommands = topLevelCommands.map(([name]) => name);
+  return `# AgentLoopKit PowerShell completion
+# Save with: agentloop completion powershell > agentloop-completion.ps1
+# Review the script before dot-sourcing it from your PowerShell startup file.
+
+$AgentLoopCommands = ${powerShellArray(topCommands)}
+$AgentLoopTaskCommands = ${powerShellArray(taskCommands)}
+$AgentLoopPolicyCommands = ${powerShellArray(policyCommands)}
+$AgentLoopTaskStatuses = ${powerShellArray(taskStatuses)}
+$AgentLoopAgents = ${powerShellArray(agentNames)}
+$AgentLoopShells = ${powerShellArray(COMPLETION_SHELLS)}
+
+Register-ArgumentCompleter -Native -CommandName agentloop, agentloopkit -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+
+  $words = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
+  $prefix = if ($null -eq $wordToComplete) { '' } else { $wordToComplete }
+  $values = $AgentLoopCommands
+
+  if ($words.Count -gt 1) {
+    switch ($words[1]) {
+      'task' {
+        if ($words.Count -gt 2 -and $words[2] -eq 'status') {
+          $values = $AgentLoopTaskStatuses
+        } else {
+          $values = $AgentLoopTaskCommands
+        }
+      }
+      'policy' { $values = $AgentLoopPolicyCommands }
+      'install-agent' { $values = $AgentLoopAgents }
+      'completion' { $values = $AgentLoopShells }
+    }
+  }
+
+  $values |
+    Where-Object { $_.StartsWith($prefix, [System.StringComparison]::OrdinalIgnoreCase) } |
+    ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+}
+`;
+}
+function renderCompletionScript(shell) {
+  switch (parseShell(shell)) {
+    case "bash":
+      return renderBash();
+    case "zsh":
+      return renderZsh();
+    case "fish":
+      return renderFish();
+    case "powershell":
+    case "pwsh":
+      return renderPowerShell();
+  }
+}
+
+// src/cli/commands/completion.ts
+function completionCommand() {
+  return new Command12("completion").description("Print shell completion scripts").argument("<shell>", "one of: bash, zsh, fish, powershell, pwsh").action((shell) => {
+    process.stdout.write(renderCompletionScript(shell));
+  });
+}
+
+// src/cli/commands/check-gates.ts
+import { Command as Command13 } from "commander";
+
+// src/core/check-gates.ts
+import path16 from "path";
+import { readFile as readFile10 } from "fs/promises";
+var requiredRootFiles = ["AGENTS.md", "AGENTLOOP.md", "agentloop.config.json"];
+var requiredHarnessFiles = [
+  ".agentloop/harness/commands.md",
+  ".agentloop/harness/definition-of-done.md",
+  ".agentloop/harness/review-checklist.md",
+  ".agentloop/harness/autonomous-work-rules.md"
+];
+var requiredPolicyFiles = [
+  ".agentloop/policies/no-destructive-actions.md",
+  ".agentloop/policies/git-policy.md",
+  ".agentloop/policies/secrets-policy.md"
+];
+function extractHeading3(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function extractOverallStatus2(markdown) {
+  return markdown.match(/Overall status:\s*([a-z-]+)/i)?.[1]?.trim() || "unknown";
+}
+function relativePath(cwd, filePath) {
+  return path16.relative(cwd, filePath) || ".";
+}
+async function missingFiles(cwd, files) {
+  const missing = [];
+  for (const file of files) {
+    if (!await pathExists(path16.join(cwd, file))) missing.push(file);
+  }
+  return missing;
+}
+function gate(id, name, status, message, filePath) {
+  return { id, name, status, message, ...filePath ? { path: filePath } : {} };
+}
+function overallStatus(gates, strict) {
+  if (gates.some((item) => item.status === "fail")) return "fail";
+  if (strict && gates.some((item) => item.status === "warn")) return "fail";
+  if (gates.some((item) => item.status === "warn")) return "warn";
+  return "pass";
+}
+function chooseNextAction2(gates) {
+  const task = gates.find((item) => item.id === "task-contract");
+  const report = gates.find((item) => item.id === "verification-report");
+  const handoff = gates.find((item) => item.id === "handoff-summary");
+  if (task?.status === "fail") {
+    return {
+      command: "agentloop create-task",
+      reason: "Create a task contract before review gates can pass."
+    };
+  }
+  if (report?.status === "fail") {
+    return {
+      command: "agentloop verify",
+      reason: "Run verification and fix failures before review."
+    };
+  }
+  if (handoff?.status !== "pass") {
+    return {
+      command: "agentloop handoff",
+      reason: "Write a reviewer handoff after verification."
+    };
+  }
+  return {
+    command: "agentloop handoff",
+    reason: "Gate evidence is present. Refresh the reviewer handoff if the diff changed."
+  };
+}
+function renderMarkdown2(result) {
+  const gateLines = result.gates.map((item) => {
+    const suffix = item.path ? ` - ${item.path}` : "";
+    return `- [${item.status}] ${item.name}: ${item.message}${suffix}`;
+  }).join("\n");
+  const gitLine = result.git.isRepository ? `${result.git.branch || "unknown branch"}${result.git.commit ? ` @ ${result.git.commit}` : ""}` : "not inside a git repository";
+  return `# AgentLoopKit Gates
+
+- Overall status: ${result.overallStatus}
+- Strict mode: ${result.strict ? "enabled (warnings fail)" : "disabled"}
+- Git: ${gitLine}
+- Changed files: ${result.git.changedFileCount}
+
+## Gates
+
+${gateLines}
+
+## Next Action
+
+Run \`${result.nextAction.command}\`.
+
+${result.nextAction.reason}
+`;
+}
+async function checkGates(options) {
+  const strict = options.strict ?? false;
+  const taskPath = await getActiveTaskPath(options) ?? await latestMarkdownFile(path16.join(options.cwd, options.config.paths.tasksDir));
+  const reportPath = await latestMarkdownFile(path16.join(options.cwd, options.config.paths.reportsDir), {
+    pattern: verificationReportPattern
+  });
+  const handoffPath = await latestMarkdownFile(path16.join(options.cwd, options.config.paths.handoffsDir), {
+    pattern: prSummaryPattern
+  });
+  const gates = [];
+  if (taskPath) {
+    const taskMarkdown = await readFile10(taskPath, "utf8");
+    gates.push(
+      gate(
+        "task-contract",
+        "Task contract",
+        "pass",
+        extractHeading3(taskMarkdown, path16.basename(taskPath, ".md")),
+        relativePath(options.cwd, taskPath)
+      )
+    );
+  } else {
+    gates.push(gate("task-contract", "Task contract", "fail", "No task contract found."));
+  }
+  if (reportPath) {
+    const reportMarkdown = await readFile10(reportPath, "utf8");
+    const status = extractOverallStatus2(reportMarkdown);
+    gates.push(
+      gate(
+        "verification-report",
+        "Verification report",
+        status === "pass" ? "pass" : "fail",
+        `Overall status: ${status}`,
+        relativePath(options.cwd, reportPath)
+      )
+    );
+  } else {
+    gates.push(
+      gate("verification-report", "Verification report", "fail", "No verification report found.")
+    );
+  }
+  if (handoffPath) {
+    gates.push(
+      gate(
+        "handoff-summary",
+        "Handoff summary",
+        "pass",
+        "Reviewer handoff found.",
+        relativePath(options.cwd, handoffPath)
+      )
+    );
+  } else {
+    gates.push(gate("handoff-summary", "Handoff summary", "warn", "No handoff summary found."));
+  }
+  const missingHarness = await missingFiles(options.cwd, [
+    ...requiredRootFiles,
+    ...requiredHarnessFiles
+  ]);
+  gates.push(
+    gate(
+      "repo-harness",
+      "Repo harness",
+      missingHarness.length ? "warn" : "pass",
+      missingHarness.length ? `Missing harness files: ${missingHarness.join(", ")}.` : "Required repo and harness files exist."
+    )
+  );
+  const missingPolicies = await missingFiles(options.cwd, requiredPolicyFiles);
+  gates.push(
+    gate(
+      "safety-policies",
+      "Safety policies",
+      missingPolicies.length ? "warn" : "pass",
+      missingPolicies.length ? `Missing policy files: ${missingPolicies.join(", ")}.` : "Core safety policy files exist."
+    )
+  );
+  const inGit = await isInsideGitRepo(options.cwd);
+  const changedFiles = inGit ? await parseGitStatus(await getGitStatus(options.cwd)) : [];
+  gates.push(
+    gate(
+      "git-context",
+      "Git context",
+      !inGit || changedFiles.length === 0 ? "warn" : "pass",
+      !inGit ? "Not inside a git repository." : changedFiles.length === 0 ? "No changed files detected." : `${changedFiles.length} changed file(s) detected.`
+    )
+  );
+  const withoutMarkdown = {
+    strict,
+    overallStatus: overallStatus(gates, strict),
+    gates,
+    git: {
+      isRepository: inGit,
+      branch: inGit ? await getGitBranch(options.cwd) : "",
+      commit: inGit ? await getGitCommit(options.cwd) : "",
+      changedFileCount: changedFiles.length
+    },
+    nextAction: chooseNextAction2(gates)
+  };
+  return { ...withoutMarkdown, markdown: renderMarkdown2(withoutMarkdown) };
+}
+
+// src/cli/commands/check-gates.ts
+function checkGatesCommand() {
+  return new Command13("check-gates").description("Check whether task, verification, handoff, harness, policy, and git gates pass").option("--json", "print machine-readable output").option("--strict", "treat warning gates as failures").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const result = await checkGates({ cwd: process.cwd(), config, strict: options.strict });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(result.markdown);
+    }
+    if (result.overallStatus === "fail") process.exitCode = 1;
+  });
+}
+
+// src/cli/commands/report.ts
+import { Command as Command14 } from "commander";
+
+// src/core/html-report.ts
+import path17 from "path";
+import { readFile as readFile11, readdir as readdir6, stat as stat5 } from "fs/promises";
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function extractLine2(markdown, pattern, fallback) {
+  if (!markdown) return fallback;
+  return markdown.match(pattern)?.[1]?.trim() || fallback;
+}
+function extractTitle(markdown, fallback) {
+  return extractLine2(markdown, /^#\s+(.+)$/m, fallback);
+}
+function extractVerificationStatus(markdown) {
+  return extractLine2(markdown, /Overall status:\s*([a-z-]+)/i, "not available");
+}
+function normalizeDisplayPath(cwd, filePath) {
+  if (!filePath) return void 0;
+  const absolutePath = path17.isAbsolute(filePath) ? filePath : path17.resolve(cwd, filePath);
+  return path17.relative(cwd, absolutePath).split(path17.sep).join("/") || ".";
+}
+function resolveUserPath(cwd, filePath) {
+  if (!filePath) return void 0;
+  return path17.isAbsolute(filePath) ? path17.resolve(filePath) : path17.resolve(cwd, filePath);
+}
+async function readMarkdownIfExists(filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  return readFile11(filePath, "utf8");
+}
+async function latestMatchingMarkdownFile(dir, pattern) {
+  if (!await pathExists(dir)) return void 0;
+  const entries = await Promise.all(
+    (await readdir6(dir, { withFileTypes: true })).filter((entry) => entry.isFile() && pattern.test(entry.name)).map(async (entry) => {
+      const filePath = path17.join(dir, entry.name);
+      const fileStat = await stat5(filePath);
+      return { filePath, name: entry.name, mtimeMs: fileStat.mtimeMs };
+    })
+  );
+  entries.sort((left, right) => {
+    if (left.mtimeMs !== right.mtimeMs) return left.mtimeMs - right.mtimeMs;
+    return left.name.localeCompare(right.name);
+  });
+  return entries.at(-1)?.filePath;
+}
+function renderSourcePath(label, filePath) {
+  return `<li><span>${escapeHtml(label)}</span><code>${escapeHtml(filePath ?? "not found")}</code></li>`;
+}
+function renderChangedFiles(changedFiles) {
+  if (!changedFiles.length) return '<p class="muted">No changed files detected.</p>';
+  return `<table>
+  <thead><tr><th>Status</th><th>Path</th></tr></thead>
+  <tbody>
+${changedFiles.map(
+    (file) => `    <tr><td><code>${escapeHtml(file.status)}</code></td><td><code>${escapeHtml(
+      file.path
+    )}</code></td></tr>`
+  ).join("\n")}
+  </tbody>
+</table>`;
+}
+function renderMarkdownBlock(label, markdown, emptyText) {
+  return `<section>
+  <h2>${escapeHtml(label)}</h2>
+  ${markdown?.trim() ? `<pre>${escapeHtml(markdown.trim())}</pre>` : `<p class="muted">${escapeHtml(emptyText)}</p>`}
+</section>`;
+}
+function generateHtmlReport(input) {
+  const taskTitle = extractTitle(input.taskMarkdown, "No task contract found");
+  const verificationStatus = extractVerificationStatus(input.verificationMarkdown);
+  const generatedAt = input.nowIso ?? (/* @__PURE__ */ new Date()).toISOString();
+  const metadata = {
+    timestamp: input.timestamp,
+    repoName: input.repoName,
+    taskTitle,
+    verificationStatus,
+    changedFileCount: input.changedFiles.length
+  };
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>AgentLoopKit Report - ${escapeHtml(input.repoName)}</title>
+  <style>
+    :root { color-scheme: light; --ink: oklch(22% 0.026 245); --muted: oklch(48% 0.023 245); --line: oklch(84% 0.018 245); --panel: oklch(97% 0.009 245); --paper: oklch(99% 0.006 245); --accent: oklch(49% 0.09 183); --warn-ink: oklch(42% 0.12 52); --warn-bg: oklch(96% 0.035 72); --terminal: oklch(19% 0.024 245); --terminal-ink: oklch(91% 0.014 245); }
+    * { box-sizing: border-box; }
+    body { margin: 0; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: var(--ink); background: var(--paper); line-height: 1.55; }
+    main { max-width: 1040px; margin: 0 auto; padding: 44px 24px 56px; }
+    header { border-bottom: 1px solid var(--line); padding-bottom: 24px; margin-bottom: 28px; }
+    .eyebrow { color: var(--accent); font-size: 13px; font-weight: 700; letter-spacing: 0; text-transform: uppercase; }
+    h1 { margin: 8px 0 12px; font-size: clamp(32px, 5vw, 54px); line-height: 1.03; letter-spacing: 0; }
+    h2 { margin: 0 0 12px; font-size: 21px; letter-spacing: 0; }
+    section { border-top: 1px solid var(--line); padding: 24px 0; }
+    .summary { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(190px, 1fr)); margin-top: 18px; }
+    .metric { background: var(--panel); border: 1px solid var(--line); border-radius: 8px; padding: 14px; }
+    .metric span { display: block; color: var(--muted); font-size: 13px; }
+    .metric strong { display: block; margin-top: 5px; font-size: 16px; overflow-wrap: anywhere; }
+    ul.sources { margin: 0; padding: 0; list-style: none; display: grid; gap: 8px; }
+    ul.sources li { display: grid; gap: 4px; }
+    .muted { color: var(--muted); }
+    .safety { border: 1px solid oklch(78% 0.08 62); color: var(--warn-ink); background: var(--warn-bg); padding: 14px 16px; border-radius: 6px; }
+    table { width: 100%; border-collapse: collapse; border: 1px solid var(--line); border-radius: 8px; overflow: hidden; }
+    th, td { text-align: left; border-bottom: 1px solid var(--line); padding: 10px 12px; vertical-align: top; }
+    th { background: var(--panel); font-size: 13px; color: var(--muted); }
+    tr:last-child td { border-bottom: 0; }
+    code { font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace; font-size: 0.92em; overflow-wrap: anywhere; }
+    pre { margin: 0; padding: 16px; overflow: auto; border: 1px solid var(--line); border-radius: 8px; background: var(--terminal); color: var(--terminal-ink); font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <div class="eyebrow">AgentLoopKit local evidence report</div>
+      <h1>${escapeHtml(taskTitle)}</h1>
+      <p class="muted">Generated ${escapeHtml(generatedAt)} from local repository artifacts. No LLM, network call, telemetry, or command execution is required to render this report.</p>
+      <div class="summary">
+        <div class="metric"><span>Repository</span><strong>${escapeHtml(input.repoName)}</strong></div>
+        <div class="metric"><span>Branch</span><strong>${escapeHtml(input.branch || "not available")}</strong></div>
+        <div class="metric"><span>Commit</span><strong>${escapeHtml(input.commit || "not available")}</strong></div>
+        <div class="metric"><span>Working tree</span><strong>${escapeHtml(input.workingTreeStatus)}</strong></div>
+        <div class="metric"><span>Verification</span><strong>${escapeHtml(verificationStatus)}</strong></div>
+        <div class="metric"><span>Changed files</span><strong>${input.changedFiles.length}</strong></div>
+      </div>
+    </header>
+
+    <section>
+      <h2>Source Artifacts</h2>
+      <ul class="sources">
+        ${renderSourcePath("Task contract", input.taskPath)}
+        ${renderSourcePath("Verification report", input.verificationPath)}
+        ${renderSourcePath("Handoff summary", input.handoffPath)}
+      </ul>
+    </section>
+
+    <section>
+      <h2>Changed Files</h2>
+      ${renderChangedFiles(input.changedFiles)}
+    </section>
+
+    ${renderMarkdownBlock("Task Contract", input.taskMarkdown, "No task contract was found.")}
+    ${renderMarkdownBlock("Verification Evidence", input.verificationMarkdown, "No verification report was found.")}
+    ${renderMarkdownBlock("Reviewer Handoff", input.handoffMarkdown, "No handoff summary was found.")}
+    ${renderMarkdownBlock("Current Deterministic Summary", input.summaryMarkdown, "No deterministic summary was generated.")}
+
+    <section>
+      <h2>Diff Stats</h2>
+      <pre>${escapeHtml(input.diffStat?.trim() || "No diff stats available.")}</pre>
+    </section>
+
+    <section>
+      <h2>Safety Notes</h2>
+      <div class="safety">This report is a local static artifact. It must not be treated as proof that verification passed unless the verification section says so. Review protected areas such as secrets, auth, billing, deployment, migrations, lockfiles, and public APIs before merge.</div>
+    </section>
+  </main>
+</body>
+</html>
+`;
+  return { html, metadata };
+}
+async function writeHtmlReport(options) {
+  const timestamp = options.timestamp ?? formatTimestamp();
+  const cwd = options.cwd;
+  const taskPath = resolveUserPath(cwd, options.taskPath) ?? await getActiveTaskPath({ cwd, config: options.config }) ?? await latestMarkdownFile(path17.join(cwd, options.config.paths.tasksDir));
+  const verificationPath = resolveUserPath(cwd, options.reportPath) ?? await latestMatchingMarkdownFile(
+    path17.join(cwd, options.config.paths.reportsDir),
+    /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-verification-report\.md$/
+  );
+  const handoffPath = resolveUserPath(cwd, options.handoffPath) ?? await latestMatchingMarkdownFile(
+    path17.join(cwd, options.config.paths.handoffsDir),
+    /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-pr-summary\.md$/
+  );
+  const [status, branch, commit, diffStat, taskMarkdown, verificationMarkdown, handoffMarkdown] = await Promise.all([
+    getGitStatus(cwd),
+    getGitBranch(cwd),
+    getGitCommit(cwd),
+    getGitDiffStat(cwd),
+    readMarkdownIfExists(taskPath),
+    readMarkdownIfExists(verificationPath),
+    readMarkdownIfExists(handoffPath)
+  ]);
+  const changedFiles = await parseGitStatus(status);
+  const summary = await summarizeRepository({
+    cwd,
+    config: options.config,
+    taskPath,
+    reportPath: verificationPath,
+    timestamp,
+    write: false
+  });
+  const report = generateHtmlReport({
+    timestamp,
+    nowIso: options.nowIso,
+    repoName: options.config.project.name || path17.basename(cwd),
+    branch,
+    commit,
+    workingTreeStatus: status.trim() ? "dirty" : "clean or unavailable",
+    taskPath: normalizeDisplayPath(cwd, taskPath),
+    verificationPath: normalizeDisplayPath(cwd, verificationPath),
+    handoffPath: normalizeDisplayPath(cwd, handoffPath),
+    changedFiles,
+    diffStat,
+    taskMarkdown,
+    verificationMarkdown,
+    handoffMarkdown,
+    summaryMarkdown: summary.markdown
+  });
+  const outPath = resolveUserPath(cwd, options.outPath) ?? path17.join(cwd, options.config.paths.reportsDir, `${timestamp}-agentloop-report.html`);
+  await writeTextFile(outPath, report.html);
+  return {
+    ...report,
+    outPath,
+    sourcePaths: {
+      task: normalizeDisplayPath(cwd, taskPath),
+      verification: normalizeDisplayPath(cwd, verificationPath),
+      handoff: normalizeDisplayPath(cwd, handoffPath)
+    }
+  };
+}
+
+// src/cli/commands/report.ts
+function reportCommand() {
+  return new Command14("report").description("Generate a local static HTML evidence report").option("--task <path>", "task contract path").option("--report <path>", "verification report path").option("--handoff <path>", "handoff summary path").option("--out <path>", "output HTML path").option("--json", "print machine-readable output").action(
+    async (options) => {
+      const config = await loadAgentLoopConfig(process.cwd());
+      const result = await writeHtmlReport({
+        cwd: process.cwd(),
+        config,
+        taskPath: options.task,
+        reportPath: options.report,
+        handoffPath: options.handoff,
+        outPath: options.out
+      });
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              outPath: result.outPath,
+              metadata: result.metadata,
+              sourcePaths: result.sourcePaths
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(`# AgentLoopKit HTML Report
+
+Report written: ${result.outPath}
+Task: ${result.metadata.taskTitle}
+Verification: ${result.metadata.verificationStatus}
+Changed files: ${result.metadata.changedFileCount}
+
+Next step: open the HTML file locally or attach it as a CI/PR artifact.`);
+      }
+    }
+  );
+}
+
+// src/cli/commands/badge.ts
+import { Command as Command15 } from "commander";
+
+// src/core/badge.ts
+import path18 from "path";
+import { readFile as readFile12, readdir as readdir7, stat as stat6 } from "fs/promises";
+var verificationReportPattern2 = /^\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-verification-report\.md$/;
+function escapeXml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function statusColor(status) {
+  switch (status) {
+    case "pass":
+      return "#2f855a";
+    case "fail":
+      return "#c2410c";
+    case "warn":
+    case "not-run":
+    case "missing":
+    case "unknown":
+      return "#a16207";
+  }
+}
+function textWidth(value) {
+  return Math.max(44, value.length * 7 + 18);
+}
+function parseSource(source) {
+  const clean = source?.trim().toLowerCase() || "verification";
+  if (clean === "verification" || clean === "gates") return clean;
+  throw new AgentLoopError("Unsupported badge source. Use one of: verification, gates.");
+}
+async function latestVerificationReport(dir) {
+  if (!await pathExists(dir)) return void 0;
+  const entries = await Promise.all(
+    (await readdir7(dir, { withFileTypes: true })).filter((entry) => entry.isFile() && verificationReportPattern2.test(entry.name)).map(async (entry) => {
+      const filePath = path18.join(dir, entry.name);
+      const fileStat = await stat6(filePath);
+      return { filePath, name: entry.name, mtimeMs: fileStat.mtimeMs };
+    })
+  );
+  entries.sort((left, right) => {
+    if (left.mtimeMs !== right.mtimeMs) return left.mtimeMs - right.mtimeMs;
+    return left.name.localeCompare(right.name);
+  });
+  return entries.at(-1)?.filePath;
+}
+function extractVerificationStatus2(markdown) {
+  const status = markdown.match(/Overall status:\s*([a-z-]+)/i)?.[1]?.trim().toLowerCase();
+  if (status === "pass" || status === "fail" || status === "not-run") return status;
+  return "unknown";
+}
+function normalizeDisplayPath2(cwd, filePath) {
+  if (!filePath) return void 0;
+  return path18.relative(cwd, filePath).split(path18.sep).join("/") || ".";
+}
+function generateSvgBadge(input) {
+  const labelWidth = textWidth(input.label);
+  const messageWidth = textWidth(input.message);
+  const totalWidth = labelWidth + messageWidth;
+  const color = statusColor(input.status);
+  const label = escapeXml(input.label);
+  const message = escapeXml(input.message);
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${label}: ${message}">
+  <title>${label}: ${message}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#fff" stop-opacity=".08"/>
+    <stop offset="1" stop-opacity=".08"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="${totalWidth}" height="20" rx="4"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelWidth}" height="20" fill="#334155"/>
+    <rect x="${labelWidth}" width="${messageWidth}" height="20" fill="${color}"/>
+    <rect width="${totalWidth}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
+    <text x="${Math.floor(labelWidth / 2)}" y="15" fill="#010101" fill-opacity=".3">${label}</text>
+    <text x="${Math.floor(labelWidth / 2)}" y="14">${label}</text>
+    <text x="${labelWidth + Math.floor(messageWidth / 2)}" y="15" fill="#010101" fill-opacity=".3">${message}</text>
+    <text x="${labelWidth + Math.floor(messageWidth / 2)}" y="14">${message}</text>
+  </g>
+</svg>
+`;
+  return { ...input, svg };
+}
+async function writeEvidenceBadge(options) {
+  const source = parseSource(options.source);
+  let status;
+  let label;
+  let message;
+  let sourcePath;
+  if (source === "verification") {
+    const reportPath = await latestVerificationReport(
+      path18.join(options.cwd, options.config.paths.reportsDir)
+    );
+    sourcePath = normalizeDisplayPath2(options.cwd, reportPath);
+    if (!reportPath) {
+      status = "missing";
+      label = "verification";
+      message = "missing";
+    } else {
+      const markdown = await readFile12(reportPath, "utf8");
+      status = extractVerificationStatus2(markdown);
+      label = "verification";
+      message = status;
+    }
+  } else {
+    const gates = await checkGates({
+      cwd: options.cwd,
+      config: options.config,
+      strict: options.strict
+    });
+    status = gates.overallStatus;
+    label = "gates";
+    message = status;
+  }
+  const badge = generateSvgBadge({ label, message, status });
+  const outPath = options.outPath ?? path18.join(options.cwd, options.config.paths.reportsDir, `agentloop-${source}.svg`);
+  const absoluteOutPath = path18.isAbsolute(outPath) ? outPath : path18.resolve(options.cwd, outPath);
+  await writeTextFile(absoluteOutPath, badge.svg);
+  return {
+    outPath: absoluteOutPath,
+    source,
+    status,
+    label,
+    message,
+    sourcePath,
+    svg: badge.svg
+  };
+}
+
+// src/cli/commands/badge.ts
+function badgeCommand() {
+  return new Command15("badge").description("Generate a local SVG evidence badge").option("--source <source>", "badge source: verification or gates", "verification").option("--out <path>", "output SVG path").option("--strict", "use strict gate status when source is gates").option("--json", "print machine-readable output").action(
+    async (options) => {
+      const config = await loadAgentLoopConfig(process.cwd());
+      const result = await writeEvidenceBadge({
+        cwd: process.cwd(),
+        config,
+        source: options.source,
+        outPath: options.out,
+        strict: options.strict
+      });
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              outPath: result.outPath,
+              source: result.source,
+              status: result.status,
+              label: result.label,
+              message: result.message,
+              sourcePath: result.sourcePath
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(`# AgentLoopKit Badge
+
+Badge written: ${result.outPath}
+Source: ${result.source}
+Status: ${result.status}
+Message: ${result.message}`);
+      }
+    }
+  );
+}
+
+// src/cli/commands/policy.ts
+import { Command as Command16 } from "commander";
+
+// src/core/policy.ts
+import path19 from "path";
+import { readdir as readdir8, readFile as readFile13, stat as stat7 } from "fs/promises";
+function policyRoot(cwd, config) {
+  return path19.resolve(cwd, config.paths.agentloopDir, "policies");
+}
+function toStoredPath2(cwd, absolutePath) {
+  return path19.relative(cwd, absolutePath).split(path19.sep).join("/");
+}
+function extractHeading4(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function normalizePolicyName(policyName) {
+  return policyName.trim().replace(/\.md$/i, "").replace(/-policy$/i, "").toLowerCase();
+}
+function normalizeContent(content) {
+  return content.replace(/\r\n/g, "\n");
+}
+async function ensurePolicyRoot(root) {
+  const rootStat = await stat7(root).catch(() => void 0);
+  if (!rootStat?.isDirectory()) {
+    throw new AgentLoopError(
+      "No AgentLoopKit policy files found. Run `agentloop init` to generate .agentloop/policies/."
+    );
+  }
+}
+async function readMarkdownFiles(root) {
+  const entries = await readdir8(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+    const absolutePath = path19.join(root, entry.name);
+    const content = await readFile13(absolutePath, "utf8");
+    files.push({
+      name: path19.basename(entry.name, ".md"),
+      fileName: entry.name,
+      absolutePath,
+      content,
+      title: extractHeading4(content, path19.basename(entry.name, ".md"))
+    });
+  }
+  return files.sort((left, right) => left.name.localeCompare(right.name));
+}
+async function listPolicies(options) {
+  const root = policyRoot(options.cwd, options.config);
+  await ensurePolicyRoot(root);
+  const policies = await readMarkdownFiles(root);
+  return policies.map((policy) => ({
+    name: policy.name,
+    title: policy.title,
+    path: toStoredPath2(options.cwd, policy.absolutePath)
+  }));
+}
+async function readPolicy(options) {
+  const policies = await listPolicies(options);
+  const requested = normalizePolicyName(options.policyName);
+  const policy = policies.find((candidate) => normalizePolicyName(candidate.name) === requested);
+  if (!policy) {
+    throw new AgentLoopError(`Policy not found: ${options.policyName}`);
+  }
+  const root = policyRoot(options.cwd, options.config);
+  const absolutePath = path19.join(root, path19.basename(policy.path));
+  const content = await readFile13(absolutePath, "utf8");
+  return {
+    ...policy,
+    content
+  };
+}
+async function getPolicyStatus(options) {
+  const root = policyRoot(options.cwd, options.config);
+  await ensurePolicyRoot(root);
+  const templateRoot = path19.join(getTemplateRoot(), "policies");
+  const [localPolicies, templatePolicies] = await Promise.all([
+    readMarkdownFiles(root),
+    readMarkdownFiles(templateRoot)
+  ]);
+  const localByName = new Map(localPolicies.map((policy) => [policy.name, policy]));
+  const templateByName = new Map(templatePolicies.map((policy) => [policy.name, policy]));
+  const names = [.../* @__PURE__ */ new Set([...templateByName.keys(), ...localByName.keys()])].sort(
+    (left, right) => left.localeCompare(right)
+  );
+  const summary = {
+    current: 0,
+    modified: 0,
+    missing: 0,
+    extra: 0
+  };
+  const policies = names.map((name) => {
+    const local = localByName.get(name);
+    const template = templateByName.get(name);
+    const status = !template ? "extra" : !local ? "missing" : normalizeContent(local.content) === normalizeContent(template.content) ? "current" : "modified";
+    summary[status] += 1;
+    return {
+      name,
+      title: local?.title ?? template?.title ?? name,
+      path: toStoredPath2(options.cwd, path19.join(root, `${name}.md`)),
+      status,
+      templatePath: template ? `templates/policies/${template.fileName}` : null
+    };
+  });
+  return {
+    policies,
+    summary
+  };
+}
+
+// src/cli/commands/policy.ts
+function printPolicyList(policies, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ policies }, null, 2));
+    return;
+  }
+  if (policies.length === 0) {
+    console.log("No AgentLoopKit policies found.");
+    console.log("Run `agentloop init` to generate .agentloop/policies/.");
+    return;
+  }
+  console.log("AgentLoopKit policies:");
+  for (const policy of policies) {
+    console.log(`- ${policy.title}`);
+    console.log(`  ${policy.path}`);
+  }
+}
+function printPolicy(policy, options) {
+  if (options.json) {
+    console.log(JSON.stringify({ policy }, null, 2));
+    return;
+  }
+  process.stdout.write(policy.content);
+}
+function printPolicyStatus(report, options) {
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log("AgentLoopKit policy status:");
+  console.log(
+    `Summary: ${report.summary.current} current, ${report.summary.modified} modified, ${report.summary.missing} missing, ${report.summary.extra} extra`
+  );
+  for (const policy of report.policies) {
+    console.log(`- ${policy.status}: ${policy.title}`);
+    console.log(`  ${policy.path}`);
+  }
+  const hasDrift = report.summary.modified > 0 || report.summary.missing > 0 || report.summary.extra > 0;
+  if (hasDrift) {
+    console.log("");
+    console.log("Next step: review policy differences before changing repo rules.");
+  }
+}
+function policyCommand() {
+  const command = new Command16("policy").description("List or inspect local AgentLoopKit policies");
+  command.command("list").description("List local policies under .agentloop/policies").option("--json", "print machine-readable output").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const policies = await listPolicies({ cwd: process.cwd(), config });
+    printPolicyList(policies, options);
+  });
+  command.command("status").description("Show local policy template status").option("--json", "print machine-readable output").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const status = await getPolicyStatus({ cwd: process.cwd(), config });
+    printPolicyStatus(status, options);
+  });
+  command.command("show").argument("<policy>", "policy name, such as security or security-policy.md").description("Show a local policy").option("--json", "print machine-readable output").action(async (policyName, options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const policy = await readPolicy({ cwd: process.cwd(), config, policyName });
+    printPolicy(policy, options);
+  });
+  return command;
+}
+
+// src/cli/commands/ci-summary.ts
+import { Command as Command17 } from "commander";
+
+// src/core/ci-summary.ts
+import path20 from "path";
+import { readFile as readFile14 } from "fs/promises";
+function extractHeading5(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function extractTaskStatus3(markdown) {
+  return markdown.match(/^- Status:\s*(.+)$/im)?.[1]?.trim() || "unknown";
+}
+function extractOverallStatus3(markdown) {
+  return markdown.match(/Overall status:\s*([a-z-]+)/i)?.[1]?.trim() || "unknown";
+}
+function displayPath(cwd, filePath) {
+  if (!filePath) return void 0;
+  return path20.relative(cwd, filePath).split(path20.sep).join("/") || ".";
+}
+function resolveUserPath2(cwd, filePath) {
+  if (!filePath) return void 0;
+  return path20.isAbsolute(filePath) ? path20.resolve(filePath) : path20.resolve(cwd, filePath);
+}
+async function readTask2(cwd, filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  const markdown = await readFile14(filePath, "utf8");
+  return {
+    path: displayPath(cwd, filePath) ?? filePath,
+    title: extractHeading5(markdown, path20.basename(filePath, ".md")),
+    status: extractTaskStatus3(markdown)
+  };
+}
+async function readVerification(cwd, filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  const markdown = await readFile14(filePath, "utf8");
+  return {
+    path: displayPath(cwd, filePath) ?? filePath,
+    title: extractHeading5(markdown, path20.basename(filePath, ".md")),
+    overallStatus: extractOverallStatus3(markdown)
+  };
+}
+async function readHandoff(cwd, filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  const markdown = await readFile14(filePath, "utf8");
+  return {
+    path: displayPath(cwd, filePath) ?? filePath,
+    title: extractHeading5(markdown, path20.basename(filePath, ".md"))
+  };
+}
+function chooseNextAction3(input) {
+  if (!input.verification) {
+    return {
+      command: "agentloop verify",
+      reason: "No verification report was found for this CI summary."
+    };
+  }
+  if (input.verification.overallStatus === "fail") {
+    return {
+      command: "agentloop verify",
+      reason: "The latest verification report failed. Fix failures and rerun verification."
+    };
+  }
+  return {
+    command: "agentloop check-gates --strict",
+    reason: "Use strict gates in CI after verification and handoff artifacts exist."
+  };
+}
+function renderCiLines(ci) {
+  const lines2 = [`- Provider: ${ci.providerName}`];
+  if ("workflow" in ci && ci.workflow) lines2.push(`- Workflow: ${ci.workflow}`);
+  if ("event" in ci && ci.event) lines2.push(`- Event: ${ci.event}`);
+  if ("ref" in ci && ci.ref) lines2.push(`- Ref: ${ci.ref}`);
+  if ("commit" in ci && ci.commit) lines2.push(`- Commit: ${ci.commit}`);
+  if ("runUrl" in ci && ci.runUrl) lines2.push(`- Run URL: ${ci.runUrl}`);
+  if ("runAttempt" in ci && ci.runAttempt) lines2.push(`- Run attempt: ${ci.runAttempt}`);
+  return lines2.join("\n");
+}
+function renderArtifactLine(label, artifact) {
+  return artifact ? `- ${label}: ${artifact.title} - ${artifact.path}` : `- ${label}: not found`;
+}
+function renderMarkdown3(result) {
+  return `# AgentLoopKit CI Summary
+
+- Generated: ${result.timestamp}
+- Overall status: ${result.gates.overallStatus}
+
+## CI Context
+${renderCiLines(result.ci)}
+
+## AgentLoop Evidence
+${renderArtifactLine("Task", result.evidence.task)}
+- Verification: ${result.evidence.verification ? `${result.evidence.verification.overallStatus} - ${result.evidence.verification.path}` : "not found"}
+${renderArtifactLine("Handoff", result.evidence.handoff)}
+- Gates: ${result.gates.overallStatus}
+
+## Gate Details
+${result.gates.gates.map((gate2) => `- [${gate2.status}] ${gate2.name}: ${gate2.message}`).join("\n")}
+
+## Next Action
+
+Run \`${result.nextAction.command}\`.
+
+${result.nextAction.reason}
+
+## Safety
+
+This command reads allowlisted CI metadata and local AgentLoop artifacts only. It does not call CI provider APIs, read secrets, upload files, run verification commands, or inspect environment variables beyond supported CI provenance fields.
+`;
+}
+async function getCiSummary(options) {
+  const timestamp = options.timestamp ?? formatTimestamp();
+  const nowIso = options.nowIso ?? (/* @__PURE__ */ new Date()).toISOString();
+  const reportsDir = path20.join(options.cwd, options.config.paths.reportsDir);
+  const handoffsDir = path20.join(options.cwd, options.config.paths.handoffsDir);
+  const taskPath = await getActiveTaskPath(options) ?? await latestMarkdownFile(path20.join(options.cwd, options.config.paths.tasksDir));
+  const verificationPath = await latestMarkdownFile(reportsDir, {
+    pattern: verificationReportPattern
+  });
+  const handoffPath = await latestMarkdownFile(handoffsDir, { pattern: prSummaryPattern });
+  const [task, verification, handoff, gates] = await Promise.all([
+    readTask2(options.cwd, taskPath),
+    readVerification(options.cwd, verificationPath),
+    readHandoff(options.cwd, handoffPath),
+    checkGates({ cwd: options.cwd, config: options.config })
+  ]);
+  const ci = detectCiContext(options.env ?? process.env) ?? {
+    provider: "none",
+    providerName: "No CI detected"
+  };
+  const withoutMarkdown = {
+    timestamp: nowIso,
+    ci,
+    evidence: {
+      task,
+      verification,
+      handoff
+    },
+    gates: {
+      overallStatus: gates.overallStatus,
+      gates: gates.gates
+    },
+    nextAction: chooseNextAction3({ verification, gates })
+  };
+  const markdown = renderMarkdown3(withoutMarkdown);
+  const writtenPath = options.write ? resolveUserPath2(options.cwd, options.outPath) ?? path20.join(options.cwd, options.config.paths.reportsDir, `${timestamp}-ci-summary.md`) : void 0;
+  if (writtenPath) await writeTextFile(writtenPath, markdown);
+  return {
+    ...withoutMarkdown,
+    markdown,
+    writtenPath
+  };
+}
+
+// src/cli/commands/ci-summary.ts
+function ciSummaryCommand() {
+  return new Command17("ci-summary").description("Summarize CI context and AgentLoop evidence").option("--write", "write summary to .agentloop/reports").option("--out <path>", "output Markdown path when using --write").option("--json", "print machine-readable output").action(async (options) => {
+    const config = await loadAgentLoopConfig(process.cwd());
+    const result = await getCiSummary({
+      cwd: process.cwd(),
+      config,
+      write: options.write,
+      outPath: options.out
+    });
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(result.markdown);
+      if (result.writtenPath) console.log(`
+CI summary written: ${result.writtenPath}`);
+    }
+  });
+}
+
+// src/cli/commands/release-notes.ts
+import { Command as Command18 } from "commander";
+
+// src/core/release-notes.ts
+import path21 from "path";
+import { readFile as readFile15 } from "fs/promises";
+import { execa as execa3 } from "execa";
+function displayPath2(cwd, filePath) {
+  if (!filePath) return void 0;
+  return path21.relative(cwd, filePath).split(path21.sep).join("/") || ".";
+}
+function resolveUserPath3(cwd, filePath) {
+  if (!filePath) return void 0;
+  return path21.isAbsolute(filePath) ? path21.resolve(filePath) : path21.resolve(cwd, filePath);
+}
+async function gitLines(cwd, args) {
+  const result = await execa3("git", args, { cwd, reject: false });
+  if (result.exitCode !== 0) return [];
+  return result.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+async function gitRefExists(cwd, ref) {
+  const result = await execa3("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+    cwd,
+    reject: false
+  });
+  return result.exitCode === 0;
+}
+async function readPackageMetadata(cwd) {
+  const packagePath = path21.join(cwd, "package.json");
+  if (!await pathExists(packagePath)) return { name: path21.basename(cwd), version: "0.0.0" };
+  const parsed = JSON.parse(await readFile15(packagePath, "utf8"));
+  return {
+    name: typeof parsed.name === "string" && parsed.name ? parsed.name : path21.basename(cwd),
+    version: typeof parsed.version === "string" && parsed.version ? parsed.version : "0.0.0"
+  };
+}
+function extractHeading6(markdown, fallback) {
+  return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
+}
+function extractTaskStatus4(markdown) {
+  return markdown.match(/^- Status:\s*(.+)$/im)?.[1]?.trim() || "unknown";
+}
+function extractOverallStatus4(markdown) {
+  return markdown.match(/Overall status:\s*([a-z-]+)/i)?.[1]?.trim() || "unknown";
+}
+async function readTask3(cwd, filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  const markdown = await readFile15(filePath, "utf8");
+  return {
+    path: displayPath2(cwd, filePath) ?? filePath,
+    title: extractHeading6(markdown, path21.basename(filePath, ".md")),
+    status: extractTaskStatus4(markdown)
+  };
+}
+async function readVerification2(cwd, filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  const markdown = await readFile15(filePath, "utf8");
+  return {
+    path: displayPath2(cwd, filePath) ?? filePath,
+    overallStatus: extractOverallStatus4(markdown)
+  };
+}
+async function readCiSummary(cwd, filePath) {
+  if (!filePath || !await pathExists(filePath)) return void 0;
+  const markdown = await readFile15(filePath, "utf8");
+  return {
+    path: displayPath2(cwd, filePath) ?? filePath,
+    title: extractHeading6(markdown, path21.basename(filePath, ".md"))
+  };
+}
+async function readChangelogSection(cwd, version) {
+  const changelogPath = path21.join(cwd, "CHANGELOG.md");
+  if (!await pathExists(changelogPath)) return "";
+  const changelog = await readFile15(changelogPath, "utf8");
+  const escapedVersion = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const heading = new RegExp(`^##\\s+\\[?${escapedVersion}\\]?\\s*$`, "im");
+  const match = heading.exec(changelog);
+  if (!match || match.index === void 0) return "";
+  const sectionStart = match.index + match[0].length;
+  const rest = changelog.slice(sectionStart);
+  const nextHeading = rest.search(/^##\s+/m);
+  return (nextHeading === -1 ? rest : rest.slice(0, nextHeading)).trim();
+}
+async function findPreviousTag(cwd, version) {
+  const currentTags = /* @__PURE__ */ new Set([`v${version}`, version]);
+  const tags = await gitLines(cwd, ["tag", "--list", "--sort=-creatordate"]);
+  return tags.find((tag) => !currentTags.has(tag));
+}
+function parseNameStatus(lines2) {
+  return lines2.map((line) => {
+    const [status = "?", ...rest] = line.split(/\s+/);
+    return { status, path: rest.join(" ") };
+  });
+}
+function renderList(lines2, empty) {
+  return lines2.length ? lines2.map((line) => `- ${line}`).join("\n") : `- ${empty}`;
+}
+function renderChangedFiles2(files) {
+  return files.length ? files.map((file) => `- ${file.status} \`${file.path}\``).join("\n") : "- No changed files detected for the selected range.";
+}
+function renderWorkingTree(files) {
+  return files.length ? [
+    "- Uncommitted changes detected. Commit or stash them before publishing a release.",
+    ...files.map((file) => `- \`${file}\``)
+  ].join("\n") : "- No uncommitted changes detected.";
+}
+function renderEvidence(result) {
+  const lines2 = [];
+  lines2.push(
+    result.evidence.task ? `- Task: ${result.evidence.task.title} (${result.evidence.task.status}) - ${result.evidence.task.path}` : "- Task: not found"
+  );
+  lines2.push(
+    result.evidence.verification ? `- Verification: Overall status: ${result.evidence.verification.overallStatus} - ${result.evidence.verification.path}` : "- Verification: not found"
+  );
+  lines2.push(
+    result.evidence.ciSummary ? `- CI summary: ${result.evidence.ciSummary.title} - ${result.evidence.ciSummary.path}` : "- CI summary: not found"
+  );
+  return lines2.join("\n");
+}
+function renderMarkdown4(result) {
+  const changelogLines = [
+    ...result.gitRange.fallbackReason ? [`- ${result.gitRange.fallbackReason}`] : [],
+    result.changelogSection || "- No matching CHANGELOG.md section found."
+  ];
+  return `# Release Notes
+
+- Generated: ${result.timestamp}
+- Package: ${result.packageName}
+- Version: ${result.version}
+- Range: ${result.gitRange.label}
+- Branch: ${result.branch || "unknown"}
+- Commit: ${result.commit || "unknown"}
+
+## Changelog
+${changelogLines.join("\n")}
+
+## Commits
+${renderList(result.commits, "No commits found for the selected range.")}
+
+## Changed Files
+${renderChangedFiles2(result.changedFiles)}
+
+## Working Tree
+${renderWorkingTree(result.workingTree.files)}
+
+## AgentLoop Evidence
+${renderEvidence(result)}
+
+## Release Checklist
+- Review these notes before publishing.
+- Confirm npm and GitHub release status from the registry or release page.
+- Attach verification evidence when creating a release.
+- Keep npm catch-up notes honest if the registry still serves an older version.
+
+## Safety
+This command is local and deterministic. Does not create tags, publish packages, call external APIs, read tokens, upload files, or rewrite changelogs.
+`;
+}
+async function generateReleaseNotes(options) {
+  const timestamp = options.timestamp ?? formatTimestamp();
+  const packageMetadata = await readPackageMetadata(options.cwd);
+  const version = options.version ?? packageMetadata.version;
+  const to = options.to ?? "HEAD";
+  const requestedFrom = options.from ?? await findPreviousTag(options.cwd, version);
+  const from = requestedFrom && await gitRefExists(options.cwd, requestedFrom) ? requestedFrom : void 0;
+  const fallbackReason = requestedFrom ? from ? void 0 : `Git ref "${requestedFrom}" was not found; using available local context.` : "No previous version tag was found; using available local context.";
+  const gitRange = {
+    from,
+    to,
+    label: from ? `${from}..${to}` : requestedFrom ? `${to} (missing from: ${requestedFrom})` : `${to} (no previous tag)`,
+    fallbackReason
+  };
+  const commitArgs = from ? ["log", "--pretty=format:%s", `${from}..${to}`] : ["log", "--pretty=format:%s", "-n", "10", to];
+  const diffArgs = from ? ["diff", "--name-status", `${from}..${to}`] : [];
+  const reportsDir = path21.join(options.cwd, options.config.paths.reportsDir);
+  const taskPath = await getActiveTaskPath(options) ?? await latestMarkdownFile(path21.join(options.cwd, options.config.paths.tasksDir));
+  const verificationPath = await latestMarkdownFile(reportsDir, {
+    pattern: verificationReportPattern
+  });
+  const ciSummaryPath = await latestMarkdownFile(reportsDir, {
+    pattern: ciSummaryPattern
+  });
+  const [
+    branch,
+    commit,
+    commits,
+    diffLines,
+    statusLines,
+    changelogSection,
+    task,
+    verification,
+    ciSummary
+  ] = await Promise.all([
+    getGitBranch(options.cwd),
+    getGitCommit(options.cwd),
+    gitLines(options.cwd, commitArgs),
+    diffArgs.length ? gitLines(options.cwd, diffArgs) : Promise.resolve([]),
+    gitLines(options.cwd, ["status", "--short"]),
+    readChangelogSection(options.cwd, version),
+    readTask3(options.cwd, taskPath),
+    readVerification2(options.cwd, verificationPath),
+    readCiSummary(options.cwd, ciSummaryPath)
+  ]);
+  const withoutMarkdown = {
+    timestamp,
+    packageName: packageMetadata.name,
+    version,
+    gitRange,
+    branch,
+    commit,
+    commits,
+    changedFiles: parseNameStatus(diffLines),
+    workingTree: {
+      clean: statusLines.length === 0,
+      files: statusLines
+    },
+    changelogSection,
+    evidence: {
+      task,
+      verification,
+      ciSummary
+    }
+  };
+  const markdown = renderMarkdown4(withoutMarkdown);
+  const writtenPath = options.write ? resolveUserPath3(options.cwd, options.outPath) ?? path21.join(options.cwd, options.config.paths.handoffsDir, `${timestamp}-release-notes.md`) : void 0;
+  if (writtenPath) await writeTextFile(writtenPath, markdown);
+  return {
+    ...withoutMarkdown,
+    markdown,
+    writtenPath
+  };
+}
+
+// src/cli/commands/release-notes.ts
+function releaseNotesCommand() {
+  return new Command18("release-notes").description("Generate deterministic release notes").option("--from <ref>", "git ref to compare from").option("--to <ref>", "git ref to compare to", "HEAD").option("--release-version <version>", "release version; defaults to package.json version").option("--write", "write notes to .agentloop/handoffs").option("--out <path>", "output Markdown path when using --write").option("--json", "print machine-readable output").action(
+    async (options) => {
+      const config = await loadAgentLoopConfig(process.cwd());
+      const result = await generateReleaseNotes({
+        cwd: process.cwd(),
+        config,
+        from: options.from,
+        to: options.to,
+        version: options.releaseVersion,
+        write: options.write,
+        outPath: options.out
+      });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(result.markdown);
+      if (result.writtenPath) {
+        console.log(`
+Release notes written: ${result.writtenPath}`);
+      } else {
+        console.log("\nNo release notes file was written. Use --write to create one.");
+      }
+    }
+  );
+}
+
+// src/cli/commands/npm-status.ts
+import { readFile as readFile17 } from "fs/promises";
+import { Command as Command19 } from "commander";
+
+// src/core/npm-status.ts
+import path22 from "path";
+import { readFile as readFile16 } from "fs/promises";
+import { execa as execa4 } from "execa";
+function uniqueStrings(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+function valueAsString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function valueAsVersions(value) {
+  if (Array.isArray(value)) return uniqueStrings(value.map(valueAsString).filter(isString));
+  const single = valueAsString(value);
+  return single ? [single] : [];
+}
+function parseNpmViewJson(json) {
+  const parsed = JSON.parse(json);
+  if (typeof parsed === "string") return { latest: parsed, versions: [parsed] };
+  if (!parsed || typeof parsed !== "object") {
+    throw new AgentLoopError("npm view JSON must be an object or string.");
+  }
+  const record = parsed;
+  const versions = valueAsVersions(record.versions);
+  const latest = valueAsString(record.version) ?? versions.at(-1);
+  if (!latest) throw new AgentLoopError("npm view JSON did not include a version.");
+  return {
+    latest,
+    versions: versions.includes(latest) ? versions : uniqueStrings([...versions, latest])
+  };
+}
+async function readPackageMetadata2(cwd) {
+  const packagePath = path22.join(cwd, "package.json");
+  if (!await pathExists(packagePath)) {
+    return { name: path22.basename(cwd), version: "0.0.0" };
+  }
+  const parsed = JSON.parse(await readFile16(packagePath, "utf8"));
+  return {
+    name: typeof parsed.name === "string" && parsed.name ? parsed.name : path22.basename(cwd),
+    version: typeof parsed.version === "string" && parsed.version ? parsed.version : "0.0.0"
+  };
+}
+function defaultNpmViewRunner(cwd, timeoutMs) {
+  return async (packageName) => {
+    const result = await execa4("npm", ["view", packageName, "version", "versions", "--json"], {
+      cwd,
+      reject: false,
+      timeout: timeoutMs
+    });
+    return {
+      exitCode: result.exitCode ?? 1,
+      stdout: result.stdout,
+      stderr: result.stderr
+    };
+  };
+}
+function statusLabel(status) {
+  switch (status) {
+    case "current":
+      return "npm latest matches local package version";
+    case "catch-up-needed":
+      return "npm latest differs from local package version";
+    case "unknown":
+      return "npm status could not be determined";
+  }
+}
+function recommendation(status) {
+  switch (status) {
+    case "current":
+      return "npm has caught up. Remove temporary GitHub tarball fallback docs if they are still present.";
+    case "catch-up-needed":
+      return "Publish the current source version after npm authentication or trusted publishing works. Do not backfill stale intermediate versions from the current checkout.";
+    case "unknown":
+      return "Fix the npm registry check and rerun this command before claiming npm availability.";
+  }
+}
+function renderVersions(versions) {
+  return versions.length ? versions.map((version) => `\`${version}\``).join(", ") : "not available";
+}
+function renderMarkdown5(result) {
+  const latest = result.registry.latest ? `\`${result.registry.latest}\`` : "not available";
+  const errorLine = result.source.error ? `
+- Registry error: ${result.source.error}` : "";
+  return `# npm Status
+
+- Package: \`${result.packageName}\`
+- Local version: \`${result.localVersion}\`
+- npm latest: ${latest}
+- Registry contains local version: ${result.registry.hasLocalVersion ? "yes" : "no"}
+- Registry versions: ${renderVersions(result.registry.versions)}
+- Status: ${statusLabel(result.status)}${errorLine}
+
+## Recommendation
+
+${result.recommendation}
+
+## Safety
+
+This command only runs \`npm view ${result.packageName} version versions --json\` unless \`--registry-json\` is provided. It does not publish packages, create tags, create GitHub releases, read npm tokens, read .env files, upload files, or change package metadata.
+`;
+}
+async function checkNpmStatus(options) {
+  const packageMetadata = await readPackageMetadata2(options.cwd);
+  const packageName = options.packageName ?? packageMetadata.name;
+  const localVersion = options.localVersion ?? packageMetadata.version;
+  const source = options.registryJson ? {
+    command: "captured npm view JSON",
+    exitCode: 0
+  } : {
+    command: `npm view ${packageName} version versions --json`,
+    exitCode: 0
+  };
+  const runner = options.npmView ?? defaultNpmViewRunner(options.cwd, options.timeoutMs ?? 15e3);
+  let registry = { versions: [] };
+  let sourceResult = source;
+  try {
+    if (options.registryJson) {
+      registry = parseNpmViewJson(options.registryJson);
+    } else {
+      const result = await runner(packageName);
+      sourceResult = {
+        ...source,
+        exitCode: result.exitCode,
+        ...result.exitCode === 0 ? {} : { error: result.stderr || result.stdout || "npm view failed" }
+      };
+      if (result.exitCode === 0) registry = parseNpmViewJson(result.stdout);
+    }
+  } catch (error) {
+    sourceResult = {
+      ...source,
+      exitCode: source.exitCode || 1,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+  const hasLocalVersion = registry.versions.includes(localVersion);
+  const status = sourceResult.error ? "unknown" : registry.latest === localVersion ? "current" : "catch-up-needed";
+  const withoutMarkdown = {
+    packageName,
+    localVersion,
+    status,
+    registry: {
+      ...registry,
+      hasLocalVersion
+    },
+    source: sourceResult,
+    recommendation: recommendation(status),
+    safety: {
+      does: ["runs npm view when no captured registry JSON is provided"],
+      doesNot: [
+        "publish packages",
+        "create tags",
+        "create GitHub releases",
+        "read npm tokens",
+        "read .env files",
+        "upload files",
+        "change package metadata"
+      ]
+    }
+  };
+  return {
+    ...withoutMarkdown,
+    markdown: renderMarkdown5(withoutMarkdown)
+  };
+}
+function shouldFailNpmStatusExpectation(result) {
+  return result.status !== "current";
+}
+
+// src/cli/commands/npm-status.ts
+function parseTimeout(value) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error("timeout must be a positive integer");
+  }
+  return parsed;
+}
+function npmStatusCommand() {
+  return new Command19("npm-status").description("Check npm registry catch-up status").option("--package-name <name>", "package name; defaults to package.json name").option("--local-version <version>", "local version; defaults to package.json version").option(
+    "--registry-json <path>",
+    "read captured `npm view <package> version versions --json` output instead of running npm"
+  ).option("--timeout-ms <ms>", "npm view timeout in milliseconds", parseTimeout, 15e3).option("--expect-current", "exit 1 unless npm latest matches the local version").option("--json", "print machine-readable output").action(
+    async (options) => {
+      const registryJson = options.registryJson ? await readFile17(options.registryJson, "utf8") : void 0;
+      const result = await checkNpmStatus({
+        cwd: process.cwd(),
+        packageName: options.packageName,
+        localVersion: options.localVersion,
+        registryJson,
+        timeoutMs: options.timeoutMs
+      });
+      if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        console.log(result.markdown);
+      }
+      if (options.expectCurrent && shouldFailNpmStatusExpectation(result)) {
+        process.exitCode = 1;
+      }
+    }
+  );
+}
+
 // src/cli/index.ts
-var program = new Command9();
-program.name("agentloop").description("A drop-in engineering loop for coding agents.").version("0.1.0", "-V, --version", "print CLI version");
+var program = new Command20();
+program.name("agentloop").description("A drop-in engineering loop for coding agents.").version(getPackageVersion(), "-V, --version", "print CLI version");
 program.addCommand(initCommand());
 program.addCommand(doctorCommand());
 program.addCommand(createTaskCommand());
 program.addCommand(verifyCommand());
 program.addCommand(summarizeCommand());
+program.addCommand(handoffCommand());
+program.addCommand(statusCommand());
+program.addCommand(nextCommand());
+program.addCommand(checkGatesCommand());
+program.addCommand(reportCommand());
+program.addCommand(badgeCommand());
+program.addCommand(ciSummaryCommand());
+program.addCommand(releaseNotesCommand());
+program.addCommand(npmStatusCommand());
+program.addCommand(policyCommand());
+program.addCommand(taskCommand());
 program.addCommand(installAgentCommand());
 program.addCommand(listTemplatesCommand());
+program.addCommand(completionCommand());
 program.addCommand(versionCommand());
 program.parseAsync(process.argv).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);