agentplane 0.5.0 → 0.6.0

package/README.md

@@ -6,7 +6,7 @@
 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.
+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)
@@ -57,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
 

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/workflow.branch_pr.md

@@ -16,8 +16,8 @@ Use this module when `workflow_mode=branch_pr`.
 5. Publish/update PR artifacts from the task worktree.
 6. Verify on the task branch.
 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.
+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
@@ -48,7 +48,7 @@ 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 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
 ```
@@ -65,8 +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; stale branch heads move to rework instead of blocking later queued work.
+- 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/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.5.0",
-  "git_head": "59109bfdc8a9746402a76fb9c7a428f75d6977f3",
-  "watched_runtime_snapshot_hash": "84365a7e93d3cd3d5b9c54bf9f3787fa7e11b2eaf257ba0c9ab3aa531fac5764"
+  "package_version": "0.6.0",
+  "git_head": "5210d5e80d61908e7e3100383fc7a6a65fb697e5",
+  "watched_runtime_snapshot_hash": "cea114f499ac1d9c6b7a1878e323d6ec16d60042a7a3342d0ae446efb5b26299"
 }