agentloopkit 0.24.4 → 0.25.0

package/README.md

@@ -49,11 +49,19 @@ npx agentloopkit init
 
 `init` writes files into the current directory. Do not run it from `~` unless you intend to configure your home directory. `--dry-run` previews the file changes without writing them.
 
+If you want AgentLoopKit for your local agent workflow but do not want to commit the generated harness:
+
+```bash
+npx agentloopkit init --local-only
+```
+
+`--local-only` writes the same files, then adds a marked block to this clone's `.git/info/exclude` for `.agentloop/`, `AGENTS.md`, `AGENTLOOP.md`, and `agentloop.config.json`. It does not edit `.gitignore`, global Git config, shell profiles, or files outside the current repo.
+
 Pin the current version when you need repeatable CI or team setup:
 
 ```bash
-npx --yes agentloopkit@0.24.4 version
-npx --yes agentloopkit@0.24.4 init
+npx --yes agentloopkit@0.25.0 version
+npx --yes agentloopkit@0.25.0 init
 ```
 
 Run the CLI after install:
@@ -87,10 +95,10 @@ npx agentloopkit completion powershell
 ```
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-cli.gif" alt="Terminal demo running AgentLoopKit init, task contracts, active task status, task-linked verify, handoff, reports, badges, release notes, gates, and task archive commands" width="100%">
+  <img src="https://raw.githubusercontent.com/abhiyoheswaran1/AgentLoopKit/main/docs/assets/readme/agentloopkit-cli.gif" alt="Terminal demo running AgentLoopKit init, doctor, task contract creation, task status, verification, handoff, gates, HTML report, and badge commands" width="100%">
 </p>
 
-The VHS demo is generated from committed sources in this repository.
+The terminal demo is generated from committed VHS sources in this repository.
 
 Pinned team usage:
 
@@ -116,6 +124,7 @@ pnpm build
 | `agentloop init`                        | Generate the repo harness and config                                           |
 | `agentloop init --dry-run`              | Preview generated files without writing them                                   |
 | `agentloop init --force`                | Allow initialization when the current directory is your home directory          |
+| `agentloop init --local-only`           | Generate the harness but exclude it from this clone's git status               |
 | `agentloop doctor`                      | Check setup health, template version, commands, git state, and risk categories |
 | `agentloop create-task`                 | Create a task contract in `.agentloop/tasks/`                                  |
 | `agentloop task list`                   | List task contracts and show the pinned active task                            |
@@ -384,7 +393,7 @@ See `docs/ci-summary.md`.
 ```bash
 agentloop release-notes
 agentloop release-notes --from v0.19.0 --to HEAD
-agentloop release-notes --release-version 0.24.4
+agentloop release-notes --release-version 0.25.0
 agentloop release-notes --json
 agentloop release-notes --write
 ```
@@ -450,7 +459,7 @@ Use `agentloop check-gates --strict` as a review-evidence gate in pull request C
 
 CI-generated verification reports include GitHub Actions provenance when available, so reviewers can trace an artifact back to the workflow run that created it.
 
-See `docs/github-actions.md`, `examples/github-actions/`, `examples/gitlab-ci/`, and `examples/buildkite/` for copy-pasteable workflows. Pin `agentloopkit@0.24.4` or a newer vetted release when reproducibility matters.
+See `docs/github-actions.md`, `examples/github-actions/`, `examples/gitlab-ci/`, and `examples/buildkite/` for copy-pasteable workflows. Pin `agentloopkit@0.25.0` or a newer vetted release when reproducibility matters.
 
 ## PR Summaries
 

package/dist/cli/index.js

@@ -8,7 +8,7 @@ import { Command } from "commander";
 
 // src/core/init.ts
 import path6 from "path";
-import { readdir as readdir3, realpath } from "fs/promises";
+import { readdir as readdir3, realpath, stat as stat2 } from "fs/promises";
 import { homedir } from "os";
 
 // src/core/constants.ts
@@ -342,6 +342,21 @@ async function listTemplateFiles() {
 }
 
 // src/core/init.ts
+var LOCAL_ONLY_EXCLUDE_START = "# agentloopkit:local-only:start";
+var LOCAL_ONLY_EXCLUDE_END = "# agentloopkit:local-only:end";
+var LOCAL_ONLY_NOTICE_START = "<!-- agentloopkit:local-only:start -->";
+var LOCAL_ONLY_NOTICE_END = "<!-- agentloopkit:local-only:end -->";
+var LOCAL_ONLY_EXCLUDE_PATTERNS = [
+  `${AGENTLOOP_DIR}/`,
+  AGENTS_FILE,
+  AGENTLOOP_FILE,
+  CONFIG_FILE
+];
+var LOCAL_ONLY_NOTICE = `${LOCAL_ONLY_NOTICE_START}
+## Local-only AgentLoopKit harness
+
+This AgentLoopKit setup is excluded by this clone's \`.git/info/exclude\`. Use these files for local agent work. Do not commit these AgentLoopKit files unless a maintainer intentionally converts the repo to a shared harness.
+${LOCAL_ONLY_NOTICE_END}`;
 async function writeGeneratedFile(filePath, content, result) {
   if (await pathExists(filePath)) {
     result.skipped.push(filePath);
@@ -395,6 +410,65 @@ ${section.trim()}
 `);
   result.updated.push(filePath);
 }
