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

package/dist/hooks/compaction/status.js

@@ -0,0 +1,360 @@
+/**
+ * Compaction status reporting and projection repair.
+ *
+ * Walks each tracked artifact path, counts active/archive entries, and
+ * builds a `CompactionStatus` per artifact plus a per-status operation
+ * row in `checkCompaction`/`fixCompaction`. The `fixCompaction` path
+ * delegates the actual write to `apply.ts`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_ARTIFACT_PATHS, parseDocsYamlMapping } from "../common.js";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { COMPACTABLE_YAML_ARTIFACTS, NON_COMPACTABLE_ARTIFACTS } from "./dryRun.js";
+import { detectStateMode } from "../../state/stateMode.js";
+import { discoverEntities } from "../../state/entityStorage.js";
+import { decisionProtectedOverflowCount, decisionSatisfiedActiveCount, overLimitCount, yamlArchiveEntries, } from "./retention.js";
+import { compactFile, compactYamlBytes, compactYamlFile } from "./apply.js";
+import { countTodoResolvedEntries, countTodoResolvedSectionHeadings, countTodoPendingSummarization, TODO_DROPPED_RECOVERY_GUIDANCE, } from "./parse.js";
+import { YAML_SPEC_BY_ARTIFACT } from "./dryRun.js";
+import { InjectedMutationFailure, withStateMutation, } from "../../state/write/mutation.js";
+import { hydrateDecisionRecords } from "../../state/decisionOverlay.js";
+import { loadProjectionPolicy } from "../../state/projectionPolicy.js";
+import { ARTIFACT_PROTOCOL_PATHS } from "../../registries/artifactProtocolIds.js";
+function artifactPaths(projectRoot) {
+    const paths = { ...DEFAULT_ARTIFACT_PATHS };
+    const docsPath = path.join(projectRoot, ARTIFACT_PROTOCOL_PATHS.docs);
+    if (fs.existsSync(docsPath)) {
+        Object.assign(paths, parseDocsYamlMapping(fs.readFileSync(docsPath, "utf8")));
+    }
+    const resolved = {};
+    for (const [artifact, rel] of Object.entries(paths)) {
+        resolved[artifact] = path.join(projectRoot, rel);
+    }
+    return resolved;
+}
+function missingStatus(artifact, p, classification) {
+    return {
+        artifact,
+        path: p,
+        classification,
+        active_count: 0,
+        archive_count: 0,
+        total_count: 0,
+        over_limit_count: 0,
+        reason: "artifact path is not present",
+        protected_overflow_count: 0,
+        exists: false,
+    };
+}
+function yamlErrorStatus(artifact, p, message) {
+    return {
+        artifact,
+        path: p,
+        classification: "error",
+        active_count: null,
+        archive_count: null,
+        total_count: null,
+        over_limit_count: null,
+        reason: message.trim() || "invalid YAML mapping root",
+        protected_overflow_count: 0,
+        exists: true,
+    };
+}
+function yamlCounts(p, activeKey, archiveKey) {
+    const data = loadYamlMapping(fs.readFileSync(p, "utf8"));
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [0, 0];
+    const active = data[activeKey] || [];
+    const archive = data[archiveKey] || [];
+    return [Array.isArray(active) ? active.length : 0, Array.isArray(archive) ? archive.length : 0];
+}
+function yamlLists(p, activeKey, archiveKey) {
+    const data = loadYamlMapping(fs.readFileSync(p, "utf8"));
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return [[], []];
+    const active = data[activeKey] || [];
+    const archive = data[archiveKey] || [];
+    return [Array.isArray(active) ? active : [], Array.isArray(archive) ? archive : []];
+}
+function countStatus(artifact, p, activeCount, archiveCount, protectedOverflowCount = 0, budgetActiveCount, projectionRecovery, projectionState) {
+    const totalCount = activeCount + archiveCount;
+    const budgetActive = budgetActiveCount ?? activeCount;
+    return {
+        artifact,
+        path: p,
+        classification: "compactable",
+        active_count: activeCount,
+        archive_count: archiveCount,
+        total_count: totalCount,
+        over_limit_count: projectionState ? 0 : overLimitCount(budgetActive, archiveCount),
+        reason: projectionState
+            ? projectionState === "over_defaults"
+                ? "lossless projection exceeds display defaults; numbered archives remain authoritative"
+                : "lossless projection is within display defaults"
+            : protectedOverflowCount
+                ? "protected-overflow review pressure"
+                : "uniform_10_40_50",
+        protected_overflow_count: protectedOverflowCount,
+        exists: true,
+        ...(projectionState ? { projection_state: projectionState } : {}),
+        ...(projectionRecovery ? { projection_recovery: projectionRecovery } : {}),
+    };
+}
+function projectionRecoveryFor(projectRoot, artifact, p) {
+    try {
+        return compactYamlBytes(fs.readFileSync(p, "utf8"), artifact, projectRoot).result.recovery;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function computeCompactionStatus(projectRoot) {
+    if (detectStateMode(projectRoot) === "entities") {
+        const discovered = discoverEntities(projectRoot);
+        const issueCount = discovered.issues.length;
+        return [{
+                artifact: "entity_state",
+                path: path.join(projectRoot, ".agentera", "entities"),
+                classification: issueCount ? "error" : "canonical_entities",
+                active_count: discovered.entities.length,
+                archive_count: 0,
+                total_count: discovered.entities.length,
+                over_limit_count: 0,
+                reason: issueCount
+                    ? `${issueCount} canonical entity validation issue(s); run agentera check validate state --format json`
+                    : "canonical entity state is independently stored and is not compacted",
+                protected_overflow_count: 0,
+                exists: true,
+            }];
+    }
+    const paths = artifactPaths(projectRoot);
+    const projectionPolicy = loadProjectionPolicy();
+    const statuses = [];
+    const todoPath = paths.todo;
+    if (fs.existsSync(todoPath)) {
+        const todoText = fs.readFileSync(todoPath, "utf8");
+        const headingCount = countTodoResolvedSectionHeadings(todoText);
+        if (headingCount > 1) {
+            // Refuse rather than silently process only the first `## ✓ Resolved`
+            // section: duplicates hide the trailing entries from the budget and
+            // from fix-mode migration. TODO has no lossless numbered archive, so
+            // recovery once entries are dropped is Git-only.
+            statuses.push({
+                artifact: "todo#Resolved",
+                path: todoPath,
+                classification: "error",
+                active_count: null,
+                archive_count: null,
+                total_count: null,
+                over_limit_count: null,
+                reason: `TODO.md has ${headingCount} '## ✓ Resolved' sections; merge into exactly one before compacting. ` +
+                    `Compaction drops oldest resolved entries and is destructive (no lossless archive); ` +
+                    TODO_DROPPED_RECOVERY_GUIDANCE,
+                protected_overflow_count: 0,
+                exists: true,
+            });
+        }
+        else if (headingCount === 0) {
+            statuses.push({
+                artifact: "todo#Resolved",
+                path: todoPath,
+                classification: "error",
+                active_count: null,
+                archive_count: null,
+                total_count: null,
+                over_limit_count: null,
+                reason: "TODO.md has no required '## ✓ Resolved' section; add exactly one before compacting.",
+                protected_overflow_count: 0,
+                exists: true,
+            });
+        }
+        else {
+            const counts = countTodoResolvedEntries(todoText);
+            const status = countStatus("todo#Resolved", todoPath, counts.full, counts.oneline);
+            // Detect in-budget (≤50) TODOs that still need a formatting rewrite:
+            // rows 11-50 that are long verbatim headers instead of ≤15-word
+            // summaries. This triggers `--mode fix` before entries overflow.
+            const pendingSummarization = countTodoPendingSummarization(todoText);
+            if (pendingSummarization > 0) {
+                status.pending_summarization_count = pendingSummarization;
+            }
+            statuses.push(status);
+        }
+    }
+    else {
+        statuses.push(missingStatus("todo#Resolved", todoPath, "compactable"));
+    }
+    for (const [artifact, [activeKey, archiveKey]] of Object.entries(COMPACTABLE_YAML_ARTIFACTS)) {
+        const p = paths[artifact];
+        if (fs.existsSync(p)) {
+            let active;
+            let archive;
+            try {
+                [active, archive] = yamlLists(p, activeKey, archiveKey);
+            }
+            catch (exc) {
+                statuses.push(yamlErrorStatus(artifact, p, exc.message));
+                continue;
+            }
+            const protectedOverflowCount = artifact === "decisions"
+                ? decisionProtectedOverflowCount(hydrateDecisionRecords(active, projectRoot), hydrateDecisionRecords(archive, projectRoot))
+                : 0;
+            const budgetActiveCount = artifact === "decisions"
+                ? decisionSatisfiedActiveCount(hydrateDecisionRecords(active, projectRoot))
+                : undefined;
+            statuses.push(countStatus(artifact, p, active.length, archive.length, protectedOverflowCount, budgetActiveCount, projectionRecoveryFor(projectRoot, artifact, p), active.length > projectionPolicy.activeEntries ||
+                archive.length > projectionPolicy.summaryEntries ||
+                active.length + archive.length > projectionPolicy.totalEntries
+                ? "over_defaults"
+                : "within_defaults"));
+        }
+        else {
+            statuses.push(missingStatus(artifact, p, "compactable"));
+        }
+    }
+    for (const [artifact, [classification, reason]] of Object.entries(NON_COMPACTABLE_ARTIFACTS)) {
+        const p = paths[artifact];
+        statuses.push({
+            artifact,
+            path: p,
+            classification,
+            active_count: null,
+            archive_count: null,
+            total_count: null,
+            over_limit_count: null,
+            reason,
+            protected_overflow_count: 0,
+            exists: fs.existsSync(p),
+        });
+    }
+    const optimizeDir = path.join(projectRoot, ".agentera", "optimize");
+    if (fs.existsSync(optimizeDir) && fs.statSync(optimizeDir).isDirectory()) {
+        const experimentPaths = [];
+        for (const sub of fs.readdirSync(optimizeDir).sort()) {
+            const expPath = path.join(optimizeDir, sub, "experiments.yaml");
+            if (fs.existsSync(expPath))
+                experimentPaths.push(expPath);
+        }
+        for (const expPath of experimentPaths) {
+            let activeCount;
+            let archiveCount;
+            try {
+                [activeCount, archiveCount] = yamlCounts(expPath, "experiments", "archive");
+            }
+            catch (exc) {
+                statuses.push(yamlErrorStatus("experiments", expPath, exc.message));
+                continue;
+            }
+            statuses.push({
+                artifact: "experiments",
+                path: expPath,
+                classification: "protected",
+                active_count: activeCount,
+                archive_count: archiveCount,
+                total_count: activeCount + archiveCount,
+                over_limit_count: overLimitCount(activeCount, archiveCount),
+                reason: "objective-state experiment files are classified but skipped by default",
+                protected_overflow_count: 0,
+                exists: true,
+            });
+        }
+    }
+    // Touch yamlArchiveEntries to keep the export alive in dry builds.
+    void yamlArchiveEntries;
+    return statuses;
+}
+function operationForStatus(status, mode) {
+    const base = (action, message) => ({
+        status,
+        mode,
+        action,
+        changed: false,
+        result: null,
+        message,
+    });
+    if (!status.exists)
+        return base("missing", status.reason);
+    if (status.classification === "error")
+        return base("error", status.reason);
+    if (status.classification !== "compactable")
+        return base("skipped", status.reason);
+    if (status.projection_recovery?.refused_count) {
+        return base("refused", `projection retained ${status.projection_recovery.retained_full} full entr${status.projection_recovery.retained_full === 1 ? "y" : "ies"}; archive recovery is required before summarization`);
+    }
+    if (status.projection_state === "over_defaults") {
+        return base(mode === "fix" ? "pending_projection" : "projection", "projection exceeds display defaults; archive history remains lossless");
+    }
+    if (!status.over_limit_count && !status.pending_summarization_count) {
+        return base("ok", status.projection_state === "within_defaults"
+            ? "within configured lossless projection defaults"
+            : "within uniform_10_40_50 limits");
+    }
+    if (status.over_limit_count) {
+        return base(mode === "check" ? "over_limit" : "pending_fix", `over uniform_10_40_50 limit by ${status.over_limit_count}`);
+    }
+    // pending_summarization_count > 0 but within budget: rows 11-50 need
+    // ≤15-word summary formatting, not entry removal.
+    const n = status.pending_summarization_count;
+    return base(mode === "check" ? "formatting" : "pending_formatting", `${n} resolved entr${n === 1 ? "y" : "ies"} in summary tier need ≤15-word summarization`);
+}
+export function checkCompaction(projectRoot) {
+    return computeCompactionStatus(projectRoot).map((status) => operationForStatus(status, "check"));
+}
+function fixCompactionUnlocked(projectRoot, transaction) {
+    const operations = [];
+    for (const status of computeCompactionStatus(projectRoot)) {
+        const baseline = operationForStatus(status, "fix");
+        if (baseline.action !== "pending_fix" &&
+            baseline.action !== "pending_projection" &&
+            baseline.action !== "pending_formatting") {
+            operations.push(baseline);
+            continue;
+        }
+        const p = status.path;
+        let result;
+        try {
+            if (status.artifact === "todo#Resolved") {
+                result = transaction.mutateProjection(p, (stage) => compactFile(stage, "todo-resolved"));
+            }
+            else if (status.artifact in YAML_SPEC_BY_ARTIFACT) {
+                result = transaction.mutateProjection(p, (stage) => compactYamlFile(stage, status.artifact, projectRoot));
+            }
+            else {
+                operations.push({ status, mode: "fix", action: "skipped", changed: false, result: null, message: `no fixer registered for ${status.artifact}` });
+                continue;
+            }
+        }
+        catch (exc) {
+            if (exc instanceof InjectedMutationFailure)
+                throw exc;
+            operations.push({ status, mode: "fix", action: "error", changed: false, result: null, message: exc.message });
+            continue;
+        }
+        operations.push({
+            status,
+            mode: "fix",
+            action: result.changed ? "compacted" : "ok",
+            changed: result.changed,
+            result,
+            message: `full ${result.full_before}->${result.full_after}; ` +
+                `archive ${result.oneline_before}->${result.oneline_after}; ` +
+                `omitted ${result.omitted_count ?? 0}; dropped ${result.dropped}`,
+        });
+    }
+    return operations;
+}
+export function fixCompaction(projectRoot, options = {}) {
+    return withStateMutation(projectRoot, (transaction) => fixCompactionUnlocked(projectRoot, transaction), options);
+}
+export function runCompaction(projectRoot, mode = "check", options = {}) {
+    if (mode === "check")
+        return checkCompaction(projectRoot);
+    if (mode === "fix") {
+        if (detectStateMode(projectRoot) === "entities") {
+            return computeCompactionStatus(projectRoot).map((status) => operationForStatus(status, "fix"));
+        }
+        return fixCompaction(projectRoot, options);
+    }
+    throw new Error(`unknown compaction mode: ${mode}`);
+}

package/dist/hooks/compaction/types.js

@@ -0,0 +1,5 @@
+/**
+ * Compaction shared types: the public envelope shapes used by the
+ * status reporting, the apply writers, and the CLI consumers.
+ */
+export {};

