agentplane 0.3.20 → 0.3.22

package/assets/policy/incidents.md

@@ -14,3 +14,6 @@
 - id: INC-20260420-01 | date: 2026-04-20 | scope: Audit CLI path resolution for global-install style layouts, fix any repo-local script path defects, and add regression tests that fail when installed CLI code resolves repository scripts from the global package location. | tags: bugfix, code, hooks | match: bugfix, code, hooks, audit, cli, path, resolution, for, global, install, style, layouts, fix, any, repo, local | failure: Audited import.meta.url/fileURLToPath candidates touching scripts/bin paths. The real repo-script risk was pre-push fallback returning a non-existent global prefix path; workflow-playbook's bin path is package-bundled and covered by existing workflow tests. | advice: Pre-push script resolution now returns repository-local script first, existing bundled fallback second, otherwise null with an actionable repository-local error message. | rule: Analogous Audit CLI path resolution for global-install style layouts, fix any repo-local script path defects, and add regression tests that fail when installed CLI code resolves repository scripts from the global package location. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604200850-9T6FTC; commit d30a706ce568 | enforcement: manual | fixability: external | state: open
 - id: INC-20260422-01 | date: 2026-04-22 | scope: Runner prompt assembly only. Do not cache task-specific prompt content or mutable task state. | tags: cache, perf, runner | match: cache, perf, runner, prompt, assembly, only, not, task, specific, content, mutable, state, source, avoid, repeated, scanning | failure: Cached bundled agent templates, bundled policy gateway templates, and framework runner prompt assembly; repo-local policy/profile reads use mtime/size validation so changed files are not stale. | advice: Added regression coverage for repeated static prompt reuse and repo-local prompt cache invalidation. | rule: Analogous Runner prompt assembly only. Do not cache task-specific prompt content or mutable task state. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604220255-AQHZT4; commit 268c42af4447 | enforcement: manual | fixability: external | state: open
 - id: INC-20260422-02 | date: 2026-04-22 | scope: Publish the next patch release containing the init cached recipe manifest compatibility fix and restored interactive init ASCII logo. | tags: ci, init, release | match: ci, init, release, publish, the, next, patch, containing, cached, recipe, manifest, compatibility, fix, and, restored, interactive | failure: Pre-push release-mode hook failed when inherited test execution changed shared git core.bare=true; restored local core.bare=false and confirmed remote tag v0.3.19 points at main merge commit 45ba9c57. | advice: Use hosted release workflow as publication evidence; record local hook pollution as a release-process follow-up rather than blocking this hotfix. | rule: Analogous Publish the next patch release containing the init cached recipe manifest compatibility fix and restored interactive init ASCII logo. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604221605-SQYRNQ; commit 45ba9c57f939 | enforcement: manual | fixability: external | state: open
