agentplane 0.3.2 → 0.3.3

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

@@ -1 +1 @@
-{"version":3,"file":"local-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/local-backend.ts"],"names":[],"mappings":"AAqBA,OAAO,EAiBL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAa,YAAW,WAAW;IAC9C,EAAE,SAAW;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,cAAc,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB3E,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAwHtC,mBAAmB,IAAI,MAAM,EAAE;IAIzB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoBjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;IAKzD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyExC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuB1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAoF/D,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD"}
+{"version":3,"file":"local-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/local-backend.ts"],"names":[],"mappings":"AAqBA,OAAO,EAiBL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACd,MAAM,aAAa,CAAC;AAErB,qBAAa,YAAa,YAAW,WAAW;IAC9C,EAAE,SAAW;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,QAAQ,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,cAAc,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB3E,SAAS,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAwHtC,mBAAmB,IAAI,MAAM,EAAE;IAIzB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoBjD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,EAAE,CAAC;IAKzD,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO3C,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyExC,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB1E,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5C,cAAc,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAuF/D,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzD"}

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

@@ -4,7 +4,7 @@ import { docChanged, parseTaskReadme, renderTaskReadme, taskReadmePath, } from "
 import { isRecord } from "../../shared/guards.js";
 import { writeTextIfChanged } from "../../shared/write-if-changed.js";
 import { buildTaskIndexEntry, loadTaskIndex, resolveTaskIndexPath, saveTaskIndex, } from "../task-index.js";
