agentplane 0.4.1 → 0.4.3

package/README.md

@@ -1,22 +1,21 @@
-# AgentPlane
+# AgentPlane CLI
+
+**The open-source audit layer for coding agents.**
+
+`agentplane` is a local CLI that turns Claude Code, Codex, Cursor, Aider, and similar coding-agent
+work into reviewable, reversible Git artifacts.
 
 [![npm](https://img.shields.io/npm/v/agentplane.svg)](https://www.npmjs.com/package/agentplane)
 [![Downloads](https://img.shields.io/npm/dm/agentplane.svg)](https://www.npmjs.com/package/agentplane)
+[![GitHub stars](https://img.shields.io/github/stars/basilisk-labs/agentplane?style=flat)](https://github.com/basilisk-labs/agentplane/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/basilisk-labs/agentplane/blob/main/LICENSE)
 [![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-3c873a.svg)](https://agentplane.org/docs/user/prerequisites)
 
-**Use coding agents without losing Git discipline.**
-
-`agentplane` is a local CLI that makes Claude Code, Codex, Cursor, Aider, and similar coding-agent
-work auditable inside your Git repository:
-
-```text
-task -> plan -> approve -> implement -> verify -> finish
-```
+[![SLSA v1 provenance](https://img.shields.io/badge/SLSA-v1-success)](https://registry.npmjs.org/-/npm/v1/attestations/agentplane@latest)
+[![Trusted publisher](https://img.shields.io/badge/npm-trusted%20publisher-blue)](https://docs.npmjs.com/generating-provenance-statements)
+[![Recipes signed: Ed25519](https://img.shields.io/badge/recipes-Ed25519%20signed-111827)](https://agentplane.org/docs/recipes)
 
-No hosted runtime. No hidden control plane. Everything stays in your repo.
-
-## Install
+## Install in 30 seconds
 
 ```bash
 npm i -g agentplane
@@ -24,141 +23,95 @@ agentplane init
 agentplane quickstart
 ```
 
-Requirements:
-
-- Node.js 20+
-- Git repository
-- Local terminal
-
-Prefer not to install globally:
+Prefer no global install:
 
 ```bash
 npx agentplane init
 npx agentplane quickstart
 ```
 
-## Why it exists
-
-Coding agents can change files. Teams still need to know what happened:
-
-- What task was the agent solving?
-- What plan was approved?
-- What changed in the repository?
-- What was verified?
-- Why was the task considered finished?
-
-AgentPlane adds a visible workflow layer around agent work without replacing Git, your editor, or
-your terminal.
+Requirements: Node.js 20+, Git, and a local terminal.
 
-## What appears in your repository
-
-`agentplane init` creates a visible workflow surface:
+## What you get after `agentplane init`
 
 ```text
 AGENTS.md or CLAUDE.md   Policy gateway for the repository
 .agentplane/            Repo-local workflow workspace
-.agentplane/config.json Current workflow configuration
+.agentplane/WORKFLOW.md Current workflow/config contract
 .agentplane/agents/     Installed agent profiles
 .agentplane/tasks/      Per-task records and evidence
-.agentplane/WORKFLOW.md Materialized workflow contract
+.agentplane/workflows/  Last-known-good workflow snapshot
 ```
 
-These artifacts make agent work inspectable. A reviewer can see what policy governed the repo, what
-task was active, what plan was accepted, what checks ran, and how the task was closed.
-
-## First task flow
+AgentPlane does not run a hosted control plane. It records the task trail inside the repository you
+already review.
 
-Create a task and record the plan:
-
-```bash
-agentplane task new --title "First task" --description "Describe the change" --priority med --owner DOCS --tag docs
-agentplane task plan set <task-id> --text "Explain the plan" --updated-by DOCS
-```
-
-If your repository requires explicit plan approval, run:
+## One task loop
 
 ```bash
+agentplane task new --title "Fix parser edge case" --description "Reject empty labels." --owner CODER --tag code
+agentplane task plan set <task-id> --text "Add a fixture, tighten validation, and run focused tests." --updated-by CODER
 agentplane task plan approve <task-id> --by ORCHESTRATOR
-```
-
-Then start work, record verification, and finish:
-
-```bash
-agentplane task start-ready <task-id> --author DOCS --body "Start: ..."
+agentplane task start-ready <task-id> --author CODER --body "Start: implementing parser validation with focused tests."
+# Run Claude Code, Codex, Cursor, Aider, or edit manually.
 agentplane task verify-show <task-id>
-agentplane verify <task-id> --ok --by DOCS --note "Checks passed"
-agentplane finish <task-id> --author DOCS --body "Verified: checks passed." --result "One-line outcome" --commit <git-rev>
+agentplane verify <task-id> --ok --by CODER --note "Focused tests passed."
+agentplane finish <task-id> --author CODER --result "Parser rejects empty labels." --commit <git-rev>
 ```
 
-That is the shortest useful path: initialize the repo, create a task, verify the change, and close it
-through recorded workflow state instead of an unstructured agent session.
+The visible output is the point: a reviewer can inspect task intent, plan, verification, and closure
+from Git-visible files.
 
-## Without vs with AgentPlane
+Roles like `CODER` and `ORCHESTRATOR` are configurable agent IDs. See
+[Agents](https://agentplane.org/docs/user/agents).
 
-| Without AgentPlane       | With AgentPlane                 |
-| ------------------------ | ------------------------------- |
-| Prompt in chat           | Task is recorded                |
-| Agent edits files        | Plan is explicit                |
-| Human inspects diff      | Approval is visible             |
-| Context is scattered     | Verification is stored          |
-| Verification is implicit | Finish creates closure evidence |
-| Closure is manual        | Everything lives close to Git   |
-
-## Workflow modes
+## Agent Change Record
 
-### `direct`
+Every task can produce an **Agent Change Record (ACR)**, a deterministic JSON evidence projection
+of intent, accepted plan, verification result, policy decisions, and closure commit.
 
-Fast local loops in the current checkout. Good for solo work, prototypes, and short tasks.
-
-### `branch_pr`
-
-Structured per-task branch and PR-style handoff. Good for teams, stricter review, and integration
-boundaries.
+```bash
+agentplane acr generate <task-id> --work-commit HEAD --write
+agentplane acr validate .agentplane/tasks/<task-id>/acr.json
+agentplane acr check <task-id> --require-plan-approved --require-verification
+agentplane acr --help
+```
 
-## Who it is for
+Schema: https://agentplane.org/schemas/acr-v0.1.schema.json
 
-- Developers using Claude Code, Codex, Cursor, Aider, or local coding agents.
-- Maintainers who want agent changes to remain reviewable.
-- Teams that need task state, verification, and closure before merging agent-generated work.
-- Local-first builders who do not want a hosted agent runtime between their repo and their workflow.
+## Workflow modes
 
-## What it is not
+- `direct` keeps work in the current checkout for fast local loops.
+- `branch_pr` creates per-task branches, worktrees, PR artifacts, and integration handoff.
 
-- Not a hosted agent platform.
-- Not a prompt framework.
-- Not a replacement for Git.
-- Not a replacement for your editor.
-- Not a replacement for Claude Code, Codex, Cursor, or Aider.
+## Compatible with
 
-## Workflow guides
+Claude Code, Codex CLI, Cursor agent, Aider, GitHub Actions agent runners, and MCP-driven
+workflows. AgentPlane does not replace them; it records what they did and whether your gates passed.
 
-Start from the guide that matches your current stack:
+## Recipes
 
-- [AgentPlane + Claude Code](https://agentplane.org/docs/workflow-guides/claude-code)
-- [AgentPlane + Codex](https://agentplane.org/docs/workflow-guides/codex)
-- [AgentPlane + Cursor](https://agentplane.org/docs/workflow-guides/cursor)
-- [AgentPlane + Aider](https://agentplane.org/docs/workflow-guides/aider)
-- [AgentPlane + GitHub Actions](https://agentplane.org/docs/workflow-guides/github-actions)
-- [AgentPlane + branch_pr workflow](https://agentplane.org/docs/workflow-guides/branch-pr)
+Recipes are signed, versioned behavior modules for AgentPlane:
 
-Installable recipes are separate signed packages; the current catalog starts with
-[Code Map](https://agentplane.org/docs/recipes/code-map).
+```bash
+agentplane recipes list-remote
+agentplane recipes install code-map --refresh --yes
+```
 
-## Documentation
+Start with [Code Map](https://agentplane.org/docs/recipes/code-map).
 
-Start here:
+## Docs
 
 - [Overview](https://agentplane.org/docs/user/overview)
 - [Setup](https://agentplane.org/docs/user/setup)
-- [Workflow](https://agentplane.org/docs/user/workflow)
 - [Task lifecycle](https://agentplane.org/docs/user/task-lifecycle)
-- [Commands](https://agentplane.org/docs/user/commands)
-- [CLI reference](https://agentplane.org/docs/user/cli-reference.generated)
+- [Workflow guides](https://agentplane.org/docs/workflow-guides)
+- [Recipes](https://agentplane.org/docs/recipes)
+- [Comparison](https://agentplane.org/docs/compare)
 
-## Support
+## Repository
 
-- [Issues](https://github.com/basilisk-labs/agentplane/issues)
-- [Contributing](https://github.com/basilisk-labs/agentplane/blob/main/CONTRIBUTING.md)
+https://github.com/basilisk-labs/agentplane
 
 ## License
 

package/assets/AGENTS.md

@@ -21,7 +21,7 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
 - CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow_mode` in `.agentplane/config.json`; use `agentplane quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `agentplane work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow.mode` in `.agentplane/WORKFLOW.md`; use `agentplane quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `agentplane work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
 
 <!-- /ap:fragment -->
 <!-- ap:fragment id="gateway.agents.source_of_truth.sources.of.truth" slot="source_of_truth" mutability="replaceable" -->
@@ -33,7 +33,7 @@ Priority order (highest first):
 1. Enforcement: CI, tests, linters, hooks, CLI validations.
 2. Policy gateway: `AGENTS.md`.
 3. Canonical policy modules from `## CANONICAL DOCS`.
-4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/config.json`.
+4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/WORKFLOW.md`.
 5. Reference examples from `## REFERENCE EXAMPLES`.
 
 Conflict rule:
@@ -114,6 +114,11 @@ node .agentplane/policy/check-routing.mjs
 - Outcome-first, concise, evidence-first: state goal, success criteria, constraints, stop rules, and output; use procedure only for command contracts, state machines, or irreversible gates; ask one narrow question only when missing information changes scope, task graph, security, or irreversible action.
 - Retrieval/progress/cache: preamble before multi-step or tool-heavy work; load only matched policy, task README, Verify Steps, and relevant files; use incidents only for analogous scope/tags; final output names actions, checks, blockers/drift, and next approval; keep stable gateway/policy/role before dynamic context and never cache mutable task state.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.user.instructions" slot="body" mutability="append_only" -->
+
+IF `.agentplane/user-instructions.md` exists THEN LOAD it as `gateway.user.instructions`.
+
 <!-- /ap:fragment -->
 <!-- ap:fragment id="gateway.agents.load_rules.load.rules" slot="load_rules" mutability="replaceable" -->
 
@@ -130,8 +135,8 @@ Condition: task includes mutation (file edits, task-state changes, commits, merg
 
 ### Conditional imports (linear IF -> LOAD contract)
 
-1. IF `workflow_mode=direct` THEN LOAD `@.agentplane/policy/workflow.direct.md`.
-2. IF `workflow_mode=branch_pr` THEN LOAD `@.agentplane/policy/workflow.branch_pr.md`.
+1. IF `workflow.mode=direct` THEN LOAD `@.agentplane/policy/workflow.direct.md`.
+2. IF `workflow.mode=branch_pr` THEN LOAD `@.agentplane/policy/workflow.branch_pr.md`.
 3. IF task touches release/version/publish THEN LOAD `@.agentplane/policy/workflow.release.md`.
 4. IF task runs `agentplane upgrade` or touches `.agentplane/.upgrade/**` THEN LOAD `@.agentplane/policy/workflow.upgrade.md`.
 5. IF task modifies implementation code paths THEN LOAD `@.agentplane/policy/dod.code.md`.
@@ -139,11 +144,6 @@ Condition: task includes mutation (file edits, task-state changes, commits, merg
 7. IF task modifies policy files (`AGENTS.md` or `.agentplane/policy/**`) THEN LOAD `@.agentplane/policy/governance.md`.
 8. IF task modifies `.agentplane/policy/incidents.md` THEN LOAD `@.agentplane/policy/incidents.md`.
 
-Routing examples:
-
-- Example (docs-only task): rules `1|6` apply in `direct`; do not load `dod.code.md`.
-- Example (upgrade task): rules `4|7` apply plus workflow mode rule.
-
 Routing constraints:
 
 - MUST NOT load unrelated policy modules.

package/assets/agents/EVALUATOR.json

@@ -0,0 +1,26 @@
+{
+  "id": "EVALUATOR",
+  "role": "Evaluate completed runner/task attempts against documented quality criteria and return pass, rework, or blocked verdicts.",
+  "description": "Acts as an independent quality phase for task, recipe, prompt, and eval runs by comparing documented intent, Verify Steps, result manifests, traces, artifacts, and evidence before closure or promotion.",
+  "inputs": {
+    "task.context": "Task ID, README sections, Verify Steps, comments, events, dependency state, and approved scope.",
+    "runner.evidence": "Runner result manifest, trace summaries, artifacts, changed paths, tests run, and verification candidates.",
+    "reference.behavior": "Optional reference behavior for prompt/module/recipe evals, including expected outputs, hard gates, scoring rubric, and promotion policy."
+  },
+  "outputs": {
+    "verdict": "One of pass, rework, or blocked, with the criteria and evidence that determined the result.",
+    "rework.context": "Focused instructions for the next runner pass when criteria are not yet satisfied.",
+    "quality.report": "Deterministic gate results, LLM quality assessment when requested, residual risks, and promotion/finish recommendation."
+  },
+  "permissions": {
+    "review.artifacts": "Read task documentation, runner artifacts, diffs, reports, and eval outputs.",
+    "task.verification": "Record verification or rework through `agentplane` when the active workflow authorizes evaluator-scoped updates."
+  },
+  "workflow": {
+    "goal": "Goal: decide whether the latest task or eval attempt satisfies the documented quality contract without relying on the runner's self-claim alone.",
+    "success.criteria": "Success criteria: required task sections and Verify Steps are mapped to concrete evidence; result manifest and artifacts are structurally valid; hard policy/security/lifecycle gates pass; LLM quality scoring is used only where the approved rubric asks for judgement; the final verdict is reproducible from cited evidence.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; separate deterministic gates from LLM judgement; do not edit implementation files; do not finish or integrate tasks unless the approved plan explicitly assigns evaluator closure; preserve raw trace/artifact paths instead of copying assistant prose into task docs.",
+    "stop.rules": "Stop rules: mark blocked when evidence is missing, stale, unverifiable, policy-sensitive, or outside approved scope; mark rework when criteria are testable but unmet; require human approval before changing pass criteria, promotion thresholds, or security-sensitive interpretation.",
+    "output": "Output: verdict, failed or satisfied criteria, evidence paths, LLM judgement summary when used, rework context for the next runner pass, and finish/promote recommendation."
+  }
+}

package/assets/agents/PLANNER.json

@@ -1,7 +1,7 @@
 {
   "id": "PLANNER",
-  "role": "Own the task backlog via agentplane and keep every approved plan mapped to the smallest valid task graph.",
-  "description": "Converts goals into atomic single-owner tasks with explicit acceptance contracts, minimal dependency edges, and no bookkeeping-only noise.",
+  "role": "Own the task backlog via agentplane and keep every approved plan recursively refined into the smallest valid task graph.",
+  "description": "Converts goals into atomic single-owner leaf tasks with explicit acceptance contracts, minimal dependency edges, and no bookkeeping-only noise.",
   "inputs": {
     "high.level.goal": "High-level goals, features, bugs, or refactors to plan.",
     "planning.constraints": "Optional constraints such as deadlines, priority, or components."
@@ -15,10 +15,10 @@
     "task.management": "Manage tasks via agentplane and follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output."
   },
   "workflow": {
-    "goal": "Goal: map an approved objective to the smallest valid executable task graph.",
-    "success.criteria": "Success criteria: no duplicate open task exists; each task has one owner, a real deliverable boundary, explicit depends_on, valid title/description/tags, and concrete Verify Steps; bookkeeping-only work stays inside the executable task.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `agentplane`; prefer one task when one work item satisfies the goal; assign existing agent IDs or schedule CREATOR only for a real capability gap; keep observations in task-local Notes/Findings.",
-    "stop.rules": "Stop rules: ask one narrow question only when the task graph would otherwise be invalid; stop on missing approval, unresolved owner/dependency boundaries, unsafe scope drift, or acceptance criteria that cannot be made concrete.",
-    "output": "Output: task IDs, owners, status, dependency edges, Verify Steps, rationale for split/merge decisions, and deferred follow-up work."
+    "goal": "Goal: map an approved objective to the smallest valid executable task graph by recursively decomposing composite nodes until every executable leaf is atomic.",
+    "success.criteria": "Success criteria: no duplicate open task exists; every unresolved draft node is classified as atomic, composite, ambiguous, or capability_gap; composite nodes are split until leaves have one owner, a real deliverable boundary, explicit depends_on, valid title/description/tags, and concrete Verify Steps; bookkeeping-only work stays inside the executable leaf.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `agentplane`; prefer one task when one work item satisfies the goal; do not over-split into microtasks when one owner and one verification boundary are enough; assign existing agent IDs or schedule CREATOR only for a real capability gap; keep observations in task-local Notes/Findings.",
+    "stop.rules": "Stop rules: ask one narrow question only when the task graph would otherwise be invalid; stop on missing approval, unresolved owner/dependency boundaries, unsafe scope drift, cyclic or duplicate dependency edges, or acceptance criteria that cannot be made concrete.",
+    "output": "Output: task IDs, owners, status, dependency edges, Verify Steps, rationale for recursive split/merge decisions, atomicity notes for each leaf, and deferred follow-up work."
   }
 }

package/assets/framework.manifest.json

@@ -22,6 +22,13 @@
       "merge_strategy": "agent_json_3way",
       "required": true
     },
+    {
+      "path": ".agentplane/agents/EVALUATOR.json",
+      "source_path": "agents/EVALUATOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
     {
       "path": ".agentplane/agents/INTEGRATOR.json",
       "source_path": "agents/INTEGRATOR.json",

package/assets/policy/incidents.md

@@ -10,3 +10,8 @@
 - id: INC-20260430-03 | date: 2026-04-30 | scope: Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. | tags: code, docs-ia, tooling | match: code, docs-ia, tooling, add, automated, docs, information, architecture, guard, that, checks, index, mdx, and, website, sidebars | failure: Remote Docs CI failed before this fix on docs/developer/project-layout.mdx referencing packages/agentplane/dist/. That path is generated output, not a required tracked source path. | advice: Follow-up fix commit is 4ab6c548 with artifact refresh 5685436b. | rule: Analogous Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604301955-HKY8NW; commit 00031a6f3ac9 | enforcement: manual | fixability: external | state: open
 - id: INC-20260501-01 | date: 2026-05-01 | scope: Run final integrated verification for the refactor wave and record any residual gaps. | tags: code | match: code, run, final, integrated, verification, for, the, refactor, wave, and, record, any, residual, gaps, normalized, compiled | failure: ci:local:full passed after focused init/platform-critical regression checks; framework:dev:bootstrap, agentplane doctor, policy routing, and spec:examples smoke also passed. | advice: Normalized compiled init prompt asset output to one trailing newline and updated the direct-mode agent-template expectation to account for policy gateway rendering. | rule: Analogous Run final integrated verification for the refactor wave and record any residual gaps. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605010645-3W3EXR; commit b48a260fa73d | enforcement: manual | fixability: external | state: open
 - id: INC-20260501-02 | date: 2026-05-01 | scope: Submit a GitHub PR adding AgentPlane to brandonhimpfen/awesome-ai-coding-agents as workflow infrastructure for AI coding agents after checking scope alignment, formatting, and category placement. | tags: docs | match: docs, submit, github, adding, agentplane, brandonhimpfen, awesome, coding, agents, workflow, infrastructure, for, after, checking, scope, alignment | failure: Added AgentPlane to brandonhimpfen/awesome-ai-coding-agents under Agent Infrastructure using repo-local AI coding-agent workflow wording. Opened https://github.com/brandonhimpfen/awesome-ai-coding-agents/pull/8 with --body-file and verified gh pr view body renders with Markdown line breaks. Ran git diff --check, python3 .github/scripts/awesome_list_lint.py, python3 .github/scripts/detect_duplicate_links.py, python3 check_readme_links.py README.md --timeout 8, node .agentplane/policy/check-routing.mjs, and agentplane doctor. | advice: Upstream PR is open. Target repo link checker confirmed the AgentPlane URL as 200 but exits non-zero because the pre-existing agentcoder/AgentCoder entry returns 404; this is disclosed in the PR body. | rule: Analogous Submit a GitHub PR adding AgentPlane to brandonhimpfen/awesome-ai-coding-agents as workflow infrastructure for AI coding agents after checking scope alignment, formatting, and category placement. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605011518-PH7024; commit cb1fe303f97a | enforcement: manual | fixability: external | state: open
+- 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

package/assets/policy/workflow.branch_pr.md

@@ -19,6 +19,22 @@ Use this module when `workflow_mode=branch_pr`.
 8. CHECKPOINT C: finish task(s) on base with verification evidence.
 9. Remove merged task branches/worktrees once the hosted-close/finish route has landed.
 
+## Related task batch worktrees
+
+When several approved tasks form one dependent change, they MAY be executed in one primary task
+worktree instead of one worktree per task. Use this only when splitting the work into separate PRs
+would add coordination risk without improving review.
+
+Batch worktree rules:
+
+- One task is the primary integration task and owns the branch, worktree, and PR.
+- Every included task id MUST be listed in the primary task plan or PR artifact before mutation.
+- Each included task MUST keep its own plan, start-ready record, Verify Steps, verification result,
+  and finish evidence.
+- Commits SHOULD mention the relevant task suffixes when a change serves more than one included
+  task.
+- The final PR MUST describe the full included task set and merge the complete result into `main`.
+
 <!-- /ap:fragment -->
 <!-- ap:fragment id="policy.workflow.branch_pr.commands.command.contract" slot="commands" mutability="replaceable" -->
 
@@ -43,6 +59,8 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 - Task documentation updates MAY be batched within one turn before approval.
 - MUST run `task plan approve` then `task start-ready` as `Step 1 -> wait -> Step 2` (never parallel).
 - In `branch_pr`, `task start-ready`, `pr open`, `pr update`, and verification commands SHOULD be run from the task worktree created by `work start`.
+- A related task batch MAY reuse one primary task worktree when all included tasks are approved,
+  listed, verified independently, and merged through the primary task PR.
 - `pr open` without `--sync-only` SHOULD complete in one pass: sync local artifacts, auto-publish the task branch to `origin` when it has no upstream yet, then create/link the remote GitHub PR.
 - `integrate` defaults to the `merge` strategy so task branch commits stay in base history. Use `--merge-strategy squash` only when intentionally compacting branch history.
 - `task start-ready` MAY surface targeted incident advice for analogous scope/tags; follow it before widening scope.

package/bin/agentplane.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 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";
@@ -185,8 +186,98 @@ 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, "..", "..");
   let packageJson = null;
   try {
     packageJson = requireFromAgentplane("./package.json");
@@ -206,8 +297,9 @@ function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requiredSpecifiers = ["@agentplaneorg/core"];
   return requiredSpecifiers.filter((specifier) => {
     try {
-      requireFromAgentplane.resolve(specifier);
-      return false;
+      const resolved = requireFromAgentplane.resolve(specifier);
+      if (isPathInside(frameworkRoot, resolved)) return false;
+      return !existsSync(path.join(agentplaneRoot, "node_modules", ...specifier.split("/")));
     } catch {
       return true;
     }
@@ -297,6 +389,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/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.4.1",
-  "git_head": "62153d7eedd49b356e67aee92d713ad9b7b8485c",
-  "watched_runtime_snapshot_hash": "2a5f3b1f84ea38e8747a50e72b94b46fe874f0fa72eaa0a4babba30323524007"
+  "package_version": "0.4.3",
+  "git_head": "04ccc002125560cd2ec87094e20cd5a9907d2016",
+  "watched_runtime_snapshot_hash": "5a534e101008bc57436f81a2364408cd0c5368241c43b43a4a814875fa750f68"
 }