agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/cli/profileAcquisition.js

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+import { TextDecoder } from "node:util";
+import { personalProfileGrounding, PersonalGlossaryBoundaryError, } from "../analytics/personalGlossaryProfile.js";
+import { personalProfileGroundingContract } from "../registries/glossaryEntryContract.js";
+import { discoverSchemasDir } from "./appContext.js";
+import { parseProfileHeaderDates, registryArtifactPath } from "./orientation.js";
+const DEFAULT_STALE_DAYS = 7;
+const STALE_DAYS_ENV = "AGENTERA_PROFILE_MAX_AGE_DAYS";
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode;
+}
+function sameSnapshot(left, right) {
+    return sameIdentity(left, right)
+        && left.size === right.size
+        && left.mtimeNs === right.mtimeNs
+        && left.ctimeNs === right.ctimeNs;
+}
+/** Read one path without following a final symlink and reject source changes. */
+export function readProfileSourceSafely(profilePath, maxBytes, hooks = {}) {
+    let pathSnapshot;
+    try {
+        pathSnapshot = fs.lstatSync(profilePath, { bigint: true });
+    }
+    catch (error) {
+        return { status: errorCode(error) === "ENOENT" ? "absent" : "unreadable" };
+    }
+    if (!pathSnapshot.isFile() || pathSnapshot.isSymbolicLink())
+        return { status: "unsafe" };
+    hooks.afterPathSnapshot?.();
+    let fd;
+    try {
+        const noFollow = hooks.noFollowFlag ?? (fs.constants.O_NOFOLLOW ?? 0);
+        fd = fs.openSync(profilePath, fs.constants.O_RDONLY | noFollow);
+    }
+    catch (error) {
+        return { status: errorCode(error) === "ELOOP" ? "unsafe" : "unreadable" };
+    }
+    try {
+        const opened = fs.fstatSync(fd, { bigint: true });
+        if (!opened.isFile() || !sameIdentity(pathSnapshot, opened))
+            return { status: "unsafe" };
+        if (opened.size > BigInt(maxBytes))
+            return { status: "oversized" };
+        hooks.afterOpen?.();
+        const bytes = Buffer.alloc(maxBytes + 1);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const read = fs.readSync(fd, bytes, offset, bytes.length - offset, offset);
+            if (read === 0)
+                break;
+            offset += read;
+        }
+        hooks.afterRead?.();
+        const afterRead = fs.fstatSync(fd, { bigint: true });
+        let currentPath;
+        try {
+            currentPath = fs.lstatSync(profilePath, { bigint: true });
+        }
+        catch {
+            return { status: "unsafe" };
+        }
+        if (!sameSnapshot(opened, afterRead) || !sameSnapshot(afterRead, currentPath)) {
+            return { status: "unsafe" };
+        }
+        if (offset > maxBytes)
+            return { status: "oversized" };
+        return { status: "ok", bytes: bytes.subarray(0, offset) };
+    }
+    catch {
+        return { status: "unreadable" };
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // The acquisition already has a bounded result; close diagnostics are private.
+        }
+    }
+}
+function staleThreshold(env) {
+    const parsed = Number.parseInt(env[STALE_DAYS_ENV] ?? String(DEFAULT_STALE_DAYS), 10);
+    return Number.isNaN(parsed) || parsed < 0 ? DEFAULT_STALE_DAYS : parsed;
+}
+function unknownFreshness(env) {
+    return {
+        state: "unknown",
+        days_since_generated: null,
+        stale_threshold_days: staleThreshold(env),
+        generated_date: null,
+        validated_date: null,
+    };
+}
+function freshness(text, env) {
+    const dates = parseProfileHeaderDates(text);
+    const anchor = dates.generatedUtc === null
+        ? dates.validatedUtc
+        : dates.validatedUtc === null
+            ? dates.generatedUtc
+            : Math.max(dates.generatedUtc, dates.validatedUtc);
+    const threshold = staleThreshold(env);
+    if (anchor === null) {
+        return { ...unknownFreshness(env), generated_date: dates.generatedDate, validated_date: dates.validatedDate };
+    }
+    const now = new Date();
+    const today = Date.UTC(now.getFullYear(), now.getMonth(), now.getDate());
+    const days = Math.round((today - anchor) / 86_400_000);
+    return {
+        state: days >= threshold ? "stale" : "current",
+        days_since_generated: days,
+        stale_threshold_days: threshold,
+        generated_date: dates.generatedDate,
+        validated_date: dates.validatedDate,
+    };
+}
+function result(profilePath, env, status, validityClass, recovery) {
+    return {
+        validity: { status, class: validityClass, recovery },
+        freshness: unknownFreshness(env),
+        profilePath,
+        groundingContent: null,
+    };
+}
+export function acquireProfile(schemasDir, env = process.env, hooks = {}) {
+    const contract = personalProfileGroundingContract();
+    let profilePath;
+    try {
+        profilePath = registryArtifactPath("profile", schemasDir ?? discoverSchemasDir(), env, { warn: false });
+    }
+    catch {
+        return result(null, env, "repair_needed", "unsafe", contract.repairRecovery);
+    }
+    const source = readProfileSourceSafely(profilePath, contract.maxProfileUtf8Bytes, hooks);
+    if (source.status === "absent") {
+        return result(profilePath, env, "absent", "absent", contract.absentRecovery);
+    }
+    if (source.status !== "ok") {
+        return result(profilePath, env, "repair_needed", source.status, contract.repairRecovery);
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(source.bytes);
+    }
+    catch {
+        return result(profilePath, env, "repair_needed", "invalid_utf8", contract.repairRecovery);
+    }
+    try {
+        const groundingContent = personalProfileGrounding(decoded);
+        return {
+            validity: { status: "valid", class: "valid", recovery: null },
+            freshness: freshness(decoded, env),
+            profilePath,
+            groundingContent,
+        };
+    }
+    catch (error) {
+        const validityClass = error instanceof PersonalGlossaryBoundaryError
+            ? error.availability
+            : "malformed";
+        return result(profilePath, env, "repair_needed", validityClass, contract.repairRecovery);
+    }
+}

