agentplane 0.3.9 → 0.3.10

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,6 +5,9 @@
 - `.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 explicit `incident-candidate` blocks marked `IncidentExternal: true`; repository-fixable defects stay task-local unless curated manually.
+- 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
 

package/assets/policy/incidents.md

@@ -6,7 +6,9 @@ This is the single file for incident-derived and situational policy rules.
 
 - 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
@@ -14,29 +16,26 @@ This is the single file for incident-derived and situational policy rules.
 - 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>`
 
-<!-- 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
+  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
@@ -45,7 +44,10 @@ example:end -->
 - 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
@@ -54,7 +56,10 @@ example:end -->
 - 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
@@ -63,7 +68,10 @@ example:end -->
 - 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
@@ -72,7 +80,10 @@ example:end -->
 - 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

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 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`.
 - 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 `incident-candidate` block in `Findings` and let `agentplane finish` or `agentplane incidents collect <task-id>` promote it.
 
 ## 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 external `incident-candidate` findings and appends valid entries to `.agentplane/policy/incidents.md`.
 - MUST stop and request re-approval on material drift.
 - Do not use worktrees in direct mode.
 - Do not perform `branch_pr`-only operations.