agentplane 0.2.26 → 0.3.2

package/assets/policy/workflow.release.md

@@ -0,0 +1,31 @@
+# Workflow: release
+
+Use this module when task touches release/version/publish flows.
+
+## Required sequence
+
+1. CHECKPOINT A: confirm clean tracked tree and approved scope.
+2. CHECKPOINT B: generate release plan and freeze version/tag target.
+3. Generate release notes with complete human-readable coverage of all task-level changes.
+4. Run release prepublish checks.
+5. CHECKPOINT C: apply release and push/tag only after all gates pass.
+6. Record release evidence (commands, outputs, resulting version/tag).
+
+## Command contract
+
+```bash
+git status --short --untracked-files=no
+agentplane task plan set <task-id> --text "Release plan: version=<v>, tag=<t>, scope=<...>" --updated-by <ROLE>
+agentplane task plan approve <task-id> --by ORCHESTRATOR
+agentplane release plan --patch
+agentplane release apply --push --yes
+agentplane verify <task-id> --ok|--rework --by <ROLE> --note "Release checks: ..."
+agentplane finish <task-id> --author <ROLE> --body "Verified: release" --result "Release <v> published" --commit <git-rev> --close-commit
+```
+
+## Constraints
+
+- MUST NOT perform irreversible release actions before explicit approval.
+- MUST NOT skip parity/version checks.
+- MUST NOT bypass required notes validation.
+- MUST stop and request re-approval if release scope/tag/version changes.

package/assets/policy/workflow.upgrade.md

@@ -0,0 +1,20 @@
+# Workflow: upgrade
+
+Use this module when task runs `agentplane upgrade` or touches `.agentplane/.upgrade/**`.
+
+## Required sequence
+
+1. Run upgrade command and capture run directory.
+2. Read upgrade review report:
+   - agent mode: `.agentplane/.upgrade/agent/<runId>/review.json`
+   - auto mode: `.agentplane/.upgrade/last-review.json`
+3. Apply upgrade as replace-all for managed files (`agentplane upgrade --auto`), excluding task data paths.
+4. For `.agentplane/policy/incidents.md`, keep existing local content and append incoming policy content (never replace non-empty local incidents file).
+5. Ensure the upgrade produced a dedicated upgrade commit with version in commit message.
+6. Verify policy/agent consistency and routing checks.
+7. Record run path and reviewed files in task notes.
+
+## Minimum verification
+
+- `node .agentplane/policy/check-routing.mjs`
+- `agentplane agents`

