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

package/dist/cli/capabilityContext/build.js

@@ -0,0 +1,242 @@
+import { asList } from "../stateQuery.js";
+import { capabilityContext } from "./contract.js";
+import { sourceProvenance, uniqueList, hasRecordedValue, taskRef } from "./shared.js";
+import { closeoutChangelogBoundary, orchestrationTaskSummary, planContextField, buildArtifactUpdateRequirements, buildPlanCompletionSweep, buildScopeBoundary, selectEvidenceTarget, taskByRef, } from "./planState.js";
+import { progressVerificationSummary } from "./progress.js";
+import { STATE_FAMILY_FALLBACK_COMMANDS, STATE_FAMILY_LIST_COMMANDS } from "./types.js";
+import { planLifecycleState } from "../planLifecycleState.js";
+import { discoverProjectVerification } from "./projectVerification.js";
+import { deferredStartupFamilies } from "./startupAggregation.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
+const TRANSIENT_BUILD_INPUT_COMMAND = preCutoverCommand("prime --context build --input <file|-> --format json");
+const TRANSIENT_BUILD_STDIN_COMMAND = preCutoverCommand("prime --context build --input - --format json");
+function transientSourceProvenance(request, field) {
+    return {
+        source_family: "transient_build_execution_request",
+        command: TRANSIENT_BUILD_INPUT_COMMAND,
+        field,
+        schema_version: request.schema_version,
+        source_kind: request.source.kind,
+        persisted: false,
+    };
+}
+export function buildExecutionContext(capability, schemas, plan, progress, health, todoItems, docs, profile, bundle, projectRoot, buildRequest = null) {
+    if (capability !== "build")
+        return null;
+    const capabilityContract = capabilityContext(capability) ?? {};
+    const lifecycle = planLifecycleState(plan);
+    const tasks = lifecycle.current_plan_degraded === true
+        ? []
+        : asList(plan.tasks).filter((t) => t && typeof t === "object" && !Array.isArray(t));
+    const target = selectEvidenceTarget(plan);
+    const selected = taskByRef(plan, (target && typeof target === "object" ? target.task : null));
+    const acceptance = buildRequest?.acceptance
+        ?? (selected && typeof selected === "object" ? asList(selected.acceptance) : []);
+    const progressVerification = progressVerificationSummary(progress);
+    const changelogBoundary = closeoutChangelogBoundary(projectRoot, plan);
+    const sweep = buildPlanCompletionSweep(plan);
+    const archiveOnly = Boolean(plan.exists) && plan.active === false;
+    let mode;
+    if (plan.active === true && plan.complete_plan)
+        mode = "completed_plan_sweep";
+    else if (buildRequest !== null && plan.active !== true)
+        mode = "no_plan";
+    else if (archiveOnly)
+        mode = "archive_only_history";
+    else if (!plan.exists || tasks.length === 0)
+        mode = "no_plan";
+    else if (target.status === "selected" && selected !== null)
+        mode = "plan_driven";
+    else
+        mode = "blocked_or_dependency_unready";
+    let stateCaveats = [];
+    let fallbackCommands = [];
+    for (const family of deferredStartupFamilies(capabilityContract)) {
+        stateCaveats.push(`${family} detail is deferred from prime --context startup.`);
+    }
+    if (lifecycle.status === "degraded") {
+        stateCaveats.push(...(lifecycle.caveats ?? []));
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
+    }
+    if (mode === "blocked_or_dependency_unready") {
+        stateCaveats.push("No dependency-ready pending plan task is available in CLI plan state.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
+    }
+    if (mode === "plan_driven" && acceptance.length === 0) {
+        stateCaveats.push("Selected Build task has no acceptance criteria in CLI plan state.");
+        fallbackCommands.push(STATE_FAMILY_FALLBACK_COMMANDS.plan);
+    }
+    if (!progress.exists) {
+        stateCaveats.push("progress state is unavailable; progress logging context is incomplete.");
+        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 (changelogBoundary.status !== "available") {
+        stateCaveats.push(...(changelogBoundary.caveats ?? []));
+        fallbackCommands.push(preCutoverCommand("state query changelog --format json"));
+    }
+    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.");
+    }
+    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.");
+    }
+    const scopeBoundary = buildRequest === null
+        ? buildScopeBoundary(plan, selected)
+        : {
+            artifact_families: ["progress", "todo", "docs", "health", "changelog", "decisions", "vision", "profile", "design"],
+            explicit_scope: buildRequest.scope,
+            source_scope: {
+                status: "unspecified",
+                explicit_paths: [],
+                policy: "The transient scope defines work intent only; no source-file allowlist or exclusion is inferred from its text.",
+            },
+            source_provenance: transientSourceProvenance(buildRequest, "scope"),
+        };
+    const sourceScope = scopeBoundary.source_scope && typeof scopeBoundary.source_scope === "object" && !Array.isArray(scopeBoundary.source_scope)
+        ? scopeBoundary.source_scope
+        : {};
+    if (sourceScope.status === "unspecified") {
+        stateCaveats.push("source-file scope is unspecified; no allowed or prohibited source paths were inferred.");
+    }
+    const noCurrentPlan = plan.active !== true && lifecycle.status !== "degraded";
+    if (noCurrentPlan) {
+        fallbackCommands = fallbackCommands.filter((command) => command !== STATE_FAMILY_FALLBACK_COMMANDS.plan);
+        if (buildRequest === null) {
+            stateCaveats.push("Explicit no-plan scope and acceptance are required before Build can execute without a current plan.");
+            fallbackCommands.push(TRANSIENT_BUILD_STDIN_COMMAND);
+        }
+    }
+    fallbackCommands = uniqueList(fallbackCommands);
+    stateCaveats = uniqueList(stateCaveats);
+    const requiredState = {
+        work_selection: mode === "plan_driven" || mode === "completed_plan_sweep" || buildRequest !== null,
+        acceptance_criteria: mode === "completed_plan_sweep" || acceptance.length > 0,
+        artifact_update_requirements: Boolean(docs.exists),
+        progress_logging_requirements: progressVerification.status === "available" || (progressVerification.caveats ?? []).length > 0,
+        changelog_boundary: changelogBoundary.status === "available",
+        scope_boundary: true,
+        safety_boundaries: true,
+        plan_state_healthy: lifecycle.status !== "degraded",
+    };
+    const missingRequired = Object.entries(requiredState).filter(([, present]) => !present).map(([name]) => name);
+    const caveated = stateCaveats.length > 0;
+    const complete = (mode === "plan_driven" || mode === "completed_plan_sweep" || buildRequest !== null)
+        && missingRequired.length === 0;
+    const workSelection = buildRequest === null
+        ? {
+            status: target.status,
+            selection_reason: target.selection_reason,
+            task: selected && typeof selected === "object" ? taskRef(selected) : null,
+            source_provenance: target.source_provenance,
+            caveats: target.caveats ?? [],
+        }
+        : {
+            status: "selected",
+            selection_reason: "explicit_no_plan_scope",
+            task: null,
+            scope: buildRequest.scope,
+            source_provenance: transientSourceProvenance(buildRequest, "scope"),
+            caveats: [],
+        };
+    const artifactUpdateRequirements = buildArtifactUpdateRequirements(plan, docs);
+    if (buildRequest !== null) {
+        artifactUpdateRequirements.required_families = ["progress", "todo", "changelog"];
+        artifactUpdateRequirements.plan_status_update_required = false;
+        artifactUpdateRequirements.policy = "Transient no-plan work does not create, mutate, or require plan state.";
+    }
+    return {
+        capability: "build",
+        mode,
+        work_selection: workSelection,
+        plan_task: selected && typeof selected === "object" ? orchestrationTaskSummary(selected) : null,
+        acceptance_criteria: {
+            status: acceptance.length > 0 ? "available" : "incomplete",
+            items: acceptance,
+            count: acceptance.length,
+            source_provenance: buildRequest === null
+                ? sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "entries.acceptance")
+                : transientSourceProvenance(buildRequest, "acceptance"),
+        },
+        constraints: {
+            plan_constraints_present: buildRequest === null && hasRecordedValue(planContextField(plan, "constraints")),
+            plan_constraints_summary: buildRequest === null
+                ? "Plan constraints are represented here as structured safety and fallback policy; run the plan CLI fallback only if full wording is needed."
+                : "Transient no-plan input supplies scope and acceptance only; no plan constraints are inferred.",
+            protected_actions: [
+                "no profile refresh",
+                "no installed app refresh",
+                "no vision edit",
+                "no objective-state edit",
+                "no dispatch without explicit cycle execution",
+                "no commit/push/tag/publication without explicit approval",
+            ],
+            unsupported_cli_command_policy: "Do not introduce capability-name or slash-alias CLI commands for Build.",
+            source_provenance: buildRequest === null
+                ? sourceProvenance("plan", STATE_FAMILY_FALLBACK_COMMANDS.plan, "summary.constraints")
+                : transientSourceProvenance(buildRequest, "scope"),
+        },
+        scope_boundary: scopeBoundary,
+        verification_expectations: {
+            latest_progress_verification: progressVerification,
+            ...discoverProjectVerification(projectRoot),
+        },
+        artifact_update_requirements: artifactUpdateRequirements,
+        progress_logging_requirements: {
+            append_cycle: buildRequest !== null || !archiveOnly,
+            verified_field_mandatory: true,
+            latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
+            source_provenance: sourceProvenance("progress", STATE_FAMILY_LIST_COMMANDS.progress),
+        },
+        changelog_boundary: changelogBoundary,
+        git_boundary: {
+            remote_push_allowed: false,
+            commit_allowed_only_with_explicit_user_request: true,
+            tag_or_publication_allowed: false,
+            source_provenance: sourceProvenance("execution_context", preCutoverCommand("prime --context build --format json"), "git_boundary"),
+        },
+        plan_completion_sweep: sweep,
+        plan_lifecycle_state: lifecycle,
+        state_family_caveats: stateCaveats,
+        fallback_commands: fallbackCommands,
+        source_contract: {
+            complete_for_execution_context: complete,
+            caveated,
+            raw_artifact_reads_required: false,
+            raw_artifact_read_policy: "Use this execution_context and included status state first. Run listed routine/query CLI fallback commands " +
+                "for missing or incomplete execution state; raw artifact reads are last-resort diagnostics, not normal Build startup behavior.",
+            required_execution_state: requiredState,
+            missing_required_execution_state: missingRequired,
+            fallback_commands: fallbackCommands,
+            caveats: stateCaveats,
+            owns: [
+                "selected work item",
+                "task details and acceptance criteria",
+                "constraints and safety boundaries",
+                "verification expectations",
+                "artifact update requirements",
+                "progress logging requirements",
+                "changelog boundary",
+                "scope boundary",
+                "read-only plan completion sweep metadata",
+                "truthful completeness metadata",
+                "plan lifecycle state",
+            ],
+            deferred: [],
+        },
+    };
+}