package/dist/hooks/validateArtifact/agentFacing.js

@@ -0,0 +1,9 @@
+/**
+ * Re-exports of protocol classification sets used by the validator.
+ * Kept as a separate module so the runtime, schema, and orchestrator
+ * submodules can all share the same set identity (no duplication of
+ * the AGENT_FACING_ARTIFACT_IDS computation across hot paths).
+ */
+import { ARTIFACT_PROTOCOL_PATHS, HUMAN_FACING_ARTIFACT_IDS } from "../../registries/artifactProtocolIds.js";
+export { ARTIFACT_PROTOCOL_PATHS, HUMAN_FACING_ARTIFACT_IDS };
+export const AGENT_FACING_ARTIFACT_IDS = new Set(Object.keys(ARTIFACT_PROTOCOL_PATHS).filter((id) => !HUMAN_FACING_ARTIFACT_IDS.has(id)));

package/dist/hooks/validateArtifact/index.js

@@ -0,0 +1,92 @@
+/**
+ * Artifact validation used by the explicit `agentera check validate artifact`
+ * command and state publication.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { resolvePath } from "../../core/paths.js";
+import { normalizeArtifactProtocolId } from "../../registries/artifactProtocolIds.js";
+import { DEFAULT_ARTIFACT_PATHS } from "../common.js";
+import { validateMd } from "./markdown.js";
+import { defaultArtifactPath, readIfNeeded, } from "./traversal.js";
+import { schemasDirDefault, validateYamlContent } from "./violations.js";
+import { AGENT_FACING_ARTIFACT_IDS, HUMAN_FACING_ARTIFACT_IDS } from "./agentFacing.js";
+export class ArtifactSchemaValidator {
+    schemasDir;
+    schemaCache;
+    constructor(schemasDir = schemasDirDefault()) {
+        this.schemasDir = schemasDir;
+        this.schemaCache = new Map();
+    }
+    loadSchema(name) {
+        if (!this.schemaCache.has(name)) {
+            const p = path.join(this.schemasDir, `${name}.yaml`);
+            if (fs.existsSync(p) && fs.statSync(p).isFile()) {
+                // cast: artifact schema parsed from a YAML schema file
+                this.schemaCache.set(name, loadYamlMapping(fs.readFileSync(p, "utf8")));
+            }
+            else {
+                this.schemaCache.set(name, null);
+            }
+        }
+        return this.schemaCache.get(name) ?? null;
+    }
+    validateYaml(content, schema, name) {
+        return validateYamlContent(content, schema, name);
+    }
+    validateMarkdown(content, name, schema = null) {
+        return validateMd(content, name, schema);
+    }
+    validateExplicit(artifact, filePath, cwd) {
+        const content = readIfNeeded(null, filePath);
+        if (content === null)
+            return [`${artifact}: cannot read artifact file '${filePath}'`];
+        const protocolId = normalizeArtifactProtocolId(artifact);
+        if (protocolId === null) {
+            return [`${artifact}: unsupported artifact protocol id`];
+        }
+        if (AGENT_FACING_ARTIFACT_IDS.has(protocolId)) {
+            const schema = this.loadSchema(protocolId);
+            if (schema === null)
+                return [`${protocolId}: schema '${protocolId}' is not available`];
+            if (Object.keys(schema).length === 0) {
+                return [`${protocolId}: schema '${protocolId}' file is empty or contains no valid definitions`];
+            }
+            return this.validateYaml(content, schema, protocolId);
+        }
+        if (HUMAN_FACING_ARTIFACT_IDS.has(protocolId)) {
+            const schema = this.loadSchema(protocolId);
+            return this.validateMarkdown(content, artifact, schema);
+        }
+        return [
+            `${artifact}: unsupported artifact; expected one of: ${Object.keys(DEFAULT_ARTIFACT_PATHS).sort().join(", ")}`,
+        ];
+    }
+}
+export function loadSchema(name) {
+    return new ArtifactSchemaValidator().loadSchema(name);
+}
+export class ArtifactValidationAdapter {
+    validator;
+    constructor(validator) {
+        this.validator = validator ?? new ArtifactSchemaValidator();
+    }
+    runExplicit(artifact, filePath, cwd) {
+        artifact = artifact.trim();
+        const defaultPath = defaultArtifactPath(artifact, cwd);
+        const resolvedFile = filePath ? (path.isAbsolute(filePath) ? filePath : path.join(cwd, filePath)) : defaultPath;
+        const violations = this.validator.validateExplicit(artifact, resolvedFile, cwd);
+        const payload = {
+            command: "validate-artifact",
+            status: violations.length > 0 ? "fail" : "pass",
+            artifact,
+            file: resolvedFile,
+            docs_mapped_default: defaultPath || null,
+            path_source: filePath ? "provided" : "docs_mapped_default",
+            violations,
+        };
+        return violations.length > 0 ? [2, payload] : [0, payload];
+    }
+}
+export { resolvePath };

package/dist/hooks/validateArtifact/markdown.js

@@ -0,0 +1,145 @@
+/**
+ * Markdown validation for human-facing artifacts (TODO.md, CHANGELOG.md,
+ * SKILL.md, ...). Walks the artifact's schema looking for any group
+ * with required `field` entries and dispatches to the appropriate
+ * section check (ITEM, RELEASE, TOKEN).
+ */
+import { parseTodoMarkdownListItem } from "../../cli/todoMarkdown.js";
+import { classifyTodoSectionHeading, countTodoResolvedSectionHeadings, isLegacyStrikethroughTodoLine, } from "../compaction/parse.js";
+import { isMapping } from "./schema.js";
+function validateTodoResolvedPlacement(content, name) {
+    const violations = [];
+    let section = "other";
+    for (const line of content.split(/\r\n|\r|\n/)) {
+        const kind = classifyTodoSectionHeading(line);
+        if (kind === "resolved") {
+            section = "resolved";
+            continue;
+        }
+        if (kind === "severity") {
+            section = "severity";
+            continue;
+        }
+        if (/^##\s/.test(line.trim())) {
+            section = "other";
+            continue;
+        }
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("-"))
+            continue;
+        const parsed = parseTodoMarkdownListItem(trimmed);
+        if (parsed?.status === "resolved") {
+            if (section === "severity") {
+                violations.push(`${name}: resolved checkbox item must live under '## ✓ Resolved', not in severity bands`);
+                break;
+            }
+        }
+        if (isLegacyStrikethroughTodoLine(trimmed)) {
+            violations.push(`${name}: legacy strikethrough resolved items are not allowed; use '- [x]' under '## ✓ Resolved'`);
+            break;
+        }
+    }
+    // Exactly one section keeps parsing and compaction unambiguous, including
+    // before the first item is resolved. See todo.yaml TC8.
+    const resolvedHeadingCount = countTodoResolvedSectionHeadings(content);
+    if (resolvedHeadingCount === 0) {
+        violations.push(`${name}: missing required '## ✓ Resolved' section`);
+    }
+    else if (resolvedHeadingCount > 1) {
+        violations.push(`${name}: ${resolvedHeadingCount} '## ✓ Resolved' sections found; merge into exactly one (duplicate sections hide entries from the compaction gate and parsing processes only the first).`);
+    }
+    return violations;
+}
+const SKIP_META = new Set(["meta", "GROUP_PREFIXES", "BUDGET", "COMPACTION", "VALIDATION", "CONVENTION"]);
+export function validateMd(content, name, schema = null) {
+    const violations = [];
+    if (!content.trim())
+        violations.push(`${name}: empty content`);
+    const fences = (content.match(/^```/gm) ?? []).length;
+    if (fences % 2)
+        violations.push(`${name}: unclosed code fence`);
+    if (schema)
+        violations.push(...validateMdSchema(content, name, schema));
+    return violations;
+}
+export function validateMdSchema(content, name, schema) {
+    const violations = [];
+    if (!content.trim())
+        return violations;
+    for (const [groupKey, groupValue] of Object.entries(schema)) {
+        if (SKIP_META.has(groupKey) || !isMapping(groupValue))
+            continue;
+        const hasRequired = Object.values(groupValue).some((e) => isMapping(e) && e.required && e.field);
+        if (!hasRequired)
+            continue;
+        if (groupKey === "ITEM")
+            validateMdItems(content, name, violations);
+        else if (groupKey === "RELEASE")
+            validateMdReleases(content, name, violations);
+        else if (groupKey === "TOKEN")
+            validateMdTokens(content, name, violations);
+    }
+    return violations;
+}
+export function validateMdItems(content, name, violations) {
+    const versionHeading = /^##\s+/m.exec(content);
+    if (!versionHeading) {
+        violations.push(`${name}: missing severity sections (expected '## <glyph> <name>' headings)`);
+        return;
+    }
+    const severityGlyphs = ["⇶", "⇉", "→", "⇢"];
+    let found = false;
+    for (const glyph of severityGlyphs) {
+        const g = glyph.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        if (new RegExp(`^##\\s*${g}`, "m").test(content)) {
+            found = true;
+            const sectionStart = new RegExp(`^##\\s*${g}.+$`, "m").exec(content);
+            if (sectionStart) {
+                const idx = sectionStart.index + sectionStart[0].length;
+                const nextMatch = content.slice(idx).match(/\n##\s/);
+                let bodyStart = idx;
+                if (content.startsWith("\r\n", bodyStart))
+                    bodyStart += 2;
+                else if (content[bodyStart] === "\n")
+                    bodyStart += 1;
+                const sectionEnd = nextMatch ? idx + nextMatch.index : content.length;
+                const sectionBody = content.slice(bodyStart, sectionEnd);
+                const headingSlice = content.slice(sectionStart.index, sectionStart.index + sectionStart[0].length);
+                const glyphNameMatch = new RegExp(`^##\\s*(${g}.+)$`, "m").exec(headingSlice);
+                const headingText = glyphNameMatch ? glyphNameMatch[1] : glyph;
+                const gluedNextSection = nextMatch?.index === 0;
+                if (gluedNextSection || /^\s*##\s/m.test(sectionBody)) {
+                    violations.push(`${name}: severity section '${headingText}' body contains a nested heading; add a blank line before the next '##' section`);
+                }
+                if (glyph === "⇶" && /^\s*-\s+\[x\]/im.test(sectionBody)) {
+                    violations.push(`${name}: severity section '⇶ Critical' must not contain resolved '- [x]' items; move them to '## ✓ Resolved'`);
+                }
+            }
+        }
+    }
+    if (name === "TODO.md" || name === "todo") {
+        violations.push(...validateTodoResolvedPlacement(content, name));
+    }
+    if (!found) {
+        violations.push(`${name}: missing severity glyph in section headings (expected '## ⇶ Critical', '## ⇉ Degraded', '## → Normal', '## ⇢ Annoying')`);
+    }
+}
+export function validateMdReleases(content, name, violations) {
+    if (!/^##\s*\[/m.test(content)) {
+        violations.push(`${name}: missing version header (expected '## [X.Y.Z]')`);
+    }
+    const changeSections = new Set(["### Added", "### Changed", "### Fixed", "### Removed"]);
+    const lines = new Set(content.split("\n"));
+    if (![...changeSections].some((s) => lines.has(s))) {
+        violations.push(`${name}: missing change sections (expected '### Added', '### Changed', '### Fixed', or '### Removed')`);
+    }
+}
+export function validateMdTokens(content, name, violations) {
+    if (!/^##\s/m.test(content)) {
+        violations.push(`${name}: missing section heading (expected '## SectionName')`);
+    }
+    const yamlBlocks = (content.match(/^```yaml\s*$/gm) ?? []).length;
+    if (!yamlBlocks) {
+        violations.push(`${name}: missing YAML code block with token definitions (expected '\`\`\`yaml')`);
+    }
+}