agentplane 0.2.19 → 0.2.21

package/assets/AGENTS.md

@@ -425,7 +425,7 @@ If config sets `agents.approvals.require_plan=true`:
 - `## Verify Steps` is the **ex-ante verification contract**: instructions and pass criteria addressed to the verifier.
 - `## Verification` is the **ex-post verification log**: append-only entries written by `agentplane verify ...`.
 - Do not hand-edit `## Verification` entries. Treat them as audit records.
-- For tasks with verify-required tags (default: `code`, `backend`, `frontend`) and for `spike`, `agentplane task plan approve`
+- For tasks with verify-required primary tags (default: `code`, `data`, `ops`) and for `spike`, `agentplane task plan approve`
   will block until `## Verify Steps` is filled (the placeholder `<!-- TODO: FILL VERIFY STEPS -->` is treated as empty).
 - Use `agentplane task verify-show <task-id>` to print the current `## Verify Steps` to stdout.
 
@@ -471,8 +471,9 @@ Use comment-driven flags (where supported by agentplane), e.g.:
 
 In this mode:
 
-- agentplane builds the commit subject as `<emoji> <suffix> <scope>: <summary>` from the status/finish body.
-- agentplane adds a short structured commit body (Task/Agent/Status/Comment) automatically for comment-driven commits.
+- agentplane builds the commit subject as `<emoji> <suffix> <primary>: <status>` for major transitions only.
+- major transitions for status/comment-driven commits: `TODO->DOING`, `DOING->BLOCKED`, `BLOCKED->DOING`, `DOING->DONE`.
+- agentplane adds a short structured commit body (`Task` / `Primary` / `Status` / `Comment`) automatically for comment-driven commits.
 
 ## Commit subject format (enforced)
 

package/bin/agentplane.js

@@ -12,6 +12,29 @@ async function exists(p) {
   }
 }
 
