agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/dist/cli/commands/schema.js

@@ -1,17 +1,17 @@
 import fs from "node:fs";
 import path from "node:path";
-import { parseYaml } from "../../core/yaml.js";
 import { activeAppModel, discoverSchemasDir, loadSchemas } from "../appContext.js";
 import { emitStructured } from "../structured.js";
 import { appModelPayload, REQUIRED_SPARSE_CONTEXT_FIELDS, ROUTINE_STRUCTURED_FIELDS, PRIME_STRUCTURED_FIELDS, surfaceMissingMessage, } from "../stateQuery.js";
 import { artifactLocationContract } from "./query.js";
 import { stateWriterArtifactContract, stateWriterContract } from "../../state/write/operations.js";
 import { CANONICAL_SHARED_SKILL_PATH } from "../../setup/sharedSkill.js";
-import { loadNativeResourceCleanupContract, nativeResourceCleanupIds, } from "../../runtime/nativeResourceCleanup.js";
 import { loadStateRetrievalAuthority } from "../../state/retrievalAuthority.js";
-import { entityMigrationAuthorityProjection } from "../../state/entityMigrationPreview.js";
+import { entityListFamilies } from "../../state/entityRetrievalHelp.js";
 import { personalGlossaryOutputContract } from "../../registries/glossaryEntryContract.js";
 import { describeArtifactSchemaFields } from "../../registries/artifactSchemaProjection.js";
