agentplane 0.4.0 → 0.4.2

package/assets/agents/UPGRADER.json

@@ -2,102 +2,26 @@
   "id": "UPGRADER",
   "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": [
-    {
-      "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": [
-    {
-      "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": [
-    {
-      "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": [
-    {
-      "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"
-    }
-  ]
+  "inputs": {
+    "upgrade.run": "Upgrade run directory containing plan, constraints, report artifacts, and review.json when available.",
+    "changed.files": "Changed files from files.json or review.json in the upgrade report.",
+    "workspace.prompts": "Current workspace AGENTS.md or CLAUDE.md, .agentplane/agents/*.json, and .agentplane/policy/* state."
+  },
+  "outputs": {
+    "validated.upgrade": "Validated upgraded policy and agent files with no contradictions against the canonical priority order.",
+    "review.report": "Short upgrade review report describing decisions, checks run, and follow-up actions.",
+    "commit.or.pr.note": "A commit or PR note referencing the upgrade run directory and remaining incompatibilities."
+  },
+  "permissions": {
+    "managed.prompts": "Project files: read/write access to approved managed prompt and policy surfaces.",
+    "git.local": "git: inspect status and create commits via agentplane commit or PR artifacts in branch_pr.",
+    "terminal.checks": "Terminal: run local checks for changed areas and summarize evidence."
+  },
+  "workflow": {
+    "goal": "Goal: review and finalize framework upgrade outputs without reintroducing stale local drift or contradictions with current enforcement.",
+    "success.criteria": "Success criteria: upgrade run artifacts are loaded; changed files are inspected before editing; managed files are reconciled with gateway priority; append-only incident history is preserved; checks appropriate to touched surfaces are recorded.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; use `agentplane` for lifecycle and commits; treat managed files as replace-first upgrade outputs; avoid speculative prompt rewrites beyond the upgrade contract.",
+    "stop.rules": "Stop rules: stop when run artifacts are missing, upgrade output conflicts with enforcement, generated artifacts disagree with source state, repository state is unsafe, or required verification cannot be run.",
+    "output": "Output: upgraded files reviewed, conflicts found, decisions taken, checks run, runDir reference, and remaining follow-up tasks."
+  }
 }

package/assets/framework.manifest.json

@@ -22,6 +22,13 @@
       "merge_strategy": "agent_json_3way",
       "required": true
     },
+    {
+      "path": ".agentplane/agents/EVALUATOR.json",
+      "source_path": "agents/EVALUATOR.json",
+      "type": "json",
+      "merge_strategy": "agent_json_3way",
+      "required": true
+    },
     {
       "path": ".agentplane/agents/INTEGRATOR.json",
       "source_path": "agents/INTEGRATOR.json",

package/assets/policy/incidents.md

@@ -6,3 +6,10 @@
 - id: INC-20260430-01 | date: 2026-04-30 | scope: Make release hygiene pass by reconciling generated project agent and policy mirrors with canonical framework prompt assets after the fragmented prompt migration. Scope is limited to sync output and any minimal follow-up needed for agents:check. | tags: agents, policy, release | match: agents, policy, release, make, hygiene, pass, reconciling, generated, project, agent, and, mirrors, with, canonical, framework, prompt | failure: bun run agents:check initially failed because target .agentplane agent and policy mirrors lagged the canonical fragmented prompt assets. | advice: Ran bun run agents:sync and verified the generated mirror output. | rule: Analogous Make release hygiene pass by reconciling generated project agent and policy mirrors with canonical framework prompt assets after the fragmented prompt migration. Scope is limited to sync output and any minimal follow-up needed for agents:check. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604300724-ZTGZYT; commit ac0e1ff930ed | enforcement: manual | fixability: external | state: open
 - id: INC-20260429-01 | date: 2026-04-29 | scope: recipe manifest/project overlay parsing for prompt module declarations and mutation sets. | tags: code, prompt-assembly, recipes, schemas | match: code, prompt-assembly, recipes, schemas, recipe, manifest, project, overlay, parsing, for, prompt, module, declarations, and, mutation, sets | failure: Checks passed: bun test packages/agentplane/src/commands/recipes/impl/project-installed-recipes.test.ts packages/agentplane/src/commands/recipes/impl/resolver.test.ts packages/agentplane/src/commands/recipes.transaction.test.ts packages/agentplane/src/runtime/prompt-modules/mutations.test.ts; bun run typecheck; git diff --check; bun run framework:dev:bootstrap; agentplane doctor; extra bun test packages/recipes/src/index.test.ts packages/recipes/src/overlay.test.ts; targeted eslint on touched files. | advice: No prompt graph application was added in this step; that remains for the dependent recipe application task. | rule: Analogous recipe manifest/project overlay parsing for prompt module declarations and mutation sets. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604291531-Z6XH6Q; commit c69211301720 | enforcement: manual | fixability: external | state: open
 - id: INC-20260429-02 | date: 2026-04-29 | scope: apply active recipe prompt module mutations during project overlay/prompt graph refresh. | tags: code, prompt-assembly, recipes, workflow | match: code, prompt-assembly, recipes, workflow, apply, active, recipe, prompt, module, mutations, during, project, overlay, graph, refresh, compiled | failure: Checks passed: agentplane doctor; bun run framework:dev:bootstrap; bun run typecheck; bun test packages/agentplane/src/commands/recipes/impl/overlay-project.test.ts packages/agentplane/src/commands/recipes.transaction.test.ts packages/agentplane/src/commands/recipes.catalog-install.test.ts packages/agentplane/src/runtime/prompt-modules/compiler.test.ts; git diff --check; extra bun test packages/agentplane/src/commands/recipes/impl/project-installed-recipes.test.ts; targeted eslint on touched files. | advice: Runner/runtime consumption and drift diagnostics remain scoped to the following diagnostic task. | rule: Analogous apply active recipe prompt module mutations during project overlay/prompt graph refresh. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604291531-N0H28A; commit ac327dd2b0c1 | enforcement: manual | fixability: external | state: open
+- id: INC-20260430-02 | date: 2026-04-30 | scope: Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. | tags: code, docs-ia, tooling | match: code, docs-ia, tooling, add, automated, docs, information, architecture, guard, that, checks, index, mdx, and, website, sidebars | failure: docs:site:typecheck emits untracked website/\*.js files in this repo; they were removed before docs:site:build. Build then passed. | advice: Task implementation commit is 7a95d2ca with generated task artifact refresh c5166206. | rule: Analogous Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604301955-HKY8NW; commit 00031a6f3ac9 | enforcement: manual | fixability: external | state: open
+- id: INC-20260430-03 | date: 2026-04-30 | scope: Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. | tags: code, docs-ia, tooling | match: code, docs-ia, tooling, add, automated, docs, information, architecture, guard, that, checks, index, mdx, and, website, sidebars | failure: Remote Docs CI failed before this fix on docs/developer/project-layout.mdx referencing packages/agentplane/dist/. That path is generated output, not a required tracked source path. | advice: Follow-up fix commit is 4ab6c548 with artifact refresh 5685436b. | rule: Analogous Add an automated docs information-architecture guard that checks docs/index.mdx and website/sidebars.ts alignment, catches orphan current docs, and fails on markdown references to repository paths that no longer exist. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604301955-HKY8NW; commit 00031a6f3ac9 | enforcement: manual | fixability: external | state: open
+- id: INC-20260501-01 | date: 2026-05-01 | scope: Run final integrated verification for the refactor wave and record any residual gaps. | tags: code | match: code, run, final, integrated, verification, for, the, refactor, wave, and, record, any, residual, gaps, normalized, compiled | failure: ci:local:full passed after focused init/platform-critical regression checks; framework:dev:bootstrap, agentplane doctor, policy routing, and spec:examples smoke also passed. | advice: Normalized compiled init prompt asset output to one trailing newline and updated the direct-mode agent-template expectation to account for policy gateway rendering. | rule: Analogous Run final integrated verification for the refactor wave and record any residual gaps. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605010645-3W3EXR; commit b48a260fa73d | enforcement: manual | fixability: external | state: open
+- id: INC-20260501-02 | date: 2026-05-01 | scope: Submit a GitHub PR adding AgentPlane to brandonhimpfen/awesome-ai-coding-agents as workflow infrastructure for AI coding agents after checking scope alignment, formatting, and category placement. | tags: docs | match: docs, submit, github, adding, agentplane, brandonhimpfen, awesome, coding, agents, workflow, infrastructure, for, after, checking, scope, alignment | failure: Added AgentPlane to brandonhimpfen/awesome-ai-coding-agents under Agent Infrastructure using repo-local AI coding-agent workflow wording. Opened https://github.com/brandonhimpfen/awesome-ai-coding-agents/pull/8 with --body-file and verified gh pr view body renders with Markdown line breaks. Ran git diff --check, python3 .github/scripts/awesome_list_lint.py, python3 .github/scripts/detect_duplicate_links.py, python3 check_readme_links.py README.md --timeout 8, node .agentplane/policy/check-routing.mjs, and agentplane doctor. | advice: Upstream PR is open. Target repo link checker confirmed the AgentPlane URL as 200 but exits non-zero because the pre-existing agentcoder/AgentCoder entry returns 404; this is disclosed in the PR body. | rule: Analogous Submit a GitHub PR adding AgentPlane to brandonhimpfen/awesome-ai-coding-agents as workflow infrastructure for AI coding agents after checking scope alignment, formatting, and category placement. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605011518-PH7024; commit cb1fe303f97a | enforcement: manual | fixability: external | state: open
+- id: INC-20260501-03 | date: 2026-05-01 | scope: Make post-publish release evidence PR recovery authenticate gh so successful releases do not end as failed after publication. | tags: ci, release, workflow | match: ci, release, workflow, make, post, publish, evidence, recovery, authenticate, successful, releases, not, end, failed, after, publication | failure: Release evidence gh CLI steps now set GH_TOKEN from github.token. | advice: Added GH_TOKEN env to release evidence PR check/create/merge steps and contract coverage. | rule: Analogous Make post-publish release evidence PR recovery authenticate gh so successful releases do not end as failed after publication. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605012054-HS993A; commit c329da9be70f | enforcement: manual | fixability: external | state: open
+- id: INC-20260501-04 | date: 2026-05-01 | scope: Update the Homebrew formula renderer and tap formula so fresh AgentPlane releases install without Homebrew npm min-release-age blocking fresh package dependencies. | tags: release, workflow | match: release, workflow, update, the, homebrew, formula, renderer, and, tap, fresh, agentplane, releases, install, without, npm, min | failure: Updated render-homebrew-formula to install the cached npm tarball without std_npm_args/min-release-age, added contract coverage, and pushed basilisk-labs/homebrew-tap c6d3e94 for v0.4.1. Local Homebrew install reached Cellar successfully; final link was blocked only by an existing /opt/homebrew/bin/agentplane npm-global symlink. | advice: Run brew link --overwrite agentplane when an old npm-global symlink is present; standalone no-Node install requires a future native/bundled CLI artifact. | rule: Analogous Update the Homebrew formula renderer and tap formula so fresh AgentPlane releases install without Homebrew npm min-release-age blocking fresh package dependencies. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605012143-NEK3E8; commit 43bc2ed84a23 | enforcement: manual | fixability: external | state: open
+- id: INC-20260503-01 | date: 2026-05-03 | scope: Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. | tags: code, release, workflow | match: code, release, workflow, port, the, artifacts, language, configuration, and, artifact, validation, from, stale, cli, branch, onto | failure: Ported artifacts_language=en and PR artifact language validation onto current main; stale trust branch was not merged because it would reintroduce old task states. | advice: No rework required before PR. | rule: Analogous Port the artifacts_language configuration and PR artifact language validation from the stale cli-artifacts branch onto current main, preserving current v0.4.2 release state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202605030733-BHD4S4; commit c66cff3d6f16 | enforcement: manual | fixability: external | state: open

package/assets/policy/workflow.branch_pr.md

@@ -19,6 +19,22 @@ Use this module when `workflow_mode=branch_pr`.
 8. CHECKPOINT C: finish task(s) on base with verification evidence.
 9. Remove merged task branches/worktrees once the hosted-close/finish route has landed.
 
+## Related task batch worktrees
+
+When several approved tasks form one dependent change, they MAY be executed in one primary task
+worktree instead of one worktree per task. Use this only when splitting the work into separate PRs
+would add coordination risk without improving review.
+
+Batch worktree rules:
+
+- One task is the primary integration task and owns the branch, worktree, and PR.
+- Every included task id MUST be listed in the primary task plan or PR artifact before mutation.
+- Each included task MUST keep its own plan, start-ready record, Verify Steps, verification result,
+  and finish evidence.
+- Commits SHOULD mention the relevant task suffixes when a change serves more than one included
+  task.
+- The final PR MUST describe the full included task set and merge the complete result into `main`.
+
 <!-- /ap:fragment -->
 <!-- ap:fragment id="policy.workflow.branch_pr.commands.command.contract" slot="commands" mutability="replaceable" -->
 
@@ -43,6 +59,8 @@ agentplane finish <task-id> --author INTEGRATOR --body "Verified: ..." --result
 - 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).
 - In `branch_pr`, `task start-ready`, `pr open`, `pr update`, and verification commands SHOULD be run from the task worktree created by `work start`.
+- A related task batch MAY reuse one primary task worktree when all included tasks are approved,
+  listed, verified independently, and merged through the primary task PR.
 - `pr open` without `--sync-only` SHOULD complete in one pass: sync local artifacts, auto-publish the task branch to `origin` when it has no upstream yet, then create/link the remote GitHub PR.
 - `integrate` defaults to the `merge` strategy so task branch commits stay in base history. Use `--merge-strategy squash` only when intentionally compacting branch history.
 - `task start-ready` MAY surface targeted incident advice for analogous scope/tags; follow it before widening scope.

package/assets/policy/workflow.release.md

@@ -42,5 +42,5 @@ agentplane finish <task-id> --author <ROLE> --body "Verified: release" --result
 - MUST NOT bypass required notes validation.
 - MUST stop and request re-approval if release scope/tag/version changes.
 - In `direct`, `release apply --push --yes` is the publication route and may create/push the release tag.
-- In `branch_pr`, `release apply` is not the publication route; use `release candidate --push --yes`, merge the candidate into the protected base branch, then let hosted publish run from `main`.
+- In `branch_pr`, `release apply` is not the publication route; use `release candidate --push --yes`, merge the candidate into the protected base branch, then explicitly dispatch `Publish to npm` with the release commit `sha`.
 <!-- /ap:fragment -->

package/bin/agentplane.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -187,6 +188,7 @@ function renderStalePolicyWarning(reason) {
 
 function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requireFromAgentplane = createRequire(path.join(agentplaneRoot, "package.json"));
+  const frameworkRoot = path.resolve(agentplaneRoot, "..", "..");
   let packageJson = null;
   try {
     packageJson = requireFromAgentplane("./package.json");
@@ -206,8 +208,9 @@ function missingRepoRuntimeDependencies(agentplaneRoot) {
   const requiredSpecifiers = ["@agentplaneorg/core"];
   return requiredSpecifiers.filter((specifier) => {
     try {
-      requireFromAgentplane.resolve(specifier);
-      return false;
+      const resolved = requireFromAgentplane.resolve(specifier);
+      if (isPathInside(frameworkRoot, resolved)) return false;
+      return !existsSync(path.join(agentplaneRoot, "node_modules", ...specifier.split("/")));
     } catch {
       return true;
     }

package/dist/.build-manifest.json

@@ -2,7 +2,7 @@
   "schema_version": 1,
   "manifest_kind": "package",
   "package_name": "agentplane",
-  "package_version": "0.4.0",
-  "git_head": "060b70ca465b780337c2ec9da035fc66e615803f",
-  "watched_runtime_snapshot_hash": "82fa091f9239f2e026072e502e8a3ca48fe8e84136b5e568cfd7f880579add53"
+  "package_version": "0.4.2",
+  "git_head": "2c98719336c87cbe2aaf196d14b32c841a9defa1",
+  "watched_runtime_snapshot_hash": "56c2045c93aa3da808e26b1dc2396f28fbdcbe7a9c1ba9db50362d2432b0f257"
 }