agentplane 0.2.26 → 0.3.1

package/assets/agents/UPGRADER.json

@@ -1,15 +1,15 @@
 {
   "id": "UPGRADER",
-  "role": "Resolve semantic conflicts after `agentplane upgrade` (prompt/policy merge).",
-  "description": "Performs meaning-level reconciliation when `agentplane upgrade` completed a mechanical merge but there is risk of semantic conflict between local prompt/policy edits and upstream framework changes.",
+  "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).",
   "inputs": [
     "An upgrade run directory (typically `.agentplane/.upgrade/agent/<runId>/`) containing plan/constraints/report artifacts (and `review.json` when available).",
-    "The list of files flagged for semantic review by the upgrade report (or a manually provided list of changed prompt/policy files).",
-    "The current workspace versions of `AGENTS.md` and `.agentplane/agents/*.json` (and the packaged defaults under `packages/agentplane/assets/`)."
+    "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/*`."
   ],
   "outputs": [
-    "A reconciled `AGENTS.md` and `.agentplane/agents/*.json` with no contradictions against the canonical policy priority order.",
-    "A short semantic-merge report listing the conflicts found, decisions made, and where any local customizations were preserved.",
+    "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."
   ],
   "permissions": [
@@ -20,9 +20,10 @@
   "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 extract the list of files that need semantic review.",
-    "Reconcile `AGENTS.md` changes by preserving local customizations inside the Local Overrides block (`<!-- AGENTPLANE:LOCAL-START/END -->`) where feasible.",
-    "Reconcile `.agentplane/agents/*.json` by removing contradictions with `AGENTS.md` and minimizing unrelated churn; keep non-conflicting local improvements.",
+    "Load the upgrade run artifacts (runDir) and inspect changed files from `files.json` / `review.json`.",
+    "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.",
     "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."
   ]

package/assets/framework.manifest.json

@@ -1,13 +1,6 @@
 {
   "schema_version": 1,
   "files": [
-    {
-      "path": "AGENTS.md",
-      "source_path": "AGENTS.md",
-      "type": "markdown",
-      "merge_strategy": "agents_policy_markdown",
-      "required": true
-    },
     {
       "path": ".agentplane/agents/CODER.json",
       "source_path": "agents/CODER.json",
@@ -84,6 +77,118 @@
       "type": "json",
       "merge_strategy": "agent_json_3way",
       "required": true
+    },
+    {
+      "path": ".agentplane/policy/check-routing.mjs",
+      "source_path": "policy/check-routing.mjs",
+      "type": "text",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/dod.code.md",
+      "source_path": "policy/dod.code.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/dod.core.md",
+      "source_path": "policy/dod.core.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/dod.docs.md",
+      "source_path": "policy/dod.docs.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/examples/migration-note.md",
+      "source_path": "policy/examples/migration-note.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/examples/pr-note.md",
+      "source_path": "policy/examples/pr-note.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/examples/unit-test-pattern.md",
+      "source_path": "policy/examples/unit-test-pattern.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/governance.md",
+      "source_path": "policy/governance.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/incidents.md",
+      "source_path": "policy/incidents.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/security.must.md",
+      "source_path": "policy/security.must.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/workflow.branch_pr.md",
+      "source_path": "policy/workflow.branch_pr.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/workflow.direct.md",
+      "source_path": "policy/workflow.direct.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/workflow.md",
+      "source_path": "policy/workflow.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/workflow.release.md",
+      "source_path": "policy/workflow.release.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": ".agentplane/policy/workflow.upgrade.md",
+      "source_path": "policy/workflow.upgrade.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
+    },
+    {
+      "path": "AGENTS.md",
+      "source_path": "AGENTS.md",
+      "type": "markdown",
+      "merge_strategy": "agents_policy_markdown",
+      "required": true
     }
   ]
 }

package/assets/policy/check-routing.mjs

@@ -0,0 +1,180 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function collectPaths(text, re) {
+  const out = [];
+  for (const match of text.matchAll(re)) {
+    const value = String(match[1] ?? "").trim();
+    if (value) out.push(value);
+  }
+  return out;
+}
+
+function isRepoRelative(p) {
+  if (!p) return false;
+  if (path.isAbsolute(p)) return false;
+  if (p.startsWith("../") || p.includes("/../")) return false;
+  return true;
+}
+
+function readLines(filePath) {
+  return fs.readFileSync(filePath, "utf8").split(/\r?\n/).length;
+}
+
+function assertFilesExist(repoRoot, paths, label, errors) {
+  for (const relPath of paths) {
+    if (!isRepoRelative(relPath)) {
+      errors.push(`${label} path is not repo-relative: ${relPath}`);
+      continue;
+    }
+    const absPath = path.join(repoRoot, relPath);
+    if (!fs.existsSync(absPath)) {
+      errors.push(`${label} path does not exist: ${relPath}`);
+    }
+  }
+}
+
+function listFilesRecursive(dirPath, relPrefix = "") {
+  if (!fs.existsSync(dirPath)) return [];
+  const entries = fs.readdirSync(dirPath).toSorted((a, b) => a.localeCompare(b));
+  const out = [];
+  for (const entry of entries) {
+    if (entry.startsWith(".")) continue;
+    const abs = path.join(dirPath, entry);
+    const rel = relPrefix ? `${relPrefix}/${entry}` : entry;
+    const st = fs.statSync(abs);
+    if (st.isDirectory()) {
+      out.push(...listFilesRecursive(abs, rel));
+      continue;
+    }
+    if (st.isFile()) out.push(rel);
+  }
+  return out;
+}
+
+function main() {
+  const repoRoot = process.cwd();
+  const codexPath = path.join(repoRoot, "AGENTS.md");
+  const claudePath = path.join(repoRoot, "CLAUDE.md");
+  const hasCodex = fs.existsSync(codexPath);
+  const hasClaude = fs.existsSync(claudePath);
+  let gatewayPath = codexPath;
+  if (!hasCodex && hasClaude) gatewayPath = claudePath;
+  const gatewayFileName = path.basename(gatewayPath);
+  if (!hasCodex && !hasClaude) {
+    throw new Error(
+      "Policy routing check failed:\n- Missing policy gateway file: AGENTS.md or CLAUDE.md",
+    );
+  }
+  const text = fs.readFileSync(gatewayPath, "utf8");
+  const errors = [];
+
+  const lineCount = text.split(/\r?\n/).length;
+  if (lineCount > 250) {
+    errors.push(`${gatewayFileName} exceeds policy budget (<=250 lines): got ${lineCount}`);
+  }
+
+  const requiredHeadings = [
+    "# PURPOSE",
+    "## PROJECT",
+    "## SOURCES OF TRUTH",
+    "## COMMANDS",
+    "## TOOLING",
+    "## LOAD RULES",
+    "## MUST / MUST NOT",
+    "## CORE DOD",
+    "## SIZE BUDGET",
+    "## CANONICAL DOCS",
+    "## REFERENCE EXAMPLES",
+  ];
+  for (const heading of requiredHeadings) {
+    if (!text.includes(heading)) {
+      errors.push(`Missing required heading: ${heading}`);
+    }
+  }
+
+  if (!text.includes("MUST NOT load unrelated policy modules")) {
+    errors.push("Missing strict routing guard: MUST NOT load unrelated policy modules");
+  }
+  if (!text.includes("MUST NOT use wildcard policy paths")) {
+    errors.push("Missing strict routing guard: MUST NOT use wildcard policy paths");
+  }
+
+  if (/->\s*LOAD\s+`/i.test(text) || /-\s*IF\s+.*->/i.test(text)) {
+    errors.push("Legacy IF/LOAD routing syntax is forbidden; use @path imports in LOAD RULES");
+  }
+
+  const importPaths = collectPaths(text, /`@([^`\s]+)`/g);
+  const docPaths = collectPaths(text, /-\s*DOC\s+`([^`]+)`/g);
+  const examplePaths = collectPaths(text, /-\s*EXAMPLE\s+`([^`]+)`/g);
+  const wildcardPolicyPaths = [...importPaths, ...docPaths, ...examplePaths].filter((p) =>
+    p.includes("*"),
+  );
+  for (const wildcard of wildcardPolicyPaths) {
+    errors.push(`Wildcard policy path is not allowed: ${wildcard}`);
+  }
+
+  if (importPaths.length < 6) {
+    errors.push(`Expected at least 6 @import paths, got ${importPaths.length}`);
+  }
+  if (docPaths.length < 6) {
+    errors.push(`Expected at least 6 DOC paths, got ${docPaths.length}`);
+  }
+  if (examplePaths.length < 3) {
+    errors.push(`Expected at least 3 EXAMPLE paths, got ${examplePaths.length}`);
+  }
+
+  const incidentsPath = ".agentplane/policy/incidents.md";
+  if (!docPaths.includes(incidentsPath)) {
+    errors.push(`Missing canonical DOC path: ${incidentsPath}`);
+  }
+  if (!importPaths.includes(incidentsPath)) {
+    errors.push(`Missing @import rule for incidents path: ${incidentsPath}`);
+  }
+
+  assertFilesExist(repoRoot, [...new Set(importPaths)], "IMPORT", errors);
+  assertFilesExist(repoRoot, [...new Set(docPaths)], "DOC", errors);
+  assertFilesExist(repoRoot, [...new Set(examplePaths)], "EXAMPLE", errors);
+
+  const policyDir = path.join(repoRoot, ".agentplane", "policy");
+  const policyFiles = listFilesRecursive(policyDir);
+  const markdownModules = policyFiles.filter((relPath) => relPath.endsWith(".md"));
+
+  for (const relPath of markdownModules) {
+    const abs = path.join(policyDir, relPath);
+    const moduleLines = readLines(abs);
+    if (moduleLines > 100) {
+      errors.push(
+        `Policy module exceeds budget (<=100 lines): .agentplane/policy/${relPath} (${moduleLines})`,
+      );
+    }
+  }
+
+  const importedMarkdown = [...new Set(importPaths.filter((p) => p.endsWith(".md")))];
+  let worstCaseLoadedLines = 0;
+  for (const relPath of importedMarkdown) {
+    const abs = path.join(repoRoot, relPath);
+    if (!fs.existsSync(abs)) continue;
+    worstCaseLoadedLines += readLines(abs);
+  }
+  if (worstCaseLoadedLines > 600) {
+    errors.push(
+      `Worst-case loaded policy graph exceeds budget (<=600 lines): ${worstCaseLoadedLines}`,
+    );
+  }
+
+  const incidentFiles = policyFiles.filter((relPath) => /incident/i.test(path.basename(relPath)));
+  if (incidentFiles.length !== 1 || incidentFiles[0] !== "incidents.md") {
+    errors.push(
+      `Policy incidents must use a single file (.agentplane/policy/incidents.md). Found: ${incidentFiles.join(", ") || "none"}`,
+    );
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Policy routing check failed:\n- ${errors.join("\n- ")}`);
+  }
+
+  process.stdout.write("policy routing OK\n");
+}
+
+main();

package/assets/policy/dod.code.md

@@ -0,0 +1,25 @@
+# DoD: code
+
+Apply when task changes implementation/source code.
+
+## 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 "..."`
+
+## Verification notes contract
+
+Record verification in task notes using this compact template:
+
+- `Command`: exact command string.
+- `Result`: `pass` or `fail`.
+- `Evidence`: short output summary (key lines only).
+- `Scope`: what paths/behavior the check covers.
+
+For skipped checks, record all fields:
+
+- `Skipped`: command not executed.
+- `Reason`: concrete blocker.
+- `Risk`: impact of skipping.
+- `Approval`: who approved the skip.

package/assets/policy/dod.core.md

@@ -0,0 +1,32 @@
+# DoD: core
+
+The task is complete only if all core checks are true:
+
+1. Preflight summary was produced.
+2. Plan + task graph was presented and approved.
+3. Executable task traceability exists for all repo mutations.
+4. Required task documentation sections are populated.
+5. Verification steps are executed and results recorded.
+6. Drift was either absent or explicitly re-approved.
+7. Final repo state contains no unintended tracked changes.
+
+## Required task notes template
+
+Every non-trivial task README must contain non-empty sections:
+
+- `Summary`
+- `Scope`
+- `Plan`
+- `Risks`
+- `Verify Steps`
+- `Rollback Plan`
+- `Notes`
+
+## Material drift criteria
+
+Treat drift as material and require re-approval when at least one is true:
+
+- Files outside approved scope are modified.
+- 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).

package/assets/policy/dod.docs.md

@@ -0,0 +1,32 @@
+# DoD: docs/policy
+
+Apply when task changes docs or policy files only.
+
+## Minimum checks
+
+- `node .agentplane/policy/check-routing.mjs`
+- `agentplane doctor`
+- Targeted lint/tests if docs generation or scripts were changed.
+
+## Verification notes contract
+
+Record docs/policy verification in task notes using this template:
+
+- `Command`: exact command string.
+- `Result`: `pass` or `fail`.
+- `Evidence`: short output summary.
+- `Scope`: changed docs/policy paths covered by the check.
+- `Links`: updated canonical docs/examples referenced by the change.
+
+For skipped checks, record:
+
+- `Skipped`: command not executed.
+- `Reason`: concrete blocker.
+- `Risk`: impact of skipping.
+- `Approval`: who approved the skip.
+
+## 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.

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

@@ -0,0 +1,6 @@
+# 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.

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

@@ -0,0 +1,16 @@
+# Example: PR Note
+
+```md
+### Summary
+
+Implemented policy-gateway refactor for AGENTS.md and moved workflow detail into modular files.
+
+### Verification
+
+- node .agentplane/policy/check-routing.mjs
+- bun run agents:check
+
+### Risks
+
+- Routing ambiguity if new modules are added without updating AGENTS load rules.
+```

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

@@ -0,0 +1,19 @@
+# Example: Unit Test Pattern
+
+```ts
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { describe, expect, it } from "vitest";
+
+const execFileAsync = promisify(execFile);
+
+describe("policy routing check", () => {
+  it("passes for current repository policy files", async () => {
+    await expect(
+      execFileAsync("node", ["scripts/check-policy-routing.mjs"], {
+        cwd: process.cwd(),
+      }),
+    ).resolves.toBeDefined();
+  });
+});
+```

package/assets/policy/governance.md

@@ -0,0 +1,37 @@
+# Policy Governance
+
+## Incident source of truth
+
+- `.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/`.
+
+## Stabilization criteria
+
+Use `stabilized` only when one of these is true:
+
+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.
+
+Promotion from `incidents.md` into canonical policy modules is allowed only when:
+
+1. The incident is `stabilized`.
+2. Enforcement is defined (`CI`, `test`, `lint`, or policy check script).
+3. Policy gateway load rules are updated if routing behavior changes.
+
+## Canonical module immutability
+
+- Canonical modules are immutable by default during feature delivery tasks.
+- Canonical modules MAY be changed only in a dedicated policy task with explicit user approval.
+- Every canonical policy edit MUST include `node .agentplane/policy/check-routing.mjs` in verification evidence.
+
+## Policy budget
+
+- The policy gateway file (`AGENTS.md` or `CLAUDE.md`) MUST remain compact (target <= 250 lines).
+- Detailed procedures MUST be placed in canonical modules listed in the gateway file.
+- If a policy change needs >20 new lines in the gateway file, move detail to a module and keep only routing + hard gate in gateway.
+
+## Rule quality
+
+- MUST rules should be enforceable by tooling where possible.
+- Non-enforceable guidance should be marked as SHOULD and kept out of hard-gate sections.

package/assets/policy/incidents.md

@@ -0,0 +1,36 @@
+# 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
+
+- None yet.

package/assets/policy/security.must.md

@@ -0,0 +1,7 @@
+# Security MUST Rules
+
+- MUST NOT commit secrets, credentials, or private keys.
+- MUST NOT access outside-repo files without explicit user approval.
+- MUST NOT perform network actions when approval is required and not granted.
+- MUST NOT modify auth/crypto/security-critical codepaths without explicit scope approval.
+- MUST report security-sensitive drift immediately and stop before mutation.

package/assets/policy/workflow.branch_pr.md

@@ -0,0 +1,34 @@
+# Workflow: branch_pr
+
+Use this module when `workflow_mode=branch_pr`.
+
+## Required sequence
+
+1. CHECKPOINT A: plan/approve on base checkout.
+2. Start work with dedicated task branch + worktree.
+3. Keep single-writer discipline per task worktree.
+4. Publish/update PR artifacts.
+5. Verify on task branch.
+6. CHECKPOINT B: integrate on base branch by INTEGRATOR.
+7. CHECKPOINT C: finish task(s) on base with verification evidence.
+
+## Command contract
+
+```bash
+agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree
+agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
+agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
+agentplane pr update <task-id>
+agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
+agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify
+agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+```
+
+## 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).
+- 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

@@ -0,0 +1,46 @@
+# Workflow: direct
+
+Use this module when `workflow_mode=direct`.
+
+## Required sequence
+
+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.
+5. Approve plan (if required), then start task sequentially.
+6. Implement changes in current checkout.
+7. Run verification commands from loaded DoD modules.
+8. Record verification result (`agentplane verify ...`) for the task scope.
+9. CHECKPOINT C: finish task with traceable evidence.
+
+## Command contract
+
+```bash
+agentplane task new --title "..." --description "..." --priority med --owner <ROLE> --tag <tag>
+agentplane task plan set <task-id> --text "..." --updated-by <ROLE>
+agentplane task plan approve <task-id> --by ORCHESTRATOR
+agentplane task start-ready <task-id> --author <ROLE> --body "Start: ..."
+agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
+agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev> --close-commit
+```
+
+## ERROR RECOVERY
+
+If any step fails:
+
+1. Stop mutation immediately.
+2. Record failure details in task `Notes` (`what failed`, `where`, `impact`).
+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`.
+
+## 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).
+- MUST stop and request re-approval on material drift.
+- Do not use worktrees in direct mode.
+- Do not perform `branch_pr`-only operations.

package/assets/policy/workflow.md

@@ -0,0 +1,9 @@
+# Workflow Policy Index
+
+This document is an index for workflow procedures.
+Use `AGENTS.md` load rules to decide which module to read.
+
+- Direct workflow: `.agentplane/policy/workflow.direct.md`
+- Branch PR workflow: `.agentplane/policy/workflow.branch_pr.md`
+- Release workflow: `.agentplane/policy/workflow.release.md`
+- Upgrade workflow: `.agentplane/policy/workflow.upgrade.md`