package/dist/cli/capabilityContext/closeout.js

@@ -0,0 +1,233 @@
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import { artifactPath } from "../appContext.js";
+import { asList } from "../stateQuery.js";
+import { capabilityContext } from "./contract.js";
+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", 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."],
+    };
+}
+export function closeoutVersionPolicy(docs) {
+    const conventions = docsConventions(docs);
+    const semverPolicy = conventions.semver_policy && typeof conventions.semver_policy === "object" && !Array.isArray(conventions.semver_policy) ? conventions.semver_policy : {};
+    const versionFiles = asList(conventions.version_files);
+    const registry = conventions.version_files_registry ?? null;
+    const available = Object.keys(semverPolicy).length > 0;
+    return {
+        status: available ? "available" : "unavailable",
+        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, 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", STATE_FAMILY_FALLBACK_COMMANDS.todo),
+        selected_target_version: selectedTargetVersion,
+        open_count: blockers.length,
+        items: blockers,
+        caveats: exists ? [] : ["TODO state is unavailable in CLI state."],
+    };
+}
+export function closeoutBenchmarkEvidence(docs) {
+    const coverage = docs.coverage && typeof docs.coverage === "object" && !Array.isArray(docs.coverage) ? docs.coverage : {};
+    const testsSummary = String(coverage.tests ?? "").trim();
+    if (testsSummary && testsSummary.toLowerCase().includes("benchmark")) {
+        return {
+            status: "available",
+            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",
+            user_local_benchmark_reads_required: false,
+            summary: testsSummary,
+            caveats: [],
+        };
+    }
+    return {
+        status: "unavailable",
+        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",
+        user_local_benchmark_reads_required: false,
+        summary: null,
+        caveats: ["Supported CLI/state summaries do not expose benchmark evidence; do not read user-local benchmark files for normal closeout."],
+    };
+}
+export function localGitTagEvidence(targetVersion) {
+    const tag = targetVersion ? `v${targetVersion}` : null;
+    const source = { source_family: "local_git", command: "git tag --list <target-tag>", remote: false };
+    if (!tag) {
+        return { status: "unavailable", tag: null, source_provenance: source, object_type: null, caveats: ["No selected target version is available for local tag evidence."] };
+    }
+    let stdout;
+    try {
+        stdout = execFileSync("git", ["tag", "--list", tag], { cwd: process.cwd(), encoding: "utf8", timeout: 2000 });
+    }
+    catch (exc) {
+        const e = exc;
+        if (typeof e.status === "number" && e.status !== 0) {
+            return { status: "unavailable", tag, source_provenance: source, object_type: null, caveats: ["Local git tag evidence is unavailable because this project is not a git worktree."] };
+        }
+        return { status: "unavailable", tag, source_provenance: source, object_type: null, caveats: [`Local git tag evidence is unavailable: ${exc.message}`] };
+    }
+    if (!stdout.split(/\r\n|\r|\n/).includes(tag)) {
+        return { status: "absent", tag, source_provenance: source, object_type: null, caveats: [`Local tag ${tag} is not present.`] };
+    }
+    let objectType = null;
+    try {
+        const out = execFileSync("git", ["cat-file", "-t", tag], { cwd: process.cwd(), encoding: "utf8", timeout: 2000 });
+        objectType = out.trim() || null;
+    }
+    catch {
+        objectType = null;
+    }
+    return {
+        status: "available",
+        tag,
+        source_provenance: source,
+        object_type: objectType,
+        caveats: objectType ? [] : [`Local tag ${tag} exists but object type could not be verified.`],
+    };
+}
+export function closeoutReleaseBoundary(changelogBoundary, bundle) {
+    const targetVersion = changelogBoundary.selected_target_version;
+    const localTag = localGitTagEvidence(targetVersion ? String(targetVersion) : null);
+    const metadataRecorded = Boolean(changelogBoundary.selected_target_recorded);
+    const caveats = [...(changelogBoundary.caveats ?? []), ...(localTag.caveats ?? [])];
+    if (!metadataRecorded && localTag.status !== "available") {
+        caveats.push("No local closeout metadata or local tag evidence is recorded for the selected target.");
+    }
+    return {
+        status: changelogBoundary.boundary_present ? "available" : "incomplete",
+        selected_target_version: targetVersion ?? null,
+        boundary: changelogBoundary.boundary ?? null,
+        local_metadata_evidence: {
+            status: metadataRecorded ? "recorded" : "not_recorded",
+            source_provenance: changelogBoundary.source_provenance ?? null,
+            field: "changelog_boundary.selected_target_recorded",
+        },
+        local_tag_evidence: localTag,
+        publication_evidence: {
+            package_publication: "not_recorded_in_cli_state",
+            remote_push: "not_recorded_in_cli_state",
+            remote_checks_performed: false,
+            registry_checks_performed: false,
+            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("status", preCutoverCommand("prime --format json"), "app.status"),
+        },
+        caveats,
+    };
+}
+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 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(decisionHistory);
+    const requiredState = {
+        artifact_mappings: artifactMappings.status === "available",
+        version_policy: versionPolicy.status === "available",
+        todo_blockers: todoBlockers.status === "available",
+        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 === "available",
+    };
+    const missingRequired = Object.entries(requiredState).filter(([, present]) => !present).map(([k]) => k);
+    let stateCaveats = [];
+    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 !== "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([
+        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: "document",
+        artifact_mappings: artifactMappings,
+        version_policy: versionPolicy,
+        todo_blockers: todoBlockers,
+        changelog_boundary: changelogBoundary,
+        release_boundary: releaseBoundary,
+        progress_evidence: progressEvidence,
+        benchmark_evidence: benchmarkEvidence,
+        decision_review_pressure: reviewPressure,
+        state_family_caveats: stateCaveats,
+        fallback_commands: fallbackCommands,
+        source_contract: {
+            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 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.",
+            closeout_state_families: ["docs", "todo", "changelog", "progress", "benchmark_evidence", "decisions"],
+            required_closeout_state: requiredState,
+            missing_required_closeout_state: missingRequired,
+            fallback_commands: fallbackCommands,
+            caveats: stateCaveats,
+            owns: [
+                "artifact mappings",
+                "version policy",
+                "TODO blockers",
+                "changelog or no-release boundary",
+                "local metadata/tag versus publication boundary",
+                "latest progress evidence",
+                "benchmark evidence pointer or unavailable caveat",
+                "protected decision review pressure",
+                "provenance pointers and non-empty evidence flags",
+                "fallback commands",
+                "raw-read policy",
+                "truthful completeness flag",
+            ],
+        },
+    };
+}

