agentera 3.0.0-dev.2 → 3.0.0-dev.20

package/dist/cli/capabilityContext/build.js

@@ -0,0 +1,190 @@
+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 { planLifecycleState } from "../planLifecycleState.js";
+export function buildExecutionContext(capability, schemas, plan, progress, health, todoItems, docs, profile, bundle) {
+    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 = selected && typeof selected === "object" ? asList(selected.acceptance) : [];
+    const progressVerification = progressVerificationSummary(progress);
+    const changelogBoundary = closeoutChangelogBoundary(schemas, 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 (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 (capabilityContract.missing_state_families ?? [])) {
+        stateCaveats.push(`${family} state is not included in prime --context startup context.`);
+    }
+    fallbackCommands.push(...(capabilityContract.cli_fallback ?? []));
+    if (!plan.exists) {
+        stateCaveats.push("plan state is unavailable; execution context cannot select plan-driven work.");
+        fallbackCommands.push("agentera state plan --format json");
+    }
+    if (lifecycle.status === "degraded") {
+        stateCaveats.push(...(lifecycle.caveats ?? []));
+        fallbackCommands.push("agentera state plan --format json");
+    }
+    if (mode === "blocked_or_dependency_unready") {
+        stateCaveats.push("No dependency-ready pending plan task is available in CLI plan state.");
+        fallbackCommands.push("agentera state plan --format json");
+    }
+    if (mode === "plan_driven" && acceptance.length === 0) {
+        stateCaveats.push("Selected Build task has no acceptance criteria in CLI plan state.");
+        fallbackCommands.push("agentera state plan --format json");
+    }
+    if (!progress.exists) {
+        stateCaveats.push("progress state is unavailable; progress logging context is incomplete.");
+        fallbackCommands.push("agentera state progress --format json");
+    }
+    if (!health.exists) {
+        stateCaveats.push("health state is unavailable or incomplete.");
+        fallbackCommands.push("agentera state health --format json");
+    }
+    if (!docs.exists) {
+        stateCaveats.push("docs mapping state is unavailable or incomplete.");
+        fallbackCommands.push("agentera state docs --format json");
+    }
+    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("agentera state todo --format json");
+    }
+    if (changelogBoundary.status !== "available") {
+        stateCaveats.push(...(changelogBoundary.caveats ?? []));
+        fallbackCommands.push("agentera state query changelog --format json");
+    }
+    if (profile.status !== "loaded") {
+        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 = buildScopeBoundary(plan, selected);
+    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.");
+    }
+    fallbackCommands = uniqueList(fallbackCommands);
+    stateCaveats = uniqueList(stateCaveats);
+    const requiredState = {
+        work_selection: mode === "plan_driven" || mode === "completed_plan_sweep",
+        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,
+    };
+    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") && missingRequired.length === 0;
+    return {
+        capability: "build",
+        mode,
+        work_selection: {
+            status: target.status,
+            selection_reason: target.selection_reason,
+            task: selected && typeof selected === "object" ? taskRef(selected) : null,
+            source_provenance: target.source_provenance,
+            caveats: target.caveats ?? [],
+        },
+        plan_task: selected && typeof selected === "object" ? orchestrationTaskSummary(selected) : null,
+        acceptance_criteria: {
+            status: acceptance.length > 0 ? "available" : "incomplete",
+            items: acceptance,
+            count: acceptance.length,
+            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.acceptance"),
+        },
+        constraints: {
+            plan_constraints_present: hasRecordedValue(planContextField(plan, "constraints")),
+            plan_constraints_summary: "Plan constraints are represented here as structured safety and fallback policy; " +
+                "run the plan CLI fallback only if full wording is needed.",
+            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: sourceProvenance("plan", "agentera plan --format json", "summary.constraints"),
+        },
+        scope_boundary: scopeBoundary,
+        verification_expectations: {
+            latest_progress_verification: progressVerification,
+            expected_commands: ["focused pytest targets", "Build capability validation", "self-validation", "agentera gate", "compaction check", "git diff --check"],
+            source_provenance: sourceProvenance("plan", "agentera plan --format json", "entries.acceptance"),
+        },
+        artifact_update_requirements: buildArtifactUpdateRequirements(plan, docs),
+        progress_logging_requirements: {
+            append_cycle: !archiveOnly,
+            verified_field_mandatory: true,
+            latest_progress_verification_pointer: progressVerification.latest_progress_verification_pointer ?? null,
+            source_provenance: sourceProvenance("progress", "agentera progress --format json"),
+        },
+        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", "agentera 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.",
+            included_state_families: capabilityContract.included_state_families ?? [],
+            missing_state_families: capabilityContract.missing_state_families ?? [],
+            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: [],
+        },
+    };
+}
+//# sourceMappingURL=build.js.map

