agentplane 0.3.9 → 0.3.11

package/assets/AGENTS.md

@@ -17,7 +17,7 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
 - CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. In this repository, `workflow_mode=branch_pr`, so the normal guarded route starts from `agentplane work start ... --worktree` on the base branch; treat `direct` as an explicit alternative only when intentionally selected.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. The guarded route is determined by `workflow_mode` in `.agentplane/config.json`; use `agentplane quickstart` as the canonical summary of the active path before mutating. In `branch_pr`, start from `agentplane work start ... --worktree`; in `direct`, stay in the current checkout and use the task lifecycle route.
 
 ---
 
@@ -84,6 +84,8 @@ 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 incidents advise <task-id>
+agentplane incidents collect <task-id> --check
 agentplane doctor
 node .agentplane/policy/check-routing.mjs
 ```
@@ -207,5 +209,5 @@ Detailed DoD rules are in `.agentplane/policy/dod.core.md`, `.agentplane/policy/
 ## CHANGE CONTROL
 
 - Follow incident-log, immutability, and policy-budget rules in `.agentplane/policy/governance.md`.
-- Record situational incident rules only in `.agentplane/policy/incidents.md`; do not load/read that file during normal startup unless the task directly touches it or recovery/incident handling requires it.
+- Record situational incident rules only in `.agentplane/policy/incidents.md`; use targeted lookup/promotion (`task start-ready`, `incidents advise`, `incidents collect`, `finish`) instead of bulk-loading it during normal startup.
 - Keep `AGENTS.md` as a gateway; move detailed procedures to canonical modules.

package/assets/agents/CODER.json

@@ -24,7 +24,7 @@
     "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.",
     "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); do not promote directly into policy incidents.",
+    "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.",
     "Coordinate handoffs to TESTER/REVIEWER/DOCS only when those roles already have explicit executable tasks; otherwise keep findings and verification in the same task.",
     "Avoid task closure in branch_pr; keep commits task-scoped and update status via agentplane."

package/assets/policy/dod.core.md

@@ -34,7 +34,7 @@ Target `doc_version=3` tasks use:
 - `Rollback Plan`
 - `Findings`
 
-`Findings` is task-local. Policy incidents are curated separately in `.agentplane/policy/incidents.md`.
+`Findings` is task-local. Reusable external incident advice stays there first, then is promoted into `.agentplane/policy/incidents.md` through `finish` or `agentplane incidents collect <task-id>`.
 
 ## Material drift criteria
 

package/assets/policy/governance.md

@@ -5,13 +5,15 @@
 - `.agentplane/policy/incidents.md` is the single incident registry.
 - 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 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,79 +1,21 @@
 # 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`.
-- `rule` MUST be concrete and testable (`MUST` / `MUST NOT`).
-- `state` values: `open`, `stabilized`, `promoted`.
-
-## Entry template
-
-- id: `INC-YYYYMMDD-NN`
-- date: `YYYY-MM-DD`
-- scope: `<affected scope>`
-- failure: `<observed failure mode>`
-- rule: `<new or refined MUST/MUST NOT>`
-- evidence: `<task ids / logs / links>`
-- enforcement: `<CI|test|lint|script|manual>`
-- state: `<open|stabilized|promoted>`
-
-<!-- example:start
-- id: INC-20260305-01
-- date: 2026-03-05
-- scope: commit-msg hook in repo development mode
-- failure: commit-msg rejected valid commits because stale-dist check blocked src_dirty/git_head_changed
-- rule: commit-msg MUST validate subject semantics and MUST NOT block on stale dist freshness checks
-- evidence: task 20260305-HOOKS-FIX, commit 9fe55c73
-- enforcement: test + hook script
-- state: open
-example:end -->
-
-## Entries
-
-- 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
+- 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

package/assets/policy/workflow.branch_pr.md

@@ -29,6 +29,8 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 - MUST NOT perform mutating actions before explicit user approval.
 - 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 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,14 +38,16 @@ 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 process/policy-related and strong enough for repo-wide memory, promote it explicitly into `.agentplane/policy/incidents.md`.
+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
 
 - MUST NOT perform mutating actions before explicit user approval.
 - 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.
 - In direct mode, `finish` auto-creates the deterministic close commit by default; use `--no-close-commit` only for explicit manual handling.
+- `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 {
@@ -122,6 +123,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 +181,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 +248,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" +

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,16 @@ function isPreflightCommand(args) {
   return args[0] === "preflight";
 }
 
+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 (
@@ -52,5 +62,8 @@ export function classifyStaleDistPolicy(argv = process.argv) {
   ) {
     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" };
 }