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

package/dist/cli/capabilityContext/evidence.js

@@ -0,0 +1,463 @@
+import fs from "node:fs";
+import { artifactPath } from "../appContext.js";
+import { asList } from "../stateQuery.js";
+import { capabilityContext } from "./contract.js";
+import { docsConventions, sourceProvenance, uniqueList, hasRecordedValue } from "./shared.js";
+import { selectEvidenceTarget, taskByRef } from "./planState.js";
+import { progressVerificationSummary, retryState } from "./progress.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS, STATE_FAMILY_LIST_COMMANDS } from "./types.js";
+import { deferredStartupFamilies } from "./startupAggregation.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+export function dateFromIsoUtc(s) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(s.trim());
+    if (!m)
+        return null;
+    const utc = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const back = new Date(utc);
+    if (back.getUTCFullYear() !== Number(m[1]) || back.getUTCMonth() !== Number(m[2]) - 1 || back.getUTCDate() !== Number(m[3]))
+        return null;
+    return utc;
+}
+export function todayUtcMs() {
+    const now = new Date();
+    return Date.UTC(now.getFullYear(), now.getMonth(), now.getDate());
+}
+export function currentStateStatus(value, label, staleAfterDays = 30) {
+    if (typeof value !== "string" || !value.trim())
+        return ["unknown", null];
+    const observed = dateFromIsoUtc(value.trim().slice(0, 10));
+    if (observed === null)
+        return ["unknown", `${label} current-state date is not ISO-parseable in CLI state.`];
+    const ageDays = Math.round((todayUtcMs() - observed) / 86400000);
+    if (ageDays > staleAfterDays)
+        return ["stale", `${label} evidence is stale (${ageDays} days old; threshold=${staleAfterDays}).`];
+    return ["current", null];
+}
+export function evidenceDocsState(docs) {
+    const available = Boolean(docs.exists);
+    const nonEmptyFields = ["mapping_entries", "indexed_documents", "last_audit"].filter((f) => hasRecordedValue(docs[f]));
+    const [currentState, currentStateCaveat] = currentStateStatus(docs.last_audit, "Docs");
+    return {
+        status: available ? "available" : "unavailable",
+        source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs),
+        mapping_entries: docs.mapping_entries ?? 0,
+        indexed_documents: docs.indexed_documents ?? 0,
+        last_audit: docs.last_audit ?? null,
+        current_state: currentState,
+        non_empty_evidence_present: nonEmptyFields.length > 0,
+        non_empty_evidence_fields: nonEmptyFields,
+        caveats: [
+            ...(available ? [] : ["Docs state is unavailable in CLI docs state."]),
+            ...(available && currentStateCaveat ? [currentStateCaveat] : []),
+        ],
+    };
+}
+export function evidenceHealthState(health) {
+    const available = Boolean(health.exists);
+    const nonEmptyFields = ["id", "artifact", "trajectory", "grade"].filter((f) => hasRecordedValue(health[f]));
+    const auditDate = health.date ?? health.timestamp ?? null;
+    const [currentState, currentStateCaveat] = currentStateStatus(auditDate, "Health");
+    return {
+        status: available ? "available" : "unavailable",
+        source_provenance: sourceProvenance("health", STATE_FAMILY_LIST_COMMANDS.health),
+        id: health.id ?? null,
+        artifact: health.artifact ?? "health",
+        date: auditDate,
+        timestamp: auditDate,
+        trajectory: health.trajectory ?? null,
+        grade: health.grade ?? null,
+        degrading: Boolean(health.degrading),
+        current_state: currentState,
+        non_empty_evidence_present: nonEmptyFields.length > 0,
+        non_empty_evidence_fields: nonEmptyFields,
+        caveats: [
+            ...(available ? [] : ["Health state is unavailable in CLI health state."]),
+            ...(available && currentStateCaveat ? [currentStateCaveat] : []),
+        ],
+    };
+}
+export function evidenceTodoState(schemas, todoItems) {
+    const info = schemas.todo ?? { path: "TODO.md", record: undefined, schema: {}, fields: {} };
+    const exists = fs.existsSync(artifactPath(info, "todo"));
+    return {
+        status: exists ? "available" : "unavailable",
+        source_provenance: sourceProvenance("todo", STATE_FAMILY_FALLBACK_COMMANDS.todo),
+        open_count: todoItems.length,
+        items: todoItems,
+        non_empty_evidence_present: todoItems.length > 0,
+        non_empty_evidence_fields: todoItems.length > 0 ? ["items"] : [],
+        caveats: exists ? [] : ["TODO state is unavailable in CLI TODO state."],
+    };
+}
+export function evidenceProtectedStateChecks() {
+    const source = sourceProvenance("evidence_context", preCutoverCommand("prime --context audit --format json"), "protected_state_checks");
+    return {
+        status: "not_checked_by_design",
+        allowed_status_values: ["verified_local", "not_checked_by_design", "requires_manual_check", "unavailable"],
+        source_provenance: source,
+        checks: [
+            {
+                name: "vision_state",
+                status: "not_checked_by_design",
+                protected: true,
+                checked: false,
+                source_provenance: source,
+                caveats: ["Vision state is protected during execution cycles and was not read or modified."],
+            },
+            {
+                name: "objective_state",
+                status: "not_checked_by_design",
+                protected: true,
+                checked: false,
+                source_provenance: source,
+                caveats: ["Objective state is protected during execution cycles and was not read or modified."],
+            },
+        ],
+        caveats: ["Protected-state boundaries are reported without reading or modifying vision or objective state."],
+    };
+}
+export function evidenceVersionChecks(docs) {
+    const conventions = docsConventions(docs);
+    const versionFiles = asList(conventions.version_files);
+    const semverPolicy = conventions.semver_policy && typeof conventions.semver_policy === "object" && !Array.isArray(conventions.semver_policy) ? conventions.semver_policy : {};
+    const source = sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.conventions");
+    const ec = (field) => sourceProvenance("evidence_context", preCutoverCommand("prime --context audit --format json"), field);
+    const checks = [
+        {
+            name: "docs_version_policy",
+            status: Object.keys(semverPolicy).length > 0 ? "verified_local" : "unavailable",
+            source_provenance: source,
+            evidence: { semver_policy: semverPolicy },
+            caveats: Object.keys(semverPolicy).length > 0 ? [] : ["Docs semver policy is unavailable in CLI docs state."],
+        },
+        {
+            name: "version_files",
+            status: versionFiles.length > 0 ? "verified_local" : "unavailable",
+            source_provenance: source,
+            evidence: { version_files: versionFiles },
+            caveats: versionFiles.length > 0 ? [] : ["Docs version files are unavailable in CLI docs state."],
+        },
+        {
+            name: "publication_evidence",
+            status: "requires_manual_check",
+            source_provenance: ec("version_checks.publication_evidence"),
+            remote_checks_performed: false,
+            registry_checks_performed: false,
+            caveats: ["Publication and registry evidence is not recorded in CLI evidence context and requires manual verification if needed."],
+        },
+        {
+            name: "remote_push_evidence",
+            status: "requires_manual_check",
+            source_provenance: ec("version_checks.remote_push_evidence"),
+            remote_checks_performed: false,
+            caveats: ["Remote push evidence is not recorded in CLI evidence context and requires manual verification if needed."],
+        },
+        {
+            name: "installed_app_refresh",
+            status: "not_checked_by_design",
+            source_provenance: ec("version_checks.installed_app_refresh"),
+            refresh_performed: false,
+            caveats: ["Installed app refresh state is deliberately not checked or changed by evidence context."],
+        },
+    ];
+    let status;
+    if (checks.some((c) => c.status === "requires_manual_check"))
+        status = "requires_manual_check";
+    else if (checks.some((c) => c.status === "unavailable"))
+        status = "unavailable";
+    else
+        status = "verified_local";
+    return {
+        status,
+        allowed_status_values: ["verified_local", "not_checked_by_design", "requires_manual_check", "unavailable"],
+        source_provenance: source,
+        checks,
+        caveats: checks.flatMap((c) => (c.caveats ?? [])),
+    };
+}
+export function evidencePlanCriteria(plan, target) {
+    const taskRefObj = target.task && typeof target.task === "object" && !Array.isArray(target.task) ? target.task : null;
+    const selected = taskByRef(plan, taskRefObj);
+    const criteria = selected && typeof selected === "object" ? asList(selected.acceptance) : [];
+    return {
+        status: criteria.length > 0 ? "available" : "incomplete",
+        source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries.acceptance"),
+        target: taskRefObj,
+        criteria,
+        criteria_count: criteria.length,
+        non_empty_evidence_present: criteria.length > 0,
+        non_empty_evidence_fields: criteria.length > 0 ? ["criteria"] : [],
+        caveats: criteria.length > 0 ? [] : ["Selected evaluation target has no acceptance criteria in CLI plan state."],
+    };
+}
+export function residualRiskEntry(category, status, message, sp) {
+    return { category, status, message, source_provenance: sp };
+}
+function decisionHistoryEntries(history) {
+    return asList(history.entries).flatMap((value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return [];
+        const entry = value;
+        const record = entry.record;
+        if (!record || typeof record !== "object" || Array.isArray(record))
+            return [];
+        return [{ ...record, id: entry.id ?? null, artifact: entry.artifact ?? "decisions", retrieval: entry.retrieval ?? null }];
+    });
+}
+function decisionHistoryCounts(history) {
+    return history.counts && typeof history.counts === "object" && !Array.isArray(history.counts)
+        ? history.counts
+        : {};
+}
+export function decisionContextRisk(history) {
+    const entries = decisionHistoryEntries(history);
+    const counts = decisionHistoryCounts(history);
+    if (history.command !== "state decisions list") {
+        return {
+            status: "unavailable",
+            source_provenance: sourceProvenance("decisions", STATE_FAMILY_LIST_COMMANDS.decisions),
+            summary: null,
+            caveats: ["Decision state is unavailable in CLI evidence context."],
+        };
+    }
+    const omitted = Number(counts.remaining ?? history.omitted_count ?? 0);
+    const missing = entries.filter((entry) => !entry.id || !entry.date || !entry.question || !entry.choice).length;
+    const caveats = uniqueList([
+        ...(omitted > 0 ? [`Decision startup history omits ${omitted} decision detail entr${omitted === 1 ? "y" : "ies"}; run ${STATE_FAMILY_LIST_COMMANDS.decisions} for the ordinary bounded list.`] : []),
+        ...(missing > 0 ? [`${missing} bounded decision entr${missing === 1 ? "y is" : "ies are"} missing review context fields.`] : []),
+    ]);
+    return {
+        status: caveats.length > 0 ? "caveated" : "available",
+        source_provenance: sourceProvenance("decisions", STATE_FAMILY_LIST_COMMANDS.decisions),
+        summary: {
+            total_entries: Number(counts.total ?? entries.length),
+            returned_entries: Number(counts.returned ?? entries.length),
+            omitted_entries: omitted,
+            entries_with_missing_fields: missing,
+            authority: "canonical_entity_files",
+        },
+        caveats,
+    };
+}
+export function parseDecisionReviewDate(value) {
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    return dateFromIsoUtc(value.trim().slice(0, 10));
+}
+export function decisionReviewDue(entry) {
+    const satisfaction = entry.satisfaction && typeof entry.satisfaction === "object" && !Array.isArray(entry.satisfaction) ? entry.satisfaction : {};
+    const candidates = [
+        ["review_date", entry.review_date],
+        ["review_by", entry.review_by],
+        ["satisfaction.review_date", satisfaction.review_date],
+        ["satisfaction.review_by", satisfaction.review_by],
+        ["satisfaction.review_due", satisfaction.review_due],
+    ];
+    for (const [field, value] of candidates) {
+        const parsed = parseDecisionReviewDate(value);
+        if (parsed !== null)
+            return [field, parsed];
+    }
+    return [null, null];
+}
+export function decisionLabel(entry) {
+    const id = entry.id;
+    if (typeof id === "string" && id)
+        return `Decision ${id}`;
+    const number = entry.number;
+    if (number !== null && number !== undefined && number !== "")
+        return `Decision ${number}`;
+    const summary = entry.summary;
+    if (typeof summary === "string" && summary.trim())
+        return summary.trim().split(":", 1)[0];
+    return "Decision entry";
+}
+export function isoFromUtcMs(utc) {
+    const d = new Date(utc);
+    return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, "0")}-${String(d.getUTCDate()).padStart(2, "0")}`;
+}
+export function decisionReviewPressure(history) {
+    const sp = sourceProvenance("decisions", STATE_FAMILY_LIST_COMMANDS.decisions);
+    if (history.command !== "state decisions list") {
+        return { status: "unavailable", source_provenance: sp, summary: null, stale_protected_decisions: [], caveats: [] };
+    }
+    const activeEntries = decisionHistoryEntries(history);
+    const counts = decisionHistoryCounts(history);
+    const omitted = Number(counts.remaining ?? history.omitted_count ?? 0);
+    const protectedActive = activeEntries.filter((e) => e.satisfaction && typeof e.satisfaction === "object" && !Array.isArray(e.satisfaction) && e.satisfaction.review_needed);
+    const protectedArchive = [];
+    const today = todayUtcMs();
+    const stale = [];
+    let caveats = omitted > 0
+        ? [`Decision review pressure is bounded with ${omitted} decision(s) omitted; continue with ${STATE_FAMILY_LIST_COMMANDS.decisions}.`]
+        : [];
+    for (const [collection, entries] of [["decisions", protectedActive], ["archive", protectedArchive]]) {
+        for (const entry of entries) {
+            const [field, reviewDate] = decisionReviewDue(entry);
+            if (reviewDate === null || reviewDate > today)
+                continue;
+            const label = decisionLabel(entry);
+            const message = `${label} requires protected decision review because ${field} elapsed on ${isoFromUtcMs(reviewDate)}.`;
+            stale.push({ label, collection, reason: "review_date_elapsed", review_date: isoFromUtcMs(reviewDate), source_field: field, message });
+            caveats.push(message);
+        }
+    }
+    const protectedOverflowCount = Math.max(protectedActive.length - 10, protectedArchive.length - 40, protectedActive.length + protectedArchive.length - 50, 0);
+    if (protectedOverflowCount) {
+        const message = "Protected decisions exceed the 10/40/50 compaction budget; " +
+            `${protectedOverflowCount} protected decision(s) require review before compaction can complete.`;
+        stale.push({ label: "decisions", collection: "decisions/archive", reason: "protected_compaction_budget_pressure", protected_overflow_count: protectedOverflowCount, message });
+        caveats.push(message);
+    }
+    caveats = uniqueList(caveats);
+    return {
+        status: stale.length > 0 || protectedOverflowCount > 0 ? "review_required" : omitted > 0 ? "degraded" : "available",
+        source_provenance: sp,
+        summary: {
+            protected_active_decisions: protectedActive.length,
+            protected_archive_decisions: protectedArchive.length,
+            protected_overflow_count: protectedOverflowCount,
+            stale_protected_decisions: stale.length,
+            returned_decisions: Number(counts.returned ?? activeEntries.length),
+            total_decisions: Number(counts.total ?? activeEntries.length),
+            omitted_decisions: omitted,
+        },
+        stale_protected_decisions: stale,
+        caveats,
+    };
+}
+export function auditEvidenceContext(capability, schemas, plan, progress, health, todoItems, docs, profile, bundle, decisionHistory) {
+    if (capability !== "audit")
+        return null;
+    const capabilityContract = capabilityContext(capability) ?? {};
+    const evaluationTarget = selectEvidenceTarget(plan);
+    const planCriteria = evidencePlanCriteria(plan, evaluationTarget);
+    const progressVerification = progressVerificationSummary(progress);
+    const docsState = evidenceDocsState(docs);
+    const healthState = evidenceHealthState(health);
+    const todoState = evidenceTodoState(schemas, todoItems);
+    const protectedStateChecks = evidenceProtectedStateChecks();
+    const versionChecks = evidenceVersionChecks(docs);
+    const decisionRisk = decisionContextRisk(decisionHistory);
+    const reviewPressure = decisionReviewPressure(decisionHistory);
+    let stateCaveats = [];
+    const attributedRisks = [];
+    for (const family of deferredStartupFamilies(capabilityContract)) {
+        const message = `${family} detail is deferred from prime --context startup.`;
+        stateCaveats.push(message);
+        attributedRisks.push(residualRiskEntry("deferred_state_detail", "caveated", message, sourceProvenance("prime", preCutoverCommand("prime --context audit --format json"), "capability_context.startup.availability")));
+    }
+    if (bundle.status !== "up_to_date") {
+        const message = "Agentera app files are not up to date; this is a caveat, not approval to repair or update app files.";
+        stateCaveats.push(message);
+        attributedRisks.push(residualRiskEntry("installed_app_state", "caveated", message, sourceProvenance("status", preCutoverCommand("prime --format json"), "app.status")));
+    }
+    if (profile.status !== "valid") {
+        const message = "profile-derived state is unavailable in prime --context response.";
+        stateCaveats.push(message);
+        attributedRisks.push(residualRiskEntry("profile_state", "unavailable", message, sourceProvenance("status", preCutoverCommand("prime --format json"), "profile.status")));
+    }
+    else if (profile.stale === true) {
+        const message = "profile-derived state is stale; this is a caveat, not approval to refresh profile state.";
+        stateCaveats.push(message);
+        attributedRisks.push(residualRiskEntry("profile_state", "caveated", message, sourceProvenance("status", preCutoverCommand("prime --format json"), "profile.stale")));
+    }
+    for (const component of [evaluationTarget, planCriteria, progressVerification, docsState, healthState, todoState, protectedStateChecks, versionChecks]) {
+        for (const caveat of (component.caveats ?? [])) {
+            stateCaveats.push(caveat);
+            // cast: component source_provenance comes from evidence builders backed by parsed artifact/decision state
+            const componentSp = component.source_provenance ?? sourceProvenance("evidence_context", preCutoverCommand("prime --context audit --format json"));
+            attributedRisks.push(residualRiskEntry("evidence_family", "caveated", caveat, componentSp));
+        }
+    }
+    for (const caveat of (decisionRisk.caveats ?? [])) {
+        stateCaveats.push(caveat);
+        attributedRisks.push(residualRiskEntry("decisions_context", decisionRisk.status, caveat, decisionRisk.source_provenance));
+    }
+    for (const caveat of (reviewPressure.caveats ?? [])) {
+        stateCaveats.push(caveat);
+        attributedRisks.push(residualRiskEntry("decision_review_pressure", reviewPressure.status, caveat, reviewPressure.source_provenance));
+    }
+    const retry = retryState();
+    for (const caveat of (retry.caveats ?? [])) {
+        stateCaveats.push(caveat);
+        attributedRisks.push(residualRiskEntry("retry_state", retry.status, caveat, retry.source_provenance));
+    }
+    stateCaveats = uniqueList(stateCaveats);
+    const dedupedRisks = [];
+    const seen = new Set();
+    for (const risk of attributedRisks) {
+        const key = `${risk.category}\u0000${risk.message}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            dedupedRisks.push(risk);
+        }
+    }
+    const requiredState = {
+        evaluation_target: evaluationTarget.status === "selected",
+        plan_criteria: planCriteria.status === "available",
+        progress_verification: progressVerification.status === "available",
+        docs_state: docsState.status === "available",
+        health_state: healthState.status === "available",
+        todo_state: todoState.status === "available",
+        source_contract: true,
+    };
+    const missingRequired = Object.entries(requiredState).filter(([, present]) => !present).map(([name]) => name);
+    const fallbackCommands = uniqueList([
+        STATE_FAMILY_FALLBACK_COMMANDS.plan,
+        STATE_FAMILY_FALLBACK_COMMANDS.progress,
+        STATE_FAMILY_FALLBACK_COMMANDS.docs,
+        STATE_FAMILY_FALLBACK_COMMANDS.health,
+        STATE_FAMILY_FALLBACK_COMMANDS.todo,
+        preCutoverCommand("state query --list-artifacts --format json"),
+    ]);
+    return {
+        capability: "audit",
+        evaluation_target: evaluationTarget,
+        plan_criteria: planCriteria,
+        progress_verification: progressVerification,
+        docs_state: docsState,
+        health_state: healthState,
+        todo_state: todoState,
+        protected_state_checks: protectedStateChecks,
+        version_checks: versionChecks,
+        decision_context: decisionRisk,
+        decision_review_pressure: reviewPressure,
+        residual_risks: {
+            status: dedupedRisks.length > 0 ? "caveated" : "none_recorded",
+            items: stateCaveats,
+            attributed_items: dedupedRisks,
+            caveats: [],
+        },
+        state_family_caveats: stateCaveats,
+        fallback_commands: fallbackCommands,
+        source_contract: {
+            complete_for_evidence_context: missingRequired.length === 0,
+            caveated: stateCaveats.length > 0,
+            raw_artifact_reads_required: false,
+            raw_artifact_read_policy: "Use this evidence_context and included status state first. Run listed routine/query CLI fallback commands " +
+                "for missing or incomplete evidence state; raw artifact reads are last-resort diagnostics, not normal evaluation startup behavior.",
+            required_evidence_state: requiredState,
+            missing_required_evidence_state: missingRequired,
+            fallback_commands: fallbackCommands,
+            caveats: stateCaveats,
+            owns: [
+                "evaluation target",
+                "plan criteria",
+                "progress verification",
+                "docs state",
+                "health state",
+                "TODO state",
+                "protected-state placeholder checks",
+                "version boundary checks",
+                "compacted decision caveats",
+                "protected decision review pressure",
+                "attributed residual risks",
+                "fallback commands",
+                "raw-read policy",
+                "truthful completeness metadata",
+            ],
+            deferred: [],
+        },
+    };
+}