+async function maybeWarnGlobalBinaryInRepoCheckout() {
+  const cwd = process.cwd();
+  const repoCli = path.join(cwd, "packages", "agentplane", "src", "cli.ts");
+  const repoBin = path.join(cwd, "packages", "agentplane", "bin", "agentplane.js");
+  if (!(await exists(repoCli)) || !(await exists(repoBin))) return;
+
+  const thisBin = fileURLToPath(import.meta.url);
+  const normalizedThis = path.resolve(thisBin);
+  const normalizedRepo = path.resolve(repoBin);
+  if (normalizedThis === normalizedRepo) return;
+
+  process.stderr.write(
+    "warning: running global agentplane binary inside repository checkout.\n" +
+      "using global binary: " +
+      normalizedThis +
+      "\n" +
+      "expected local binary: " +
+      normalizedRepo +
+      "\n" +
+      "tip: run `node packages/agentplane/bin/agentplane.js ...` for repo-local changes.\n",
+  );
+}
+
 function isTestLikePath(absPath) {
   // The repo build does not emit test files to dist. If we treat test mtimes as
   // "src is newer than dist", we can block normal commits that only change tests.
@@ -106,5 +129,6 @@ async function assertDistUpToDate() {
   return true;
 }
 
+await maybeWarnGlobalBinaryInRepoCheckout();
 const ok = await assertDistUpToDate();
 if (ok) await import("../dist/cli.js");

package/dist/backends/task-backend/load.d.ts

@@ -3,6 +3,8 @@ import { type TaskBackend } from "./shared.js";
 export declare function loadTaskBackend(opts: {
     cwd: string;
     rootOverride?: string | null;
+    resolvedProject?: ResolvedProject;
+    config?: AgentplaneConfig;
 }): Promise<{
     backend: TaskBackend;
     backendId: string;

package/dist/backends/task-backend/load.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/load.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AA0C7D,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC,CAuBD"}
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/load.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAAgB,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAuF7D,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,gBAAgB,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC,CAUD"}

package/dist/backends/task-backend/load.js

@@ -18,6 +18,37 @@ async function loadBackendConfig(configPath) {
         throw err;
     }
 }
+async function instantiateTaskBackend(opts) {
+    const backendConfigPath = path.join(opts.resolved.gitRoot, opts.config.tasks_backend.config_path);
+    const backendConfig = await loadBackendConfig(backendConfigPath);
+    const normalized = normalizeBackendConfig(backendConfig);
+    const backendId = normalized.id;
+    const settings = normalized.settings;
+    if (backendId === "redmine") {
+        await loadDotEnv(opts.resolved.gitRoot);
+        const cacheDirRaw = resolveMaybeRelative(opts.resolved.gitRoot, settings.cache_dir);
+        const cacheDir = cacheDirRaw ?? path.join(opts.resolved.gitRoot, opts.config.paths.workflow_dir);
+        const cache = cacheDir ? new LocalBackend({ dir: cacheDir }) : null;
+        const redmine = new RedmineBackend(settings, { cache });
+        return {
+            backend: redmine,
+            backendId,
+            resolved: opts.resolved,
+            config: opts.config,
+            backendConfigPath,
+        };
+    }
+    const localDir = resolveMaybeRelative(opts.resolved.gitRoot, settings.dir) ??
+        path.join(opts.resolved.gitRoot, opts.config.paths.workflow_dir);
+    const local = new LocalBackend({ dir: localDir });
+    return {
+        backend: local,
+        backendId: "local",
+        resolved: opts.resolved,
+        config: opts.config,
+        backendConfigPath,
+    };
+}
 function resolveMaybeRelative(root, input) {
     if (!input)
         return null;
@@ -36,23 +67,12 @@ function normalizeBackendConfig(raw) {
     return { id, version, settings };
 }
 export async function loadTaskBackend(opts) {
-    const resolved = await resolveProject({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
-    const loaded = await loadConfig(resolved.agentplaneDir);
-    const backendConfigPath = path.join(resolved.gitRoot, loaded.config.tasks_backend.config_path);
-    const backendConfig = await loadBackendConfig(backendConfigPath);
-    const normalized = normalizeBackendConfig(backendConfig);
-    const backendId = normalized.id;
-    const settings = normalized.settings;
-    if (backendId === "redmine") {
-        await loadDotEnv(resolved.gitRoot);
-        const cacheDirRaw = resolveMaybeRelative(resolved.gitRoot, settings.cache_dir);
-        const cacheDir = cacheDirRaw ?? path.join(resolved.gitRoot, loaded.config.paths.workflow_dir);
-        const cache = cacheDir ? new LocalBackend({ dir: cacheDir }) : null;
-        const redmine = new RedmineBackend(settings, { cache });
-        return { backend: redmine, backendId, resolved, config: loaded.config, backendConfigPath };
+    const resolved = opts.resolvedProject ??
+        (await resolveProject({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+    if (opts.config) {
+        return await instantiateTaskBackend({ resolved, config: opts.config });
     }
-    const localDir = resolveMaybeRelative(resolved.gitRoot, settings.dir) ??
-        path.join(resolved.gitRoot, loaded.config.paths.workflow_dir);
-    const local = new LocalBackend({ dir: localDir });
-    return { backend: local, backendId: "local", resolved, config: loaded.config, backendConfigPath };
+    const loadedConfig = await loadConfig(resolved.agentplaneDir);
+    const config = loadedConfig.config;
+    return await instantiateTaskBackend({ resolved, config });
 }

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":"AA+LA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA6EzC"}
+{"version":3,"file":"command-guide.d.ts","sourceRoot":"","sources":["../../src/cli/command-guide.ts"],"names":[],"mappings":"AAgMA,wBAAgB,SAAS,IAAI,MAAM,EAAE,CAEpC;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzD;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CA8EzC"}

package/dist/cli/command-guide.js

@@ -57,11 +57,11 @@ const CHEAT_SHEET_ROWS = [
     },
     {
         operation: "INTEGRATOR: finish task(s)",
-        command: '`agentplane finish <task-id> [<task-id> ...] --commit <git-rev> --author INTEGRATOR --body "Verified: ..." [--result "<one line>"]`',
+        command: '`agentplane finish <task-id> [<task-id> ...] --commit <git-rev> --author INTEGRATOR --body "Verified: ..." [--result "<one line>"] [--close-commit] [--close-unstage-others]`',
     },
     {
         operation: "INTEGRATOR: commit closure",
-        command: "`agentplane commit <task-id> --close`",
+        command: "Preferred: `agentplane finish <task-id> --close-commit` (single command). Legacy/manual: `agentplane commit <task-id> --close [--check-only] [--unstage-others]` / duplicate no-op close: `agentplane task close-duplicate <task-id> --of <canonical-task-id> --author <ROLE>`",
     },
 ];
 const ROLE_GUIDES = [
@@ -82,7 +82,7 @@ const ROLE_GUIDES = [
             '- Update tasks: `agentplane task update <task-id> --title "..." --description "..." --priority med --owner <ROLE> --depends-on <task-id>`',
             "- Scaffold artifacts: `agentplane task scaffold <task-id>`",
             '- Plan lifecycle: `agentplane task plan set <task-id> --text "..." --updated-by <ROLE>` -> `agentplane task plan approve <task-id> --by <id>`',
-            "- Verify Steps discipline: if a task has verify-required tags (default: code/backend/frontend), fill `## Verify Steps` before plan approval.",
+            "- Verify Steps discipline: if a task primary tag is verify-required (default: code/data/ops), fill `## Verify Steps` before plan approval.",
             '- Task docs (when planning needs it): `agentplane task doc set <task-id> --section Summary --text "..."`',
         ],
     },
@@ -95,7 +95,7 @@ const ROLE_GUIDES = [
             "- Verify Steps: `agentplane task verify-show <task-id>` (use as the verification contract before recording results).",
             '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
             '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / close: `agentplane commit <task-id> --close`',
+            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
         ],
     },
     {
@@ -107,7 +107,7 @@ const ROLE_GUIDES = [
             "- Verify Steps: `agentplane task verify-show <task-id>` (treat as the verification contract).",
             '- Verify: `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
             '- PR artifacts (branch_pr): `agentplane pr open <task-id> --branch task/<task-id>/<slug> --author <ROLE>` / `agentplane pr update <task-id>` / `agentplane pr note <task-id> --author <ROLE> --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / close: `agentplane commit <task-id> --close`',
+            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
         ],
     },
     {
@@ -115,7 +115,7 @@ const ROLE_GUIDES = [
         lines: [
             '- Task docs: `agentplane task doc set <task-id> --section Summary --text "..."` (repeat per section or use `--file`)',
             '- PR notes: `agentplane pr note <task-id> --author DOCS --body "..."`',
-            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / close: `agentplane commit <task-id> --close`',
+            '- Commit: `agentplane guard commit <task-id> -m "<emoji> <suffix> <scope>: <summary>"` / `agentplane commit <task-id> -m "<emoji> <suffix> <scope>: <summary>" --allow <path-prefix>` / preferred close path: `agentplane finish <task-id> --close-commit [--close-unstage-others]`',
         ],
     },
     {
@@ -128,8 +128,8 @@ const ROLE_GUIDES = [
     {
         role: "INTEGRATOR",
         lines: [
-            '- branch_pr: `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: ..."`',
-            '- direct: task owner uses `agentplane finish <task-id> --commit <git-rev> --author <OWNER> --body "Verified: ..."` after the implementation commit',
+            '- branch_pr: `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: ..." --close-commit`',
+            '- direct: task owner uses `agentplane finish <task-id> --commit <git-rev> --author <OWNER> --body "Verified: ..." --close-commit` after the implementation commit',
             "- Optional cleanup: `agentplane cleanup merged --yes`",
         ],
     },
@@ -205,7 +205,7 @@ export function renderQuickstart() {
         '- `agentplane task new --title "..." --description "..." --priority med --owner CODER --tag <tag>`',
         '- `agentplane start <task-id> --author <ROLE> --body "Start: ..."`',
         '- `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`',
-        '- `agentplane finish <task-id> --author <ROLE> --body "Verified: ..."`',
+        '- `agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --commit <git-rev> --close-commit`',
         "",
         "## Branch workflow (branch_pr)",
         "",
@@ -233,7 +233,7 @@ export function renderQuickstart() {
         "",
         "- Show the current config: `agentplane config show`",
         "- Set a value by dotted key: `agentplane config set workflow_mode branch_pr`",
-        '- Set JSON values (lists/objects): `agentplane config set tasks.verify.required_tags \'["code","backend"]\'`',
+        '- Set JSON values (lists/objects): `agentplane config set tasks.verify.require_steps_for_primary \'["code","data","ops"]\'`',
         "",
         "## Role/phase command guide (when to use what)",
         "",
@@ -258,6 +258,7 @@ export function renderQuickstart() {
         "",
         "Notes:",
         "- `suffix` is the task ID segment after the last dash.",
-        "- When using comment-driven flags, the subject is auto-built as `<emoji> <suffix> <scope>: <summary>`, and the body is auto-built from your status/finish comment.",
+        "- When using comment-driven flags, the subject is auto-built as `<emoji> <suffix> <primary>: <status>` and only for major transitions (TODO->DOING, DOING->BLOCKED, BLOCKED->DOING, DOING->DONE).",
+        "- Comment-driven commit bodies are structured: `Task`, `Primary`, `Status`, `Comment`.",
     ].join("\n");
 }

package/dist/cli/run-cli/command-catalog.d.ts

@@ -15,5 +15,5 @@ export type CommandEntry = {
     needsConfig: boolean;
     needsTaskContext: boolean;
 };
-export declare const COMMANDS: readonly [CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry];
+export declare const COMMANDS: readonly [CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry, CommandEntry];
 //# sourceMappingURL=command-catalog.d.ts.map

package/dist/cli/run-cli/command-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/command-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAiGvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,kBAAkB,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACjF,eAAe,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3E,kBAAkB,EAAE,MAAM,SAAS,QAAQ,EAAE,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAgBF,eAAO,MAAM,QAAQ,yuCAuYuB,CAAC"}
+{"version":3,"file":"command-catalog.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/command-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAoGvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAC5E,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEzE,MAAM,MAAM,OAAO,GAAG;IACpB,MAAM,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IACpE,kBAAkB,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACjF,eAAe,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3E,kBAAkB,EAAE,MAAM,SAAS,QAAQ,EAAE,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC1D,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAgBF,eAAO,MAAM,QAAQ,iyCA2ZuB,CAAC"}

package/dist/cli/run-cli/command-catalog.js

@@ -1,5 +1,5 @@
 import { initSpec } from "./commands/init.js";
-import { agentsSpec, quickstartSpec, roleSpec } from "./commands/core.js";
+import { agentsSpec, preflightSpec, quickstartSpec, roleSpec } from "./commands/core.js";
 import { configSetSpec, configShowSpec, modeGetSpec, modeSetSpec } from "./commands/config.js";
 import { ideSyncSpec } from "./commands/ide.js";
 import { taskNewSpec } from "../../commands/task/new.spec.js";
@@ -22,6 +22,9 @@ import { taskLintSpec } from "../../commands/task/lint.command.js";
 import { taskMigrateSpec } from "../../commands/task/migrate.command.js";
 import { taskMigrateDocSpec } from "../../commands/task/migrate-doc.command.js";
 import { taskDeriveSpec } from "../../commands/task/derive.command.js";
+import { taskCloseDuplicateSpec } from "../../commands/task/close-duplicate.command.js";
+import { taskCloseNoopSpec } from "../../commands/task/close-noop.command.js";
+import { taskStartReadySpec } from "../../commands/task/start-ready.command.js";
 import { taskPlanSetSpec } from "../../commands/task/plan-set.command.js";
 import { taskPlanApproveSpec } from "../../commands/task/plan-approve.command.js";
 import { taskPlanRejectSpec } from "../../commands/task/plan-reject.command.js";
@@ -112,6 +115,11 @@ export const COMMANDS = [
         needsConfig: false,
         needsTaskContext: false,
     }),
+    entry(preflightSpec, () => import("./commands/core.js").then((m) => m.runPreflight), {
+        needsProject: false,
+        needsConfig: false,
+        needsTaskContext: false,
+    }),
     entry(roleSpec, () => import("./commands/core.js").then((m) => m.runRole), {
         needsProject: false,
         needsConfig: false,
@@ -158,6 +166,9 @@ export const COMMANDS = [
     entry(taskShowSpec, (deps) => import("../../commands/task/show.run.js").then((m) => m.makeRunTaskShowHandler(deps.getCtx))),
     entry(taskNewSpec, (deps) => import("../../commands/task/new.command.js").then((m) => m.makeRunTaskNewHandler(deps.getCtx))),
     entry(taskDeriveSpec, (deps) => import("../../commands/task/derive.command.js").then((m) => m.makeRunTaskDeriveHandler(deps.getCtx))),
+    entry(taskCloseDuplicateSpec, (deps) => import("../../commands/task/close-duplicate.command.js").then((m) => m.makeRunTaskCloseDuplicateHandler(deps.getCtx))),
+    entry(taskStartReadySpec, (deps) => import("../../commands/task/start-ready.command.js").then((m) => m.makeRunTaskStartReadyHandler(deps.getCtx))),
+    entry(taskCloseNoopSpec, (deps) => import("../../commands/task/close-noop.command.js").then((m) => m.makeRunTaskCloseNoopHandler(deps.getCtx))),
     entry(taskAddSpec, (deps) => import("../../commands/task/add.command.js").then((m) => m.makeRunTaskAddHandler(deps.getCtx))),
     entry(taskUpdateSpec, (deps) => import("../../commands/task/update.command.js").then((m) => m.makeRunTaskUpdateHandler(deps.getCtx))),
     entry(taskCommentSpec, (deps) => import("../../commands/task/comment.command.js").then((m) => m.makeRunTaskCommentHandler(deps.getCtx))),

package/dist/cli/run-cli/commands/core.d.ts

@@ -1,10 +1,18 @@
 import type { CommandHandler, CommandSpec } from "../../spec/spec.js";
 import type { RunDeps } from "../command-catalog.js";
-type QuickstartParsed = Record<string, never>;
+type QuickstartParsed = {
+    json: boolean;
+};
 export declare const quickstartSpec: CommandSpec<QuickstartParsed>;
 export declare const runQuickstart: CommandHandler<QuickstartParsed>;
+type PreflightParsed = {
+    json: boolean;
+};
+export declare const preflightSpec: CommandSpec<PreflightParsed>;
+export declare const runPreflight: CommandHandler<PreflightParsed>;
 type RoleParsed = {
     role: string;
+    json: boolean;
 };
 export declare const roleSpec: CommandSpec<RoleParsed>;
 export declare const runRole: CommandHandler<RoleParsed>;

package/dist/cli/run-cli/commands/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,KAAK,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE9C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAOxD,CAAC;AASF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAO5C,CAAC;AAkMF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA0FhF"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../../src/cli/run-cli/commands/core.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,KAAK,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAcxD,CAAC;AA6BF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAE1D,CAAC;AAEF,KAAK,eAAe,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AA0LzC,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,eAAe,CAgBtD,CAAC;AAsCF,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,eAAe,CAExD,CAAC;AAEF,KAAK,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,QAAQ,EAAE,WAAW,CAAC,UAAU,CAe5C,CAAC;AAoOF,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,UAAU,CAE9C,CAAC;AAEF,KAAK,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,YAAY,CAMhD,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,CA0FhF"}

package/dist/cli/run-cli/commands/core.js

@@ -1,6 +1,9 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
-import { resolveProject } from "@agentplaneorg/core";
+import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { loadTaskBackend } from "../../../backends/task-backend.js";
+import { GitContext } from "../../../commands/shared/git-context.js";
+import { gitCurrentBranch } from "../../../commands/shared/git-ops.js";
 import { fileExists } from "../../fs-utils.js";
 import { CliError } from "../../../shared/errors.js";
 import { dedupeStrings } from "../../../shared/strings.js";
@@ -12,26 +15,256 @@ export const quickstartSpec = {
     id: ["quickstart"],
     group: "Core",
     summary: "Print CLI quickstart and command cheat sheet.",
-    options: [],
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit compact machine-readable output for agent runtimes.",
+        },
+    ],
     examples: [{ cmd: "agentplane quickstart", why: "Show quickstart." }],
-    parse: () => ({}),
+    parse: (raw) => ({ json: raw.opts.json === true }),
 };
 async function cmdQuickstart(opts) {
     return wrapCommand({ command: "quickstart", rootOverride: opts.rootOverride }, () => {
-        process.stdout.write(`${renderQuickstart()}\n`);
+        const text = renderQuickstart();
+        if (opts.json) {
+            const lines = text
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0);
+            const payload = {
+                source_of_truth: {
+                    workflow_policy: "AGENTS.md",
+                    cli_syntax: "quickstart/role output",
+                },
+                lines,
+            };
+            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+            return 0;
+        }
+        process.stdout.write(`${text}\n`);
         return 0;
     });
 }
-export const runQuickstart = (ctx) => {
-    return cmdQuickstart({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });
+export const runQuickstart = (ctx, p) => {
+    return cmdQuickstart({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, json: p.json });
+};
+function compactError(err) {
+    if (err instanceof Error) {
+        const first = (err.message ?? "").split("\n", 1)[0] ?? "";
+        return first.trim() || err.name;
+    }
+    return String(err);
+}
+function probeYesNo(probe) {
+    return probe.ok ? "yes" : "no";
+}
+function probeValueOrUnknown(probe) {
+    return probe.ok && probe.value !== undefined ? String(probe.value) : "unknown";
+}
+function inferWorkflowMode(config) {
+    if (!config)
+        return "unknown";
+    return config.workflow_mode === "direct" || config.workflow_mode === "branch_pr"
+        ? config.workflow_mode
+        : "unknown";
+}
+function inferApprovals(config) {
+    if (!config) {
+        return {
+            require_plan: "unknown",
+            require_verify: "unknown",
+            require_network: "unknown",
+        };
+    }
+    const approvals = config.agents?.approvals;
+    if (!approvals) {
+        return {
+            require_plan: "unknown",
+            require_verify: "unknown",
+            require_network: "unknown",
+        };
+    }
+    return {
+        require_plan: approvals.require_plan,
+        require_verify: approvals.require_verify,
+        require_network: approvals.require_network,
+    };
+}
+async function buildPreflightReport(opts) {
+    const nextActions = [];
+    const quickstartText = renderQuickstart();
+    const quickstartLoaded = {
+        ok: quickstartText.trim().length > 0,
+        error: quickstartText.trim().length > 0 ? undefined : "quickstart renderer returned empty output",
+    };
+    let resolved = null;
+    try {
+        resolved = await resolveProject({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null });
+    }
+    catch (err) {
+        nextActions.push({
+            command: "agentplane init",
+            reason: `project not resolved (${compactError(err)})`,
+        });
+    }
+    let config = null;
+    let configLoaded = { ok: false, error: "project not resolved" };
+    if (resolved) {
+        try {
+            const loaded = await loadConfig(resolved.agentplaneDir);
+            config = loaded.config;
+            configLoaded = { ok: true };
+        }
+        catch (err) {
+            const message = compactError(err);
+            configLoaded = { ok: false, error: message };
+            nextActions.push({
+                command: "agentplane config show",
+                reason: `config failed validation (${message})`,
+            });
+        }
+    }
+    let taskListLoaded = {
+        ok: false,
+        error: "project not resolved",
+    };
+    if (resolved) {
+        try {
+            const loaded = await loadTaskBackend({
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride ?? null,
+            });
+            const tasks = await loaded.backend.listTasks();
+            taskListLoaded = { ok: true, count: tasks.length };
+        }
+        catch (err) {
+            const message = compactError(err);
+            taskListLoaded = { ok: false, error: message };
+            nextActions.push({
+                command: "agentplane task list",
+                reason: `task backend unavailable (${message})`,
+            });
+        }
+    }
+    let workingTree = {
+        ok: false,
+        error: "project not resolved",
+    };
+    let branch = {
+        ok: false,
+        error: "project not resolved",
+    };
+    if (resolved) {
+        try {
+            const git = new GitContext({ gitRoot: resolved.gitRoot });
+            const [staged, unstagedTracked] = await Promise.all([
+                git.statusStagedPaths(),
+                git.statusUnstagedTrackedPaths(),
+            ]);
+            workingTree = { ok: true, value: staged.length === 0 && unstagedTracked.length === 0 };
+            if (!workingTree.value) {
+                nextActions.push({
+                    command: "git status --short --untracked-files=no",
+                    reason: "tracked changes detected",
+                });
+            }
+        }
+        catch (err) {
+            const message = compactError(err);
+            workingTree = { ok: false, error: message };
+            nextActions.push({
+                command: "git status --short --untracked-files=no",
+                reason: `cannot inspect git status (${message})`,
+            });
+        }
+        try {
+            const current = await gitCurrentBranch(resolved.gitRoot);
+            branch = { ok: true, value: current };
+        }
+        catch (err) {
+            branch = { ok: false, error: compactError(err) };
+        }
+    }
+    return {
+        project_detected: resolved !== null,
+        config_loaded: configLoaded,
+        quickstart_loaded: quickstartLoaded,
+        task_list_loaded: taskListLoaded,
+        working_tree_clean_tracked: workingTree,
+        current_branch: branch,
+        workflow_mode: inferWorkflowMode(config),
+        approvals: inferApprovals(config),
+        outside_repo_needed: false,
+        next_actions: nextActions,
+    };
+}
+export const preflightSpec = {
+    id: ["preflight"],
+    group: "Core",
+    summary: "Run aggregated preflight checks and print a deterministic readiness report.",
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit machine-readable JSON report.",
+        },
+    ],
+    examples: [
+        { cmd: "agentplane preflight --json", why: "Produce one-shot agent-readable preflight." },
+    ],
+    parse: (raw) => ({ json: raw.opts.json === true }),
+};
+async function cmdPreflight(opts) {
+    return wrapCommand({ command: "preflight", rootOverride: opts.rootOverride }, async () => {
+        const report = await buildPreflightReport({ cwd: opts.cwd, rootOverride: opts.rootOverride });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            return 0;
+        }
+        process.stdout.write("Preflight Summary\n");
+        process.stdout.write(`- project detected: ${report.project_detected ? "yes" : "no"}\n`);
+        process.stdout.write(`- config loaded: ${probeYesNo(report.config_loaded)}\n`);
+        process.stdout.write(`- quickstart loaded: ${probeYesNo(report.quickstart_loaded)}\n`);
+        process.stdout.write(`- task list loaded: ${probeYesNo(report.task_list_loaded)}\n`);
+        process.stdout.write(`- working tree clean (tracked-only): ${probeValueOrUnknown(report.working_tree_clean_tracked)}\n`);
+        process.stdout.write(`- current git branch: ${probeValueOrUnknown(report.current_branch)}\n`);
+        process.stdout.write(`- workflow_mode: ${report.workflow_mode}\n`);
+        process.stdout.write("- approval gates:\n");
+        process.stdout.write(`  - require_plan: ${String(report.approvals.require_plan)}\n`);
+        process.stdout.write(`  - require_verify: ${String(report.approvals.require_verify)}\n`);
+        process.stdout.write(`  - require_network: ${String(report.approvals.require_network)}\n`);
+        process.stdout.write("- outside-repo: not needed\n");
+        if (report.next_actions.length > 0) {
+            process.stdout.write("Next actions:\n");
+            for (const action of report.next_actions) {
+                process.stdout.write(`- ${action.command}: ${action.reason}\n`);
+            }
+        }
+        return 0;
+    });
+}
+export const runPreflight = (ctx, p) => {
+    return cmdPreflight({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, json: p.json });
 };
 export const roleSpec = {
     id: ["role"],
     group: "Core",
     summary: "Show role-specific workflow guidance.",
     args: [{ name: "role", required: true, valueHint: "<role>" }],
+    options: [
+        {
+            kind: "boolean",
+            name: "json",
+            default: false,
+            description: "Emit compact machine-readable role payload.",
+        },
+    ],
     examples: [{ cmd: "agentplane role ORCHESTRATOR", why: "Show ORCHESTRATOR guide." }],
-    parse: (raw) => ({ role: String(raw.args.role ?? "") }),
+    parse: (raw) => ({ role: String(raw.args.role ?? ""), json: raw.opts.json === true }),
 };
 function parseAgentProfileJson(filePath, text) {
     let parsed;
@@ -159,6 +392,23 @@ async function cmdRole(opts) {
             });
         }
         if (guide) {
+            if (opts.json) {
+                const payload = {
+                    role: normalizedRole,
+                    builtin_guide: guide
+                        .split("\n")
+                        .map((line) => line.trim())
+                        .filter((line) => line.length > 0),
+                };
+                if (agentProfile) {
+                    payload.agent_profile = {
+                        filename: agentProfile.filename,
+                        profile: agentProfile.profile,
+                    };
+                }
+                process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+                return 0;
+            }
             process.stdout.write(`${guide}\n`);
             if (agentProfile) {
                 const block = renderAgentProfileBlock({
@@ -183,12 +433,22 @@ async function cmdRole(opts) {
             roleId: normalizedRole,
             profile: agentProfile.profile,
         });
+        if (opts.json) {
+            process.stdout.write(`${JSON.stringify({
+                role: normalizedRole,
+                agent_profile: {
+                    filename: agentProfile.filename,
+                    profile: agentProfile.profile,
+                },
+            }, null, 2)}\n`);
+            return 0;
+        }
         process.stdout.write(`${block}\n`);
         return 0;
     });
 }
 export const runRole = (ctx, p) => {
-    return cmdRole({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, role: p.role });
+    return cmdRole({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, role: p.role, json: p.json });
 };
 export const agentsSpec = {
     id: ["agents"],