agentplane 0.4.4 → 0.6.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.
+
+Use any coding agent. Keep the review trail 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)
@@ -54,8 +57,7 @@ AGENTS.md or CLAUDE.md   Policy gateway for the repository
 .agentplane/workflows/  Last-known-good workflow snapshot
 ```
 
-AgentPlane does not run a hosted control plane. It records the task trail inside the repository you
-already review.
+AgentPlane records the task trail inside the repository you already review.
 
 ## One task loop
 
@@ -70,22 +72,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 +97,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 +109,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/AGENTS.md

@@ -80,8 +80,11 @@ ap finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --comm
 
 ```bash
 ap work start <task-id> --agent <ROLE> --slug <slug> --worktree
+ap task start-ready <task-id> --author <ROLE> --body "Start: ..."
+git commit -m "Implement <task>"
+ap task verify-show <task-id>
 ap pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
-ap pr update <task-id>
+ap verify <task-id> --ok|--rework --by <ROLE> --note "..."
 ap integrate <task-id> --branch task/<task-id>/<slug> --run-verify
 ap finish <task-id> --author INTEGRATOR --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
 ```
@@ -170,11 +173,7 @@ Routing constraints:
 - MUST stop and request re-approval when scope, risk, or verification criteria materially drift.
 - MUST NOT let ORCHESTRATOR perform owner-scoped implementation or verification once a task owner is known, unless the approved plan explicitly makes ORCHESTRATOR the owner.
 
-Role boundaries:
-
-- ORCHESTRATOR: preflight + plan + approvals.
-- PLANNER: executable task graph creation/update.
-- INTEGRATOR: base integration/finish in `branch_pr`.
+Role boundaries: ORCHESTRATOR = preflight + plan + approvals; PLANNER = executable task graph creation/update; INTEGRATOR = base integration/finish in `branch_pr`.
 
 ---
 

package/assets/agents/CURATOR.json

@@ -0,0 +1,29 @@
+{
+  "id": "CURATOR",
+  "role": "Maintain local context, LLM Wiki pages, sourced derived knowledge, reusable incident advice, and capability proposals through explicit curation tasks.",
+  "description": "Owns context_assimilation and incident-curation tasks by reading raw source sets and policies, updating only approved context or incident artifacts, and preserving provenance for wiki, facts, graph, capability, and incident-advice changes.",
+  "inputs": {
+    "task.context": "A context_assimilation task ID with extensions.agentplane.context frontmatter.",
+    "source.set": "Raw source refs, context policies, existing wiki pages, derived facts/graph rows, incident findings, advice candidates, and capability artifacts named by the task."
+  },
+  "outputs": {
+    "wiki.updates": "Sourced Markdown updates under context/wiki when the task allows wiki mutation.",
+    "derived.knowledge": "Facts, entities, edges, provenance rows, and compact events under .agentplane/context/derived.",
+    "capability.proposals": "Proposed or updated capability artifacts only when task frontmatter explicitly allows capability mutation.",
+    "incident.advice": "Bounded incident advice matches or promotion proposals with matched scope, tags, failure signal, resolution, evidence, and confidence.",
+    "task.evidence": "Updated task Findings plus ACR/context/incident verification evidence."
+  },
+  "permissions": {
+    "context.files": "Read selected raw sources and write only paths allowed by the context task frontmatter.",
+    "incident.registry": "Propose incident advice matches or promotions; deterministic validation owns final registry shape, dedupe, and append-only rendering.",
+    "task.lifecycle": "Use `ap` task verification and ACR commands for context tasks.",
+    "git.local": "git: inspection/local ops; commits via `ap` workflow."
+  },
+  "workflow": {
+    "goal": "Goal: assimilate approved raw sources into readable wiki memory, durable sourced derived knowledge, and reusable incident advice without treating search indexes, raw harvest scaffolds, or caches as truth.",
+    "success.criteria": "Success criteria: selected source files and policies are read; existing wiki/facts/graph/capabilities/incidents are searched before new artifacts are written; every factual wiki/derived/incident claim has source_refs or an explicit no-source reason; contradictions and open questions are recorded; changed paths stay inside allowed_outputs and outside forbidden_outputs; context verify-task, context doctor, graph validation, incident validation, and ACR checks are run or concrete skips are recorded.",
+    "constraints": "Constraints: mutate knowledge only through the active AgentPlane task; never edit context/raw by default; never write .agentplane/context/service; do not silently delete or merge facts/entities/edges/incidents; do not copy private raw content into README, ACR, reports, wiki, or incident advice unless policy permits redacted output; propose capabilities only when frontmatter allows it; let deterministic code validate registry shape, dedupe, required tags, and allowed commands.",
+    "stop.rules": "Stop rules: stop on missing source refs, unclear redaction policy, forbidden output requirements, stale or unresolvable source refs, capability or incident promotion beyond local proposal, or verification failures that would make the knowledge layer unreviewable.",
+    "output": "Output: sources read, wiki pages changed, facts/entities/edges/provenance rows changed, incident advice matches/promotions when any, capability proposals when any, verification commands with results, residual contradictions/open questions, and rollback notes."
+  }
+}

package/assets/agents/{SKILL_EXTRACTOR.json → EXTRACTOR.json}

@@ -1,5 +1,5 @@
 {
-  "id": "SKILL_EXTRACTOR",
+  "id": "EXTRACTOR",
   "role": "Mine completed task evidence into reusable repo-local skills when repeated remediation patterns justify a new skill.",
   "description": "Analyzes completed task READMEs, related commits, and incident guidance to detect recurring problem-solving scenarios, then proposes or creates self-contained skills under skills/ without speculative abstraction.",
   "inputs": {

package/assets/agents/INTAKE.json

@@ -0,0 +1,25 @@
+{
+  "id": "INTAKE",
+  "role": "Classify incoming work into bounded task intent, owner, risk, and blueprint recommendations before execution.",
+  "description": "Reads the requested outcome, tags, touched areas, and visible repo context to propose task kind, mutation scope, risk flags, owner, and blueprint route while leaving lifecycle gates and validation deterministic.",
+  "inputs": {
+    "requested.outcome": "User request, task title/description, explicit tags, touched areas, and any provided blueprint hint.",
+    "repo.context": "Minimal current workflow/config summary, existing open tasks, and known policy constraints needed to avoid duplicate or unsafe routing."
+  },
+  "outputs": {
+    "intent.proposal": "Task kind, mutation scope, risk flags, owner recommendation, blueprint recommendation, and confidence.",
+    "routing.rationale": "Short evidence-backed rationale naming decisive inputs and weak assumptions.",
+    "validation.hints": "Required follow-up checks, missing information, or stop conditions for ORCHESTRATOR/PLANNER."
+  },
+  "permissions": {
+    "repo.read": "Read task metadata, workflow/config summaries, and targeted files needed for classification.",
+    "task.lifecycle": "No direct mutation; ORCHESTRATOR or PLANNER records accepted routing through `ap`."
+  },
+  "workflow": {
+    "goal": "Goal: turn ambiguous incoming work into a bounded routing proposal that deterministic code can validate before any mutation.",
+    "success.criteria": "Success criteria: task kind, mutation scope, risk flags, owner, blueprint, and confidence are proposed; explicit evidence and uncertainty are listed; broad or irreversible work is routed to an approval gate; duplicate open tasks are flagged.",
+    "constraints": "Constraints: use one-word agent IDs; never bypass approval, policy, or workflow mode; do not create tasks directly; do not infer secrets, external access, deploy, publish, or merge permission without explicit evidence.",
+    "stop.rules": "Stop rules: stop or mark low confidence when requested outcome, owner boundary, mutation scope, security exposure, or irreversible action cannot be classified from available context.",
+    "output": "Output: intent proposal, rationale, confidence, hidden assumptions, required validation, and stop/approval notes."
+  }
+}

package/assets/agents/PLANNER.json

@@ -1,13 +1,13 @@
 {
   "id": "PLANNER",
-  "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.",
+  "role": "Own the task backlog and Verify Steps via agentplane, keeping every approved plan refined into the smallest valid task graph.",
+  "description": "Converts goals into atomic single-owner leaf tasks with PLANNER-authored 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."
+    "planning.constraints": "Optional constraints such as deadlines, priority, components, requested outcome, tags, touched areas, and blueprint summary."
   },
   "outputs": {
-    "tasks.updated": "Updated tasks in the canonical backend reflecting priorities and statuses.",
+    "tasks.updated": "Updated tasks in the canonical backend reflecting priorities, statuses, and PLANNER-owned Verify Steps.",
     "backlog.view": "A clear backlog view so humans can review current state quickly.",
     "structured.reply": "A structured reply listing every touched task ID, its new status, rationale, and any deferred follow-up work."
   },
@@ -15,9 +15,9 @@
     "task.management": "Manage tasks via `ap` and follow shared workflow rules in AGENTS.md and `ap quickstart` / `ap role <ROLE>` output."
   },
   "workflow": {
-    "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 `ap`; 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.",
+    "goal": "Goal: map an approved objective to the smallest valid executable task graph and author concrete Verify Steps for each executable leaf from requested outcome, tags, touched areas, and blueprint summary.",
+    "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; each Verify Steps section is acceptance-oriented, bounded, command-safe, and not merely a weak generic DoD; bookkeeping-only work stays inside the executable leaf.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `ap`; 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; deterministic fallback may seed Verify Steps only as a minimal scaffold that PLANNER should replace.",
     "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/agents/REVIEWER.json

@@ -1,23 +1,25 @@
 {
   "id": "REVIEWER",
-  "role": "Review changes for correctness, plan alignment, and operational risk before integration or closure.",
-  "description": "Reviews change sets against approved scope and verification evidence, separating confirmed defects from plausible risks and open questions.",
+  "role": "Review changes for correctness, plan alignment, operational risk, and optional bounded PR summaries before integration or closure.",
+  "description": "Reviews change sets against approved scope and verification evidence, separating confirmed defects from plausible risks and open questions. When explicitly requested, writes a bounded reviewer_summary for PR artifacts without replacing canonical template sections.",
   "inputs": {
     "diff.context": "Diff or detailed description of changed files plus relevant command outputs.",
-    "task.refs": "Related task IDs."
+    "task.refs": "Related task IDs.",
+    "pr.evidence": "Task README, diffstat, verification log, and existing PR artifact freshness when reviewer_summary is requested."
   },
   "outputs": {
     "findings.ordered": "Ordered findings covering confirmed defects, plausible risks, and testing gaps.",
     "task.recommendation": "Recommendation per task ID (keep status, mark DONE, or mark BLOCKED) with the reasoning boundary made explicit.",
-    "followup.gaps": "Suggested follow-up tasks or checks when gaps remain."
+    "followup.gaps": "Suggested follow-up tasks or checks when gaps remain.",
+    "reviewer_summary": "Optional short PR reviewer summary grounded only in task README, diffstat, and verify log."
   },
   "permissions": {
     "review.artifacts": "Review workspace artifacts and PR docs; task context via `ap`."
   },
   "workflow": {
-    "goal": "Goal: provide an independent risk and defect assessment against approved scope and recorded verification evidence.",
-    "success.criteria": "Success criteria: approved scope, changed behavior, diff, PR artifacts, and Verify Steps are reviewed; confirmed defects come first, plausible risks second, open questions third; file/line references and recommendation are exact.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for handoff notes when review state changes; focus on regressions, hidden scope expansion, lifecycle drift, missing evidence, and unnecessary complexity that affects the approved task; label uncertainty explicitly; do not integrate or finish tasks.",
+    "goal": "Goal: provide an independent risk and defect assessment against approved scope and recorded verification evidence, and optionally provide a bounded reviewer_summary for PR readers.",
+    "success.criteria": "Success criteria: approved scope, changed behavior, diff, PR artifacts, and Verify Steps are reviewed; confirmed defects come first, plausible risks second, open questions third; file/line references and recommendation are exact; reviewer_summary, when present, is concise, source-grounded, and non-authoritative.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for handoff notes when review state changes; focus on regressions, hidden scope expansion, lifecycle drift, missing evidence, and unnecessary complexity that affects the approved task; label uncertainty explicitly; do not integrate or finish tasks; do not replace canonical PR sections, freshness checks, validation, or raw evidence with narrative.",
     "stop.rules": "Stop rules: stop or mark review blocked on insufficient diff, missing Verify Steps, missing evidence, scope mismatch, stale PR artifacts, or repository state that makes the review non-reproducible.",
     "output": "Output: severity-ordered findings, exact references, tests/evidence reviewed, recommendation per task, and open questions that could change the decision."
   }

package/assets/agents/UPGRADER.json

@@ -1,7 +1,7 @@
 {
   "id": "UPGRADER",
-  "role": "Review and finalize framework upgrades after `ap upgrade` without reintroducing stale local drift.",
-  "description": "Validates replace-first upgrade results, ensures policy and prompt consistency, and preserves only sanctioned local history such as append-only incidents.",
+  "role": "Validate and finalize framework upgrades after `ap upgrade` without reintroducing stale local drift.",
+  "description": "Validates replace-first upgrade results, checks policy and prompt consistency, and preserves only sanctioned local history such as append-only incidents. It does not perform semantic human edits to managed agent files during upgrade.",
   "inputs": {
     "upgrade.run": "Upgrade run directory containing plan, constraints, report artifacts, and review.json when available.",
     "changed.files": "Changed files from files.json or review.json in the upgrade report.",
@@ -18,9 +18,9 @@
     "terminal.checks": "Terminal: run local checks for changed areas and summarize evidence."
   },
   "workflow": {
-    "goal": "Goal: review and finalize framework upgrade outputs without reintroducing stale local drift or contradictions with current enforcement.",
+    "goal": "Goal: validate and finalize framework upgrade outputs without reintroducing stale local drift or contradictions with current enforcement.",
     "success.criteria": "Success criteria: upgrade run artifacts are loaded; changed files are inspected before editing; managed files are reconciled with gateway priority; append-only incident history is preserved; checks appropriate to touched surfaces are recorded.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for lifecycle and commits; treat managed files as replace-first upgrade outputs; avoid speculative prompt rewrites beyond the upgrade contract.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `ap` for lifecycle and commits; treat managed files as replace-first upgrade outputs; do not perform semantic rewrites to managed agent files; preserve only sanctioned local user-instructions and append-only incident history.",
     "stop.rules": "Stop rules: stop when run artifacts are missing, upgrade output conflicts with enforcement, generated artifacts disagree with source state, repository state is unsafe, or required verification cannot be run.",
     "output": "Output: upgraded files reviewed, conflicts found, decisions taken, checks run, runDir reference, and remaining follow-up tasks."
   }

package/assets/evaluators/recovery-context.md

@@ -0,0 +1,47 @@
+---
+id: recovery-context
+title: Recovery Context Invariant Review
+version: 1
+status: preview
+profile: EVALUATOR
+tags:
+  - recovery
+  - invariants
+  - concurrency
+---
+
+# Recovery Context Invariant Review
+
+Use this evaluator only when the primary implementation path already produced a concrete change or when recovery context is needed after an interruption.
+
+## Inputs
+
+- Task id, task README, approved plan, and Verify Steps.
+- Current diff or PR patch.
+- Relevant comments, review findings, incidents, and recovery/handoff context.
+- Known concurrent-agent activity and task-artifact drift classification, if present.
+
+## Review Procedure
+
+1. Reconstruct the intended contract from the task, not from the implementation summary.
+2. Compare the diff against explicit invariants, stop rules, negative cases, and user constraints.
+3. Check whether recovery context changes the interpretation of the task or exposes stale assumptions.
+4. Inspect concurrency-sensitive paths and classify whether observed drift belongs to active agent work, stale handoff, or unrelated workspace drift.
+5. Identify missing tests, missing docs, or verification that only proves the happy path.
+6. Do not execute fixes. Return review findings only.
+
+## Output
+
+Return a concise structured review:
+
+- `verdict`: `pass`, `rework`, or `blocked`.
+- `findings`: ordered by severity, each with file/path evidence and the broken invariant.
+- `missing_tests`: concrete tests or checks that would have caught the issue.
+- `hidden_assumptions`: assumptions the implementation relies on but did not prove.
+- `recovery_context`: what the next agent should know only if normal context is insufficient.
+
+## Stop Rules
+
+- Use `blocked` when required task context, diff, or recovery context is missing.
+- Use `rework` when behavior diverges from the approved contract even if local checks pass.
+- Use `pass` only when the implementation and verification evidence cover positive, negative, and concurrency-sensitive paths relevant to the task.

package/assets/framework.manifest.json

@@ -15,6 +15,13 @@
       "merge_strategy": "agent_json_3way",
       "required": true
     },
+    {
+      "path": ".agentplane/agents/CURATOR.json",
+      "source_path": "agents/CURATOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
     {
       "path": ".agentplane/agents/DOCS.json",
       "source_path": "agents/DOCS.json",
@@ -29,6 +36,20 @@
       "merge_strategy": "agent_json_3way",
       "required": true
     },
+    {
+      "path": ".agentplane/agents/EXTRACTOR.json",
+      "source_path": "agents/EXTRACTOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
+    {
+      "path": ".agentplane/agents/INTAKE.json",
+      "source_path": "agents/INTAKE.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
     {
       "path": ".agentplane/agents/INTEGRATOR.json",
       "source_path": "agents/INTEGRATOR.json",
@@ -64,13 +85,6 @@
       "merge_strategy": "agent_json_3way",
       "required": true
     },
-    {
-      "path": ".agentplane/agents/SKILL_EXTRACTOR.json",
-      "source_path": "agents/SKILL_EXTRACTOR.json",
-      "type": "json",
-      "merge_strategy": "agent_json_3way",
-      "required": true
-    },
     {
       "path": ".agentplane/agents/TESTER.json",
       "source_path": "agents/TESTER.json",
@@ -92,6 +106,13 @@
       "merge_strategy": "agent_json_3way",
       "required": true
     },
+    {
+      "path": ".agentplane/evaluators/recovery-context.md",
+      "source_path": "evaluators/recovery-context.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
     {
       "path": ".agentplane/policy/check-routing.mjs",
       "source_path": "policy/check-routing.mjs",
@@ -204,5 +225,11 @@
       "merge_strategy": "agents_policy_markdown",
       "required": true
     }
+  ],
+  "removals": [
+    {
+      "path": ".agentplane/agents/SKILL_EXTRACTOR.json",
+      "type": "json"
+    }
   ]
 }

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: INTEGRATOR runs integration from the base checkout; protected bases finalize through the task GitHub PR merge, not a direct local base mutation.
+9. CHECKPOINT C: finish/close-tail evidence lands after the task PR merge and hosted close route complete.
+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 --drain --wait --poll-interval-ms 30000 --timeout-ms 600000
 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
 ```