+async function resolveGitInfoExcludePath(cwd) {
+  const dotGitPath = path6.join(cwd, ".git");
+  const dotGitStat = await stat2(dotGitPath).catch(() => void 0);
+  if (!dotGitStat) return void 0;
+  if (dotGitStat.isDirectory()) {
+    return path6.join(dotGitPath, "info", "exclude");
+  }
+  if (!dotGitStat.isFile()) return void 0;
+  const gitFile = await readTextIfExists(dotGitPath);
+  const match = /^gitdir:\s*(.+)\s*$/m.exec(gitFile);
+  if (!match) return void 0;
+  const gitDir = match[1].trim();
+  const resolvedGitDir = path6.isAbsolute(gitDir) ? gitDir : path6.resolve(cwd, gitDir);
+  return path6.join(resolvedGitDir, "info", "exclude");
+}
+async function upsertLocalOnlyGitExclude(cwd, result) {
+  const excludePath = await resolveGitInfoExcludePath(cwd);
+  if (!excludePath) {
+    throw new Error(
+      "Local-only mode requires a Git repository because it writes to .git/info/exclude. Run git init first, or run agentloop init without --local-only."
+    );
+  }
+  result.localOnly = {
+    excludePath,
+    patterns: [...LOCAL_ONLY_EXCLUDE_PATTERNS]
+  };
+  const excludeExists = await pathExists(excludePath);
+  const existing = await readTextIfExists(excludePath);
+  if (existing.includes(LOCAL_ONLY_EXCLUDE_START)) return;
+  const block = [
+    LOCAL_ONLY_EXCLUDE_START,
+    "# AgentLoopKit local-only harness files for this clone.",
+    ...LOCAL_ONLY_EXCLUDE_PATTERNS,
+    LOCAL_ONLY_EXCLUDE_END
+  ].join("\n");
+  if (result.dryRun) {
+    (excludeExists ? result.updated : result.created).push(excludePath);
+    return;
+  }
+  const prefix = existing.trimEnd();
+  await writeTextFile(excludePath, `${prefix ? `${prefix}
+
+` : ""}${block}
+`);
+  (excludeExists ? result.updated : result.created).push(excludePath);
+}
+async function upsertLocalOnlyNotice(filePath, result) {
+  const existing = await readTextIfExists(filePath);
+  if (existing.includes(LOCAL_ONLY_NOTICE_START)) return;
+  if (result.dryRun) {
+    (existing ? result.updated : result.created).push(filePath);
+    return;
+  }
+  await writeTextFile(filePath, `${existing.trimEnd()}
+
+${LOCAL_ONLY_NOTICE}
+`);
+  (existing ? result.updated : result.created).push(filePath);
+}
 async function resolveComparablePath(filePath) {
   try {
     return await realpath(filePath);
@@ -420,6 +494,9 @@ async function initializeAgentLoop(options) {
       "Refusing to initialize your home directory. Run this inside a project repository, or pass --force if you intentionally want AgentLoopKit files in your home directory."
     );
   }
+  if (options.localOnly) {
+    await upsertLocalOnlyGitExclude(cwd, result);
+  }
   const packageManager = await detectPackageManager(cwd);
   const projectType = await detectProjectType(cwd);
   const projectName = await detectProjectName(cwd);
@@ -438,7 +515,8 @@ async function initializeAgentLoop(options) {
     lintCommand: commands.lint || "not configured",
     typecheckCommand: commands.typecheck || "not configured",
     buildCommand: commands.build || "not configured",
-    formatCommand: commands.format || "not configured"
+    formatCommand: commands.format || "not configured",
+    localOnlyInstructions: options.localOnly ? LOCAL_ONLY_NOTICE : ""
   };
   for (const group of TEMPLATE_GROUPS) {
     if (group === "tasks") continue;
@@ -480,6 +558,10 @@ async function initializeAgentLoop(options) {
     await readTemplate("root/AGENTLOOP.md", values),
     result
   );
+  if (options.localOnly) {
+    await upsertLocalOnlyNotice(path6.join(cwd, AGENTS_FILE), result);
+    await upsertLocalOnlyNotice(path6.join(cwd, AGENTLOOP_FILE), result);
+  }
   const configPath = path6.join(cwd, CONFIG_FILE);
   if (await pathExists(configPath)) {
     result.skipped.push(configPath);
@@ -502,29 +584,43 @@ var consoleLogger = {
 
 // src/cli/commands/init.ts
 function initCommand() {
-  return new Command("init").description("Initialize AgentLoopKit in the current repository").option("--dry-run", "show planned changes without writing files").option("--json", "print machine-readable output").option("--force", "allow initialization when the current directory is your home directory").action(async (options) => {
-    const result = await initializeAgentLoop({
-      cwd: process.cwd(),
-      dryRun: options.dryRun,
-      force: options.force
-    });
-    if (options.json) {
-      consoleLogger.info(JSON.stringify(result, null, 2));
-      return;
-    }
-    consoleLogger.info(
-      options.dryRun ? "AgentLoopKit init dry run complete." : "AgentLoopKit initialized."
-    );
-    consoleLogger.info(`Created: ${result.created.length}`);
-    consoleLogger.info(`Updated: ${result.updated.length}`);
-    consoleLogger.info(`Skipped: ${result.skipped.length}`);
-    if (!options.dryRun) {
-      consoleLogger.info("\nNext steps:");
-      consoleLogger.info("- Review AGENTS.md and AGENTLOOP.md");
-      consoleLogger.info("- Run agentloop doctor");
-      consoleLogger.info("- Create a task with agentloop create-task");
+  return new Command("init").description("Initialize AgentLoopKit in the current repository").option("--dry-run", "show planned changes without writing files").option("--json", "print machine-readable output").option("--force", "allow initialization when the current directory is your home directory").option(
+    "--local-only",
+    "keep generated AgentLoopKit files out of git by updating this repo clone .git/info/exclude"
+  ).action(
+    async (options) => {
+      const result = await initializeAgentLoop({
+        cwd: process.cwd(),
+        dryRun: options.dryRun,
+        force: options.force,
+        localOnly: options.localOnly
+      });
+      if (options.json) {
+        consoleLogger.info(JSON.stringify(result, null, 2));
+        return;
+      }
+      consoleLogger.info(
+        options.dryRun ? "AgentLoopKit init dry run complete." : "AgentLoopKit initialized."
+      );
+      consoleLogger.info(`Created: ${result.created.length}`);
+      consoleLogger.info(`Updated: ${result.updated.length}`);
+      consoleLogger.info(`Skipped: ${result.skipped.length}`);
+      if (result.localOnly) {
+        consoleLogger.info("\nLocal-only mode:");
+        consoleLogger.info(`- Updated exclude file: ${result.localOnly.excludePath}`);
+        consoleLogger.info(
+          "- AgentLoopKit files stay on disk for local agents but stay out of git status."
+        );
+        consoleLogger.info("- Undo: remove the agentloopkit:local-only block from .git/info/exclude.");
+      }
+      if (!options.dryRun) {
+        consoleLogger.info("\nNext steps:");
+        consoleLogger.info("- Review AGENTS.md and AGENTLOOP.md");
+        consoleLogger.info("- Run agentloop doctor");
+        consoleLogger.info("- Create a task with agentloop create-task");
+      }
     }
-  });
+  );
 }
 
 // src/cli/commands/doctor.ts
@@ -1268,7 +1364,7 @@ import { readFile as readFile8 } from "fs/promises";
 
 // src/core/artifacts.ts
 import path11 from "path";
-import { readdir as readdir4, stat as stat2 } from "fs/promises";
+import { readdir as readdir4, stat as stat3 } 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$/;
@@ -1279,7 +1375,7 @@ async function latestMarkdownFile(dir, options = {}) {
       (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);
+      const fileStat = await stat3(filePath);
       return { filePath, name: entry.name, mtimeMs: fileStat.mtimeMs };
     })
   );
@@ -1292,7 +1388,7 @@ async function latestMarkdownFile(dir, options = {}) {
 
 // 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";
+import { mkdir as mkdir2, readdir as readdir5, readFile as readFile7, rename, rm, stat as stat4 } 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");
@@ -1337,7 +1433,7 @@ async function resolveTaskPath(options) {
     if (!options.strict) return void 0;
     throw new AgentLoopError("Active task must be a Markdown file.");
   }
-  const fileStat = await stat3(absolutePath).catch(() => void 0);
+  const fileStat = await stat4(absolutePath).catch(() => void 0);
   if (!fileStat?.isFile()) {
     if (!options.strict) return void 0;
     throw new AgentLoopError(`Task contract not found: ${options.taskPath}`);
@@ -1444,7 +1540,7 @@ async function listTasks(options) {
       const filePath = path12.join(root, entry.name);
       const [metadata, fileStat] = await Promise.all([
         readTaskMetadata(options.cwd, filePath),
-        stat3(filePath)
+        stat4(filePath)
       ]);
       return {
         ...metadata,
@@ -1776,7 +1872,7 @@ import { Command as Command9 } from "commander";
 
 // src/core/status.ts
 import path15 from "path";
-import { readFile as readFile9, stat as stat4 } from "fs/promises";
+import { readFile as readFile9, stat as stat5 } from "fs/promises";
 function extractHeading2(markdown, fallback) {
   return markdown.match(/^#\s+(.+)$/m)?.[1]?.trim() || fallback;
 }
@@ -1789,7 +1885,7 @@ function extractOverallStatus(markdown) {
 async function readTask(cwd, filePath) {
   if (!filePath) return void 0;
   const markdown = await readFile9(filePath, "utf8");
-  const fileStat = await stat4(filePath);
+  const fileStat = await stat5(filePath);
   return {
     path: path15.relative(cwd, filePath),
     title: extractHeading2(markdown, path15.basename(filePath, ".md")),
@@ -1800,7 +1896,7 @@ async function readTask(cwd, filePath) {
 async function readReport(cwd, filePath) {
   if (!filePath) return void 0;
   const markdown = await readFile9(filePath, "utf8");
-  const fileStat = await stat4(filePath);
+  const fileStat = await stat5(filePath);
   return {
     path: path15.relative(cwd, filePath),
     title: extractHeading2(markdown, path15.basename(filePath, ".md")),
@@ -2566,7 +2662,7 @@ 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";
+import { readFile as readFile11, readdir as readdir6, stat as stat6 } from "fs/promises";
 function escapeHtml(value) {
   return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -2598,7 +2694,7 @@ async function latestMatchingMarkdownFile(dir, pattern) {
   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);
+      const fileStat = await stat6(filePath);
       return { filePath, name: entry.name, mtimeMs: fileStat.mtimeMs };
     })
   );
@@ -2827,7 +2923,7 @@ 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";
+import { readFile as readFile12, readdir as readdir7, stat as stat7 } 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;");
@@ -2858,7 +2954,7 @@ async function latestVerificationReport(dir) {
   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);
+      const fileStat = await stat7(filePath);
       return { filePath, name: entry.name, mtimeMs: fileStat.mtimeMs };
     })
   );
@@ -2996,7 +3092,7 @@ 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";
+import { readdir as readdir8, readFile as readFile13, stat as stat8 } from "fs/promises";
 function policyRoot(cwd, config) {
   return path19.resolve(cwd, config.paths.agentloopDir, "policies");
 }
@@ -3013,7 +3109,7 @@ function normalizeContent(content) {
   return content.replace(/\r\n/g, "\n");
 }
 async function ensurePolicyRoot(root) {
-  const rootStat = await stat7(root).catch(() => void 0);
+  const rootStat = await stat8(root).catch(() => void 0);
   if (!rootStat?.isDirectory()) {
     throw new AgentLoopError(
       "No AgentLoopKit policy files found. Run `agentloop init` to generate .agentloop/policies/."