agentplane 0.3.7 → 0.3.8

package/assets/AGENTS.md

@@ -17,7 +17,7 @@ Detailed procedures live in canonical modules from `## CANONICAL DOCS`.
 - Repository type: user project initialized with `agentplane`.
 - Gateway role: keep this file compact and deterministic; move scenario-specific details to policy modules.
 - CLI rule: use `agentplane` from `PATH`; if unavailable, stop and request installation guidance (do not invent repo-local entrypoints).
-- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation.
+- Startup shortcut: run `## COMMANDS -> Preflight`, then use `agentplane quickstart`; activate `agentplane role ORCHESTRATOR` for planning and `agentplane role <ROLE>` for the active owner before owner-scoped execution; then apply `## LOAD RULES` before any mutation. In this repository, `workflow_mode=branch_pr`, so the normal guarded route starts from `agentplane work start ... --worktree` on the base branch; treat `direct` as an explicit alternative only when intentionally selected.
 
 ---
 
@@ -69,6 +69,16 @@ agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."
 agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>
 ```
 
+### branch_pr lifecycle
+
+```bash
+agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree
+agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>
+agentplane pr update <task-id>
+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
+```
+
 ### Verification
 
 ```bash

package/assets/RUNNER.md

@@ -0,0 +1,17 @@
+# agentplane runner
+
+Operate as the agentplane execution runner.
+
+- Treat `bundle.json` as the authoritative input contract.
+- This invocation already passed repository preflight, plan approval, and task start lifecycle gates.
+- Do not run repository startup commands such as `agentplane config show`, `agentplane quickstart`, `agentplane task list`, `git status`, or `git rev-parse` unless the bundle explicitly requires them as task work.
+- Do not create, approve, start, verify, finish, block, or rerun tasks unless the bundle explicitly requires task-metadata edits as part of the requested work.
+- Do not recursively invoke `agentplane task run`, `agentplane scenario execute`, or similar runner entrypoints from inside the runner.
+- Apply prompt blocks in ascending `priority` order.
+- Framework and repository policy blocks override owner, task, and recipe context.
+- Do not reconstruct missing context from CLI argv.
+- Use task and recipe context from the bundle before making assumptions.
+- Keep outputs and evidence inside declared runner artifacts and allowed repository changes.
+- Execute-mode runs must write a valid JSON result manifest to `AGENTPLANE_RUNNER_RESULT_PATH` before exiting.
+- Minimal manifest example: `{"schema_version":1,"status":"success","summary":"Completed.","capabilities_used":["runner.exec"]}`
+- When the requested task outcome is satisfied, stop immediately instead of re-running repository bootstrap or lifecycle flows.

package/bin/agentplane.js

@@ -4,6 +4,11 @@ import path from "node:path";
 import { stat } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { distExists, isPackageBuildFresh } from "./dist-guard.js";
+import {
+  FRAMEWORK_DEV_BOOTSTRAP_COMMAND,
+  FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE,
+  FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS,
+} from "./framework-dev-contract.js";
 import { getWatchedRuntimePathsForPackage } from "./runtime-watch.js";
 import { classifyStaleDistPolicy } from "./stale-dist-policy.js";
 import { isPathInside, resolveFrameworkBinaryContext } from "./runtime-context.js";
@@ -126,10 +131,14 @@ async function assertDistUpToDate() {
   const allowStale = (process.env.AGENTPLANE_DEV_ALLOW_STALE_DIST ?? "").trim() === "1";
   if (!(await distExists(agentplaneRoot))) {
     process.stderr.write(
-      "error: agentplane dist is missing for this repo checkout.\n" +
+      "error: agentplane dist is missing for this framework checkout.\n" +
+        "This worktree is not bootstrapped yet.\n" +
         "Fix:\n" +
-        "  bun run --filter=@agentplaneorg/core build\n" +
-        "  bun run --filter=agentplane build\n",
+        `  ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n` +
+        "Manual fallback:\n" +
+        FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS.map((command) => `  ${command}\n`).join("") +
+        "Supported global override when you intentionally want the installed binary:\n" +
+        `  ${FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE}\n`,
     );
     process.exitCode = 2;
     return false;
@@ -188,8 +197,7 @@ async function assertDistUpToDate() {
           `command: ${commandText || "<unknown>"}\n` +
           `detected: ${staleReasons.join(", ")}\n` +
           "rebuild recommended:\n" +
-          "  bun run --filter=@agentplaneorg/core build\n" +
-          "  bun run --filter=agentplane build\n",
+          `  ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n`,
       );
       return true;
     }
@@ -197,8 +205,9 @@ async function assertDistUpToDate() {
     process.stderr.write(
       "error: refusing to run a stale repo build (manifest/git quick-check failed).\n" +
         "Fix:\n" +
-        "  bun run --filter=@agentplaneorg/core build\n" +
-        "  bun run --filter=agentplane build\n" +
+        `  ${FRAMEWORK_DEV_BOOTSTRAP_COMMAND}\n` +
+        "Manual fallback:\n" +
+        FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS.map((command) => `  ${command}\n`).join("") +
         `Detected: ${staleReasons.join(", ")}\n` +
         "Override (not recommended): set AGENTPLANE_DEV_ALLOW_STALE_DIST=1\n",
     );

package/bin/framework-dev-contract.d.ts

@@ -0,0 +1,6 @@
+export declare const FRAMEWORK_DEV_BOOTSTRAP_COMMAND: string;
+export declare const FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS: string[];
+export declare const FRAMEWORK_DEV_REPO_LOCAL_VERIFY_COMMAND: string;
+export declare const FRAMEWORK_DEV_GLOBAL_VERIFY_COMMAND: string;
+export declare const FRAMEWORK_DEV_REINSTALL_SCRIPT: string;
+export declare const FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE: string;

package/bin/framework-dev-contract.js

@@ -0,0 +1,13 @@
+export const FRAMEWORK_DEV_BOOTSTRAP_COMMAND = "bun run framework:dev:bootstrap";
+export const FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS = [
+  "bun install",
+  "git submodule update --init --recursive agentplane-recipes",
+  "bun run --filter=@agentplaneorg/core build",
+  "bun run --filter=agentplane build",
+];
+export const FRAMEWORK_DEV_REPO_LOCAL_VERIFY_COMMAND =
+  "node packages/agentplane/bin/agentplane.js runtime explain";
+export const FRAMEWORK_DEV_GLOBAL_VERIFY_COMMAND = "agentplane runtime explain";
+export const FRAMEWORK_DEV_REINSTALL_SCRIPT = "scripts/reinstall-global-agentplane.sh";
+export const FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE =
+  "AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1 agentplane <command>";

package/bin/stale-dist-policy.js

@@ -34,6 +34,10 @@ function isReadyInspectionCommand(args) {
   return args[0] === "ready";
 }
 
+function isPreflightCommand(args) {
+  return args[0] === "preflight";
+}
+
 export function classifyStaleDistPolicy(argv = process.argv) {
   const args = normalizeArgs(argv);
   if (
@@ -43,7 +47,8 @@ export function classifyStaleDistPolicy(argv = process.argv) {
     isRoleOrQuickstartCommand(args) ||
     isConfigInspectionCommand(args) ||
     isTaskInspectionCommand(args) ||
-    isReadyInspectionCommand(args)
+    isReadyInspectionCommand(args) ||
+    isPreflightCommand(args)
   ) {
     return { mode: "warn_and_run", reason: "read_only_diagnostic" };
   }