@@ -62,7 +65,16 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 - 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.
+- In `branch_pr`, the task GitHub PR is the primary integration mechanism. Local `integrate`
+  serializes the lane and drives the provider merge route; it MUST NOT treat GitHub PR merge as an
+  exceptional shortcut around local base mutation.
+- If protected `main` requires GitHub PR merges, the agent MUST create/update the GitHub PR,
+  wait until all hosted checks are complete and stable (including late agent checks that appear
+  after the first green rollup), then merge it through GitHub. If auto-merge remains blocked
+  after stable green checks, the agent MUST continue with the permitted GitHub merge route
+  available to its credentials instead of stopping at enabled auto-merge.
 - `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; agents waiting behind `claimed` or `handoff` entries SHOULD use bounded polling (`--wait --poll-interval-ms 30000 --timeout-ms 600000`) instead of retrying ad hoc; 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/bin/agentplane.js

@@ -2,7 +2,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { mkdir, rm, stat } from "node:fs/promises";
+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
@@ -202,14 +202,55 @@ async function withBootstrapLock(repoRoot, fn) {
     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;
+    const owner = await (async () => {
+      try {
+        return JSON.parse(await readFile(path.join(lockDir, "owner.json"), "utf8"));
+      } catch {
+        return null;
+      }
+    })();
+    if (owner && typeof owner.pid === "number") {
+      let alive = true;
+      try {
+        process.kill(owner.pid, 0);
+      } catch (ownerError) {
+        alive = ownerError?.code === "EPERM";
+      }
+      if (alive) {
+        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;
+      }
+      await rm(lockDir, { recursive: true, force: true });
+      await mkdir(lockDir, { recursive: false });
+    } else {
+      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;
+    }
   }
 
+  await writeFile(
+    path.join(lockDir, "owner.json"),
+    JSON.stringify(
+      {
+        pid: process.pid,
+        operation: "agentplane-auto-bootstrap",
+        acquired_at: new Date().toISOString(),
+        repo_root: repoRoot,
+      },
+      null,
+      2,
+    ) + "\n",
+    "utf8",
+  );
+
   try {
     return await fn();
   } finally {
@@ -239,6 +280,12 @@ async function autoBootstrapAndRerun(repoRoot, staleReasons, commandPolicy) {
       env: {
         ...process.env,
         AGENTPLANE_DEV_AUTO_BOOTSTRAP: "0",
+        AGENTPLANE_FRAMEWORK_BUILD_LOCK_PATH: path.join(
+          repoRoot,
+          ".agentplane",
+          "cache",
+          "framework-dev-bootstrap.lock",
+        ),
       },
     });
 

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.6.0",
+  "git_head": "5210d5e80d61908e7e3100383fc7a6a65fb697e5",
+  "watched_runtime_snapshot_hash": "cea114f499ac1d9c6b7a1878e323d6ec16d60042a7a3342d0ae446efb5b26299"
 }