+- id: INC-20260423-01 | date: 2026-04-23 | scope: commit allowlist staging behavior and diagnostics for active task artifacts. Out of scope: broad commit policy rewrites or protected path model changes. | tags: code, git, workflow | match: code, git, workflow, commit, allowlist, staging, behavior, and, diagnostics, for, active, task, artifacts, out, scope, broad | failure: Ran bun run test:project -- cli-core packages/agentplane/src/cli/run-cli.core.guard.commit-wrapper.test.ts; bun run test:project -- guard; Prettier check for changed files. | advice: Added non-empty-index staging before guard validation and regression coverage. | rule: Analogous commit allowlist staging behavior and diagnostics for active task artifacts. Out of scope: broad commit policy rewrites or protected path model changes. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604230838-598K1H; commit afa741361351 | enforcement: manual | fixability: external | state: open
+- id: INC-20260423-02 | date: 2026-04-23 | scope: generated guidance and default examples for test commands. Out of scope: rewriting historical release notes or changing user-supplied task verify commands. | tags: code, guidance, testing | match: code, guidance, testing, generated, and, default, examples, for, test, commands, out, scope, rewriting, historical, release, notes | failure: Ran bun run test:project -- cli-core packages/agentplane/src/cli/run-cli.core.tasks.scaffold-derive.test.ts; bun run workflows:command-check; bun run docs:cli:check; Prettier check for changed files. | advice: Updated task derive example/test fixture and expanded workflow command contract scanning to command specs. | rule: Analogous generated guidance and default examples for test commands. Out of scope: rewriting historical release notes or changing user-supplied task verify commands. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604230839-Y92ZJJ; commit 7e088c735372 | enforcement: manual | fixability: external | state: open
+- id: INC-20260423-03 | date: 2026-04-23 | scope: Move managed hook shim readiness checks out of doctor/workspace.ts so hotspot gate passes after installed-user diagnostics additions. | tags: code, quality | match: code, quality, move, managed, hook, shim, readiness, checks, out, doctor, workspace, hotspot, gate, passes, after, installed | failure: Ran bun run hotspots:check; bun run test:project -- agentplane packages/agentplane/src/commands/doctor.command.runtime.test.ts; Prettier check for changed files. | advice: Extracted hook readiness diagnostics to doctor/hook-readiness.ts and updated oversized test baseline for already-grown warning files. | rule: Analogous Move managed hook shim readiness checks out of doctor/workspace.ts so hotspot gate passes after installed-user diagnostics additions. work MUST review and apply the recorded external incident advice before retrying. | evidence: task 202604230949-E1BG2Q; commit 2fc331ddf503 | enforcement: manual | fixability: external | state: open

package/dist/.build-manifest.json

