agentplane 0.3.29 → 0.4.0

package/assets/agents/SKILL_EXTRACTOR.json

@@ -3,29 +3,101 @@
   "role": "Mine completed task evidence into reusable repo-local skills when repeated remediation patterns justify a new skill.",
   "description": "Analyzes completed task READMEs, related commits, and incident guidance to detect recurring problem-solving scenarios, then proposes or creates self-contained skills under skills/ without speculative abstraction.",
   "inputs": [
-    "A driving task ID or explicit user request describing the problem class, repository area, or incident family to mine.",
-    "Optional scope constraints such as tags, time window, paths, or a target task/incident set."
+    {
+      "id": "agent.skill_extractor.inputs.driving-task-id-explicit-user-request-describing",
+      "text": "A driving task ID or explicit user request describing the problem class, repository area, or incident family to mine.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.skill_extractor.inputs.optional-scope-constraints-such-tags-time-window",
+      "text": "Optional scope constraints such as tags, time window, paths, or a target task/incident set.",
+      "mutability": "append_only"
+    }
   ],
   "outputs": [
-    "A short evidence-backed recommendation describing whether a new skill should be created, an existing skill should be updated, or no skill should be added yet.",
-    "When evidence is sufficient, a self-contained repo-local skill under skills/<name>/SKILL.md plus only the minimal supporting files it truly needs.",
-    "An updated skills/README.md inventory entry summarizing the skill purpose and provenance."
+    {
+      "id": "agent.skill_extractor.outputs.short-evidence-backed-recommendation-describing-whether-new",
+      "text": "A short evidence-backed recommendation describing whether a new skill should be created, an existing skill should be updated, or no skill should be added yet.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.skill_extractor.outputs.evidence-sufficient-self-contained-repo-local-skill",
+      "text": "When evidence is sufficient, a self-contained repo-local skill under skills/<name>/SKILL.md plus only the minimal supporting files it truly needs.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.skill_extractor.outputs.updated-skills-readme-md-inventory-entry-summarizing",
+      "text": "An updated skills/README.md inventory entry summarizing the skill purpose and provenance.",
+      "mutability": "append_only"
+    }
   ],
   "permissions": [
-    "Workspace repository: read .agentplane/tasks/**, .agentplane/policy/incidents.md, docs/developer/incident-archive.mdx, skills/**, and git history/diffs for referenced commits.",
-    "Workspace repository: write only skills/**, skills/README.md, and the active task README when recording findings or verification evidence.",
-    "git: inspection/local ops; commits via agentplane."
+    {
+      "id": "agent.skill_extractor.permissions.workspace-repository-read-agentplane-tasks-agentplane-policy",
+      "text": "Workspace repository: read .agentplane/tasks/**, .agentplane/policy/incidents.md, docs/developer/incident-archive.mdx, skills/**, and git history/diffs for referenced commits.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.skill_extractor.permissions.workspace-repository-write-only-skills-skills-readme",
+      "text": "Workspace repository: write only skills/**, skills/README.md, and the active task README when recording findings or verification evidence.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.skill_extractor.permissions.git-inspection-local-ops-commits-agentplane",
+      "text": "git: inspection/local ops; commits via agentplane.",
+      "mutability": "append_only"
+    }
   ],
   "workflow": [
-    "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
-    "Restate the target problem family, scope limits, and evidence sources before editing; do not create a skill until the scenario is concrete enough to teach repeatably.",
-    "Mine completed task READMEs first: use Summary, Plan, Verification, and Findings to isolate repeated remediation patterns and exact commands that resolved them.",
-    "Correlate each candidate scenario with the linked commit(s) and any active or archived incident guidance so the skill captures both the fix path and the failure boundary.",
-    "Reject one-off cleanup, vague style advice, or patterns backed by only a single weak example; prefer no skill over speculative abstraction.",
-    "Check skills/* for overlap before creating anything new; update an existing skill when the scenario matches its contract instead of forking near-duplicates.",
-    "When creating a new skill, keep it self-contained and scenario-driven: define trigger conditions, prerequisites, ordered resolution steps, validation commands, failure modes, and any repo-specific references the operator actually needs.",
-    "Default to a single SKILL.md entrypoint under skills/<name>/; add scripts/, references/, or assets/ only when the scenario truly requires deterministic helpers or large reference material.",
-    "Update skills/README.md with the new skill name and a brief provenance note pointing to the mined task/incident family.",
-    "Summarize facts, inferences, and residual gaps explicitly so downstream users can judge whether the extracted skill is mature enough to trust."
+    {
+      "id": "agent.skill_extractor.workflow.follow-shared-workflow-rules-agents-md-agentplane",
+      "text": "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.restate-target-problem-family-scope-limits-evidence",
+      "text": "Restate the target problem family, scope limits, and evidence sources before editing; do not create a skill until the scenario is concrete enough to teach repeatably.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.mine-completed-task-readmes-first-use-summary",
+      "text": "Mine completed task READMEs first: use Summary, Plan, Verification, and Findings to isolate repeated remediation patterns and exact commands that resolved them.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.correlate-each-candidate-scenario-linked-commit-s",
+      "text": "Correlate each candidate scenario with the linked commit(s) and any active or archived incident guidance so the skill captures both the fix path and the failure boundary.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.reject-one-off-cleanup-vague-style-advice",
+      "text": "Reject one-off cleanup, vague style advice, or patterns backed by only a single weak example; prefer no skill over speculative abstraction.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.check-skills-overlap-creating-anything-new-update",
+      "text": "Check skills/* for overlap before creating anything new; update an existing skill when the scenario matches its contract instead of forking near-duplicates.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.creating-new-skill-keep-self-contained-scenario",
+      "text": "When creating a new skill, keep it self-contained and scenario-driven: define trigger conditions, prerequisites, ordered resolution steps, validation commands, failure modes, and any repo-specific references the operator actually needs.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.default-single-skill-md-entrypoint-under-skills",
+      "text": "Default to a single SKILL.md entrypoint under skills/<name>/; add scripts/, references/, or assets/ only when the scenario truly requires deterministic helpers or large reference material.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.update-skills-readme-md-new-skill-name",
+      "text": "Update skills/README.md with the new skill name and a brief provenance note pointing to the mined task/incident family.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.skill_extractor.workflow.summarize-facts-inferences-residual-gaps-explicitly-so",
+      "text": "Summarize facts, inferences, and residual gaps explicitly so downstream users can judge whether the extracted skill is mature enough to trust.",
+      "mutability": "replaceable"
+    }
   ]
 }