+import { advertisedValidateFamilyNames } from "./validate.js";
+import { SCHEMA_TOP_LEVEL_COMMANDS } from "../dispatch/projections.js";
 export const TRANSITIONAL_TOP_LEVEL_ALIASES = [
     {
         legacy: "query",
@@ -59,6 +59,19 @@ export const REMOVED_TOP_LEVEL_CORRECTIONS = {
     objective: "state objective",
     experiments: "state experiments",
 };
+function projectedStateRetrieval(retrieval) {
+    const projected = JSON.parse(JSON.stringify(retrieval));
+    const commands = projected.commands;
+    const families = (projected.list_help.families);
+    for (const family of entityListFamilies()) {
+        commands[family.key] = { list: family.syntax, get: family.get };
+        const source = families[family.key];
+        source.example = family.example;
+        if (family.bareRecovery)
+            source.bare_recovery = family.bareRecovery;
+    }
+    return projected;
+}
 const CAPABILITY_NAMES = [
     "status",
     "vision",
@@ -93,9 +106,21 @@ const DOCTOR_SIGNAL_KINDS = [
     "version_mismatch",
     "corrupt_bundle_marker",
 ];
+const DOCTOR_SELF_CHECK_CATEGORIES = [
+    "Agentera CLI self-check status",
+    "installed app and install-root status",
+    "canonical shared-skill diagnosis",
+    "project integration and project-state migration diagnostics",
+    "bounded offline smoke checks when requested",
+];
+const DOCTOR_EXCLUDES = [
+    "project artifact health",
+    "codebase quality audit findings",
+    "capability architecture, test, dependency, or documentation audit output",
+];
 const STATUS_STRUCTURED_FIELDS = PRIME_STRUCTURED_FIELDS;
 const COMMAND_DESCRIPTIONS = {
-    prime: "Composite orientation briefing and capability startup context; bare JSON is at most 12000 UTF-8 bytes and status startup at most 25000.",
+    prime: "Composite orientation briefing and capability startup context; bare JSON is at most 12000 UTF-8 bytes and status startup at most 22500.",
     schema: "Runtime CLI/schema introspection.",
     query: "Deprecated alias for state query. Advanced custom artifact query.",
     lint: "Deprecated alias for check lint. Optional draft prose preview; typed writers validate published bytes.",
@@ -103,7 +128,7 @@ const COMMAND_DESCRIPTIONS = {
     verify: "Deprecated alias for check verify. Run bounded verification families.",
     stats: "Deprecated alias for report. Read or refresh privacy-gated usage analytics.",
     validate: "Deprecated alias for check validate. Validate capabilities and repository contracts.",
-    upgrade: "Preview or apply app and project-state migration, including recognized v2 rewiring, or explicit native Agentera resource cleanup.",
+    upgrade: "Preview or apply one-way app and project-state migration.",
     doctor: "Check Agentera CLI, app, shared-skill, and project-integration status.",
 };
 function availableStructuredFields(command) {
@@ -134,7 +159,6 @@ const COMMAND_FILTERS_ALL = {
         "project",
         "install_root",
         "home",
-        "legacy_cleanup",
         "only",
         "dry_run",
         "yes",
@@ -143,28 +167,9 @@ const COMMAND_FILTERS_ALL = {
     ],
     schema: ["format"],
 };
-function contractPath() {
+function integrationAuthorityPath() {
     const sourceRoot = path.resolve(discoverSchemasDir(), "..", "..", "..", "..");
-    return path.join(sourceRoot, "references", "cli", "agent-ready-state-contract.yaml");
-}
-function loadDecision45Contract() {
-    const p = contractPath();
-    let isFile = false;
-    try {
-        isFile = fs.statSync(p).isFile();
-    }
-    catch {
-        isFile = false;
-    }
-    if (!isFile)
-        return [null, "Decision 45 CLI contract is missing"];
-    try {
-        // cast: parseYaml result of the Decision 45 contract file (YAML IO boundary)
-        return [parseYaml(fs.readFileSync(p, "utf8")), null];
-    }
-    catch (exc) {
-        return [null, `Decision 45 CLI contract could not be read: ${exc.message}`];
-    }
+    return path.join(sourceRoot, "skills", "agentera", "SKILL.md");
 }
 function commandDescription(name, kind, fields = null, outputFormats, filters) {
     let formats = outputFormats ?? ["text", "json", "yaml"];
@@ -245,17 +250,6 @@ function describeCommands() {
     ]), commandDescription("doctor", "self_check"));
     return commands;
 }
-function contractSection(contract, key, gaps) {
-    if (contract && typeof contract === "object" && !Array.isArray(contract) && key in contract) {
-        return contract[key];
-    }
-    gaps.push({
-        scope: key,
-        status: "unknown",
-        message: `Decision 45 contract section '${key}' is unavailable`,
-    });
-    return null;
-}
 function describeArtifactSchemas(schemasDir, schemas, model, artifactLocations) {
     const gaps = [];
     let isDir = false;
@@ -324,13 +318,10 @@ function dirExists(p) {
     }
 }
 export function buildSchemaPayload(command = "schema") {
-    const [contract, contractError] = loadDecision45Contract();
     const appModel = activeAppModel();
     const schemasDir = discoverSchemasDir(appModel);
     const schemas = loadSchemas(schemasDir);
     const gaps = [];
-    if (contractError)
-        gaps.push({ scope: "contract", status: "missing", message: contractError });
     const artifactLocationsPayload = artifactLocationContract(schemasDir, schemas);
     const artifactLocations = {};
     // cast: artifacts payload is built by query.ts over on-disk schemas/registry (IO boundary)
@@ -338,33 +329,41 @@ export function buildSchemaPayload(command = "schema") {
         artifactLocations[String(entry.name)] = entry;
     const [artifactSchemas, schemaGaps] = describeArtifactSchemas(schemasDir, schemas, appModel, artifactLocations);
     gaps.push(...schemaGaps);
-    const nativeResourceCleanup = loadNativeResourceCleanupContract();
     const retrievalAuthority = loadStateRetrievalAuthority();
     const profileGlossary = personalGlossaryOutputContract();
-    const slashAliases = contractSection(contract, "slash_route_aliases", gaps);
-    const doctorContract = contractSection(contract, "doctor", gaps);
-    const structuredOutput = contractSection(contract, "structured_output", gaps);
-    const fieldSelection = contractSection(contract, "field_selection", gaps);
-    const isDict = (v) => v && typeof v === "object" && !Array.isArray(v);
-    const cp = contractPath();
+    const authorityPath = integrationAuthorityPath();
     return {
         schemaVersion: "agentera.schema.v1",
         command,
         status: gaps.length > 0 ? "incomplete" : "ok",
         source: {
-            contract: cp,
-            contract_exists: fileExists(cp),
+            integration_authority: authorityPath,
+            integration_authority_exists: fileExists(authorityPath),
             schemas_dir: schemasDir,
             schemas_dir_exists: dirExists(schemasDir),
             schema_count: artifactSchemas.length,
             app_model: appModelPayload(appModel),
         },
         commands: describeCommands(),
+        command_vocabulary: {
+            scope: "selected_schema_projection",
+            note: "commands is a scoped schema projection; dispatcher_top_level is the complete accepted top-level runtime inventory",
+        },
+        dispatcher_top_level: {
+            authority: "packages/cli/src/cli/dispatch/commands.ts#DISPATCHER_TOP_LEVEL_COMMANDS",
+            commands: [...SCHEMA_TOP_LEVEL_COMMANDS],
+        },
+        validation: {
+            command: "agentera check validate",
+            families: [...advertisedValidateFamilyNames()],
+        },
         state_writer: stateWriterContract(),
-        state_retrieval: { authority: retrievalAuthority.authority, ...retrievalAuthority.retrieval },
-        entity_migration: entityMigrationAuthorityProjection(),
+        state_retrieval: {
+            authority: retrievalAuthority.authority,
+            ...projectedStateRetrieval(retrievalAuthority.retrieval),
+        },
         integration: {
-            authority: "references/cli/agent-ready-state-contract.yaml",
+            authority: "skills/agentera/SKILL.md",
             active_contract: "one shared skill plus the Agentera CLI",
             shared_skill: {
                 path: CANONICAL_SHARED_SKILL_PATH,
@@ -373,26 +372,12 @@ export function buildSchemaPayload(command = "schema") {
             cli: {
                 command: "agentera",
             },
-            supported_routes: {
-                v2_migration: "agentera upgrade --channel development --project PROJECT --dry-run|--yes",
-                native_resource_cleanup: "agentera upgrade --legacy-cleanup RESOURCE_ID --dry-run|--yes",
-                personal_glossary: `${profileGlossary.command} --input <file|-> [--dry-run] --format json`,
-            },
             personal_glossary: {
                 command: profileGlossary.command,
                 request_schema_version: profileGlossary.requestSchemaVersion,
                 output_statuses: profileGlossary.outputStatuses,
                 project_checkout: "not_required",
             },
-            native_resource_cleanup: {
-                contract: nativeResourceCleanup.sourcePath,
-                selection: "native_agentera_resource_only",
-                resource_ids: nativeResourceCleanupIds(nativeResourceCleanup),
-                preview: "strictly_read_only",
-                apply_requires: "explicit_approval",
-                ownership: "matching whole-resource ledger identity and fingerprint",
-                shared_configuration_without_key_ledger: "action_required",
-            },
             historical_import: {
                 source: "claude",
                 import_flag: "--import-source claude",
@@ -404,26 +389,20 @@ export function buildSchemaPayload(command = "schema") {
         },
         routine_state_commands: ROUTINE_STATE_COMMANDS,
         structured_output: {
-            formats: isDict(structuredOutput)
-                ? (structuredOutput.formats ?? ["json", "yaml"])
-                : "unknown",
+            formats: ["json", "yaml"],
             fields_by_command: {
                 routine_state_commands: ROUTINE_STRUCTURED_FIELDS,
                 status: STATUS_STRUCTURED_FIELDS,
             },
         },
         field_selection: {
-            syntax: isDict(fieldSelection)
-                ? (fieldSelection.syntax ?? "--fields FIELD[,FIELD...]")
-                : "unknown",
+            syntax: "--fields FIELD[,FIELD...]",
             retained_context: REQUIRED_SPARSE_CONTEXT_FIELDS,
-            applies_to: isDict(fieldSelection)
-                ? (fieldSelection.applies_to ?? ROUTINE_STATE_COMMANDS)
-                : "unknown",
+            applies_to: ROUTINE_STATE_COMMANDS,
         },
         slash_route_aliases: {
-            status: isDict(slashAliases) ? (slashAliases.status ?? "unknown") : "unknown",
-            aliases: isDict(slashAliases) ? (slashAliases.aliases ?? {}) : {},
+            status: "excluded_from_cli_commands",
+            aliases: {},
             cli_commands_added: true,
             note: "Decision 43 slash-route aliases map to direct capability-name routing guidance commands in Agentera 3.0.",
         },
@@ -431,19 +410,11 @@ export function buildSchemaPayload(command = "schema") {
         artifact_locations: artifactLocationsPayload,
         doctor: {
             command: "doctor",
-            removed_command: isDict(doctorContract)
-                ? (doctorContract.removed_command ?? "unknown")
-                : "unknown",
-            compatibility_alias: isDict(doctorContract)
-                ? (doctorContract.compatibility_alias ?? "unknown")
-                : "unknown",
-            self_check_categories: isDict(doctorContract)
-                ? (doctorContract.owns ?? "unknown")
-                : "unknown",
-            excludes: isDict(doctorContract) ? (doctorContract.excludes ?? "unknown") : "unknown",
-            adjacent_surfaces: isDict(doctorContract)
-                ? (doctorContract.adjacent_surfaces ?? "unknown")
-                : "unknown",
+            removed_command: "bundle-status",
+            compatibility_alias: "forbidden",
+            self_check_categories: DOCTOR_SELF_CHECK_CATEGORIES,
+            excludes: DOCTOR_EXCLUDES,
+            adjacent_surfaces: { codebase_audit: "/agentera audit" },
             signal_kinds: DOCTOR_SIGNAL_KINDS,
             shared_skill_field: "shared_skill",
             integration_mode: "shared_skill_and_cli_only",
@@ -456,4 +427,3 @@ export function cmdSchema(args, io) {
     emitStructured(buildSchemaPayload("schema"), args.format ?? "json", out);
     return 0;
 }
-//# sourceMappingURL=schema.js.map

package/dist/cli/commands/state/decisions.js

@@ -385,4 +385,3 @@ export function queryDecisions(args, _schemas, io) {
         emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=decisions.js.map

package/dist/cli/commands/state/docs.js

@@ -68,4 +68,3 @@ export function queryDocs(args, schemas, io) {
         return error.exitCode;
     }
 }
-//# sourceMappingURL=docs.js.map

package/dist/cli/commands/state/experimentRecords.js

@@ -149,4 +149,3 @@ export function runExperimentRecords(argv, io) {
         }, 1), format, io);
     }
 }
-//# sourceMappingURL=experimentRecords.js.map

package/dist/cli/commands/state/experiments.js

@@ -12,4 +12,3 @@ export function queryExperiments(args, _schemas, io) {
         emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=experiments.js.map

package/dist/cli/commands/state/get.js

@@ -127,4 +127,3 @@ export function runStateGet(artifactId, argv, io, projectRoot = process.cwd()) {
         return emitFailure(failure(error.message, undefined, artifactId), format, io);
     }
 }
-//# sourceMappingURL=get.js.map

package/dist/cli/commands/state/health.js

@@ -12,4 +12,3 @@ export function queryHealth(args, _schemas, io) {
         emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=health.js.map

package/dist/cli/commands/state/index.js

@@ -14,4 +14,3 @@ import { queryExperiments } from "./experiments.js";
 import { queryTodo, normalizeSeverity } from "./todo.js";
 import { queryDecisions, decisionContextEntry, decisionSatisfactionContext, decisionSourceContract, extractDecisionEntries, hydrateDecisionEntries, displayFields, } from "./decisions.js";
 export { queryProgress, queryPlan, queryHealth, queryDocs, queryObjective, queryExperiments, queryTodo, queryDecisions, normalizeSeverity, decisionContextEntry, decisionSatisfactionContext, decisionSourceContract, extractDecisionEntries, hydrateDecisionEntries, displayFields, };
-//# sourceMappingURL=index.js.map

package/dist/cli/commands/state/list.js

@@ -192,4 +192,3 @@ export function runStateList(artifactId, argv, io, projectRoot = process.cwd())
         }, 1), format, io);
     }
 }
-//# sourceMappingURL=list.js.map

package/dist/cli/commands/state/objective.js

@@ -23,4 +23,3 @@ export function queryObjective(args, _schemas, io) {
         return error.exitCode;
     }
 }
-//# sourceMappingURL=objective.js.map

package/dist/cli/commands/state/plan.js

@@ -12,4 +12,3 @@ export function queryPlan(args, _schemas, io) {
         emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=plan.js.map

package/dist/cli/commands/state/planTasks.js

@@ -152,4 +152,3 @@ export function runPlanTasks(argv, io) {
         }, 1), format, io);
     }
 }
-//# sourceMappingURL=planTasks.js.map

package/dist/cli/commands/state/plans.js

@@ -152,4 +152,3 @@ export function runPlans(argv, io) {
         }, 1), format, io);
     }
 }
