agentplane 0.2.25 → 0.3.1

package/dist/cli/run-cli.js

@@ -15,15 +15,18 @@ import { helpSpec } from "./spec/help.js";
 import { usageError } from "./spec/errors.js";
 import { suggestOne } from "./spec/suggest.js";
 import { COMMANDS } from "./run-cli/command-catalog.js";
+import { getReasonCodeMeta } from "./reason-codes.js";
 const GLOBAL_FLAGS = [
     { key: "help", forms: ["--help", "-h"], takesValue: false, scoped: false },
     { key: "version", forms: ["--version", "-v"], takesValue: false, scoped: false },
     { key: "noUpdateCheck", forms: ["--no-update-check"], takesValue: false, scoped: false },
     { key: "allowNetwork", forms: ["--allow-network"], takesValue: false, scoped: true },
     { key: "jsonErrors", forms: ["--json-errors"], takesValue: false, scoped: true },
+    { key: "outputMode", forms: ["--output"], takesValue: true, scoped: false },
     { key: "root", forms: ["--root"], takesValue: true, scoped: false },
 ];
 const GLOBAL_FLAG_FORMS = new Map(GLOBAL_FLAGS.flatMap((def) => def.forms.map((form) => [form, def])));
+const HELP_TAIL_OPTIONS = new Set(["--compact", "--json"]);
 function prescanJsonErrors(argv) {
     // If parseGlobalArgs throws (e.g. missing --root value), we still want to honor
     // `--json-errors` in the "scoped global" zone (before the command id).
@@ -54,6 +57,7 @@ function parseGlobalArgs(argv) {
     let jsonErrors = false;
     let root;
     let allowNetwork = false;
+    let outputMode;
     const rest = [];
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -103,6 +107,27 @@ function parseGlobalArgs(argv) {
                 i++;
                 break;
             }
+            case "outputMode": {
+                const next = argv[i + 1];
+                if (!next) {
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: "Missing value after --output (expected text|json)",
+                    });
+                }
+                const normalized = next.trim().toLowerCase();
+                if (normalized !== "text" && normalized !== "json") {
+                    throw new CliError({
+                        exitCode: 2,
+                        code: "E_USAGE",
+                        message: `Invalid value for --output: ${next} (expected text|json)`,
+                    });
+                }
+                outputMode = normalized;
+                i++;
+                break;
+            }
             default: {
                 // Exhaustive by construction; keep a defensive fallback.
                 rest.push(arg);
@@ -110,7 +135,85 @@ function parseGlobalArgs(argv) {
             }
         }
     }
