agentplane 0.4.2 → 0.4.4

package/assets/codex-plugin/skills/agentplane/SKILL.md

@@ -15,21 +15,21 @@ Use AgentPlane through its CLI instead of editing `.agentplane/` state directly.
 
 ## Startup
 
-1. If the repository is not initialized, run `agentplane init`.
-2. Run `agentplane quickstart`.
-3. Inspect `AGENTS.md`, `agentplane task list`, `git status --short --untracked-files=no`, and `git rev-parse --abbrev-ref HEAD`.
-4. Use `agentplane role ORCHESTRATOR` while planning and approvals are active.
-5. Switch to `agentplane role <ROLE>` before owner-scoped execution or verification.
+1. If the repository is not initialized, run `ap init` or `agentplane init`.
+2. Run `ap quickstart`.
+3. Inspect `AGENTS.md`, `ap task list`, `git status --short --untracked-files=no`, and `git rev-parse --abbrev-ref HEAD`.
+4. Use `ap role ORCHESTRATOR` while planning and approvals are active.
+5. Switch to `ap role <ROLE>` before owner-scoped execution or verification.
 
 ## Rules
 
-- Treat `AGENTS.md`, `agentplane quickstart`, and `agentplane role <ROLE>` as the policy surface.
-- Use `agentplane task ...`, `agentplane work ...`, `agentplane verify ...`, and `agentplane finish ...`; do not edit `.agentplane/tasks.json` manually.
-- In `branch_pr`, start from `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`.
+- Treat `AGENTS.md`, `ap quickstart`, and `ap role <ROLE>` as the policy surface.
+- Use `ap task ...`, `ap work ...`, `ap verify ...`, and `ap finish ...`; do not edit `.agentplane/tasks.json` manually.
+- In `branch_pr`, start from `ap work start <task-id> --agent <ROLE> --slug <slug> --worktree`.
 - Keep repository artifacts in English unless the user explicitly requests another language for a specific artifact.
-- Record verification evidence in the task README and through `agentplane verify`.
+- Record verification evidence in the task README and through `ap verify`.
 
 ## Limits
 
-- This plugin bundles workflow guidance only. It does not install the `agentplane` binary for you.
-- If `agentplane` is missing from `PATH`, install it first, then use the workflow commands above.
+- This plugin bundles workflow guidance only. It does not install the `ap`/`agentplane` binary for you.
+- If both `ap` and `agentplane` are missing from `PATH`, install AgentPlane first, then use the workflow commands above.

package/assets/policy/check-routing.mjs

@@ -34,6 +34,46 @@ function assertFilesExist(repoRoot, paths, label, errors) {
   }
 }
 
