agentplane 0.3.5 → 0.3.7

package/dist/commands/upgrade.js

@@ -11,7 +11,10 @@ import { exitCodeForError } from "../cli/exit-codes.js";
 import { warnMessage } from "../cli/output.js";
 import { CliError } from "../shared/errors.js";
 import { ensureWorkflowArtifacts } from "../shared/workflow-artifacts.js";
+import { checkTaskReadmeMigrationState } from "./doctor/workspace.js";
+import { loadCommandContext } from "./shared/task-backend.js";
 import { ensureNetworkApproved } from "./shared/network-approval.js";
+import { migrateTaskDocsInWorkspace } from "./task/migrate-doc.js";
 import { getVersion } from "../meta/version.js";
 import { applyManagedFiles, cleanupAutoUpgradeArtifacts, createUpgradeCommit, ensureCleanTrackedTreeForUpgrade, persistUpgradeState, } from "./upgrade/apply.js";
 import { printUpgradeDryRun, writeUpgradeAgentReview } from "./upgrade/report.js";
@@ -210,6 +213,12 @@ export async function cmdUpgradeParsed(opts) {
         rootOverride: opts.rootOverride ?? null,
     });
     const loaded = await loadConfig(resolved.agentplaneDir);
+    const commandCtx = await loadCommandContext({
+        cwd: opts.cwd,
+        rootOverride: opts.rootOverride ?? null,
+        resolvedProject: resolved,
+        config: loaded.config,
+    });
     if (flags.mode === "auto" && !flags.dryRun) {
         await ensureCleanTrackedTreeForUpgrade(resolved.gitRoot);
     }
@@ -624,6 +633,21 @@ export async function cmdUpgradeParsed(opts) {
             createdBackups,
             toBaselineKey,
         });
