agentera 3.0.0-dev.4 → 3.0.0-dev.46

package/dist/cli/commands/validate.js

@@ -1,20 +1,54 @@
 import path from "node:path";
-import { readdirSync as fsReaddirSync, readFileSync as fsReadFileSync, statSync as fsStatSync } from "node:fs";
+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.js";
+import { ArtifactValidationAdapter } from "../../hooks/validateArtifact/index.js";
 import { validateCapability, validateContractSelf, validateProtocolSelf } from "../../validate/capability.js";
 import { loadYamlMapping } from "../../core/yaml.js";
-import { parseToml as parseTomlValidate } from "../../core/toml.js";
 import { validateGraph } from "../../validate/crossCapability.js";
-import { lifecycleMain } from "../../validate/lifecycleAdapters.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",
-    "lifecycle-adapters": "validate_lifecycle_adapters.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",
 };
 function pySplitlines(s) {
     if (!s)
@@ -31,11 +65,6 @@ function runCrossCapability() {
     }
     return { stdout: "cross-capability artifact graph ok\n", stderr: "", returncode: 0 };
 }
-function runLifecycleAdapters() {
-    const lines = [];
-    const rc = lifecycleMain({ out: (line) => lines.push(line) });
-    return { stdout: lines.map((l) => l + "\n").join(""), stderr: "", returncode: rc };
-}
 function runAppHomeContract() {
     const errors = validateAppHome(resolvePath(repoRoot()));
     if (errors.length > 0) {
@@ -47,18 +76,63 @@ function runAppHomeContract() {
     }
     return { stdout: "OK: app-home contract terminology is release-ready\n", stderr: "", returncode: 0 };
 }
+function runVocabularyAuthority() {
+    const lines = [];
+    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) });
+    return { stdout: lines.map((l) => l + "\n").join(""), stderr: "", returncode: rc };
+}
+function runReleaseMetadata() {
+    const lines = [];
+    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() {
     // appHomeContract.validate resolves its own default root; pass the source root.
     return process.cwd();
 }
 const DELEGATED_RUNNERS = {
-    "cross-capability": runCrossCapability,
-    "lifecycle-adapters": runLifecycleAdapters,
-    "app-home-contract": runAppHomeContract,
+    "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",
@@ -71,12 +145,17 @@ 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;
 }
 function delegatedValidationPayload(targetFamily, result, engineCommand) {
     const payload = validationProcessPayload(targetFamily, targetFamily, null, result);
+    // cast: payload.engine carries captured subprocess stdout/stderr (IO boundary)
     payload.engine = { ...payload.engine, command: engineCommand };
     return payload;
 }
@@ -84,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, descriptors, " +
-            "cross-capability, lifecycle-adapters, app-home-contract, capability-contract.");
+        throw new Error(`unsupported validate target family; valid families: ${VALIDATE_FAMILY_NAMES.join(", ")}.`);
     }
-    const result = DELEGATED_RUNNERS[family]();
+    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);
     }
@@ -102,13 +182,17 @@ 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 = [
-    "hej", "visionera", "resonera", "inspirera", "planera", "realisera",
-    "optimera", "inspektera", "dokumentera", "profilera", "visualisera", "orkestrera",
+    "status", "vision", "discuss", "research", "plan", "build",
+    "optimize", "audit", "document", "profile", "design", "orchestrate",
 ];
 const CONTRACT_PATH = "skills/agentera/capability_schema_contract.yaml";
 const PROTOCOL_PATH = "skills/agentera/protocol.yaml";
+const TODO_READINESS_PATH = "skills/agentera/schemas/artifacts/todo.yaml";
 function pyRepr(value) {
     return value.includes("'") && !value.includes('"') ? `"${value}"` : `'${value}'`;
 }
@@ -122,7 +206,7 @@ function validateCapabilityTarget(target) {
         const valid = CAPABILITY_NAMES.join(", ");
         throw new Error(`unsupported capability target ${pyRepr(target)}; valid capability names: ${valid}. ` +
             "Syntax: agentera validate capability <capability-or-path> [--format text|json]. " +
-            "Example: agentera validate capability hej");
+            "Example: agentera validate capability status");
     }
     validatePathValue(target, "capability path");
     return target;
