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

package/dist/validate/selfAudit.js

@@ -2,27 +2,7 @@
  * Self-audit checks for artifact writing conventions. Faithful TS port of
  * `scripts/self_audit.py`. Advisory only — report but do not block writes.
  */
-const FULL_FILE_BUDGETS = {
-    "PROGRESS.md": 3000,
-    "EXPERIMENTS.md": 2500,
-    "HEALTH.md": 2000,
-    "DECISIONS.md": 5000,
-    "TODO.md": 5000,
-    "CHANGELOG.md": 5000,
-    "PLAN.md": 2500,
-    "VISION.md": 1500,
-    "DESIGN.md": 2000,
-    "DOCS.md": 2000,
-};
-const PER_ENTRY_BUDGETS = {
-    "PROGRESS.md": 500,
-    "EXPERIMENTS.md": 300,
-    "HEALTH.md": 150,
-    "DECISIONS.md": 200,
-    "TODO.md": 100,
-    "CHANGELOG.md": 300,
-    "PLAN.md": 100,
-};
+import { inspectArtifactVerbosityBudget, } from "../registries/verbosityBudgetContract.js";
 const FILE_PATH_RE = /\b(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z]{1,10}\b/;
 const REPO_PATH_RE = /\b(?:internal|src|lib|pkg|cmd|app|test|tests|doc|docs|script|scripts|skill|skills|hook|hooks|fixture|fixtures|reference|references)(?:\/[A-Za-z0-9_.-]+)+\b/;
 const LINE_NUMBER_RE = /:\d{2,}\b/;
@@ -45,33 +25,56 @@ const BANNED_PATTERNS = [
     ["filler introductions", /After\s+careful\s+consideration\b/i],
     ["summary preambles", /\bIn\s+summary\b/i],
     ["summary preambles", /\bTo\s+recap\b/i],
-    ["summary preambles", /\bOverall\b/i],
+    ["summary preambles", /\bOverall\b(?!\s+acceptance\b)/i],
     ["excessive justification", /I\s+chose\s+this\s+approach\s+because\b/i],
 ];
 /** Count non-whitespace tokens, matching Python's str.split(). */
 function wordCount(text) {
     return (text.match(/\S+/g) ?? []).length;
 }