-//# sourceMappingURL=plans.js.map

package/dist/cli/commands/state/progress.js

@@ -11,4 +11,3 @@ export function queryProgress(args, _schemas, io) {
         emitStructured(response, format, output);
     return 0;
 }
-//# sourceMappingURL=progress.js.map

package/dist/cli/commands/state/shared.js

@@ -12,4 +12,3 @@ export function out(io) {
 export function err(io) {
     return io.err ?? ((t) => process.stderr.write(t));
 }
-//# sourceMappingURL=shared.js.map

package/dist/cli/commands/state/todo.js

@@ -40,4 +40,3 @@ export function queryTodo(args, _schemas, io, openOnly = false) {
         return error.exitCode;
     }
 }
-//# sourceMappingURL=todo.js.map

package/dist/cli/commands/state/write.js

@@ -182,6 +182,16 @@ function parseWrite(artifactRaw, argv) {
             i += 1;
             continue;
         }
+        const bareBoolean = byFlag.get(token);
+        if (bareBoolean?.kind === "boolean") {
+            if ((occurrences.get(token) ?? 0) > 0)
+                invalid({ class: "mutually_exclusive", message: `${token} may only be supplied once` });
+            occurrences.set(token, 1);
+            setNested(values, bareBoolean.field, true);
+            setNested(callerPayload, bareBoolean.field, true);
+            i += 1;
+            continue;
+        }
         const parsed = readFlag(argv, i);
         if (parsed.value === null || parsed.value.startsWith("--"))
             invalid({
@@ -422,4 +432,3 @@ export function runStateWrite(artifactRaw, argv, io) {
 function fsStdin() {
     return process.stdin.isTTY ? Buffer.alloc(0) : fs.readFileSync(0);
 }
-//# sourceMappingURL=write.js.map

package/dist/cli/commands/upgrade.js

@@ -187,4 +187,3 @@ export function cmdUpgrade(args, io = {}, dependencies = {}) {
     return exit;
 }
 import path from "node:path";
-//# sourceMappingURL=upgrade.js.map

package/dist/cli/commands/upgradeVerify.js

@@ -116,4 +116,3 @@ export function renderVerifySummary(result, json) {
     }
     return lines.join("\n") + "\n";
 }
-//# sourceMappingURL=upgradeVerify.js.map

package/dist/cli/commands/validate.js

@@ -3,27 +3,50 @@ import { readdirSync as fsReaddirSync, statSync as fsStatSync } from "node:fs";
 import { resolvePath } from "../../core/paths.js";
 import { resolveSourceRoot } from "../../core/sourceRoot.js";
 import { validateAgentString, validatePathValue } from "../argvalidate.js";
-import { HookCliAdapter } from "../../hooks/validateArtifact/index.js";
+import { ArtifactValidationAdapter } from "../../hooks/validateArtifact/index.js";
 import { validateCapability, validateContractSelf, validateProtocolSelf } from "../../validate/capability.js";
 import { loadYamlMapping } from "../../core/yaml.js";
 import { validateGraph } from "../../validate/crossCapability.js";
 import { validate as validateAppHome } from "../../validate/appHomeContract.js";
 import { selfAuditMain } from "../../validate/selfAudit.js";
 import { vocabularyAuthorityMain } from "../../validate/vocabularyAuthority.js";
+import { activationConjunctionMain } from "../../validate/activationConjunction.js";
+import { isRetainedReferenceSourceCheckout, retainedReferenceAuthorityMain, } from "../../validate/retainedReferenceAuthority.js";
 import { releaseMetadataMain } from "../../release/releaseMetadata.js";
 import { VALIDATE_ARTIFACT_PROTOCOL_IDS, normalizeArtifactProtocolId, } from "../../registries/artifactProtocolIds.js";
 import { emitStructured } from "../structured.js";
 import { validateEntityState } from "../../state/entityStorage.js";
 import { inspectTodoReconciliationDrift } from "../../state/todoDocsEntities.js";
+import { inspectTodoReconciliationState } from "../../state/todoReconciliationInspection.js";
 import { detectStateModeBinding } from "../../state/stateMode.js";
 import { loadEntityCutoverTargetsForMarker } from "../../state/entityCutover.js";
 import { validateRealProjectRoot } from "../../state/projectRoot.js";
 import { readProjectFileSnapshot } from "../../state/safeProjectFile.js";
 import { loadTodoReadinessContract, TodoReadinessContractError, } from "../../registries/todoReadinessContract.js";
+export const VALIDATE_FAMILY_NAMES = [
+    "cross-capability",
+    "app-home-contract",
+    "vocabularyAuthority",
+    "retained-references",
+    "activation-conjunction",
+    "selfAudit",
+    "release-metadata",
+    "capability",
+    "capability-contract",
+    "artifact",
+    "state",
+];
+/** Source-only validation must not appear as a packaged CLI capability. */
+export function advertisedValidateFamilyNames() {
+    return isRetainedReferenceSourceCheckout()
+        ? VALIDATE_FAMILY_NAMES
+        : VALIDATE_FAMILY_NAMES.filter((family) => !["retained-references", "activation-conjunction"].includes(family));
+}
 const VALIDATE_DELEGATED_SCRIPTS = {
     "cross-capability": "validate_cross_capability.py",
     "app-home-contract": "validate_app_home_contract.py",
     vocabularyAuthority: "validate_vocabulary_authority.py",
+    "retained-references": "packages/cli/src/validate/retainedReferenceAuthority.ts",
     selfAudit: "self_audit.py",
     "release-metadata": "validate_release_metadata.py",
 };
@@ -58,6 +81,29 @@ function runVocabularyAuthority() {
     const rc = vocabularyAuthorityMain({ out: (line) => lines.push(line) });
     return { stdout: lines.map((l) => l + "\n").join(""), stderr: "", returncode: rc };
 }
+function runRetainedReferenceAuthority() {
+    const lines = [];
+    const rc = retainedReferenceAuthorityMain({ out: (line) => lines.push(line) });
+    return {
+        stdout: lines.map((line) => line + "\n").join(""),
+        stderr: "",
+        returncode: rc,
+        violations: rc === 0
+            ? []
+            : lines.filter((line) => line.startsWith("- ")).map((line) => line.slice(2)),
+    };
+}
+function unsupportedRetainedReferenceValidation() {
+    const recovery = "Run this source-checkout-only target from the repository root after pnpm -C packages/cli build.";
+    return {
+        stdout: "",
+        stderr: `retained-reference validation is unavailable outside a source checkout. ${recovery}\n`,
+        returncode: 1,
+        violations: ["retained-reference validation is unavailable outside a source checkout"],
+        failureClass: "unsupported_source_checkout",
+        recovery,
+    };
+}
 function runSelfAudit() {
     const lines = [];
     const rc = selfAuditMain({ out: (line) => lines.push(line) });
@@ -65,7 +111,11 @@ function runSelfAudit() {
 }
 function runReleaseMetadata() {
     const lines = [];
-    const rc = releaseMetadataMain({ out: (line) => lines.push(line) });
+    const adapter = process.env.AGENTERA_RELEASE_ADAPTER;
+    const rc = releaseMetadataMain({
+        ...(adapter === "stable" || adapter === "development" ? { adapter } : {}),
+        out: (line) => lines.push(line),
+    });
     return { stdout: lines.map((l) => l + "\n").join(""), stderr: "", returncode: rc };
 }
 function repoRoot() {
@@ -76,12 +126,13 @@ const DELEGATED_RUNNERS = {
     "cross-capability": () => runCrossCapability(),
     "app-home-contract": () => runAppHomeContract(),
     vocabularyAuthority: () => runVocabularyAuthority(),
+    "retained-references": () => runRetainedReferenceAuthority(),
     selfAudit: () => runSelfAudit(),
     "release-metadata": () => runReleaseMetadata(),
 };
 function validationProcessPayload(targetFamily, target, p, result) {
     const lines = pySplitlines(result.stderr).map((l) => l.trim());
-    const violations = lines.filter((l) => l.trim()).map((l) => (l.startsWith("  ") ? l.slice(2) : l));
+    const violations = result.violations ?? lines.filter((l) => l.trim()).map((l) => (l.startsWith("  ") ? l.slice(2) : l));
     const payload = {
         command: "validate",
         status: result.returncode === 0 ? "pass" : "fail",
@@ -94,6 +145,10 @@ function validationProcessPayload(targetFamily, target, p, result) {
             stderr: pySplitlines(result.stderr),
         },
     };
+    if (result.failureClass)
+        payload.failure_class = result.failureClass;
+    if (result.recovery)
+        payload.recovery = result.recovery;
     if (p !== null)
         payload.path = resolvePath(p);
     return payload;
@@ -108,10 +163,11 @@ export function cmdValidate(family, args, io) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const err = io.err ?? ((t) => process.stderr.write(t));
     if (!(family in DELEGATED_RUNNERS)) {
-        throw new Error("unsupported validate target family; valid families: capability, artifact, " +
-            "cross-capability, app-home-contract, vocabularyAuthority, selfAudit, release-metadata, capability-contract.");
+        throw new Error(`unsupported validate target family; valid families: ${VALIDATE_FAMILY_NAMES.join(", ")}.`);
     }
-    const result = DELEGATED_RUNNERS[family](args);
+    const result = family === "retained-references" && !isRetainedReferenceSourceCheckout()
+        ? unsupportedRetainedReferenceValidation()
+        : DELEGATED_RUNNERS[family](args);
     if ((args.format ?? "text") === "json") {
         emitStructured(delegatedValidationPayload(family, result, VALIDATE_DELEGATED_SCRIPTS[family]), "json", out);
     }
@@ -126,6 +182,9 @@ export function cmdValidate(family, args, io) {
 export function isDelegatedValidateFamily(family) {
     return family in DELEGATED_RUNNERS;
 }
+export function cmdValidateActivationConjunction(io) {
+    return activationConjunctionMain({ out: io.out });
+}
 // ── capability + capability-contract families ───────────────────────
 const CAPABILITY_NAMES = [
     "status", "vision", "discuss", "research", "plan", "build",
@@ -356,7 +415,7 @@ export function cmdValidateArtifact(args, io) {
     const artifact = String(args.artifact);
     validateArtifactLabel(artifact);
     const cwd = resolvePath(args.cwd ?? process.cwd());
-    const adapter = new HookCliAdapter();
+    const adapter = new ArtifactValidationAdapter();
     const [rc, payload] = adapter.runExplicit(artifact, args.file ?? null, cwd);
     if ((args.format ?? "text") === "json") {
         const wrapped = {
@@ -375,7 +434,7 @@ export function cmdValidateArtifact(args, io) {
     out(`status=${payload.status} | artifact=${payload.artifact} | ` +
         `file=${payload.file} | docs_mapped_default=${payload.docs_mapped_default} | ` +
         `path_source=${payload.path_source}\n`);
-    // cast: payload.violations come from the artifact-validation hook (subprocess IO boundary)
+    // cast: payload.violations come from the artifact-validation engine IO boundary
     for (const violation of payload.violations)
         err(`${violation}\n`);
     return rc;
@@ -397,6 +456,17 @@ export function cmdValidateState(args, io) {
     }
     return payload.valid ? 0 : 1;
 }
+function todoReconciliationValidationIssue(diagnosis) {
+    const label = diagnosis.state === "inactive" ? "inactive" : diagnosis.state === "unsafe_active" ? "unsafe active" : "invalid lifecycle";
+    return {
+        code: `todo_reconciliation_${diagnosis.state}`,
+        path: "TODO.md",
+        artifact: "todo",
+        message: `TODO reconciliation is ${label}; the project is not operable through the reconciled TODO surface`,
+        recovery: diagnosis.recovery_command,
+        diagnosis: diagnosis,
+    };
+}
 /** The executable whole-state contract shared by the public command and upgrade verification. */
 export function validateStatePayload(projectRootInput) {
     const projectRoot = resolvePath(projectRootInput);
@@ -426,12 +496,36 @@ export function validateStatePayload(projectRootInput) {
         }
     }
     catch (error) {
+        const message = error.message;
         if (issues.length < 100)
-            issues.push({ code: "invalid_state_marker_or_manifest", path: ".agentera/state-mode.yaml", message: error.message, recovery: "Restore the durable marker and immutable migration evidence, then rerun this read-only check." });
+            issues.push({
+                code: message.includes("state mode marker") ? "invalid_lifecycle_state" : "invalid_state_marker_or_manifest",
+                path: ".agentera/state-mode.yaml",
+                message: message.includes("state mode marker") ? "entity-state lifecycle marker is invalid" : message,
+                recovery: "Restore the durable marker and immutable migration evidence, then rerun this read-only check.",
+            });
         else
             additionalOmittedIssues += 1;
     }
     if (entityMode) {
+        let reconciliation = null;
+        try {
+            reconciliation = inspectTodoReconciliationState(projectRoot);
+            if (reconciliation?.status === "action_required") {
+                if (issues.length < 100)
+                    issues.push(todoReconciliationValidationIssue(reconciliation));
+                else
+                    additionalOmittedIssues += 1;
+            }
+        }
+        catch (error) {
+            if (issues.length < 100)
+                issues.push({ code: "invalid_todo_reconciliation", path: "TODO.md", artifact: "todo", message: "TODO reconciliation could not be inspected without state changes", recovery: "Restore valid bounded TODO reconciliation state, then rerun this read-only check." });
+            else
+                additionalOmittedIssues += 1;
+        }
+        if (reconciliation?.state === "invalid_lifecycle")
+            return finishStateValidation(projectRoot, result, issues, additionalOmittedIssues);
         try {
             const reconciliation = inspectTodoReconciliationDrift(projectRoot);
             const driftItems = Array.isArray(reconciliation.items) ? reconciliation.items.filter((item) => item !== null && typeof item === "object" && !Array.isArray(item)) : [];
@@ -463,6 +557,9 @@ export function validateStatePayload(projectRootInput) {
                 additionalOmittedIssues += 1;
         }
     }
+    return finishStateValidation(projectRoot, result, issues, additionalOmittedIssues);
+}
+function finishStateValidation(projectRoot, result, issues, additionalOmittedIssues) {
     const omittedIssueCount = result.omittedIssueCount + additionalOmittedIssues;
     const valid = result.valid && issues.length === 0 && omittedIssueCount === 0;
     const payload = {
@@ -479,4 +576,3 @@ export function validateStatePayload(projectRootInput) {
     };
     return payload;
 }
-//# sourceMappingURL=validate.js.map

package/dist/cli/commands/verify.js

@@ -223,4 +223,3 @@ export function cmdVerify(args, io = {}) {
     }
     return result.returncode;
 }
-//# sourceMappingURL=verify.js.map

package/dist/cli/contracts/bundleStatus.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=bundleStatus.js.map