+        const migratedTaskDocs = flags.migrateTaskDocs
+            ? await migrateTaskDocsInWorkspace({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+                all: true,
+                taskIds: [],
+                resolvedProject: resolved,
+                config: loaded.config,
+                ctx: commandCtx,
+            })
+            : { changed: 0, changedPaths: [] };
+        if (flags.migrateTaskDocs) {
+            const details = migratedTaskDocs.changed > 0 ? `changed=${migratedTaskDocs.changed}` : "already current";
+            process.stdout.write(`Task README migration: ${details}\n`);
+        }
         const hasManagedMutations = additions.length > 0 || updates.length > 0;
         const shouldMutateConfig = await persistUpgradeState({
             agentplaneDir: resolved.agentplaneDir,
@@ -655,6 +679,7 @@ export async function cmdUpgradeParsed(opts) {
             ...new Set([
                 ...additions,
                 ...updates,
+                ...migratedTaskDocs.changedPaths,
                 ...workflowArtifacts.commitPaths,
                 ...(shouldMutateConfig ? [CONFIG_REL_PATH] : []),
             ]),
@@ -662,6 +687,8 @@ export async function cmdUpgradeParsed(opts) {
         const commit = await createUpgradeCommit({
             gitRoot: resolved.gitRoot,
             paths: commitPaths,
+            tasksPath: loaded.config.paths.tasks_path,
+            workflowDir: loaded.config.paths.workflow_dir,
             versionLabel: upgradeVersionLabel,
             source: bundleLayout,
             additions: additions.length,
@@ -677,6 +704,13 @@ export async function cmdUpgradeParsed(opts) {
         if (commit) {
             process.stdout.write(`Upgrade commit: ${commit.hash.slice(0, 12)} ${commit.subject}\n`);
         }
+        const taskReadmeMigrationFindings = await checkTaskReadmeMigrationState(resolved.gitRoot, commandCtx);
+        if (taskReadmeMigrationFindings.length > 0) {
+            process.stderr.write(`${warnMessage("upgrade post-check: task README migration follow-up detected")}\n`);
+            for (const finding of taskReadmeMigrationFindings) {
+                process.stderr.write(`- ${finding}\n`);
+            }
+        }
         return 0;
     }
     finally {

package/dist/commands/verify.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.spec.d.ts","sourceRoot":"","sources":["../../src/commands/verify.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,KAAK,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC;AAEzC,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CA8FhD,CAAC"}
+{"version":3,"file":"verify.spec.d.ts","sourceRoot":"","sources":["../../src/commands/verify.spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAOvD,KAAK,WAAW,GAAG,IAAI,GAAG,cAAc,CAAC;AAEzC,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAoFhD,CAAC"}

package/dist/commands/verify.spec.js

@@ -1,4 +1,5 @@
 import { usageError } from "../cli/spec/errors.js";
+import { parseVerifyCommonOptions, validateVerifyDetailsFileExclusive, } from "./task/verify-command-shared.js";
 export const verifySpec = {
     id: ["verify"],
     group: "Lifecycle",
@@ -72,13 +73,7 @@ export const verifySpec = {
                 message: "Exactly one of --ok or --rework must be provided.",
             });
         }
-        if (typeof raw.opts.details === "string" && typeof raw.opts.file === "string") {
-            throw usageError({
-                spec: verifySpec,
-                command: "verify",
-                message: "Options --details and --file are mutually exclusive.",
-            });
-        }
+        validateVerifyDetailsFileExclusive(raw, verifySpec, { command: "verify" });
     },
     parse: (raw) => {
         const ok = raw.opts.ok === true;
@@ -86,11 +81,7 @@ export const verifySpec = {
         return {
             taskId: typeof raw.args["task-id"] === "string" ? raw.args["task-id"] : "",
             state,
-            by: raw.opts.by,
-            note: raw.opts.note,
-            details: raw.opts.details,
-            file: raw.opts.file,
-            quiet: raw.opts.quiet === true,
+            ...parseVerifyCommonOptions(raw),
         };
     },
 };

package/dist/policy/rules/allowlist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../../src/policy/rules/allowlist.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CA0C9D"}
+{"version":3,"file":"allowlist.d.ts","sourceRoot":"","sources":["../../../src/policy/rules/allowlist.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE/D,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CAqD9D"}

package/dist/policy/rules/allowlist.js

@@ -1,12 +1,25 @@
 import { gitPathIsUnderPrefix, normalizeGitPathPrefix } from "../../shared/git-path.js";
+import { protectedPathAllowPrefixes } from "../../shared/protected-paths.js";
 import { gitError, okResult } from "../result.js";
 export function allowlistRule(ctx) {
     const allowRaw = ctx.allow?.prefixes ?? [];
     const staged = ctx.git.stagedPaths ?? [];
+    const allow = allowRaw.map((p) => normalizeGitPathPrefix(p));
+    const protectedAllow = protectedPathAllowPrefixes({
+        tasksPath: ctx.config.paths.tasks_path,
+        workflowDir: ctx.config.paths.workflow_dir,
+        taskId: ctx.taskId,
+        allowTasks: ctx.allow?.allowTasks === true,
+        allowPolicy: ctx.allow?.allowPolicy === true,
+        allowConfig: ctx.allow?.allowConfig === true,
+        allowHooks: ctx.allow?.allowHooks === true,
+        allowCI: ctx.allow?.allowCI === true,
+    });
+    const effectiveAllow = [...new Set([...allow, ...protectedAllow])];
     if (staged.length === 0) {
         return { ok: false, errors: [gitError("No staged files (git index empty)")], warnings: [] };
     }
-    if (allowRaw.length === 0) {
+    if (effectiveAllow.length === 0) {
         const message = ctx.action === "guard_commit" || ctx.action === "commit"
             ? "Provide at least one --allow <path> prefix"
             : "Provide at least one allowlist prefix";
@@ -16,8 +29,7 @@ export function allowlistRule(ctx) {
             warnings: [],
         };
     }
-    const allow = allowRaw.map((p) => normalizeGitPathPrefix(p));
-    if (allow.includes(".")) {
+    if (effectiveAllow.includes(".")) {
         return {
             ok: false,
             errors: [
@@ -28,7 +40,7 @@ export function allowlistRule(ctx) {
     }
     const errors = [];
     for (const filePath of staged) {
-        if (!allow.some((prefix) => gitPathIsUnderPrefix(filePath, prefix))) {
+        if (!effectiveAllow.some((prefix) => gitPathIsUnderPrefix(filePath, prefix))) {
             errors.push(`Staged file is outside allowlist: ${filePath}`);
         }
     }

package/dist/policy/rules/protected-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../../src/policy/rules/protected-paths.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc7E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CAgDnE"}
+{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../../src/policy/rules/protected-paths.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAgB,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAc7E,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,aAAa,GAAG,YAAY,CAqDnE"}

package/dist/policy/rules/protected-paths.js

@@ -18,7 +18,12 @@ export function protectedPathsRule(ctx) {
     const allowCI = ctx.allow?.allowCI === true;
     const errors = [];
     for (const filePath of staged) {
-        const kind = protectedPathKindForFile({ filePath, tasksPath });
+        const kind = protectedPathKindForFile({
+            filePath,
+            tasksPath,
+            workflowDir: ctx.config.paths.workflow_dir,
+            taskId: ctx.taskId,
+        });
         if (!kind)
             continue;
         if (kind === "tasks" && !allowTasks) {

package/dist/ports/task-backend-port.d.ts

@@ -1,8 +1,8 @@
-import type { TaskData } from "../backends/task-backend.js";
+import type { TaskData, TaskWriteOptions } from "../backends/task-backend.js";
 export type TaskBackendPort = {
     listTasks(): Promise<TaskData[]>;
     getTask(id: string): Promise<TaskData | null>;
-    writeTask(task: TaskData): Promise<void>;
+    writeTask(task: TaskData, opts?: TaskWriteOptions): Promise<void>;
     exportProjectionSnapshot(path: string): Promise<void>;
 };
 //# sourceMappingURL=task-backend-port.d.ts.map

package/dist/ports/task-backend-port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-backend-port.d.ts","sourceRoot":"","sources":["../../src/ports/task-backend-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD,CAAC"}
+{"version":3,"file":"task-backend-port.d.ts","sourceRoot":"","sources":["../../src/ports/task-backend-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE9E,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IACjC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAC9C,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD,CAAC"}

package/dist/shared/agent-emoji.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-emoji.d.ts","sourceRoot":"","sources":["../../src/shared/agent-emoji.ts"],"names":[],"mappings":"AAmCA,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB"}
+{"version":3,"file":"agent-emoji.d.ts","sourceRoot":"","sources":["../../src/shared/agent-emoji.ts"],"names":[],"mappings":"AAkCA,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlB"}

package/dist/shared/protected-paths.d.ts

@@ -4,9 +4,26 @@ export type ProtectedPathOverride = {
     cliFlag: string;
     envVar: string;
 };
+export declare function taskArtifactPrefixes(opts: {
+    tasksPath: string;
+    workflowDir?: string;
+    taskId?: string;
+}): string[];
+export declare function protectedPathAllowPrefixes(opts: {
+    tasksPath: string;
+    workflowDir?: string;
+    taskId?: string;
+    allowTasks?: boolean;
+    allowPolicy?: boolean;
+    allowConfig?: boolean;
+    allowHooks?: boolean;
+    allowCI?: boolean;
+}): string[];
 export declare function getProtectedPathOverride(kind: ProtectedPathKind): ProtectedPathOverride;
 export declare function protectedPathKindForFile(opts: {
     filePath: string;
     tasksPath: string;
+    workflowDir?: string;
+    taskId?: string;
 }): ProtectedPathKind | null;
 //# sourceMappingURL=protected-paths.d.ts.map

package/dist/shared/protected-paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../src/shared/protected-paths.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAQF,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,CAkBvF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,iBAAiB,GAAG,IAAI,CA8B3B"}
+{"version":3,"file":"protected-paths.d.ts","sourceRoot":"","sources":["../../src/shared/protected-paths.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,IAAI,CAAC;AAE/E,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAYF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,EAAE,CAOX;AAYD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,MAAM,EAAE,CAkBX;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,iBAAiB,GAAG,qBAAqB,CAkBvF;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,iBAAiB,GAAG,IAAI,CAsC3B"}

package/dist/shared/protected-paths.js

@@ -1,9 +1,53 @@
-function pathIsUnder(candidate, prefix) {
-    if (prefix === "." || prefix === "")
-        return true;
-    if (candidate === prefix)
-        return true;
-    return candidate.startsWith(`${prefix}/`);
+import { gitPathIsUnderPrefix, normalizeGitPathPrefix } from "./git-path.js";
+function taskWorkflowPrefix(workflowDir, taskId) {
+    const dir = normalizeGitPathPrefix(workflowDir ?? "");
+    const id = (taskId ?? "").trim();
+    if (!dir || !id)
+        return null;
+    return normalizeGitPathPrefix(`${dir}/${id}`);
+}
+export function taskArtifactPrefixes(opts) {
+    const out = new Set();
+    const tasksPath = normalizeGitPathPrefix(opts.tasksPath);
+    if (tasksPath)
+        out.add(tasksPath);
+    const workflowPrefix = taskWorkflowPrefix(opts.workflowDir, opts.taskId);
+    if (workflowPrefix)
+        out.add(workflowPrefix);
+    return [...out].toSorted((a, b) => a.localeCompare(b));
+}
+const POLICY_PATH_PREFIXES = [
+    "AGENTS.md",
+    "CLAUDE.md",
+    "packages/agentplane/assets/AGENTS.md",
+    ".agentplane/agents",
+];
+const CONFIG_PATH_PREFIXES = [".agentplane/config.json", ".agentplane/backends"];
+const HOOK_PATH_PREFIXES = ["lefthook.yml"];
+const CI_PATH_PREFIXES = [".github/workflows", ".github/actions"];
+export function protectedPathAllowPrefixes(opts) {
+    const out = new Set();
+    if (opts.allowTasks) {
+        for (const prefix of taskArtifactPrefixes(opts))
+            out.add(prefix);
+    }
+    if (opts.allowPolicy) {
+        for (const prefix of POLICY_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    if (opts.allowConfig) {
+        for (const prefix of CONFIG_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    if (opts.allowHooks) {
+        for (const prefix of HOOK_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    if (opts.allowCI) {
+        for (const prefix of CI_PATH_PREFIXES)
+            out.add(prefix);
+    }
+    return [...out].toSorted((a, b) => a.localeCompare(b));
 }
 export function getProtectedPathOverride(kind) {
     switch (kind) {
@@ -28,24 +72,29 @@ export function protectedPathKindForFile(opts) {
     const p = opts.filePath;
     if (!p)
         return null;
-    if (p === opts.tasksPath)
+    if (taskArtifactPrefixes({
+        tasksPath: opts.tasksPath,
+        workflowDir: opts.workflowDir,
+        taskId: opts.taskId,
+    }).some((prefix) => gitPathIsUnderPrefix(p, prefix))) {
         return "tasks";
+    }
     // "Rules of the game": authoring/agent policies and registry.
     if (p === "AGENTS.md" ||
         p === "CLAUDE.md" ||
         p === "packages/agentplane/assets/AGENTS.md" ||
-        pathIsUnder(p, ".agentplane/agents")) {
+        gitPathIsUnderPrefix(p, ".agentplane/agents")) {
         return "policy";
     }
     // Framework config and task backend config determine enforcement behavior.
-    if (p === ".agentplane/config.json" || pathIsUnder(p, ".agentplane/backends")) {
+    if (p === ".agentplane/config.json" || gitPathIsUnderPrefix(p, ".agentplane/backends")) {
         return "config";
     }
     // Local hook orchestrator is a quality gate for commits.
     if (p === "lefthook.yml")
         return "hooks";
     // CI workflows are "remote hooks" for quality gates.
-    if (pathIsUnder(p, ".github/workflows") || pathIsUnder(p, ".github/actions")) {
+    if (gitPathIsUnderPrefix(p, ".github/workflows") || gitPathIsUnderPrefix(p, ".github/actions")) {
         return "ci";
     }
     return null;

package/dist/shared/repo-cli-version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"repo-cli-version.d.ts","sourceRoot":"","sources":["../../src/shared/repo-cli-version.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,WAAW,GACX,qBAAqB,GACrB,2BAA2B,CAAC;AAEhC,MAAM,MAAM,yBAAyB,GAAG;IACtC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAKjF;AAqBD,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,iBAAiB,GACzB,yBAAyB,CAuC3B"}
+{"version":3,"file":"repo-cli-version.d.ts","sourceRoot":"","sources":["../../src/shared/repo-cli-version.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG7D,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,WAAW,GACX,qBAAqB,GACrB,2BAA2B,CAAC;AAEhC,MAAM,MAAM,yBAAyB,GAAG;IACtC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAKjF;AA8BD,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,iBAAiB,GACzB,yBAAyB,CAuC3B"}

package/dist/shared/repo-cli-version.js

@@ -9,16 +9,22 @@ export function getRepoExpectedCliVersion(config) {
 function buildRecovery(runtime, expectedVersion) {
     switch (runtime.mode) {
         case "global-installed": {
-            return `Run: npm i -g agentplane@${expectedVersion}`;
+            return `Run: npm i -g agentplane@${expectedVersion}. Then verify: agentplane runtime explain`;
         }
         case "global-in-framework":
         case "global-forced-in-framework": {
-            return "Run: scripts/reinstall-global-agentplane.sh";
+            const prefix = runtime.mode === "global-forced-in-framework"
+                ? "Unset AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1 if forced global mode is not intentional. "
+                : "";
+            return (`${prefix}Run: scripts/reinstall-global-agentplane.sh. ` +
+                "Fallback: node packages/agentplane/bin/agentplane.js runtime explain. " +
+                "Then verify: agentplane runtime explain");
         }
         case "repo-local":
         case "repo-local-handoff": {
             return (`Sync this framework checkout to agentplane ${expectedVersion} or lower ` +
-                "framework.cli.expected_version if the repository intentionally targets an older CLI.");
+                "framework.cli.expected_version if the repository intentionally targets an older CLI. " +
+                "Then verify: agentplane runtime explain");
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentplane",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Agent Plane CLI for task workflows, recipes, and project automation.",
   "keywords": [
     "agentplane",
@@ -55,7 +55,7 @@
     "prepublishOnly": "node ../../scripts/enforce-github-publish.mjs && npm run prepack"
   },
   "dependencies": {
-    "@agentplaneorg/core": "0.3.5",
+    "@agentplaneorg/core": "0.3.7",
     "yauzl": "^2.10.0"
   },
   "devDependencies": {