@@ -1,13 +1,13 @@
 {
   "schema_version": 1,
   "package_dir": "/home/runner/work/agentplane/agentplane/packages/agentplane",
-  "generated_at": "2026-04-22T17:14:55.584Z",
-  "git_head": "f8bb47a8001d4867a9c35374f733f243b1004aac",
-  "src_cli_mtime_ms": 1776877983086.4597,
+  "generated_at": "2026-04-23T10:57:53.234Z",
+  "git_head": "73ef1559365a7fe053726b4e7cd49568d8105d7f",
+  "src_cli_mtime_ms": 1776941764898.929,
   "src_index_mtime_ms": null,
-  "dist_cli_mtime_ms": 1776878095383.3855,
+  "dist_cli_mtime_ms": 1776941873033.4214,
   "dist_index_mtime_ms": null,
-  "tsbuildinfo_mtime_ms": 1776878093325.3518,
+  "tsbuildinfo_mtime_ms": 1776941870953.412,
   "watched_runtime_paths": [
     "src",
     "bin/agentplane.js",
@@ -15,7 +15,7 @@
     "bin/runtime-context.js",
     "bin/stale-dist-policy.js"
   ],
-  "watched_runtime_snapshot_hash": "9a7adee478ae1a91572053a6e683b07798d30e6abc4b8c1ca4d904d46edb6f3c",
+  "watched_runtime_snapshot_hash": "ddde696f154e2ae49bf5b10fbeaaa63db94d57c5858b7b6b68cdde6faf92fc94",
   "watched_runtime_files": [
     {
       "path": "bin/agentplane.js",
@@ -299,8 +299,8 @@
     },
     {
       "path": "src/cli/bootstrap-guide.ts",
-      "sha256": "3b07c9784c96ded54ec32792b1aab45fc88385b7aac196bf7350608acc4db64d",
-      "size_bytes": 6891
+      "sha256": "028fa8b3b233b589f1b492a34d4a5fc3f52835aac7649ccc479d943638445bd9",
+      "size_bytes": 7087
     },
     {
       "path": "src/cli/checksum.ts",
@@ -309,8 +309,8 @@
     },
     {
       "path": "src/cli/command-guide.ts",
-      "sha256": "e255edf911de9114ae8cfdcdae8f667fb69f1116351f8dd2d411c52b295aa9af",
-      "size_bytes": 10457
+      "sha256": "8158a55d3858a84216157878c1901ae5b05464827f2f5f3136d64b3063cf8b18",
+      "size_bytes": 10622
     },
     {
       "path": "src/cli/command-invocations.ts",
@@ -564,8 +564,8 @@
     },
     {
       "path": "src/cli/run-cli/commands/init/recipes.ts",
-      "sha256": "2164d394458cc6892b0f75720a7e8fa0ca64a48dab9a3caf5c32a00cbb2d418f",
-      "size_bytes": 1892
+      "sha256": "bd309ab8d4f6b541dd977c0bdb632af5ec8db934e261fc6b56adcd064373d9f9",
+      "size_bytes": 1912
     },
     {
       "path": "src/cli/run-cli/commands/init/spec.ts",
@@ -824,8 +824,8 @@
     },
     {
       "path": "src/commands/branch/work-start.hook-shim.ts",
-      "sha256": "2774009f78ab0d950574c30829fc3c07a62c907503e4aa060ee63a8a30987216",
-      "size_bytes": 1548
+      "sha256": "f7476ddae2e26bee6d7bcfa4cb7b47c8115e2503ed00674272f5afed50349538",
+      "size_bytes": 2246
     },
     {
       "path": "src/commands/branch/work-start.materialize.ts",
@@ -887,6 +887,11 @@
       "sha256": "5d85f2539e6828a414cb9f5f2132de869c03d4913465dded51a8279a0aa43737",
       "size_bytes": 1700
     },
+    {
+      "path": "src/commands/doctor/hook-readiness.ts",
+      "sha256": "cf88e56388325bf8edeeb1e7ab5e76e4d7a2acd90aadee346818016453bb868d",
+      "size_bytes": 7624
+    },
     {
       "path": "src/commands/doctor/layering.ts",
       "sha256": "c1e655996e5253b486500b68ad19f4493da67dd85758f0097acb173ba487955c",
@@ -904,8 +909,8 @@
     },
     {
       "path": "src/commands/doctor/workspace.ts",
-      "sha256": "8d92b2eab7ba2485787995f1807adc1c618e832436b812a86cb82bce09bc9ef2",
-      "size_bytes": 14977
+      "sha256": "9813d51c56559082d99604b2dd17546872a863bd5a9c926e6901cddb4bf6c60f",
+      "size_bytes": 15102
     },
     {
       "path": "src/commands/finish.run.ts",
@@ -969,8 +974,8 @@
     },
     {
       "path": "src/commands/guard/impl/commit.ts",
-      "sha256": "2578c9ab061d260b0c6518c458a18b85444489d2cd7cf0d362858d9266215c9b",
-      "size_bytes": 15217
+      "sha256": "1736bcdc25f33e8097f6fec256c2e37710207e17f4604a7eb08dae82ae520e85",
+      "size_bytes": 16326
     },
     {
       "path": "src/commands/guard/impl/env.ts",
@@ -1019,8 +1024,8 @@
     },
     {
       "path": "src/commands/hooks/install.ts",
-      "sha256": "c4930d3732fef17d8518038ea60f0bf11d901e85fd1a9ddcadbd82ce4f02847f",
-      "size_bytes": 5087
+      "sha256": "dee64b96a4430439640c3f02c6f291cc618caed1af099291a0d67aec31f4b375",
+      "size_bytes": 5785
     },
     {
       "path": "src/commands/hooks/run.command.ts",
@@ -1044,8 +1049,8 @@
     },
     {
       "path": "src/commands/hooks/run.pre-push.ts",
-      "sha256": "d36b49c91eaeef229c9a2f1ffbff6f41cd3c09632660fed4fd984354fa79dc28",
-      "size_bytes": 3247
+      "sha256": "4d7abee3621fdde76a572e57b8f622ab4af7a2e0ce936c48661a4d3c91095d21",
+      "size_bytes": 11740
     },
     {
       "path": "src/commands/hooks/run.ts",
@@ -1414,8 +1419,8 @@
     },
     {
       "path": "src/commands/recipes/impl/installed-recipes.ts",
-      "sha256": "13c8c7b63d672d9588edc8c54c79fa8e35df4ac5caca174b2cd641563a2a3627",
-      "size_bytes": 2974
+      "sha256": "fbc372ff5d8fd731ce8ff35c006537ae7148ee92619ed1343b9f55ae81f29d70",
+      "size_bytes": 3979
     },
     {
       "path": "src/commands/recipes/impl/mutation-transaction.ts",
@@ -1804,8 +1809,8 @@
     },
     {
       "path": "src/commands/task/derive.command.ts",
-      "sha256": "fe9b5850ad73f9836397b20aba34b1b30c0cff5b86dd3ca8a9dcd0b67063796f",
-      "size_bytes": 3603
+      "sha256": "b903c0b7df07a26cbad1dbb9046c7109d73a778c0df56a68725b334e4e419db0",
+      "size_bytes": 3627
     },
     {
       "path": "src/commands/task/derive.ts",
@@ -1874,8 +1879,8 @@
     },
     {
       "path": "src/commands/task/finish-execute.ts",
-      "sha256": "a2ac26822e1700ace23fc365fdd0467cb7e0a6b4345e40e71476abcc73e071c2",
-      "size_bytes": 11110
+      "sha256": "55b58c8792de4767b7cc202bbdc16ab9568d4d31a51f6a7553316c379d8ccd29",
+      "size_bytes": 11597
     },
     {
       "path": "src/commands/task/finish-findings.ts",
@@ -2284,8 +2289,8 @@
     },
     {
       "path": "src/commands/task/shared/transitions.ts",
-      "sha256": "75a5e5220a2c71b6673cb6be7cc94c248b2710ddeeba1ff7b15d1373f9eeffd0",
-      "size_bytes": 7530
+      "sha256": "94be63f0fb51cc244cd48178aebd887bd5c83de23f66bcc29a46ce18d46cd09d",
+      "size_bytes": 8088
     },
     {
       "path": "src/commands/task/shared/workflow-transition-service.ts",
@@ -2339,8 +2344,8 @@
     },
     {
       "path": "src/commands/task/verify-command-shared.ts",
-      "sha256": "536bb3a2a9ebf56eb843494fe855dc95a53bbab6cb145504e5017e1b80161dd7",
-      "size_bytes": 7970
+      "sha256": "1bda6957958dceceb6876ea0d8e2bb0d07640d76dcf3e1552fa45fe50e6b89d8",
+      "size_bytes": 8079
     },
     {
       "path": "src/commands/task/verify-ok.command.ts",

package/dist/cli/bootstrap-guide.d.ts

@@ -1,5 +1,6 @@
 export declare const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
 export declare const AGENT_BOOTSTRAP_RUNTIME_SURFACE = "agentplane quickstart";
+export declare const BRANCH_PR_HOSTED_GATE_GUIDANCE = "confirm hosted required checks through the repository's configured CI/provider gate; optional framework-maintainer helper when present: `bun run workflow:wait-remote-checks`";
 export type BootstrapSection = {
     heading: string;
     summary: string;

package/dist/cli/bootstrap-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bootstrap-guide.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap-guide.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,4CAA4C,CAAC;AAClF,eAAO,MAAM,+BAA+B,0BAA0B,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,iHAM/B,CAAC;AAEX,eAAO,MAAM,4BAA4B,UAIxC,CAAC;AAEF,eAAO,MAAM,oCAAoC,4JAMvC,CAAC;AAEX,eAAO,MAAM,+BAA+B,0HAOlC,CAAC;AAEX,eAAO,MAAM,2BAA2B,sFAI9B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAgDhD,CAAC;AAEX,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAiB3F;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CA2B3C"}
+{"version":3,"file":"bootstrap-guide.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap-guide.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,4CAA4C,CAAC;AAClF,eAAO,MAAM,+BAA+B,0BAA0B,CAAC;AACvE,eAAO,MAAM,8BAA8B,kLACsI,CAAC;AAElL,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,iHAM/B,CAAC;AAEX,eAAO,MAAM,4BAA4B,UAIxC,CAAC;AAEF,eAAO,MAAM,oCAAoC,4JAMvC,CAAC;AAEX,eAAO,MAAM,+BAA+B,0HAOlC,CAAC;AAEX,eAAO,MAAM,2BAA2B,sFAI9B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAgDhD,CAAC;AAEX,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAiB3F;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CA2B3C"}

package/dist/cli/bootstrap-guide.js

@@ -1,6 +1,7 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
 export const AGENT_BOOTSTRAP_DOC_PATH = "docs/user/agent-bootstrap.generated.mdx";
 export const AGENT_BOOTSTRAP_RUNTIME_SURFACE = "agentplane quickstart";
+export const BRANCH_PR_HOSTED_GATE_GUIDANCE = "confirm hosted required checks through the repository's configured CI/provider gate; optional framework-maintainer helper when present: `bun run workflow:wait-remote-checks`";
 export const BOOTSTRAP_PREFLIGHT_COMMANDS = [
     COMMAND_SNIPPETS.core.configShow,
     COMMAND_SNIPPETS.core.quickstart,
@@ -118,13 +119,13 @@ export function renderBootstrapDoc() {
         "",
         ...renderCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
         "",
-        "After preflight, follow the configured workflow mode. In repositories configured for `branch_pr`, start with `agentplane help work start`, keep local PR artifacts current with `agentplane pr ...`, wait for hosted required checks with `bun run workflow:wait-remote-checks`, and only then integrate on base; use the direct-mode route below only when `workflow_mode=direct` is intentional.",
+        `After preflight, follow the configured workflow mode. In repositories configured for \`branch_pr\`, start with \`agentplane help work start\`, keep local PR artifacts current with \`agentplane pr ...\`, ${BRANCH_PR_HOSTED_GATE_GUIDANCE}, and only then integrate on base; use the direct-mode route below only when \`workflow_mode=direct\` is intentional.`,
         "",
         ...renderBootstrapSectionLines(BOOTSTRAP_SECTIONS),
         "",
         "## Non-default paths",
         "",
-        "- `branch_pr`: in repositories configured this way, start a task branch/worktree, maintain PR artifacts, wait for hosted required checks, and let INTEGRATOR close on base only after the remote gate is green.",
+        `- \`branch_pr\`: in repositories configured this way, start a task branch/worktree, maintain PR artifacts, ${BRANCH_PR_HOSTED_GATE_GUIDANCE}, and let INTEGRATOR close on base only after the remote gate is green.`,
         "- `direct`: use `task new/plan approve/start-ready -> task verify-show -> verify -> finish` only when `workflow_mode=direct` is intentional.",
         "- Use manual close flags only when a specific policy or recovery situation requires them.",
         "",

package/dist/cli/command-guide.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAqGF,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAMvE;AAMD,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAAO,GAC/C,MAAM,GAAG,IAAI,CA6Bf;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAqCzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9B,CAAC;AAqGF,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAMvE;AAMD,wBAAgB,UAAU,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,GAAE;IAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAAO,GAC/C,MAAM,GAAG,IAAI,CA6Bf;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAsCzC"}

package/dist/cli/command-guide.js

@@ -1,5 +1,5 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
-import { BOOTSTRAP_PREFLIGHT_COMMANDS, BOOTSTRAP_TASK_PREP_COMMANDS } from "./bootstrap-guide.js";
+import { BOOTSTRAP_PREFLIGHT_COMMANDS, BOOTSTRAP_TASK_PREP_COMMANDS, BRANCH_PR_HOSTED_GATE_GUIDANCE, } from "./bootstrap-guide.js";
 const SHARED_STARTUP_NOTE = `- Shared startup path: \`${COMMAND_SNIPPETS.core.quickstart}\` is the canonical installed bootstrap; use \`${COMMAND_SNIPPETS.core.role}\` to activate the current role before role-scoped planning or execution.`;
 function renderQuickstartCommandBlock(commands) {
     return ["```bash", ...commands, "```"];
@@ -66,7 +66,7 @@ const ROLE_GUIDES = [
         role: "INTEGRATOR",
         lines: [
             SHARED_STARTUP_NOTE,
-            '- branch_pr: require a green hosted PR gate first (`bun run workflow:wait-remote-checks` on the task branch or PR), then run `agentplane pr check <task-id>` -> `agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify` -> `agentplane finish <task-id> --commit <git-rev> --author INTEGRATOR --body "Verified: ..." --result "..." --close-commit` on the base branch.',
+            `- branch_pr: require a green hosted PR gate first (${BRANCH_PR_HOSTED_GATE_GUIDANCE}), then run \`agentplane pr check <task-id>\` -> \`agentplane integrate <task-id> --branch task/<task-id>/<slug> --merge-strategy squash --run-verify\` -> \`agentplane finish <task-id> --commit <git-rev> --author INTEGRATOR --body "Verified: ..." --result "..." --close-commit\` on the base branch.`,
             "- branch_pr hosted shortcut: if GitHub merges the task PR directly, `Task Hosted Close` pushes the deterministic closure branch automatically and opens the follow-up closure PR when organization policy allows Actions PR creation; otherwise it leaves a manual PR link on the merged task PR. Pull the updated base branch after that closure PR merges instead of creating a local finish-only tail commit.",
             `- direct: the task owner normally closes with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \`.`,
             "- For branch-level flags and branch/base diagnostics, use `agentplane help work start`, `agentplane help integrate`, and `agentplane help branch base`.",
@@ -159,7 +159,7 @@ export function renderQuickstart() {
         "",
         "Configured workflow route:",
         "",
-        "- `branch_pr`: start from `agentplane help work start`, keep local PR artifacts current with `agentplane pr ...`, wait for hosted required checks with `bun run workflow:wait-remote-checks`, then integrate on base.",
+        `- \`branch_pr\`: start from \`agentplane help work start\`, keep local PR artifacts current with \`agentplane pr ...\`, ${BRANCH_PR_HOSTED_GATE_GUIDANCE}, then integrate on base.`,
         `- \`direct\`: task setup is \`${BOOTSTRAP_TASK_PREP_COMMANDS[0]}\` -> \`${BOOTSTRAP_TASK_PREP_COMMANDS[1]}\` -> \`${BOOTSTRAP_TASK_PREP_COMMANDS[2]}\`.`,
         `- \`direct\`: execution is \`${COMMAND_SNIPPETS.core.startTask}\` -> \`${COMMAND_SNIPPETS.core.taskVerifyShow}\` -> \`${COMMAND_SNIPPETS.core.verifyTask}\` -> \`${COMMAND_SNIPPETS.core.finishTask}\` with \`--result "..." \`.`,
         "- In `direct`, `finish` creates the deterministic close commit by default; do not assume that route is the repository default when `workflow_mode=branch_pr`.",
@@ -173,7 +173,8 @@ export function renderQuickstart() {
         "",
         "## Non-default",
         "",
-        "- `branch_pr`: use `agentplane help work start`, `agentplane help pr`, `bun run workflow:wait-remote-checks`, and `agentplane help integrate` when the repository is configured that way.",
+        "- `branch_pr`: use `agentplane help work start`, `agentplane help pr`, `agentplane pr check <task-id>`, and `agentplane help integrate` when the repository is configured that way.",
+        "- Framework maintainers may use repo-local helper scripts such as `bun run workflow:wait-remote-checks` when those scripts exist; installed user repositories must not depend on them.",
         "- Recovery/mixed state: use `agentplane doctor`, `agentplane upgrade`, and `agentplane runtime explain`.",
         "- Manual close or allowlist details belong in command-specific help, not on this first screen.",
     ].join("\n");

package/dist/cli/run-cli/commands/init/recipes.js

@@ -1,9 +1,9 @@
 import { cmdRecipeAddParsed } from "../../../../commands/recipes/impl/commands/add.js";
-import { readInstalledRecipesFile } from "../../../../commands/recipes/impl/installed-recipes.js";
+import { readAndMigrateInstalledRecipesFile } from "../../../../commands/recipes/impl/installed-recipes.js";
 import { resolveInstalledRecipesPath } from "../../../../commands/recipes/impl/paths.js";
 import { CliError } from "../../../../shared/errors.js";
 export async function listCachedRecipes() {
-    const cached = await readInstalledRecipesFile(resolveInstalledRecipesPath());
+    const cached = await readAndMigrateInstalledRecipesFile(resolveInstalledRecipesPath());
     return cached.recipes.map((recipe) => ({
         id: recipe.id,
         summary: recipe.manifest.summary,