agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/cli/commands/prime/collectEntityOrientation.js

@@ -0,0 +1,326 @@
+import path from "node:path";
+import { listProgressEntities } from "../../../state/progressEntities.js";
+import { listDecisionEntities } from "../../../state/decisionEntities.js";
+import { listHealthEntities } from "../../../state/healthEntities.js";
+import { listPlanEntities, listPlanTaskEntities, openPlanConflictDiagnostic } from "../../../state/planEntities.js";
+import { listObjectiveEntities, listExperimentEntities } from "../../../state/objectiveExperimentEntities.js";
+import { assertTodoReconciliationReadable, listTodoDocsEntities, projectTodoReadEntities } from "../../../state/todoDocsEntities.js";
+import { inspectTodoReconciliationState } from "../../../state/todoReconciliationInspection.js";
+import { StateRetrievalFailure } from "../../../state/directRetrieval.js";
+import { discoverEntities } from "../../../state/entityStorage.js";
+import { summaryCaveat } from "../../../state/summaryEntityRead.js";
+import { boundStartupValue, STARTUP_ARRAY_LIMIT } from "../../../state/startupProjection.js";
+import { rememberPlanTaskIndex } from "../../planTaskIndex.js";
+import { firstActionablePlanTask } from "../../capabilityContext/planState.js";
+import { issueCounts } from "../../orientation.js";
+import { preCutoverCommand } from "../../preCutoverCommand.js";
+import { evaluateTodoReadinessQueue } from "../../todoReadinessSelection.js";
+import { projectCurrentGlossaryCaveats } from "../../../state/progressGlossaryCaveat.js";
+import { glossaryCaveatContract } from "../../../registries/glossaryCaveatContract.js";
+import { renderTodoPublicRecord } from "../../todoMarkdown.js";
+function entries(payload) {
+    return Array.isArray(payload.entries)
+        ? payload.entries.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry))
+        : [];
+}
+function bounded(value) {
+    return boundStartupValue(value);
+}
+function record(entry) {
+    return entry?.record && typeof entry.record === "object" && !Array.isArray(entry.record)
+        ? entry.record
+        : {};
+}
+function header(entry) {
+    const value = record(entry).header;
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function terminal(status) {
+    return ["complete", "completed", "closed", "done", "resolved", "retired", "superseded"].includes(String(status ?? "").toLowerCase());
+}
+function healthSummary(latest, history) {
+    if (!latest) {
+        return history
+            ? { exists: true, status: "degraded", startup_outcome: "degraded", degraded_history: history }
+            : { exists: false, status: "absent", startup_outcome: "ok" };
+    }
+    const healthRecord = record(latest);
+    const grades = healthRecord.grades && typeof healthRecord.grades === "object" && !Array.isArray(healthRecord.grades)
+        ? healthRecord.grades
+        : {};
+    const ranks = { A: 0, B: 1, C: 2, D: 3, F: 4 };
+    let worst = null;
+    for (const [dimension, grade] of Object.entries(grades)) {
+        const text = String(grade);
+        const rank = ranks[text.toUpperCase().slice(0, 1)] ?? -1;
+        if (worst === null || rank > worst[2])
+            worst = [dimension, text, rank];
+    }
+    const trajectory = String(healthRecord.trajectory ?? "");
+    const degrading = ["degrading", "declining", "worse"].includes(trajectory.toLowerCase()) || (worst !== null && worst[2] >= ranks.D);
+    return {
+        exists: true,
+        status: degrading ? "degraded" : "available",
+        startup_outcome: degrading ? "degraded" : "ok",
+        id: latest.id,
+        artifact: latest.artifact,
+        date: String(healthRecord.date ?? ""),
+        trajectory,
+        grade: worst?.[1] ?? "",
+        worst,
+        degrading,
+        ...(history ? { degraded_history: history } : {}),
+    };
+}
+function degradedHistory(artifact, totalSummaryCount) {
+    if (totalSummaryCount === 0)
+        return undefined;
+    return {
+        summary_count: totalSummaryCount,
+        returned_count: 0,
+        omitted_count: totalSummaryCount,
+        retrieval: {
+            list: preCutoverCommand(`state ${artifact} list --limit 20 --format json`),
+            get: preCutoverCommand(`state ${artifact} get --id ID --format json`),
+        },
+    };
+}
+function projectedHistory(list, artifact, fullCount, summaryCount, degraded) {
+    const total = fullCount + summaryCount;
+    const listCommand = preCutoverCommand(`state ${artifact} list --limit 20 --format json`);
+    const getCommand = preCutoverCommand(`state ${artifact} get --id ID --format json`);
+    return {
+        schemaVersion: list.schemaVersion,
+        command: list.command,
+        status: summaryCount > 0 ? "degraded" : "ok",
+        compatibility: summaryCount > 0 ? (fullCount > 0 ? "mixed" : "degraded") : "current",
+        detail_availability: "omitted",
+        counts: { total, returned: 0, remaining: total, full: fullCount, summary: summaryCount },
+        ...(summaryCount > 0 ? { caveats: [summaryCaveat(artifact)] } : {}),
+        omitted: total > 0,
+        omitted_count: total,
+        omission_reason: total > 0 ? "startup_history_detail" : "none",
+        retrieval: { list: listCommand, get: getCommand },
+        ...(degraded ? { degraded_history: degraded } : {}),
+        source_contract: list.source_contract,
+    };
+}
+function entityPlanStatus(entry) {
+    const plan = entry.record ?? {};
+    const planHeader = plan.header && typeof plan.header === "object" && !Array.isArray(plan.header)
+        ? plan.header
+        : {};
+    return String(planHeader.status ?? plan.status ?? "");
+}
+function selected(entries, artifact, candidateIds = entries.map((entry) => String(entry.id)), sourceRoot) {
+    if (candidateIds.length < 2)
+        return entries[0];
+    const ids = candidateIds.slice().sort();
+    const noun = artifact === "plan" ? "open plans" : "active objectives";
+    const list = preCutoverCommand(`state ${artifact} list --format json`);
+    const planConflict = artifact === "plan" ? openPlanConflictDiagnostic(ids, sourceRoot) : undefined;
+    throw new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "ambiguous",
+            artifact,
+            message: planConflict?.message ?? `multiple ${noun} require explicit selection: ${ids.join(", ")}`,
+            syntax: preCutoverCommand(`state ${artifact} get --id ID --format json`),
+            example: preCutoverCommand(`state ${artifact} get --id ${String(entries[0]?.id)} --format json`),
+            recovery: planConflict?.recovery ?? `Run ${list}, resolve the competing ${noun}, and retry prime.`,
+            ...(planConflict ? { details: planConflict.details } : {}),
+        },
+    }, 1);
+}
+/** Bounded startup projection built only from canonical entity readers. */
+export function collectEntityOrientation(projectRoot, sourceRoot) {
+    assertTodoReconciliationReadable(projectRoot, sourceRoot);
+    const discovery = discoverEntities(projectRoot, sourceRoot);
+    const todoReconciliation = inspectTodoReconciliationState(projectRoot, sourceRoot, discovery);
+    const caveatContract = glossaryCaveatContract(path.join(sourceRoot, "references", "artifacts", "glossary-entry-contract.yaml"));
+    const glossaryCaveatProjection = projectCurrentGlossaryCaveats(discovery.entities, caveatContract);
+    const invalidProgress = (entity) => (entity.artifact === "progress" || ["progress_cycle", "progress_summary"].includes(entity.boundary ?? "")) &&
+        entity.classification !== "valid";
+    const progressDiscovery = discovery.entities.some(invalidProgress)
+        ? { ...discovery, entities: discovery.entities.filter((entity) => !invalidProgress(entity)) }
+        : discovery;
+    const progressList = listProgressEntities(projectRoot, 10, {}, undefined, { sourceRoot, format: "json", discovery: progressDiscovery });
+    const decisionList = listDecisionEntities(projectRoot, 10, undefined, undefined, { sourceRoot, format: "json", discovery });
+    const healthList = listHealthEntities(projectRoot, 10, undefined, undefined, { sourceRoot, format: "json", discovery });
+    const planList = listPlanEntities(projectRoot, 2, undefined, { sourceRoot, format: "json", statuses: ["open", "active"], discovery });
+    const objectiveList = listObjectiveEntities(projectRoot, 2, undefined, { sourceRoot, format: "json", statuses: ["open", "active"], discovery });
+    const closedObjectiveList = listObjectiveEntities(projectRoot, 1, undefined, { sourceRoot, format: "json", statuses: ["closed"], discovery });
+    const todoList = listTodoDocsEntities(projectRoot, "todo", 20, undefined, { status: "open" }, { sourceRoot, format: "json", discovery });
+    const docsList = listTodoDocsEntities(projectRoot, "docs", 20, undefined, {}, { sourceRoot, format: "json", discovery });
+    const progressEntries = entries(progressList);
+    const healthEntries = entries(healthList);
+    const decisionEntries = entries(decisionList);
+    const fullProgressEntries = progressEntries.filter((entry) => entry.detail_availability === "full");
+    const fullHealthEntries = healthEntries.filter((entry) => entry.detail_availability === "full");
+    const fullDecisionEntries = decisionEntries.filter((entry) => entry.detail_availability === "full");
+    const progressHistory = degradedHistory("progress", discovery.entities.filter((entry) => entry.boundary === "progress_summary").length);
+    const decisionHistory = degradedHistory("decisions", discovery.entities.filter((entry) => entry.boundary === "decision_summary").length);
+    const healthHistory = degradedHistory("health", discovery.entities.filter((entry) => entry.boundary === "health_summary").length);
+    const progressFullCount = discovery.entities.filter((entry) => entry.boundary === "progress_cycle").length;
+    const decisionFullCount = discovery.entities.filter((entry) => entry.boundary === "decision").length;
+    const healthFullCount = discovery.entities.filter((entry) => entry.boundary === "health_audit").length;
+    const progressSummaryCount = discovery.entities.filter((entry) => entry.boundary === "progress_summary").length;
+    const decisionSummaryCount = discovery.entities.filter((entry) => entry.boundary === "decision_summary").length;
+    const healthSummaryCount = discovery.entities.filter((entry) => entry.boundary === "health_summary").length;
+    const planEntries = entries(planList);
+    const objectiveEntries = entries(objectiveList);
+    const todoEntries = entries(todoList);
+    const docsEntries = entries(docsList);
+    // Startup detail is bounded to two plans, but ambiguous diagnostics must use
+    // the complete canonical candidate set so their ID sample and omission count
+    // match direct plan selection without creating another selector.
+    const openPlanCandidateIds = discovery.entities
+        .filter((entry) => entry.boundary === "plan" && entry.classification === "valid" && entry.id && ["open", "active"].includes(entityPlanStatus(entry)))
+        .map((entry) => entry.id);
+    const selectedPlan = selected(planEntries, "plan", openPlanCandidateIds, sourceRoot);
+    const taskPage = selectedPlan
+        ? listPlanTaskEntities(projectRoot, String(selectedPlan.id), 100, undefined, { sourceRoot, format: "json", discovery })
+        : null;
+    const taskEntries = (taskPage
+        ? entries(taskPage)
+        : []).map((entry) => ({ ...record(entry), id: entry.id, artifact: entry.artifact, provenance: entry.provenance }));
+    const allTaskEntries = selectedPlan
+        ? discovery.entities
+            .filter((entry) => entry.boundary === "plan_task" && entry.classification === "valid" && entry.record?.plan === selectedPlan.id && entry.id)
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map((entry) => ({ ...entry.record, id: entry.id, artifact: entry.artifact, provenance: { storage: "canonical_entity_file", path: entry.relativePath } }))
+        : [];
+    const firstPending = firstActionablePlanTask(allTaskEntries);
+    const taskStatusCounts = allTaskEntries.reduce((counts, entry) => {
+        const status = String(entry.status ?? "pending").toLowerCase();
+        counts[status] = (counts[status] ?? 0) + 1;
+        return counts;
+    }, {});
+    const publicTaskEntries = taskEntries.slice(0, STARTUP_ARRAY_LIMIT);
+    const taskDetailOmitted = allTaskEntries.length > publicTaskEntries.length;
+    const taskRetrieval = selectedPlan
+        ? { list: preCutoverCommand(`state plan tasks list ${String(selectedPlan.id)} --limit 100 --format json`), restart: preCutoverCommand(`state plan tasks list ${String(selectedPlan.id)} --limit 100 --format json`), get: preCutoverCommand("state plan tasks get --id ID --format json") }
+        : {};
+    const plan = selectedPlan ? {
+        exists: true,
+        active: true,
+        id: selectedPlan.id,
+        artifact: selectedPlan.artifact,
+        status: String(header(selectedPlan).status ?? "open"),
+        title: String(header(selectedPlan).title ?? ""),
+        tasks: publicTaskEntries,
+        complete: taskStatusCounts.complete ?? 0,
+        superseded: taskStatusCounts.superseded ?? 0,
+        total: allTaskEntries.length,
+        complete_plan: allTaskEntries.length > 0 && allTaskEntries.every((entry) => terminal(entry.status)),
+        first_pending: firstPending ?? null,
+        task_status_counts: taskStatusCounts,
+        task_omission: { omitted: taskDetailOmitted, total: allTaskEntries.length, returned_count: publicTaskEntries.length, omitted_count: allTaskEntries.length - publicTaskEntries.length, omission_reason: taskDetailOmitted ? taskPage?.omitted === true ? taskPage.omission_reason : "startup_detail_capacity" : "none", retrieval: taskRetrieval },
+        diagnostics: [],
+    } : { exists: false, active: false, status: "missing", tasks: [], complete: 0, superseded: 0, total: 0, complete_plan: false, first_pending: null };
+    const latestProgress = fullProgressEntries[0];
+    const latestProgressRecord = record(latestProgress);
+    const progress = latestProgress ? {
+        exists: true,
+        status: "available",
+        latest: {
+            id: latestProgress.id,
+            artifact: latestProgress.artifact,
+            ...Object.fromEntries(["what", "next"]
+                .filter((field) => latestProgressRecord[field] !== undefined)
+                .map((field) => [field, latestProgressRecord[field]])),
+        },
+        ...(latestProgressRecord.verified === undefined ? {} : { latest_verification: latestProgressRecord.verified }),
+        cycle_count: Number(progressList.counts?.total ?? progressEntries.length),
+        ...(progressHistory ? { degraded_history: progressHistory } : {}),
+    } : progressEntries.length ? {
+        exists: true,
+        status: "degraded_history",
+        cycle_count: Number(progressList.counts?.total ?? progressEntries.length),
+        degraded_history: progressHistory,
+    } : { exists: false, status: "missing", cycle_count: 0 };
+    const health = healthSummary(fullHealthEntries[0], healthEntries.length ? healthHistory : undefined);
+    const activeObjective = selected(objectiveEntries, "objective");
+    const closedObjectiveCount = Number(closedObjectiveList.counts?.total ?? 0);
+    const objectiveRecord = record(activeObjective);
+    const objective = activeObjective ? {
+        exists: true,
+        active: true,
+        id: activeObjective.id,
+        artifact: activeObjective.artifact,
+        title: String(header(activeObjective).title ?? ""),
+        status: String(header(activeObjective).status ?? "open"),
+        metric: String(objectiveRecord.metric?.description ?? ""),
+        experiments: entries(listExperimentEntities(projectRoot, String(activeObjective.id), 20, undefined, { sourceRoot, format: "json", discovery })),
+        closed_count: closedObjectiveCount,
+    } : { exists: closedObjectiveCount > 0, active: false, closed_count: closedObjectiveCount };
+    const completeTodoEntities = projectTodoReadEntities(projectRoot, sourceRoot, discovery);
+    const todoReadiness = evaluateTodoReadinessQueue(completeTodoEntities, sourceRoot);
+    const todoItems = todoEntries.map((entry) => {
+        const todo = record(entry);
+        return {
+            id: String(entry.id), artifact: String(entry.artifact),
+            severity: String(todo.severity ?? "normal"),
+            status: String(todo.status ?? "open"),
+            kind: typeof todo.kind === "string" ? todo.kind : null,
+            target_version: typeof todo.target_version === "string" ? todo.target_version : null,
+            title: typeof todo.title === "string" ? todo.title : null,
+            requirements: Array.isArray(todo.requirements) ? todo.requirements : [],
+            acceptance: Array.isArray(todo.acceptance) ? todo.acceptance : [],
+            release_blocker: todo.release_blocker === true,
+            text: renderTodoPublicRecord(todo),
+        };
+    });
+    const todoCounts = issueCounts(completeTodoEntities
+        .filter((entry) => entry.record.status === "open")
+        .map((entry) => ({ severity: String(entry.record.severity ?? "normal") })));
+    const todoListCounts = todoList.counts;
+    const todoDetail = {
+        total: Number(todoListCounts?.total ?? todoEntries.length),
+        returned: Number(todoListCounts?.returned ?? todoEntries.length),
+        omitted: Number(todoListCounts?.remaining ?? 0),
+        retrieval: todoList.retrieval ?? {},
+    };
+    const docs = {
+        exists: docsEntries.length > 0,
+        status: docsEntries.length ? "available" : "missing",
+        indexed_documents: Number(docsList.counts?.total ?? docsEntries.length),
+        entries: docsEntries,
+    };
+    const reviewEntries = fullDecisionEntries.filter((entry) => {
+        const satisfaction = record(entry).satisfaction;
+        return satisfaction?.review_needed === true || satisfaction?.state === "open";
+    });
+    const decisionAttention = reviewEntries.length ? {
+        type: "decision_review",
+        count: reviewEntries.length,
+        states: {},
+        entries: reviewEntries.slice(0, 3).map((entry) => ({
+            id: String(entry.id), artifact: String(entry.artifact), title: String(record(entry).question ?? "Decision"), state: String(record(entry).satisfaction?.state ?? "open"), source: entry.provenance ?? null,
+        })),
+        max_entries: 3,
+        bounded: reviewEntries.length > 3,
+        attention: `${reviewEntries.length} decision(s) require review`,
+    } : null;
+    const firstDecision = reviewEntries[0];
+    const decision = firstDecision ? { object: String(firstDecision.id), title: String(record(firstDecision).question ?? "Decision review") } : null;
+    const projection = bounded({
+        plan, docs, progress, health, objective, todoItems, todoCounts, decision, decisionAttention,
+        glossaryCaveatAttention: glossaryCaveatProjection.attention,
+        glossaryCaveatAttentionPolicy: glossaryCaveatProjection.attention ? {
+            public_limit: glossaryCaveatProjection.publicAttentionLimit,
+            reserved_slots: glossaryCaveatProjection.reservedGlossarySlots,
+        } : null,
+        history: {
+            progress: projectedHistory(progressList, "progress", progressFullCount, progressSummaryCount, progressHistory),
+            decisions: projectedHistory(decisionList, "decisions", decisionFullCount, decisionSummaryCount, decisionHistory),
+            health: projectedHistory(healthList, "health", healthFullCount, healthSummaryCount, healthHistory),
+        },
+    });
+    // The opaque continuation cursor is already list-budget bounded and must stay
+    // byte-exact so omitted TODO detail remains recoverable.
+    const result = { ...projection, todoDetail, todoReadiness, todoReconciliation };
+    rememberPlanTaskIndex(result.plan, allTaskEntries);
+    return result;
+}