-    return { globals: { help, version, noUpdateCheck, root, jsonErrors, allowNetwork }, rest };
+    return {
+        globals: { help, version, noUpdateCheck, root, jsonErrors, allowNetwork, outputMode },
+        rest,
+    };
+}
+const OUTPUT_MODE_ENV = "AGENTPLANE_OUTPUT";
+function resolveOutputMode(modeFromFlag) {
+    if (modeFromFlag)
+        return modeFromFlag;
+    const fromEnv = process.env[OUTPUT_MODE_ENV]?.trim().toLowerCase();
+    if (!fromEnv || fromEnv === "text")
+        return "text";
+    if (fromEnv === "json")
+        return "json";
+    throw new CliError({
+        exitCode: 2,
+        code: "E_USAGE",
+        message: `Invalid ${OUTPUT_MODE_ENV}: ${fromEnv} (expected text|json)`,
+    });
+}
+function chunkToString(chunk, encoding) {
+    if (typeof chunk === "string")
+        return chunk;
+    if (chunk instanceof Uint8Array)
+        return Buffer.from(chunk).toString(encoding);
+    return String(chunk);
+}
+async function runWithOutputMode(opts) {
+    if (opts.mode === "text")
+        return await opts.run();
+    const stdoutWrite = process.stdout.write.bind(process.stdout);
+    const stderrWrite = process.stderr.write.bind(process.stderr);
+    let stdout = "";
+    let stderr = "";
+    process.stdout.write = ((chunk, ...rest) => {
+        const encoding = typeof rest[0] === "string" ? rest[0] : undefined;
+        stdout += chunkToString(chunk, encoding);
+        const callback = rest.find((item) => typeof item === "function");
+        callback?.(null);
+        return true;
+    });
+    process.stderr.write = ((chunk, ...rest) => {
+        const encoding = typeof rest[0] === "string" ? rest[0] : undefined;
+        stderr += chunkToString(chunk, encoding);
+        const callback = rest.find((item) => typeof item === "function");
+        callback?.(null);
+        return true;
+    });
+    try {
+        const exitCode = await opts.run();
+        let parsed;
+        const trimmedStdout = stdout.trim();
+        if (trimmedStdout.length > 0) {
+            try {
+                parsed = JSON.parse(trimmedStdout);
+            }
+            catch {
+                parsed = undefined;
+            }
+        }
+        const payload = {
+            schema_version: 1,
+            mode: "agent_json_v1",
+            command: opts.command,
+            ok: exitCode === 0,
+            exit_code: exitCode,
+            stdout: trimmedStdout,
+            stderr: stderr.trim(),
+        };
+        if (parsed !== undefined) {
+            payload.data = parsed;
+        }
+        stdoutWrite(`${JSON.stringify(payload, null, 2)}\n`);
+        return exitCode;
+    }
+    finally {
+        process.stdout.write = stdoutWrite;
+        process.stderr.write = stderrWrite;
+    }
 }
 function matchCommandCatalog(tokens) {
     let best = null;
@@ -135,8 +238,15 @@ function matchCommandCatalog(tokens) {
 }
 function writeError(err, jsonErrors) {
     const guidance = resolveErrorGuidance(err);
+    const contextReasonCode = typeof err.context?.reason_code === "string" ? String(err.context.reason_code) : undefined;
+    const reasonCode = contextReasonCode ?? guidance.nextAction?.reasonCode;
+    const reasonDecode = getReasonCodeMeta(reasonCode);
     if (jsonErrors) {
-        process.stdout.write(`${formatJsonError(err, { hint: guidance.hint, nextAction: guidance.nextAction })}\n`);
+        process.stdout.write(`${formatJsonError(err, {
+            hint: guidance.hint,
+            nextAction: guidance.nextAction,
+            reasonDecode,
+        })}\n`);
     }
     else {
         const header = `error [${err.code}]`;
@@ -152,6 +262,10 @@ function writeError(err, jsonErrors) {
         if (guidance.nextAction) {
             process.stderr.write(`next_action: ${guidance.nextAction.command} (${guidance.nextAction.reason})\n`);
         }
+        if (reasonDecode) {
+            process.stderr.write(`reason_code: ${reasonDecode.code} [${reasonDecode.category}] ${reasonDecode.summary}\n`);
+            process.stderr.write(`reason_action: ${reasonDecode.action}\n`);
+        }
     }
 }
 const AGENTPLANE_HOME_ENV = "AGENTPLANE_HOME";
@@ -163,9 +277,20 @@ function resolveAgentplaneHome() {
 }
 function resolveErrorGuidance(err) {
     const command = typeof err.context?.command === "string" ? err.context.command : undefined;
+    const reasonCode = typeof err.context?.reason_code === "string" ? String(err.context.reason_code) : undefined;
     const usage = command ? `agentplane help ${command} --compact` : "agentplane help";
     switch (err.code) {
         case "E_USAGE": {
+            if (reasonCode === "sync_backend_mismatch") {
+                return {
+                    hint: "Configured backend id mismatch. Check active backend and retry with a matching id.",
+                    nextAction: {
+                        command: "agentplane config show",
+                        reason: "inspect active backend id before running sync",
+                        reasonCode: "sync_backend_mismatch",
+                    },
+                };
+            }
             return {
                 hint: `See \`${usage}\` for usage.`,
                 nextAction: {
@@ -176,6 +301,16 @@ function resolveErrorGuidance(err) {
             };
         }
         case "E_GIT": {
+            if (reasonCode === "reconcile_git_state_unreadable") {
+                return {
+                    hint: "Reconcile check could not read git state.",
+                    nextAction: {
+                        command: "git status --short --untracked-files=no",
+                        reason: "confirm repository state is readable before mutating commands",
+                        reasonCode: "reconcile_git_state_unreadable",
+                    },
+                };
+            }
             if (command?.startsWith("branch")) {
                 return {
                     hint: "Check git repo/branch; run `git branch` or pass --root <path>.",
@@ -236,6 +371,17 @@ function resolveErrorGuidance(err) {
             };
         }
         case "E_VALIDATION": {
+            if (reasonCode === "reconcile_task_scan_failed" ||
+                reasonCode === "reconcile_task_scan_incomplete") {
+                return {
+                    hint: "Reconcile check failed due to task scan drift or parse/read errors.",
+                    nextAction: {
+                        command: "agentplane task list --strict-read",
+                        reason: "surface task scan/read failures before retrying mutating commands",
+                        reasonCode: reasonCode,
+                    },
+                };
+            }
             return {
                 hint: "Fix invalid config/input shape and rerun.",
                 nextAction: {
@@ -361,10 +507,17 @@ export async function runCli(argv) {
     let jsonErrors = prescanJsonErrors(argv);
     try {
         const { globals, rest } = parseGlobalArgs(argv);
-        jsonErrors = globals.jsonErrors;
+        const outputMode = resolveOutputMode(globals.outputMode);
+        jsonErrors = globals.jsonErrors || outputMode === "json";
         if (globals.version) {
-            process.stdout.write(`${getVersion()}\n`);
-            return 0;
+            return await runWithOutputMode({
+                mode: outputMode,
+                command: "version",
+                run: () => {
+                    process.stdout.write(`${getVersion()}\n`);
+                    return Promise.resolve(0);
+                },
+            });
         }
         const runCli2HelpFast = async (helpArgv) => {
             const { buildRegistry } = await import("./run-cli/registry.run.js");
@@ -384,12 +537,42 @@ export async function runCli(argv) {
             }
             const tail = helpArgv.slice(match.consumed);
             const parsed = parseCommandArgv(match.spec, tail).parsed;
-            return await match.handler({ cwd: process.cwd(), rootOverride: globals.root }, parsed);
+            return await runWithOutputMode({
+                mode: outputMode,
+                command: match.spec.id.join(" "),
+                run: async () => {
+                    return await match.handler({ cwd: process.cwd(), rootOverride: globals.root }, parsed);
+                },
+            });
         };
         // `--help` is treated as an alias for `help` and supports per-command help:
         // - agentplane --help
         // - agentplane <cmd...> --help [--compact|--json]
         if (globals.help) {
+            const matchedHelp = matchCommandCatalog(rest);
+            if (matchedHelp) {
+                const rawHelpTail = rest.slice(matchedHelp.consumed);
+                const commandFlags = new Set();
+                for (const opt of matchedHelp.entry.spec.options ?? []) {
+                    const optRecord = opt;
+                    const long = typeof optRecord.name === "string" ? optRecord.name.trim() : "";
+                    if (long)
+                        commandFlags.add(`--${long}`);
+                    const short = typeof optRecord.alias === "string" ? optRecord.alias.trim() : "";
+                    if (short)
+                        commandFlags.add(`-${short}`);
+                }
+                const invalidHelpTail = rawHelpTail.filter((token) => token.startsWith("-") && !HELP_TAIL_OPTIONS.has(token) && !commandFlags.has(token));
+                if (invalidHelpTail.length > 0) {
+                    throw usageError({
+                        spec: helpSpec,
+                        command: "help",
+                        message: `Unsupported flag(s) after --help: ${invalidHelpTail.join(", ")}.`,
+                    });
+                }
+                const helpTail = rawHelpTail.filter((token) => token.startsWith("-") && HELP_TAIL_OPTIONS.has(token));
+                return await runCli2HelpFast(["help", ...matchedHelp.entry.spec.id, ...helpTail]);
+            }
             return await runCli2HelpFast(["help", ...rest]);
         }
         if (rest.length === 0) {
@@ -451,7 +634,7 @@ export async function runCli(argv) {
         await maybeWarnOnUpdate({
             currentVersion: getVersion(),
             skip: globals.noUpdateCheck || skipUpdateCheckForPolicy || matched?.entry.needsConfig === false,
-            jsonErrors: globals.jsonErrors,
+            jsonErrors,
         });
         let ctxPromise = null;
         const getCtx = async (commandForErrorContext) => {
@@ -493,7 +676,11 @@ export async function runCli(argv) {
         if (match) {
             const tail = rest.slice(match.consumed);
             const parsed = parseCommandArgv(match.spec, tail).parsed;
-            return await match.handler({ cwd, rootOverride: globals.root }, parsed);
+            return await runWithOutputMode({
+                mode: outputMode,
+                command: match.spec.id.join(" "),
+                run: async () => await match.handler({ cwd, rootOverride: globals.root }, parsed),
+            });
         }
         const input = rest.join(" ");
         const fullCandidates = registry.list().map((e) => e.spec.id.join(" "));

package/dist/commands/backend/sync.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.command.d.ts","sourceRoot":"","sources":["../../../src/commands/backend/sync.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7E,KAAK,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,iBAAiB,CAQtD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAuC1D,CAAC;AAEF,iBAAS,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,8BAEtF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC1E,KAAK,UAAU,EAAE,GAAG,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,CAStE"}
+{"version":3,"file":"sync.command.d.ts","sourceRoot":"","sources":["../../../src/commands/backend/sync.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAItE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAwB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAE7E,KAAK,iBAAiB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3C,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,iBAAiB,CAQtD,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CAuC1D,CAAC;AAEF,iBAAS,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAUpF;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,8BAEtF;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,IAC1E,KAAK,UAAU,EAAE,GAAG,iBAAiB,KAAG,OAAO,CAAC,MAAM,CAAC,CAStE"}

package/dist/commands/backend/sync.command.js

@@ -1,3 +1,4 @@
+import { COMMAND_SNIPPETS } from "../../cli/command-snippets.js";
 import { usageError } from "../../cli/spec/errors.js";
 import { suggestOne } from "../../cli/spec/suggest.js";
 import { cmdBackendSyncParsed } from "../backend.js";
@@ -7,7 +8,7 @@ export const backendSpec = {
     summary: "Backend-related operations.",
     description: "This is a command group. Use a subcommand such as `agentplane backend sync ...`.",
     args: [{ name: "cmd", required: false, variadic: true, valueHint: "<cmd>" }],
-    examples: [{ cmd: "agentplane backend sync local --direction pull", why: "Sync the backend." }],
+    examples: [{ cmd: COMMAND_SNIPPETS.backendSync.pullLocal, why: "Sync the backend." }],
     parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
 };
 export const backendSyncSpec = {
@@ -21,8 +22,8 @@ export const backendSyncSpec = {
             name: "direction",
             valueHint: "<push|pull>",
             choices: ["push", "pull"],
-            required: true,
-            description: "Sync direction.",
+            default: "push",
+            description: "Sync direction (default: push).",
         },
         {
             kind: "string",
@@ -36,15 +37,15 @@ export const backendSyncSpec = {
         { kind: "boolean", name: "quiet", default: false, description: "Reduce output noise." },
     ],
     examples: [
-        { cmd: "agentplane backend sync local --direction pull", why: "Pull from backend." },
+        { cmd: COMMAND_SNIPPETS.backendSync.pullLocal, why: "Pull from backend." },
         {
-            cmd: "agentplane backend sync redmine --direction push --yes",
+            cmd: COMMAND_SNIPPETS.backendSync.pushRedmineWithYes,
             why: "Push to a networked backend with explicit approval.",
         },
     ],
     parse: (raw) => ({
         backendId: String(raw.args.id),
-        direction: raw.opts.direction,
+        direction: (raw.opts.direction ?? "push"),
         conflict: (raw.opts.conflict ?? "diff"),
         yes: raw.opts.yes === true,
         quiet: raw.opts.quiet === true,

package/dist/commands/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAGnF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwClB"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/commands/backend.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAGnF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,eAAe,GAAG,MAAM,CAAC;IAC7D,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyClB"}

package/dist/commands/backend.js

@@ -15,6 +15,7 @@ export async function cmdBackendSyncParsed(opts) {
                 exitCode: 2,
                 code: "E_USAGE",
                 message: `Configured backend is "${backendId}", not "${opts.flags.backendId}"`,
+                context: { command: "backend sync", reason_code: "sync_backend_mismatch" },
             });
         }
         if (!backend.sync) {
@@ -57,6 +58,7 @@ export async function cmdSyncParsed(opts) {
                 exitCode: 2,
                 code: "E_USAGE",
                 message: `Configured backend is "${backendId}", not "${opts.flags.backendId}"`,
+                context: { command: "sync", reason_code: "sync_backend_mismatch" },
             });
         }
         if (!backend.sync) {

package/dist/commands/doctor.run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.run.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.run.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAK1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAsPrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAwBlD,CAAC"}
+{"version":3,"file":"doctor.run.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.run.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAM1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAyUrD,eAAO,MAAM,SAAS,EAAE,cAAc,CAAC,YAAY,CAmDlD,CAAC"}

package/dist/commands/doctor.run.js

@@ -3,8 +3,10 @@ import path from "node:path";
 import { resolveProject } from "@agentplaneorg/core";
 import { warnMessage, successMessage } from "../cli/output.js";
 import { RUNTIME_GITIGNORE_LINES } from "../shared/runtime-artifacts.js";
+import { resolvePolicyGatewayForRepo } from "../shared/policy-gateway.js";
 import { execFileAsync, gitEnv } from "./shared/git.js";
 import { loadCommandContext } from "./shared/task-backend.js";
+import { emitWorkflowEvent, isWorkflowEnforcementDisabled, resolveWorkflowPaths, safeAutofixWorkflowText, validateWorkflowAtPath, workflowEnforcementEnvHint, } from "../workflow-runtime/index.js";
 async function listTsFiles(rootDir) {
     const out = [];
     async function walk(absDir) {
@@ -57,15 +59,19 @@ async function isDirectory(absPath) {
 }
 async function checkWorkspace(repoRoot) {
     const problems = [];
-    const requiredFiles = [
-        path.join(repoRoot, "AGENTS.md"),
-        path.join(repoRoot, ".agentplane", "config.json"),
-    ];
+    const requiredFiles = [path.join(repoRoot, ".agentplane", "config.json")];
     for (const filePath of requiredFiles) {
         if (!(await pathExists(filePath))) {
             problems.push(`Missing required file: ${path.relative(repoRoot, filePath)}`);
         }
     }
+    const gateway = await resolvePolicyGatewayForRepo({
+        gitRoot: repoRoot,
+        fallbackFlavor: "codex",
+    });
+    if (!(await pathExists(gateway.absPath))) {
+        problems.push("Missing required policy gateway file: AGENTS.md or CLAUDE.md");
+    }
     const agentsDir = path.join(repoRoot, ".agentplane", "agents");
     if (!(await isDirectory(agentsDir))) {
         problems.push("Missing required directory: .agentplane/agents");
@@ -160,6 +166,75 @@ async function safeFixTaskIndex(repoRoot) {
         return { changed: false, note: "Skip: could not rebuild tasks index cache." };
     }
 }
+async function checkWorkflowContract(repoRoot) {
+    const result = await validateWorkflowAtPath(repoRoot);
+    const findings = result.diagnostics.map((d) => `[${d.severity}] ${d.code} ${d.path}: ${d.message}`);
+    emitWorkflowEvent({
+        event: "workflow_doctor_check",
+        details: { ok: result.ok, findings: result.diagnostics.length },
+    });
+    return findings;
+}
+function findingSeverity(problem) {
+    const normalized = problem.trimStart();
+    if (normalized.startsWith("[WARN]"))
+        return "WARN";
+    if (normalized.startsWith("[INFO]"))
+        return "INFO";
+    if (normalized.startsWith("[ERROR]"))
+        return "ERROR";
+    return "ERROR";
+}
+async function safeFixWorkflow(repoRoot) {
+    const paths = resolveWorkflowPaths(repoRoot);
+    let current = "";
+    let sourcePath = paths.workflowPath;
+    try {
+        current = await fs.readFile(paths.workflowPath, "utf8");
+    }
+    catch {
+        try {
+            current = await fs.readFile(paths.legacyWorkflowPath, "utf8");
+            sourcePath = paths.legacyWorkflowPath;
+        }
+        catch {
+            return { changed: false, note: "Skip: workflow contract file not found." };
+        }
+    }
+    const fixed = safeAutofixWorkflowText(current);
+    if (fixed.diagnostics.some((d) => d.code === "WF_FIX_SKIPPED_UNSAFE")) {
+        const details = fixed.diagnostics.map((d) => `${d.path}`).join(", ");
+        return {
+            changed: false,
+            note: `Skip: unsafe workflow autofix required (unknown keys). Proposed manual review: ${details}`,
+        };
+    }
+    if (!fixed.changed) {
+        if (sourcePath === paths.workflowPath) {
+            return { changed: false, note: "OK: workflow contract already normalized." };
+        }
+        await fs.mkdir(path.dirname(paths.workflowPath), { recursive: true });
+        await fs.writeFile(paths.workflowPath, current, "utf8");
+        await fs.rm(paths.legacyWorkflowPath, { force: true });
+        await fs.mkdir(paths.workflowDir, { recursive: true });
+        await fs.copyFile(paths.workflowPath, paths.lastKnownGoodPath);
+        return {
+            changed: true,
+            note: "Fixed: moved legacy WORKFLOW.md into .agentplane and refreshed last-known-good.",
+        };
+    }
+    await fs.mkdir(path.dirname(paths.workflowPath), { recursive: true });
+    await fs.writeFile(paths.workflowPath, fixed.text, "utf8");
+    if (sourcePath === paths.legacyWorkflowPath) {
+        await fs.rm(paths.legacyWorkflowPath, { force: true });
+    }
+    await fs.mkdir(paths.workflowDir, { recursive: true });
+    await fs.copyFile(paths.workflowPath, paths.lastKnownGoodPath);
+    return {
+        changed: true,
+        note: "Fixed: normalized workflow contract and refreshed last-known-good.",
+    };
+}
 async function checkDoneTaskCommitInvariants(repoRoot) {
     const tasksPath = path.join(repoRoot, ".agentplane", "tasks.json");
     let raw = "";
@@ -216,11 +291,11 @@ async function checkDoneTaskCommitInvariants(repoRoot) {
             continue;
         const subject = subjectByHash.get(hash) ?? "";
         if (!subject) {
-            problems.push(`DONE task references unknown commit hash: ${id} -> ${hash}`);
+            problems.push(`[WARN] DONE task references unknown commit hash: ${id} -> ${hash}`);
             continue;
         }
         if (/\bclose:/iu.test(subject)) {
-            problems.push(`DONE task implementation commit points to a close commit: ${id} -> ${hash} (${subject})`);
+            problems.push(`[WARN] DONE task implementation commit points to a close commit: ${id} -> ${hash} (${subject})`);
         }
     }
     return problems;
@@ -228,22 +303,38 @@ async function checkDoneTaskCommitInvariants(repoRoot) {
 export const runDoctor = async (ctx, p) => {
     const resolved = await resolveProject({ cwd: ctx.cwd, rootOverride: ctx.rootOverride ?? null });
     const repoRoot = resolved.gitRoot;
-    const problems = await checkWorkspace(repoRoot);
-    problems.push(...(await checkDoneTaskCommitInvariants(repoRoot)));
-    if (p.dev) {
-        problems.push(...(await checkLayering(repoRoot)));
-    }
-    if (problems.length > 0) {
-        console.error(warnMessage(`doctor found ${problems.length} problem(s):`));
-        for (const prob of problems)
-            console.error(`- ${prob}`);
-        return 1;
+    const runChecks = async () => {
+        const checks = await checkWorkspace(repoRoot);
+        checks.push(...(await checkDoneTaskCommitInvariants(repoRoot)));
+        if (!isWorkflowEnforcementDisabled()) {
+            checks.push(...(await checkWorkflowContract(repoRoot)));
+        }
+        if (p.dev) {
+            checks.push(...(await checkLayering(repoRoot)));
+        }
+        return checks;
+    };
+    if (isWorkflowEnforcementDisabled()) {
+        console.log(successMessage("doctor", undefined, `workflow contract checks disabled via ${workflowEnforcementEnvHint()}.`));
     }
     if (p.fix) {
         const fix = await safeFixGitignore(repoRoot);
         console.log(successMessage("doctor fix", undefined, fix.note));
         const idx = await safeFixTaskIndex(repoRoot);
         console.log(successMessage("doctor fix", undefined, idx.note));
+        const workflowFix = await safeFixWorkflow(repoRoot);
+        console.log(successMessage("doctor fix", undefined, workflowFix.note));
+    }
+    const problems = await runChecks();
+    const errors = problems.filter((problem) => findingSeverity(problem) === "ERROR");
+    if (problems.length > 0) {
+        const warningCount = problems.filter((problem) => findingSeverity(problem) === "WARN").length;
+        const infoCount = problems.filter((problem) => findingSeverity(problem) === "INFO").length;
+        console.error(warnMessage(`doctor findings: errors=${errors.length} warnings=${warningCount} info=${infoCount}`));
+        for (const prob of problems)
+            console.error(`- ${prob}`);
+        if (errors.length > 0)
+            return 1;
     }
     console.log(successMessage("doctor", undefined, "OK"));
     return 0;

package/dist/commands/guard/impl/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commands.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAOvF,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAyDxE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAS9E;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgJlB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/guard/impl/commands.ts"],"names":[],"mappings":"AAGA,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAQvF,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAyDxE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsBlB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAa9E;AAED,wBAAsB,SAAS,CAAC,IAAI,EAAE;IACpC,GAAG,CAAC,EAAE,cAAc,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;IACf,kBAAkB,EAAE,OAAO,CAAC;IAC5B,cAAc,EAAE,OAAO,CAAC;CACzB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmJlB"}

package/dist/commands/guard/impl/commands.js

@@ -4,6 +4,7 @@ import { CliError } from "../../../shared/errors.js";
 import { loadCommandContext } from "../../shared/task-backend.js";
 import { loadTaskFromContext } from "../../shared/task-backend.js";
 import { execFileAsync, gitEnv } from "../../shared/git.js";
+import { ensureReconciledBeforeMutation } from "../../shared/reconcile-check.js";
 import { suggestAllowPrefixes } from "./allow.js";
 import { buildCloseCommitMessage, taskReadmePathForTask } from "./close-message.js";
 import { buildGitCommitEnv } from "./env.js";
@@ -111,7 +112,10 @@ export async function cmdGuardSuggestAllow(opts) {
 }
 export async function cmdGuardCommit(opts) {
     try {
-        await guardCommitCheck(opts);
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        await ensureReconciledBeforeMutation({ ctx, command: "guard commit" });
+        await guardCommitCheck({ ...opts, ctx });
         if (!opts.quiet)
             process.stdout.write("OK\n");
         return 0;
@@ -124,9 +128,12 @@ export async function cmdGuardCommit(opts) {
 }
 export async function cmdCommit(opts) {
     try {
+        const ctx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
         if (opts.close) {
-            const ctx = opts.ctx ??
-                (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+            if (!opts.closeCheckOnly) {
+                await ensureReconciledBeforeMutation({ ctx, command: "commit" });
+            }
             // Make the close commit deterministic: start from a clean index unless --unstage-others is used.
             let staged = await ctx.git.statusStagedPaths();
             if (staged.length > 0 && opts.closeUnstageOthers) {
@@ -208,8 +215,9 @@ export async function cmdCommit(opts) {
                 message: "--auto-allow is disabled; pass explicit --allow <path-prefix>.",
             });
         }
+        await ensureReconciledBeforeMutation({ ctx, command: "commit" });
         await guardCommitCheck({
-            ctx: opts.ctx,
+            ctx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             taskId: opts.taskId,
@@ -224,8 +232,6 @@ export async function cmdCommit(opts) {
             requireClean: opts.requireClean,
             quiet: opts.quiet,
         });
-        const ctx = opts.ctx ??
-            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
         const env = buildGitCommitEnv({
             taskId: opts.taskId,
             allowTasks: opts.allowTasks,

package/dist/commands/recipes/impl/commands/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/install.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAM3E,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,GAAG,EAAE,OAAO,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CAkMlB"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/install.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAM3E,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,kBAAkB,CAAC;IAC/B,GAAG,EAAE,OAAO,CAAC;CACd,GAAG,OAAO,CAAC,MAAM,CAAC,CA6NlB"}