agentplane 0.2.26 → 0.3.1

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,8 @@
 #!/usr/bin/env node
-import { execFileSync } 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";
 
 async function exists(p) {
   try {
@@ -36,88 +36,18 @@ 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 resolveGitHead(cwd) {
-  try {
-    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim() || null;
-  } catch {
-    return null;
-  }
-}
-
-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;
-  }
-}
-
-async function fileMtimeMs(p) {
-  try {
-    const s = await stat(p);
-    if (!s.isFile()) return null;
-    return s.mtimeMs;
-  } catch {
-    return null;
+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;
 }
 
-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" };
-  }
-
-  const currentHead = resolveGitHead(packageRoot);
-  if (manifest.git_head && currentHead && manifest.git_head !== currentHead) {
-    return { ok: false, reason: "git_head_changed" };
-  }
-
-  if (hasSrcChanges(packageRoot)) {
-    return { ok: false, reason: "src_dirty" };
-  }
-
-  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" };
-  }
-
-  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 +57,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 +70,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" +
@@ -167,5 +120,5 @@ async function assertDistUpToDate() {
 }
 
 await maybeWarnGlobalBinaryInRepoCheckout();
-const ok = await assertDistUpToDate();
+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/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-06T15:25:37.651Z",
+  "git_head": "1be96fc47916b76925f9bc59ce7d24176216a87f",
+  "src_cli_mtime_ms": 1772810682734.0005,
   "src_index_mtime_ms": null,
-  "dist_cli_mtime_ms": 1772718124490.9443,
+  "dist_cli_mtime_ms": 1772810737168.81,
   "dist_index_mtime_ms": null,
-  "tsbuildinfo_mtime_ms": 1772718124554.9443
+  "tsbuildinfo_mtime_ms": 1772810737234.8098
 }

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/command-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AAkMA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA2FzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AA0MA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA6FzC"}

package/dist/cli/command-guide.js

@@ -32,6 +32,10 @@ const CHEAT_SHEET_ROWS = [
         operation: "CODER/TESTER/DOCS: start checkout (branch_pr)",
         command: "`agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
     },