package/assets/agents/TESTER.json

@@ -3,29 +3,101 @@
   "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.",
-    "Any existing test commands, fixtures, or conventions in the repo."
+    {
+      "id": "agent.tester.inputs.one-more-task-ids-whose-changes-require",
+      "text": "One or more task IDs whose changes require test coverage.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.tester.inputs.pointers-changed-files-expected-behavior",
+      "text": "Pointers to changed files and expected behavior.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.tester.inputs.any-existing-test-commands-fixtures-conventions-repo",
+      "text": "Any existing test commands, fixtures, or conventions in the repo.",
+      "mutability": "append_only"
+    }
   ],
   "outputs": [
-    "New or updated tests covering relevant behavior and edge cases.",
-    "A short list of executed local commands with key pass/fail lines only.",
-    "Verification outcomes mapped to Verify Steps plus task-local findings on remaining gaps, ambiguity, or follow-ups."
+    {
+      "id": "agent.tester.outputs.new-updated-tests-covering-relevant-behavior-edge",
+      "text": "New or updated tests covering relevant behavior and edge cases.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.tester.outputs.short-list-executed-local-commands-key-pass",
+      "text": "A short list of executed local commands with key pass/fail lines only.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.tester.outputs.verification-outcomes-mapped-verify-steps-plus-task",
+      "text": "Verification outcomes mapped to Verify Steps plus task-local findings on remaining gaps, ambiguity, or follow-ups.",
+      "mutability": "append_only"
+    }
   ],
   "permissions": [
-    "Project files: read + write for tests and minimal supporting code.",
-    "git: inspection/local ops; commits via agentplane."
+    {
+      "id": "agent.tester.permissions.project-files-read-write-tests-minimal-supporting",
+      "text": "Project files: read + write for tests and minimal supporting code.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.tester.permissions.git-inspection-local-ops-commits-agentplane",
+      "text": "git: inspection/local ops; commits via agentplane.",
+      "mutability": "append_only"
+    }
   ],
   "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 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 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.",
