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

package/dist/cli/capabilityContext/closeout.js

@@ -7,12 +7,15 @@ import { docsConventions, sourceProvenance, uniqueList } from "./shared.js";
 import { closeoutChangelogBoundary } from "./planState.js";
 import { progressVerificationSummary } from "./progress.js";
 import { decisionReviewPressure } from "./evidence.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS } from "./types.js";
+import { deferredStartupFamilies } from "./startupAggregation.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 export function closeoutArtifactMappings(docs) {
     const mapping = asList(docs.mapping);
     const ok = Boolean(docs.exists) && mapping.length > 0;
     return {
         status: ok ? "available" : "unavailable",
-        source_provenance: sourceProvenance("docs", "agentera docs --format json", "summary.mapping"),
+        source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.mapping"),
         entries: mapping,
         mapping_entries: mapping.length,
         caveats: ok ? [] : ["Docs artifact mappings are unavailable or empty in CLI docs state."],
@@ -26,21 +29,25 @@ export function closeoutVersionPolicy(docs) {
     const available = Object.keys(semverPolicy).length > 0;
     return {
         status: available ? "available" : "unavailable",
-        source_provenance: sourceProvenance("docs", "agentera docs --format json", "summary.conventions"),
+        source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.conventions"),
         version_files: versionFiles,
         version_files_registry: registry,
         semver_policy: semverPolicy,
         caveats: available ? [] : ["Docs version policy is unavailable in CLI docs state."],
     };
 }
-export function closeoutTodoBlockers(schemas, todoItems) {
+export function closeoutTodoBlockers(schemas, todoItems, selectedTargetVersion = null) {
     const info = schemas.todo ?? { path: "TODO.md", record: undefined, schema: {}, fields: {} };
     const exists = fs.existsSync(artifactPath(info, "todo"));
+    const blockers = selectedTargetVersion === null
+        ? []
+        : todoItems.filter((item) => item.status === "open" && item.release_blocker === true && item.target_version === selectedTargetVersion);
     return {
         status: exists ? "available" : "unavailable",
-        source_provenance: sourceProvenance("todo", "agentera todo --format json"),
-        open_count: todoItems.length,
-        items: todoItems,
+        source_provenance: sourceProvenance("todo", STATE_FAMILY_FALLBACK_COMMANDS.todo),
+        selected_target_version: selectedTargetVersion,
+        open_count: blockers.length,
+        items: blockers,
         caveats: exists ? [] : ["TODO state is unavailable in CLI state."],
     };
 }
@@ -50,7 +57,7 @@ export function closeoutBenchmarkEvidence(docs) {
     if (testsSummary && testsSummary.toLowerCase().includes("benchmark")) {
         return {
             status: "available",
-            source_provenance: sourceProvenance("docs", "agentera docs --format json", "summary.coverage.tests"),
+            source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.coverage.tests"),
             summary_present: true,
             non_empty_evidence_present: true,
             history_scope: "cli_visible_summary",
@@ -61,7 +68,7 @@ export function closeoutBenchmarkEvidence(docs) {
     }
     return {
         status: "unavailable",
-        source_provenance: sourceProvenance("docs", "agentera docs --format json", "summary.coverage.tests"),
+        source_provenance: sourceProvenance("docs", STATE_FAMILY_FALLBACK_COMMANDS.docs, "summary.coverage.tests"),
         summary_present: false,
         non_empty_evidence_present: false,
         history_scope: "not_exposed_by_supported_cli_state",
@@ -129,30 +136,30 @@ export function closeoutReleaseBoundary(changelogBoundary, bundle) {
             remote_push: "not_recorded_in_cli_state",
             remote_checks_performed: false,
             registry_checks_performed: false,
-            source_provenance: sourceProvenance("closeout_context", "agentera prime --context dokumentera --format json", "release_boundary.publication_evidence"),
+            source_provenance: sourceProvenance("closeout_context", preCutoverCommand("prime --context document --format json"), "release_boundary.publication_evidence"),
             caveats: ["Closeout context does not contact remotes or package registries."],
         },
         app_refresh_evidence: {
             installed_app_status: bundle.status ?? null,
             refresh: "not_recorded_in_cli_state",
             approval_recorded: false,
-            source_provenance: sourceProvenance("hej", "agentera hej --format json", "bundle.status"),
+            source_provenance: sourceProvenance("status", preCutoverCommand("prime --format json"), "app.status"),
         },
         caveats,
     };
 }
-export function dokumenteraCloseoutContext(capability, schemas, plan, progress, todoItems, docs, profile, bundle) {
-    if (capability !== "dokumentera")
+export function documentCloseoutContext(capability, schemas, plan, progress, todoItems, docs, profile, bundle, decisionHistory, projectRoot) {
+    if (capability !== "document")
         return null;
     const capabilityContract = capabilityContext(capability) ?? {};
     const artifactMappings = closeoutArtifactMappings(docs);
     const versionPolicy = closeoutVersionPolicy(docs);
-    const todoBlockers = closeoutTodoBlockers(schemas, todoItems);
-    const changelogBoundary = closeoutChangelogBoundary(schemas, plan);
+    const changelogBoundary = closeoutChangelogBoundary(projectRoot, plan);
+    const todoBlockers = closeoutTodoBlockers(schemas, todoItems, typeof changelogBoundary.selected_target_version === "string" ? changelogBoundary.selected_target_version : null);
     const progressEvidence = progressVerificationSummary(progress);
     const benchmarkEvidence = closeoutBenchmarkEvidence(docs);
     const releaseBoundary = closeoutReleaseBoundary(changelogBoundary, bundle);
-    const reviewPressure = decisionReviewPressure(schemas);
+    const reviewPressure = decisionReviewPressure(decisionHistory);
     const requiredState = {
         artifact_mappings: artifactMappings.status === "available",
         version_policy: versionPolicy.status === "available",
@@ -160,33 +167,32 @@ export function dokumenteraCloseoutContext(capability, schemas, plan, progress,
         changelog_boundary: Boolean(changelogBoundary.boundary_present),
         progress_evidence: progressEvidence.status === "available",
         benchmark_evidence_or_caveat: benchmarkEvidence.status === "available" || (benchmarkEvidence.caveats ?? []).length > 0,
-        decision_review_pressure: reviewPressure.status !== "review_required",
+        decision_review_pressure: reviewPressure.status === "available",
     };
     const missingRequired = Object.entries(requiredState).filter(([, present]) => !present).map(([k]) => k);
     let stateCaveats = [];
-    for (const family of (capabilityContract.missing_state_families ?? [])) {
-        stateCaveats.push(`${family} state is not included in prime --context startup context.`);
+    for (const family of deferredStartupFamilies(capabilityContract)) {
+        stateCaveats.push(`${family} detail is deferred from prime --context startup.`);
     }
     for (const component of [artifactMappings, versionPolicy, todoBlockers, changelogBoundary, releaseBoundary, progressEvidence, benchmarkEvidence, reviewPressure]) {
         stateCaveats.push(...(component.caveats ?? []));
     }
     if (bundle.status !== "up_to_date")
         stateCaveats.push("Agentera app files are not up to date; this is a caveat, not approval to repair or update app files.");
-    if (profile.status !== "loaded")
+    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.");
     stateCaveats = uniqueList(stateCaveats);
     const fallbackCommands = uniqueList([
-        "agentera todo --format json",
-        "agentera docs --format json",
-        "agentera progress --format json",
-        "agentera query changelog --format json",
-        "agentera query --list-artifacts --format json",
-        ...(capabilityContract.cli_fallback ?? []),
+        STATE_FAMILY_FALLBACK_COMMANDS.todo,
+        STATE_FAMILY_FALLBACK_COMMANDS.docs,
+        STATE_FAMILY_FALLBACK_COMMANDS.progress,
+        preCutoverCommand("state query changelog --format json"),
+        preCutoverCommand("state query --list-artifacts --format json"),
     ]);
     return {
-        capability: "dokumentera",
+        capability: "document",
         artifact_mappings: artifactMappings,
         version_policy: versionPolicy,
         todo_blockers: todoBlockers,
@@ -201,10 +207,8 @@ export function dokumenteraCloseoutContext(capability, schemas, plan, progress,
             complete_for_closeout_context: missingRequired.length === 0,
             caveated: stateCaveats.length > 0,
             raw_artifact_reads_required: false,
-            raw_artifact_read_policy: "Use this closeout_context and included hej state first. Run listed routine/query CLI fallback commands " +
+            raw_artifact_read_policy: "Use this closeout_context and included status state first. Run listed routine/query CLI fallback commands " +
                 "for missing or incomplete closeout state; raw artifact reads are last-resort diagnostics, not normal closeout behavior.",
-            included_state_families: capabilityContract.included_state_families ?? [],
-            missing_state_families: capabilityContract.missing_state_families ?? [],
             closeout_state_families: ["docs", "todo", "changelog", "progress", "benchmark_evidence", "decisions"],
             required_closeout_state: requiredState,
             missing_required_closeout_state: missingRequired,
@@ -227,4 +231,3 @@ export function dokumenteraCloseoutContext(capability, schemas, plan, progress,
         },
     };
 }
-//# sourceMappingURL=closeout.js.map

package/dist/cli/capabilityContext/contract.js

@@ -3,9 +3,11 @@ import path from "node:path";
 import { loadYamlMapping } from "../../core/yaml.js";
 import { activeAppModel, discoverSchemasDir } from "../appContext.js";
 import { capabilityStartupCommand } from "../../capabilities/index.js";
-import { PLANERA_COMPLETED_PLAN_ARCHIVE_CONFIRMATION, PLANERA_INSTRUCTIONS_AUTHORITY_EXCEPTIONS, PLANERA_PLANNING_LEVELS, PLANERA_RAW_PLAN_ACCESS_ALLOWED_FOR, PLANERA_STARTUP_CONTRACT_VERSION, PLANERA_STEP_VERBS, STARTUP_ENVELOPE_STATE_FAMILIES, STATE_FAMILY_FALLBACK_COMMANDS, } from "./types.js";
+import { PLAN_COMPLETED_PLAN_ARCHIVE_CONFIRMATION, PLAN_INSTRUCTIONS_AUTHORITY_EXCEPTIONS, PLAN_PLANNING_LEVELS, PLAN_RAW_PLAN_ACCESS_ALLOWED_FOR, PLAN_STARTUP_CONTRACT_VERSION, PLAN_STEP_VERBS, PLAN_TASK_COHERENCE_RULE, STATE_FAMILY_FALLBACK_COMMANDS, } from "./types.js";
 import { CAPABILITY_INSTRUCTIONS, capabilityInstructionModulePath } from "../../capabilities/index.js";
 import { isFile, pyRepr, appendUnique } from "./shared.js";
+import { startupAvailabilityProjection } from "./startupAggregation.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 export function capabilityInstructionContractPath() {
     const model = activeAppModel();
     const active = path.join(String(model.authoritativeRoot ?? model.activeBundleRoot), "references", "cli", "capability-instruction-contract.yaml");
@@ -18,7 +20,7 @@ export function capabilityInstructionContract() {
     if (!isFile(p))
         return {};
     try {
-        return loadYamlMapping(fs.readFileSync(p, "utf8"));
+        return loadYamlMapping(fs.readFileSync(p, "utf8")); // cast: IO boundary — YAML parse of capability-instruction contract file
     }
     catch (exc) {
         process.stderr.write(`warning: failed to load capability instruction contract: ${exc.message}\n`);
@@ -27,19 +29,21 @@ export function capabilityInstructionContract() {
 }
 export function capabilityInstructionTarget(capability) {
     const module = capabilityInstructionModulePath(capability);
-    const prose = CAPABILITY_INSTRUCTIONS[capability] ?? null;
+    const instructions = CAPABILITY_INSTRUCTIONS[capability] ?? null;
     return {
         module,
-        exists: prose !== null && prose.length > 0,
+        exists: instructions !== null && instructions.length > 0,
         runtime_path: module,
-        prose_present: prose !== null,
-        prose_length: prose === null ? 0 : prose.length,
+        instructions_present: instructions !== null,
+        instructions_length: instructions === null ? 0 : instructions.length,
     };
 }
 export function firstInvocationReadMetadata(capability) {
     const authority = capabilityInstructionContract();
-    const firstRead = authority.first_invocation_read && typeof authority.first_invocation_read === "object" ? authority.first_invocation_read : {};
-    const allowedValues = firstRead.allowed_values && typeof firstRead.allowed_values === "object" ? firstRead.allowed_values : {};
+    const firstRead = authority.first_invocation_read && typeof authority.first_invocation_read === "object" && !Array.isArray(authority.first_invocation_read)
+        ? authority.first_invocation_read
+        : {};
+    const allowedValues = firstRead.allowed_values && typeof firstRead.allowed_values === "object" && !Array.isArray(firstRead.allowed_values) ? firstRead.allowed_values : {};
     const value = "prime_context";
     const valueContract = (allowedValues[value] ?? {});
     return {
@@ -60,56 +64,56 @@ export function firstInvocationReadMetadata(capability) {
         },
     };
 }
-export function planeraStartupContract() {
+export function planStartupContract() {
     return {
-        schemaVersion: PLANERA_STARTUP_CONTRACT_VERSION,
+        schemaVersion: PLAN_STARTUP_CONTRACT_VERSION,
         status: "implemented_compact_normal_startup_contract",
-        canonical_surface: "agentera prime --context planera --format json",
+        canonical_surface: capabilityStartupCommand("plan"),
         bounded: true,
         instructions_runtime_read_required: false,
         instructions_authority: {
-            normal_startup: "Use this compact context for normal Planera execution startup; " +
-                "shell out to `agentera prime --context planera --format json` for the full Planera prose.",
-            read_planera_instructions_when: PLANERA_INSTRUCTIONS_AUTHORITY_EXCEPTIONS,
+            normal_startup: "Use this compact context for normal Plan execution startup; " +
+                `shell out to \`${capabilityStartupCommand("plan")}\` for the full Plan instructions.`,
+            read_plan_instructions_when: PLAN_INSTRUCTIONS_AUTHORITY_EXCEPTIONS,
         },
         planning: {
-            levels: PLANERA_PLANNING_LEVELS,
+            levels: PLAN_PLANNING_LEVELS,
             step_marker_format: "── step N/6: verb",
-            required_steps: PLANERA_STEP_VERBS,
+            required_steps: PLAN_STEP_VERBS,
             full_plan_review_required: true,
             pre_write_self_audit_required: true,
-            max_full_plan_tasks: 8,
+            task_coherence_rule: PLAN_TASK_COHERENCE_RULE,
         },
         cli_first_orientation: {
             use_startup_state_first: true,
-            current_plan_command: "agentera plan --format json",
+            current_plan_command: STATE_FAMILY_FALLBACK_COMMANDS.plan,
             complete_plan_contract_key: "source_contract.complete_for_plan_artifact",
             fallback_policy: "Use CLI-provided fallback commands for missing or incomplete state families " +
                 "before any last-resort raw artifact read.",
         },
         artifact_access_boundaries: {
-            skip_raw_plan_artifact_when: "`agentera plan --format json` reports source_contract.complete_for_plan_artifact=true " +
+            skip_raw_plan_artifact_when: `\`${STATE_FAMILY_FALLBACK_COMMANDS.plan}\` reports source_contract.complete_for_plan_artifact=true ` +
                 "during normal read-only startup or evaluation.",
-            raw_plan_artifact_allowed_for: PLANERA_RAW_PLAN_ACCESS_ALLOWED_FOR,
-            completed_plan_archive_confirmation: PLANERA_COMPLETED_PLAN_ARCHIVE_CONFIRMATION,
-            artifact_mapping_source: "agentera docs/query artifact mapping before writes or closeout",
+            raw_plan_artifact_allowed_for: PLAN_RAW_PLAN_ACCESS_ALLOWED_FOR,
+            completed_plan_archive_confirmation: PLAN_COMPLETED_PLAN_ARCHIVE_CONFIRMATION,
+            artifact_mapping_source: STATE_FAMILY_FALLBACK_COMMANDS.docs,
         },
         handoff_expectations: [
-            "skip level suggests ⧉ realisera and waits for confirmation unless the user already asked to implement now",
-            "single-task plans suggest ⧉ realisera and wait for confirmation",
-            "full plans suggest ⎈ orkestrera and wait for confirmation",
+            "skip level suggests ⧉ build and waits for confirmation unless the user already asked to implement now",
+            "single-task plans suggest ⧉ build and wait for confirmation",
+            "full plans suggest ⎈ orchestrate and wait for confirmation",
         ],
         unsupported_command_boundary: {
             capability_cli_commands_added: true,
             forbidden_examples: [],
-            route_boundary: "Use `/agentera plan` for routing, `agentera plan` for plan state, " +
-                "and `agentera planera` for capability routing guidance only.",
+            route_boundary: "Use `/agentera plan` for routing, `agentera state plan list` for plan state, " +
+                "and `agentera plan` for capability routing guidance only.",
         },
         seam_decision: {
             selected: "prime --context",
             not_changed: [
-                { surface: "agentera schema --format json", reason: "runtime/schema command discovery, not capability workflow startup context" },
-                { surface: "dispatcher guidance", reason: "route and CLI-state separation guidance, not a bounded Planera workflow payload" },
+                { surface: preCutoverCommand("schema --format json"), reason: "runtime/schema command discovery, not capability workflow startup context" },
+                { surface: "dispatcher guidance", reason: "route and CLI-state separation guidance, not a bounded Plan workflow payload" },
             ],
         },
     };
@@ -122,7 +126,7 @@ export function capabilityArtifactInventory(capability) {
         return [inventory, `No capability artifact schema found for ${capability}.`];
     let data;
     try {
-        data = loadYamlMapping(fs.readFileSync(p, "utf8"));
+        data = loadYamlMapping(fs.readFileSync(p, "utf8")); // cast: IO boundary — YAML parse of artifact inventory file
     }
     catch (exc) {
         return [inventory, `Capability artifact schema for ${capability} could not be read: ${exc.message}`];
@@ -138,10 +142,10 @@ export function capabilityArtifactInventory(capability) {
             continue;
         }
         const e = entry;
-        const artifactId = String(e.artifact_id ?? "").trim();
+        const artifactId = String(e.artifact ?? "").trim();
         const localRole = String(e.local_role ?? "").trim();
         if (!artifactId) {
-            errors.push(`entry ${key} is missing artifact_id`);
+            errors.push(`entry ${key} is missing artifact`);
             continue;
         }
         if (localRole === "consumes")
@@ -163,24 +167,13 @@ export function capabilityContext(capability) {
         return null;
     const [inventory, error] = capabilityArtifactInventory(capability);
     const needs = inventory.read_needs;
-    const writeTargets = inventory.write_targets;
-    const missing = needs.filter((name) => !STARTUP_ENVELOPE_STATE_FAMILIES.has(name));
-    const cliFallback = missing.filter((name) => name in STATE_FAMILY_FALLBACK_COMMANDS).map((name) => STATE_FAMILY_FALLBACK_COMMANDS[name]);
     const context = {
         capability,
         first_invocation_read: firstInvocationReadMetadata(capability),
-        declared_state_needs: needs,
-        declared_write_targets: writeTargets,
-        artifact_inventory: inventory,
-        included_state_families: needs.filter((name) => STARTUP_ENVELOPE_STATE_FAMILIES.has(name)),
-        missing_state_families: missing,
-        cli_fallback: cliFallback,
-        raw_artifact_read_policy: "Use the included state families from this prime --context response first. " +
-            "If needed families are missing or CLI state is incomplete, run the CLI fallback commands before raw file access.",
+        availability: startupAvailabilityProjection(needs),
         schema_error: error,
     };
-    if (capability === "planera")
-        context.startup_contract = planeraStartupContract();
+    if (capability === "plan")
+        context.startup_contract = planStartupContract();
     return context;
 }
-//# sourceMappingURL=contract.js.map