@@ -191,6 +275,7 @@ export function cmdValidateCapability(target, args, io) {
                 target,
                 path: resolvePath(capDir),
                 checks,
+                // cast: c.violations are captured validation-engine lines (subprocess IO boundary)
                 violations: checks.flatMap((c) => c.violations),
                 summary: {
                     passed: checks.filter((c) => c.status === "pass").length,
@@ -260,12 +345,33 @@ function protocolSelfResult() {
     }
     return { stdout, stderr, returncode };
 }
+function todoReadinessResult() {
+    let stdout = `Validating TODO readiness: ${TODO_READINESS_PATH}\n`;
+    let errors = [];
+    try {
+        loadTodoReadinessContract(path.join(resolveSourceRoot(), TODO_READINESS_PATH), path.join(resolveSourceRoot(), PROTOCOL_PATH), path.join(resolveSourceRoot(), CONTRACT_PATH));
+    }
+    catch (exc) {
+        errors = exc instanceof TodoReadinessContractError ? exc.errors : [exc.message];
+    }
+    let stderr = "";
+    let returncode = 0;
+    if (errors.length > 0) {
+        stderr = "FAILED:\n" + errors.map((error) => `  ${error}\n`).join("");
+        returncode = 1;
+    }
+    else {
+        stdout += "PASS: TODO readiness contract is internally consistent\n";
+    }
+    return { stdout, stderr, returncode };
+}
 export function cmdValidateCapabilityContract(args, io) {
     const out = io.out ?? ((t) => process.stdout.write(t));
     const err = io.err ?? ((t) => process.stderr.write(t));
     const results = [
         ["capability-contract-self", contractSelfResult()],
         ["capability-protocol", protocolSelfResult()],
+        ["todo-readiness", todoReadinessResult()],
     ];
     if ((args.format ?? "text") === "json") {
         const checks = results.map(([name, result]) => delegatedValidationPayload(name, result, "validate_capability.py"));
@@ -273,8 +379,9 @@ export function cmdValidateCapabilityContract(args, io) {
             command: "validate",
             status: results.every(([, r]) => r.returncode === 0) ? "pass" : "fail",
             target_family: "capability-contract",
-            target: "capability-schema-contract-and-protocol",
+            target: "capability-schema-contract-protocol-and-todo-readiness",
             checks,
+            // cast: c.violations are captured validation-engine lines (subprocess IO boundary)
             violations: checks.flatMap((c) => c.violations),
             summary: {
                 passed: results.filter(([, r]) => r.returncode === 0).length,
@@ -292,199 +399,14 @@ export function cmdValidateCapabilityContract(args, io) {
     }
     return results.every(([, r]) => r.returncode === 0) ? 0 : 1;
 }
-// ── descriptors family ──────────────────────────────────────────────
-function pySplitlinesText(s) {
-    return s.split(/\r\n|\r|\n/);
-}
-function descriptorValidationPayload() {
-    const sourceRoot = resolveSourceRoot();
-    const codexDir = path.join(sourceRoot, "skills", "agentera", "agents");
-    const opencodeDir = path.join(sourceRoot, ".opencode", "agents");
-    const classificationPath = path.join(sourceRoot, "references", "cli", "capability-tool-classification.yaml");
-    const checks = [];
-    const violations = [];
-    let capPermissions = {};
-    try {
-        const classificationData = loadYamlMapping(fsReadFileSync(classificationPath, "utf8"));
-        capPermissions = {};
-        for (const categoryData of Object.values(classificationData.classification)) {
-            for (const [capability, capData] of Object.entries(categoryData.capabilities)) {
-                capPermissions[capability] = capData.permission;
-            }
-        }
-    }
-    catch (exc) {
-        violations.push(`classification authority: failed to load classification: ${exc.message}`);
-        capPermissions = {};
-    }
-    for (const name of CAPABILITY_NAMES) {
-        const codexPath = path.join(codexDir, `${name}.toml`);
-        let check = { runtime: "codex", capability: name, path: codexPath, status: "pass" };
-        let text;
-        let parsed;
-        try {
-            text = fsReadFileSync(codexPath, "utf8");
-            parsed = parseTomlValidate(text);
-        }
-        catch (exc) {
-            check = { ...check, status: "fail", message: exc.message };
-            violations.push(`codex ${name}: ${exc.message}`);
-            checks.push(check);
-            continue;
-        }
-        const expectedRef = `capabilities/${name}/instructions.md`;
-        if (parsed.name !== name) {
-            check = { ...check, status: "fail", message: "name field does not match capability" };
-            violations.push(`codex ${name}: name field must be ${name}`);
-        }
-        else if (typeof parsed.description !== "string" || !parsed.description.trim()) {
-            check = { ...check, status: "fail", message: "description is required" };
-            violations.push(`codex ${name}: description is required`);
-        }
-        else if (typeof parsed.developer_instructions !== "string" || !parsed.developer_instructions.includes(expectedRef)) {
-            check = { ...check, status: "fail", message: "developer_instructions must reference capability instructions" };
-            violations.push(`codex ${name}: developer_instructions must reference ${expectedRef}`);
-        }
-        else if (!pySplitlinesText(text).slice(0, 5).includes("# agentera_managed: true")) {
-            check = { ...check, status: "fail", message: "managed marker is required" };
-            violations.push(`codex ${name}: managed marker is required`);
-        }
-        else {
-            const devInst = parsed.developer_instructions;
-            const expectedPermission = (capPermissions[name] ?? {});
-            if (expectedPermission && Object.keys(expectedPermission).length > 0) {
-                let expectedGuidance;
-                if (expectedPermission.write === "allow" && expectedPermission.bash === "allow") {
-                    expectedGuidance = "You have full file write, file edit, and shell execution tools available";
-                }
-                else if (expectedPermission.write === "allow" && expectedPermission.bash === "deny") {
-                    expectedGuidance =
-                        "You have file write and file edit tools available to create or update files, but shell execution is disabled";
-                }
-                else {
-                    expectedGuidance = "You are a read-only agent \u2014 do not write files or execute shell commands";
-                }
-                if (!devInst.includes(expectedGuidance)) {
-                    check = { ...check, status: "fail", message: `developer_instructions must contain guidance '${expectedGuidance}'` };
-                    violations.push(`codex ${name}: developer_instructions must contain guidance '${expectedGuidance}'`);
-                }
-            }
-        }
-        checks.push(check);
-        const opencodePath = path.join(opencodeDir, `${name}.md`);
-        let ocheck = { runtime: "opencode", capability: name, path: opencodePath, status: "pass" };
-        let otext;
-        try {
-            otext = fsReadFileSync(opencodePath, "utf8");
-        }
-        catch (exc) {
-            ocheck = { ...ocheck, status: "fail", message: exc.message };
-            violations.push(`opencode ${name}: ${exc.message}`);
-            checks.push(ocheck);
-            continue;
-        }
-        let frontmatter = {};
-        try {
-            const lines = pySplitlinesText(otext);
-            if (lines.length > 0 && lines[0] === "---") {
-                const closing = lines.indexOf("---", 1);
-                if (closing !== -1) {
-                    const frontmatterText = lines.slice(1, closing).join("\n");
-                    frontmatter = loadYamlMapping(frontmatterText);
-                }
-            }
-        }
-        catch {
-            frontmatter = {};
-        }
-        const expectedRefO = `capabilities/${name}/instructions.md`;
-        const expectedPermission = (capPermissions[name] ?? {});
-        const actualPermission = frontmatter.permission;
-        if ("name" in frontmatter) {
-            ocheck = { ...ocheck, status: "fail", message: "name frontmatter must be omitted" };
-            violations.push(`opencode ${name}: name frontmatter must be omitted`);
-        }
-        else if (frontmatter.agentera_managed === "true") {
-            ocheck = { ...ocheck, status: "fail", message: "agentera_managed frontmatter must be omitted" };
-            violations.push(`opencode ${name}: agentera_managed frontmatter must be omitted`);
-        }
-        else if (frontmatter.mode !== "subagent") {
-            ocheck = { ...ocheck, status: "fail", message: "mode: subagent frontmatter is required" };
-            violations.push(`opencode ${name}: mode: subagent frontmatter is required`);
-        }
-        else if (!frontmatter.description) {
-            ocheck = { ...ocheck, status: "fail", message: "description is required" };
-            violations.push(`opencode ${name}: description is required`);
-        }
-        else if (!actualPermission || typeof actualPermission !== "object" || Array.isArray(actualPermission)) {
-            ocheck = { ...ocheck, status: "fail", message: "permission frontmatter is required and must be an object" };
-            violations.push(`opencode ${name}: permission frontmatter is required and must be an object`);
-        }
-        else if (actualPermission.write !== expectedPermission.write ||
-            actualPermission.bash !== expectedPermission.bash) {
-            ocheck = { ...ocheck, status: "fail", message: "permission frontmatter does not match classification" };
-            violations.push(`opencode ${name}: permission frontmatter must be write: ${expectedPermission.write}, bash: ${expectedPermission.bash}`);
-        }
-        else if (!otext.includes("<!-- agentera: managed -->")) {
-            ocheck = { ...ocheck, status: "fail", message: "managed body marker is required" };
-            violations.push(`opencode ${name}: managed body marker is required`);
-        }
-        else if (!otext.includes(expectedRefO)) {
-            ocheck = { ...ocheck, status: "fail", message: "descriptor must reference capability instructions" };
-            violations.push(`opencode ${name}: descriptor must reference ${expectedRefO}`);
-        }
-        else if (otext.includes("Dispatch only through the runtime-native") || otext.includes(`\`@${name}\``)) {
-            ocheck = { ...ocheck, status: "fail", message: "descriptor must not self-dispatch from a subagent" };
-            violations.push(`opencode ${name}: descriptor must execute directly without self-dispatch`);
-        }
-        checks.push(ocheck);
-    }
-    return {
-        command: "validate",
-        status: violations.length > 0 ? "fail" : "pass",
-        target_family: "descriptors",
-        target: "agent-descriptors",
-        checks,
-        violations,
-        summary: {
-            passed: checks.filter((c) => c.status === "pass").length,
-            failed: checks.filter((c) => c.status === "fail").length,
-        },
-    };
-}
-export function cmdValidateDescriptors(args, io) {
-    const out = io.out ?? ((t) => process.stdout.write(t));
-    const err = io.err ?? ((t) => process.stderr.write(t));
-    const payload = descriptorValidationPayload();
-    if ((args.format ?? "text") === "json") {
-        emitStructured(payload, "json", out);
-    }
-    else {
-        out(`descriptor validation ${payload.status}: ${payload.summary.passed} passed, ${payload.summary.failed} failed\n`);
-        for (const violation of payload.violations)
-            err(`- ${violation}\n`);
-    }
-    return payload.status === "pass" ? 0 : 1;
-}
 // ── artifact family ─────────────────────────────────────────────────
-const VALIDATE_ARTIFACT_LABELS = [
-    "CHANGELOG.md",
-    "DECISIONS.md",
-    "DESIGN.md",
-    "DOCS.md",
-    "HEALTH.md",
-    "PLAN.md",
-    "PROGRESS.md",
-    "TODO.md",
-    "VISION.md",
-];
 function validateArtifactLabel(artifact) {
     validateAgentString(artifact, "artifact");
-    if (!VALIDATE_ARTIFACT_LABELS.includes(artifact)) {
-        const valid = VALIDATE_ARTIFACT_LABELS.join(", ");
-        throw new Error(`unsupported artifact ${pyRepr(artifact)}; valid artifacts: ${valid}. ` +
-            "Syntax: agentera validate artifact --artifact <ARTIFACT> [--file <PATH>] [--format text|json]. " +
-            "Example: agentera validate artifact --artifact PLAN.md --file .agentera/plan.yaml --format json");
+    if (normalizeArtifactProtocolId(artifact) === null) {
+        const valid = VALIDATE_ARTIFACT_PROTOCOL_IDS.join(", ");
+        throw new Error(`unsupported artifact ${pyRepr(artifact)}; valid artifact_id values: ${valid}. ` +
+            "Syntax: agentera check validate artifact --artifact <ARTIFACT_ID> [--file <PATH>] [--format text|json]. " +
+            "Example: agentera check validate artifact --artifact plan --file .agentera/plan.yaml --format json");
     }
 }
 export function cmdValidateArtifact(args, io) {
@@ -493,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 = {
@@ -512,8 +434,145 @@ 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 engine IO boundary
     for (const violation of payload.violations)
         err(`${violation}\n`);
     return rc;
 }
-//# sourceMappingURL=validate.js.map
+export function cmdValidateState(args, io) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    const err = io.err ?? ((text) => process.stderr.write(text));
+    const projectRoot = resolvePath(args.cwd ?? process.cwd());
+    const payload = validateStatePayload(projectRoot);
+    const issues = payload.issues;
+    if ((args.format ?? "text") === "json")
+        emitStructured(payload, "json", out);
+    else {
+        out(`status=${payload.status} | entities=${payload.entity_count} | issues=${payload.issue_count} | project_root=${projectRoot}\n`);
+        for (const issue of issues)
+            err(`${issue.code}: ${issue.message}\nrecovery: ${issue.recovery}\n`);
+        if (payload.omitted_issue_count > 0)
+            err(`omitted ${payload.omitted_issue_count} additional issues; repair listed issues and rerun agentera check validate state --cwd ${JSON.stringify(projectRoot)}\n`);
+    }
+    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);
+    const result = validateEntityState(projectRoot);
+    const issues = [...result.issues];
+    let additionalOmittedIssues = 0;
+    let entityMode = false;
+    try {
+        const binding = detectStateModeBinding(projectRoot);
+        if (binding.mode === "entities") {
+            entityMode = true;
+            binding.publicationContext.close();
+            const markerSnapshot = readProjectFileSnapshot(validateRealProjectRoot(projectRoot), ".agentera/state-mode.yaml");
+            if (markerSnapshot.kind !== "file")
+                throw new Error("entity-mode marker became unavailable during maintenance validation");
+            const marker = loadYamlMapping(markerSnapshot.bytes.toString("utf8"));
+            if (typeof marker.migration_id === "string" || marker.cutover === "one_way_git") {
+                const targets = loadEntityCutoverTargetsForMarker(projectRoot, markerSnapshot.bytes);
+                const byPath = new Map(result.entities.map((entity) => [entity.relativePath, entity]));
+                for (const target of targets) {
+                    const actual = byPath.get(target.path);
+                    if (!actual || actual.classification !== "valid" || (target.id && actual.id !== target.id) || (target.artifact && actual.artifact !== target.artifact)) {
+                        issues.push({ code: "missing_migrated_entity", path: target.path, id: target.id ?? null, artifact: target.artifact ?? null, message: `cutover target '${target.path}' is missing or no longer has its declared identity`, recovery: "Restore a valid canonical entity at the manifest-declared path; no state was changed." });
+                    }
+                }
+            }
+        }
+    }
+    catch (error) {
+        const message = error.message;
+        if (issues.length < 100)
+            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)) : [];
+            const reconciliationOmitted = Number(reconciliation.omitted_count ?? 0);
+            const available = Math.max(0, 100 - issues.length);
+            for (const item of driftItems.slice(0, available)) {
+                const id = String(item.id ?? "unknown");
+                const state = String(item.state ?? "drift");
+                const fields = [...new Set([
+                        ...(Array.isArray(item.markdown_changed_fields) ? item.markdown_changed_fields : []),
+                        ...(Array.isArray(item.entity_changed_fields) ? item.entity_changed_fields : []),
+                        ...(Array.isArray(item.conflicting_fields) ? item.conflicting_fields : []),
+                    ].filter((field) => typeof field === "string"))].sort();
+                issues.push({
+                    code: "todo_reconciliation_drift",
+                    path: "TODO.md",
+                    id,
+                    artifact: "todo",
+                    message: `managed TODO '${id}' has ${state} reconciliation drift${fields.length ? ` in ${fields.join(", ")}` : ""}`,
+                    recovery: "Review the reported authority and run the intended typed TODO mutation once; the writer reconciles one-sided changes atomically and rejects conflicts before effects.",
+                });
+            }
+            additionalOmittedIssues += Math.max(0, driftItems.length - available) + (Number.isSafeInteger(reconciliationOmitted) && reconciliationOmitted > 0 ? reconciliationOmitted : 0);
+        }
+        catch (error) {
+            if (issues.length < 100)
+                issues.push({ code: "invalid_todo_reconciliation", path: "TODO.md", artifact: "todo", message: error.message, recovery: "Restore valid bounded managed TODO Markdown, activation metadata, and public baselines, then rerun this read-only check." });
+            else
+                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 = {
+        command: "check validate state",
+        target_family: "state",
+        status: valid ? "pass" : "fail",
+        valid,
+        project_root: projectRoot,
+        entity_count: result.entityCount,
+        issue_count: issues.length + omittedIssueCount,
+        omitted_issue_count: omittedIssueCount,
+        valid_artifact_values: result.validArtifactValues,
+        issues: issues,
+    };
+    return payload;
+}