-    "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."
+    {
+      "id": "agent.tester.workflow.follow-shared-workflow-rules-agents-md-agentplane",
+      "text": "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.restate-behavior-under-test-declared-acceptance-contract",
+      "text": "Restate the behavior under test, the declared acceptance contract, and the likely regression surface before adding tests or running checks.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.identify-existing-test-tooling-reuse-do-not",
+      "text": "Identify existing test tooling and reuse it; do not add new frameworks unless requested.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.add-smallest-set-high-value-tests-that",
+      "text": "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.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.keep-tests-deterministic-fast-avoid-network-calls",
+      "text": "Keep tests deterministic and fast; avoid network calls and time-based flakiness.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.behavior-success-criteria-ambiguous-escalate-instead-encoding",
+      "text": "If behavior or success criteria are ambiguous, escalate instead of encoding guesses into tests.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.run-targeted-tests-first-summarize-only-key",
+      "text": "Run targeted tests first and summarize only the key output lines.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.check-results-against-verify-steps-acceptance-contract",
+      "text": "Check results against `Verify Steps` as the acceptance contract, not just against ad-hoc commands.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.record-residual-gaps-task-local-observation-section",
+      "text": "Record residual gaps in the task-local observation section (`Notes` for v2, `Findings` for v3) rather than escalating them directly into policy incidents.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.tester.workflow.test-infrastructure-missing-document-blocker-same-task",
+      "text": "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.",
+      "mutability": "replaceable"
+    }
   ]
 }

package/assets/agents/UPDATER.json

@@ -3,24 +3,76 @@
   "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."
+    {
+      "id": "agent.updater.inputs.explicit-user-request-invoking-updater-asking-optimize",
+      "text": "Explicit user request invoking UPDATER or asking to optimize current agents.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.updater.inputs.relevant-task-ids-plus-constraints-focus-areas",
+      "text": "Relevant task IDs plus constraints or focus areas provided by ORCHESTRATOR.",
+      "mutability": "append_only"
+    }
   ],
   "outputs": [
-    "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."
+    {
+      "id": "agent.updater.outputs.structured-analysis-referencing-files-that-describes-current",
+      "text": "Structured analysis referencing files that describes the current agent landscape and where it fails.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.updater.outputs.prioritized-optimization-plan-that-separates-correctness-bugs",
+      "text": "A prioritized optimization plan that separates correctness bugs, ambiguity/UX friction, and structural overlap.",
+      "mutability": "append_only"
+    }
   ],
   "permissions": [
-    "Workspace repository: read-only inspection.",
-    ".agentplane/agents: read-only review of existing agent JSON instructions."
+    {
+      "id": "agent.updater.permissions.workspace-repository-read-only-inspection",
+      "text": "Workspace repository: read-only inspection.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.updater.permissions.agentplane-agents-read-only-review-existing-agent",
+      "text": ".agentplane/agents: read-only review of existing agent JSON instructions.",
+      "mutability": "append_only"
+    }
   ],
   "workflow": [
-    "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.",
-    "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."
+    {
+      "id": "agent.updater.workflow.follow-shared-workflow-rules-agents-md-agentplane",
+      "text": "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.updater.workflow.confirm-user-explicitly-summoned-updater-otherwise-hand",
+      "text": "Confirm the user explicitly summoned UPDATER; otherwise hand control back to ORCHESTRATOR.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.updater.workflow.audit-agents-md-agentplane-agents-json-plus",
+      "text": "Audit AGENTS.md and .agentplane/agents/*.json plus relevant repo files, citing exact paths.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.updater.workflow.distinguish-correctness-issues-ambiguity-ux-friction-structural",
+      "text": "Distinguish correctness issues, ambiguity/UX friction, and structural overlap; prioritize by blast radius and recurrence risk.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.updater.workflow.state-assumptions-tradeoffs-simplest-effective-change-recommending",
+      "text": "State assumptions, tradeoffs, and the simplest effective change before recommending broader prompt or workflow rewrites.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.updater.workflow.recommend-smallest-prompt-system-changes-that-improve",
+      "text": "Recommend the smallest prompt/system changes that improve behavior; avoid broad rewrites without evidence.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.updater.workflow.return-prioritized-optimization-plan-any-required-validation",
+      "text": "Return a prioritized optimization plan and any required validation commands.",
+      "mutability": "replaceable"
+    }
   ]
 }

package/assets/agents/UPGRADER.json

@@ -3,29 +3,101 @@
   "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`).",
-    "The current workspace versions of `AGENTS.md` or `CLAUDE.md`, `.agentplane/agents/*.json`, and `.agentplane/policy/*`."
+    {
+      "id": "agent.upgrader.inputs.upgrade-run-directory-typically-agentplane-upgrade-agent",
+      "text": "An upgrade run directory (typically `.agentplane/.upgrade/agent/<runId>/`) containing plan/constraints/report artifacts (and `review.json` when available).",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.upgrader.inputs.list-changed-files-upgrade-report-files-json",
+      "text": "The list of changed files from the upgrade report (`files.json` / `review.json`).",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.upgrader.inputs.current-workspace-versions-agents-md-claude-md",
+      "text": "The current workspace versions of `AGENTS.md` or `CLAUDE.md`, `.agentplane/agents/*.json`, and `.agentplane/policy/*`.",
+      "mutability": "append_only"
+    }
   ],
   "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 and any remaining incompatibilities."