+    {
+        operation: "CODER/TESTER: start task deterministically",
+        command: '`agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (run after successful `task plan approve`; do not run in parallel)',
+    },
     {
         operation: "CODER/TESTER/DOCS: update PR artifacts",
         command: "`agentplane pr update <task-id>`",
@@ -84,15 +88,17 @@ const ROLE_GUIDES = [
             "- `task new` auto-seeds README sections; use `task scaffold` only for backfill/import/manual repair.",
             '- Plan lifecycle: `agentplane task plan set <task-id> --text "..." --updated-by <ROLE>` -> `agentplane task plan approve <task-id> --by <id>`',
             "- Verify Steps discipline: if a task primary tag is verify-required (default: code/data/ops), fill `## Verify Steps` before plan approval.",
-            '- Task docs (when planning needs it): `agentplane task doc set <task-id> --section Summary --text "..."`',
+            "- Doc quality gate: `task plan approve` and `finish` fail when required agent-filled sections (`Summary/Scope/Plan/Risks/Rollback Plan`, per config) are empty/TODO placeholders.",
+            '- Task docs (when planning needs it): `agentplane task doc set <task-id> --section Summary --text "..."`; if `--text`/`--file` contains multiple known headings, the command applies it as one batched full-doc update.',
         ],
     },
     {
         role: "CODER",
         lines: [
-            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates.",
+            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates; batched doc updates are allowed before approval.",
             "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Status updates: `agentplane start <task-id> --author <ROLE> --body "Start: ..."` / `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
+            '- Start status (deterministic): `agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (after `task plan approve`, sequential only).',
+            '- Other status updates: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
             "- Verify Steps: `agentplane task verify-show <task-id>` (use as the verification contract before recording results).",
             '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
             '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
@@ -102,9 +108,10 @@ const ROLE_GUIDES = [
     {
         role: "TESTER",
         lines: [
-            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates.",
+            "- direct mode: single-stream in the current checkout; `agentplane work start <task-id> --agent <ROLE> --slug <slug>` records the active task and keeps the current branch (no task branches). Use `task doc set` / `task plan set` for normal docs updates; batched doc updates are allowed before approval.",
             "- branch_pr: `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-            '- Status updates: `agentplane start <task-id> --author <ROLE> --body "Start: ..."` / `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
+            '- Start status (deterministic): `agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."` (after `task plan approve`, sequential only).',
+            '- Other status updates: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`',
             "- Verify Steps: `agentplane task verify-show <task-id>` (treat as the verification contract).",
             '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
             '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
@@ -114,7 +121,7 @@ const ROLE_GUIDES = [
     {
         role: "DOCS",
         lines: [
-            '- Task docs: `agentplane task doc set <task-id> --section Summary --text "..."` (repeat per section or use `--file`)',
+            '- Task docs: `agentplane task doc set <task-id> --section Summary --text "..."` (repeat per section, or send one multi-heading full-doc payload via `--text`/`--file`)',
             '- PR notes: `agentplane pr note <task-id> --author DOCS --body "..."`',
             '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
         ],
@@ -137,7 +144,7 @@ const ROLE_GUIDES = [
     {
         role: "CREATOR",
         lines: [
-            '- Task bookkeeping: `agentplane task update <task-id> ...` / `agentplane start <task-id> --author CREATOR --body "Start: ..."`',
+            '- Task bookkeeping: `agentplane task update <task-id> ...` / `agentplane task start-ready <task-id> --author CREATOR --body "Start: ..."`',
             '- Commits: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>`',
         ],
     },
@@ -188,10 +195,10 @@ export function renderQuickstart() {
     return [
         "# agentplane quickstart",
         "",
-        "AGENTS.md is the source of truth for the workflow/process policy; quickstart and role output are the source of truth for CLI syntax and artifacts.",
+        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy; quickstart and role output are the source of truth for CLI syntax and artifacts.",
         "Do not edit `.agentplane/tasks.json` by hand.",
         "",
-        "- See AGENTS.md for the canonical workflow policy and approval gates.",
+        "- See your policy gateway file (AGENTS.md or CLAUDE.md) for canonical workflow policy and approval gates.",
         "",
         "## Project setup",
         "",
@@ -257,12 +264,14 @@ export function renderQuickstart() {
         "## Global flags",
         "",
         "- `--root <path>`: treat <path> as project root",
+        "- `--output <text|json>`: force global CLI output mode (`json` is agent-oriented envelope mode)",
         "- `--json-errors`: emit JSON-formatted errors",
         "- `--help` / `-h`: show help",
         "- `--version`: show version",
         "- `--no-update-check`: skip checking npm for a newer CLI version",
         "",
         "Notes:",
+        "- `AGENTPLANE_OUTPUT=json` enables global JSON output mode for agent runtimes.",
         "- `.env` at the repo root is loaded automatically (without overwriting existing environment variables).",
         "",
         "## Commit message format",

package/dist/cli/command-snippets.d.ts

@@ -3,7 +3,7 @@ export declare const COMMAND_SNIPPETS: {
         readonly taskList: "agentplane task list";
         readonly taskShow: "agentplane task show <task-id>";
         readonly taskNew: "agentplane task new --title \"...\" --description \"...\" --priority med --owner CODER --tag <tag>";
-        readonly startTask: "agentplane start <task-id> --author <ROLE> --body \"Start: ...\"";
+        readonly startTask: "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"";
         readonly verifyTask: "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"";
         readonly finishTask: "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --commit <git-rev> --close-commit";
         readonly quickstart: "agentplane quickstart";

package/dist/cli/command-snippets.js

@@ -3,7 +3,7 @@ export const COMMAND_SNIPPETS = {
         taskList: "agentplane task list",
         taskShow: "agentplane task show <task-id>",
         taskNew: 'agentplane task new --title "..." --description "..." --priority med --owner CODER --tag <tag>',
-        startTask: 'agentplane start <task-id> --author <ROLE> --body "Start: ..."',
+        startTask: 'agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."',
         verifyTask: 'agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."',
         finishTask: 'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev> --close-commit',
         quickstart: "agentplane quickstart",

package/dist/cli/run-cli/commands/core.js

@@ -37,7 +37,7 @@ async function cmdQuickstart(opts) {
                 .filter((line) => line.length > 0);
             const payload = {
                 source_of_truth: {
-                    workflow_policy: "AGENTS.md",
+                    workflow_policy: "AGENTS.md|CLAUDE.md",
                     cli_syntax: "quickstart/role output",
                 },
                 lines,
@@ -437,7 +437,7 @@ function renderAgentProfileBlock(opts) {
         ...(permissions.length > 0 ? ["", "Permissions:", ...permissions.map((s) => `- ${s}`)] : []),
         ...(workflow.length > 0 ? ["", "Workflow:", ...workflow.map((s) => `- ${s}`)] : []),
         "",
-        `Source: .agentplane/agents/${opts.filename} (lower priority; see AGENTS.md)`,
+        `Source: .agentplane/agents/${opts.filename} (lower priority; see policy gateway file AGENTS.md or CLAUDE.md)`,
     ];
     return lines.join("\n").trimEnd();
 }

package/dist/cli/run-cli/commands/ide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/ide.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAkBlD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF"}
+{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/ide.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAGrD,KAAK,aAAa,GAAG;IAAE,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,aAAa,CAkBlD,CAAC;AAEF,wBAAsB,UAAU,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CA4ClB;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAElF"}

package/dist/cli/run-cli/commands/ide.js

@@ -1,11 +1,12 @@
 import { mkdir, readFile } from "node:fs/promises";
 import path from "node:path";
 import { writeTextIfChanged } from "../../../shared/write-if-changed.js";
+import { resolvePolicyGatewayForRepo } from "../../../shared/policy-gateway.js";
 import { wrapCommand } from "./wrap-command.js";
 export const ideSyncSpec = {
     id: ["ide", "sync"],
     group: "IDE",
-    summary: "Generate IDE entrypoints from AGENTS.md.",
+    summary: "Generate IDE entrypoints from policy gateway file (AGENTS.md or CLAUDE.md).",
     options: [
         {
             kind: "string",
@@ -24,13 +25,17 @@ export const ideSyncSpec = {
 export async function cmdIdeSync(opts) {
     return wrapCommand({ command: "ide sync", rootOverride: opts.rootOverride }, async () => {
         const resolved = await opts.deps.getResolvedProject("ide sync");
-        const agentsPath = path.join(resolved.gitRoot, "AGENTS.md");
+        const gateway = await resolvePolicyGatewayForRepo({
+            gitRoot: resolved.gitRoot,
+            fallbackFlavor: "codex",
+        });
+        const agentsPath = gateway.absPath;
         const agentsText = await readFile(agentsPath, "utf8");
         const header = [
             "<!--",
             "  AUTOGENERATED by agentplane ide sync.",
             "  DO NOT EDIT MANUALLY.",
-            "  Source: AGENTS.md",
+            `  Source: ${gateway.fileName}`,
             "-->",
             "",
         ].join("\n");

package/dist/cli/run-cli/commands/init/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/ui.ts"],"names":[],"mappings":"AAyBA,wBAAgB,iBAAiB,IAAI,MAAM,CAY1C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG5E"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/ui.ts"],"names":[],"mappings":"AAyBA,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAG5E"}