-export function checkVerbosity(text, artifact, budgets = null) {
-    const count = wordCount(text);
-    const table = budgets ?? PER_ENTRY_BUDGETS;
-    let perEntryBudget = table[artifact];
-    if (perEntryBudget === undefined) {
-        const fullBudget = FULL_FILE_BUDGETS[artifact];
-        perEntryBudget = fullBudget !== undefined ? Math.floor(fullBudget / 5) : 500;
+export function checkVerbosity(text, artifact, contractPath) {
+    return checkAuthoritativeWordBudget(text, artifact, false, contractPath);
+}
+export function checkFullFileVerbosity(text, artifact, contractPath) {
+    return checkAuthoritativeWordBudget(text, artifact, true, contractPath);
+}
+function authorityError(artifact, detail) {
+    return [
+        false,
+        `verbosity authority error for ${JSON.stringify(artifact)}: ${detail}; ` +
+            "repair the declared owner in references/artifacts/verbosity-budget-authority.yaml",
+    ];
+}
+function applicableDimensions(dimensions, fullArtifact) {
+    return dimensions.filter((dimension) => fullArtifact ? dimension.scope === "full_file" : dimension.scope !== "full_file");
+}
+function checkAuthoritativeWordBudget(text, artifact, fullArtifact, contractPath) {
+    let dimensions;
+    try {
+        dimensions = inspectArtifactVerbosityBudget(artifact, contractPath).dimensions;
+    }
+    catch (error) {
+        return authorityError(artifact, error.message);
+    }
+    const invalid = dimensions.filter((dimension) => dimension.classification === "invalid_declaration");
+    if (invalid.length > 0) {
+        return authorityError(artifact, invalid.map((dimension) => `${dimension.scope}: ${dimension.error ?? "invalid declaration"}`).join("; "));
+    }
+    const applicable = applicableDimensions(dimensions, fullArtifact);
+    if (applicable.length > 1) {
+        const kind = fullArtifact ? "full-file" : "per-entry";
+        return authorityError(artifact, `multiple ${kind} declarations apply: ${applicable.map((d) => d.scope).join(", ")}`);
     }
-    if (count <= perEntryBudget) {
+    const dimension = applicable[0];
+    if (!dimension || dimension.classification !== "numeric_limit") {
         return [true, ""];
     }
-    return [false, `verbosity mismatch: ${count} words exceeds ${perEntryBudget} budget`];
-}
-export function checkFullFileVerbosity(text, artifact) {
     const count = wordCount(text);
-    const budget = FULL_FILE_BUDGETS[artifact] ?? 2500;
-    if (count <= budget) {
+    if (count <= dimension.limit) {
         return [true, ""];
     }
-    return [false, `verbosity mismatch: ${count} words exceeds ${budget} full-file budget`];
+    const qualifier = fullArtifact ? " full-file" : "";
+    return [false, `verbosity mismatch: ${count} words exceeds ${dimension.limit}${qualifier} budget`];
 }
 export function checkAbstraction(text) {
     for (const re of [
@@ -104,4 +107,37 @@ export function checkFiller(text) {
     }
     return [false, "filler: " + matched.join(", ")];
 }
-//# sourceMappingURL=selfAudit.js.map
+/** Smoke-validate that self-audit conventions and budgets are wired. */
+export function validateSelfAuditConventions() {
+    const errors = [];
+    const sample = "concrete anchor `scripts/agentera` at line 42 with 12 words total here";
+    const [verbosityOk] = checkVerbosity(sample, "progress");
+    if (!verbosityOk) {
+        errors.push("self-audit: verbosity check failed on smoke sample");
+    }
+    const [abstractionOk] = checkAbstraction(sample);
+    if (!abstractionOk) {
+        errors.push("self-audit: abstraction check failed to detect concrete anchor in smoke sample");
+    }
+    const [fillerOk] = checkFiller("Shipped the plan task with a concrete file path.");
+    if (!fillerOk) {
+        errors.push("self-audit: filler check false-positive on clean smoke sample");
+    }
+    const [fillerFailOk, fillerDetail] = checkFiller("In summary, the work is done.");
+    if (fillerFailOk || !fillerDetail.includes("filler")) {
+        errors.push("self-audit: filler check must flag banned summary preambles");
+    }
+    return errors;
+}
+export function selfAuditMain(opts = {}) {
+    const out = opts.out ?? ((line) => process.stdout.write(line + "\n"));
+    const errors = validateSelfAuditConventions();
+    if (errors.length > 0) {
+        out("self-audit validation failed:");
+        for (const error of errors)
+            out(`- ${error}`);
+        return 1;
+    }
+    out("self-audit conventions ok");
+    return 0;
+}

package/dist/validate/v1LegacyCruft.js

@@ -0,0 +1,131 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { resolvePath } from "../core/paths.js";
+import { confirmedVariantGuardContract } from "../registries/glossaryEntryContract.js";
+import { containsGlossaryTerm } from "../registries/glossaryTermOccurrence.js";
+import { loadProjectGlossaryDocument, } from "../state/write/glossaryPublication.js";
+const EXCLUDED_DIRECTORIES = new Set(confirmedVariantGuardContract().excludedDirectories);
+// Lowercased extensions classify ASCII path suffixes; they are not term identities.
+const TEXT_EXTENSIONS = new Set([
+    ".cjs", ".css", ".go", ".html", ".js", ".json", ".jsonc", ".jsx",
+    ".md", ".mjs", ".py", ".rs", ".sh", ".toml", ".ts", ".tsx", ".txt",
+    ".xml", ".yaml", ".yml",
+]);
+const RERUN = "pnpm -C packages/cli exec vitest run test/cli/v1LegacyCruft.test.ts";
+function fixedLegacyViolations(root) {
+    const violations = [];
+    if (fs.existsSync(path.join(root, "skills/hej")))
+        violations.push("skills/hej/ bridge directory present");
+    if (fs.existsSync(path.join(root, "references/v1-section-mapping.md"))) {
+        violations.push("references/v1-section-mapping.md present");
+    }
+    if (fs.existsSync(path.join(root, ".opencode/commands/hej.md"))) {
+        violations.push(".opencode/commands/hej.md legacy bridge command present");
+    }
+    const marketplacePath = path.join(root, ".claude-plugin/marketplace.json");
+    if (fs.existsSync(marketplacePath)) {
+        const marketplace = JSON.parse(fs.readFileSync(marketplacePath, "utf8"));
+        const names = (marketplace.plugins ?? []).map((item) => item.name);
+        if (names.includes("status"))
+            violations.push(".claude-plugin/marketplace.json still lists hej plugin");
+    }
+    const codexPath = path.join(root, ".codex-plugin/plugin.json");
+    if (fs.existsSync(codexPath)) {
+        const codex = JSON.parse(fs.readFileSync(codexPath, "utf8"));
+        const names = (codex.skillMetadata ?? []).map((item) => item.name);
+        if (names.includes("status"))
+            violations.push(".codex-plugin/plugin.json still lists hej skillMetadata");
+    }
+    const packageRegistryPath = path.join(root, "references/adapters/package-registry.yaml");
+    if (fs.existsSync(packageRegistryPath)) {
+        const registry = YAML.parse(fs.readFileSync(packageRegistryPath, "utf8"));
+        const versionFiles = registry.records?.[0]?.docs_targets?.version_files ?? [];
+        if (versionFiles.includes("skills/hej/SKILL.md")) {
+            violations.push("package-registry docs_targets still lists skills/hej/SKILL.md");
+        }
+    }
+    return violations;
+}
+function confirmedVariants(document) {
+    return document.approvals.flatMap((approval, index) => {
+        const entry = document.entries[index];
+        const canonical = String(entry.term);
+        // Project-glossary validation already rejects every canonical/variant
+        // identity collision. Preserve all validated variants for guard scanning.
+        return approval.proposal.variants
+            .map(({ term, evidence }) => ({
+            variant: term,
+            canonical,
+            approvalDigest: approval.proposal_digest,
+            evidence,
+        }));
+    });
+}
+function projectTextFiles(root) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isSymbolicLink())
+                continue;
+            const target = path.join(directory, entry.name);
+            if (entry.isDirectory()) {
+                if (!EXCLUDED_DIRECTORIES.has(entry.name))
+                    visit(target);
+            }
+            else if (entry.isFile() && TEXT_EXTENSIONS.has(path.extname(entry.name).toLocaleLowerCase())) {
+                files.push(target);
+            }
+        }
+    };
+    visit(root);
+    return files;
+}
+function lineDigest(line) {
+    return crypto.createHash("sha256").update(line).digest("hex");
+}
+function isApprovedEvidence(variant, sourcePath, line, text) {
+    const digest = lineDigest(text);
+    return variant.evidence.some((item) => item.source_path === sourcePath && item.line === line && item.source_record_sha256 === digest);
+}
+function variantViolations(root, document, glossaryPath) {
+    const violations = [];
+    const seen = new Set();
+    for (const file of projectTextFiles(root)) {
+        if (path.resolve(file) === path.resolve(glossaryPath))
+            continue;
+        const sourcePath = path.relative(root, file).split(path.sep).join(path.posix.sep);
+        const lines = fs.readFileSync(file, "utf8").split(/\r?\n/);
+        for (const variant of confirmedVariants(document)) {
+            for (const [index, text] of lines.entries()) {
+                const line = index + 1;
+                if (!containsGlossaryTerm(text, variant.variant) || isApprovedEvidence(variant, sourcePath, line, text))
+                    continue;
+                const identity = `${variant.approvalDigest}\0${variant.variant}\0${sourcePath}\0${line}`;
+                if (seen.has(identity))
+                    continue;
+                seen.add(identity);
+                const evidence = variant.evidence.map((item) => `${item.source_path}:${item.line}`).join(", ");
+                violations.push(`confirmed variant '${variant.variant}' reintroduced at ${sourcePath}:${line}; canonical term '${variant.canonical}' ` +
+                    `from approval ${variant.approvalDigest} (confirmed variant evidence: ${evidence}). ` +
+                    `Correction: replace '${variant.variant}' with '${variant.canonical}' at ${sourcePath}:${line}; rerun: ${RERUN}`);
+            }
+        }
+    }
+    return violations.sort();
+}
+export function scanPost30CruftViolations(root) {
+    const resolved = resolvePath(root);
+    const violations = fixedLegacyViolations(resolved);
+    try {
+        const loaded = loadProjectGlossaryDocument(resolved);
+        if (loaded)
+            violations.push(...variantViolations(resolved, loaded.document, loaded.path));
+    }
+    catch (error) {
+        violations.push(`project glossary is malformed: ${error.message}. ` +
+            `Correction: restore a valid confirmed document or rerun agentera state glossary publish --input REQUEST.yaml --format json; rerun: ${RERUN}`);
+    }
+    return violations.sort();
+}

package/dist/validate/vocabularyAuthority.js

@@ -0,0 +1,303 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePath } from "../core/paths.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { loadYamlMappingFile } from "../core/yaml.js";
+import { APP_MANUAL_REVIEW_NEEDED, APP_MIGRATION_NEEDED, APP_OUTDATED, APP_REPAIR_NEEDED, APP_UP_TO_DATE, } from "../upgrade/doctor.js";
+import { validateGlossaryEntryContract } from "../registries/glossaryEntryContract.js";
+/**
+ * Validate vocabulary authority YAML contracts (Decision 54 lifecycle status
+ * vocabulary, Decision 57 first_invocation_read, update channels, index order).
+ * Emits the same delegated validate envelope shape as lifecycle-adapters.
+ */
+const EXPECTED_STATUSES = [
+    "up_to_date",
+    "outdated",
+    "repair_needed",
+    "migration_needed",
+    "manual_review_needed",
+    "ready_to_apply",
+    "applied",
+    "no_changes_needed",
+];
+const EXPECTED_VERBS = ["install", "repair", "update", "migrate", "upgrade", "refresh"];
+const EXPECTED_LIFECYCLE_CONSUMERS = ["doctor", "status", "upgrade", "docs", "tests"];
+const EXPECTED_CHANNELS = ["stable", "development"];
+const EXPECTED_CHANNEL_CONSUMERS = ["upgrade", "doctor", "prime", "docs", "tests"];
+function rootDefault() {
+    return resolveSourceRoot();
+}
+function authorityPath(root, relative) {
+    return path.join(root, relative);
+}
+function canonicalStatuses(authority) {
+    return new Set(Object.keys(authority.canonical_statuses));
+}
+function rejectedLifecycleStatusValues(authority) {
+    const statuses = authority.canonical_statuses;
+    const verbs = authority.operation_verbs;
+    const deprecated = Object.values(statuses).flatMap((entry) => {
+        const aliases = entry.deprecated_aliases;
+        return Array.isArray(aliases) ? aliases : [];
+    });
+    const nonLifecycleVerbs = Object.entries(verbs)
+        .filter(([, entry]) => entry.lifecycle_allowed === false)
+        .map(([name]) => name);
+    return new Set([...deprecated, ...nonLifecycleVerbs].map(String));
+}
+function validateLifecycleAuthority(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/app-lifecycle-vocabulary.yaml");
+    let authority;
+    try {
+        authority = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`app-lifecycle-vocabulary.yaml: ${exc.message}`];
+    }
+    if (!Array.isArray(authority.canonical_status_order) || authority.canonical_status_order.length === 0) {
+        errors.push("app-lifecycle-vocabulary.yaml: canonical_status_order is required");
+    }
+    else if (JSON.stringify(authority.canonical_status_order) !== JSON.stringify([...EXPECTED_STATUSES])) {
+        errors.push("app-lifecycle-vocabulary.yaml: canonical_status_order drifted from Decision 54 pin");
+    }
+    const statusKeys = Object.keys(authority.canonical_statuses);
+    if (JSON.stringify(statusKeys) !== JSON.stringify([...EXPECTED_STATUSES])) {
+        errors.push("app-lifecycle-vocabulary.yaml: canonical_statuses keys drifted from Decision 54 pin");
+    }
+    for (const status of EXPECTED_STATUSES) {
+        const entry = authority.canonical_statuses[status];
+        if (!entry || !String(entry.concept ?? "").trim() || !String(entry.definition ?? "").trim()) {
+            errors.push(`app-lifecycle-vocabulary.yaml: canonical status '${status}' is incomplete`);
+        }
+    }
+    const aliasToStatus = new Map();
+    for (const [status, raw] of Object.entries(authority.canonical_statuses)) {
+        for (const alias of raw.deprecated_aliases) {
+            aliasToStatus.set(alias, status);
+        }
+    }
+    const expectedAliases = {
+        fresh: "up_to_date",
+        stale: "outdated",
+        refresh_required: "repair_needed",
+        fixed: "applied",
+        noop: "no_changes_needed",
+    };
+    for (const [alias, status] of Object.entries(expectedAliases)) {
+        if (aliasToStatus.get(alias) !== status) {
+            errors.push(`app-lifecycle-vocabulary.yaml: deprecated alias '${alias}' must map to '${status}'`);
+        }
+    }
+    const doctorAllowed = new Set(authority.consumers.doctor.may_emit_statuses);
+    const observed = [
+        APP_UP_TO_DATE,
+        APP_OUTDATED,
+        APP_REPAIR_NEEDED,
+        APP_MIGRATION_NEEDED,
+        APP_MANUAL_REVIEW_NEEDED,
+    ];
+    for (const status of observed) {
+        if (!canonicalStatuses(authority).has(status)) {
+            errors.push(`doctor constant '${status}' is not a canonical lifecycle status`);
+        }
+        else if (!doctorAllowed.has(status)) {
+            errors.push(`doctor consumer may not emit canonical status '${status}'`);
+        }
+        else if (rejectedLifecycleStatusValues(authority).has(status)) {
+            errors.push(`doctor constant '${status}' is a rejected lifecycle alias or verb`);
+        }
+    }
+    if (!Array.isArray(authority.consumer_order) || authority.consumer_order.length === 0) {
+        errors.push("app-lifecycle-vocabulary.yaml: consumer_order is required");
+    }
+    else if (JSON.stringify(authority.consumer_order) !== JSON.stringify([...EXPECTED_LIFECYCLE_CONSUMERS])) {
+        errors.push("app-lifecycle-vocabulary.yaml: consumer_order drifted from Decision 54 pin");
+    }
+    const allowedStatuses = new Set(EXPECTED_STATUSES);
+    const allowedVerbs = new Set(EXPECTED_VERBS);
+    for (const consumer of EXPECTED_LIFECYCLE_CONSUMERS) {
+        const entry = authority.consumers[consumer];
+        if (!entry) {
+            errors.push(`app-lifecycle-vocabulary.yaml: missing consumer '${consumer}'`);
+            continue;
+        }
+        if (entry.may_define_new_statuses !== false) {
+            errors.push(`app-lifecycle-vocabulary.yaml: consumer '${consumer}' must not define new statuses`);
+        }
+        for (const status of entry.may_emit_statuses ?? []) {
+            if (!allowedStatuses.has(status)) {
+                errors.push(`app-lifecycle-vocabulary.yaml: consumer '${consumer}' emits unknown status '${status}'`);
+            }
+        }
+        for (const verb of entry.may_use_verbs ?? []) {
+            if (!allowedVerbs.has(verb)) {
+                errors.push(`app-lifecycle-vocabulary.yaml: consumer '${consumer}' uses unknown verb '${verb}'`);
+            }
+        }
+    }
+    const delegation = authority.docs_delegation;
+    if (delegation?.document !== "references/cli/vocabulary.md" ||
+        delegation?.required_anchor !== "App lifecycle status vocabulary" ||
+        delegation?.authority_path !== "references/cli/app-lifecycle-vocabulary.yaml") {
+        errors.push("app-lifecycle-vocabulary.yaml: docs_delegation contract drifted");
+    }
+    return errors;
+}
+function validateUpdateChannelsAuthority(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/update-channels.yaml");
+    let authority;
+    try {
+        authority = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`update-channels.yaml: ${exc.message}`];
+    }
+    if (authority.default_channel !== "stable") {
+        errors.push("update-channels.yaml: default_channel must be stable");
+    }
+    if (JSON.stringify(authority.channel_order) !== JSON.stringify([...EXPECTED_CHANNELS])) {
+        errors.push("update-channels.yaml: channel_order drifted");
+    }
+    const stable = authority.channels.stable;
+    const development = authority.channels.development;
+    if (!stable || !development) {
+        errors.push("update-channels.yaml: stable and development channels are required");
+    }
+    else {
+        const stableNpm = stable.resolution?.npm;
+        const devNpm = development.resolution?.npm;
+        if (stableNpm?.dist_tag !== "latest" || devNpm?.dist_tag !== "next") {
+            errors.push("update-channels.yaml: npm dist_tag pins drifted");
+        }
+        if (!String(stableNpm?.update_command ?? "").includes("@latest")) {
+            errors.push("update-channels.yaml: stable npm update_command must reference @latest");
+        }
+        if (!String(devNpm?.update_command ?? "").includes("@next")) {
+            errors.push("update-channels.yaml: development npm update_command must reference @next");
+        }
+        if (development.resolution?.git && development.resolution.git) {
+            const devGit = development.resolution.git;
+            if (devGit.supported !== false) {
+                errors.push("update-channels.yaml: development git resolution must be unsupported");
+            }
+        }
+    }
+    if (!Array.isArray(authority.consumer_order)) {
+        errors.push("update-channels.yaml: consumer_order is required");
+    }
+    else if (JSON.stringify(authority.consumer_order) !== JSON.stringify([...EXPECTED_CHANNEL_CONSUMERS])) {
+        errors.push("update-channels.yaml: consumer_order drifted");
+    }
+    const delegation = authority.docs_delegation;
+    if (delegation?.document !== "references/cli/vocabulary.md" ||
+        delegation?.required_anchor !== "Update channels" ||
+        delegation?.authority_path !== "references/cli/update-channels.yaml") {
+        errors.push("update-channels.yaml: docs_delegation contract drifted");
+    }
+    return errors;
+}
+function validateInstructionContract(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/capability-instruction-contract.yaml");
+    let authority;
+    try {
+        authority = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`capability-instruction-contract.yaml: ${exc.message}`];
+    }
+    const firstRead = authority.first_invocation_read;
+    if (!firstRead) {
+        errors.push("capability-instruction-contract.yaml: first_invocation_read block is required");
+        return errors;
+    }
+    const allowed = firstRead.allowed_values;
+    if (!allowed || typeof allowed.prime_context !== "object") {
+        errors.push("capability-instruction-contract.yaml: first_invocation_read.allowed_values.prime_context is required");
+    }
+    else {
+        const meaning = String(allowed.prime_context.meaning ?? "");
+        if (!meaning.includes("npx -y agentera@next prime --context")) {
+            errors.push("capability-instruction-contract.yaml: prime_context obligation must reference npx -y agentera@next prime --context");
+        }
+    }
+    if (firstRead.default_rule !== "prime_context") {
+        errors.push("capability-instruction-contract.yaml: first_invocation_read.default_rule must be prime_context");
+    }
+    const cliMeta = authority.current_state?.cli_metadata;
+    if (cliMeta?.field !== "first_invocation_read") {
+        errors.push("capability-instruction-contract.yaml: cli_metadata.field must be first_invocation_read");
+    }
+    const delegation = authority.docs_delegation;
+    if (delegation?.document !== "references/cli/vocabulary.md" ||
+        delegation?.required_anchor !== "Capability instruction contract" ||
+        delegation?.authority_path !== "references/cli/capability-instruction-contract.yaml") {
+        errors.push("capability-instruction-contract.yaml: docs_delegation contract drifted");
+    }
+    return errors;
+}
+function validateVocabularyIndex(root) {
+    const errors = [];
+    const p = authorityPath(root, "references/cli/vocabulary-index.yaml");
+    let index;
+    try {
+        index = loadYamlMappingFile(p); // cast: YAML parse IO boundary
+    }
+    catch (exc) {
+        return [`vocabulary-index.yaml: ${exc.message}`];
+    }
+    const order = index.authority_order;
+    if (!Array.isArray(order)) {
+        return ["vocabulary-index.yaml: authority_order is required"];
+    }
+    const lifecycleIdx = order.indexOf("references/cli/app-lifecycle-vocabulary.yaml");
+    const channelsIdx = order.indexOf("references/cli/update-channels.yaml");
+    if (lifecycleIdx < 0 || channelsIdx < 0) {
+        errors.push("vocabulary-index.yaml: authority_order missing required vocabulary authorities");
+    }
+    else if (!(lifecycleIdx < channelsIdx)) {
+        errors.push("vocabulary-index.yaml: authority_order must place lifecycle before channels");
+    }
+    const vocabularyMd = authorityPath(root, "references/cli/vocabulary.md");
+    if (!fs.existsSync(vocabularyMd)) {
+        errors.push("references/cli/vocabulary.md: missing vocabulary prose delegation surface");
+        return errors;
+    }
+    const vocabulary = fs.readFileSync(vocabularyMd, "utf8");
+    const lifecycleSection = vocabulary.split("### App lifecycle status vocabulary")[1]?.split("### Update channels", 1)[0] ?? "";
+    if (!lifecycleSection.includes("references/cli/app-lifecycle-vocabulary.yaml") ||
+        !lifecycleSection.includes("machine-readable authority")) {
+        errors.push("references/cli/vocabulary.md: app lifecycle section must delegate to YAML authority");
+    }
+    const channelsSection = vocabulary.split("### Update channels")[1]?.split("## Evaluation and evidence grammar", 1)[0] ?? "";
+    if (!channelsSection.includes("references/cli/update-channels.yaml") ||
+        !channelsSection.includes("machine-readable authority")) {
+        errors.push("references/cli/vocabulary.md: update channels section must delegate to YAML authority");
+    }
+    return errors;
+}
+export function validateVocabularyAuthority(root = rootDefault()) {
+    const resolved = resolvePath(root);
+    return [
+        ...validateLifecycleAuthority(resolved),
+        ...validateUpdateChannelsAuthority(resolved),
+        ...validateInstructionContract(resolved),
+        ...validateVocabularyIndex(resolved),
+        ...validateGlossaryEntryContract(authorityPath(resolved, "references/artifacts/glossary-entry-contract.yaml")),
+    ];
+}
+export function vocabularyAuthorityMain(opts = {}) {
+    const root = resolvePath(opts.root ?? rootDefault());
+    const out = opts.out ?? ((line) => process.stdout.write(line + "\n"));
+    const errors = validateVocabularyAuthority(root);
+    if (errors.length > 0) {
+        out("vocabulary authority validation failed:");
+        for (const error of errors)
+            out(`- ${error}`);
+        return 1;
+    }
+    out("vocabulary authority ok");
+    return 0;
+}