package/dist/cli/capabilityContext/index.js

@@ -0,0 +1,3 @@
+export { CAPABILITY_NAMES } from "./types.js";
+export { validatePrimeCapability } from "./shared.js";
+export { buildPrimeCapabilityContextPayload } from "./startup.js";

package/dist/cli/capabilityContext/orchestration.js

@@ -0,0 +1,131 @@
+import { capabilityContext } from "./contract.js";
+import { entryStatus, uniqueList } from "./shared.js";
+import { formatPlanTaskDepRef, indexPlanTasksByNumber, orchestrationTaskSummary, planDependsOnList, resolvePlanTaskByRef, DONE_STATUSES_ORCH, BLOCKED_STATUSES_ORCH, } from "./planState.js";
+import { progressVerificationSummary, retryState, evaluatorHandoff } from "./progress.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS } from "./types.js";
+import { planLifecycleState } from "../planLifecycleState.js";
+import { planTaskIndex } from "../planTaskIndex.js";
+import { entityListFamily } from "../../state/entityRetrievalHelp.js";
+import { deferredStartupFamilies } from "./startupAggregation.js";
+import { preCutoverCommand, preCutoverCommandFromBare } from "../preCutoverCommand.js";
+export function orchestrationContext(capability, plan, progress, health, todoItems, docs, profile, nextAction) {
+    if (capability !== "orchestrate")
+        return null;
+    const lifecycle = planLifecycleState(plan);
+    const tasks = lifecycle.current_plan_degraded === true
+        ? []
+        : planTaskIndex(plan);
+    const taskByNumber = indexPlanTasksByNumber(tasks);
+    const dependencyReady = [];
+    const blocked = [];
+    const complete = tasks.filter((task) => entryStatus(task, "pending") === "complete").length;
+    const superseded = tasks.filter((task) => entryStatus(task, "pending") === "superseded").length;
+    const statusCounts = tasks.reduce((counts, task) => {
+        const status = entryStatus(task, "pending");
+        counts[status] = (counts[status] ?? 0) + 1;
+        return counts;
+    }, {});
+    for (const task of tasks) {
+        const status = entryStatus(task, "pending");
+        if (DONE_STATUSES_ORCH.has(status))
+            continue;
+        const reasons = [];
+        if (BLOCKED_STATUSES_ORCH.has(status))
+            reasons.push(`task status is ${status}`);
+        for (const dep of planDependsOnList(task)) {
+            const dependency = resolvePlanTaskByRef(taskByNumber, dep);
+            if (dependency === undefined)
+                reasons.push(`dependency ${formatPlanTaskDepRef(dep)} is not present in plan tasks`);
+            else if (!DONE_STATUSES_ORCH.has(entryStatus(dependency, "pending"))) {
+                reasons.push(`dependency ${formatPlanTaskDepRef(dep)} is ${entryStatus(dependency, "pending")}`);
+            }
+        }
+        if (reasons.length > 0)
+            blocked.push({ ...orchestrationTaskSummary(task), blocked_reasons: reasons });
+        else
+            dependencyReady.push(orchestrationTaskSummary(task));
+    }
+    const selected = dependencyReady.length > 0 ? dependencyReady[0] : null;
+    const planTasks = entityListFamily("plan_tasks");
+    const queueCommand = plan.id
+        ? preCutoverCommand(`state ${planTasks.commandTokens.join(" ")} list ${String(plan.id)} --limit 100 --format json`)
+        : null;
+    const queueRetrieval = queueCommand
+        ? { list: queueCommand, restart: queueCommand, get: preCutoverCommandFromBare(planTasks.get) }
+        : null;
+    const stateCaveats = [];
+    let fallbackCommands = [];
+    const capabilityContract = capabilityContext(capability) ?? {};
+    for (const family of deferredStartupFamilies(capabilityContract)) {
+        stateCaveats.push(`${family} detail is deferred from prime --context startup.`);
+    }
+    if (!plan.exists) {
+        stateCaveats.push("plan state is unavailable; task queue cannot be complete.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
+    }
+    if (lifecycle.status === "degraded") {
+        stateCaveats.push(...(lifecycle.caveats ?? []));
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
+    }
+    if (!progress.exists) {
+        stateCaveats.push("progress state is unavailable; latest verification is not summarized here.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.progress);
+    }
+    if (!health.exists) {
+        stateCaveats.push("health state is unavailable or incomplete.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.health);
+    }
+    if (!docs.exists) {
+        stateCaveats.push("docs mapping state is unavailable or incomplete.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.docs);
+    }
+    if (todoItems.length === 0) {
+        stateCaveats.push("todo state has no open entries in prime --context response; absence may mean none open or unavailable.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.todo);
+    }
+    if (profile.status !== "valid") {
+        stateCaveats.push("profile-derived state is unavailable in prime --context response.");
+    }
+    else if (profile.stale === true) {
+        stateCaveats.push("profile-derived state is stale; this is a caveat, not approval to refresh profile state.");
+    }
+    fallbackCommands = uniqueList(fallbackCommands);
+    const progressVerification = progressVerificationSummary(progress);
+    const retry = retryState(selected, tasks);
+    const handoff = evaluatorHandoff(selected, progressVerification, retry, stateCaveats);
+    const contextComplete = Boolean(plan.exists) && tasks.length > 0 && stateCaveats.length === 0 && (dependencyReady.length + blocked.length === 0 || queueRetrieval !== null);
+    return {
+        capability: "orchestrate",
+        task_queue: { total: tasks.length, complete, superseded, status_counts: statusCounts, dependency_ready_tasks: dependencyReady, blocked_tasks: blocked, retrieval: queueRetrieval },
+        selected_next_task: selected,
+        selected_next_action: nextAction,
+        progress_verification: progressVerification,
+        retry_state: retry,
+        plan_lifecycle_state: lifecycle,
+        evaluator_handoff: handoff,
+        task_summaries: tasks.map((task) => orchestrationTaskSummary(task)),
+        state_family_caveats: stateCaveats,
+        fallback_commands: fallbackCommands,
+        source_contract: {
+            complete_for_orchestration_context: contextComplete,
+            raw_artifact_reads_required: false,
+            raw_artifact_read_policy: "Use this orchestration_context and included status state first. Run listed routine CLI fallback commands " +
+                "for missing or incomplete state families; raw artifact reads are last-resort diagnostics, not normal startup behavior.",
+            fallback_commands: fallbackCommands,
+            caveats: stateCaveats,
+            owns: [
+                "dependency-ready task queue",
+                "blocked task reasons",
+                "selected next task",
+                "task acceptance summaries",
+                "task evidence summaries",
+                "latest progress verification summary",
+                "retry_state provenance",
+                "evaluator handoff inputs",
+                "state-family caveats",
+                "plan lifecycle state",
+            ],
+            deferred: [],
+        },
+    };
+}