+function remediationForRoutingError(error) {
+  if (error.includes("exceeds policy budget")) {
+    return {
+      code: "POLICY_ROUTING_BUDGET",
+      why: "Large gateway or policy modules make agent startup context harder to route deterministically.",
+      fix: "Move scenario-specific detail into the correct canonical module or shorten duplicate rule text.",
+      safeCommand: "node .agentplane/policy/check-routing.mjs",
+      stopCondition:
+        "Stop if the size reduction would remove a hard constraint or source-of-truth rule.",
+    };
+  }
+  if (error.includes("path does not exist") || error.includes("Missing canonical")) {
+    return {
+      code: "POLICY_ROUTING_MISSING_PATH",
+      why: "AGENTS.md references a policy file that agents cannot load.",
+      fix: "Restore the referenced file or update the gateway reference to the canonical existing path.",
+      safeCommand: "agentplane doctor",
+      stopCondition: "Stop if the missing file is a policy module deleted by another active task.",
+    };
+  }
+  return {
+    code: "POLICY_ROUTING_FAILED",
+    why: "The policy gateway no longer matches the deterministic load-rule contract.",
+    fix: "Repair AGENTS.md load rules, canonical docs, examples, or policy module layout.",
+    safeCommand: "node .agentplane/policy/check-routing.mjs",
+    stopCondition: "Stop if the repair changes workflow mode, approval gates, or policy ownership.",
+  };
+}
+
+function renderRemediation(error) {
+  const r = remediationForRoutingError(error);
+  return [
+    `  Code: ${r.code}`,
+    `  Why: ${r.why}`,
+    `  Fix: ${r.fix}`,
+    `  Safe command: ${r.safeCommand}`,
+    `  Stop condition: ${r.stopCondition}`,
+  ].join("\n");
+}
+
 function listFilesRecursive(dirPath, relPrefix = "") {
   if (!fs.existsSync(dirPath)) return [];
   const entries = fs.readdirSync(dirPath).toSorted((a, b) => a.localeCompare(b));
@@ -171,7 +211,11 @@ function main() {
   }
 
   if (errors.length > 0) {
-    throw new Error(`Policy routing check failed:\n- ${errors.join("\n- ")}`);
+    throw new Error(
+      `Policy routing check failed:\n${errors
+        .map((error) => `- ${error}\n${renderRemediation(error)}`)
+        .join("\n")}`,
+    );
   }
 
   process.stdout.write("policy routing OK\n");

package/assets/policy/incidents.md

@@ -13,3 +13,6 @@
 - id: INC-20260501-03 | date: 2026-05-01 | scope: Make post-publish release evidence PR recovery authenticate gh so successful releases do not end as failed after publication. | tags: ci, release, workflow | match: ci, release, workflow, make, post, publish, evidence, recovery, authenticate, successful, releases, not, end, failed, after, publication | failure: Release evidence gh CLI steps now set GH_TOKEN from github.token. | advice: Added GH_TOKEN env to release evidence PR check/create/merge steps and contract coverage. | rule: Analogous Make post-publish release evidence PR recovery authenticate gh so successful releases do not end as failed after publication. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605012054-HS993A; commit c329da9be70f | enforcement: manual | fixability: external | state: open
 - id: INC-20260501-04 | date: 2026-05-01 | scope: Update the Homebrew formula renderer and tap formula so fresh AgentPlane releases install without Homebrew npm min-release-age blocking fresh package dependencies. | tags: release, workflow | match: release, workflow, update, the, homebrew, formula, renderer, and, tap, fresh, agentplane, releases, install, without, npm, min | failure: Updated render-homebrew-formula to install the cached npm tarball without std_npm_args/min-release-age, added contract coverage, and pushed basilisk-labs/homebrew-tap c6d3e94 for v0.4.1. Local Homebrew install reached Cellar successfully; final link was blocked only by an existing /opt/homebrew/bin/agentplane npm-global symlink. | advice: Run brew link --overwrite agentplane when an old npm-global symlink is present; standalone no-Node install requires a future native/bundled CLI artifact. | rule: Analogous Update the Homebrew formula renderer and tap formula so fresh AgentPlane releases install without Homebrew npm min-release-age blocking fresh package dependencies. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605012143-NEK3E8; commit 43bc2ed84a23 | enforcement: manual | fixability: external | state: open
 - id: INC-20260503-01 | date: 2026-05-03 | scope: Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. | tags: code, release, workflow | match: code, release, workflow, port, the, artifacts, language, configuration, and, artifact, validation, from, stale, cli, branch, onto | failure: Ported artifacts_language=en and PR artifact language validation onto current main; stale trust branch was not merged because it would reintroduce old task states. | advice: No rework required before PR. | rule: Analogous Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030733-BHD4S4; commit c66cff3d6f16 | enforcement: manual | fixability: external | state: open
+- id: INC-20260503-02 | date: 2026-05-03 | scope: Update standalone release artifact smoke testing to accept the current doctor OK output and surface doctor output on failures so v0.4.2 publish can complete. | tags: code, release, testing | match: code, release, testing, update, standalone, artifact, smoke, accept, the, current, doctor, output, and, surface, failures, publish | failure: Publish run 25273723107 failed before npm/tag at standalone linux-x64 doctor smoke because the script expected 'doctor OK' but current CLI emits 'doctor (OK)'. | advice: Smoke now accepts both legacy and current doctor OK markers and includes doctor output on failure. | rule: Analogous Update standalone release artifact smoke testing to accept the current doctor OK output and surface doctor output on failures so v0.4.2 publish can complete. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030807-DBY2RS; commit 2c98719336c8 | enforcement: manual | fixability: external | state: open
+- id: INC-20260503-03 | date: 2026-05-03 | scope: Split AgentPlane default sign-off identity from repo-wide manual DCO validation and make .agentplane/tasks.json an optional generated export snapshot rather than tracked required state. | tags: code, git, tasks | match: code, git, tasks, split, agentplane, default, sign, off, identity, from, repo, wide, manual, dco, validation, and | failure: Full hook-run suite was not used as final evidence because an unrelated existing pre-push scenario still tries to git add .agentplane/config.json after the WORKFLOW-only migration. | advice: Focused checks pass; remaining doctor warning is outside this task scope. | rule: Analogous Split AgentPlane default sign-off identity from repo-wide manual DCO validation and make .agentplane/tasks.json an optional generated export snapshot rather than tracked required state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605031737-9A4FWX; commit eda55d00831b | enforcement: manual | fixability: external | state: open
+- id: INC-20260504-01 | date: 2026-05-04 | scope: Introduce a shared agent-facing remediation contract for diagnostic failures and apply it to high-value doctor, workflow, ACR, and policy routing surfaces. | tags: code | match: code, introduce, shared, agent, facing, remediation, contract, for, diagnostic, failures, and, apply, high, value, doctor, workflow | failure: Commands passed: focused bun tests for workflow/ACR/policy routing plus targeted stale-dist workspace dependency test; bun run typecheck; Prettier check on touched files; ESLint on touched files; bun run arch:check; git diff --check; bun run framework:dev:bootstrap; agentplane doctor; node .agentplane/policy/check-routing.mjs. | advice: No mandatory check remains skipped. The full stale-dist-readonly file still contains an unrelated pre-existing auto-bootstrap timeout when run under this ad hoc focused bundle; the new workspace dependency test passes independently. | rule: Analogous Introduce a shared agent-facing remediation contract for diagnostic failures and apply it to high-value doctor, workflow, ACR, and policy routing surfaces. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605041849-WF1Q77; commit cc2c971ed53e | enforcement: manual | fixability: external | state: open

package/bin/agentplane.js

@@ -2,7 +2,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { stat } from "node:fs/promises";
+import { mkdir, rm, stat } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
@@ -186,6 +186,95 @@ function renderStalePolicyWarning(reason) {
   return "warning: allowing read-only diagnostic command to run with a stale repo build inside the framework checkout.\n";
 }
 
+function staleAutoBootstrapEnabled() {
+  return (process.env.AGENTPLANE_DEV_AUTO_BOOTSTRAP ?? "1").trim() !== "0";
+}
+
+function alreadyTriedStaleAutoBootstrap() {
+  return (process.env.AGENTPLANE_DEV_AUTO_BOOTSTRAPPED ?? "").trim() === "1";
+}
+
+async function withBootstrapLock(repoRoot, fn) {
+  const lockParent = path.join(repoRoot, ".agentplane", "cache");
+  const lockDir = path.join(lockParent, "framework-dev-bootstrap.lock");
+  await mkdir(lockParent, { recursive: true });
+  try {
+    await mkdir(lockDir, { recursive: false });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    process.stderr.write(
+      "error: another framework dev bootstrap is already running.\n" +
+        `Retry after the lock is released: ${path.relative(repoRoot, lockDir)}\n`,
+    );
+    process.exitCode = 2;
+    return true;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await rm(lockDir, { recursive: true, force: true });
+  }
+}
+
+async function autoBootstrapAndRerun(repoRoot, staleReasons, commandPolicy) {
+  if (!staleAutoBootstrapEnabled() || alreadyTriedStaleAutoBootstrap()) return false;
+
+  const commandText = process.argv
+    .slice(2)
+    .map((value) => String(value ?? "").trim())
+    .filter(Boolean)
+    .join(" ");
+  process.stderr.write(
+    "info: stale repo build detected; running framework dev bootstrap before command.\n" +
+      `command: ${commandText || "<unknown>"}\n` +
+      `detected: ${staleReasons.join(", ")}\n` +
+      `reason: ${commandPolicy.reason}\n`,
+  );
+
+  return await withBootstrapLock(repoRoot, async () => {
+    const bootstrap = spawnSync("bun", ["run", "framework:dev:bootstrap"], {
+      cwd: repoRoot,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        AGENTPLANE_DEV_AUTO_BOOTSTRAP: "0",
+      },
+    });
+
+    if (bootstrap.error || bootstrap.status !== 0) {
+      const reason = bootstrap.error?.message ?? `exit ${bootstrap.status ?? "unknown"}`;
+      process.stderr.write(
+        `error: automatic framework dev bootstrap failed (${reason}).\n` +
+          "Manual fallback:\n" +
+          FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS.map((command) => `  ${command}\n`).join(""),
+      );
+      process.exitCode = bootstrap.status ?? 2;
+      return true;
+    }
+
+    const rerun = spawnSync(
+      process.execPath,
+      [fileURLToPath(import.meta.url), ...process.argv.slice(2)],
+      {
+        cwd: process.cwd(),
+        stdio: "inherit",
+        env: {
+          ...process.env,
+          AGENTPLANE_DEV_AUTO_BOOTSTRAPPED: "1",
+        },
+      },
+    );
+    if (rerun.error) {
+      process.stderr.write(`error: failed to rerun after bootstrap: ${rerun.error.message}\n`);
+      process.exitCode = 2;
+      return true;
+    }
+    process.exitCode = rerun.status ?? (rerun.signal ? 1 : 0);
+    return true;
+  });
+}
+
 function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requireFromAgentplane = createRequire(path.join(agentplaneRoot, "package.json"));
   const frameworkRoot = path.resolve(agentplaneRoot, "..", "..");