package/bin/agentplane.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
-import { execFileSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
-import { readFile, stat } from "node:fs/promises";
+import { stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
+import { distExists, isPackageBuildFresh } from "./dist-guard.js";
+import { resolveFrameworkBinaryContext } from "./runtime-context.js";
 
 async function exists(p) {
   try {
@@ -14,15 +16,12 @@ async function exists(p) {
 }
 
 async function maybeWarnGlobalBinaryInRepoCheckout() {
-  const cwd = process.cwd();
-  const repoCli = path.join(cwd, "packages", "agentplane", "src", "cli.ts");
-  const repoBin = path.join(cwd, "packages", "agentplane", "bin", "agentplane.js");
-  if (!(await exists(repoCli)) || !(await exists(repoBin))) return;
-
   const thisBin = fileURLToPath(import.meta.url);
+  const context = resolveFrameworkBinaryContext({ cwd: process.cwd(), thisBin });
+  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return;
+
   const normalizedThis = path.resolve(thisBin);
-  const normalizedRepo = path.resolve(repoBin);
-  if (normalizedThis === normalizedRepo) return;
+  const normalizedRepo = path.resolve(context.checkout.repoBin);
 
   process.stderr.write(
     "warning: running global agentplane binary inside repository checkout.\n" +
@@ -36,88 +35,65 @@ async function maybeWarnGlobalBinaryInRepoCheckout() {
   );
 }
 
-async function readJsonIfExists(p) {
-  let raw = "";
-  try {
-    raw = await readFile(p, "utf8");
-  } catch {
-    return null;
-  }
-  try {
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
+function shouldUseGlobalBinaryInFramework() {
+  return (process.env.AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK ?? "").trim() === "1";
 }
 
-function resolveGitHead(cwd) {
-  try {
-    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim() || null;
-  } catch {
-    return null;
-  }
+function isRepoLocalHandoffInvocation() {
+  return (process.env.AGENTPLANE_REPO_LOCAL_HANDOFF ?? "").trim() === "1";
 }
 
-function hasSrcChanges(cwd) {
-  try {
-    const out = execFileSync(
-      "git",
-      ["status", "--porcelain", "--untracked-files=all", "--", "src"],
-      {
-        cwd,
-        encoding: "utf8",
-      },
-    );
-    return out.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
+function handoffToRepoLocalBinary(context) {
+  const repoBin = context.checkout?.repoBin;
+  if (!repoBin) return false;
 
-async function fileMtimeMs(p) {
-  try {
-    const s = await stat(p);
-    if (!s.isFile()) return null;
-    return s.mtimeMs;
-  } catch {
-    return null;
+  process.stderr.write(
+    `info: detected framework checkout; delegating to repo-local binary: ${repoBin}\n`,
+  );
+
+  const result = spawnSync(process.execPath, [repoBin, ...process.argv.slice(2)], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      AGENTPLANE_REPO_LOCAL_HANDOFF: "1",
+    },
+  });
+
+  if (result.error) {
+    process.stderr.write(`error: failed to launch repo-local binary: ${result.error.message}\n`);
+    process.exitCode = 2;
+    return true;
   }
+
+  process.exitCode = result.status ?? (result.signal ? 1 : 0);
+  return true;
 }
 
-async function isPackageBuildFresh(packageRoot) {
-  const manifestPath = path.join(packageRoot, "dist", ".build-manifest.json");
-  const manifest = await readJsonIfExists(manifestPath);
-  if (!manifest || manifest.schema_version !== 1) {
-    return { ok: false, reason: "manifest_missing" };
-  }
+function maybeHandoffToRepoLocalBinary() {
+  if (shouldUseGlobalBinaryInFramework() || isRepoLocalHandoffInvocation()) return false;
 
-  const currentHead = resolveGitHead(packageRoot);
-  if (manifest.git_head && currentHead && manifest.git_head !== currentHead) {
-    return { ok: false, reason: "git_head_changed" };
-  }
+  const context = resolveFrameworkBinaryContext({
+    cwd: process.cwd(),
+    thisBin: fileURLToPath(import.meta.url),
+  });
+  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return false;
 
-  if (hasSrcChanges(packageRoot)) {
-    return { ok: false, reason: "src_dirty" };
-  }
+  return handoffToRepoLocalBinary(context);
+}
 
-  const srcCliMtimeMs = await fileMtimeMs(path.join(packageRoot, "src", "cli.ts"));
-  const srcIndexMtimeMs = await fileMtimeMs(path.join(packageRoot, "src", "index.ts"));
-  if (
-    typeof manifest.src_cli_mtime_ms === "number" &&
-    typeof srcCliMtimeMs === "number" &&
-    srcCliMtimeMs > manifest.src_cli_mtime_ms
-  ) {
-    return { ok: false, reason: "src_cli_newer_than_manifest" };
-  }
-  if (
-    typeof manifest.src_index_mtime_ms === "number" &&
-    typeof srcIndexMtimeMs === "number" &&
-    srcIndexMtimeMs > manifest.src_index_mtime_ms
-  ) {
-    return { ok: false, reason: "src_index_newer_than_manifest" };
+function isHooksRunCommitMsgInvocation(argv) {
+  const args = argv.slice(2).map((value) => String(value ?? "").trim());
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] !== "hooks") continue;
+    return args[i + 1] === "run" && args[i + 2] === "commit-msg";
   }
+  return false;
+}
 
-  return { ok: true, reason: "fresh" };
+function isPathInside(baseDir, targetPath) {
+  const rel = path.relative(path.resolve(baseDir), path.resolve(targetPath));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
 }
 
 async function assertDistUpToDate() {
@@ -127,8 +103,7 @@ async function assertDistUpToDate() {
   if (!inRepo) return true;
 
   const allowStale = (process.env.AGENTPLANE_DEV_ALLOW_STALE_DIST ?? "").trim() === "1";
-  const agentplaneDistDir = path.join(agentplaneRoot, "dist");
-  if (!(await exists(agentplaneDistDir))) {
+  if (!(await distExists(agentplaneRoot))) {
     process.stderr.write(
       "error: agentplane dist is missing for this repo checkout.\n" +
         "Fix:\n" +
@@ -141,16 +116,40 @@ async function assertDistUpToDate() {
 
   const repoRoot = path.resolve(agentplaneRoot, "..", "..");
   const coreRoot = path.join(repoRoot, "packages", "core");
-  const checks = [{ name: "agentplane", root: agentplaneRoot }];
-  if (await exists(path.join(coreRoot, "src"))) checks.push({ name: "core", root: coreRoot });
+  const checks = [
+    {
+      name: "agentplane",
+      root: agentplaneRoot,
+      watchedPaths: ["src", "bin/agentplane.js", "bin/dist-guard.js"],
+    },
+  ];
+  if (await exists(path.join(coreRoot, "src")))
+    checks.push({ name: "core", root: coreRoot, watchedPaths: ["src"] });
 
   const staleReasons = [];
   for (const check of checks) {
-    const result = await isPackageBuildFresh(check.root);
-    if (!result.ok) staleReasons.push(`${check.name}:${result.reason}`);
+    const result = await isPackageBuildFresh(check.root, { watchedPaths: check.watchedPaths });
+    if (!result.ok) {
+      const detail =
+        Array.isArray(result.changedPaths) && result.changedPaths.length > 0
+          ? `(${result.changedPaths.slice(0, 5).join(", ")}${result.changedPaths.length > 5 ? ", ..." : ""})`
+          : "";
+      staleReasons.push(`${check.name}:${result.reason}${detail}`);
+    }
   }
 
   if (staleReasons.length > 0 && !allowStale) {
+    const runningInsideCheckout = isPathInside(repoRoot, process.cwd());
+    if (!runningInsideCheckout) {
+      process.stderr.write(
+        "warning: linked development binary has a stale build, but current working directory is outside the agentplane checkout.\n" +
+          "proceeding with existing dist output.\n" +
+          `detected: ${staleReasons.join(", ")}\n` +
+          "tip: rebuild (`bun run --filter=@agentplaneorg/core build && bun run --filter=agentplane build`) or reinstall from npm for stable global usage.\n",
+      );
+      return true;
+    }
+
     process.stderr.write(
       "error: refusing to run a stale repo build (manifest/git quick-check failed).\n" +
         "Fix:\n" +
@@ -166,6 +165,8 @@ async function assertDistUpToDate() {
   return true;
 }
 
-await maybeWarnGlobalBinaryInRepoCheckout();
-const ok = await assertDistUpToDate();
-if (ok) await import("../dist/cli.js");
+if (!maybeHandoffToRepoLocalBinary()) {
+  await maybeWarnGlobalBinaryInRepoCheckout();
+  const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();
+  if (ok) await import("../dist/cli.js");
+}

package/bin/dist-guard.js

@@ -0,0 +1,124 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { readFile, stat } from "node:fs/promises";
+
+async function exists(p) {
+  try {
+    await stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonIfExists(p) {
+  let raw = "";
+  try {
+    raw = await readFile(p, "utf8");
+  } catch {
+    return null;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function resolveGitHead(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function listGitPaths(cwd, args) {
+  try {
+    const out = execFileSync("git", args, { cwd, encoding: "utf8" });
+    return out
+      .split(/\r?\n/u)
+      .map((line) => line.trim())
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function uniqueSorted(values) {
+  return [...new Set(values)].toSorted((a, b) => a.localeCompare(b));
+}
+
+function workingTreeChangedPaths(cwd, watchedPaths) {
+  const lines = listGitPaths(cwd, [
+    "status",
+    "--porcelain",
+    "--untracked-files=all",
+    "--",
+    ...watchedPaths,
+  ]);
+  return uniqueSorted(lines.map((line) => line.slice(3).trim()).filter(Boolean));
+}
+
+function committedChangedPathsSince(cwd, fromGitHead, watchedPaths) {
+  if (!fromGitHead) return [];
+  return uniqueSorted(
+    listGitPaths(cwd, ["diff", "--name-only", `${fromGitHead}..HEAD`, "--", ...watchedPaths]),
+  );
+}
+
+async function fileMtimeMs(p) {
+  try {
+    const s = await stat(p);
+    if (!s.isFile()) return null;
+    return s.mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+export async function isPackageBuildFresh(packageRoot, options = {}) {
+  const watchedPaths = options.watchedPaths ?? ["src"];
+  const manifestPath = path.join(packageRoot, "dist", ".build-manifest.json");
+  const manifest = await readJsonIfExists(manifestPath);
+  if (!manifest || manifest.schema_version !== 1) {
+    return { ok: false, reason: "manifest_missing", changedPaths: [] };
+  }
+
+  const currentHead = resolveGitHead(packageRoot);
+  const changedPaths = uniqueSorted([
+    ...committedChangedPathsSince(packageRoot, manifest.git_head, watchedPaths),
+    ...workingTreeChangedPaths(packageRoot, watchedPaths),
+  ]);
+
+  if (changedPaths.length > 0) {
+    return { ok: false, reason: "watched_paths_changed", changedPaths };
+  }
+
+  const srcCliMtimeMs = await fileMtimeMs(path.join(packageRoot, "src", "cli.ts"));
+  const srcIndexMtimeMs = await fileMtimeMs(path.join(packageRoot, "src", "index.ts"));
+  if (
+    typeof manifest.src_cli_mtime_ms === "number" &&
+    typeof srcCliMtimeMs === "number" &&
+    srcCliMtimeMs > manifest.src_cli_mtime_ms
+  ) {
+    return { ok: false, reason: "src_cli_newer_than_manifest", changedPaths: [] };
+  }
+  if (
+    typeof manifest.src_index_mtime_ms === "number" &&
+    typeof srcIndexMtimeMs === "number" &&
+    srcIndexMtimeMs > manifest.src_index_mtime_ms
+  ) {
+    return { ok: false, reason: "src_index_newer_than_manifest", changedPaths: [] };
+  }
+
+  if (manifest.git_head && currentHead && manifest.git_head !== currentHead) {
+    return { ok: true, reason: "fresh_after_non_runtime_head_change", changedPaths: [] };
+  }
+
+  return { ok: true, reason: "fresh", changedPaths: [] };
+}
+
+export async function distExists(packageRoot) {
+  return await exists(path.join(packageRoot, "dist"));
+}

package/bin/runtime-context.d.ts

@@ -0,0 +1,20 @@
+export type FrameworkCheckout = {
+  repoRoot: string;
+  packageRoot: string;
+  repoBin: string;
+  repoCli: string;
+};
+
+export type FrameworkBinaryContext = {
+  inFrameworkCheckout: boolean;
+  isRepoLocalBinary: boolean;
+  checkout: FrameworkCheckout | null;
+  thisBin: string;
+};
+
+export function findFrameworkCheckout(startDir: string): FrameworkCheckout | null;
+
+export function resolveFrameworkBinaryContext(options: {
+  cwd: string;
+  thisBin: string;
+}): FrameworkBinaryContext;

package/bin/runtime-context.js

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * @typedef {{
+ *   repoRoot: string;
+ *   packageRoot: string;
+ *   repoBin: string;
+ *   repoCli: string;
+ * }} FrameworkCheckout
+ */
+
+/**
+ * @typedef {{
+ *   cwd: string;
+ *   thisBin: string;
+ * }} FrameworkBinaryContextOptions
+ */
+
+/**
+ * @typedef {{
+ *   inFrameworkCheckout: boolean;
+ *   isRepoLocalBinary: boolean;
+ *   checkout: FrameworkCheckout | null;
+ *   thisBin: string;
+ * }} FrameworkBinaryContext
+ */
+
+function fileExists(p) {
+  return existsSync(p);
+}
+
+/**
+ * @param {string} startDir
+ * @returns {FrameworkCheckout | null}
+ */
+export function findFrameworkCheckout(startDir) {
+  let dir = path.resolve(startDir);
+  for (;;) {
+    const packageRoot = path.join(dir, "packages", "agentplane");
+    const repoBin = path.join(packageRoot, "bin", "agentplane.js");
+    const repoCli = path.join(packageRoot, "src", "cli.ts");
+    if (fileExists(repoBin) && fileExists(repoCli)) {
+      return {
+        repoRoot: dir,
+        packageRoot,
+        repoBin,
+        repoCli,
+      };
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * @param {FrameworkBinaryContextOptions} options
+ * @returns {FrameworkBinaryContext}
+ */
+export function resolveFrameworkBinaryContext(options) {
+  const cwd = path.resolve(options.cwd);
+  const thisBin = path.resolve(options.thisBin);
+  const checkout = findFrameworkCheckout(cwd);
+  if (!checkout) {
+    return {
+      inFrameworkCheckout: false,
+      isRepoLocalBinary: false,
+      checkout: null,
+      thisBin,
+    };
+  }
+
+  return {
+    inFrameworkCheckout: true,
+    isRepoLocalBinary: path.resolve(checkout.repoBin) === thisBin,
+    checkout,
+    thisBin,
+  };
+}

package/dist/.build-manifest.json

@@ -1,11 +1,11 @@
 {
   "schema_version": 1,
   "package_dir": "/home/runner/work/agentplane/agentplane/packages/agentplane",
-  "generated_at": "2026-03-05T13:42:04.968Z",
-  "git_head": "7fdf3f088d7d98748b9ef5db06f5bef3766b534d",
-  "src_cli_mtime_ms": 1772718067546.3232,
+  "generated_at": "2026-03-07T17:34:46.688Z",
+  "git_head": "8ffbebd27d5fa6dcf906b1781f8fe2d0030c6c98",
+  "src_cli_mtime_ms": 1772904835121.3193,
   "src_index_mtime_ms": null,
-  "dist_cli_mtime_ms": 1772718124490.9443,
+  "dist_cli_mtime_ms": 1772904886214.584,
   "dist_index_mtime_ms": null,
-  "tsbuildinfo_mtime_ms": 1772718124554.9443
+  "tsbuildinfo_mtime_ms": 1772904886278.5845
 }

package/dist/agents/agents-template.d.ts

@@ -1,10 +1,17 @@
+import { type PolicyGatewayFlavor } from "../shared/policy-gateway.js";
 export type WorkflowMode = "direct" | "branch_pr";
 type AgentTemplate = {
     fileName: string;
     contents: string;
 };
+export type PolicyTemplate = {
+    relativePath: string;
+    contents: string;
+};
 export declare function loadAgentsTemplate(): Promise<string>;
 export declare function loadAgentTemplates(): Promise<AgentTemplate[]>;
+export declare function loadPolicyTemplates(): Promise<PolicyTemplate[]>;
 export declare function filterAgentsByWorkflow(template: string, workflow: WorkflowMode): string;
+export declare function loadPolicyGatewayTemplate(flavor: PolicyGatewayFlavor): Promise<string>;
 export {};
 //# sourceMappingURL=agents-template.d.ts.map

package/dist/agents/agents-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents-template.d.ts","sourceRoot":"","sources":["../../src/agents/agents-template.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElD,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAwC5D,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAG1D;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAanE;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,MAAM,CASvF"}
+{"version":3,"file":"agents-template.d.ts","sourceRoot":"","sources":["../../src/agents/agents-template.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAUrC,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,CAAC;AAElD,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5D,MAAM,MAAM,cAAc,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAwCxE,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAE1D;AAED,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAanE;AAsBD,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAerE;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,MAAM,CASvF;AAED,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5F"}

package/dist/agents/agents-template.js

@@ -1,8 +1,10 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { policyGatewayFileName, renderPolicyGatewayTemplateText, } from "../shared/policy-gateway.js";
 const AGENTS_TEMPLATE_URL = new URL("../../assets/AGENTS.md", import.meta.url);
 const AGENTS_DIR_URL = new URL("../../assets/agents/", import.meta.url);
+const POLICY_DIR_URL = new URL("../../assets/policy/", import.meta.url);
 const HEADING_RE = /^(#+)\s+(.*)$/;
 function ensureTrailingNewline(text) {
     return text.endsWith("\n") ? text : `${text}\n`;
@@ -41,8 +43,7 @@ function removeSections(lines, titles) {
     return lines.filter((_line, index) => !shouldRemove.has(index));
 }
 export async function loadAgentsTemplate() {
-    const text = await readFile(AGENTS_TEMPLATE_URL, "utf8");
-    return ensureTrailingNewline(text.trimEnd());
+    return loadPolicyGatewayTemplate("codex");
 }
 export async function loadAgentTemplates() {
     const dirPath = fileURLToPath(AGENTS_DIR_URL);
@@ -56,6 +57,39 @@ export async function loadAgentTemplates() {
     }
     return templates;
 }
+async function listFilesRecursive(dirPath, relPrefix = "") {
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    const sorted = entries.toSorted((a, b) => a.name.localeCompare(b.name));
+    const files = [];
+    for (const entry of sorted) {
+        // Ignore editor/OS hidden metadata files.
+        if (entry.name.startsWith("."))
+            continue;
+        const absPath = path.join(dirPath, entry.name);
+        const relPath = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...(await listFilesRecursive(absPath, relPath)));
+            continue;
+        }
+        if (entry.isFile())
+            files.push(relPath);
+    }
+    return files;
+}
+export async function loadPolicyTemplates() {
+    const dirPath = fileURLToPath(POLICY_DIR_URL);
+    const relFiles = await listFilesRecursive(dirPath);
+    const templates = [];
+    for (const relFile of relFiles) {
+        const filePath = path.join(dirPath, relFile);
+        const contents = await readFile(filePath, "utf8");
+        templates.push({
+            relativePath: relFile.replaceAll("\\", "/"),
+            contents: ensureTrailingNewline(contents.trimEnd()),
+        });
+    }
+    return templates;
+}
 export function filterAgentsByWorkflow(template, workflow) {
     const lines = template.replaceAll("\r\n", "\n").split("\n");
     const removeTitles = workflow === "direct"
@@ -64,3 +98,8 @@ export function filterAgentsByWorkflow(template, workflow) {
     const filtered = removeSections(lines, removeTitles);
     return ensureTrailingNewline(filtered.join("\n").trimEnd());
 }
+export async function loadPolicyGatewayTemplate(flavor) {
+    const text = await readFile(AGENTS_TEMPLATE_URL, "utf8");
+    const rendered = renderPolicyGatewayTemplateText(text, policyGatewayFileName(flavor));
+    return ensureTrailingNewline(rendered.trimEnd());
+}

package/dist/cli/bootstrap-guide.d.ts

@@ -0,0 +1,18 @@
+export declare const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
+export type BootstrapSection = {
+    heading: string;
+    summary: string;
+    commands: readonly string[];
+    notes?: readonly string[];
+};
+export declare const BOOTSTRAP_PREFLIGHT_COMMANDS: readonly ["agentplane config show", "agentplane quickstart", "agentplane task list", "git status --short --untracked-files=no", "git rev-parse --abbrev-ref HEAD"];
+export declare const BOOTSTRAP_TASK_PREP_COMMANDS: string[];
+export declare const BOOTSTRAP_TASK_LIFECYCLE_COMMANDS: readonly [...string[], "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
+export declare const BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS: readonly ["agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
+export declare const BOOTSTRAP_VERIFICATION_COMMANDS: readonly ["agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane doctor", "node .agentplane/policy/check-routing.mjs"];
+export declare const BOOTSTRAP_RECOVERY_COMMANDS: readonly ["agentplane doctor", "agentplane upgrade --dry-run", "agentplane upgrade"];
+export declare const BOOTSTRAP_SECTIONS: readonly BootstrapSection[];
+export declare function renderBootstrapReferenceLine(): string;
+export declare function renderBootstrapSectionLines(sections: readonly BootstrapSection[]): string[];
+export declare function renderBootstrapDoc(): string;
+//# sourceMappingURL=bootstrap-guide.d.ts.map

package/dist/cli/bootstrap-guide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap-guide.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap-guide.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,4CAA4C,CAAC;AAElF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,oKAM/B,CAAC;AAEX,eAAO,MAAM,4BAA4B,UAIxC,CAAC;AAEF,eAAO,MAAM,iCAAiC,2RAKpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,wOAIvC,CAAC;AAEX,eAAO,MAAM,+BAA+B,8LAKlC,CAAC;AAEX,eAAO,MAAM,2BAA2B,sFAI9B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EA+ChD,CAAC;AAEX,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAiB3F;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CA0B3C"}