agentplane 0.3.10 → 0.3.12

package/assets/AGENTS.md

@@ -65,7 +65,7 @@ agentplane task new --title "..." --description "..." --priority med --owner <RO
 agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
 agentplane task plan approve <task-id> --by ORCHESTRATOR
 agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
-agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
+agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..." [--observation "..." --impact "..." --resolution "..."] [--local-only]
 agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
@@ -83,7 +83,7 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 
 ```bash
 agentplane task verify-show <task-id>
-agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
+agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..." [--observation "..." --impact "..." --resolution "..."] [--local-only]
 agentplane incidents advise <task-id>
 agentplane incidents collect <task-id> --check
 agentplane doctor

package/assets/agents/CODER.json

@@ -19,10 +19,14 @@
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Restate the active task scope, target behavior, and any blocking unknowns before editing; inspect the repository first instead of guessing.",
+    "State assumptions and ambiguities explicitly; if multiple interpretations or a simpler viable approach exist, say so before editing instead of choosing silently.",
     "Keep diffs minimal, task-scoped, and easy to review; if the root cause or blast radius expands materially, stop and route drift back through ORCHESTRATOR or PLANNER.",
     "Prefer existing patterns, helpers, and tests over new abstractions; explain deliberate deviations rather than silently introducing them.",
+    "Do not add speculative features, configurability, abstractions, or impossible-scenario handling beyond the approved task.",
+    "Keep changes surgical: touch only files and lines that trace directly to the request, and remove only the unused code your own edits create.",
     "Document edits with exact file paths and concise before/after rationale.",
     "Run the smallest sufficient local commands (tests/linters/formatters) and summarize only the output lines that change a decision.",
+    "Turn the task into verifiable goals before coding: prefer a reproducing or acceptance check first, then loop until it passes.",
     "Prefer declared verify commands; treat `Verify Steps` as the acceptance contract and request PLANNER updates when the contract itself drifts.",
     "Record local deviations, follow-ups, and incident candidates in the task-local observation section (`Notes` for v2, `Findings` for v3); use structured `incident-candidate` blocks for external/unfixable-in-repo incidents and let `finish` or `agentplane incidents collect` promote them.",
     "Separate confirmed facts, inferred risks, and open questions in handoff summaries.",

package/assets/agents/CREATOR.json

@@ -18,6 +18,7 @@
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Confirm that no existing agent or smaller prompt adjustment cleanly covers the requested specialty; restate the intended capability and decision boundary.",
+    "State assumptions and unresolved boundary questions explicitly; prefer the smallest prompt change to an existing role over creating a new agent for speculative flexibility.",
     "Create the new agent JSON with uppercase snake case ID and crisp IO/permissions/workflow that do not overlap existing roles.",
     "Keep the new prompt explicit, minimal, and workflow-compatible with AGENTS.md precedence.",
     "Update AGENTS.md registry guidance as needed and refresh any derived lists per spec.",

package/assets/agents/DOCS.json

@@ -18,8 +18,9 @@
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Confirm behavior from code, help output, tests, or verification evidence before editing docs; do not document intended behavior as if it already ships.",
+    "State any documentation assumptions explicitly; if behavior is ambiguous, stop at the evidence boundary instead of filling the gap with plausible prose.",
     "Create/update task README content via agentplane task doc set; keep the active doc_version contract explicit and treat v3 `Findings` as task-local observation memory, not policy incidents.",
-    "Update only the docs surfaces required for the changed behavior and keep wording aligned with gateway/policy/CLI precedence.",
+    "Update only the docs surfaces required for the changed behavior and keep wording aligned with gateway/policy/CLI precedence; keep edits surgical and task-scoped.",
     "When generated or mirrored docs exist, update the canonical source or generation path instead of hand-editing downstream artifacts.",
     "Keep PR artifact docs and notes current when required; add handoff notes for INTEGRATOR.",
     "Separate confirmed behavior, known caveats, and deferred follow-up in summaries.",

package/assets/agents/INTEGRATOR.json

@@ -19,10 +19,11 @@
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Operate from the repo root on the pinned base branch; treat integration as a state machine: confirm preconditions -> run pr check -> integrate -> finish via agentplane.",
+    "State branch, metadata, and verification assumptions explicitly before mutating base; if they are not satisfied, stop instead of inferring missing state.",
     "Stop on dirty base state, stale PR artifacts, missing verification evidence, or branch/task mismatch; do not paper over inconsistent state.",
     "Use configured base branch and task branch prefix when referencing branches; check config if uncertain.",
     "Ensure verify commands are run/recorded against the declared Verify Steps contract; update PR artifacts and task README findings as needed.",
-    "Keep integration writes limited to merge outputs, required verification artifacts, and deterministic closure updates.",
+    "Keep integration writes limited to merge outputs, required verification artifacts, and deterministic closure updates; avoid adjacent cleanup that is not directly required by the task state machine.",
     "When closing multiple tasks, use batch finish only when the same verification evidence and commit metadata genuinely apply.",
     "Summaries should distinguish merged commit(s), verification evidence, and any remaining cleanup.",
     "Check `closure_commit_requires_approval` in .agentplane/config.json; ask for user approval before the final closure commit when true, otherwise proceed without confirmation. Optionally clean task branches/worktrees after closure."

package/assets/agents/ORCHESTRATOR.json

@@ -18,6 +18,8 @@
     "Use `agentplane config show|set` for config changes (workflow_mode, branch/task settings); avoid manual edits.",
     "Convert the first user message into an execution plan; do not create tasks until the user approves it.",
     "Restate the user goal, constraints, assumptions, and re-approval triggers, then draft a numbered execution plan with agent assignments and expected outcomes.",
+    "State assumptions explicitly, surface competing interpretations instead of choosing silently, and prefer the simplest viable plan over speculative flexibility.",
+    "Make each plan step goal-driven with a concrete verification check or observable pass condition whenever the repository already has an enforcement surface.",
     "Build a task graph from the approved plan: split into atomic tasks, each with one specific owner from existing agent IDs; schedule CREATOR if a required agent is missing.",
     "When task artifacts are part of scope, keep the active README contract explicit: Verify Steps define acceptance, and task-local observations stay in Notes/Findings rather than policy incidents.",
     "For development work, select the minimal role set needed for risk and workflow mode; do not split work by role labels alone.",

package/assets/agents/PLANNER.json

@@ -19,10 +19,12 @@
     "Review the backlog before changes to avoid duplicates or conflicts.",
     "After overall plan approval, create executable tasks directly from the approved task graph plan.",
     "If task graph planning yields exactly one work item, create exactly one task and keep full traceability there.",
+    "State planning assumptions explicitly; if scope is ambiguous, resolve that ambiguity before multiplying tasks.",
+    "Prefer the smallest task graph that preserves ownership and verification; do not split work for hypothetical future flexibility.",
     "Split goals into atomic tasks only at real deliverable, owner, or dependency boundaries; set depends_on explicitly (use [] for none).",
     "Create tasks with valid parameters: non-empty title/description/owner, at least one meaningful tag, deduped depends_on/verify.",
     "Write titles, descriptions, and Plans as observable work, not implementation poetry.",
-    "Treat Verify Steps as concrete acceptance checks; encode uncertainty as explicit scope notes or follow-up tasks, not vague README prose.",
+    "Treat Verify Steps as concrete acceptance checks; translate goals into verifiable checks or commands when possible, and encode uncertainty as explicit scope notes or follow-up tasks instead of vague README prose.",
     "Keep task-local observations in Notes/Findings rather than policy incidents.",
     "Before creating a new task, check open tasks (`TODO|DOING|BLOCKED`) and reuse/update a matching task when scope and owner align.",
     "Do not create separate tasks for role handoffs unless there is an independent deliverable, a different required owner, or an explicit dependency boundary.",

package/assets/agents/REVIEWER.json

@@ -16,6 +16,7 @@
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Review changes against approved scope, changed behavior, and declared verification contract before forming conclusions.",
     "Prioritize confirmed defects first, then plausible risks, then open questions; label uncertainty explicitly.",
+    "Flag unnecessary complexity explicitly: speculative flexibility, avoidable abstractions, and scope creep are review defects when they do not serve the approved task.",
     "Prefer PR artifact review when present (README completeness, diffstat, verify log).",
     "Report findings ordered by severity with exact file/line references and concise testing notes.",
     "Focus on regressions, hidden scope expansion, lifecycle drift, and missing evidence rather than style-only commentary.",

package/assets/agents/TESTER.json

@@ -20,9 +20,9 @@
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Restate the behavior under test, the declared acceptance contract, and the likely regression surface before adding tests or running checks.",
     "Identify existing test tooling and reuse it; do not add new frameworks unless requested.",
-    "Add the smallest set of high-value tests that distinguishes working behavior from the most likely failure modes.",
+    "Add the smallest set of high-value tests that distinguishes working behavior from the most likely failure modes; prefer the narrowest reproducer or acceptance check first.",
     "Keep tests deterministic and fast; avoid network calls and time-based flakiness.",
-    "If behavior is ambiguous, escalate instead of encoding guesses into tests.",
+    "If behavior or success criteria are ambiguous, escalate instead of encoding guesses into tests.",
     "Run targeted tests first and summarize only the key output lines.",
     "Check results against `Verify Steps` as the acceptance contract, not just against ad-hoc commands.",
     "Record residual gaps in the task-local observation section (`Notes` for v2, `Findings` for v3) rather than escalating them directly into policy incidents.",

package/assets/agents/UPDATER.json

@@ -19,6 +19,7 @@
     "Confirm the user explicitly summoned UPDATER; otherwise hand control back to ORCHESTRATOR.",
     "Audit AGENTS.md and .agentplane/agents/*.json plus relevant repo files, citing exact paths.",
     "Distinguish correctness issues, ambiguity/UX friction, and structural overlap; prioritize by blast radius and recurrence risk.",
+    "State assumptions, tradeoffs, and the simplest effective change before recommending broader prompt or workflow rewrites.",
     "Recommend the smallest prompt/system changes that improve behavior; avoid broad rewrites without evidence.",
     "Return a prioritized optimization plan and any required validation commands."
   ]

package/assets/agents/UPGRADER.json

@@ -21,7 +21,7 @@
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "Treat `AGENTS.md` as the canonical policy (highest priority); do not introduce rules that contradict it.",
     "Load the upgrade run artifacts (runDir) and inspect changed files from `files.json` / `review.json` before editing anything.",
-    "Treat managed files as replace-first outputs from upgrade; do not re-introduce manual merge paths.",
+    "Treat managed files as replace-first outputs from upgrade; do not re-introduce manual merge paths or speculative prompt rewrites beyond what the contract requires.",
     "For `.agentplane/policy/incidents.md`, ensure local history is append-only and not overwritten.",
     "Reconcile `.agentplane/agents/*.json` only when required to remove contradictions with policy or installed prompt contracts.",
     "Stop and report when upgrade output conflicts with current enforcement, generated artifacts, or the installed agent contract.",

package/assets/policy/governance.md

@@ -6,15 +6,14 @@
 - Incident-derived and situational rules MUST be added only to `incidents.md`.
 - MUST NOT create additional incident policy files under `.agentplane/policy/`.
 - New reusable operational incidents SHOULD be promoted from task `Findings` via `agentplane finish` or `agentplane incidents collect <task-id>`.
-- Auto-promotion is reserved for explicit `incident-candidate` blocks marked `IncidentExternal: true`; repository-fixable defects stay task-local unless curated manually.
+- Auto-promotion is reserved for resolved reusable findings marked `Fixability: external` or `Fixability: repo-fixable` (or the compatibility markers `IncidentExternal: true` / `IncidentInternal: true`); optional `IncidentScope`, `IncidentAdvice`, `IncidentRule`, `IncidentTags`, and `IncidentMatch` fields override the inferred registry entry when needed.
 - Normal startup MUST NOT bulk-load `incidents.md`; targeted lookup for analogous work is allowed through `task start-ready` and `agentplane incidents advise`.
 
 ## Stabilization criteria
 
-Use `stabilized` only when one of these is true:
+Use `stabilized` only when the same failure class recurs at least 2 times in 30 days.
 
-1. The same failure class recurs at least 2 times in 30 days.
-2. A single Sev-1 / production-blocking failure has reproducible steps and evidence.
+First auto-promoted external incidents may stay `open`, but targeted advice lookup is still allowed to use them so analogous work can reuse the recovery guidance before the second recurrence.
 
 Promotion from `incidents.md` into canonical policy modules is allowed only when:
 

package/assets/policy/incidents.md

@@ -1,90 +1,22 @@
 # Policy Incidents Log
 
-This is the single file for incident-derived and situational policy rules.
-
-## Entry contract
-
-- Add entries append-only.
-- Every entry MUST include: `id`, `date`, `scope`, `failure`, `rule`, `evidence`, `enforcement`, `state`.
-- New machine-matched entries SHOULD also include: `tags`, `match`, `advice`, `source_task`, `fixability`.
-- `rule` MUST be concrete and testable (`MUST` / `MUST NOT`).
-- `fixability: external` means the issue cannot be removed by changing only repository code and should stay as reusable operational advice.
-- `state` values: `open`, `stabilized`, `promoted`.
-
-## Entry template
-
-- id: `INC-YYYYMMDD-NN`
-- date: `YYYY-MM-DD`
-- scope: `<affected scope>`
-- tags: `<comma-separated matching tags>`
-- match: `<comma-separated lookup keywords>`
-- failure: `<observed failure mode>`
-- advice: `<reusable recovery or prevention guidance>`
-- rule: `<new or refined MUST/MUST NOT>`
-- evidence: `<task ids / logs / links>`
-- enforcement: `<CI|test|lint|script|manual>`
-- source_task: `<task id>`
-- fixability: `<external>`
-- state: `<open|stabilized|promoted>`
-
-## Entries
-
-- id: INC-20260308-01
-  date: 2026-03-08
-  scope: release apply internal push path
-  tags: release, git, hooks
-  match: release, push, pre-push, hooks
-  failure: release apply re-entered local pre-push hooks and could stall after creating the local release commit and tag
-  advice: keep release ref pushes inside the release orchestrator path and avoid recursively re-entering local pre-push hooks
-  rule: Release orchestration MUST push its own release refs without recursively re-entering local pre-push hooks.
-  evidence: task 202603061532-9Y41NM; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 4
-  enforcement: test + command implementation
-  state: stabilized
-
-- id: INC-20260308-02
-  date: 2026-03-08
-  scope: stale-dist guard in framework checkout
-  tags: runtime, framework, diagnostics
-  match: stale-dist, runtime, dirty-tree, diagnostics
-  failure: stale-dist enforcement treated git dirtiness as stale runtime and blocked diagnostics or rebuilt checkouts incorrectly
-  advice: compare stale-dist state against recorded build snapshots and let read-only diagnostics warn instead of hard-failing on dirty runtime trees
-  rule: Stale-dist freshness MUST compare current runtime inputs against the recorded build snapshot, and read-only diagnostics MUST warn-and-run instead of hard-failing on dirty runtime trees.
-  evidence: tasks 202603072032-2M0V8V, 202603072032-1BC7VQ, 202603072032-V9VGT2, 202603072032-4D9ASG
-  enforcement: test + runtime guard
-  state: stabilized
-
-- id: INC-20260308-03
-  date: 2026-03-08
-  scope: framework checkout PATH resolution
-  tags: runtime, framework, cli
-  match: path, runtime, handoff, global-cli
-  failure: contributors inside the framework repo could execute an older global agentplane binary instead of the checkout they were editing
-  advice: verify the active runtime inside the framework checkout and keep PATH handoff repo-local by default unless a deliberate global override is set
-  rule: Inside the framework checkout, agentplane resolved from PATH MUST hand off to the repo-local runtime by default unless an explicit global opt-out is set.
-  evidence: tasks 202603071647-M0Q79C, 202603071647-Y4BZ1T, 202603071647-25WS52
-  enforcement: test + wrapper logic
-  state: stabilized
-
-- id: INC-20260308-04
-  date: 2026-03-08
-  scope: release mutation generated surfaces
-  tags: release, docs, generated
-  match: release, generated-docs, versioned-docs
-  failure: release apply could leave version-sensitive generated docs stale until later parity checks failed
-  advice: regenerate version-sensitive generated docs inside the release mutation itself instead of deferring them to later parity checks
-  rule: Release mutation MUST regenerate and stage generated docs that encode released package versions as part of the release commit itself.
-  evidence: task 202603071745-T3QE04; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 5
-  enforcement: test + release mutation
-  state: stabilized
-
-- id: INC-20260308-05
-  date: 2026-03-08
-  scope: release mutation repository CLI expectation
-  tags: release, cli, config
-  match: release, expected-version, config
-  failure: repository-owned framework.cli.expected_version could drift behind the actual released version because release apply did not persist it
-  advice: keep repository CLI expectation aligned with the released package version whenever release mutation touches repository config
-  rule: Release mutation MUST keep framework.cli.expected_version aligned with the released package version whenever repository config is present.
-  evidence: tasks 202603081315-Y4D6AE, 202603081538-GF7P9C; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 3
-  enforcement: test + release mutation
-  state: stabilized
+- Append-only. Required fields: `id`, `date`, `scope`, `failure`, `rule`, `evidence`, `enforcement`, `state`; optional: `tags`, `match`, `advice`, `source_task`, `fixability`.
+- id: INC-20260308-01 | date: 2026-03-08 | scope: release apply internal push path | failure: release apply re-entered local pre-push hooks and could stall after creating the local release commit and tag | rule: Release orchestration MUST push its own release refs without recursively re-entering local pre-push hooks. | evidence: task 202603061532-9Y41NM; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 4 | enforcement: test + command implementation | state: stabilized
+- id: INC-20260308-02 | date: 2026-03-08 | scope: stale-dist guard in framework checkout | failure: stale-dist enforcement treated git dirtiness as stale runtime and blocked diagnostics or rebuilt checkouts incorrectly | rule: Stale-dist freshness MUST compare current runtime inputs against the recorded build snapshot, and read-only diagnostics MUST warn-and-run instead of hard-failing on dirty runtime trees. | evidence: tasks 202603072032-2M0V8V, 202603072032-1BC7VQ, 202603072032-V9VGT2, 202603072032-4D9ASG | enforcement: test + runtime guard | state: stabilized
+- id: INC-20260308-03 | date: 2026-03-08 | scope: framework checkout PATH resolution | failure: contributors inside the framework repo could execute an older global agentplane binary instead of the checkout they were editing | rule: Inside the framework checkout, agentplane resolved from PATH MUST hand off to the repo-local runtime by default unless an explicit global opt-out is set. | evidence: tasks 202603071647-M0Q79C, 202603071647-Y4BZ1T, 202603071647-25WS52 | enforcement: test + wrapper logic | state: stabilized
+- id: INC-20260308-04 | date: 2026-03-08 | scope: release mutation generated surfaces | failure: release apply could leave version-sensitive generated docs stale until later parity checks failed | rule: Release mutation MUST regenerate and stage generated docs that encode released package versions as part of the release commit itself. | evidence: task 202603071745-T3QE04; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 5 | enforcement: test + release mutation | state: stabilized
+- id: INC-20260308-05 | date: 2026-03-08 | scope: release mutation repository CLI expectation | failure: repository-owned framework.cli.expected_version could drift behind the actual released version because release apply did not persist it | rule: Release mutation MUST keep framework.cli.expected_version aligned with the released package version whenever repository config is present. | evidence: tasks 202603081315-Y4D6AE, 202603081538-GF7P9C; docs/developer/cli-bug-ledger-v0-3-x.mdx entry 3 | enforcement: test + release mutation | state: stabilized
+- id: INC-20260407-01 | date: 2026-04-07 | scope: branch_pr GitHub transport helpers | failure: GitHub transport intermittently failed with GraphQL EOF, TLS handshake errors, and SSL_ERROR_SYSCALL during PR creation, remote-check waiting, and reconcile helpers | advice: treat transient GitHub transport failures as retriable, prefer bounded polling or REST fallbacks over single-shot watch flows, and surface auth or usage failures immediately | rule: GitHub-dependent workflow helpers MUST classify EOF/TLS/SSL transport failures as transient and retry with bounded backoff; they MUST surface auth and usage failures immediately instead of looping or failing opaquely. | evidence: tasks 202604062101-XYXG7Y, 202604062309-QE4CX6, 202604050745-18JJ5E | enforcement: test + workflow helper | state: open
+- id: INC-20260407-02 | date: 2026-04-07 | scope: protected-main branch_pr closure permissions | failure: hosted branch_pr closure could not create follow-up PRs when the GitHub App or Actions token lacked PR creation rights, leaving manual closure tails after the task PR was already merged | advice: preserve deterministic closure metadata in task artifacts and complete the closure PR from an authenticated local session when hosted automation lacks create-PR permission | rule: Protected-main branch_pr closure MUST preserve enough task metadata for deterministic manual reconciliation when hosted automation cannot create the closure PR due to external GitHub permission limits. | evidence: tasks 202604032235-G375FB, 202604050745-18JJ5E, 202604062153-RSJFC2 | enforcement: manual + workflow | state: open
+- id: INC-20260407-03 | date: 2026-04-07 | scope: task findings incident promotion | failure: Structured findings needed hidden promote/external flags before incidents collection could see them. | advice: Use task findings add defaults for reusable incident candidates; use --local-only only for task-scoped notes. | rule: Structured findings intended as reusable workflow advice MUST promote by default; task-local-only notes MUST opt out explicitly with --local-only. | evidence: task 202604070754-ZD0ZAZ | enforcement: manual | state: open
+- id: INC-20260407-04 | date: 2026-04-07 | scope: task normalize hosted reconcile target selection | failure: GitHub EOF or TLS transport failures during hosted branch_pr reconcile could abort task normalize before it reached the known stale task because the command scanned every candidate task. | advice: When GitHub transport is flaky, reconcile only the known task ids instead of scanning the full branch_pr history. | rule: Hosted reconcile commands MUST support explicit task-id scoping so known drift can be resolved without depending on unrelated GitHub lookups. | evidence: task 202604071853-XGX2YJ; commit 5fd312cceb20 | enforcement: manual | state: open
+- id: INC-20260409-01 | date: 2026-04-09 | scope: branch_pr work-start base task README cleanup | failure: work start --worktree left untracked .agentplane/tasks/<task-id>/README.md copies in the base checkout and later git pull could block once upstream tracked the same paths | rule: branch_pr work start MUST remove base-checkout task README copies that were only materialized for the worktree, while keeping the worktree-local copies intact. | evidence: task 202604081931-77V6J5 | enforcement: test + command implementation | state: stabilized
+- id: INC-20260409-02 | date: 2026-04-09 | scope: branch_pr follow-up orchestration helpers | match: branch_pr, integrate, pr artifacts, pr meta, wait-remote-checks, remote checks, multi pr | failure: integrate recovery assumed PR artifacts already existed and the remote-check wait helper only accepted one PR target, forcing manual base-side hydration and serial closure-wave waiting. | advice: keep integrate able to recover PR metadata without a pre-hydrated base checkout and let remote-check waiting accept explicit PR batches during closure waves. | rule: branch_pr follow-up helpers MUST recover missing PR artifacts from available branch or hosted metadata and MUST accept explicit multi-PR batches so integrate and remote-check waiting stay runnable during closure waves. | evidence: tasks 202604091136-SR7Z25, 202604091136-V5N3P8; fixes 202604091218-WWSX2G, 202604091218-8S07FZ | enforcement: test + command implementation | state: open
+- id: INC-20260409-03 | date: 2026-04-09 | scope: Make branch_pr hosted-merge reconcile and task normalize resolve GitHub auth from the user's existing gh login, without requiring a manual GH_TOKEN export in the shell. | tags: code, github, workflow | match: code, github, workflow, make, branch, hosted, merge, reconcile, and, task, normalize, resolve, auth, from, the, user | failure: Repo dotenv loading could inject GITHUB_TOKEN into gh subprocesses and override a valid gh keyring session during hosted merge sync. | advice: Track auth vars loaded only from repo dotenv and strip them from gh child env, while preserving explicit shell or CI auth tokens and HOME-based gh sessions. | rule: Analogous Make branch_pr hosted-merge reconcile and task normalize resolve GitHub auth from the user's existing gh login, without requiring a manual GH_TOKEN export in the shell. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604091841-2ZX1MQ; commit 3f71884dad3e | enforcement: manual | fixability: external | state: open
+- id: INC-20260409-04 | date: 2026-04-09 | scope: Make merged branch_pr tasks land in tracked main history as DONE with reconciled PR metadata, so pulling origin/main does not reopen them as DOING or require local normalize dirt. | tags: code, tasks, workflow | match: code, tasks, workflow, make, merged, branch, land, tracked, main, history, done, with, reconciled, metadata, pulling, origin | failure: Hosted-close recovery had to be driven one task at a time even when multiple remote task-close branches were already waiting, so merged tasks stayed DOING on main longer than necessary. | advice: Allow task hosted-close-pr to accept multiple task ids in one invocation so closure PR batches can be materialized deterministically from the existing remote task-close branches. | rule: Analogous Make merged branch_pr tasks land in tracked main history as DONE with reconciled PR metadata, so pulling origin/main does not reopen them as DOING or require local normalize dirt. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604091841-PX5WAV | enforcement: manual | fixability: external | state: open
+- id: INC-20260409-05 | date: 2026-04-09 | scope: branch_pr verify/finish incident no-op messaging | tags: incidents, workflow, ux | match: incidents, workflow, ux, branch, verify, finish, incident, messaging, explain, registry, outcome, explicitly, and, operators, still, misread | failure: Lifecycle no-op output for verify and finish looked indistinguishable from a broken incidents pipeline, so operators could not tell when incidents.md stayed unchanged only because the note/body was plain text. | advice: Print context-specific verify and finish messages that explicitly name incidents.md, explain that plain notes stay task-local, and point operators at observation/impact/resolution fields or explicit collection on base. | rule: Analogous branch_pr verify/finish incident no-op messaging work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604092105-RF8TWW | enforcement: manual | fixability: repo-fixable | state: open
+- id: INC-20260410-01 | date: 2026-04-10 | scope: Preflight hides cross-task workflow artifact drift when tracked status looks clean. | tags: workflow, git, ux, code | match: workflow, git, ux, code, preflight, hides, cross, task, artifact, drift, when, tracked, status, looks, clean, expose | failure: Preflight could report a tracked-clean working tree while untracked .agentplane/tasks artifacts from other task ids were still present and capable of breaking later integrate or close flows. | advice: Preflight now inspects full changed paths under the workflow task directory, reports task artifact drift explicitly in JSON/text output, and points operators at git status --short --untracked-files=all -- .agentplane/tasks. | rule: Analogous Preflight hides cross-task workflow artifact drift when tracked status looks clean. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604100023-MFGFK9; commit a2b9ccf1e12e | enforcement: manual | fixability: repo-fixable | state: open
+- id: INC-20260410-02 | date: 2026-04-10 | scope: Integrate leaves framework runtime stale after watched-source merges. | tags: workflow, runtime, git, code | match: workflow, runtime, git, code, integrate, leaves, framework, stale, after, watched, source, merges, auto, bootstrap, touches, sources | failure: Base-side integrate could land watched runtime source changes in the framework checkout, but the repo-local runtime stayed stale until the operator manually ran framework bootstrap before finish closeout. | advice: Integrate now auto-runs bun run framework:dev:bootstrap in framework checkouts when watched runtime sources changed, and falls back to explicit manual guidance only if the refresh fails. | rule: Analogous Integrate leaves framework runtime stale after watched-source merges. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604100023-EVJWDM; commit 0f4d2f9a92e0 | enforcement: manual | fixability: repo-fixable | state: open
+- id: INC-20260410-03 | date: 2026-04-10 | scope: Integrate currently can apply task code onto the base branch and only then discover that the task branch never committed .agentplane/tasks/<task-id>/pr artifacts. Validate the branch-backed task/PR artifact set before any merge-side mutation so base never advances when closeout metadata is absent. | tags: code, workflow | match: code, workflow, integrate, currently, can, apply, task, onto, the, base, branch, and, only, then, discover, that | failure: Integrate validated task/PR metadata too late: a task branch could omit committed .agentplane/tasks/<task-id>/pr artifacts and still reach merge-side mutation before failing. | advice: Added committed-artifact validation before merge-side mutation, covered the missing-artifact and post-merge-removal regressions, and updated prepare.test mocks for the new contract. | rule: Analogous Integrate currently can apply task code onto the base branch and only then discover that the task branch never committed .agentplane/tasks/<task-id>/pr artifacts. Validate the branch-backed task/PR artifact set before any merge-side mutation so base never advances when closeout metadata is absent. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604100213-MVAGSD | enforcement: manual | fixability: external | state: open
+- id: INC-20260410-04 | date: 2026-04-10 | scope: Verify-required task scaffolds currently seed a placeholder Verify Steps block that immediately fails plan approval. Generate concrete acceptance steps from the primary tag and any explicit verify commands so a freshly scaffolded task is reviewable without manual README surgery. | tags: code, workflow | match: code, workflow, verify, required, task, scaffolds, currently, seed, placeholder, steps, block, that, immediately, fails, plan, approval | failure: Verify-required task scaffolds could seed a placeholder Verify Steps block when no explicit verify command was supplied, so plan approval failed on a fresh task before any human refinement. | advice: Removed the placeholder path for verify-required scaffolds without explicit verify commands, updated warning text to reflect concrete seeded acceptance steps, and added regression coverage for task new, task derive, and plan approve. | rule: Analogous Verify-required task scaffolds currently seed a placeholder Verify Steps block that immediately fails plan approval. Generate concrete acceptance steps from the primary tag and any explicit verify commands so a freshly scaffolded task is reviewable without manual README surgery. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604100213-1AAPW1 | enforcement: manual | fixability: external | state: open
+- id: INC-20260410-05 | date: 2026-04-10 | scope: Generate the next patch release plan from v0.3.10, draft release notes, prepare a release candidate branch/PR, and reconcile the current mismatch between release apply --push and the protected-main publish route before any irreversible release action. | tags: release | match: release, generate, the, next, patch, plan, from, draft, notes, prepare, candidate, branch, and, reconcile, current, mismatch | failure: Protected-main publication remains intentionally deferred because agentplane release apply --push --yes still assumes a direct push/tag route while this repository publishes via main-driven automation. | advice: Push the release branch, review the candidate, and confirm a protected-main-safe publish path before running the final release apply/tag flow. | rule: Analogous Generate the next patch release plan from v0.3.10, draft release notes, prepare a release candidate branch/PR, and reconcile the current mismatch between release apply --push and the protected-main publish route before any irreversible release action. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604101009-36KKA9 | enforcement: manual | fixability: external | state: open

package/assets/policy/workflow.branch_pr.md

@@ -30,7 +30,7 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 - Task documentation updates MAY be batched within one turn before approval.
 - MUST run `task plan approve` then `task start-ready` as `Step 1 -> wait -> Step 2` (never parallel).
 - `task start-ready` MAY surface targeted incident advice for analogous scope/tags; follow it before widening scope.
-- Keep structured external `incident-candidate` findings in the task README; base-branch `finish` or `agentplane incidents collect <task-id>` promotes valid entries into `.agentplane/policy/incidents.md`.
+- 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.
 - Planning and closure happen on base checkout.
 - Do not export task snapshots from task branches.

package/assets/policy/workflow.direct.md

@@ -38,7 +38,7 @@ If any step fails:
    - `doc_version=3`: task `Findings`
 3. Mark task blocked: `agentplane block <task-id> --author <ROLE> --body "Blocked: ..."`.
 4. Request re-approval before scope/risk changes.
-5. If failure is external/process-related and should become reusable advice, record a structured `incident-candidate` block in `Findings` and let `agentplane finish` or `agentplane incidents collect <task-id>` promote it.
+5. If failure is external/process-related and should become reusable advice, record a structured `Observation` / `Impact` / `Resolution` block in `Findings` and mark it with `Fixability: external` (or `IncidentExternal: true`); plain prose in `Findings` stays task-local and does not update `.agentplane/policy/incidents.md`.
 
 ## Constraints
 
@@ -47,7 +47,7 @@ If any step fails:
 - MUST run `task plan approve` then `task start-ready` as `Step 1 -> wait -> Step 2` (never parallel).
 - `task start-ready` MAY surface targeted incident advice for analogous scope/tags; follow it before widening scope.
 - In direct mode, `finish` auto-creates the deterministic close commit by default; use `--no-close-commit` only for explicit manual handling.
-- `finish` evaluates structured external `incident-candidate` findings and appends valid entries to `.agentplane/policy/incidents.md`.
+- `finish` evaluates structured resolved external findings, auto-derives incident advice when only `Observation` / `Impact` / `Resolution` plus `Fixability: external` are present, and appends valid entries to `.agentplane/policy/incidents.md`; plain `Findings` text remains task-local.
 - MUST stop and request re-approval on material drift.
 - Do not use worktrees in direct mode.
 - Do not perform `branch_pr`-only operations.

package/bin/agentplane.js

@@ -2,6 +2,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { stat } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
 import {
@@ -25,7 +26,17 @@ async function exists(p) {
 async function maybeWarnGlobalBinaryInRepoCheckout() {
   const thisBin = fileURLToPath(import.meta.url);
   const context = resolveFrameworkBinaryContext({ cwd: process.cwd(), thisBin });
-  if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return;
+  const currentBinaryContext = resolveFrameworkBinaryContext({
+    cwd: path.dirname(thisBin),
+    thisBin,
+  });
+  if (
+    !context.inFrameworkCheckout ||
+    context.isRepoLocalBinary ||
+    context.isRepoLocalRuntime ||
+    currentBinaryContext.isRepoLocalRuntime
+  )
+    return;
 
   const normalizedThis = path.resolve(thisBin);
   const normalizedRepo = path.resolve(context.checkout.repoBin);
@@ -101,7 +112,21 @@ function handoffToRepoLocalBinary(context) {
   return true;
 }
 
-function maybeHandoffToRepoLocalBinary() {
+async function repoLocalRuntimeReady(repoBin) {
+  if (!repoBin) return false;
+  const agentplaneRoot = path.resolve(path.dirname(repoBin), "..");
+  if (!(await distExists(agentplaneRoot))) return false;
+  return missingRepoRuntimeDependencies(agentplaneRoot).length === 0;
+}
+
+function resolveCurrentBinaryFrameworkContext(thisBin) {
+  return resolveFrameworkBinaryContext({
+    cwd: path.dirname(thisBin),
+    thisBin,
+  });
+}
+
+async function maybeHandoffToRepoLocalBinary() {
   if (shouldUseGlobalBinaryInFramework() || isRepoLocalHandoffInvocation()) return false;
 
   const context = resolveFrameworkBinaryContext({
@@ -110,6 +135,37 @@ function maybeHandoffToRepoLocalBinary() {
   });
   if (!context.inFrameworkCheckout || context.isRepoLocalBinary) return false;
 
+  if (!(await repoLocalRuntimeReady(context.checkout?.repoBin ?? ""))) {
+    const currentBinaryContext = resolveCurrentBinaryFrameworkContext(context.thisBin);
+    const canStayOnCurrentRepoLocalBinary =
+      currentBinaryContext.inFrameworkCheckout &&
+      currentBinaryContext.isRepoLocalRuntime &&
+      currentBinaryContext.checkout?.repoRoot !== context.checkout?.repoRoot;
+    if (canStayOnCurrentRepoLocalBinary) {
+      process.stderr.write(
+        "warning: target framework checkout repo-local runtime is not bootstrapped; " +
+          `staying on current repo-local binary: ${context.thisBin}\n` +
+          `unbootstrapped checkout binary: ${context.checkout?.repoBin ?? "<missing>"}\n` +
+          `fix target checkout with: ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n`,
+      );
+      return false;
+    }
+
+    const canStayOnCurrentInstalledBinary =
+      !currentBinaryContext.inFrameworkCheckout &&
+      !currentBinaryContext.isRepoLocalBinary &&
+      !currentBinaryContext.isRepoLocalRuntime;
+    if (canStayOnCurrentInstalledBinary) {
+      process.stderr.write(
+        "warning: target framework checkout repo-local runtime is not bootstrapped; " +
+          `staying on current installed binary: ${context.thisBin}\n` +
+          `unbootstrapped checkout binary: ${context.checkout?.repoBin ?? "<missing>"}\n` +
+          `fix target checkout with: ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n`,
+      );
+      return false;
+    }
+  }
+
   return handoffToRepoLocalBinary(context);
 }
 
@@ -122,6 +178,42 @@ function isHooksRunCommitMsgInvocation(argv) {
   return false;
 }
 
+function renderStalePolicyWarning(reason) {
+  if (reason === "task_artifact_mutation") {
+    return "warning: allowing task-artifact lifecycle command to run with a stale repo build inside the framework checkout.\n";
+  }
+  return "warning: allowing read-only diagnostic command to run with a stale repo build inside the framework checkout.\n";
+}
+
+function missingRepoRuntimeDependencies(agentplaneRoot) {
+  const requireFromAgentplane = createRequire(path.join(agentplaneRoot, "package.json"));
+  let packageJson = null;
+  try {
+    packageJson = requireFromAgentplane("./package.json");
+  } catch {
+    return [];
+  }
+  const declaredDeps = {};
+  if (packageJson?.dependencies && typeof packageJson.dependencies === "object") {
+    Object.assign(declaredDeps, packageJson.dependencies);
+  }
+  if (packageJson?.optionalDependencies && typeof packageJson.optionalDependencies === "object") {
+    Object.assign(declaredDeps, packageJson.optionalDependencies);
+  }
+  if (!("@agentplaneorg/core" in declaredDeps)) {
+    return [];
+  }
+  const requiredSpecifiers = ["@agentplaneorg/core"];
+  return requiredSpecifiers.filter((specifier) => {
+    try {
+      requireFromAgentplane.resolve(specifier);
+      return false;
+    } catch {
+      return true;
+    }
+  });
+}
+
 async function assertDistUpToDate() {
   const here = path.dirname(fileURLToPath(import.meta.url));
   const agentplaneRoot = path.resolve(here, "..");
@@ -144,6 +236,24 @@ async function assertDistUpToDate() {
     return false;
   }
 
+  const missingDeps = missingRepoRuntimeDependencies(agentplaneRoot);
+  if (missingDeps.length > 0) {
+    process.stderr.write(
+      "error: repo-local runtime dependencies are missing for this framework checkout.\n" +
+        "This worktree is not bootstrapped yet.\n" +
+        "Missing module resolution:\n" +
+        missingDeps.map((specifier) => `  ${specifier}\n`).join("") +
+        "Fix:\n" +
+        `  ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n` +
+        "Manual fallback:\n" +
+        FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS.map((command) => `  ${command}\n`).join("") +
+        "Supported global override when you intentionally want the installed binary:\n" +
+        `  ${FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE}\n`,
+    );
+    process.exitCode = 2;
+    return false;
+  }
+
   const repoRoot = path.resolve(agentplaneRoot, "..", "..");
   const coreRoot = path.join(repoRoot, "packages", "core");
   const checks = [
@@ -193,7 +303,7 @@ async function assertDistUpToDate() {
         .filter(Boolean)
         .join(" ");
       process.stderr.write(
-        "warning: allowing read-only diagnostic command to run with a stale repo build inside the framework checkout.\n" +
+        renderStalePolicyWarning(commandPolicy.reason) +
           `command: ${commandText || "<unknown>"}\n` +
           `detected: ${staleReasons.join(", ")}\n` +
           "rebuild recommended:\n" +
@@ -224,7 +334,7 @@ const runtimeContext = resolveFrameworkBinaryContext({
 });
 primeRuntimeEnv(runtimeContext);
 
-if (!maybeHandoffToRepoLocalBinary()) {
+if (!(await maybeHandoffToRepoLocalBinary())) {
   await maybeWarnGlobalBinaryInRepoCheckout();
   const ok = isHooksRunCommitMsgInvocation(process.argv) ? true : await assertDistUpToDate();
   if (ok) await import("../dist/cli.js");

package/bin/runtime-watch.js

@@ -23,6 +23,7 @@ export function isRuntimeRelevantWatchedFile(filePath) {
   if (!inSourceTree) return true;
   if (normalized.includes("/__snapshots__/")) return false;
   const baseName = path.posix.basename(normalized);
+  if (baseName.startsWith(".")) return false;
   return !/\.(?:test)\.[cm]?[jt]sx?$/u.test(baseName);
 }
 

package/bin/stale-dist-policy.d.ts

@@ -1,6 +1,6 @@
 export type StaleDistPolicy = {
   mode: "warn_and_run" | "strict";
-  reason: "read_only_diagnostic" | "default";
+  reason: "read_only_diagnostic" | "task_artifact_mutation" | "default";
 };
 
 export function classifyStaleDistPolicy(argv?: string[]): StaleDistPolicy;

package/bin/stale-dist-policy.js

@@ -38,6 +38,20 @@ function isPreflightCommand(args) {
   return args[0] === "preflight";
 }
 
+function isPostMergeHookCommand(args) {
+  return args[0] === "hooks" && args[1] === "run" && args[2] === "post-merge";
+}
+
+function isTaskArtifactMutationCommand(args) {
+  if (args[0] === "verify") return true;
+  if (args[0] === "finish") return true;
+  if (args[0] !== "task") return false;
+  if (args[1] === "doc" && args[2] === "set") return true;
+  if (args[1] === "plan" && ["set", "approve", "reject"].includes(args[2] ?? "")) return true;
+  if (args[1] === "start-ready") return true;
+  return args[1] === "verify" && ["ok", "rework"].includes(args[2] ?? "");
+}
+
 export function classifyStaleDistPolicy(argv = process.argv) {
   const args = normalizeArgs(argv);
   if (
@@ -48,9 +62,13 @@ export function classifyStaleDistPolicy(argv = process.argv) {
     isConfigInspectionCommand(args) ||
     isTaskInspectionCommand(args) ||
     isReadyInspectionCommand(args) ||
-    isPreflightCommand(args)
+    isPreflightCommand(args) ||
+    isPostMergeHookCommand(args)
   ) {
     return { mode: "warn_and_run", reason: "read_only_diagnostic" };
   }
+  if (isTaskArtifactMutationCommand(args)) {
+    return { mode: "warn_and_run", reason: "task_artifact_mutation" };
+  }
   return { mode: "strict", reason: "default" };
 }