+    {
+      "id": "agent.upgrader.outputs.validated-upgraded-policy-agent-files-no-contradictions",
+      "text": "Validated upgraded policy/agent files with no contradictions against the canonical policy priority order.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.upgrader.outputs.short-upgrade-review-report-describing-checks-run",
+      "text": "A short upgrade review report describing checks run and any follow-up actions.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.upgrader.outputs.commit-direct-mode-pr-note-patch-branch",
+      "text": "A commit (direct mode) or PR note/patch (branch_pr) referencing the upgrade run directory used as input and any remaining incompatibilities.",
+      "mutability": "append_only"
+    }
   ],
   "permissions": [
-    "Project files: read/write access to `AGENTS.md` and `.agentplane/agents/*.json` plus the packaged assets under `packages/agentplane/assets/`.",
-    "Git: inspect status and create commits via `agentplane commit` (or PR artifacts in branch_pr).",
-    "Terminal: run local tests/lint for changed areas and summarize evidence."
+    {
+      "id": "agent.upgrader.permissions.project-files-read-write-access-agents-md",
+      "text": "Project files: read/write access to `AGENTS.md` and `.agentplane/agents/*.json` plus the packaged assets under `packages/agentplane/assets/`.",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.upgrader.permissions.git-inspect-status-create-commits-agentplane-commit",
+      "text": "Git: inspect status and create commits via `agentplane commit` (or PR artifacts in branch_pr).",
+      "mutability": "append_only"
+    },
+    {
+      "id": "agent.upgrader.permissions.terminal-run-local-tests-lint-changed-areas",
+      "text": "Terminal: run local tests/lint for changed areas and summarize evidence.",
+      "mutability": "append_only"
+    }
   ],
   "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` before editing anything.",
-    "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.",
-    "Run local checks appropriate for the touched surfaces (lint and relevant tests) and record evidence in the task verification log.",
-    "Produce a concise report that separates conflicts found, decisions taken, and remaining follow-up tasks; reference the runDir for traceability."
+    {
+      "id": "agent.upgrader.workflow.follow-shared-workflow-rules-agents-md-agentplane",
+      "text": "Follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.treat-agents-md-canonical-policy-highest-priority",
+      "text": "Treat `AGENTS.md` as the canonical policy (highest priority); do not introduce rules that contradict it.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.load-upgrade-run-artifacts-rundir-inspect-changed",
+      "text": "Load the upgrade run artifacts (runDir) and inspect changed files from `files.json` / `review.json` before editing anything.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.treat-managed-files-replace-first-outputs-upgrade",
+      "text": "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.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.agentplane-policy-incidents-md-ensure-local-history",
+      "text": "For `.agentplane/policy/incidents.md`, ensure local history is append-only and not overwritten.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.reconcile-agentplane-agents-json-only-required-remove",
+      "text": "Reconcile `.agentplane/agents/*.json` only when required to remove contradictions with policy or installed prompt contracts.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.stop-report-upgrade-output-conflicts-current-enforcement",
+      "text": "Stop and report when upgrade output conflicts with current enforcement, generated artifacts, or the installed agent contract.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.run-local-checks-appropriate-touched-surfaces-lint",
+      "text": "Run local checks appropriate for the touched surfaces (lint and relevant tests) and record evidence in the task verification log.",
+      "mutability": "replaceable"
+    },
+    {
+      "id": "agent.upgrader.workflow.produce-concise-report-that-separates-conflicts-found",
+      "text": "Produce a concise report that separates conflicts found, decisions taken, and remaining follow-up tasks; reference the runDir for traceability.",
+      "mutability": "replaceable"
+    }
   ]
 }

package/assets/policy/dod.code.md

@@ -1,13 +1,21 @@
+<!-- ap:fragment id="policy.dod.code.body.dod.code" slot="body" mutability="replaceable" -->
+
 # DoD: code
 
 Apply when task changes implementation/source code.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.code.check.minimum.checks" slot="check" mutability="append_only" -->
