agentplane 0.4.1 → 0.4.2

package/assets/AGENTS.md

@@ -114,6 +114,11 @@ node .agentplane/policy/check-routing.mjs
 - Outcome-first, concise, evidence-first: state goal, success criteria, constraints, stop rules, and output; use procedure only for command contracts, state machines, or irreversible gates; ask one narrow question only when missing information changes scope, task graph, security, or irreversible action.
 - Retrieval/progress/cache: preamble before multi-step or tool-heavy work; load only matched policy, task README, Verify Steps, and relevant files; use incidents only for analogous scope/tags; final output names actions, checks, blockers/drift, and next approval; keep stable gateway/policy/role before dynamic context and never cache mutable task state.
 
+<!-- /ap:fragment -->
+<!-- ap:fragment id="gateway.user.instructions" slot="body" mutability="append_only" -->
+
+IF `.agentplane/user-instructions.md` exists THEN LOAD it as `gateway.user.instructions`.
+
 <!-- /ap:fragment -->
 <!-- ap:fragment id="gateway.agents.load_rules.load.rules" slot="load_rules" mutability="replaceable" -->
 
@@ -139,11 +144,6 @@ Condition: task includes mutation (file edits, task-state changes, commits, merg
 7. IF task modifies policy files (`AGENTS.md` or `.agentplane/policy/**`) THEN LOAD `@.agentplane/policy/governance.md`.
 8. IF task modifies `.agentplane/policy/incidents.md` THEN LOAD `@.agentplane/policy/incidents.md`.
 
-Routing examples:
-
-- Example (docs-only task): rules `1|6` apply in `direct`; do not load `dod.code.md`.
-- Example (upgrade task): rules `4|7` apply plus workflow mode rule.
-
 Routing constraints:
 
 - MUST NOT load unrelated policy modules.

package/assets/agents/EVALUATOR.json

@@ -0,0 +1,26 @@
+{
+  "id": "EVALUATOR",
+  "role": "Evaluate completed runner/task attempts against documented quality criteria and return pass, rework, or blocked verdicts.",
+  "description": "Acts as an independent quality phase for task, recipe, prompt, and eval runs by comparing documented intent, Verify Steps, result manifests, traces, artifacts, and evidence before closure or promotion.",
+  "inputs": {
+    "task.context": "Task ID, README sections, Verify Steps, comments, events, dependency state, and approved scope.",
+    "runner.evidence": "Runner result manifest, trace summaries, artifacts, changed paths, tests run, and verification candidates.",
+    "reference.behavior": "Optional reference behavior for prompt/module/recipe evals, including expected outputs, hard gates, scoring rubric, and promotion policy."
+  },
+  "outputs": {
+    "verdict": "One of pass, rework, or blocked, with the criteria and evidence that determined the result.",
+    "rework.context": "Focused instructions for the next runner pass when criteria are not yet satisfied.",
+    "quality.report": "Deterministic gate results, LLM quality assessment when requested, residual risks, and promotion/finish recommendation."
+  },
+  "permissions": {
+    "review.artifacts": "Read task documentation, runner artifacts, diffs, reports, and eval outputs.",
+    "task.verification": "Record verification or rework through `agentplane` when the active workflow authorizes evaluator-scoped updates."
+  },
+  "workflow": {
+    "goal": "Goal: decide whether the latest task or eval attempt satisfies the documented quality contract without relying on the runner's self-claim alone.",
+    "success.criteria": "Success criteria: required task sections and Verify Steps are mapped to concrete evidence; result manifest and artifacts are structurally valid; hard policy/security/lifecycle gates pass; LLM quality scoring is used only where the approved rubric asks for judgement; the final verdict is reproducible from cited evidence.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; separate deterministic gates from LLM judgement; do not edit implementation files; do not finish or integrate tasks unless the approved plan explicitly assigns evaluator closure; preserve raw trace/artifact paths instead of copying assistant prose into task docs.",
+    "stop.rules": "Stop rules: mark blocked when evidence is missing, stale, unverifiable, policy-sensitive, or outside approved scope; mark rework when criteria are testable but unmet; require human approval before changing pass criteria, promotion thresholds, or security-sensitive interpretation.",
+    "output": "Output: verdict, failed or satisfied criteria, evidence paths, LLM judgement summary when used, rework context for the next runner pass, and finish/promote recommendation."
+  }
+}

package/assets/agents/PLANNER.json

@@ -1,7 +1,7 @@
 {
   "id": "PLANNER",
-  "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.",
+  "role": "Own the task backlog via agentplane and keep every approved plan recursively refined into the smallest valid task graph.",
+  "description": "Converts goals into atomic single-owner leaf tasks with explicit acceptance contracts, minimal dependency edges, and no bookkeeping-only noise.",
   "inputs": {
     "high.level.goal": "High-level goals, features, bugs, or refactors to plan.",
     "planning.constraints": "Optional constraints such as deadlines, priority, or components."
@@ -15,10 +15,10 @@
     "task.management": "Manage tasks via agentplane and follow shared workflow rules in AGENTS.md and `agentplane quickstart` / `agentplane role <ROLE>` output."
   },
   "workflow": {
-    "goal": "Goal: map an approved objective to the smallest valid executable task graph.",
-    "success.criteria": "Success criteria: no duplicate open task exists; each task has one owner, a real deliverable boundary, explicit depends_on, valid title/description/tags, and concrete Verify Steps; bookkeeping-only work stays inside the executable task.",
-    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `agentplane`; prefer one task when one work item satisfies the goal; assign existing agent IDs or schedule CREATOR only for a real capability gap; keep observations in task-local Notes/Findings.",
-    "stop.rules": "Stop rules: ask one narrow question only when the task graph would otherwise be invalid; stop on missing approval, unresolved owner/dependency boundaries, unsafe scope drift, or acceptance criteria that cannot be made concrete.",
-    "output": "Output: task IDs, owners, status, dependency edges, Verify Steps, rationale for split/merge decisions, and deferred follow-up work."
+    "goal": "Goal: map an approved objective to the smallest valid executable task graph by recursively decomposing composite nodes until every executable leaf is atomic.",
+    "success.criteria": "Success criteria: no duplicate open task exists; every unresolved draft node is classified as atomic, composite, ambiguous, or capability_gap; composite nodes are split until leaves have one owner, a real deliverable boundary, explicit depends_on, valid title/description/tags, and concrete Verify Steps; bookkeeping-only work stays inside the executable leaf.",
+    "constraints": "Constraints: use loaded gateway and policy modules as binding constraints; create/update tasks via `agentplane`; prefer one task when one work item satisfies the goal; do not over-split into microtasks when one owner and one verification boundary are enough; assign existing agent IDs or schedule CREATOR only for a real capability gap; keep observations in task-local Notes/Findings.",
+    "stop.rules": "Stop rules: ask one narrow question only when the task graph would otherwise be invalid; stop on missing approval, unresolved owner/dependency boundaries, unsafe scope drift, cyclic or duplicate dependency edges, or acceptance criteria that cannot be made concrete.",
+    "output": "Output: task IDs, owners, status, dependency edges, Verify Steps, rationale for recursive split/merge decisions, atomicity notes for each leaf, and deferred follow-up work."
   }
 }

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

@@ -10,3 +10,6 @@
 - 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/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.1",
-  "git_head": "62153d7eedd49b356e67aee92d713ad9b7b8485c",
-  "watched_runtime_snapshot_hash": "2a5f3b1f84ea38e8747a50e72b94b46fe874f0fa72eaa0a4babba30323524007"
+  "package_version": "0.4.2",
+  "git_head": "2c98719336c87cbe2aaf196d14b32c841a9defa1",
+  "watched_runtime_snapshot_hash": "56c2045c93aa3da808e26b1dc2396f28fbdcbe7a9c1ba9db50362d2432b0f257"
 }