agentera 3.0.0-dev.6 → 3.0.0-dev.69

package/dist/cli/capabilityContext/planState.js

@@ -1,8 +1,8 @@
-import fs from "node:fs";
 import { asList } from "../stateQuery.js";
-import { artifactPath } from "../appContext.js";
-import { sourceMetadata } from "../stateQuery.js";
 import { entryStatus, sourceProvenance, taskRef, hasRecordedValue, } from "./shared.js";
+import { planTaskIndex } from "../planTaskIndex.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS } from "./types.js";
+import { boundedChangelogUnavailable, CHANGELOG_MAX_OUTPUT_BYTES, readChangelog, } from "../../state/changelog.js";
 export function orchestrationTaskSummary(task) {
     const evidence = task.evidence;
     const evidenceItems = Array.isArray(evidence) ? evidence : evidence === null || evidence === undefined || evidence === "" ? [] : [evidence];
@@ -11,9 +11,10 @@ export function orchestrationTaskSummary(task) {
         depends_on: planDependsOnList(task),
         acceptance_summary: { count: asList(task.acceptance).length, items: asList(task.acceptance) },
         evidence_summary: { count: evidenceItems.length, items: evidenceItems },
+        evaluation_state: task.evaluation ?? null,
     };
 }
-/** Coerce plan task numbers and depends_on refs to comparable lookup keys (int/string/object forms). */
+/** Coerce canonical IDs and internal legacy task refs to comparable lookup keys. */
 export function planTaskRefKeys(value) {
     if (value === null || value === undefined)
         return [];
@@ -46,10 +47,10 @@ export function planDependsOnList(task) {
 export function indexPlanTasksByNumber(tasks) {
     const taskByNumber = {};
     for (const task of tasks) {
-        if (task.number === null || task.number === undefined)
-            continue;
-        for (const key of planTaskRefKeys(task.number))
-            taskByNumber[key] = task;
+        for (const value of [task.id, task.number]) {
+            for (const key of planTaskRefKeys(value))
+                taskByNumber[key] = task;
+        }
     }
     return taskByNumber;
 }
@@ -61,15 +62,16 @@ export function resolvePlanTaskByRef(taskByNumber, dep) {
     }
     return undefined;
 }
-export const DONE_STATUSES_ORCH = new Set(["complete", "completed", "closed", "done", "resolved", "retired"]);
+export const DONE_STATUSES_ORCH = new Set(["complete", "completed", "closed", "done", "resolved", "retired", "superseded"]);
 export const BLOCKED_STATUSES_ORCH = new Set(["blocked", "stuck"]);
 export const TARGET_VERSION_RE = /\b\d+\.\d+\.\d+\b/;
+export const TARGET_VERSION_MAX_BYTES = 64;
 export function dependencyReadyTasks(tasks) {
     const taskByNumber = indexPlanTasksByNumber(tasks);
     const ready = [];
     for (const task of tasks) {
         const status = entryStatus(task, "pending");
-        if (DONE_STATUSES_ORCH.has(status) || BLOCKED_STATUSES_ORCH.has(status))
+        if (status !== "pending")
             continue;
         let blocked = false;
         for (const dep of planDependsOnList(task)) {
@@ -84,37 +86,34 @@ export function dependencyReadyTasks(tasks) {
     }
     return ready;
 }
+export function firstActionablePlanTask(tasks) {
+    return tasks.find((task) => entryStatus(task, "pending") === "in_progress")
+        ?? dependencyReadyTasks(tasks)[0]
+        ?? null;
+}
 export function selectEvidenceTarget(plan) {
-    const tasks = asList(plan.tasks).filter((t) => t && typeof t === "object" && !Array.isArray(t));
+    const tasks = planTaskIndex(plan);
     const noTarget = {
         status: "no_target",
         target_type: "repository",
         task: null,
         selection_reason: "no_plan_task_target",
-        source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries"),
+        source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries"),
         caveats: ["No plan task target was selected; evaluate repository-level evidence only."],
     };
     if (!plan.exists || tasks.length === 0)
         return noTarget;
-    const inProgress = tasks.find((task) => entryStatus(task, "pending") === "in_progress");
-    if (inProgress) {
-        return {
-            status: "selected",
-            target_type: "plan_task",
-            task: taskRef(inProgress),
-            selection_reason: "in_progress_task",
-            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.status"),
-            caveats: [],
-        };
-    }
-    const ready = dependencyReadyTasks(tasks);
-    if (ready.length > 0) {
+    const actionable = firstActionablePlanTask(tasks);
+    if (actionable) {
+        const inProgress = entryStatus(actionable, "pending") === "in_progress";
         return {
             status: "selected",
             target_type: "plan_task",
-            task: taskRef(ready[0]),
-            selection_reason: "first_dependency_ready_pending_task",
-            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.depends_on"),
+            task: taskRef(actionable),
+            selection_reason: inProgress
+                ? "in_progress_task"
+                : "first_dependency_ready_pending_task",
+            source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, inProgress ? "entries.status" : "entries.depends_on"),
             caveats: [],
         };
     }
@@ -125,7 +124,7 @@ export function selectEvidenceTarget(plan) {
             target_type: "plan_task",
             task: taskRef(completedWithEvidence),
             selection_reason: "latest_completed_task_with_evidence",
-            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.evidence"),
+            source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries.evidence"),
             caveats: [],
         };
     }
@@ -134,17 +133,14 @@ export function selectEvidenceTarget(plan) {
 export function taskByRef(plan, ref) {
     if (!ref)
         return null;
-    for (const task of asList(plan.tasks)) {
-        if (task && typeof task === "object" && !Array.isArray(task) && task.number === ref.number)
-            return task;
-    }
-    return null;
+    const tasks = planTaskIndex(plan);
+    return resolvePlanTaskByRef(indexPlanTasksByNumber(tasks), ref) ?? null;
 }
 export function planContextField(plan, field) {
     const summary = plan.summary && typeof plan.summary === "object" && !Array.isArray(plan.summary) ? plan.summary : {};
     return field in summary ? summary[field] : plan[field];
 }
-export function realiseraScopeBoundary(plan, selected) {
+export function buildScopeBoundary(plan, selected) {
     const explicitPaths = [];
     const scopeField = planContextField(plan, "scope");
     const sources = [selected ?? {}, scopeField && typeof scopeField === "object" ? scopeField : {}];
@@ -168,31 +164,42 @@ export function realiseraScopeBoundary(plan, selected) {
         },
     };
 }
-export function realiseraArtifactUpdateRequirements(plan, docs) {
+export function buildArtifactUpdateRequirements(plan, docs) {
     const mapping = asList(docs.mapping);
     const mapped = mapping.filter((e) => e && typeof e === "object" && e.artifact).map((e) => e.artifact);
+    const archiveOnly = Boolean(plan.exists) && plan.active === false;
+    const completionSweep = plan.active === true && Boolean(plan.complete_plan);
     return {
-        required_families: ["plan", "progress", "todo", "changelog"],
+        required_families: archiveOnly
+            ? []
+            : ["plan", "todo", "changelog", ...(completionSweep ? ["progress"] : [])],
+        conditional_families: archiveOnly || completionSweep ? [] : ["progress"],
         protected_families: ["vision", "objective", "profile", "installed_app"],
         docs_mapping_available: Boolean(docs.exists && mapping.length > 0),
         mapped_artifacts: mapped,
-        plan_status_update_required: Boolean(plan.exists),
-        policy: "Update execution artifacts during the cycle; do not mutate protected state without explicit approval.",
-        source_provenance: sourceProvenance("docs", "agentera docs --format json", "summary.mapping"),
+        plan_status_update_required: plan.active === true,
+        policy: archiveOnly
+            ? "Archived plan history is non-executable and requires no execution artifact updates."
+            : "Update required execution artifacts during the cycle; evaluate conditional progress through its typed writer guidance and do not mutate protected state without explicit approval.",
+        source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.mapping"),
     };
 }
-export function realiseraPlanCompletionSweep(plan) {
-    const complete = Boolean(plan.complete_plan);
+export function buildPlanCompletionSweep(plan) {
+    const complete = plan.active === true && Boolean(plan.complete_plan);
     return {
         status: complete ? "eligible" : "not_eligible",
         mutation_allowed: false,
-        required_updates: ["progress aggregate cycle", "changelog plan-level entries", "TODO milestone advance", "health cross-reference"],
-        archive_candidate: complete ? "active plan archive path is generated only during Realisera sweep execution" : null,
-        caveats: complete ? [] : ["Plan completion sweep is not eligible until every plan task is complete."],
-        source_provenance: sourceProvenance("plan", "agentera plan --format json", "summary.status"),
+        required_updates: complete ? ["progress aggregate cycle", "changelog plan-level entries", "TODO milestone advance", "health cross-reference"] : [],
+        archive_candidate: complete ? "active plan archive path is generated only during Build sweep execution" : null,
+        caveats: complete
+            ? []
+            : plan.active === false && plan.exists
+                ? ["Archived plan history is non-executable and cannot trigger a completion sweep."]
+                : ["Plan completion sweep is not eligible until every plan task is complete."],
+        source_provenance: sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "summary.status"),
     };
 }
-export function selectedTargetVersion(plan) {
+function selectedTargetVersionState(plan) {
     const textParts = [String(plan.title ?? "")];
     const firstPending = plan.first_pending;
     if (firstPending && typeof firstPending === "object" && !Array.isArray(firstPending)) {
@@ -206,66 +213,52 @@ export function selectedTargetVersion(plan) {
         }
     }
     const match = TARGET_VERSION_RE.exec(textParts.join("\n"));
-    return match ? match[0] : null;
+    if (!match)
+        return { value: null, boundExceeded: false };
+    if (Buffer.byteLength(match[0], "utf8") > TARGET_VERSION_MAX_BYTES) {
+        return { value: null, boundExceeded: true };
+    }
+    return { value: match[0], boundExceeded: false };
 }
-export function changelogRecordsTarget(text, targetVersion) {
-    if (!targetVersion)
-        return false;
-    const escaped = targetVersion.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-    const re = new RegExp(`(?<![\\d.])${escaped}(?![\\d.+-])`);
-    return text.split(/\r\n|\r|\n/).some((line) => re.test(line));
+export function selectedTargetVersion(plan) {
+    return selectedTargetVersionState(plan).value;
 }
-export function closeoutChangelogBoundary(schemas, plan) {
-    const info = schemas.changelog ?? { path: "CHANGELOG.md", record: undefined, schema: {}, fields: {} };
-    const p = artifactPath(info, "changelog");
-    const source = sourceMetadata("changelog", p);
-    const targetVersion = selectedTargetVersion(plan);
-    const unavailable = (caveat) => ({
-        status: "unavailable",
-        source,
-        source_provenance: sourceProvenance("changelog", "agentera query changelog --format json"),
-        selected_target_version: targetVersion,
-        selected_target_recorded: false,
-        unreleased_present: false,
-        latest_release_heading: null,
-        boundary_present: false,
-        boundary: null,
-        caveats: [caveat],
-    });
-    if (!fs.existsSync(p))
-        return unavailable("CHANGELOG state is unavailable in CLI state.");
-    let text;
-    try {
-        text = fs.readFileSync(p, "utf8");
+function serializedProjectionBytes(projection) {
+    return Buffer.byteLength(`${JSON.stringify(projection, null, 2)}\n`, "utf8");
+}
+export function closeoutChangelogBoundary(projectRoot, plan) {
+    const shared = readChangelog(projectRoot);
+    const target = selectedTargetVersionState(plan);
+    const targetVersion = target.value;
+    const selectedRecorded = shared.projection.status === "available"
+        && targetVersion !== null
+        && shared.recognizedReleaseVersions.includes(targetVersion);
+    const caveats = [...(shared.projection.caveats ?? [])];
+    if (shared.projection.status === "available" && targetVersion && !selectedRecorded) {
+        caveats.push(`CHANGELOG state has no ${targetVersion} closeout entry yet.`);
     }
-    catch (exc) {
-        return unavailable(`CHANGELOG state could not be read by the CLI: ${exc.message}`);
+    if (target.boundExceeded) {
+        caveats.push("Selected target version is unavailable because its identity exceeds the supported bound.");
     }
-    const headings = text.split(/\r\n|\r|\n/).filter((line) => line.startsWith("## ")).map((line) => line.trim());
-    const unreleased = headings.find((h) => h.toLowerCase().includes("unreleased")) ?? null;
-    const latestRelease = headings.find((h) => !h.toLowerCase().includes("unreleased")) ?? null;
-    const selectedRecorded = changelogRecordsTarget(text, targetVersion);
-    const caveats = [];
-    if (headings.length === 0)
-        caveats.push("CHANGELOG state has no release headings.");
-    if (targetVersion && !selectedRecorded)
-        caveats.push(`CHANGELOG state has no ${targetVersion} closeout entry yet.`);
-    const boundary = unreleased || latestRelease;
-    return {
-        status: headings.length > 0 ? "available" : "incomplete",
-        source,
-        source_provenance: {
-            ...sourceProvenance("changelog", "agentera query changelog --format json", "release_headings"),
-            internal_source: "CLI-resolved CHANGELOG.md heading scan",
-        },
+    const boundary = {
+        ...shared.projection,
         selected_target_version: targetVersion,
         selected_target_recorded: selectedRecorded,
-        unreleased_present: unreleased !== null,
-        latest_release_heading: latestRelease,
-        boundary_present: boundary !== null,
-        boundary,
         release_state: selectedRecorded ? "selected_target_recorded" : "no_selected_target_closeout_entry",
         caveats,
+        recovery: shared.projection.recovery ?? null,
     };
+    if (serializedProjectionBytes(boundary) <= CHANGELOG_MAX_OUTPUT_BYTES)
+        return boundary;
+    const bounded = boundedChangelogUnavailable("CHANGELOG closeout state is unavailable because its bounded target overlay exceeds the supported output limit.").projection;
+    const fallback = {
+        ...bounded,
+        selected_target_version: null,
+        selected_target_recorded: false,
+        release_state: "no_selected_target_closeout_entry",
+    };
+    if (serializedProjectionBytes(fallback) > CHANGELOG_MAX_OUTPUT_BYTES) {
+        throw new Error("fixed changelog closeout projection exceeds its output limit");
+    }
+    return fallback;
 }
-//# sourceMappingURL=planState.js.map

package/dist/cli/capabilityContext/progress.js

@@ -1,8 +1,9 @@
 import { evaluatorHandoffOutputRequirements, loadEvaluatorHandoffContract, } from "../../registries/evaluatorHandoffContract.js";
 import { capabilityInstructionContractPath } from "./contract.js";
 import { hasRecordedValue, isFile, taskRef } from "./shared.js";
+import { STATE_FAMILY_LIST_COMMANDS } from "./types.js";
 export function progressVerificationSummary(progress) {
-    const source = { source_family: "progress", command: "agentera progress --format json" };
+    const source = { source_family: "progress", command: STATE_FAMILY_LIST_COMMANDS.progress };
     if (!progress.exists) {
         return {
             status: "unavailable",
@@ -19,7 +20,11 @@ export function progressVerificationSummary(progress) {
     }
     const latest = progress.latest && typeof progress.latest === "object" && !Array.isArray(progress.latest) ? progress.latest : {};
     const verified = latest.verified;
-    const verifiedPresent = hasRecordedValue(verified);
+    const latestVerification = progress.latest_verification && typeof progress.latest_verification === "object" && !Array.isArray(progress.latest_verification)
+        ? progress.latest_verification
+        : {};
+    const projectedVerifiedPresent = latest.verified_present === true || latestVerification.present === true;
+    const verifiedPresent = hasRecordedValue(verified) || projectedVerifiedPresent;
     const cycle = {};
     for (const key of ["number", "timestamp", "type", "phase"]) {
         if (latest[key] !== null && latest[key] !== undefined && latest[key] !== "")
@@ -35,21 +40,56 @@ export function progressVerificationSummary(progress) {
         verified_present: verifiedPresent,
         non_empty_evidence_present: verifiedPresent,
         non_empty_evidence_fields: evidenceFields,
-        verified: verifiedPresent ? verified : null,
-        verification_summary: verifiedPresent ? verified : null,
+        verified: hasRecordedValue(verified) ? verified : null,
+        verification_summary: hasRecordedValue(verified) ? verified : projectedVerifiedPresent ? { present: true } : null,
         latest_progress_verification_pointer: pointer,
         caveats,
     };
 }
-export function retryState() {
+export function retryState(selected = null, tasks = []) {
+    const task = selected ??
+        tasks.find((candidate) => {
+            const evaluation = candidate.evaluation;
+            return Boolean(evaluation && typeof evaluation === "object" && !Array.isArray(evaluation));
+        }) ??
+        null;
+    const evaluation = task && task.evaluation_state && typeof task.evaluation_state === "object" && !Array.isArray(task.evaluation_state)
+        ? task.evaluation_state
+        : task && task.evaluation && typeof task.evaluation === "object" && !Array.isArray(task.evaluation)
+            ? task.evaluation
+            : null;
+    const source = {
+        source_family: "plan",
+        command: "agentera state plan record-evaluation --id ID --attempt-id ID --verdict {pass,fail}",
+    };
+    if (evaluation) {
+        const attemptCount = Number(evaluation.attempt_count ?? 0);
+        const failureCount = Number(evaluation.failure_count ?? 0);
+        const exhausted = failureCount >= 2;
+        return {
+            status: exhausted ? "exhausted" : "recorded",
+            task: taskRef(task),
+            attempt_count: Number.isInteger(attemptCount) ? attemptCount : null,
+            failure_count: Number.isInteger(failureCount) ? failureCount : null,
+            retry_budget: 2,
+            last_verdict: evaluation.last_verdict ?? null,
+            failure_evidence: evaluation.last_failure_evidence ?? null,
+            provenance: evaluation.provenance ?? null,
+            source_provenance: source,
+            caveats: exhausted ? ["Evaluation retry budget is exhausted; the task is blocked."] : [],
+        };
+    }
     return {
         status: "not_recorded",
-        source_provenance: {
-            source_family: "progress",
-            command: "agentera progress --format json",
-            reason: "Current CLI/artifact state records progress cycles but no retry attempt state for orchestration tasks.",
-        },
-        caveats: ["Retry attempt state is not recorded; no attempt count is exposed."],
+        task: task ? taskRef(task) : null,
+        attempt_count: 0,
+        failure_count: 0,
+        retry_budget: 2,
+        last_verdict: null,
+        failure_evidence: null,
+        provenance: null,
+        source_provenance: source,
+        caveats: [],
     };
 }
 export function evaluatorHandoffOutputRequirementsFromContract() {
@@ -58,6 +98,7 @@ export function evaluatorHandoffOutputRequirementsFromContract() {
         return {};
     try {
         const contract = loadEvaluatorHandoffContract(contractPath);
+        // cast: contract loaded from parsed capability-instruction-contract.yaml; registry returns Record<string,unknown>
         return evaluatorHandoffOutputRequirements(contract);
     }
     catch {
@@ -79,18 +120,23 @@ export function evaluatorHandoff(selected, progressVerification, retry, stateCav
             output_requirements: outputRequirements,
         };
     }
-    const evidenceRequirements = (selected.evidence_summary?.items ?? []);
+    const evidenceSummary = selected.evidence_summary && typeof selected.evidence_summary === "object" && !Array.isArray(selected.evidence_summary)
+        ? selected.evidence_summary
+        : null;
+    const evidenceRequirements = (evidenceSummary?.items ?? []);
     if (evidenceRequirements.length === 0) {
         caveats.push("Selected task has no explicit evidence requirements recorded in plan state.");
     }
+    const acceptanceSummary = selected.acceptance_summary && typeof selected.acceptance_summary === "object" && !Array.isArray(selected.acceptance_summary)
+        ? selected.acceptance_summary
+        : null;
     return {
         status: "ready",
         task: taskRef(selected),
-        acceptance_criteria: selected.acceptance_summary?.items ?? [],
+        acceptance_criteria: acceptanceSummary?.items ?? [],
         evidence_requirements: evidenceRequirements,
         latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
         evaluation_caveats: caveats,
         output_requirements: outputRequirements,
     };
 }
-//# sourceMappingURL=progress.js.map