package/dist/cli/startupCompletenessContract.js

@@ -0,0 +1,59 @@
+import { STATE_FAMILY_FALLBACK_COMMANDS, STATE_FAMILY_LIST_COMMANDS } from "./capabilityContext/types.js";
+export const STARTUP_AVAILABLE_STATE_FIELDS = [
+    "app_home",
+    "mode",
+    "profile",
+    "v1_migration",
+    "health",
+    "todo",
+    "plan",
+    "docs",
+    "progress",
+    "objective",
+    "state_presence",
+    "project_integration",
+    "attention",
+    "decision_attention",
+    "next_action",
+    "orchestration_context",
+    "closeout_context",
+    "evidence_context",
+    "benchmark_context",
+    "execution_context",
+];
+export const STARTUP_COMPLETENESS_CONFIDENCE_CAVEATS = [
+    "representative benchmark evidence exists, but some source products remain degraded by schema divergence",
+    "Audit evidence context uses existing status, plan, progress, docs, health, TODO, and decisions state outputs",
+];
+export const STARTUP_COMPLETENESS_CLI_FALLBACK = [
+    STATE_FAMILY_FALLBACK_COMMANDS.plan,
+    STATE_FAMILY_FALLBACK_COMMANDS.docs,
+    STATE_FAMILY_LIST_COMMANDS.progress,
+];
+export function startupCompletenessContract(input = {}) {
+    const missingState = [];
+    const schemaError = input.schemaError ?? null;
+    if (schemaError) {
+        missingState.push(schemaError);
+    }
+    if (input.profileStatus === "not found")
+        missingState.push("profile not found");
+    if (input.profileStatus === "absent")
+        missingState.push("profile absent");
+    if (input.profileStatus === "repair_needed")
+        missingState.push("profile repair needed");
+    const complete = missingState.length === 0;
+    return {
+        complete_for_capability_startup: complete,
+        raw_artifact_reads_required: false,
+        raw_artifact_read_policy: "Do not read raw artifacts when complete_for_capability_startup is true. " +
+            "When incomplete, try cli_fallback first; raw reads are permitted only for a named corruption or CLI-defect diagnostic.",
+        available_state: [...STARTUP_AVAILABLE_STATE_FIELDS],
+        missing_state: missingState,
+        confidence_caveats: [...STARTUP_COMPLETENESS_CONFIDENCE_CAVEATS],
+        cli_fallback: [...STARTUP_COMPLETENESS_CLI_FALLBACK],
+    };
+}
+export function capabilityStartupComplete(input = {}) {
+    return Boolean(startupCompletenessContract(input).complete_for_capability_startup);
+}