-import { DEFAULT_DOC_UPDATED_BY, DOC_VERSION, defaultPlanApproval, defaultVerificationResult, extractTaskDoc, generateTaskId, invalidLengthMessage, mapLimit, mergeTaskDoc, missingTaskIdMessage, nowIso, resolveDocUpdatedByFromFrontmatter, resolveDocUpdatedByFromTask, taskRecordToData, validateTaskId, writeTasksExportFromTasks, } from "./shared.js";
+import { DEFAULT_DOC_UPDATED_BY, defaultPlanApproval, defaultVerificationResult, extractTaskDoc, generateTaskId, invalidLengthMessage, mapLimit, mergeTaskDoc, missingTaskIdMessage, normalizeDocVersion, nowIso, resolveDocUpdatedByFromFrontmatter, resolveDocUpdatedByFromTask, taskRecordToData, validateTaskId, writeTasksExportFromTasks, } from "./shared.js";
 export class LocalBackend {
     id = "local";
     root;
@@ -229,18 +229,17 @@ export class LocalBackend {
         if (payload.verification === undefined) {
             payload.verification = defaultVerificationResult();
         }
+        const existingDocVersion = normalizeDocVersion(existingFrontmatter.doc_version);
         if (task.doc !== undefined) {
             const docText = String(task.doc ?? "");
             body = mergeTaskDoc(body, docText);
             if (docChanged(existingDoc, docText)) {
-                payload.doc_version = DOC_VERSION;
+                payload.doc_version = normalizeDocVersion(task.doc_version, existingDocVersion);
                 payload.doc_updated_at = nowIso();
                 payload.doc_updated_by = resolveDocUpdatedByFromTask(task, this.updatedBy);
             }
         }
-        if (payload.doc_version !== DOC_VERSION) {
-            payload.doc_version = DOC_VERSION;
-        }
+        payload.doc_version = normalizeDocVersion(payload.doc_version, existingDocVersion);
         if (payload.doc_updated_at === undefined || payload.doc_updated_at === "") {
             payload.doc_updated_at = nowIso();
         }
@@ -258,14 +257,13 @@ export class LocalBackend {
         const docText = String(doc ?? "");
         const body = mergeTaskDoc(parsed.body, docText);
         const frontmatter = { ...parsed.frontmatter };
+        const currentDocVersion = normalizeDocVersion(frontmatter.doc_version);
         if (docChanged(extractTaskDoc(parsed.body), docText) || !frontmatter.doc_updated_at) {
-            frontmatter.doc_version = DOC_VERSION;
+            frontmatter.doc_version = currentDocVersion;
             frontmatter.doc_updated_at = nowIso();
             frontmatter.doc_updated_by = resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, this.updatedBy);
         }
-        if (frontmatter.doc_version !== DOC_VERSION) {
-            frontmatter.doc_version = DOC_VERSION;
-        }
+        frontmatter.doc_version = normalizeDocVersion(frontmatter.doc_version, currentDocVersion);
         const next = renderTaskReadme(frontmatter, body);
         await writeTextIfChanged(readme, next.endsWith("\n") ? next : `${next}\n`);
     }
@@ -274,7 +272,7 @@ export class LocalBackend {
         const text = await readFile(readme, "utf8");
         const parsed = parseTaskReadme(text);
         const frontmatter = { ...parsed.frontmatter };
-        frontmatter.doc_version = DOC_VERSION;
+        frontmatter.doc_version = normalizeDocVersion(frontmatter.doc_version);
         frontmatter.doc_updated_at = nowIso();
         frontmatter.doc_updated_by = resolveDocUpdatedByFromFrontmatter(frontmatter, updatedBy, this.updatedBy);
         const next = renderTaskReadme(frontmatter, parsed.body || "");
@@ -340,8 +338,7 @@ export class LocalBackend {
             }
             if (payload.verification === undefined)
                 payload.verification = defaultVerificationResult();
-            if (payload.doc_version !== DOC_VERSION)
-                payload.doc_version = DOC_VERSION;
+            payload.doc_version = normalizeDocVersion(payload.doc_version, normalizeDocVersion(fm.doc_version));
             if (payload.doc_updated_at === undefined || payload.doc_updated_at === "") {
                 payload.doc_updated_at = nowIso();
             }

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

@@ -1 +1 @@
-{"version":3,"file":"redmine-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/redmine-backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"redmine-backend.d.ts","sourceRoot":"","sources":["../../../src/backends/task-backend/redmine-backend.ts"],"names":[],"mappings":"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"}

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

@@ -7,7 +7,7 @@ import { doneRatioForStatus, issueToTask as issueToTaskImpl, startDateFromTaskId
 import { coerceDocVersion as coerceRedmineDocVersion, maybeParseJson as maybeParseRedmineJson, } from "./redmine/parse.js";
 import { findIssueByTaskId as findIssueByTaskIdImpl, listTasksRemote as listTasksRemoteImpl, } from "./redmine/remote.js";
 import { readRedmineEnv } from "./redmine/env.js";
-import { BackendError, DEFAULT_DOC_UPDATED_BY, DOC_VERSION, RedmineUnavailable, ensureDocMetadata, firstNonEmptyString, generateTaskId, mapLimit, missingTaskIdMessage, nowIso, redmineConfigMissingEnvMessage, redmineIssueIdMissingMessage, sleep, toStringSafe, unknownTaskIdMessage, validateTaskId, writeTasksExportFromTasks, } from "./shared.js";
+import { BackendError, DEFAULT_DOC_UPDATED_BY, DOC_VERSION, RedmineUnavailable, ensureDocMetadata, firstNonEmptyString, generateTaskId, mapLimit, missingTaskIdMessage, normalizeDocVersion, nowIso, redmineConfigMissingEnvMessage, redmineIssueIdMissingMessage, sleep, toStringSafe, unknownTaskIdMessage, validateTaskId, writeTasksExportFromTasks, } from "./shared.js";
 export class RedmineBackend {
     id = "redmine";
     baseUrl;
@@ -151,7 +151,11 @@ export class RedmineBackend {
             const issueIdText = toStringSafe(issue.id);
             if (!issueIdText)
                 throw new Error(redmineIssueIdMissingMessage());
-            const taskDoc = { doc: String(doc ?? "") };
+            const cachedTask = this.issueToTask(issue, taskId);
+            const taskDoc = {
+                doc: String(doc ?? ""),
+                doc_version: cachedTask?.doc_version,
+            };
             ensureDocMetadata(taskDoc, updatedBy);
             const customFields = [];
             this.appendCustomField(customFields, "doc", taskDoc.doc);
@@ -161,13 +165,12 @@ export class RedmineBackend {
             await this.requestJson("PUT", `issues/${issueIdText}.json`, {
                 issue: { custom_fields: customFields },
             });
-            const task = this.issueToTask(issue, taskId);
-            if (task) {
-                task.doc = taskDoc.doc;
-                task.doc_version = taskDoc.doc_version;
-                task.doc_updated_at = taskDoc.doc_updated_at;
-                task.doc_updated_by = taskDoc.doc_updated_by;
-                await this.cacheTask(task, false);
+            if (cachedTask) {
+                cachedTask.doc = taskDoc.doc;
+                cachedTask.doc_version = taskDoc.doc_version;
+                cachedTask.doc_updated_at = taskDoc.doc_updated_at;
+                cachedTask.doc_updated_by = taskDoc.doc_updated_by;
+                await this.cacheTask(cachedTask, false);
             }
         }
         catch (err) {
@@ -195,7 +198,11 @@ export class RedmineBackend {
             if (!issueIdText)
                 throw new Error(redmineIssueIdMissingMessage());
             const docValue = this.customFieldValue(issue, this.customFields.doc);
-            const taskDoc = { doc: docValue ?? "" };
+            const cachedTask = this.issueToTask(issue, taskId);
+            const taskDoc = {
+                doc: docValue ?? "",
+                doc_version: cachedTask?.doc_version,
+            };
             ensureDocMetadata(taskDoc, updatedBy);
             const customFields = [];
             this.appendCustomField(customFields, "doc_version", taskDoc.doc_version);
@@ -205,12 +212,11 @@ export class RedmineBackend {
                 await this.requestJson("PUT", `issues/${issueIdText}.json`, {
                     issue: { custom_fields: customFields },
                 });
-                const task = this.issueToTask(issue, taskId);
-                if (task) {
-                    task.doc_version = taskDoc.doc_version;
-                    task.doc_updated_at = taskDoc.doc_updated_at;
-                    task.doc_updated_by = taskDoc.doc_updated_by;
-                    await this.cacheTask(task, false);
+                if (cachedTask) {
+                    cachedTask.doc_version = taskDoc.doc_version;
+                    cachedTask.doc_updated_at = taskDoc.doc_updated_at;
+                    cachedTask.doc_updated_by = taskDoc.doc_updated_by;
+                    await this.cacheTask(cachedTask, false);
                 }
             }
         }
@@ -311,8 +317,7 @@ export class RedmineBackend {
     ensureDocMetadata(task) {
         if (task.doc === undefined)
             return;
-        if (task.doc_version !== DOC_VERSION)
-            task.doc_version = DOC_VERSION;
+        task.doc_version = normalizeDocVersion(task.doc_version);
         task.doc_updated_at ??= nowIso();
         task.doc_updated_by ??= DEFAULT_DOC_UPDATED_BY;
     }

package/dist/backends/task-backend/shared/constants.d.ts

@@ -1,4 +1,5 @@
 export declare const TASK_ID_RE: RegExp;
 export declare const DEFAULT_DOC_UPDATED_BY = "agentplane";
 export declare const DOC_VERSION = 2;
+export declare const SUPPORTED_DOC_VERSIONS: readonly [2, 3];
 //# sourceMappingURL=constants.d.ts.map

package/dist/backends/task-backend/shared/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,QAA6D,CAAC;AACrF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AACnD,eAAO,MAAM,WAAW,IAAI,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU,QAA6D,CAAC;AACrF,eAAO,MAAM,sBAAsB,eAAe,CAAC;AACnD,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,sBAAsB,iBAAkB,CAAC"}

package/dist/backends/task-backend/shared/constants.js

@@ -2,3 +2,4 @@ import { TASK_ID_ALPHABET } from "@agentplaneorg/core";
 export const TASK_ID_RE = new RegExp(String.raw `^\d{12}-[${TASK_ID_ALPHABET}]{4,}$`);
 export const DEFAULT_DOC_UPDATED_BY = "agentplane";
 export const DOC_VERSION = 2;
+export const SUPPORTED_DOC_VERSIONS = [2, 3];

package/dist/backends/task-backend/shared/doc.d.ts

@@ -6,6 +6,7 @@ declare const mergeTaskDoc: MergeTaskDoc;
 export declare function nowIso(): string;
 export declare function resolveDocUpdatedByFromFrontmatter(frontmatter: Record<string, unknown>, updatedBy: string | undefined, fallback: string): string;
 export declare function resolveDocUpdatedByFromTask(task: TaskData, fallback: string): string;
+export declare function normalizeDocVersion(value: unknown, fallback?: 2 | 3): 2 | 3;
 export declare function ensureDocMetadata(task: TaskDocMeta & Partial<Pick<TaskData, "comments" | "owner">>, updatedBy?: string): void;
 export { extractTaskDoc, mergeTaskDoc };
 //# sourceMappingURL=doc.d.ts.map

package/dist/backends/task-backend/shared/doc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/doc.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,KAAK,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAC/C,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAE1D,QAAA,MAAM,cAAc,EAAE,cAAmC,CAAC;AAC1D,QAAA,MAAM,YAAY,EAAE,YAA+B,CAAC;AAEpD,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAyBD,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,MAAM,CAaR;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASpF;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,EACjE,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CAUN;AAED,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"doc.d.ts","sourceRoot":"","sources":["../../../../src/backends/task-backend/shared/doc.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAExD,KAAK,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAC/C,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;AAE1D,QAAA,MAAM,cAAc,EAAE,cAAmC,CAAC;AAC1D,QAAA,MAAM,YAAY,EAAE,YAA+B,CAAC;AAEpD,wBAAgB,MAAM,IAAI,MAAM,CAE/B;AAyBD,wBAAgB,kCAAkC,CAChD,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,MAAM,GACf,MAAM,CAaR;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CASpF;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,CAAC,GAAG,CAAe,GAAG,CAAC,GAAG,CAAC,CAExF;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,EACjE,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CAUN;AAED,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC"}

package/dist/backends/task-backend/shared/doc.js

@@ -64,8 +64,11 @@ export function resolveDocUpdatedByFromTask(task, fallback) {
     const fallbackValue = normalizeUpdatedBy(fallback);
     return fallbackValue || fallback;
 }
+export function normalizeDocVersion(value, fallback = DOC_VERSION) {
+    return value === 3 ? 3 : value === 2 ? 2 : fallback;
+}
 export function ensureDocMetadata(task, updatedBy) {
-    task.doc_version = DOC_VERSION;
+    task.doc_version = normalizeDocVersion(task.doc_version);
     task.doc_updated_at = nowIso();
     const explicit = normalizeUpdatedBy(updatedBy);
     if (updatedBy !== undefined) {

package/dist/backends/task-backend/shared/export.js

@@ -3,8 +3,8 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { canonicalizeJson } from "@agentplaneorg/core";
 import { writeJsonStableIfChanged } from "../../../shared/write-if-changed.js";
-import { DEFAULT_DOC_UPDATED_BY, DOC_VERSION } from "./constants.js";
-import { resolveDocUpdatedByFromTask } from "./doc.js";
+import { DEFAULT_DOC_UPDATED_BY } from "./constants.js";
+import { normalizeDocVersion, resolveDocUpdatedByFromTask } from "./doc.js";
 import { toStringArray } from "./strings.js";
 function taskDataToExport(task) {
     const base = {
@@ -22,7 +22,7 @@ function taskDataToExport(task) {
         comments: Array.isArray(task.comments)
             ? task.comments.filter((item) => !!item && typeof item.author === "string" && typeof item.body === "string")
             : [],
-        doc_version: task.doc_version ?? DOC_VERSION,
+        doc_version: normalizeDocVersion(task.doc_version),
         doc_updated_at: task.doc_updated_at ?? "",
         doc_updated_by: resolveDocUpdatedByFromTask(task, DEFAULT_DOC_UPDATED_BY),
         dirty: Boolean(task.dirty),

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

@@ -7,9 +7,7 @@ export type BootstrapSection = {
 };
 export declare const BOOTSTRAP_PREFLIGHT_COMMANDS: readonly ["agentplane config show", "agentplane quickstart", "agentplane task list", "git status --short --untracked-files=no", "git rev-parse --abbrev-ref HEAD"];
 export declare const BOOTSTRAP_TASK_PREP_COMMANDS: string[];
-export declare const BOOTSTRAP_TASK_LIFECYCLE_COMMANDS: readonly [...string[], "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
-export declare const BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS: readonly ["agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
-export declare const BOOTSTRAP_VERIFICATION_COMMANDS: readonly ["agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane doctor", "node .agentplane/policy/check-routing.mjs"];
+export declare const BOOTSTRAP_DIRECT_HAPPY_PATH_COMMANDS: readonly [...string[], "agentplane task start-ready <task-id> --author <ROLE> --body \"Start: ...\"", "agentplane task verify-show <task-id>", "agentplane verify <task-id> --ok|--rework --by <ROLE> --note \"...\"", "agentplane finish <task-id> --author <ROLE> --body \"Verified: ...\" --result \"...\" --commit <git-rev>"];
 export declare const BOOTSTRAP_RECOVERY_COMMANDS: readonly ["agentplane doctor", "agentplane upgrade --dry-run", "agentplane upgrade"];
 export declare const BOOTSTRAP_SECTIONS: readonly BootstrapSection[];
 export declare function renderBootstrapReferenceLine(): string;

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

@@ -1 +1 @@
-{"version":3,"file":"bootstrap-guide.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap-guide.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,4CAA4C,CAAC;AAElF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,oKAM/B,CAAC;AAEX,eAAO,MAAM,4BAA4B,UAIxC,CAAC;AAEF,eAAO,MAAM,iCAAiC,2RAKpC,CAAC;AAEX,eAAO,MAAM,oCAAoC,wOAIvC,CAAC;AAEX,eAAO,MAAM,+BAA+B,8LAKlC,CAAC;AAEX,eAAO,MAAM,2BAA2B,sFAI9B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EA+ChD,CAAC;AAEX,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAiB3F;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CA0B3C"}
+{"version":3,"file":"bootstrap-guide.d.ts","sourceRoot":"","sources":["../../src/cli/bootstrap-guide.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,4CAA4C,CAAC;AAElF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B,CAAC;AAEF,eAAO,MAAM,4BAA4B,oKAM/B,CAAC;AAEX,eAAO,MAAM,4BAA4B,UAIxC,CAAC;AAEF,eAAO,MAAM,oCAAoC,oUAMvC,CAAC;AAEX,eAAO,MAAM,2BAA2B,sFAI9B,CAAC;AAEX,eAAO,MAAM,kBAAkB,EAAE,SAAS,gBAAgB,EAmChD,CAAC;AAEX,wBAAgB,4BAA4B,IAAI,MAAM,CAErD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAiB3F;AAMD,wBAAgB,kBAAkB,IAAI,MAAM,CA2B3C"}

package/dist/cli/bootstrap-guide.js

@@ -12,23 +12,13 @@ export const BOOTSTRAP_TASK_PREP_COMMANDS = [
     'agentplane task plan set <task-id> --text "..." --updated-by <ROLE>',
     "agentplane task plan approve <task-id> --by ORCHESTRATOR",
 ];
-export const BOOTSTRAP_TASK_LIFECYCLE_COMMANDS = [
+export const BOOTSTRAP_DIRECT_HAPPY_PATH_COMMANDS = [
     ...BOOTSTRAP_TASK_PREP_COMMANDS,
     COMMAND_SNIPPETS.core.startTask,
-    COMMAND_SNIPPETS.core.verifyTask,
-    'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>',
-];
-export const BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS = [
     "agentplane task verify-show <task-id>",
     COMMAND_SNIPPETS.core.verifyTask,
     'agentplane finish <task-id> --author <ROLE> --body "Verified: ..." --result "..." --commit <git-rev>',
 ];
-export const BOOTSTRAP_VERIFICATION_COMMANDS = [
-    "agentplane task verify-show <task-id>",
-    COMMAND_SNIPPETS.core.verifyTask,
-    "agentplane doctor",
-    "node .agentplane/policy/check-routing.mjs",
-];
 export const BOOTSTRAP_RECOVERY_COMMANDS = [
     "agentplane doctor",
     "agentplane upgrade --dry-run",
@@ -45,36 +35,25 @@ export const BOOTSTRAP_SECTIONS = [
         ],
     },
     {
-        heading: "2. Prepare executable task scope",
-        summary: "Work only through executable task ids. Create the task, fill plan/docs, then approve the plan.",
-        commands: BOOTSTRAP_TASK_PREP_COMMANDS,
+        heading: "2. Direct happy path",
+        summary: "Use one short direct-mode route: create the task, approve it, start it, verify it, and finish it.",
+        commands: BOOTSTRAP_DIRECT_HAPPY_PATH_COMMANDS,
         notes: [
             "Use `task doc set` to fill required README sections before approval.",
             "For dependent tasks, wait until upstream tasks are DONE before `task start-ready`.",
-        ],
-    },
-    {
-        heading: "3. Start work deterministically",
-        summary: "Move the task to DOING only after plan approval succeeds.",
-        commands: [COMMAND_SNIPPETS.core.startTask],
-        notes: ["`task plan approve` and `task start-ready` must run sequentially, never in parallel."],
-    },
-    {
-        heading: "4. Verify and finish",
-        summary: "Treat Verify Steps as the contract, then record verification and close with traceable metadata.",
-        commands: BOOTSTRAP_VERIFY_AND_FINISH_COMMANDS,
-        notes: [
+            "`task plan approve` and `task start-ready` must run sequentially, never in parallel.",
             "In `direct`, `finish` creates the deterministic close commit by default.",
-            "Use `--no-close-commit` only for explicit manual close handling.",
+            "Treat `task verify-show` as the verification contract right before `verify` and `finish`.",
         ],
     },
     {
-        heading: "5. Recover mixed or broken state",
-        summary: "Use diagnostics before manual repair, especially after framework upgrades or partial edits.",
+        heading: "3. Fallbacks and recovery",
+        summary: "Keep exceptional paths out of the normal route: use these only for recovery, framework upgrades, or branch_pr work.",
         commands: BOOTSTRAP_RECOVERY_COMMANDS,
         notes: [
             "Run `doctor` before touching managed policy files by hand.",
             "`upgrade` applies the managed framework files from the installed CLI bundle.",
+            "Manual close handling (`--no-close-commit`, `--close-unstage-others`) belongs here, not in the default direct path.",
         ],
     },
 ];
@@ -118,14 +97,15 @@ export function renderBootstrapDoc() {
         "",
         ...renderCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
         "",
-        "After preflight, continue with the smallest task flow that matches your mode and role.",
+        "After preflight, stay on the direct happy path unless the repository state is broken or you are explicitly in `branch_pr`.",
         "",
         ...renderBootstrapSectionLines(BOOTSTRAP_SECTIONS),
         "",
-        "## Direct vs branch_pr",
+        "## Non-default paths",
         "",
-        "- `direct`: work in the current checkout and finish the task yourself.",
+        "- `direct`: the default route is `task new/plan approve/start-ready -> task verify-show -> verify -> finish`.",
         "- `branch_pr`: start a task branch/worktree, maintain PR artifacts, and let INTEGRATOR close on base.",
+        "- Use manual close flags only when a specific policy or recovery situation requires them.",
         "",
     ];
     return `${lines.join("\n")}\n`;

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

package/dist/cli/command-guide.js

@@ -1,17 +1,8 @@
 import { COMMAND_SNIPPETS } from "./command-snippets.js";
-import { AGENT_BOOTSTRAP_DOC_PATH, BOOTSTRAP_SECTIONS, renderBootstrapReferenceLine, } from "./bootstrap-guide.js";
-function renderBootstrapOverview() {
-    const lines = [];
-    for (const section of BOOTSTRAP_SECTIONS) {
-        lines.push(`## ${section.heading}`, "", section.summary, "");
-        for (const command of section.commands) {
-            lines.push(`- \`${command}\``);
-        }
-        lines.push("");
-    }
-    if (lines.at(-1) === "")
-        lines.pop();
-    return lines;
+import { AGENT_BOOTSTRAP_DOC_PATH, BOOTSTRAP_PREFLIGHT_COMMANDS, BOOTSTRAP_TASK_PREP_COMMANDS, } from "./bootstrap-guide.js";
+const CLI_REFERENCE_DOC_PATH = "docs/user/cli-reference.generated.mdx";
+function renderQuickstartCommandBlock(commands) {
+    return ["```bash", ...commands, "```"];
 }
 const ROLE_GUIDES = [
     {
@@ -39,6 +30,7 @@ const ROLE_GUIDES = [
             `- Start deterministically with \`${COMMAND_SNIPPETS.core.startTask}\` after plan approval.`,
             '- Treat `agentplane task verify-show <task-id>` as the verification contract, then record `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`.',
             `- Preferred direct close path: \`${COMMAND_SNIPPETS.core.finishTask}\` with \`--result "..." \`; add \`--no-close-commit\` only for explicit manual close handling.`,
+            "- For manual close or allowlist detail, use `agentplane help finish` and `agentplane help commit` on demand.",
         ],
     },
     {
@@ -48,6 +40,7 @@ const ROLE_GUIDES = [
             "- Start only after plan approval and explicit Verify Steps exist.",
             '- Use `agentplane task verify-show <task-id>` before running checks, then record `agentplane verify <task-id> --ok|--rework --by <ROLE> --note "..."`.',
             `- In direct mode, close with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \` when you own final verification.`,
+            "- For mixed-state recovery or runtime ambiguity, use `agentplane doctor` and `agentplane runtime explain` instead of relying on the short quickstart screen.",
         ],
     },
     {
@@ -56,6 +49,7 @@ const ROLE_GUIDES = [
             `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
             '- Keep task docs and user docs aligned with runtime behavior via `agentplane task doc set <task-id> --section <name> --text "..."`.',
             "- For implementation tasks, verify generated/help surfaces after changing CLI-facing text.",
+            `- Treat \`${CLI_REFERENCE_DOC_PATH}\` as the deep reference surface; keep first-screen help intentionally shorter.`,
         ],
     },
     {
@@ -72,6 +66,7 @@ const ROLE_GUIDES = [
             `- Shared bootstrap path: \`${COMMAND_SNIPPETS.core.quickstart}\` -> \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
             '- 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: ..." --result "..." --close-commit`.',
             `- direct: the task owner normally closes with \`${COMMAND_SNIPPETS.core.finishTask}\` plus \`--result "..." \`.`,
+            "- For branch-level flags and branch/base diagnostics, use `agentplane help work start`, `agentplane help integrate`, and `agentplane help branch base`.",
         ],
     },
     {
@@ -115,38 +110,36 @@ export function renderQuickstart() {
     return [
         "# agentplane quickstart",
         "",
-        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy. CLI syntax lives in quickstart and `agentplane role <ROLE>`.",
+        "The policy gateway file (AGENTS.md or CLAUDE.md) is the source of truth for workflow/process policy.",
+        "Keep this first screen short: use it for startup only, then go deeper with `agentplane role <ROLE>` or `agentplane help <command>`.",
         "Do not edit `.agentplane/tasks.json` by hand.",
         "If the repository is not initialized yet, stop and run `agentplane init` first.",
         "",
-        renderBootstrapReferenceLine(),
+        `Canonical bootstrap doc: \`${AGENT_BOOTSTRAP_DOC_PATH}\`.`,
         "",
-        ...renderBootstrapOverview(),
+        "## First screen",
         "",
-        "## Role-specific deltas",
+        "Run preflight:",
         "",
-        `- Use \`${COMMAND_SNIPPETS.core.role}\` for role-specific constraints after you understand the shared bootstrap path.`,
-        "- Role output should add deltas, not replace the canonical bootstrap flow.",
+        ...renderQuickstartCommandBlock(BOOTSTRAP_PREFLIGHT_COMMANDS),
         "",
-        "## Branch workflow extras",
+        "Default direct route:",
         "",
-        "- `agentplane work start <task-id> --agent <ROLE> --slug <slug> --worktree`",
-        "- `agentplane pr open <task-id>` / `agentplane pr update <task-id>` / `agentplane pr check <task-id>`",
-        "- `agentplane integrate <task-id> --branch task/<task-id>/<slug> --run-verify`",
+        `- Task setup: \`${BOOTSTRAP_TASK_PREP_COMMANDS[0]}\` -> \`${BOOTSTRAP_TASK_PREP_COMMANDS[1]}\` -> \`${BOOTSTRAP_TASK_PREP_COMMANDS[2]}\`.`,
+        `- Execution: \`${COMMAND_SNIPPETS.core.startTask}\` -> \`agentplane task verify-show <task-id>\` -> \`${COMMAND_SNIPPETS.core.verifyTask}\` -> \`${COMMAND_SNIPPETS.core.finishTask}\` with \`--result "..." \`.`,
+        "- In `direct`, `finish` creates the deterministic close commit by default.",
         "",
-        "## More guidance",
+        "## Go deeper",
         "",
-        "- `agentplane help <command>` for command-level flags and examples.",
-        `- \`${COMMAND_SNIPPETS.core.role}\` for role-specific deltas.`,
-        `- \`${AGENT_BOOTSTRAP_DOC_PATH}\` for the canonical startup path in repository docs.`,
+        `- \`${COMMAND_SNIPPETS.core.role}\` for role-specific deltas and mode-specific ownership rules.`,
+        "- `agentplane help <command>` for flags, examples, and exceptional/manual flows.",
+        `- \`${AGENT_BOOTSTRAP_DOC_PATH}\` for the full startup path instead of repeating it on the first screen.`,
+        `- \`${CLI_REFERENCE_DOC_PATH}\` for the generated full command reference.`,
         "",
-        "## Commit message format",
+        "## Non-default",
         "",
-        "Use: `<emoji> <suffix> <scope>: <summary>`.",
-        "",
-        "Notes:",
-        "- `suffix` is the task ID segment after the last dash.",
-        "- 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`.",
+        "- `branch_pr`: use `agentplane help work start`, `agentplane help pr`, and `agentplane help integrate`.",
+        "- Recovery/mixed state: use `agentplane doctor`, `agentplane upgrade`, and `agentplane runtime explain`.",
+        "- Manual close or allowlist details belong in command-specific help, not on this first screen.",
     ].join("\n");
 }

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

@@ -0,0 +1,7 @@
+import { COMMANDS } from "./command-catalog.js";
+export type CatalogMatch = {
+    entry: (typeof COMMANDS)[number];
+    consumed: number;
+};
+export declare function matchCommandCatalog(tokens: readonly string[]): CatalogMatch | null;
+//# sourceMappingURL=catalog.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../../../src/cli/run-cli/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,MAAM,MAAM,YAAY,GAAG;IAAE,KAAK,EAAE,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAElF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,YAAY,GAAG,IAAI,CAkBlF"}

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

@@ -0,0 +1,22 @@
+import { COMMANDS } from "./command-catalog.js";
+export function matchCommandCatalog(tokens) {
+    let best = null;
+    for (const entry of COMMANDS) {
+        const id = entry.spec.id;
+        if (tokens.length < id.length)
+            continue;
+        let ok = true;
+        for (const [i, seg] of id.entries()) {
+            if (tokens[i] !== seg) {
+                ok = false;
+                break;
+            }
+        }
+        if (!ok)
+            continue;
+        if (!best || id.length > best.consumed) {
+            best = { entry, consumed: id.length };
+        }
+    }
+    return best;
+}

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, 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, 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;AAkHvD,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,m4CA+hBuB,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;AAmHvD,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,+5CA6iBuB,CAAC"}

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

@@ -67,6 +67,7 @@ import { workflowBuildSpec } from "../../commands/workflow-build.command.js";
 import { workflowRestoreSpec } from "../../commands/workflow-restore.command.js";
 import { workflowDebugSpec, workflowLandSpec, workflowSyncSpec, } from "../../commands/workflow-playbook.command.js";
 import { docsCliSpec } from "../../commands/docs/cli.command.js";
+import { runtimeExplainSpec, runtimeSpec } from "../../commands/runtime.command.js";
 import { hooksSpec } from "../../commands/hooks/hooks.command.js";
 import { hooksInstallSpec } from "../../commands/hooks/install.command.js";
 import { hooksUninstallSpec } from "../../commands/hooks/uninstall.command.js";
@@ -124,6 +125,16 @@ export const COMMANDS = [
         needsConfig: false,
         needsTaskContext: false,
     }),
+    entry(runtimeSpec, () => import("../../commands/runtime.command.js").then((m) => m.runRuntime), {
+        needsProject: false,
+        needsConfig: false,
+        needsTaskContext: false,
+    }),
+    entry(runtimeExplainSpec, () => import("../../commands/runtime.command.js").then((m) => m.runRuntimeExplain), {
+        needsProject: false,
+        needsConfig: false,
+        needsTaskContext: false,
+    }),
     entry(roleSpec, () => import("./commands/core.js").then((m) => m.runRole), {
         needsProject: false,
         needsConfig: false,

package/dist/cli/run-cli/commands/init/write-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-config.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-config.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,YAAY,CAAC;IACpD,gBAAgB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC,EAAE,MAAM,EAAE,CAAC;CACrD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}
+{"version":3,"file":"write-config.d.ts","sourceRoot":"","sources":["../../../../../src/cli/run-cli/commands/init/write-config.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,cAAc,GAAG,UAAU,GAAG,YAAY,CAAC;IACpD,gBAAgB,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC5C,WAAW,EAAE;QACX,SAAS,EAAE,MAAM,CAAC;QAClB,cAAc,EAAE,MAAM,CAAC;QACvB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,yCAAyC,EAAE,MAAM,EAAE,CAAC;CACrD,CAAC;AAEF,wBAAsB,oBAAoB,CACxC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,OAAO,GAAG,SAAS,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAAC;IACjC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,sBAAsB,EAAE,OAAO,CAAC;IAChC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,SAAS,EAAE,mBAAmB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhB"}

package/dist/cli/run-cli/commands/init/write-config.js

@@ -2,6 +2,7 @@ import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { defaultConfig, saveConfig, setByDottedKey } from "@agentplaneorg/core";
 import { writeJsonStableIfChanged } from "../../../../shared/write-if-changed.js";
+import { getVersion } from "../../../../meta/version.js";
 export async function ensureAgentplaneDirs(agentplaneDir, backend) {
     await mkdir(agentplaneDir, { recursive: true });
     await mkdir(path.join(agentplaneDir, "tasks"), { recursive: true });
@@ -21,6 +22,7 @@ export async function writeInitConfig(opts) {
     setByDottedKey(rawConfig, "agents.approvals.require_plan", String(opts.requirePlanApproval));
     setByDottedKey(rawConfig, "agents.approvals.require_network", String(opts.requireNetworkApproval));
     setByDottedKey(rawConfig, "agents.approvals.require_verify", String(opts.requireVerifyApproval));
+    setByDottedKey(rawConfig, "framework.cli.expected_version", getVersion());
     setByDottedKey(rawConfig, "execution", JSON.stringify(opts.execution));
     await saveConfig(opts.agentplaneDir, rawConfig);
 }