@@ -208,7 +297,7 @@ function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requiredSpecifiers = ["@agentplaneorg/core"];
   return requiredSpecifiers.filter((specifier) => {
     try {
-      const resolved = requireFromAgentplane.resolve(specifier);
+      const resolved = requireFromAgentplane.resolve(`${specifier}/package.json`);
       if (isPathInside(frameworkRoot, resolved)) return false;
       return !existsSync(path.join(agentplaneRoot, "node_modules", ...specifier.split("/")));
     } catch {
@@ -243,6 +332,11 @@ async function assertDistUpToDate() {
   if (missingDeps.length > 0) {
     process.stderr.write(
       "error: repo-local runtime dependencies are missing for this framework checkout.\n" +
+        "Code: FRAMEWORK_RUNTIME_DEPENDENCY_MISSING\n" +
+        "Why: the repo-local CLI cannot resolve its workspace runtime packages from this checkout.\n" +
+        "Fix: restore the framework install layout, then rebuild the repo-local packages.\n" +
+        `Safe command: ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n` +
+        "Stop condition: stop if the missing package resolves outside this repository or bun install would need unapproved network access.\n" +
         "This worktree is not bootstrapped yet.\n" +
         "Missing module resolution:\n" +
         missingDeps.map((specifier) => `  ${specifier}\n`).join("") +
@@ -300,6 +394,10 @@ async function assertDistUpToDate() {
 
     const commandPolicy = classifyStaleDistPolicy(process.argv);
     if (commandPolicy.mode === "warn_and_run") {
+      if (await autoBootstrapAndRerun(repoRoot, staleReasons, commandPolicy)) {
+        return false;
+      }
+
       const commandText = process.argv
         .slice(2)
         .map((value) => String(value ?? "").trim())

package/bin/ap.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+process.env.AGENTPLANE_CLI_ALIAS = "ap";
+process.env.AGENTPLANE_AGENT_MODE = "1";
+process.env.AGENTPLANE_PROMPTS ??= "plain";
+process.env.AGENTPLANE_NO_UPDATE_CHECK ??= "1";
+
+await import("./agentplane.js");

package/bin/runtime-watch.js

@@ -5,6 +5,7 @@ import path from "node:path";
 const WATCHED_RUNTIME_PATHS = {
   agentplane: [
     "src",
+    "bin/ap.js",
     "bin/agentplane.js",
     "bin/dist-guard.js",
     "bin/runtime-context.js",

package/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.4.2",
-  "git_head": "2c98719336c87cbe2aaf196d14b32c841a9defa1",
-  "watched_runtime_snapshot_hash": "56c2045c93aa3da808e26b1dc2396f28fbdcbe7a9c1ba9db50362d2432b0f257"
+  "package_version": "0.4.4",
+  "git_head": "dfe70bf54c4612e25ccac8aea363a744b4bed245",
+  "watched_runtime_snapshot_hash": "1a9fc1a9c09926b82cd9510670d6fea8600c41462b2ba9efec04965a879a5fcc"
 }