agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/dist/cli/commands/state/list.js

@@ -0,0 +1,159 @@
+import { resolveSourceRoot } from "../../../core/sourceRoot.js";
+import { listStateEntries, boundStateList, renderStateListText, } from "../../../state/listRetrieval.js";
+import { numberedArchiveArtifacts } from "../../../state/archiveDiscovery.js";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { emitStructured } from "../../structured.js";
+function requestedFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--format") {
+            const value = argv[index + 1];
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+        if (token.startsWith("--format=")) {
+            const value = token.slice("--format=".length);
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+    }
+    return "text";
+}
+function syntax(artifactId) {
+    return `agentera state ${artifactId} list [--limit N] [--cursor TOKEN] --format json`;
+}
+function failure(className, artifactId, message, example = `agentera state ${artifactId} list --limit 20 --format json`, validValues) {
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: className,
+            message,
+            syntax: syntax(artifactId),
+            example,
+            recovery: "Correct the command using the valid syntax and retry; no state was changed.",
+            artifact_id: artifactId,
+            ...(validValues ? { valid_values: validValues } : {}),
+        },
+    }, 2);
+}
+function readValue(argv, index, name) {
+    const token = argv[index];
+    if (token.startsWith(`${name}=`))
+        return { value: token.slice(name.length + 1), next: index + 1 };
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return { value, next: index + 2 };
+}
+function parseListArgs(artifactId, argv, sourceRoot) {
+    const validValues = numberedArchiveArtifacts(sourceRoot);
+    if (!validValues.includes(artifactId)) {
+        throw failure("unsupported_artifact", artifactId, `unsupported state artifact '${artifactId}'`, undefined, validValues);
+    }
+    let limit = 20;
+    let cursor;
+    let format = "text";
+    const filters = {};
+    const allowedFilters = artifactId === "progress" ? new Set(["--topic", "--status"]) : artifactId === "decisions" ? new Set(["--topic"]) : new Set(["--dimension"]);
+    let limitSupplied = false;
+    let cursorSupplied = false;
+    let formatSupplied = false;
+    const filterSupplied = new Set();
+    for (let index = 0; index < argv.length;) {
+        const token = argv[index];
+        const name = token.startsWith("--limit") ? "--limit" : token.startsWith("--cursor") ? "--cursor" : token.startsWith("--format") ? "--format" : [...allowedFilters].find((filter) => token === filter || token.startsWith(`${filter}=`)) ?? null;
+        if (!name)
+            throw failure("invalid_request", artifactId, `unrecognized argument '${token}'`);
+        let parsed;
+        try {
+            parsed = readValue(argv, index, name);
+        }
+        catch (error) {
+            throw failure("invalid_request", artifactId, error.message);
+        }
+        index = parsed.next;
+        if (name === "--limit") {
+            if (limitSupplied)
+                throw failure("invalid_request", artifactId, "--limit may only be supplied once");
+            limitSupplied = true;
+            if (!/^[1-9][0-9]*$/.test(parsed.value))
+                throw failure("invalid_request", artifactId, "argument --limit must be a positive canonical integer from 1 through 100");
+            limit = Number(parsed.value);
+            if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+                throw failure("invalid_request", artifactId, "argument --limit must be between 1 and 100", `agentera state ${artifactId} list --limit 20 --format json`);
+        }
+        else if (name === "--cursor") {
+            if (cursorSupplied)
+                throw failure("invalid_request", artifactId, "--cursor may only be supplied once");
+            cursorSupplied = true;
+            if (parsed.value.length === 0)
+                throw failure("invalid_request", artifactId, "argument --cursor must be a non-empty opaque token");
+            cursor = parsed.value;
+        }
+        else {
+            if (name !== "--format") {
+                if (filterSupplied.has(name))
+                    throw failure("invalid_request", artifactId, `${name} may only be supplied once`);
+                filterSupplied.add(name);
+                const key = name.slice(2);
+                filters[key] = parsed.value;
+                continue;
+            }
+            if (formatSupplied)
+                throw failure("invalid_request", artifactId, "--format may only be supplied once");
+            formatSupplied = true;
+            if (parsed.value !== "text" && parsed.value !== "json" && parsed.value !== "yaml") {
+                throw failure("invalid_request", artifactId, `argument --format: invalid choice: '${parsed.value}' (choose from 'text', 'json', 'yaml')`);
+            }
+            format = parsed.value;
+        }
+    }
+    return { limit, ...(cursor ? { cursor } : {}), format, filters };
+}
+function emitFailure(error, format, io) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    if (format === "json" || format === "yaml")
+        emitStructured(error.body, format, out);
+    else {
+        const details = error.body.error;
+        out([
+            `Error: ${details.message}`,
+            `Class: ${details.class}`,
+            `Syntax: ${details.syntax}`,
+            `Example: ${details.example}`,
+            `Recovery: ${details.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return error.exitCode;
+}
+export function runStateList(artifactId, argv, io) {
+    const format = requestedFormat(argv);
+    const sourceRoot = resolveSourceRoot();
+    try {
+        const args = parseListArgs(artifactId, argv, sourceRoot);
+        const response = boundStateList(listStateEntries(process.cwd(), artifactId, args.limit, args.filters, args.cursor, { sourceRoot }), args.format === "text" ? "text" : args.format, sourceRoot, process.cwd());
+        const out = io.out ?? ((text) => process.stdout.write(text));
+        if (args.format === "text")
+            out(renderStateListText(response));
+        else
+            emitStructured(response, args.format, out);
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof StateRetrievalFailure)
+            return emitFailure(error, format, io);
+        return emitFailure(new StateRetrievalFailure({
+            schemaVersion: "agentera.stateFailure.v1",
+            status: "fail",
+            error: {
+                class: "unsupported_state",
+                message: error.message,
+                syntax: syntax(artifactId),
+                example: `agentera state ${artifactId} list --limit 20 --format json`,
+                recovery: "Use a state format supported by the storage authority, then retry.",
+            },
+        }, 1), format, io);
+    }
+}
+//# sourceMappingURL=list.js.map

package/dist/cli/commands/state/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../src/cli/commands/state/list.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/state/objective.js

@@ -0,0 +1,69 @@
+/**
+ * `state objective` query (OBJECTIVE.md / objective.yaml).
+ *
+ * Reports the single current objective plus its closure block (when
+ * status is "closed"), with the same envelope shape used by prime.
+ */
+import { asList, emitStateStructured, filterByFieldValue, formatEntry, loadArtifact, missingSchemaError, sourceMetadata, structuredState, truncate, } from "../../stateQuery.js";
+import { artifactPath } from "../../appContext.js";
+import { firstPresent } from "../../stateQuery.js";
+import { out, err } from "./shared.js";
+export function queryObjective(args, schemas, io) {
+    const o = out(io);
+    const e = err(io);
+    const info = schemas.objective;
+    if (!info) {
+        e(missingSchemaError("objective") + "\n");
+        return 1;
+    }
+    const p = artifactPath(info, "objective");
+    const data = loadArtifact(p);
+    const format = args.format ?? "text";
+    const isDict = data !== null && typeof data === "object" && !Array.isArray(data);
+    if (!isDict) {
+        if (format !== "text") {
+            return emitStateStructured("objective", structuredState("objective", [], sourceMetadata("objective", p), { filters: { status: args.status ?? null } }), format, args.fields, o, e);
+        }
+        return 0;
+    }
+    // cast: data is the parsed objective artifact from loadArtifact (YAML/MD IO boundary)
+    const d = data;
+    const legacyEntries = asList(d.entries);
+    if (legacyEntries.length > 0) {
+        let entries = legacyEntries;
+        const statusFilter = args.status ?? null;
+        if (statusFilter)
+            entries = filterByFieldValue(entries, "status", statusFilter);
+        if (format !== "text") {
+            return emitStateStructured("objective", structuredState("objective", entries, sourceMetadata("objective", p), { filters: { status: statusFilter } }), format, args.fields, o, e);
+        }
+        for (const entry of entries) {
+            const line = formatEntry(entry, ["title", "status", "target", "reason"]);
+            if (line)
+                o(line + "\n");
+        }
+        return 0;
+    }
+    const header = d.header && typeof d.header === "object" && !Array.isArray(d.header) ? d.header : {};
+    const objective = d.objective && typeof d.objective === "object" && !Array.isArray(d.objective) ? d.objective : d;
+    const title = firstPresent(header, ["title"], objective.title ?? "");
+    const status = firstPresent(header, ["status"], objective.status ?? "");
+    const closure = d.closure && typeof d.closure === "object" && !Array.isArray(d.closure) ? d.closure : {};
+    if (format !== "text") {
+        return emitStateStructured("objective", structuredState("objective", objective ? [objective] : [], sourceMetadata("objective", p), {
+            filters: { status: args.status ?? null },
+            summary: { title, status, header, closure },
+        }), format, args.fields, o, e);
+    }
+    o(`Objective: title=${truncate(title)} | status=${status || "unknown"}\n`);
+    for (const key of ["description", "target", "measurement", "direction", "unit"]) {
+        const value = objective[key] ?? d[key];
+        if (value)
+            o(`${key}: ${truncate(value)}\n`);
+    }
+    if (Object.keys(closure).length > 0) {
+        o(formatEntry(closure, ["final_value", "target", "reason"]) + "\n");
+    }
+    return 0;
+}
+//# sourceMappingURL=objective.js.map

package/dist/cli/commands/state/objective.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"objective.js","sourceRoot":"","sources":["../../../../src/cli/commands/state/objective.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/state/plan.js

@@ -0,0 +1,379 @@
+/**
+ * `state plan` query (active PLAN.yaml + immutable archive history).
+ *
+ * Source-contract builder for plan artifacts: declares the
+ * `complete_for_plan_artifact` / `complete_for_normal_startup_evaluation`
+ * flags that downstream capabilities (prime, orchestrate) read
+ * before raw plan access.
+ */
+import { emitStateStructured, filterByFieldValue, missingSchemaError, sourceMetadata, statusCounts, structuredState, } from "../../stateQuery.js";
+import { artifactPath } from "../../appContext.js";
+import { firstPresent } from "../../stateQuery.js";
+import { out, err } from "./shared.js";
+import { discoverPlanArtifacts, planDocumentParts, planCatalogEntry, } from "../../planArtifacts.js";
+import { planLifecycleState } from "../../planLifecycleState.js";
+import { resolvePlanTaskEvidence } from "../../planEvidence.js";
+const PLAN_HISTORY_CATALOG_LIMIT = 10;
+const PLAN_TEXT_TASK_LIMIT = 10;
+const PLAN_TEXT_MAX_UTF8_BYTES = 32_768;
+function planCatalogRetrieval() {
+    return {
+        list: "agentera state plan list --format json",
+        get: "agentera state plan get --plan PLAN_ID --format json",
+    };
+}
+function textScalar(value) {
+    return String(value).replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+}
+function taskTextRow(task) {
+    const parts = [];
+    for (const field of ["number", "status", "name", "title"]) {
+        const value = task[field];
+        if (value !== null && value !== undefined && value !== "" && !Array.isArray(value) && typeof value !== "object") {
+            parts.push(`${field}=${textScalar(value)}`);
+        }
+    }
+    return `Task: ${parts.join(" | ")}\n`;
+}
+function renderPlanText(data, tasks, summary, evidenceComplete, planId, diagnostics) {
+    const rows = [{
+            kind: "plan",
+            text: `Plan: status=${textScalar(summary.status ?? "unknown")} | title=${textScalar(summary.title ?? "")} | created=${textScalar(summary.created ?? "-")}\n`,
+        }];
+    if (!evidenceComplete)
+        rows.push({ kind: "plan", text: "Evidence: incomplete | missing authoritative task evidence\n" });
+    for (const diagnostic of diagnostics) {
+        rows.push({
+            kind: "plan",
+            text: `Plan diagnostic: path=${textScalar(diagnostic.path)} | category=${textScalar(diagnostic.category)} | diagnostic=${textScalar(diagnostic.message)}\n`,
+        });
+    }
+    for (const key of ["what", "why"]) {
+        if (data[key] !== null && data[key] !== undefined && data[key] !== "") {
+            rows.push({ kind: "plan", text: `${key}: ${textScalar(data[key])}\n` });
+        }
+    }
+    const counts = statusCounts(tasks);
+    if (Object.keys(counts).length > 0) {
+        rows.push({
+            kind: "plan",
+            text: `Task status: ${Object.keys(counts).sort().map((name) => `${name}=${counts[name]}`).join(", ")}\n`,
+        });
+    }
+    rows.push(...tasks.slice(0, PLAN_TEXT_TASK_LIMIT).map((task) => ({ kind: "task", text: taskTextRow(task) })));
+    const retained = [];
+    const countOmitted = Math.max(0, tasks.length - PLAN_TEXT_TASK_LIMIT);
+    let byteTaskOmitted = 0;
+    let bytePlanOmitted = 0;
+    const output = () => {
+        const lines = retained.map((row) => row.text);
+        const taskOmitted = countOmitted + byteTaskOmitted;
+        if (taskOmitted > 0) {
+            const reason = countOmitted > 0 && byteTaskOmitted > 0
+                ? "text_projection_limit_and_output_byte_budget"
+                : byteTaskOmitted > 0 ? "text_output_byte_budget" : "text_projection_limit";
+            lines.push(`Tasks omitted: ${taskOmitted} | reason=${reason}\n`);
+            lines.push("Continue: agentera state plan tasks list --format json\n");
+            lines.push("Get one: agentera state plan tasks get --task N --format json\n");
+        }
+        if (bytePlanOmitted > 0) {
+            lines.push(`Plan fields omitted: ${bytePlanOmitted} | reason=text_output_byte_budget\n`);
+            lines.push(`Get plan: agentera state plan get --plan ${planId} --format json\n`);
+        }
+        return lines.join("");
+    };
+    for (const row of rows) {
+        retained.push(row);
+        while (Buffer.byteLength(output(), "utf8") > PLAN_TEXT_MAX_UTF8_BYTES) {
+            const omitted = retained.pop();
+            if (!omitted)
+                break;
+            if (omitted.kind === "task")
+                byteTaskOmitted += 1;
+            else
+                bytePlanOmitted += 1;
+        }
+    }
+    return output();
+}
+function planArtifactSummary(artifact) {
+    const { data } = artifact;
+    const parts = planDocumentParts(data);
+    const header = { ...parts.header, status: parts.status };
+    const summary = {
+        header,
+        title: firstPresent(header, ["title"], data.title ?? ""),
+        status: parts.status,
+        created: firstPresent(header, ["created"], data.created ?? ""),
+        what: data.what,
+        why: data.why,
+        constraints: data.constraints,
+        scope: data.scope,
+        design: data.design,
+        overall_acceptance: data.overall_acceptance,
+        surprises: data.surprises,
+        previous_plan_archived: data.previous_plan_archived,
+    };
+    const out = {};
+    for (const [k, v] of Object.entries(summary)) {
+        if (v !== null && v !== undefined && v !== "")
+            out[k] = v;
+    }
+    return out;
+}
+function planSource(primary, discovery) {
+    const source = sourceMetadata("plan", primary?.path ?? discovery.activePath);
+    const archivePaths = discovery.archived.map((artifact) => artifact.path);
+    source.active = Boolean(discovery.active);
+    source.archived = Boolean(primary?.archived);
+    source.active_path = discovery.activePath;
+    source.archive_count = archivePaths.length;
+    source.archive_paths = archivePaths.slice(0, PLAN_HISTORY_CATALOG_LIMIT);
+    const archivePathsOmitted = Math.max(0, archivePaths.length - PLAN_HISTORY_CATALOG_LIMIT);
+    source.archive_paths_omitted = archivePathsOmitted > 0;
+    source.archive_paths_omitted_count = archivePathsOmitted;
+    source.archive_paths_omission_reason = archivePathsOmitted > 0 ? "archive_path_catalog_limit" : null;
+    source.archive_paths_retrieval = {
+        list: "agentera state plan list --format json",
+        get: "agentera state plan get --plan PLAN_ID --format json",
+    };
+    if (discovery.diagnostics.length > 0)
+        source.diagnostics = discovery.diagnostics;
+    const activeDiagnostics = discovery.diagnostics.filter((diagnostic) => diagnostic.path === discovery.activePath && diagnostic.category !== "legacy");
+    if (activeDiagnostics.length > 0)
+        source.invalid_path = discovery.activePath;
+    if (primary && discovery.diagnostics.some((diagnostic) => diagnostic.path === primary.path && diagnostic.category === "legacy")) {
+        source.legacy_input = true;
+    }
+    if (discovery.invalidArchivePaths.length > 0)
+        source.invalid_archive_paths = discovery.invalidArchivePaths;
+    return source;
+}
+function planCatalog(discovery) {
+    const artifacts = [
+        ...(discovery.active ? [discovery.active] : []),
+        ...discovery.archived,
+    ];
+    return artifacts
+        .slice(0, PLAN_HISTORY_CATALOG_LIMIT)
+        .map((artifact) => planCatalogEntry(artifact, discovery.activePath, discovery.identities.find((identity) => identity.artifact.path === artifact.path)));
+}
+function activePlanDiagnostics(discovery) {
+    return discovery.diagnostics.filter((diagnostic) => diagnostic.path === discovery.activePath && diagnostic.category !== "legacy");
+}
+function planSourceContract(source, summary, discovery) {
+    const legacyEntries = Boolean(summary.legacy_entries);
+    const evidenceIncomplete = summary.evidence_status === "incomplete";
+    const currentDiagnostics = activePlanDiagnostics(discovery);
+    const active = source.active === true;
+    const verifiedAbsence = !active && currentDiagnostics.length === 0;
+    const lifecycle = planLifecycleState({
+        exists: source.exists,
+        active: source.active,
+        active_path: source.active_path,
+        diagnostics: currentDiagnostics,
+    });
+    const complete = verifiedAbsence ||
+        (Boolean(source.exists) &&
+            !legacyEntries &&
+            !evidenceIncomplete &&
+            currentDiagnostics.length === 0 &&
+            lifecycle.current_plan_degraded !== true);
+    const startupComplete = complete;
+    const missingState = [];
+    if (!source.exists && !verifiedAbsence)
+        missingState.push("plan artifact");
+    else if (!active && !verifiedAbsence)
+        missingState.push("active plan artifact");
+    if (legacyEntries)
+        missingState.push("current plan task artifact shape");
+    if (evidenceIncomplete)
+        missingState.push("task evidence");
+    if (currentDiagnostics.length > 0)
+        missingState.push("valid current plan artifact");
+    const summaryFields = Object.keys(summary).sort();
+    const entryFields = [
+        "number",
+        "name",
+        "depends_on",
+        "status",
+        "acceptance",
+        "evidence",
+        "evidence_status",
+        "evidence_provenance",
+        "blocked_reason",
+    ];
+    return {
+        artifact: "plan",
+        canonical_artifact_label: "plan",
+        persisted_artifact_path: source.path,
+        active_plan_path: discovery.activePath,
+        active_plan_exists: active,
+        archived_plan_count: discovery.archived.length,
+        archive_paths: discovery.archived
+            .slice(0, PLAN_HISTORY_CATALOG_LIMIT)
+            .map((artifact) => artifact.path),
+        archive_paths_omitted: discovery.archived.length > PLAN_HISTORY_CATALOG_LIMIT,
+        archive_paths_omitted_count: Math.max(0, discovery.archived.length - PLAN_HISTORY_CATALOG_LIMIT),
+        archive_paths_omission_reason: discovery.archived.length > PLAN_HISTORY_CATALOG_LIMIT ? "archive_path_catalog_limit" : null,
+        archive_paths_retrieval: {
+            list: "agentera state plan list --format json",
+            get: "agentera state plan get --plan PLAN_ID --format json",
+        },
+        invalid_archive_paths: discovery.invalidArchivePaths,
+        lifecycle_state: lifecycle,
+        complete_for_plan_artifact: complete,
+        complete_for_normal_startup_evaluation: startupComplete,
+        raw_artifact_reads_required: false,
+        raw_artifact_read_policy: "Use `agentera state plan --format json` entries, summary, source, and source_contract before raw plan access. " +
+            "When complete_for_plan_artifact is true, skip defensive `.agentera/plan.yaml` reads during normal read-only " +
+            "plan startup/evaluation; raw plan artifact access is reserved for writes, archival, validation, corruption " +
+            "diagnostics, or unavailable/incomplete CLI state.",
+        included_state: [
+            "header",
+            "what",
+            "why",
+            "constraints",
+            "scope",
+            "design",
+            "tasks",
+            "task dependencies",
+            "task acceptance criteria",
+            "task evidence",
+            "task evidence provenance",
+            "overall_acceptance",
+            "surprises",
+            "previous_plan_archived",
+            "archived plan history",
+        ],
+        complete_state: {
+            summary: summaryFields,
+            entries: entryFields,
+            normal_startup_evaluation: startupComplete,
+        },
+        raw_artifact_access_boundary: {
+            normal_read_only_startup_evaluation: "skip raw plan artifact reads when complete_for_plan_artifact is true",
+            allowed_raw_artifact_uses: [
+                "artifact writes",
+                "plan archival",
+                "artifact validation",
+                "corruption diagnostics",
+                "unavailable or incomplete CLI state after CLI fallbacks",
+            ],
+        },
+        missing_state: missingState,
+        fallback: complete ? [] : ["agentera docs --format json"],
+        fallback_policy: "When plan CLI output is missing or incomplete, use supported CLI state such as `agentera docs --format json` " +
+            "for artifact mapping before any last-resort raw plan artifact read.",
+        summary_fields: summaryFields,
+        entry_fields: entryFields,
+    };
+}
+export function queryPlan(args, schemas, io) {
+    const o = out(io);
+    const e = err(io);
+    const info = schemas.plan;
+    if (!info) {
+        e(missingSchemaError("plan") + "\n");
+        return 1;
+    }
+    const p = artifactPath(info, "plan");
+    const discovery = discoverPlanArtifacts(p);
+    const currentDiagnostics = activePlanDiagnostics(discovery);
+    // Archived plans are immutable history, never executable current state.
+    // Keep them in the catalog instead of promoting the newest archive to the
+    // current plan when the active artifact is absent.
+    const primary = discovery.active;
+    const format = args.format ?? "text";
+    const catalog = planCatalog(discovery);
+    const catalogTotal = (discovery.active ? 1 : 0) + discovery.archived.length;
+    if (!primary) {
+        if (format !== "text") {
+            const source = planSource(null, discovery);
+            const lifecycle = planLifecycleState({
+                exists: false,
+                active: false,
+                active_path: discovery.activePath,
+                diagnostics: currentDiagnostics,
+            });
+            const summary = lifecycle.status === "degraded"
+                ? {
+                    invalid_path: discovery.activePath,
+                    diagnostic: currentDiagnostics[0] ?? discovery.diagnostics.find((diagnostic) => diagnostic.category !== "legacy"),
+                    absence_reason: "Current plan artifact is invalid.",
+                }
+                : { absence_reason: "No active plan exists." };
+            summary.lifecycle_state = lifecycle;
+            const payload = structuredState("plan", [], source, {
+                filters: { status: args.status ?? null },
+                summary,
+                sourceContract: planSourceContract(source, summary, discovery),
+            });
+            if (lifecycle.current_plan_degraded === true)
+                payload.status = "incomplete";
+            payload.plans = catalog;
+            payload.plan_catalog = {
+                total: catalogTotal,
+                returned: catalog.length,
+                omitted: catalogTotal > catalog.length,
+                omitted_count: Math.max(0, catalogTotal - catalog.length),
+                omission_reason: catalogTotal > catalog.length ? "archive_catalog_limit" : null,
+                retrieval: planCatalogRetrieval(),
+            };
+            return emitStateStructured("plan", payload, format, args.fields, o, e);
+        }
+        const [diagnostic] = activePlanDiagnostics(discovery);
+        if (diagnostic) {
+            o(`Plan: invalid | path=${diagnostic.path} | category=${diagnostic.category} | diagnostic=${diagnostic.message}\n`);
+        }
+        return 0;
+    }
+    const dataDict = primary.data;
+    const parts = planDocumentParts(dataDict);
+    const evidence = resolvePlanTaskEvidence(primary, parts.tasks, schemas);
+    const summary = {
+        ...planArtifactSummary(primary),
+        ...(parts.legacyEntries ? { legacy_entries: true } : {}),
+    };
+    if (currentDiagnostics.length > 0) {
+        summary.invalid_path = discovery.activePath;
+        summary.current_plan_diagnostic = currentDiagnostics[0];
+    }
+    summary.evidence_status = evidence.complete ? "complete" : "incomplete";
+    summary.evidence_sources = evidence.sources;
+    let tasks = evidence.tasks;
+    const statusFilter = args.status ?? null;
+    if (statusFilter)
+        tasks = filterByFieldValue(tasks, "status", statusFilter);
+    const source = planSource(primary, discovery);
+    const lifecycle = planLifecycleState({
+        exists: source.active === true || source.archived === true,
+        active: source.active,
+        active_path: source.active_path,
+        diagnostics: currentDiagnostics,
+    });
+    summary.lifecycle_state = lifecycle;
+    if (format !== "text") {
+        const payload = structuredState("plan", tasks, source, {
+            filters: { status: statusFilter },
+            summary,
+            sourceContract: planSourceContract(source, summary, discovery),
+        });
+        if (!evidence.complete || lifecycle.current_plan_degraded === true)
+            payload.status = "incomplete";
+        payload.plans = catalog;
+        payload.plan_catalog = {
+            total: catalogTotal,
+            returned: catalog.length,
+            omitted: catalogTotal > catalog.length,
+            omitted_count: Math.max(0, catalogTotal - catalog.length),
+            omission_reason: catalogTotal > catalog.length ? "archive_catalog_limit" : null,
+            retrieval: planCatalogRetrieval(),
+        };
+        return emitStateStructured("plan", payload, format, args.fields, o, e);
+    }
+    const identity = discovery.identities.find((candidate) => candidate.artifact.path === primary.path);
+    o(renderPlanText(dataDict, tasks, summary, evidence.complete, identity?.stableId ?? "PLAN_ID", currentDiagnostics));
+    return 0;
+}
+//# sourceMappingURL=plan.js.map