package/dist/cli/commands/prime/collectOrientationState.js

@@ -0,0 +1,212 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { detectV1ArtifactPairs } from "../../../upgrade/migrateArtifactsV2ToV3.js";
+import { summarizeProjectIntegration } from "../../../upgrade/projectIntegration.js";
+import { selectStatusReadiness, statePresence, } from "../../orientation.js";
+import { buildOrientationAttention } from "../../orientation/attention.js";
+import { corpusCoverageSummary } from "../../orientation/corpusCoverage.js";
+import { profileSignalsStatus } from "../../../analytics/profileSignals.js";
+import { statusBundleContext } from "./bundleStatus.js";
+import { v1MigrationSummary } from "./v1Migration.js";
+import { diagnoseCanonicalSkill } from "../../../setup/sharedSkill.js";
+import { collectEntityOrientation } from "./collectEntityOrientation.js";
+import { acquireProfile } from "../../profileAcquisition.js";
+import { fullEntityUpgradeCommand } from "../../../upgrade/upgradeCommands.js";
+import { classifyEntityCutoverProject } from "../../../state/entityMigrationPreview.js";
+import { preCutoverCommand } from "../../preCutoverCommand.js";
+const EMPTY_SCHEMAS = Object.freeze({});
+function stateCutover(project, sourceRoot) {
+    try {
+        const projectState = classifyEntityCutoverProject(project, sourceRoot);
+        if (projectState === "v3") {
+            return { status: "complete", project_state: "v3", recovery_command: null };
+        }
+        return { status: "required", project_state: projectState, recovery_command: fullEntityUpgradeCommand(project) };
+    }
+    catch {
+        return { status: "invalid_lifecycle", project_state: "invalid_lifecycle", recovery_command: preCutoverCommand("check validate state --format json") };
+    }
+}
+export function collectOrientationState(opts) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ? opts.home : os.homedir();
+    const project = path.resolve(opts.projectRoot ?? process.cwd());
+    const { bundle, channel, install, successorAnnounced } = statusBundleContext(opts);
+    const sourceRoot = bundle.sourceRoot;
+    const schemasDir = path.join(sourceRoot, "skills", "agentera", "schemas", "artifacts");
+    const schemas = EMPTY_SCHEMAS;
+    let savedContext = false;
+    try {
+        savedContext = fs.readdirSync(path.join(project, ".agentera")).some((f) => f.endsWith(".yaml"));
+    }
+    catch {
+        savedContext = false;
+    }
+    const mode = savedContext ? "returning" : "fresh";
+    const acquiredProfile = acquireProfile(schemasDir, env);
+    const profile = acquiredProfile.profilePath ?? "";
+    const profileStatus = acquiredProfile.validity.status;
+    const profileDict = {
+        status: profileStatus,
+        validity: acquiredProfile.validity,
+        freshness: acquiredProfile.freshness,
+    };
+    if (acquiredProfile.validity.status === "valid" && acquiredProfile.freshness.state !== "unknown") {
+        profileDict.days_since_generated = acquiredProfile.freshness.days_since_generated ?? undefined;
+        profileDict.stale = acquiredProfile.freshness.state === "stale";
+        profileDict.stale_threshold_days = acquiredProfile.freshness.stale_threshold_days;
+        if (acquiredProfile.freshness.generated_date)
+            profileDict.generated_date = acquiredProfile.freshness.generated_date;
+        if (acquiredProfile.freshness.validated_date)
+            profileDict.validated_date = acquiredProfile.freshness.validated_date;
+    }
+    const boundedSignals = profileSignalsStatus(env, process.platform);
+    const { tiers_dir: _tiersDir, signal_path: _signalPath, ...publicBoundedSignals } = boundedSignals;
+    profileDict.bounded_signals = publicBoundedSignals;
+    const v1Artifacts = detectV1ArtifactPairs(project);
+    const v1Migration = v1MigrationSummary(v1Artifacts, { sourceRoot, home, env });
+    const entity = collectEntityOrientation(project, sourceRoot);
+    const cutover = stateCutover(project, sourceRoot);
+    const plan = entity.plan;
+    const docs = entity.docs;
+    const progress = entity.progress;
+    const health = entity.health;
+    const history = entity.history;
+    const objective = entity.objective;
+    const presence = statePresence(plan, docs, progress, health, objective);
+    const todoItems = entity.todoItems;
+    const counts = entity.todoCounts;
+    const decision = entity.decision;
+    const decisionAttention = entity.decisionAttention;
+    const corpusCoverage = corpusCoverageSummary(env, process.platform);
+    const sharedSkill = diagnoseCanonicalSkill(home);
+    const projectIntegration = summarizeProjectIntegration({
+        project,
+        sourceRoot,
+        home,
+        env,
+        installRoot: String(bundle.appHome),
+        bundleStatus: String(bundle.status),
+        retryCommand: bundle.retryCommand,
+        crossMajorBoundaryDetected: bundle.crossMajorBoundaryDetected ?? false,
+        channel: bundle.updateChannel ?? null,
+        resolvedChannel: channel,
+        installClassification: install,
+        successorAnnounced,
+        precomputedV1Artifacts: v1Artifacts,
+    });
+    const readiness = selectStatusReadiness(plan, health, objective, todoItems, decision, savedContext, entity.todoReadiness);
+    const reconciliationReadiness = entity.todoReconciliation?.status === "action_required"
+        ? withRecommended(readiness, {
+            object: entity.todoReconciliation.state === "unsafe_inactive" ? "Replan unsafe TODO activation correction" : entity.todoReconciliation.state === "inactive" ? "Activate TODO reconciliation" : "Repair TODO reconciliation",
+            capability: entity.todoReconciliation.state === "unsafe_inactive" ? "plan" : "build",
+            reason: entity.todoReconciliation.recovery_command,
+            phase: entity.todoReconciliation.state === "unsafe_inactive" ? "plan" : entity.todoReconciliation.state === "invalid_lifecycle" ? "audit" : "build",
+        })
+        : readiness;
+    const nextAction = cutover.status !== "complete"
+        ? withRecommended(readiness, {
+            object: "Complete Agentera entity-state cutover",
+            capability: "status",
+            reason: `Status startup is blocked until entity-state cutover completes. Exact recovery: ${cutover.recovery_command}`,
+            phase: "build",
+        })
+        : selectProjectIntegrationNextAction(reconciliationReadiness, projectIntegration);
+    const attention = buildOrientationAttention({
+        project_root: project,
+        schemas_dir: schemasDir,
+        schemas,
+        app: bundle,
+        mode,
+        profile_dict: profileDict,
+        profile_status: profileStatus,
+        profile,
+        v1_migration: v1Migration,
+        project_integration: projectIntegration,
+        state_cutover: cutover,
+        shared_skill: sharedSkill,
+        plan,
+        docs,
+        progress,
+        health,
+        objective,
+        state_presence: presence,
+        corpus_coverage: corpusCoverage,
+        todo_items: todoItems,
+        todo_detail: entity.todoDetail,
+        todo_reconciliation: entity.todoReconciliation,
+        counts,
+        decision_attention: decisionAttention,
+        glossary_caveat_attention: entity.glossaryCaveatAttention,
+        glossary_caveat_attention_policy: entity.glossaryCaveatAttentionPolicy,
+        next_action: nextAction,
+        attention: [],
+        history,
+    });
+    return {
+        project_root: project,
+        schemas_dir: schemasDir,
+        schemas,
+        app: bundle,
+        mode,
+        profile_dict: profileDict,
+        profile_status: profileStatus,
+        profile,
+        v1_migration: v1Migration,
+        project_integration: projectIntegration,
+        state_cutover: cutover,
+        shared_skill: sharedSkill,
+        plan,
+        docs,
+        progress,
+        health,
+        objective,
+        state_presence: presence,
+        corpus_coverage: corpusCoverage,
+        todo_items: todoItems,
+        todo_detail: entity.todoDetail,
+        todo_reconciliation: entity.todoReconciliation,
+        counts,
+        decision_attention: decisionAttention,
+        glossary_caveat_attention: entity.glossaryCaveatAttention,
+        glossary_caveat_attention_policy: entity.glossaryCaveatAttentionPolicy,
+        next_action: nextAction,
+        attention,
+        history,
+    };
+}
+/** Promote `newRecommended` to position 1, demoting the prior recommendation
+ *  (and its alternatives) into `alternatives`. Used when a project-integration
+ *  override (upgrade, major-boundary block) takes precedence over the
+ *  state-derived cascade; the demoted candidates remain visible as what to do
+ *  once the override is resolved. */
+export function selectProjectIntegrationNextAction(readiness, projectIntegration) {
+    if (projectIntegration.recommendation === "upgrade") {
+        return withRecommended(readiness, {
+            object: projectIntegration.pending_artifacts > 0
+                ? "Upgrade Agentera artifacts"
+                : "Upgrade Agentera",
+            capability: "status",
+            reason: projectIntegration.dry_run_command
+                ? `${projectIntegration.message} Exact preview: ${projectIntegration.dry_run_command}`
+                : projectIntegration.message,
+            phase: "build",
+        });
+    }
+    if (projectIntegration.major_boundary_block) {
+        return withRecommended(readiness, {
+            object: "Await v3 successor announcement",
+            capability: "status",
+            reason: projectIntegration.major_boundary_block,
+            phase: "audit",
+        });
+    }
+    return readiness;
+}
+function withRecommended(hint, newRecommended) {
+    return {
+        recommended: newRecommended,
+        alternatives: [hint.recommended, ...hint.alternatives],
+    };
+}