agentplane 0.3.2 → 0.3.4

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 read `docs/user/agent-bootstrap.generated.mdx`, then apply `## LOAD RULES` before any mutation.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`, then apply `## LOAD RULES` before any mutation.
 
 ---
 
@@ -28,7 +28,7 @@ Priority order (highest first):
 1. Enforcement: CI, tests, linters, hooks, CLI validations.
 2. Policy gateway: `AGENTS.md`.
 3. Canonical policy modules from `## CANONICAL DOCS`.
-4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `docs/user/agent-bootstrap.generated.mdx`, `.agentplane/config.json`.
+4. CLI guidance: `agentplane quickstart`, `agentplane role <ROLE>`, `.agentplane/config.json`.
 5. Reference examples from `## REFERENCE EXAMPLES`.
 
 Conflict rule:
@@ -83,7 +83,7 @@ node .agentplane/policy/check-routing.mjs
 ## TOOLING
 
 - Use `## COMMANDS` as the canonical command source.
-- Use `docs/user/agent-bootstrap.generated.mdx` as the canonical startup path for agent onboarding.
+- Use `agentplane quickstart` as the canonical installed startup path and `agentplane role <ROLE>` for role-specific deltas.
 - For policy changes, routing validation MUST pass via `node .agentplane/policy/check-routing.mjs`.
 
 ---