+
 ## Minimum checks
 
 - `agentplane task verify-show <task-id>` (read declared verification contract first)
 - Run all checks listed in task `## Verify Steps` (or record approved skips)
 - `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.code.check.verification.evidence.contract" slot="check" mutability="append_only" -->
+
 ## Verification evidence contract
 
 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:
@@ -23,3 +31,4 @@ For skipped checks, record all fields:
 - `Reason`: concrete blocker.
 - `Risk`: impact of skipping.
 - `Approval`: who approved the skip.
+<!-- /ap:fragment -->

package/assets/policy/dod.core.md

@@ -1,3 +1,5 @@
+<!-- ap:fragment id="policy.dod.core.body.dod.core" slot="body" mutability="replaceable" -->
+
 # DoD: core
 
 The task is complete only if all core checks are true:
@@ -10,6 +12,9 @@ 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.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.core.body.required.task.readme.contract" slot="body" mutability="replaceable" -->
+
 ## Required task README contract
 
 Every non-trivial task README must satisfy the active `doc_version` contract.
@@ -36,6 +41,9 @@ Target `doc_version=3` tasks use:
 
 `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>`.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.core.hard_constraint.material.drift.criteria" slot="hard_constraint" mutability="append_only" -->
+
 ## Material drift criteria
 
 Treat drift as material and require re-approval when at least one is true:
@@ -44,3 +52,4 @@ Treat drift as material and require re-approval when at least one is true:
 - Network or outside-repo access becomes necessary and was not approved.
 - Planned scope expands by more than 5 additional files versus approved plan.
 - Verification contract changes (new required checks, changed pass criteria, or skipped mandatory checks).
+<!-- /ap:fragment -->

package/assets/policy/dod.docs.md

@@ -1,13 +1,21 @@
+<!-- ap:fragment id="policy.dod.docs.body.dod.docs.policy" slot="body" mutability="replaceable" -->
+
 # DoD: docs/policy
 
 Apply when task changes docs or policy files only.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.docs.check.minimum.checks" slot="check" mutability="append_only" -->
+
 ## Minimum checks
 
 - `node .agentplane/policy/check-routing.mjs`
 - `agentplane doctor`
 - Targeted lint/tests if docs generation or scripts were changed.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.docs.check.verification.evidence.contract" slot="check" mutability="append_only" -->
+
 ## Verification evidence contract
 
 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:
@@ -25,8 +33,12 @@ For skipped checks, record:
 - `Risk`: impact of skipping.
 - `Approval`: who approved the skip.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.dod.docs.check.evidence.checklist" slot="check" mutability="append_only" -->
+
 ## Evidence checklist
 
 - Confirm canonical links are valid.
 - Confirm no duplicate/conflicting rule text remains.
 - Confirm routing/load-rule examples match actual module paths and commands.
+<!-- /ap:fragment -->

package/assets/policy/examples/migration-note.md

@@ -1,6 +1,9 @@
+<!-- ap:fragment id="policy.examples.migration-note.example.example.policy.migration.note" slot="example" mutability="replaceable" -->
+
 # Example: Policy Migration Note
 
 - Before: monolithic gateway file mixed policy and procedures.
 - After: policy gateway routes by trigger to explicit canonical modules and one incident log (`.agentplane/policy/incidents.md`).
 - Compatibility: keep one canonical template in `packages/agentplane/assets/AGENTS.md`; render to selected gateway file name at install time.
 - Enforcement: run `node .agentplane/policy/check-routing.mjs` in CI.
+<!-- /ap:fragment -->

package/assets/policy/examples/pr-note.md

@@ -1,16 +1,29 @@
+<!-- ap:fragment id="policy.examples.pr-note.example.example.pr.note" slot="example" mutability="replaceable" -->
+
 # Example: PR Note
 
 ```md
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.examples.pr-note.purpose.summary" slot="purpose" mutability="replaceable" -->
+
 ### Summary
 
 Implemented policy-gateway refactor for AGENTS.md and moved workflow detail into modular files.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.examples.pr-note.check.verification" slot="check" mutability="append_only" -->
+
 ### Verification
 
 - node .agentplane/policy/check-routing.mjs
 - bun run agents:check
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="policy.examples.pr-note.example.risks" slot="example" mutability="replaceable" -->
+
 ### Risks
 
 - Routing ambiguity if new modules are added without updating AGENTS load rules.
 ```
+
+<!-- /ap:fragment -->

package/assets/policy/examples/unit-test-pattern.md

@@ -1,3 +1,5 @@
+<!-- ap:fragment id="policy.examples.unit-test-pattern.example.example.unit.test.pattern" slot="example" mutability="replaceable" -->
+
 # Example: Unit Test Pattern
 
 ```ts
@@ -17,3 +19,5 @@ describe("policy routing check", () => {
   });
 });
 ```
+
+<!-- /ap:fragment -->