package/dist/cli/stateQuery.js

@@ -5,7 +5,11 @@ import { loadYamlMapping } from "../core/yaml.js";
 import { activeAppModel, discoverSchemasDir } from "./appContext.js";
 import { validateAgentString, validateIdentifier } from "./argvalidate.js";
 import { emitStructured } from "./structured.js";
-export const REQUIRED_SPARSE_CONTEXT_FIELDS = ["command", "status"];
+import { truncateCodePoints } from "../core/text.js";
+import { boundStructuredProjection } from "../state/projectionPolicy.js";
+import { preCutoverCommand } from "./preCutoverCommand.js";
+/** Shared state-query infrastructure ported from scripts/agentera. */
+export const REQUIRED_SPARSE_CONTEXT_FIELDS = ["command", "outcome"];
 export const ROUTINE_STRUCTURED_FIELDS = [
     "command",
     "status",
@@ -14,18 +18,51 @@ export const ROUTINE_STRUCTURED_FIELDS = [
     "source",
     "filters",
     "summary",
+    "plans",
     "source_contract",
 ];
+/** Canonical structured field set for the bare prime orientation briefing.
+ *  `agentera schema` discovery, the emitted prime JSON `source_contract.fields`,
+ *  and the text-mode source-contract line derive from this list. The shared skill
+ *  is the permanent host integration authority. The published bare-prime shape
+ *  stays stable: omission of default-only conditional payload is governed by
+ *  `state_presence` (missing-vs-empty) and named recovery commands, not by
+ *  trimming this set. */
+export const PRIME_STRUCTURED_FIELDS = [
+    "command", "outcome", "app_home", "app", "mode", "v1_migration", "health",
+    "todo", "plan", "docs", "progress", "objective", "state_presence", "shared_skill", "project_integration", "attention",
+    "history",
+    "decision_attention", "next_action", "orchestration_context", "closeout_context",
+    "evidence_context", "benchmark_context", "execution_context", "startup", "source", "source_contract",
+];
+/** Retired prime fields that receive one structured correction instead of
+ *  falling through to the generic unsupported-field error. */
+export const RETIRED_PRIME_FIELD_CORRECTIONS = {
+    issues: "todo",
+};
+/** Field declared available on the prime selector but emitted only by the
+ *  `prime --context <capability>` surface, not by the bare default briefing.
+ *  The bare briefing carries it as a `source_contract.capability_context`
+ *  pointer with a `fetch_command`. */
+export const PRIME_CONTEXT_ONLY_FIELDS = ["capability_context"];
+/** Fields selectable via `prime [--context <cap>] --fields`. Derives the
+ *  canonical structured set and the context-only `capability_context` pointer
+ *  from one authority, so schema discovery and the prime selector cannot drift. */
+export function availablePrimeFields(command) {
+    return command === "prime"
+        ? [...PRIME_STRUCTURED_FIELDS, ...PRIME_CONTEXT_ONLY_FIELDS]
+        : [...PRIME_STRUCTURED_FIELDS];
+}
 export const COMMAND_FILTERS = {
-    hej: [],
-    plan: ["status"],
-    progress: ["topic", "status", "limit"],
-    health: ["dimension"],
+    prime: [],
+    plan: ["status", "limit", "cursor"],
+    progress: ["topic", "status", "limit", "cursor"],
+    health: ["dimension", "limit", "cursor"],
     todo: ["severity", "status"],
-    decisions: ["topic"],
+    decisions: ["topic", "limit", "cursor"],
     docs: ["topic", "status"],
     objective: ["status"],
-    experiments: ["topic", "status", "limit"],
+    experiments: ["topic", "status", "limit", "cursor", "objective"],
     query: ["list_artifacts", "topic", "severity", "dimension", "status", "limit"],
 };
 export function appModelPayload(model = activeAppModel()) {
@@ -39,8 +76,8 @@ export function surfaceMissingMessage(surface, p, model = activeAppModel()) {
     return (`${surface} is missing. Agentera cannot find it at ${p}. ` +
         `Agentera directory: ${payload.appHome}. ` +
         `App files directory: ${payload.managedAppRoot}. ` +
-        "Run `agentera doctor` to preview the repair; run " +
-        "`agentera doctor --format json` for structured details. " +
+        `Run \`${preCutoverCommand("doctor")}\` to preview the repair; run ` +
+        `\`${preCutoverCommand("doctor --format json")}\` for structured details. ` +
         `Technical details: appHome=${payload.appHome} managedAppRoot=${payload.managedAppRoot} ` +
         `skillRoot=${payload.skillRoot} runtimeRoot=${payload.runtimeRoot}.`);
 }
@@ -72,13 +109,16 @@ export function extractEntries(data) {
     if (Array.isArray(data))
         return data.filter((e) => e && typeof e === "object" && !Array.isArray(e));
     if (typeof data === "object") {
+        // cast: data is the parsed artifact body from loadArtifact (YAML/JSON IO boundary)
         for (const [key, val] of Object.entries(data)) {
             if (key === "archive")
                 continue;
             if (Array.isArray(val) && val.length > 0 && val[0] && typeof val[0] === "object" && !Array.isArray(val[0])) {
+                // cast: val is an entries array selected from the parsed artifact (IO boundary)
                 return val;
             }
         }
+        // cast: single-object artifact body from loadArtifact (IO boundary)
         return [data];
     }
     return [];
@@ -94,6 +134,7 @@ function pyStr(val) {
     if (Array.isArray(val))
         return "[" + val.map((v) => pyReprInner(v)).join(", ") + "]";
     if (typeof val === "object") {
+        // cast: val is an artifact-scalar object being rendered for display (IO boundary)
         return "{" + Object.entries(val).map(([k, v]) => `${pyReprInner(k)}: ${pyReprInner(v)}`).join(", ") + "}";
     }
     return String(val);
@@ -106,13 +147,13 @@ function pyReprInner(val) {
 export function formatScalar(val) {
     if (Array.isArray(val) || (val !== null && typeof val === "object")) {
         const s = pyStr(val);
-        return s.length > 80 ? s.slice(0, 80) + "..." : s;
+        return truncateCodePoints(s, 80, "...");
     }
     return pyStr(val);
 }
 export function truncate(value, limit = 110) {
     const text = formatScalar(value).replace(/\n/g, " ");
-    return text.length > limit ? text.slice(0, limit - 3) + "..." : text;
+    return truncateCodePoints(text, limit, "...");
 }
 export function asList(value) {
     return Array.isArray(value) ? value : [];
@@ -137,6 +178,7 @@ export function printStatusCounts(prefix, counts, out) {
 }
 export function stringFieldNames(fields) {
     return Object.entries(fields)
+        // cast: field descriptor read from a parsed artifact schema (YAML IO boundary)
         .filter(([, d]) => d?.type === "string")
         .map(([n]) => n);
 }
@@ -162,6 +204,7 @@ export function filterByFieldValue(entries, fieldName, value, substring = false)
                 result.push(e);
         }
         else if (v && typeof v === "object") {
+            // cast: v is a field value drawn from a parsed artifact entry (IO boundary)
             const keys = Object.keys(v);
             if (keys.includes(value) || (substring && keys.some((k) => k.toLowerCase().includes(vl))))
                 result.push(e);
@@ -180,6 +223,13 @@ function cycleSortKey(entry) {
         return [0, timestamp];
     return [0, ""];
 }
+export function omitProgressCommit(entry) {
+    const { commit: _commit, ...rest } = entry;
+    return rest;
+}
+export function progressEntriesForOutput(entries) {
+    return entries.map(omitProgressCommit);
+}
 export function recentCycles(entries, limit) {
     const sorted = [...entries].sort((a, b) => {
         const ka = cycleSortKey(a);
@@ -250,7 +300,7 @@ export function requestedFields(fieldsArg) {
     return fields;
 }
 function availableStructuredFields(command) {
-    // State commands only; prime/hej/capability handled by their own commands.
+    // State commands only; prime/capability handled by their own commands.
     return ROUTINE_STRUCTURED_FIELDS;
 }
 export function selectStructuredFields(command, value, fieldsArg, err) {
@@ -275,7 +325,7 @@ export function emitStateStructured(command, value, format, fieldsArg, out, err)
     const selected = selectStructuredFields(command, value, fieldsArg, err);
     if (selected === null)
         return 1;
-    emitStructured(selected, format, out);
+    emitStructured(boundStructuredProjection(selected, command, format), format, out);
     return 0;
 }
 export function validateFilterValues(args, names) {
@@ -289,4 +339,3 @@ export function validateFilterValues(args, names) {
         }
     }
 }
-//# sourceMappingURL=stateQuery.js.map

package/dist/cli/structured.js

@@ -15,4 +15,3 @@ export function emitStructured(value, outputFormat, out) {
         out(YAML.stringify(value, { sortMapEntries: false }));
     }
 }
-//# sourceMappingURL=structured.js.map

package/dist/cli/todoMarkdown.js

@@ -0,0 +1,46 @@
+/**
+ * Markdown TODO list-item parsing for GitHub checkboxes and Agentera type tags.
+ */
+const TODO_LIST_ITEM_RE = /^- \[([^\]]+)\]\s+(.*)/;
+const TODO_TYPE_TAG_RE = /^\[([a-z][a-z0-9_-]*)(?::([^\]\s]+))?\]\s+(.*)$/;
+const TODO_LEGACY_ID_RE = /^(?:(\[[a-z][a-z0-9_-]*(?::[^\]\s]+)?\]\s+))?`([a-z]{10})`\s+(.*)$/;
+const TODO_ID_TAG_RE = /^\[id:([a-z]{10})\]\s+(.*)$/;
+function isGithubCheckboxResolved(token) {
+    return token.toLowerCase() === "x";
+}
+/**
+ * Classify a trimmed markdown TODO bullet line.
+ * Returns null when the line is not a `- […] …` list item.
+ */
+export function parseTodoMarkdownListItem(line) {
+    const m = TODO_LIST_ITEM_RE.exec(line);
+    if (!m)
+        return null;
+    const token = m[1];
+    const rest = m[2].trim();
+    const explicitId = TODO_ID_TAG_RE.exec(rest);
+    const legacyId = explicitId ? null : TODO_LEGACY_ID_RE.exec(rest);
+    const id = explicitId?.[1] ?? legacyId?.[2];
+    const publicRest = explicitId?.[2]?.trim()
+        ?? (legacyId ? `${legacyId[1] ?? ""}${legacyId[3]}`.trim() : rest);
+    const typed = TODO_TYPE_TAG_RE.exec(publicRest) ?? TODO_TYPE_TAG_RE.exec(`[${token}] ${publicRest}`);
+    const status = isGithubCheckboxResolved(token) ? "resolved" : "open";
+    return {
+        status,
+        description: rest,
+        ...(typed ? { kind: typed[1], target_version: typed[2] ?? null, title: typed[3].trim() } : { title: publicRest }),
+        ...(id ? { id } : {}),
+        ...(publicRest !== rest ? { public_description: publicRest } : {}),
+    };
+}
+export function isResolvedTodoMarkdownStatus(status) {
+    return status === "resolved";
+}
+export function renderTodoPublicRecord(record) {
+    if (typeof record.title === "string" && record.title.trim()) {
+        const kind = typeof record.kind === "string" && record.kind.trim() ? record.kind : "task";
+        const target = typeof record.target_version === "string" && record.target_version.trim() ? `:${record.target_version}` : "";
+        return `[${kind}${target}] ${record.title.trim()}`;
+    }
+    return String(record.description ?? "");
+}

package/dist/cli/todoReadinessSelection.js

@@ -0,0 +1,192 @@
+import path from "node:path";
+import { preCutoverCommand } from "./preCutoverCommand.js";
+import { loadTodoReadinessContract } from "../registries/todoReadinessContract.js";
+import { TODO_SEVERITY_ORDER } from "./todoSeverity.js";
+import { renderTodoPublicRecord } from "./todoMarkdown.js";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validProjectedOrder(value) {
+    if (!mapping(value))
+        return false;
+    if (value.kind === "absent")
+        return Object.keys(value).length === 1;
+    return value.kind === "managed"
+        && Object.keys(value).sort().join(",") === "kind,markdownOrder"
+        && Number.isSafeInteger(value.markdownOrder)
+        && Number(value.markdownOrder) > 0;
+}
+function projectedMode(entities) {
+    const declared = entities.filter((entity) => Object.hasOwn(entity, "projectedOrder"));
+    if (!declared.length)
+        return false;
+    if (declared.length !== entities.length || declared.some((entity) => !validProjectedOrder(entity.projectedOrder))) {
+        throw new Error("projected TODO readiness requires one valid projectedOrder for every entity");
+    }
+    return true;
+}
+function compareProjectedOrder(left, right) {
+    const a = left.projectedOrder;
+    const b = right.projectedOrder;
+    if (a.kind !== b.kind)
+        return a.kind === "managed" ? -1 : 1;
+    if (a.kind === "managed" && b.kind === "managed")
+        return a.markdownOrder - b.markdownOrder || left.id.localeCompare(right.id);
+    return (left.queueRank ?? Number.MAX_SAFE_INTEGER) - (right.queueRank ?? Number.MAX_SAFE_INTEGER) || left.id.localeCompare(right.id);
+}
+function dependencies(readiness) {
+    return Array.isArray(readiness.dependencies)
+        ? readiness.dependencies.filter(mapping)
+        : [];
+}
+function hasDependencyCycle(itemId, byId) {
+    const visit = (id, visiting, visited) => {
+        if (visiting.has(id))
+            return true;
+        if (visited.has(id))
+            return false;
+        const entity = byId.get(id);
+        const readiness = mapping(entity?.record.readiness) ? entity.record.readiness : null;
+        if (!readiness)
+            return false;
+        visiting.add(id);
+        for (const dependency of dependencies(readiness)) {
+            if (dependency.artifact === "todo" && typeof dependency.id === "string") {
+                if (visit(dependency.id, visiting, visited))
+                    return true;
+            }
+        }
+        visiting.delete(id);
+        visited.add(id);
+        return false;
+    };
+    return visit(itemId, new Set(), new Set());
+}
+export function evaluateTodoReadinessQueue(entities, sourceRoot) {
+    if (entities.length === 0) {
+        return {
+            selected: null,
+            evaluations: [],
+            triage: { count: 0, bounded: true, recovery: null },
+            abstainRecovery: null,
+        };
+    }
+    const contract = sourceRoot
+        ? loadTodoReadinessContract(path.join(sourceRoot, "skills/agentera/schemas/artifacts/todo.yaml"), path.join(sourceRoot, "skills/agentera/protocol.yaml"), path.join(sourceRoot, "skills/agentera/capability_schema_contract.yaml"))
+        : loadTodoReadinessContract();
+    const projected = projectedMode(entities);
+    const byId = new Map(entities.map((entity) => [entity.id, entity]));
+    const evaluate = (entity) => {
+        const { record } = entity;
+        const readiness = mapping(record.readiness) ? record.readiness : null;
+        const dependencyList = readiness ? dependencies(readiness) : [];
+        let outcome = "actionable";
+        let declaredRecovery = null;
+        if (record.status === "resolved")
+            outcome = "todo_resolved";
+        else if (!readiness)
+            outcome = "readiness_absent";
+        else if (readiness.blocked !== null) {
+            outcome = "blocked";
+            declaredRecovery = mapping(readiness.blocked) && typeof readiness.blocked.recovery === "string"
+                ? readiness.blocked.recovery
+                : null;
+        }
+        else if (mapping(readiness.gate) && readiness.gate.state === "pending") {
+            outcome = "gate_pending";
+            declaredRecovery = typeof readiness.gate.recovery === "string" ? readiness.gate.recovery : null;
+        }
+        else if (dependencyList.some((dependency) => dependency.artifact !== "todo")) {
+            outcome = "dependency_cross_artifact";
+        }
+        else if (dependencyList.some((dependency) => typeof dependency.id !== "string" || !byId.has(dependency.id))) {
+            outcome = "dependency_missing";
+        }
+        else if (hasDependencyCycle(entity.id, byId)) {
+            outcome = "dependency_cycle";
+        }
+        else if (dependencyList.some((dependency) => byId.get(String(dependency.id))?.record.status !== "resolved")) {
+            outcome = "dependency_open";
+        }
+        const authority = contract.outcomes[outcome];
+        const capability = readiness && typeof readiness.capability === "string" ? readiness.capability : undefined;
+        const queueRank = readiness && Number.isInteger(readiness.queue_rank) ? Number(readiness.queue_rank) : undefined;
+        return {
+            id: entity.id,
+            artifact: entity.artifact,
+            severity: String(record.severity ?? "normal"),
+            description: renderTodoPublicRecord(record),
+            outcome,
+            result: String(authority.result),
+            eligible: authority.eligible === true,
+            attention: String(authority.attention),
+            recovery: declaredRecovery ?? (typeof authority.recovery === "string" ? authority.recovery : null),
+            retrieval: { exact: preCutoverCommand(`state todo get --id ${entity.id} --format json`) },
+            ...(capability ? {
+                capability,
+                phase: contract.phaseByCapability.get(capability),
+                reason: typeof readiness?.reason === "string" ? readiness.reason : "",
+            } : {}),
+            ...(queueRank === undefined ? {} : { queueRank }),
+            ...(projected ? { projectedOrder: entity.projectedOrder } : {}),
+        };
+    };
+    const evaluations = entities.map(evaluate);
+    const actionable = evaluations.filter((entry) => entry.eligible);
+    if (!projected) {
+        const ranks = new Map();
+        for (const entry of actionable) {
+            const key = `${entry.severity}\0${String(entry.queueRank)}`;
+            ranks.set(key, [...(ranks.get(key) ?? []), entry]);
+        }
+        for (const conflicts of ranks.values()) {
+            if (conflicts.length < 2)
+                continue;
+            const authority = contract.outcomes.ordering_conflict;
+            for (const entry of conflicts) {
+                entry.outcome = "ordering_conflict";
+                entry.result = String(authority.result);
+                entry.eligible = false;
+                entry.attention = String(authority.attention);
+                entry.recovery = typeof authority.recovery === "string" ? authority.recovery : null;
+            }
+        }
+    }
+    const selected = evaluations
+        .filter((entry) => entry.eligible)
+        .sort((left, right) => (TODO_SEVERITY_ORDER[left.severity] ?? TODO_SEVERITY_ORDER.normal)
+        - (TODO_SEVERITY_ORDER[right.severity] ?? TODO_SEVERITY_ORDER.normal)
+        || (projected
+            ? compareProjectedOrder(left, right)
+            : (left.queueRank ?? Number.MAX_SAFE_INTEGER) - (right.queueRank ?? Number.MAX_SAFE_INTEGER) || left.id.localeCompare(right.id)))[0] ?? null;
+    const triageCount = evaluations.filter((entry) => entry.attention === "item").length;
+    const mixedRecovery = contract.queueOutcomes.mixed_actionable_and_triage?.recovery;
+    const queueRecovery = contract.queueOutcomes.all_non_actionable?.recovery;
+    const nonActionable = evaluations
+        .filter((entry) => !entry.eligible && entry.result !== "resolved")
+        .sort((left, right) => (TODO_SEVERITY_ORDER[left.severity] ?? TODO_SEVERITY_ORDER.normal)
+        - (TODO_SEVERITY_ORDER[right.severity] ?? TODO_SEVERITY_ORDER.normal)
+        || contract.precedence.indexOf(left.outcome) - contract.precedence.indexOf(right.outcome)
+        || (left.queueRank ?? Number.MAX_SAFE_INTEGER) - (right.queueRank ?? Number.MAX_SAFE_INTEGER));
+    const recoveryCandidate = nonActionable[0];
+    const equallyRankedRecoveries = recoveryCandidate
+        ? new Set(nonActionable
+            .filter((entry) => entry.severity === recoveryCandidate.severity
+            && entry.outcome === recoveryCandidate.outcome
+            && entry.queueRank === recoveryCandidate.queueRank)
+            .map((entry) => entry.recovery))
+        : new Set();
+    const abstainRecovery = equallyRankedRecoveries.size === 1
+        ? recoveryCandidate?.recovery ?? null
+        : typeof queueRecovery === "string" ? queueRecovery : null;
+    return {
+        selected,
+        evaluations,
+        triage: {
+            count: triageCount,
+            bounded: true,
+            recovery: triageCount > 0 && typeof mixedRecovery === "string" ? mixedRecovery : null,
+        },
+        abstainRecovery: !selected ? abstainRecovery : null,
+    };
+}

package/dist/cli/todoSeverity.js

@@ -0,0 +1,18 @@
+/** Severity band keys for TODO.md sections — shared by state todo, prime, and orientation. */
+export const TODO_SEVERITY_ORDER_KEYS = [
+    "critical",
+    "degraded",
+    "warning",
+    "normal",
+    "info",
+    "annoying",
+];
+/** Sort priority for TODO severity bands (lower = higher priority). */
+export const TODO_SEVERITY_ORDER = {
+    critical: 0,
+    degraded: 1,
+    warning: 1,
+    normal: 2,
+    info: 3,
+    annoying: 3,
+};