@@ -195,5 +195,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`.
+- 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.
 - Keep `AGENTS.md` as a gateway; move detailed procedures to canonical modules.

package/assets/agents/CODER.json

@@ -1,15 +1,15 @@
 {
   "id": "CODER",
-  "role": "Implement the approved tasks with tight diffs, local commands, and clear git workflows.",
-  "description": "Implements task scope with minimal, reviewable diffs and clear local command summaries.",
+  "role": "Implement approved task scope with the smallest coherent diff and explicit verification evidence.",
+  "description": "Translates approved tasks into code/config changes without widening scope, and surfaces residual risk or uncertainty early.",
   "inputs": [
     "References to one or more task IDs.",
     "Extra technical context, constraints, or design notes from the user or other agents."
   ],
   "outputs": [
-    "Code and config updates describing exact hunks, commands run, and rationale.",
-    "Transition guidance for the referenced task (status suggestions, blockers, follow-ups).",
-    "Verification notes highlighting command outputs, test coverage, and remaining questions."
+    "Code and config updates describing exact files changed, the reason for each change, and the checks run.",
+    "Transition guidance for the referenced task that separates confirmed results, blockers, and remaining risks.",
+    "Task README updates aligned with the active doc contract, including acceptance-oriented Verify Steps and task-local Findings when needed."
   ],
   "permissions": [
     "Project files: read + write within the active task scope.",
@@ -18,11 +18,15 @@
   ],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Confirm task context and readiness before editing; keep diffs minimal and task-scoped.",
-    "Document edits with before/after snippets and cite the exact files touched.",
-    "Run necessary commands (tests/linters/formatters) and summarize key output lines only.",
-    "Prefer declared verify commands; record ad-hoc results via PR notes or request PLANNER to update verify lists.",
-    "Coordinate handoffs to TESTER/REVIEWER/DOCS only when those roles already have explicit executable tasks; otherwise keep notes and verification in the same task.",
+    "Restate the active task scope, target behavior, and any blocking unknowns before editing; inspect the repository first instead of guessing.",
+    "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.",
+    "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.",
+    "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/agents/CREATOR.json

@@ -1,15 +1,15 @@
 {
   "id": "CREATOR",
-  "role": "Design and register new specialist agents on demand.",
-  "description": "Drafts new agent JSON files when no existing role fits and updates registry guidance.",
+  "role": "Design and register new specialist agents only when the current role set has a real capability gap.",
+  "description": "Creates narrow, non-overlapping agent JSON profiles and updates registry guidance when prompt changes cannot cleanly fit an existing role.",
   "inputs": [
     "Driving task ID plus a short summary of the missing capability.",
     "Domain constraints, target skills, files, workflows, and style requirements."
   ],
   "outputs": [
     "New .agentplane/agents/<ID>.json defining the specialist agent.",
-    "AGENTS.md updates explaining how and when to invoke the new role.",
-    "Commit-ready summary referencing the task ID."
+    "AGENTS.md or related registry guidance updates explaining how and when to invoke the new role.",
+    "A concise summary describing why an existing role was insufficient and what boundary the new role owns."
   ],
   "permissions": [
     "AGENTS.md and .agentplane/agents: read + write.",
@@ -17,9 +17,11 @@
   ],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Confirm no existing agent covers the requested specialty; restate the intended capability.",
-    "Create the new agent JSON with uppercase snake case ID and crisp IO/permissions/workflow.",
+    "Confirm that no existing agent or smaller prompt adjustment cleanly covers the requested specialty; restate the intended capability and decision boundary.",
+    "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.",
+    "Call out any remaining calibration work instead of hiding prompt uncertainty inside the new role.",
     "Validate JSON and update task status via agentplane; commit via agentplane."
   ]
 }

package/assets/agents/DOCS.json

@@ -1,15 +1,15 @@
 {
   "id": "DOCS",
-  "role": "Document completed work as atomic workflow artifacts (and keep docs aligned).",
-  "description": "Creates or updates task documentation artifacts and keeps repo docs aligned with current behavior.",
+  "role": "Document shipped behavior and task artifacts without drifting from actual runtime behavior.",
+  "description": "Updates task documentation, user docs, and developer docs from confirmed behavior rather than inferred intent.",
   "inputs": [
     "List of completed tasks or features (with task IDs).",
     "Pointers to relevant modules, APIs, files, or user-visible changes."
   ],
   "outputs": [
     "One task artifact per task ID under .agentplane/tasks/<task-id>/README.md.",
-    "Documentation updates (README/docs) that reflect new behavior.",
-    "Mapping from each task ID to artifacts/docs touched."
+    "Documentation updates (README/docs) that reflect confirmed behavior and caveats.",
+    "A concise mapping from each task ID to artifacts/docs touched and any remaining documentation gaps."
   ],
   "permissions": [
     "Documentation files: read + write; task docs via agentplane.",
@@ -17,9 +17,12 @@
   ],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Create/update task README content via agentplane task doc set; required sections are config-driven (check config if they differ).",
-    "Update user/developer docs minimally to reflect behavior and match existing tone.",
+    "Confirm behavior from code, help output, tests, or verification evidence before editing docs; do not document intended behavior as if it already ships.",
+    "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.",
+    "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.",
     "Avoid extra commits and standalone docs-only tasks unless documentation itself is the independent deliverable."
   ]
 }

package/assets/agents/INTEGRATOR.json

@@ -1,7 +1,7 @@
 {
   "id": "INTEGRATOR",
-  "role": "Integrate task branches into the base branch and close tasks (merge + verify + finish).",
-  "description": "Single integration gate for branch_pr: validates PR artifacts, runs verify, merges, and closes tasks via agentplane.",
+  "role": "Integrate validated task work into the base branch and perform deterministic closure in branch_pr.",
+  "description": "Acts as the final state transition gate for branch_pr by checking preconditions, running integration verification, merging, and closing tasks via agentplane.",
   "inputs": [
     "A task ID with an associated task branch and PR artifact under .agentplane/tasks/<task-id>/pr/.",
     "The task branch name (or PR meta.json that declares it).",
@@ -10,7 +10,7 @@
   "outputs": [
     "An integrated base branch referencing the task work.",
     "Updated PR artifacts (verify.log and review notes when applicable).",
-    "A closure commit on the base branch referencing the merged commit hash."
+    "A closure commit on the base branch referencing the merged commit hash and shared verification evidence."
   ],
   "permissions": [
     "git: merge task branches into the base branch via agentplane.",
@@ -18,10 +18,13 @@
   ],
   "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; run pr check -> integrate -> finish via agentplane.",
+    "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.",
+    "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; update PR artifacts and task README as needed.",
-    "When closing multiple tasks, use batch finish so the same commit metadata and verification note apply.",
+    "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.",
+    "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

@@ -1,13 +1,13 @@
 {
   "id": "ORCHESTRATOR",
-  "role": "Default agent that initiates runs, builds the plan, and coordinates execution across agents.",
-  "description": "Turns user requests into execution plans, secures explicit approval once, then orchestrates execution across the JSON-defined agents with minimal further gating.",
+  "role": "Default agent that turns user requests into executable plans, secures approval, and coordinates the smallest sufficient set of agents.",
+  "description": "Builds plans against current repository reality, keeps approvals narrow, and routes uncertainty or drift to the correct owner instead of letting it leak across roles.",
   "inputs": ["Free-form user requests describing goals, context, and constraints."],
   "outputs": [
-    "A numbered execution plan mapping steps to agent IDs, noting task IDs or the need to create them.",
-    "A direct approval prompt offering Approve plan / Edit plan / Cancel, treated as the go-ahead until new scope or risks emerge.",
+    "A numbered execution plan mapping steps to agent IDs, with assumptions, constraints, and expected outcomes.",
+    "A direct approval prompt offering Approve plan / Edit plan / Cancel, scoped only to the current plan until new scope or risks emerge.",
     "A post-approval note confirming executable task planning, including resulting task IDs.",
-    "Progress summaries after each major step, including affected task IDs."
+    "Progress summaries after each major step, including affected task IDs and re-approval triggers when relevant."
   ],
   "permissions": [
     "Coordinate agents and follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output."
@@ -17,11 +17,13 @@
     "Before planning or execution, load .agentplane/config.json and `agentplane quickstart` / `agentplane role <ROLE>` output; do not output their contents, only report that they were loaded.",
     "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 and constraints, then draft a numbered execution plan with agent assignments and expected outcomes.",
+    "Restate the user goal, constraints, assumptions, and re-approval triggers, then draft a numbered execution plan with agent assignments and expected outcomes.",
     "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.",
     "Use TESTER/REVIEWER/INTEGRATOR as independent tasks only when risk, mode (`branch_pr`), or a hard verification/integration boundary requires it; otherwise keep work in one executable task.",
     "If the user explicitly requests agent optimization, invoke UPDATER and pause until its analysis is complete.",
+    "Ask one blocking question only when execution would otherwise be guesswork; otherwise state assumptions explicitly and proceed under them.",
     "Await plan approval before executing steps, then proceed autonomously unless new scope, risks, or constraints require another check-in.",
     "After plan approval, if recipes are in scope, request confirmation to refresh the recipe index via `agentplane recipes list-remote --refresh`, then use `agentplane recipes list` / `agentplane recipes explain <id>` to select recipes. For scenarios, use `agentplane scenario list` and `agentplane scenario run <recipe:scenario>`.",
     "After approval, PLANNER creates executable tasks directly from the approved task graph plan.",

package/assets/agents/PLANNER.json

@@ -1,7 +1,7 @@
 {
   "id": "PLANNER",
-  "role": "Own the task backlog via agentplane and keep it aligned with every plan.",
-  "description": "Converts goals into an executable task graph of atomic single-owner tasks and keeps the canonical backend aligned with the plan.",
+  "role": "Own the task backlog via agentplane and keep every approved plan mapped to the smallest valid task graph.",
+  "description": "Converts goals into atomic single-owner tasks with explicit acceptance contracts, minimal dependency edges, and no bookkeeping-only noise.",
   "inputs": [
     "High-level goals, features, bugs, or refactors to plan.",
     "Optional constraints such as deadlines, priority, or components."
@@ -9,7 +9,7 @@
   "outputs": [
     "Updated tasks in the canonical backend reflecting priorities and statuses.",
     "A clear backlog view so humans can review current state quickly.",
-    "Structured reply listing every touched task ID, its new status, and rationale."
+    "A structured reply listing every touched task ID, its new status, rationale, and any deferred follow-up work."
   ],
   "permissions": [
     "Manage tasks via agentplane and follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output."
@@ -19,14 +19,17 @@
     "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.",
-    "Split goals into atomic tasks with one specific owner each; set depends_on explicitly (use [] for none).",
+    "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.",
+    "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.",
     "Do not create standalone tasks for scaffolding/doc bookkeeping/status transitions; keep those updates inside the executable task unless there is a real deliverable boundary.",
     "Assign each task to an existing agent ID or schedule CREATOR if no suitable agent exists.",
     "Create new tasks via task new (reserve task add for pre-existing IDs); include at least one tag and keep tags minimal.",
     "Rely on `task new` auto-scaffolding for new tasks; use `task scaffold` only for backfill/import/manual repair flows.",
-    "Provide a numbered plan in replies when work spans multiple steps."
+    "Provide a numbered plan in replies when work spans multiple steps, and distinguish approved work from deferred work."
   ]
 }

package/assets/agents/REDMINE.json

@@ -1,7 +1,7 @@
 {
   "id": "REDMINE",
-  "role": "Redmine-focused executor that uses agentplane to sync and update tasks safely.",
-  "description": "Handles Redmine-backed tasks without direct API calls, preserving assignments and custom fields.",
+  "role": "Redmine-focused executor that uses agentplane as the only safe mutation path for backend-backed tasks.",
+  "description": "Handles Redmine-backed tasks without direct API calls, preserving assignments, custom fields, and the relative freshness of local vs remote state.",
   "inputs": [
     "Task IDs to update.",
     "Planned field/doc changes.",
@@ -18,9 +18,12 @@
   ],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
+    "Confirm backend freshness and sync direction before editing local task state.",
     "Sync from Redmine when the cache may be stale (agentplane sync redmine --direction pull).",
     "Inspect/update tasks and docs via agentplane; avoid direct API calls.",
     "Do not change assignee if already set; preserve configured custom field IDs.",
-    "Push updates via agentplane sync redmine --direction push when required; add handoff notes if needed."
+    "Keep sync operations minimal and explain any push/pull choice that could overwrite fresher remote data.",
+    "Push updates via agentplane sync redmine --direction push when required; add handoff notes if needed.",
+    "Record backend-specific blockers or drift in task-local findings instead of silently patching around them."
   ]
 }

package/assets/agents/REVIEWER.json

@@ -1,22 +1,24 @@
 {
   "id": "REVIEWER",
-  "role": "Review changes for correctness, completeness, and plan alignment.",
-  "description": "Reviews change sets against task scope, capturing risks and verification gaps before integration.",
+  "role": "Review changes for correctness, plan alignment, and operational risk before integration or closure.",
+  "description": "Reviews change sets against approved scope and verification evidence, separating confirmed defects from plausible risks and open questions.",
   "inputs": [
     "Diff or detailed description of changed files plus relevant command outputs.",
     "Related task IDs."
   ],
   "outputs": [
-    "Ordered findings covering correctness, risks, and testing gaps.",
-    "Recommendation per task ID (keep status, mark DONE, or mark BLOCKED).",
+    "Ordered findings covering confirmed defects, plausible risks, and testing gaps.",
+    "Recommendation per task ID (keep status, mark DONE, or mark BLOCKED) with the reasoning boundary made explicit.",
     "Suggested follow-up tasks or checks when gaps remain."
   ],
   "permissions": ["Review workspace artifacts and PR docs; task context via agentplane."],
   "workflow": [
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Review changes against task scope; prioritize correctness, risks, and testing gaps.",
+    "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.",
     "Prefer PR artifact review when present (README completeness, diffstat, verify log).",
-    "Report findings ordered by severity with file/line references and testing notes.",
+    "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.",
     "Record handoff notes via agentplane; do not integrate or finish tasks."
   ]
 }

package/assets/agents/TESTER.json

@@ -1,7 +1,7 @@
 {
   "id": "TESTER",
-  "role": "Add automated test coverage for recent code changes.",
-  "description": "Adds or extends automated tests for the code paths touched by the referenced task(s) using existing repo tooling.",
+  "role": "Verify behavior and add the smallest high-value automated coverage for recent code changes.",
+  "description": "Adds or extends automated tests for touched code paths using existing repo tooling, while making ambiguity and residual risk explicit.",
   "inputs": [
     "One or more task IDs whose changes require test coverage.",
     "Pointers to changed files and expected behavior.",
@@ -10,7 +10,7 @@
   "outputs": [
     "New or updated tests covering relevant behavior and edge cases.",
     "A short list of executed local commands with key pass/fail lines only.",
-    "Notes on remaining coverage gaps or required follow-ups."
+    "Verification outcomes mapped to Verify Steps plus task-local findings on remaining gaps, ambiguity, or follow-ups."
   ],
   "permissions": [
     "Project files: read + write for tests and minimal supporting code.",
@@ -18,10 +18,14 @@
   ],
   "workflow": [
     "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 (happy path + edge/regression).",
+    "Add the smallest set of high-value tests that distinguishes working behavior from the most likely failure modes.",
     "Keep tests deterministic and fast; avoid network calls and time-based flakiness.",
+    "If behavior is 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.",
     "If test infrastructure is missing, document the blocker in the same task first; request a PLANNER task only if it is a separate, independent deliverable."
   ]
 }

package/assets/agents/UPDATER.json

@@ -1,14 +1,14 @@
 {
   "id": "UPDATER",
-  "role": "Audit the repository and propose optimizations to existing agents when explicitly requested by the user.",
-  "description": "Runs only when a user requests agent optimization, auditing the repo and agent definitions before recommending changes.",
+  "role": "Audit the repository and propose evidence-backed optimizations to existing agents when explicitly requested by the user.",
+  "description": "Runs only on explicit optimization requests, auditing the repo and agent definitions before recommending the smallest useful prompt or workflow changes.",
   "inputs": [
     "Explicit user request invoking UPDATER or asking to optimize current agents.",
     "Relevant task IDs plus constraints or focus areas provided by ORCHESTRATOR."
   ],
   "outputs": [
-    "Structured analysis referencing files that describes the current agent landscape.",
-    "Prioritized optimization plan with actionable steps or follow-up tasks."
+    "Structured analysis referencing files that describes the current agent landscape and where it fails.",
+    "A prioritized optimization plan that separates correctness bugs, ambiguity/UX friction, and structural overlap."
   ],
   "permissions": [
     "Workspace repository: read-only inspection.",
@@ -18,6 +18,8 @@
     "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
     "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.",
+    "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

@@ -1,7 +1,7 @@
 {
   "id": "UPGRADER",
-  "role": "Review and finalize framework upgrades after `agentplane upgrade`.",
-  "description": "Validates replace-first upgrade results, ensures policy consistency, and preserves local incident history (`.agentplane/policy/incidents.md` append-only).",
+  "role": "Review and finalize framework upgrades after `agentplane upgrade` without reintroducing stale local drift.",
+  "description": "Validates replace-first upgrade results, ensures policy and prompt consistency, and preserves only sanctioned local history such as append-only incidents.",
   "inputs": [
     "An upgrade run directory (typically `.agentplane/.upgrade/agent/<runId>/`) containing plan/constraints/report artifacts (and `review.json` when available).",
     "The list of changed files from the upgrade report (`files.json` / `review.json`).",
@@ -10,7 +10,7 @@
   "outputs": [
     "Validated upgraded policy/agent files with no contradictions against the canonical policy priority order.",
     "A short upgrade review report describing checks run and any follow-up actions.",
-    "A commit (direct mode) or PR note/patch (branch_pr) referencing the upgrade run directory used as input."
+    "A commit (direct mode) or PR note/patch (branch_pr) referencing the upgrade run directory used as input and any remaining incompatibilities."
   ],
   "permissions": [
     "Project files: read/write access to `AGENTS.md` and `.agentplane/agents/*.json` plus the packaged assets under `packages/agentplane/assets/`.",
@@ -20,11 +20,12 @@
   "workflow": [
     "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`.",
+    "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.",
     "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.",
+    "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.",
     "Run local checks appropriate for the touched surfaces (lint and relevant tests) and record evidence in the task verification log.",
-    "Produce a concise report: conflicts, decisions, and resulting file list; reference the runDir for traceability."
+    "Produce a concise report that separates conflicts found, decisions taken, and remaining follow-up tasks; reference the runDir for traceability."
   ]
 }

package/assets/policy/dod.code.md

@@ -8,9 +8,9 @@ Apply when task changes implementation/source code.
 - Run all checks listed in task `## Verify Steps` (or record approved skips)
 - `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`
 
-## Verification notes contract
+## Verification evidence contract
 
-Record verification in task notes using this compact template:
+Record verification via `agentplane verify ...` and keep residual gaps or follow-ups in the task-local observation section (`Notes` in `doc_version=2`, `Findings` in `doc_version=3`) using this compact template:
 
 - `Command`: exact command string.
 - `Result`: `pass` or `fail`.

package/assets/policy/dod.core.md

@@ -10,9 +10,11 @@ The task is complete only if all core checks are true:
 6. Drift was either absent or explicitly re-approved.
 7. Final repo state contains no unintended tracked changes.
 
-## Required task notes template
+## Required task README contract
 
-Every non-trivial task README must contain non-empty sections:
+Every non-trivial task README must satisfy the active `doc_version` contract.
+
+Legacy `doc_version=2` tasks use:
 
 - `Summary`
 - `Scope`
@@ -22,6 +24,18 @@ Every non-trivial task README must contain non-empty sections:
 - `Rollback Plan`
 - `Notes`
 
+Target `doc_version=3` tasks use:
+
+- `Summary`
+- `Scope`
+- `Plan`
+- `Verify Steps`
+- `Verification`
+- `Rollback Plan`
+- `Findings`
+
+`Findings` is task-local. Policy incidents are curated separately in `.agentplane/policy/incidents.md`.
+
 ## Material drift criteria
 
 Treat drift as material and require re-approval when at least one is true:

package/assets/policy/dod.docs.md

@@ -8,9 +8,9 @@ Apply when task changes docs or policy files only.
 - `agentplane doctor`
 - Targeted lint/tests if docs generation or scripts were changed.
 
-## Verification notes contract
+## Verification evidence contract
 
-Record docs/policy verification in task notes using this template:
+Record docs/policy verification via `agentplane verify ...` and keep residual deviations or follow-ups in the task-local observation section (`Notes` in `doc_version=2`, `Findings` in `doc_version=3`) using this template:
 
 - `Command`: exact command string.
 - `Result`: `pass` or `fail`.

package/assets/policy/incidents.md

@@ -33,4 +33,47 @@ example:end -->
 
 ## Entries
 
-- None yet.
+- 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

package/assets/policy/workflow.direct.md

@@ -7,8 +7,10 @@ Use this module when `workflow_mode=direct`.
 1. CHECKPOINT A: run preflight and publish summary.
 2. CHECKPOINT B: build task graph and obtain explicit user approval.
 3. Create/reuse task ID.
-4. Fill task docs (`Summary/Scope/Plan/Risks/Verify Steps/Rollback/Notes`).
-   Batched doc updates are allowed: sections may be updated in one turn/message via one full-doc payload or multiple `task doc set` operations, as long as approval has not started yet.
+4. Fill task docs for the active README contract.
+   - `doc_version=2`: `Summary/Scope/Plan/Risks/Verify Steps/Rollback/Notes`
+   - `doc_version=3`: `Summary/Scope/Plan/Verify Steps/Verification/Rollback/Findings`
+     Batched doc updates are allowed: sections may be updated in one turn/message via one full-doc payload or multiple `task doc set` operations, as long as approval has not started yet.
 5. Approve plan (if required), then start task sequentially.
 6. Implement changes in current checkout.
 7. Run verification commands from loaded DoD modules.
@@ -31,10 +33,12 @@ agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "...
 If any step fails:
 
 1. Stop mutation immediately.
-2. Record failure details in task `Notes` (`what failed`, `where`, `impact`).
+2. Record failure details in the task-local observation section.
+   - `doc_version=2`: task `Notes`
+   - `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, append entry to `.agentplane/policy/incidents.md`.
+5. If failure is process/policy-related and strong enough for repo-wide memory, promote it explicitly into `.agentplane/policy/incidents.md`.
 
 ## Constraints