package/dist/cli/capabilityContext/contract.js

@@ -0,0 +1,179 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { activeAppModel, discoverSchemasDir } from "../appContext.js";
+import { capabilityStartupCommand } from "../../capabilities/index.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");
+    if (isFile(active))
+        return active;
+    return path.join(path.resolve(discoverSchemasDir(), "..", "..", "..", ".."), "references", "cli", "capability-instruction-contract.yaml");
+}
+export function capabilityInstructionContract() {
+    const p = capabilityInstructionContractPath();
+    if (!isFile(p))
+        return {};
+    try {
+        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`);
+        return {};
+    }
+}
+export function capabilityInstructionTarget(capability) {
+    const module = capabilityInstructionModulePath(capability);
+    const instructions = CAPABILITY_INSTRUCTIONS[capability] ?? null;
+    return {
+        module,
+        exists: instructions !== null && instructions.length > 0,
+        runtime_path: module,
+        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" && !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 {
+        field: "first_invocation_read",
+        value,
+        allowed_values: Object.keys(allowedValues),
+        default_rule: firstRead.default_rule ?? firstRead.default_future_rule ?? null,
+        module_target: capabilityInstructionTarget(capability),
+        startup_command: capabilityStartupCommand(capability),
+        obligation_summary: valueContract.obligation ?? `shell out to ${capabilityStartupCommand(capability)}`,
+        meaning: valueContract.meaning ?? null,
+        runtime_enforcement: true,
+        provenance: {
+            authority_path: "references/cli/capability-instruction-contract.yaml",
+            authority_status: authority.status ?? null,
+            decision: authority.decision ?? null,
+            source_field: "first_invocation_read.allowed_values",
+        },
+    };
+}
+export function planStartupContract() {
+    return {
+        schemaVersion: PLAN_STARTUP_CONTRACT_VERSION,
+        status: "implemented_compact_normal_startup_contract",
+        canonical_surface: capabilityStartupCommand("plan"),
+        bounded: true,
+        instructions_runtime_read_required: false,
+        instructions_authority: {
+            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: PLAN_PLANNING_LEVELS,
+            step_marker_format: "── step N/6: verb",
+            required_steps: PLAN_STEP_VERBS,
+            full_plan_review_required: true,
+            pre_write_self_audit_required: true,
+            task_coherence_rule: PLAN_TASK_COHERENCE_RULE,
+        },
+        cli_first_orientation: {
+            use_startup_state_first: true,
+            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: `\`${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: 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 ⧉ 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 state plan list` for plan state, " +
+                "and `agentera plan` for capability routing guidance only.",
+        },
+        seam_decision: {
+            selected: "prime --context",
+            not_changed: [
+                { 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" },
+            ],
+        },
+    };
+}
+export function capabilityArtifactInventory(capability) {
+    const inventory = { read_needs: [], write_targets: [] };
+    const capabilityDir = path.join(String(activeAppModel().skillRoot), "capabilities", capability);
+    const p = path.join(capabilityDir, "schemas", "artifacts.yaml");
+    if (!isFile(p))
+        return [inventory, `No capability artifact schema found for ${capability}.`];
+    let data;
+    try {
+        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}`];
+    }
+    const artifacts = data.ARTIFACTS;
+    if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts)) {
+        return [inventory, `Capability artifact schema for ${capability} has no ARTIFACTS mapping.`];
+    }
+    const errors = [];
+    for (const [key, entry] of Object.entries(artifacts)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            errors.push(`entry ${key} is not a mapping`);
+            continue;
+        }
+        const e = entry;
+        const artifactId = String(e.artifact ?? "").trim();
+        const localRole = String(e.local_role ?? "").trim();
+        if (!artifactId) {
+            errors.push(`entry ${key} is missing artifact`);
+            continue;
+        }
+        if (localRole === "consumes")
+            appendUnique(inventory.read_needs, artifactId);
+        else if (localRole === "produces")
+            appendUnique(inventory.write_targets, artifactId);
+        else if (localRole === "produces_and_consumes") {
+            appendUnique(inventory.read_needs, artifactId);
+            appendUnique(inventory.write_targets, artifactId);
+        }
+        else
+            errors.push(`entry ${key} has unsupported local_role ${pyRepr(localRole)}`);
+    }
+    const error = errors.length > 0 ? `Capability artifact schema for ${capability} has invalid ARTIFACTS entries: ${errors.join("; ")}.` : null;
+    return [inventory, error];
+}
+export function capabilityContext(capability) {
+    if (!capability)
+        return null;
+    const [inventory, error] = capabilityArtifactInventory(capability);
+    const needs = inventory.read_needs;
+    const context = {
+        capability,
+        first_invocation_read: firstInvocationReadMetadata(capability),
+        availability: startupAvailabilityProjection(needs),
+        schema_error: error,
+    };
+    if (capability === "plan")
+        context.startup_contract = planStartupContract();
+    return context;
+}