package/dist/cli/capabilityContext/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/cli/capabilityContext/build.ts"],"names":[],"mappings":"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"}

package/dist/cli/capabilityContext/closeout.js

@@ -0,0 +1,230 @@
+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";
+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"),
+        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", "agentera docs --format json", "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) {
+    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", "agentera todo --format json"),
+        open_count: todoItems.length,
+        items: todoItems,
+        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", "agentera docs --format json", "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", "agentera docs --format json", "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", "agentera 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", "agentera prime --format json", "app.status"),
+        },
+        caveats,
+    };
+}
+export function documentCloseoutContext(capability, schemas, plan, progress, todoItems, docs, profile, bundle) {
+    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 progressEvidence = progressVerificationSummary(progress);
+    const benchmarkEvidence = closeoutBenchmarkEvidence(docs);
+    const releaseBoundary = closeoutReleaseBoundary(changelogBoundary, bundle);
+    const reviewPressure = decisionReviewPressure(schemas);
+    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 !== "review_required",
+    };
+    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 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")
+        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 state todo --format json",
+        "agentera state docs --format json",
+        "agentera state progress --format json",
+        "agentera state query changelog --format json",
+        "agentera state query --list-artifacts --format json",
+        ...(capabilityContract.cli_fallback ?? []),
+    ]);
+    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.",
+            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,
+            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",
+            ],
+        },
+    };
+}
+//# sourceMappingURL=closeout.js.map

package/dist/cli/capabilityContext/closeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"closeout.js","sourceRoot":"","sources":["../../../src/cli/capabilityContext/closeout.ts"],"names":[],"mappings":"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"}

package/dist/cli/capabilityContext/contract.js

@@ -0,0 +1,190 @@
+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, STARTUP_ENVELOPE_STATE_FAMILIES, STATE_FAMILY_FALLBACK_COMMANDS, } from "./types.js";
+import { CAPABILITY_INSTRUCTIONS, capabilityInstructionModulePath } from "../../capabilities/index.js";
+import { isFile, pyRepr, appendUnique } from "./shared.js";
+import { stateWriterContract } from "../../state/write/operations.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: "agentera prime --context plan --format json",
+        bounded: true,
+        instructions_runtime_read_required: false,
+        instructions_authority: {
+            normal_startup: "Use this compact context for normal Plan execution startup; " +
+                "shell out to `agentera prime --context plan --format json` 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: "agentera plan --format json",
+            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 " +
+                "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: "agentera docs/query artifact mapping before writes or closeout",
+        },
+        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 plan` 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 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_id ?? "").trim();
+        const localRole = String(e.local_role ?? "").trim();
+        if (!artifactId) {
+            errors.push(`entry ${key} is missing artifact_id`);
+            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 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,
+        write_contract: stateWriterContract(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.",
+        schema_error: error,
+    };
+    if (capability === "plan")
+        context.startup_contract = planStartupContract();
+    return context;
+}
+//# sourceMappingURL=contract.js.map