agentera 3.0.0-dev.5 → 3.0.0-dev.7

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

@@ -0,0 +1,116 @@
+/**
+ * `state health` query (HEALTH.md / health.yaml audits).
+ *
+ * Surfaces the latest health audit by `number`, optionally filtered
+ * by dimension (a grade key or a dimensions_detail.name substring).
+ */
+import { asList, emitStateStructured, extractEntries, loadArtifact, missingSchemaError, sourceMetadata, structuredState, } from "../../stateQuery.js";
+import { artifactPath } from "../../appContext.js";
+import { out, err } from "./shared.js";
+export function healthAuditNumber(entry) {
+    const number = entry.number;
+    if (typeof number === "number" && Number.isInteger(number))
+        return number;
+    if (typeof number === "string" && /^\d+$/.test(number))
+        return parseInt(number, 10);
+    return null;
+}
+export function latestHealthAudit(entries) {
+    if (entries.length === 0)
+        return null;
+    let best = null;
+    let bestNumber = -1;
+    for (const entry of entries) {
+        const number = healthAuditNumber(entry);
+        if (number === null)
+            continue;
+        if (number > bestNumber) {
+            bestNumber = number;
+            best = entry;
+        }
+    }
+    return best !== null ? best : entries[entries.length - 1];
+}
+export function queryHealth(args, schemas, io) {
+    const o = out(io);
+    const e = err(io);
+    const info = schemas.health;
+    if (!info) {
+        e(missingSchemaError("health") + "\n");
+        return 1;
+    }
+    const p = artifactPath(info, "health");
+    const data = loadArtifact(p);
+    const entries = extractEntries(data);
+    const dimension = args.dimension ?? null;
+    let latest = latestHealthAudit(entries);
+    let latestEntries = latest ? [latest] : [];
+    if (dimension && latestEntries.length > 0) {
+        latest = latestEntries[0];
+        const dimLower = dimension.toLowerCase();
+        let matched = false;
+        const grades = latest.grades;
+        if (grades && typeof grades === "object" && !Array.isArray(grades)) {
+            matched = Object.keys(grades).some((gk) => String(gk).toLowerCase().includes(dimLower));
+        }
+        const details = latest.dimensions_detail;
+        if (Array.isArray(details)) {
+            matched =
+                matched ||
+                    details.some((d) => d && typeof d === "object" && !Array.isArray(d) && String(d.name ?? "").toLowerCase().includes(dimLower));
+        }
+        if (!matched)
+            latestEntries = [];
+    }
+    const format = args.format ?? "text";
+    if (format !== "text") {
+        return emitStateStructured("health", structuredState("health", latestEntries, sourceMetadata("health", p), {
+            filters: { dimension },
+            summary: { latest_only: true },
+        }), format, args.fields, o, e);
+    }
+    if (entries.length === 0)
+        return 0;
+    latest = latestHealthAudit(entries);
+    if (!latest)
+        return 0;
+    if (dimension) {
+        const dimLower = dimension.toLowerCase();
+        // cast: latest.grades is read from a parsed health.yaml audit entry (IO boundary)
+        const grades = (latest.grades ?? {});
+        let matched = false;
+        for (const [gk, gv] of Object.entries(grades)) {
+            if (String(gk).toLowerCase().includes(dimLower)) {
+                o(`${gk}: ${gv}\n`);
+                matched = true;
+            }
+        }
+        const details = asList(latest.dimensions_detail);
+        for (const d of details) {
+            const dn = String(d.name ?? "");
+            if (dn.toLowerCase().includes(dimLower)) {
+                const summary = d.summary ?? "";
+                if (summary)
+                    o(`  ${summary}\n`);
+                for (const f of asList(d.findings)) {
+                    o(`  [${f.severity ?? ""}] ${f.heading ?? ""}\n`);
+                }
+                matched = true;
+            }
+        }
+        if (!matched)
+            return 0;
+    }
+    else {
+        const num = latest.number ?? "?";
+        const traj = latest.trajectory ?? "";
+        o(`Audit ${num}: ${traj}\n`);
+        // cast: latest.grades is read from a parsed health.yaml audit entry (IO boundary)
+        const grades = (latest.grades ?? {});
+        for (const [gk, gv] of Object.entries(grades)) {
+            o(`  ${gk}: ${gv}\n`);
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=health.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * Public surface for the `state <name>` command family.
+ *
+ * The `cmdState` entry point validates the incoming args, loads the
+ * schema directory, and dispatches to the per-state-family handler
+ * in `STATE_COMMAND_HANDLERS`. The `isPortedStateCommand` predicate
+ * is the public surface used by `cli/dispatch.ts` to decide whether
+ * a top-level token is a state command or a deprecated alias.
+ */
+import { COMMAND_FILTERS, validateFilterValues } from "../../stateQuery.js";
+import { loadSchemas, discoverSchemasDir } from "../../appContext.js";
+import { err } from "./shared.js";
+import { queryProgress } from "./progress.js";
+import { queryPlan } from "./plan.js";
+import { queryHealth, healthAuditNumber, latestHealthAudit } from "./health.js";
+import { queryDocs } from "./docs.js";
+import { queryObjective } from "./objective.js";
+import { queryExperiments } from "./experiments.js";
+import { queryTodo, normalizeSeverity } from "./todo.js";
+import { queryDecisions, decisionContextEntry, decisionSatisfactionContext, decisionSourceContract, extractDecisionEntries, displayFields, } from "./decisions.js";
+export { queryProgress, queryPlan, queryHealth, queryDocs, queryObjective, queryExperiments, queryTodo, queryDecisions, healthAuditNumber, latestHealthAudit, normalizeSeverity, decisionContextEntry, decisionSatisfactionContext, decisionSourceContract, extractDecisionEntries, displayFields, };
+const STATE_COMMAND_HANDLERS = {
+    progress: queryProgress,
+    plan: queryPlan,
+    health: queryHealth,
+    docs: queryDocs,
+    objective: queryObjective,
+    experiments: queryExperiments,
+    todo: queryTodo,
+    decisions: queryDecisions,
+};
+export function isPortedStateCommand(command) {
+    return command in STATE_COMMAND_HANDLERS;
+}
+export function cmdState(args, io) {
+    const e = err(io);
+    try {
+        validateFilterValues(args, COMMAND_FILTERS[args.command] ?? []);
+        if (args.limit !== null && args.limit !== undefined && args.limit < 0) {
+            throw new Error("limit must be zero or greater");
+        }
+        const schemas = loadSchemas(discoverSchemasDir());
+        const handler = STATE_COMMAND_HANDLERS[args.command];
+        return handler(args, schemas, io);
+    }
+    catch (exc) {
+        e(`Error: ${exc.message}\n`);
+        return 2;
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cli/commands/state/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAiB,GAAG,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,GACd,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,aAAa,EACb,SAAS,EACT,WAAW,EACX,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,GACd,CAAC;AAEF,MAAM,sBAAsB,GAGxB;IACF,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,SAAS;IACf,MAAM,EAAE,WAAW;IACnB,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,cAAc;IACzB,WAAW,EAAE,gBAAgB;IAC7B,IAAI,EAAE,SAAS;IACf,SAAS,EAAE,cAAc;CAC1B,CAAC;AAEF,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,OAAO,IAAI,sBAAsB,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAe,EAAE,EAAM;IAC9C,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,IAAI,CAAC;QACH,oBAAoB,CAAC,IAAW,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QACvE,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,kBAAkB,EAAE,CAAC,CAAC;QAClD,MAAM,OAAO,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrD,OAAO,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,CAAC,CAAC,UAAW,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;QACxC,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC"}

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,173 @@
+/**
+ * `state plan` query (active PLAN.yaml → summary + task list).
+ *
+ * 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 { asList, emitStateStructured, filterByFieldValue, formatEntry, loadArtifact, missingSchemaError, printStatusCounts, sourceMetadata, statusCounts, structuredState, truncate, } from "../../stateQuery.js";
+import { artifactPath } from "../../appContext.js";
+import { firstPresent } from "../../stateQuery.js";
+import { out, err } from "./shared.js";
+function planArtifactSummary(data, header) {
+    const summary = {
+        header,
+        title: firstPresent(header, ["title"], data.title ?? ""),
+        status: firstPresent(header, ["status"], data.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 planSourceContract(source, summary) {
+    const legacyEntries = Boolean(summary.legacy_entries);
+    const complete = Boolean(source.exists) && !legacyEntries;
+    const missingState = [];
+    if (!source.exists)
+        missingState.push("plan artifact");
+    if (legacyEntries)
+        missingState.push("current plan task artifact shape");
+    const summaryFields = Object.keys(summary).sort();
+    const entryFields = ["number", "name", "depends_on", "status", "acceptance", "evidence", "blocked_reason"];
+    return {
+        artifact: "plan",
+        canonical_artifact_label: "plan",
+        persisted_artifact_path: source.path,
+        complete_for_plan_artifact: complete,
+        complete_for_normal_startup_evaluation: complete,
+        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",
+            "overall_acceptance",
+            "surprises",
+            "previous_plan_archived",
+        ],
+        complete_state: {
+            summary: summaryFields,
+            entries: entryFields,
+            normal_startup_evaluation: complete,
+        },
+        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 data = loadArtifact(p);
+    const isDict = data !== null && typeof data === "object" && !Array.isArray(data);
+    const format = args.format ?? "text";
+    if (!isDict) {
+        if (format !== "text") {
+            const source = sourceMetadata("plan", p);
+            const summary = { absence_reason: "No plan artifact is available from agentera plan." };
+            return emitStateStructured("plan", structuredState("plan", [], source, {
+                filters: { status: args.status ?? null },
+                summary,
+                sourceContract: planSourceContract(source, summary),
+            }), format, args.fields, o, e);
+        }
+        return 0;
+    }
+    // cast: data is the parsed plan artifact from loadArtifact (YAML IO boundary)
+    const dataDict = data;
+    const legacyEntries = asList(dataDict.entries);
+    if (legacyEntries.length > 0) {
+        let entries = legacyEntries;
+        const statusFilter = args.status ?? null;
+        if (statusFilter)
+            entries = filterByFieldValue(entries, "status", statusFilter);
+        const source = sourceMetadata("plan", p);
+        const summary = { legacy_entries: true };
+        if (format !== "text") {
+            return emitStateStructured("plan", structuredState("plan", entries, source, {
+                filters: { status: statusFilter },
+                summary,
+                sourceContract: planSourceContract(source, summary),
+            }), format, args.fields, o, e);
+        }
+        for (const entry of entries) {
+            const line = formatEntry(entry, ["status", "title", "name"]);
+            if (line)
+                o(line + "\n");
+        }
+        return 0;
+    }
+    const header = dataDict.header && typeof dataDict.header === "object" && !Array.isArray(dataDict.header) ? dataDict.header : {};
+    const summary = planArtifactSummary(dataDict, header);
+    const title = summary.title ?? "";
+    const status = summary.status ?? "";
+    const created = summary.created ?? "";
+    let tasks = asList(dataDict.tasks);
+    const statusFilter = args.status ?? null;
+    if (statusFilter)
+        tasks = filterByFieldValue(tasks, "status", statusFilter);
+    const source = sourceMetadata("plan", p);
+    if (format !== "text") {
+        return emitStateStructured("plan", structuredState("plan", tasks, source, {
+            filters: { status: statusFilter },
+            summary,
+            sourceContract: planSourceContract(source, summary),
+        }), format, args.fields, o, e);
+    }
+    o(`Plan: status=${status || "unknown"} | title=${truncate(title)} | created=${created || "-"}\n`);
+    for (const key of ["what", "why"]) {
+        const value = dataDict[key];
+        if (value)
+            o(`${key}: ${truncate(value)}\n`);
+    }
+    printStatusCounts("Task status", statusCounts(tasks), o);
+    for (const task of tasks.slice(0, 10)) {
+        const line = formatEntry(task, ["number", "status", "name", "title"]);
+        if (line)
+            o(`Task: ${line}\n`);
+    }
+    return 0;
+}
+//# sourceMappingURL=plan.js.map

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

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

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

@@ -0,0 +1,47 @@
+/**
+ * `state progress` query (PROGRESS.md / progress.yaml cycles).
+ *
+ * Reports the most recent N cycles (default 5), filtered by topic or
+ * type, with a structured envelope that downstream prime callers
+ * use to surface progress_verification without raw artifact reads.
+ */
+import { emitStateStructured, extractEntries, filterByFieldValue, filterByTopic, formatEntry, loadArtifact, missingSchemaError, progressEntriesForOutput, recentCycles, sourceMetadata, structuredState, truncate, } from "../../stateQuery.js";
+import { artifactPath } from "../../appContext.js";
+import { out, err } from "./shared.js";
+export function queryProgress(args, schemas, io) {
+    const o = out(io);
+    const e = err(io);
+    const info = schemas.progress;
+    if (!info) {
+        e(missingSchemaError("progress") + "\n");
+        return 1;
+    }
+    const p = artifactPath(info, "progress");
+    const data = loadArtifact(p);
+    let entries = extractEntries(data);
+    const topic = args.topic ?? null;
+    if (topic)
+        entries = filterByTopic(entries, topic, info.fields);
+    const statusFilter = args.status ?? null;
+    if (statusFilter)
+        entries = filterByFieldValue(entries, "type", statusFilter);
+    const effectiveLimit = (args.limit ?? 5) || 5;
+    entries = recentCycles(entries, effectiveLimit);
+    if ((args.format ?? "text") !== "text") {
+        return emitStateStructured("progress", structuredState("progress", progressEntriesForOutput(entries), sourceMetadata("progress", p), {
+            filters: { topic, status: statusFilter, limit: effectiveLimit },
+        }), args.format ?? "text", args.fields, o, e);
+    }
+    if (entries.length === 0)
+        return 0;
+    for (const entry of entries) {
+        o(formatEntry(entry, ["number", "timestamp", "type", "phase"]) + "\n");
+        for (const key of ["what", "verified", "next"]) {
+            const value = entry[key];
+            if (value)
+                o(`  ${key}: ${truncate(value)}\n`);
+        }
+    }
+    return 0;
+}
+//# sourceMappingURL=progress.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../../src/cli/commands/state/progress.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,YAAY,EACZ,cAAc,EACd,eAAe,EACf,QAAQ,GACT,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAc,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,GAAG,EAAE,GAAG,EAAiB,MAAM,aAAa,CAAC;AAEtD,MAAM,UAAU,aAAa,CAAC,IAAe,EAAE,OAAmC,EAAE,EAAM;IACxF,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,MAAM,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,CAAC,CAAC,kBAAkB,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;QACzC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;IACjC,IAAI,KAAK;QAAE,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC;IACzC,IAAI,YAAY;QAAE,OAAO,GAAG,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IAC9E,MAAM,cAAc,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;IAC9C,OAAO,GAAG,YAAY,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAEhD,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,MAAM,EAAE,CAAC;QACvC,OAAO,mBAAmB,CACxB,UAAU,EACV,eAAe,CAAC,UAAU,EAAE,wBAAwB,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE;YAC5F,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,EAAE;SAChE,CAAC,EACF,IAAI,CAAC,MAAM,IAAI,MAAM,EACrB,IAAI,CAAC,MAAM,EACX,CAAC,EACD,CAAC,CACF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACnC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACvE,KAAK,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,CAAC;YAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;YACzB,IAAI,KAAK;gBAAE,CAAC,CAAC,KAAK,GAAG,KAAK,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}

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

@@ -0,0 +1,15 @@
+/**
+ * Shared types and helpers for the per-state-family query modules.
+ *
+ * The state command family is split into one module per state
+ * artifact (plan, progress, health, docs, objective, experiments,
+ * todo, decisions). They all share the StateArgs/Io shape and the
+ * stdout/stderr write helpers.
+ */
+export function out(io) {
+    return io.out ?? ((t) => process.stdout.write(t));
+}
+export function err(io) {
+    return io.err ?? ((t) => process.stderr.write(t));
+}
+//# sourceMappingURL=shared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../../src/cli/commands/state/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,MAAM,UAAU,GAAG,CAAC,EAAM;IACxB,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,GAAG,CAAC,EAAM;IACxB,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5D,CAAC"}

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

@@ -0,0 +1,121 @@
+/**
+ * `state todo` query (TODO.md).
+ *
+ * Reads TODO.md, partitions entries by severity band (using the
+ * protocol glyphs as the section heading), and reports each entry
+ * with its severity, status, and description. Supports both the
+ * legacy structured YAML shape and the current markdown layout.
+ */
+import fs from "node:fs";
+import { emitStateStructured, extractEntries, filterByFieldValue, formatEntry, loadArtifact, printStatusCounts, sourceMetadata, statusCounts, structuredState, } from "../../stateQuery.js";
+import { artifactPath } from "../../appContext.js";
+import { isResolvedTodoMarkdownStatus, parseTodoMarkdownListItem } from "../../todoMarkdown.js";
+import { TODO_SEVERITY_ORDER_KEYS } from "../../todoSeverity.js";
+import { out, err } from "./shared.js";
+const TODO_SEV_GLYPHS = {
+    critical: "⇶",
+    degraded: "⇉",
+    warning: "⇉",
+    normal: "→",
+    info: "⇢",
+    annoying: "⇢",
+};
+export function normalizeSeverity(value, deflt = "normal") {
+    const text = String(value || deflt).toLowerCase();
+    for (const key of TODO_SEVERITY_ORDER_KEYS) {
+        if (text.includes(key))
+            return key;
+    }
+    return deflt;
+}
+export function queryTodo(args, schemas, io, openOnly = false) {
+    const o = out(io);
+    const info = schemas.todo ?? { path: "TODO.md", record: undefined, schema: {}, fields: {} };
+    const todoPath = artifactPath(info, "todo");
+    const severity = args.severity ?? null;
+    const status = args.status ?? null;
+    const format = args.format ?? "text";
+    if (!fs.existsSync(todoPath)) {
+        if (format !== "text") {
+            return emitStateStructured("todo", structuredState("todo", [], sourceMetadata("todo", todoPath), {
+                filters: { severity, status },
+            }), format, args.fields, o, err(io));
+        }
+        return 0;
+    }
+    const data = loadArtifact(todoPath);
+    let entries = extractEntries(data);
+    if (entries.length > 0) {
+        if (severity)
+            entries = filterByFieldValue(entries, "severity", severity);
+        if (status)
+            entries = filterByFieldValue(entries, "status", status);
+        if (openOnly) {
+            entries = entries.filter((entry) => !["done", "closed", "resolved"].includes(String(entry.status ?? "open").toLowerCase()));
+        }
+        if (format !== "text") {
+            return emitStateStructured("todo", structuredState("todo", entries, sourceMetadata("todo", todoPath), {
+                filters: { severity, status, open_only: openOnly || null },
+            }), format, args.fields, o, err(io));
+        }
+        printStatusCounts("TODO status", statusCounts(entries), o);
+        for (const entry of entries) {
+            const line = formatEntry(entry, ["severity", "status", "description", "title"]);
+            if (line)
+                o(line + "\n");
+        }
+        return 0;
+    }
+    const text = fs.readFileSync(todoPath, "utf8");
+    const marker = severity ? TODO_SEV_GLYPHS[severity.toLowerCase()] ?? severity : null;
+    let currentSection = null;
+    const markdownEntries = [];
+    for (const rawLine of text.split(/\r\n|\r|\n/)) {
+        const sline = rawLine.trim();
+        if (sline.startsWith("## ")) {
+            const section = sline.slice(3).trim();
+            if (section.toLowerCase().includes("resolved")) {
+                currentSection = null;
+                continue;
+            }
+            currentSection = section;
+            continue;
+        }
+        if (currentSection === null)
+            continue;
+        const parsed = parseTodoMarkdownListItem(sline);
+        if (!parsed)
+            continue;
+        if (marker && !currentSection.includes(marker))
+            continue;
+        const itemStatus = parsed.status;
+        if (openOnly && isResolvedTodoMarkdownStatus(itemStatus))
+            continue;
+        if (status) {
+            const want = status.toLowerCase();
+            const have = itemStatus.toLowerCase();
+            if (want === "open" || want === "todo") {
+                if (isResolvedTodoMarkdownStatus(have))
+                    continue;
+            }
+            else if (have !== want) {
+                continue;
+            }
+        }
+        markdownEntries.push({
+            severity: normalizeSeverity(currentSection),
+            status: itemStatus,
+            description: parsed.description,
+            section: currentSection,
+        });
+        if (format === "text")
+            o(`[${currentSection}] ${parsed.description}\n`);
+    }
+    if (format !== "text") {
+        return emitStateStructured("todo", structuredState("todo", markdownEntries, sourceMetadata("todo", todoPath), {
+            filters: { severity, status, open_only: openOnly || null },
+        }), format, args.fields, o, err(io));
+    }
+    return 0;
+}
+//# sourceMappingURL=todo.js.map