agentplane 0.4.4 → 0.5.0

package/README.md

@@ -1,9 +1,12 @@
 # AgentPlane CLI
 
-**The open-source audit layer for coding agents.**
+**Git-native infrastructure for traceable AI work.**
 
-`agentplane` is a local CLI that turns Claude Code, Codex, Cursor, Aider, and similar coding-agent
-work into reviewable, reversible Git artifacts.
+`agentplane` is a local-first CLI that turns Claude Code, Codex, Cursor, Aider, and similar
+coding-agent changes into reviewable Git evidence: task intent, approved plan, verification, finish
+state, and Agent Change Record.
+
+No hosted runtime. No telemetry. No vendor lock-in. Everything stays in your repository.
 
 [![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)
@@ -70,22 +73,22 @@ agentplane verify <task-id> --ok --by <agent-id> --note "Focused tests passed."
 agentplane finish <task-id> --author <agent-id> --result "Parser rejects empty labels." --commit <git-rev>
 ```
 
-The visible output is the point: a reviewer can inspect task intent, plan, verification, and closure
-from Git-visible files.
+The visible output is the point: a reviewer can inspect task intent, plan, verification, closure,
+and ACR from Git-visible files.
 
 Agent IDs are configurable profiles. See
 [Agents](https://agentplane.org/docs/user/agents).
 
 ## Agent Change Record
 
-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.
+Every task can produce an **Agent Change Record (ACR)**, a commit-safe JSON evidence projection of
+intent, accepted plan, Git commits, policy decisions, verification result, and merge readiness.
 
 ```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
+agentplane acr validate <task-id> --mode local
+agentplane acr check <task-id> --mode ci
+agentplane acr explain <task-id>
 ```
 
 Schema: https://agentplane.org/schemas/acr-v0.1.schema.json
@@ -95,6 +98,11 @@ Schema: https://agentplane.org/schemas/acr-v0.1.schema.json
 - `direct` keeps work in the current checkout for fast local loops.
 - `branch_pr` creates per-task branches, worktrees, PR artifacts, and integration handoff.
 
+## Not another agent
+
+AgentPlane does not replace your coding agent, editor, terminal, Git, CI, or PR review. It records
+the evidence around the tools you already use.
+
 ## Compatible with
 
 Claude Code, Codex CLI, Cursor agent, Aider, GitHub Actions agent runners, and MCP-driven
@@ -102,7 +110,9 @@ workflows. AgentPlane does not replace them; it records what they did and whethe
 
 ## Recipes
 
-Recipes are signed, versioned behavior modules for AgentPlane:
+Recipes are optional signed behavior modules. Start with the task -> plan -> verify -> ACR flow
+first; add recipes only when you need reusable profiles, prompt modules, skills, or repository
+mapping:
 
 ```bash
 agentplane recipes list-remote

package/assets/policy/incidents.md

@@ -1,18 +1,3 @@
 # Policy Incidents Log
 
 - Append-only. Required fields: `id`, `date`, `scope`, `failure`, `rule`, `evidence`, `enforcement`, `state`; optional: `tags`, `match`, `advice`, `source_task`, `fixability`.
-- id: INC-20260422-02 | date: 2026-04-22 | scope: release-mode hook environment pollution | tags: ci, release, hooks | match: ci, release, hooks, pre-push, core.bare, git config, inherited, test, pollution | failure: A release-mode pre-push hook inherited test-modified git config (`core.bare=true`) and blocked local release verification until the repository config was manually restored. | advice: Isolate git config mutations in release/hook tests and make release-mode hook diagnostics identify polluted repository git config before treating the release payload as broken. | rule: Release and hook verification MUST distinguish polluted local git config from release payload failures. | evidence: task 202604221605-SQYRNQ; commit 45ba9c57f939 | enforcement: manual | fixability: repo-fixable | state: open
-- id: INC-20260428-01 | date: 2026-04-28 | scope: release and hosted-close verification evidence reconciliation | tags: branch-pr, release, hosted-close, verification | match: branch-pr, code, workflow, hosted, close, release, evidence, verification, pending, done | failure: Release evidence reconciliation is not fully fixed: `release-task-evidence apply` writes `verification.state=ok` for new evidence, but legacy `DONE` tasks with pending verification artifacts are widespread and need a migration-aware invariant. | advice: Add a scoped release/hosted evidence reconciliation check that applies only to new release tasks or provides an explicit baseline for legacy `DONE` plus pending artifacts. | rule: Release and hosted-close flows MUST NOT present newly closed tasks as `DONE` with pending verification when closure evidence exists. | evidence: task 202604281616-WG87DQ; commit c02ef92ed563 | enforcement: manual | fixability: repo-fixable | state: stabilized
-- id: INC-20260430-01 | date: 2026-04-30 | scope: Make release hygiene pass by reconciling generated project agent and policy mirrors with canonical framework prompt assets after the fragmented prompt migration. Scope is limited to sync output and any minimal follow-up needed for agents:check. | tags: agents, policy, release | match: agents, policy, release, make, hygiene, pass, reconciling, generated, project, agent, and, mirrors, with, canonical, framework, prompt | failure: bun run agents:check initially failed because target .agentplane agent and policy mirrors lagged the canonical fragmented prompt assets. | advice: Ran bun run agents:sync and verified the generated mirror output. | rule: Analogous Make release hygiene pass by reconciling generated project agent and policy mirrors with canonical framework prompt assets after the fragmented prompt migration. Scope is limited to sync output and any minimal follow-up needed for agents:check. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604300724-ZTGZYT; commit ac0e1ff930ed | enforcement: manual | fixability: external | state: open
-- id: INC-20260429-01 | date: 2026-04-29 | scope: recipe manifest/project overlay parsing for prompt module declarations and mutation sets. | tags: code, prompt-assembly, recipes, schemas | match: code, prompt-assembly, recipes, schemas, recipe, manifest, project, overlay, parsing, for, prompt, module, declarations, and, mutation, sets | failure: Checks passed: bun test packages/agentplane/src/commands/recipes/impl/project-installed-recipes.test.ts packages/agentplane/src/commands/recipes/impl/resolver.test.ts packages/agentplane/src/commands/recipes.transaction.test.ts packages/agentplane/src/runtime/prompt-modules/mutations.test.ts; bun run typecheck; git diff --check; bun run framework:dev:bootstrap; agentplane doctor; extra bun test packages/recipes/src/index.test.ts packages/recipes/src/overlay.test.ts; targeted eslint on touched files. | advice: No prompt graph application was added in this step; that remains for the dependent recipe application task. | rule: Analogous recipe manifest/project overlay parsing for prompt module declarations and mutation sets. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604291531-Z6XH6Q; commit c69211301720 | enforcement: manual | fixability: external | state: open
-- id: INC-20260429-02 | date: 2026-04-29 | scope: apply active recipe prompt module mutations during project overlay/prompt graph refresh. | tags: code, prompt-assembly, recipes, workflow | match: code, prompt-assembly, recipes, workflow, apply, active, recipe, prompt, module, mutations, during, project, overlay, graph, refresh, compiled | failure: Checks passed: agentplane doctor; bun run framework:dev:bootstrap; bun run typecheck; bun test packages/agentplane/src/commands/recipes/impl/overlay-project.test.ts packages/agentplane/src/commands/recipes.transaction.test.ts packages/agentplane/src/commands/recipes.catalog-install.test.ts packages/agentplane/src/runtime/prompt-modules/compiler.test.ts; git diff --check; extra bun test packages/agentplane/src/commands/recipes/impl/project-installed-recipes.test.ts; targeted eslint on touched files. | advice: Runner/runtime consumption and drift diagnostics remain scoped to the following diagnostic task. | rule: Analogous apply active recipe prompt module mutations during project overlay/prompt graph refresh. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604291531-N0H28A; commit ac327dd2b0c1 | enforcement: manual | fixability: external | state: open
-- id: INC-20260430-02 | 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: docs:site:typecheck emits untracked website/\*.js files in this repo; they were removed before docs:site:build. Build then passed. | advice: Task implementation commit is 7a95d2ca with generated task artifact refresh c5166206. | 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-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
-- 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/assets/policy/workflow.branch_pr.md

@@ -15,9 +15,10 @@ Use this module when `workflow_mode=branch_pr`.
 4. Keep single-writer discipline per task worktree.
 5. Publish/update PR artifacts from the task worktree.
 6. Verify on the task branch.
-7. CHECKPOINT B: integrate on base branch by INTEGRATOR.
-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.
+7. Queue verified task branches for serialized integration when more than one agent is ready to merge.
+8. CHECKPOINT B: integrate on base branch by INTEGRATOR.
+9. CHECKPOINT C: finish task(s) on base with verification evidence.
+10. Remove merged task branches/worktrees once the hosted-close/finish route has landed.
 
 ## Related task batch worktrees
 
@@ -46,6 +47,8 @@ agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
 agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
 agentplane pr update <task-id>
 agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
+agentplane integrate queue enqueue <task-id> --branch task/<task-id>/<slug>
+agentplane integrate queue run-next --run-verify
 agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify
 agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
 ```
@@ -63,6 +66,7 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
   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.
+- When several task PRs are ready together, use the integration queue so only one branch owns the merge lane; stale branch heads move to rework instead of blocking later queued work.
 - `task start-ready` MAY surface targeted incident advice for analogous scope/tags; follow it before widening scope.
 - Keep structured resolved external findings in the task README; mark reusable ones with `Fixability: external` (or `IncidentExternal: true`) and let base-branch `finish` or `agentplane incidents collect <task-id>` promote them into `.agentplane/policy/incidents.md`, using optional `Incident*` fields only when the inferred scope/advice needs refinement. Plain `Findings` text remains task-local and does not update the shared incident registry.
 - MUST stop and request re-approval on material drift.

package/assets/policy/workflow.release.md

@@ -10,11 +10,12 @@ 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: choose the workflow-specific publication route after all gates pass.
-6. Record release evidence (commands, outputs, resulting version/tag).
+2. CHECKPOINT B: review/fix active `.agentplane/policy/incidents.md` entries through a dedicated task, archive final evidence, and clean the active incident registry.
+3. CHECKPOINT C: generate release plan and freeze version/tag target.
+4. Generate release notes with complete human-readable coverage of all task-level changes.
+5. Run release prepublish checks.
+6. CHECKPOINT D: choose the workflow-specific publication route after all gates pass.
+7. Record release evidence (commands, outputs, resulting version/tag).
 
 <!-- /ap:fragment -->
 <!-- ap:fragment id="policy.workflow.release.commands.command.contract" slot="commands" mutability="replaceable" -->
@@ -38,6 +39,7 @@ agentplane finish <task-id> --author <ROLE> --body "Verified: release" --result
 ## Constraints
 
 - MUST NOT perform irreversible release actions before explicit approval.
+- MUST NOT start release planning, prepublish, or publish while `.agentplane/policy/incidents.md` contains active incident entries.
 - 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/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.4.4",
-  "git_head": "dfe70bf54c4612e25ccac8aea363a744b4bed245",
-  "watched_runtime_snapshot_hash": "1a9fc1a9c09926b82cd9510670d6fea8600c41462b2ba9efec04965a879a5fcc"
+  "package_version": "0.5.0",
+  "git_head": "59109bfdc8a9746402a76fb9c7a428f75d6977f3",
+  "watched_runtime_snapshot_hash": "84365a7e93d3cd3d5b9c54bf9f3787fa7e11b2eaf257ba0c9ab3aa531fac5764"
 }