agentera 3.0.0-dev.7 → 3.0.0-dev.72

package/dist/eval/hybridRouteEvaluation.js

@@ -0,0 +1,155 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadYamlMapping } from "../core/yaml.js";
+import { resolveSourceRoot } from "../core/sourceRoot.js";
+import { resolveRouteRequest } from "../registries/hybridRoute.js";
+import { validateRouteReceiptSubmission } from "../registries/hybridRouteReceipt.js";
+function mapping(value, source) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${source} must be a mapping`);
+    return value;
+}
+function requiredString(value, source) {
+    if (typeof value !== "string" || !value)
+        throw new Error(`${source} must be a non-empty string`);
+    return value;
+}
+function cases(value, source) {
+    if (!Array.isArray(value))
+        throw new Error(`${source} must be a list`);
+    return value;
+}
+function elapsedMs(start) {
+    return Number(process.hrtime.bigint() - start) / 1_000_000;
+}
+function percentile(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((left, right) => left - right);
+    return sorted[Math.ceil(sorted.length * 0.95) - 1];
+}
+function hashFile(file) {
+    return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+function nullableFixtureReceipt(receipt) {
+    return {
+        version: null,
+        request_sha256: null,
+        semantic_capsule_sha256: null,
+        outcome: null,
+        capability: null,
+        compound: null,
+        question: null,
+        remainder_span: null,
+        ...receipt,
+    };
+}
+/** Runs the complete frozen synthetic conformance corpus without invoking a semantic host. */
+export function evaluateHybridRoute(sourceRoot = resolveSourceRoot()) {
+    const contractPath = path.join(sourceRoot, "references/cli/hybrid-route-contract.yaml");
+    const corpusPath = path.join(sourceRoot, "fixtures/routing/hybrid-corpus.yaml");
+    const phrasePath = path.join(sourceRoot, "skills/agentera/route-phrases.yaml");
+    const skillPath = path.join(sourceRoot, "skills/agentera/SKILL.md");
+    const contract = loadYamlMapping(fs.readFileSync(contractPath, "utf8"));
+    const corpus = loadYamlMapping(fs.readFileSync(corpusPath, "utf8"));
+    const evaluation = mapping(contract.evaluation, "contract.evaluation");
+    const targetGates = mapping(evaluation.target_gates, "contract.evaluation.target_gates");
+    const routeCases = cases(corpus.route_cases, "corpus.route_cases");
+    const receiptCases = cases(corpus.receipt_cases, "corpus.receipt_cases");
+    const results = [];
+    const deterministicTimings = [];
+    const receiptTimings = [];
+    for (const routeCase of routeCases) {
+        const start = process.hrtime.bigint();
+        const observed = resolveRouteRequest(routeCase.request, sourceRoot);
+        const elapsed = elapsedMs(start);
+        deterministicTimings.push(elapsed);
+        const passed = observed.outcome === routeCase.expected.phase1
+            && (observed.outcome !== "deterministic_selection" || (observed.tier === routeCase.expected.tier && observed.capability === routeCase.expected.capability));
+        const harmfulMisroute = observed.outcome === "deterministic_selection"
+            && (routeCase.expected.phase1 !== "deterministic_selection" || observed.capability !== routeCase.expected.capability);
+        results.push({
+            case_id: routeCase.id,
+            partition: routeCase.partition,
+            evaluation_tier: "deterministic",
+            routing_tier: observed.outcome === "deterministic_selection" ? observed.tier : "deterministic_abstention",
+            expected_outcome: routeCase.expected.phase1,
+            observed_outcome: observed.outcome,
+            ...(observed.outcome === "deterministic_selection" ? { capability: observed.capability } : {}),
+            status: passed ? "pass" : "fail",
+            ...(passed ? {} : { failure_tier: "deterministic" }),
+            harmful_misroute: harmfulMisroute,
+            elapsed_ms: elapsed,
+        });
+    }
+    for (const receiptCase of receiptCases) {
+        const start = process.hrtime.bigint();
+        let terminal = "invalid_receipt";
+        try {
+            const receipt = receiptCase.valid ? nullableFixtureReceipt(receiptCase.receipt) : receiptCase.receipt;
+            terminal = validateRouteReceiptSubmission({ request: receiptCase.request, receipt }, sourceRoot).outcome;
+        }
+        catch {
+            terminal = "invalid_receipt";
+        }
+        const elapsed = elapsedMs(start);
+        receiptTimings.push(elapsed);
+        const passed = terminal === receiptCase.expected_terminal;
+        const harmfulMisroute = terminal === "selected" && receiptCase.expected_terminal !== "selected";
+        results.push({
+            case_id: receiptCase.id,
+            partition: receiptCase.partition,
+            evaluation_tier: "receipt_validation",
+            routing_tier: "semantic_receipt_validation",
+            expected_outcome: receiptCase.expected_terminal,
+            observed_outcome: terminal,
+            status: passed ? "pass" : "fail",
+            ...(passed ? {} : { failure_tier: "receipt_validation" }),
+            harmful_misroute: harmfulMisroute,
+            elapsed_ms: elapsed,
+        });
+    }
+    const failed = results.filter(({ status }) => status === "fail");
+    const harmfulMisroutes = results.filter((result) => result.harmful_misroute === true).length;
+    return {
+        schemaVersion: "agentera.hybrid_route_evaluation.v1",
+        status: failed.length === 0 ? "pass" : "fail",
+        authority: {
+            contract_version: requiredString(contract.schema_version, "contract.schema_version"),
+            protocol_sha256: hashFile(contractPath),
+            phrase_authority_sha256: hashFile(phrasePath),
+            shared_skill_sha256: hashFile(skillPath),
+        },
+        corpus: {
+            schema_version: requiredString(corpus.schema_version, "corpus.schema_version"),
+            content_sha256: hashFile(corpusPath),
+            partitions: corpus.partitions,
+            case_count: results.length,
+        },
+        results,
+        aggregate_metrics: {
+            passed: results.length - failed.length,
+            failed: failed.length,
+            harmful_misroutes: {
+                scope: "deterministic_and_receipt_validation_conformance",
+                target: targetGates.harmful_misroutes,
+                observed: harmfulMisroutes,
+                status: harmfulMisroutes === 0 ? "pass" : "fail",
+                taxonomy: evaluation.harmful_misroute_taxonomy,
+            },
+        },
+        model_context: {
+            status: "unmeasured",
+            reason: "host_dependent",
+            samples: 0,
+            distributions: {},
+        },
+        latency: {
+            deterministic_phase1: { sample_count: deterministicTimings.length, p95_ms: percentile(deterministicTimings), target: targetGates.deterministic_phase1_p95 },
+            receipt_validation: { sample_count: receiptTimings.length, p95_ms: percentile(receiptTimings), target: targetGates.receipt_validation_p95 },
+            semantic_model: { status: "unmeasured", reason: "host_dependent" },
+            end_to_end: { status: "unmeasured", reason: "host_dependent" },
+        },
+    };
+}

package/dist/eval/semanticEval.js

@@ -169,4 +169,3 @@ export function main(argv = [], out = (l) => process.stdout.write(l)) {
     out(pyJsonIndent(report) + "\n");
     return report.status === "pass" ? 0 : 1;
 }
-//# sourceMappingURL=semanticEval.js.map

package/dist/eval/semanticFixtures.js

@@ -236,4 +236,3 @@ export function pyRepr(value) {
     }
     return "'" + value.replace(/\\/g, "\\\\").replace(/'/g, "\\'") + "'";
 }
-//# sourceMappingURL=semanticFixtures.js.map

package/dist/hooks/common.js

@@ -1,19 +1,13 @@
-import crypto from "node:crypto";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { expanduser, resolvePath } from "../core/paths.js";
 import { ARTIFACT_PROTOCOL_PATHS, normalizeArtifactMappingKeys, normalizeArtifactProtocolId, } from "../registries/artifactProtocolIds.js";
-import { resolveCandidate } from "../state/installRoot.js";
 /**
- * Shared utilities for agentera hooks. Faithful TS port of hooks/common.py:
- * compaction retention caps, runtime-local session bookmark paths, and artifact
- * path resolution.
+ * Shared utilities for compaction retention caps and artifact path resolution.
  */
 export { loadYamlMapping, loadYamlMappingFile, } from "../core/yaml.js";
 export const MAX_FULL_ENTRIES = 10;
 export const MAX_ONELINE_ENTRIES = 40;
-export const MAX_TOTAL_ENTRIES = MAX_FULL_ENTRIES + MAX_ONELINE_ENTRIES;
+export const MAX_TOTAL_ENTRIES = 50;
 export function applyRetentionCaps(fullEntries, archiveEntries, opts = {}) {
     const maxFull = opts.maxFull ?? MAX_FULL_ENTRIES;
     const maxOneline = opts.maxOneline ?? MAX_ONELINE_ENTRIES;
@@ -21,52 +15,6 @@ export function applyRetentionCaps(fullEntries, archiveEntries, opts = {}) {
     const cappedArchive = archiveEntries.slice(0, maxOneline);
     return [...fullEntries.slice(0, maxFull), ...cappedArchive].slice(0, maxTotal);
 }
-export function resolveAgenteraDataHome(env = process.env, home = os.homedir()) {
-    const configured = env.AGENTERA_HOME;
-    if (configured) {
-        return expanduser(configured);
-    }
-    const [root] = resolveCandidate(null, { env, home });
-    return root;
-}
-export function resolveSessionPath(projectRoot, env = process.env, home = os.homedir()) {
-    const dataHome = resolveAgenteraDataHome(env, home);
-    const resolved = resolvePath(projectRoot);
-    const digest = crypto.createHash("sha256").update(resolved, "utf8").digest("hex").slice(0, 16);
-    const name = path.basename(projectRoot);
-    const slug = name.replace(/[^A-Za-z0-9_.-]+/g, "-").replace(/^[.-]+|[.-]+$/g, "") || "project";
-    return path.join(dataHome, "sessions", `${slug}-${digest}`, "session.yaml");
-}
-export function sessionBookmarkToOneline(entry) {
-    return {
-        timestamp: String(entry.timestamp ?? ""),
-        artifacts: [],
-        summary: String(entry.summary ?? ""),
-        kind: "oneline",
-    };
-}
-export function compactSessionBookmarkEntries(entries, opts = {}) {
-    const maxFull = opts.maxFull ?? MAX_FULL_ENTRIES;
-    const maxOneline = opts.maxOneline ?? MAX_ONELINE_ENTRIES;
-    const maxTotal = opts.maxTotal ?? MAX_TOTAL_ENTRIES;
-    const convert = opts.toOneline ?? sessionBookmarkToOneline;
-    const ordered = [...entries].sort((a, b) => {
-        const ta = String(a.timestamp ?? "");
-        const tb = String(b.timestamp ?? "");
-        return ta < tb ? 1 : ta > tb ? -1 : 0;
-    });
-    const full = [];
-    const archive = [];
-    for (const entry of ordered) {
-        if (entry.kind === "full" && full.length < maxFull) {
-            full.push(entry);
-        }
-        else {
-            archive.push(convert(entry));
-        }
-    }
-    return applyRetentionCaps(full, archive, { maxFull, maxOneline, maxTotal });
-}
 export const DEFAULT_ARTIFACT_PATHS = { ...ARTIFACT_PROTOCOL_PATHS };
 function stripQuotes(value) {
     return value.replace(/^['"]|['"]$/g, "");
@@ -131,7 +79,7 @@ export function resolveArtifactPath(projectRoot, artifact, overrides = null) {
     return path.join(projectRoot, DEFAULT_ARTIFACT_PATHS[artifactId] ?? `.agentera/${artifactId}.yaml`);
 }
 export function loadArtifactOverrides(projectRoot) {
-    const yamlPath = path.join(projectRoot, ".agentera", "docs.yaml");
+    const yamlPath = path.join(projectRoot, ARTIFACT_PROTOCOL_PATHS.docs);
     if (fs.existsSync(yamlPath)) {
         const mapping = parseDocsYamlMapping(fs.readFileSync(yamlPath, "utf8"));
         if (Object.keys(mapping).length > 0) {
@@ -140,4 +88,3 @@ export function loadArtifactOverrides(projectRoot) {
     }
     return null;
 }
-//# sourceMappingURL=common.js.map

package/dist/hooks/compaction/apply.js

@@ -11,58 +11,202 @@
  * runtime these fields are always strings.
  */
 import fs from "node:fs";
+import path from "node:path";
 import YAML from "yaml";
 import { loadYamlMapping } from "../../core/yaml.js";
 import { MAX_FULL_ENTRIES, MAX_ONELINE_ENTRIES, MAX_TOTAL_ENTRIES, applyRetentionCaps } from "../common.js";
 import { COMPACTABLE_YAML_ARTIFACTS, SPECS, YAML_SPEC_BY_ARTIFACT, formatTodoOneline } from "./dryRun.js";
-import { applyRetentionCaps as _applyRetentionCaps, overLimitCount, selectDecisionActiveEntries, selectDecisionArchiveEntries, stableSortBy, yamlArchiveEntries, yamlArchiveEntry, yamlEntryNumber, yamlRecentFullAndOlder, yamlSortEntries, } from "./retention.js";
-import { normalizeTodoResolvedLayout, parseEntries, parseTodoResolved, extractResolvedSection } from "./parse.js";
-export function compactYamlFile(p, artifact) {
+import { decisionRequiresUserReview, selectDecisionActiveEntries, selectDecisionArchiveEntries, stableSortBy, yamlArchiveEntry, yamlEntryNumber, yamlRecentFullAndOlder, yamlSortEntries, } from "./retention.js";
+import { normalizeTodoResolvedLayout, parseEntries, parseTodoResolved, extractResolvedSection, countTodoResolvedSectionHeadings, countTodoPendingSummarization, TODO_DROPPED_RECOVERY_GUIDANCE } from "./parse.js";
+import { hydrateDecisionRecords } from "../../state/decisionOverlay.js";
+import { gateProjectionEntries } from "../../state/archiveRecovery.js";
+import { loadProjectionPolicy, projectionOmission, } from "../../state/projectionPolicy.js";
+function restoreRawSatisfaction(selected, rawEntries) {
+    return selected.map((entry) => {
+        const raw = rawEntries.find((candidate) => yamlEntryNumber(candidate) === yamlEntryNumber(entry));
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+            return entry;
+        const restored = { ...entry };
+        if ("satisfaction" in raw)
+            restored.satisfaction = raw.satisfaction;
+        else
+            delete restored.satisfaction;
+        return restored;
+    });
+}
+function existingOmissionCount(data) {
+    const count = data.omitted_count;
+    return typeof count === "number" && Number.isSafeInteger(count) && count > 0 ? count : 0;
+}
+function archiveProjectionCandidates(specName, rawArchive, generatedArchive, summaryCapacity) {
+    // Inline summaries have no independently verified complete record. They
+    // participate in the same bounded projection as verified summaries, but
+    // their omission explicitly remains degraded legacy history.
+    const candidates = [
+        ...rawArchive.map((entry) => ({ entry, source: "legacy_summary", index: 0 })),
+        ...generatedArchive.map((entry) => ({ entry, source: "archive", index: 1 })),
+    ];
+    const ordered = candidates.sort((left, right) => {
+        const leftTimestamp = String(left.entry?.timestamp ?? left.entry?.date ?? "");
+        const rightTimestamp = String(right.entry?.timestamp ?? right.entry?.date ?? "");
+        if (leftTimestamp !== rightTimestamp)
+            return leftTimestamp < rightTimestamp ? 1 : -1;
+        const leftNumber = yamlEntryNumber(left.entry);
+        const rightNumber = yamlEntryNumber(right.entry);
+        if (leftNumber !== rightNumber)
+            return rightNumber - leftNumber;
+        return left.index - right.index;
+    });
+    const reviewFirst = specName === "decisions"
+        ? [
+            ...ordered.filter((candidate) => decisionRequiresUserReview(candidate.entry)),
+            ...ordered.filter((candidate) => !decisionRequiresUserReview(candidate.entry)),
+        ]
+        : ordered;
+    const retained = reviewFirst.slice(0, summaryCapacity);
+    const omitted = reviewFirst.slice(summaryCapacity);
+    const provenance = [];
+    for (const source of ["legacy_summary", "archive"]) {
+        const omittedCount = omitted.filter((candidate) => candidate.source === source).length;
+        if (omittedCount === 0)
+            continue;
+        provenance.push({
+            source,
+            detail_availability: source === "legacy_summary" ? "unavailable" : "full",
+            compatibility: source === "legacy_summary" ? "degraded" : "complete",
+            archive_verified: source === "archive",
+            omitted_count: omittedCount,
+        });
+    }
+    return {
+        archive: yamlSortEntries(retained.map((candidate) => candidate.entry), specName),
+        omitted: omitted.length,
+        provenance,
+    };
+}
+function existingOmissionProvenance(data) {
+    const raw = data.omission_provenance;
+    const values = Array.isArray(raw) ? raw : raw && typeof raw === "object" ? [raw] : [];
+    return values.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+}
+export function compactYamlBytes(bytes, artifact, projectRoot) {
     if (!(artifact in COMPACTABLE_YAML_ARTIFACTS)) {
         throw new Error(`unsupported YAML artifact: ${artifact}`);
     }
-    if (!fs.existsSync(p)) {
-        throw new Error(p);
-    }
     const [activeKey, archiveKey] = COMPACTABLE_YAML_ARTIFACTS[artifact];
     const specName = YAML_SPEC_BY_ARTIFACT[artifact];
-    const data = loadYamlMapping(fs.readFileSync(p, "utf8"));
+    const data = loadYamlMapping(bytes);
     let active = data[activeKey] || [];
     let archive = data[archiveKey] || [];
     if (!Array.isArray(active))
         active = [];
     if (!Array.isArray(archive))
         archive = [];
-    const fullBefore = active.length;
-    const onelineBefore = archive.length;
-    if (overLimitCount(fullBefore, onelineBefore) === 0) {
-        return { full_before: fullBefore, oneline_before: onelineBefore, full_after: fullBefore, oneline_after: onelineBefore, dropped: 0, changed: false };
+    const rawActive = active;
+    const rawArchive = archive;
+    const policy = loadProjectionPolicy();
+    const selectionActive = specName === "decisions" && projectRoot
+        ? hydrateDecisionRecords(rawActive, projectRoot)
+        : rawActive;
+    const fullBefore = rawActive.length;
+    const onelineBefore = rawArchive.length;
+    if (fullBefore <= policy.activeEntries && onelineBefore <= policy.summaryEntries && fullBefore + onelineBefore <= policy.totalEntries) {
+        return {
+            bytes,
+            result: {
+                full_before: fullBefore,
+                oneline_before: onelineBefore,
+                full_after: fullBefore,
+                oneline_after: onelineBefore,
+                dropped: 0,
+                omitted_count: 0,
+                changed: false,
+            },
+        };
     }
     let recentFull;
     let olderActive;
     if (specName === "decisions") {
-        [recentFull, olderActive] = selectDecisionActiveEntries(active);
+        const [selectedRecent, selectedOlder] = selectDecisionActiveEntries(selectionActive, policy.activeEntries);
+        recentFull = restoreRawSatisfaction(selectedRecent, rawActive);
+        olderActive = restoreRawSatisfaction(selectedOlder, rawActive);
     }
     else {
-        [recentFull, olderActive] = yamlRecentFullAndOlder(active, specName);
+        [recentFull, olderActive] = yamlRecentFullAndOlder(rawActive, specName, policy.activeEntries);
     }
-    const compactedFromActive = olderActive.map((entry) => yamlArchiveEntry(specName, entry));
-    const archiveCandidates = yamlArchiveEntries([...compactedFromActive, ...archive]);
-    let archiveAfter;
+    const projectionRoot = projectRoot ?? process.cwd();
+    // Experiment summaries are the pre-existing 10/40/50 projection itself.
+    // Durable experiment archives are introduced separately; publication must
+    // not silently disable the current projection while that policy is pending.
+    const gated = specName === "experiments"
+        ? {
+            verified: olderActive,
+            refused: [],
+            recovery: {
+                status: "unsupported",
+                attempted: olderActive.length,
+                verified: 0,
+                retained_full: 0,
+                refused_count: 0,
+                refusals: [],
+            },
+        }
+        : gateProjectionEntries(projectionRoot, specName, olderActive);
+    const compactedFromActive = gated.verified.map((entry) => yamlArchiveEntry(specName, entry));
+    const retainedFull = gated.refused.map(({ entry }) => entry);
+    recentFull = yamlSortEntries([...recentFull, ...retainedFull], specName);
+    const archiveProjection = archiveProjectionCandidates(specName, rawArchive, compactedFromActive, policy.summaryEntries);
+    let archiveAfter = archiveProjection.archive;
     if (specName === "decisions") {
-        archiveAfter = selectDecisionArchiveEntries(archiveCandidates);
+        const selectionArchiveCandidates = projectRoot
+            ? hydrateDecisionRecords(archiveAfter, projectRoot)
+            : archiveAfter;
+        archiveAfter = restoreRawSatisfaction(selectDecisionArchiveEntries(selectionArchiveCandidates), archiveAfter);
     }
-    else {
-        const merged = applyRetentionCaps(recentFull, archiveCandidates);
-        archiveAfter = merged.slice(recentFull.length);
+    const omittedCount = existingOmissionCount(data) + archiveProjection.omitted;
+    if (omittedCount > 0) {
+        Object.assign(data, projectionOmission(specName, omittedCount, "projection_capacity", {
+            forceOmitted: true,
+            provenance: [...existingOmissionProvenance(data), ...archiveProjection.provenance],
+        }));
     }
     data[activeKey] = recentFull;
-    data[archiveKey] = archiveAfter;
-    fs.writeFileSync(p, YAML.stringify(data));
+    if (archiveAfter.length > 0 || archiveKey in data || compactedFromActive.length > 0) {
+        data[archiveKey] = archiveAfter;
+    }
+    else {
+        delete data[archiveKey];
+    }
+    const compactedBytes = YAML.stringify(data);
     const fullAfter = recentFull.length;
     const onelineAfter = archiveAfter.length;
-    const dropped = fullBefore + onelineBefore - fullAfter - onelineAfter;
-    return { full_before: fullBefore, oneline_before: onelineBefore, full_after: fullAfter, oneline_after: onelineAfter, dropped, changed: true };
+    // A projection may omit detail only after its complete numbered archive is
+    // verified. Omission is reported separately; logical entries are never
+    // counted as dropped.
+    const dropped = 0;
+    return {
+        bytes: compactedBytes,
+        result: {
+            full_before: fullBefore,
+            oneline_before: onelineBefore,
+            full_after: fullAfter,
+            oneline_after: onelineAfter,
+            dropped,
+            omitted_count: omittedCount,
+            ...(omittedCount > 0 ? { omission_reason: "projection_capacity" } : {}),
+            changed: true,
+            recovery: gated.recovery,
+        },
+    };
+}
+export function compactYamlFile(p, artifact, projectRoot) {
+    if (!fs.existsSync(p))
+        throw new Error(p);
+    const inferredProjectRoot = path.basename(path.dirname(p)) === ".agentera" ? path.dirname(path.dirname(p)) : path.dirname(p);
+    const compacted = compactYamlBytes(fs.readFileSync(p, "utf8"), artifact, projectRoot ?? inferredProjectRoot);
+    if (compacted.result.changed)
+        fs.writeFileSync(p, compacted.bytes);
+    return compacted.result;
 }
 function detectDirection(entries) {
     let asc = 0;
@@ -108,24 +252,32 @@ export function compactEntries(entries, maxFull = MAX_FULL_ENTRIES, maxOneline =
     return result;
 }
 function compactTodoEntries(entries) {
+    // Positional tiering per TC9: the first ten resolved rows are the
+    // recent/full-detail tier even when they have no indented body; rows
+    // 11-50 are the summary tier; rows beyond 50 are dropped. Using
+    // position (not body presence) ensures: (1) a TODO with 55 bodyless
+    // one-liners retains 50 (10 promoted to full + 40 summary), not 40;
+    // (2) a second compaction is idempotent because a compacted file
+    // with 0 body + 50 headers still reports total=50 (not oneline=50>40).
     const result = [];
-    let fullCount = 0;
-    let onelineCount = 0;
-    for (const entry of entries) {
-        if (entry.kind === "full" && fullCount < MAX_FULL_ENTRIES) {
-            result.push(entry);
-            fullCount += 1;
-            continue;
+    for (let i = 0; i < entries.length; i++) {
+        if (i < MAX_FULL_ENTRIES) {
+            // First 10: full-detail tier — preserve body if present, promote
+            // kind to "full" so the writer keeps the header (not formatOneline).
+            result.push(entries[i].kind === "oneline"
+                ? { ...entries[i], kind: "full" }
+                : entries[i]);
         }
-        if (onelineCount < MAX_ONELINE_ENTRIES) {
-            if (entry.kind === "full") {
-                result.push({ header: formatTodoOneline(entry), body: "", kind: "oneline" });
-            }
-            else {
-                result.push(entry);
-            }
-            onelineCount += 1;
+        else if (i < MAX_TOTAL_ENTRIES) {
+            // Items 11-50: summary tier — force ≤15-word summary formatting
+            // by passing kind="full" to formatTodoOneline so it goes through
+            // the truncation path (strip metadata + truncateWords). This must
+            // NOT use kind="oneline" (passthrough), which preserves long
+            // verbatim headers unchanged.
+            const summary = formatTodoOneline({ ...entries[i], kind: "full" });
+            result.push({ header: summary, body: "", kind: "oneline" });
         }
+        // Items 51+: dropped entirely.
     }
     return result;
 }
@@ -180,19 +332,39 @@ function extractHeaderPrefix(text, spec) {
 function compactTodoResolved(p) {
     const spec = SPECS["todo-resolved"];
     let text = fs.readFileSync(p, "utf8");
+    // Enforce exactly one `## ✓ Resolved` heading. Multiple headings hide
+    // trailing entries from parsing; zero headings leave placement ambiguous.
+    // The check-mode status path emits the error before reaching here; this
+    // guard protects direct callers (e.g. validate-artifact auto-compact).
+    const headingCount = countTodoResolvedSectionHeadings(text);
+    if (headingCount > 1) {
+        throw new Error(`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);
+    }
+    if (headingCount === 0) {
+        throw new Error("TODO.md has no required '## ✓ Resolved' section; add exactly one before compacting.");
+    }
+    // headingCount === 1: normalize (migrate misplaced items into existing heading)
     const normalized = normalizeTodoResolvedLayout(text);
     if (normalized.changed) {
         fs.writeFileSync(p, normalized.text);
         text = normalized.text;
     }
-    const [start, end] = extractResolvedSection(text);
+    const [start, end, currentBody] = extractResolvedSection(text);
     if (start < 0)
         return { full_before: 0, oneline_before: 0, full_after: 0, oneline_after: 0, dropped: 0, changed: normalized.changed };
     const entries = parseTodoResolved(text, spec);
-    const fullBefore = entries.filter((e) => e.kind === "full").length;
-    const onelineBefore = entries.filter((e) => e.kind === "oneline").length;
     const totalBefore = entries.length;
-    if (totalBefore <= MAX_TOTAL_ENTRIES && fullBefore <= MAX_FULL_ENTRIES && onelineBefore <= MAX_ONELINE_ENTRIES) {
+    // Positional tiering per TC9 (consistent with countTodoResolvedEntries and
+    // compactTodoEntries): first min(N,10) = full tier, rest = oneline tier.
+    const fullBefore = Math.min(totalBefore, MAX_FULL_ENTRIES);
+    const onelineBefore = Math.max(0, totalBefore - MAX_FULL_ENTRIES);
+    // Skip the rewrite when within budget AND no rows 11-50 need reformatting.
+    // This preserves idempotency: a fully-compacted file (10 verbatim + 40
+    // summaries) reports pendingSummarization=0 and returns changed=false.
+    const pendingSummarization = countTodoPendingSummarization(text);
+    if (totalBefore <= MAX_TOTAL_ENTRIES && pendingSummarization === 0) {
         return {
             full_before: fullBefore,
             oneline_before: onelineBefore,
@@ -202,6 +374,9 @@ function compactTodoResolved(p) {
             changed: normalized.changed,
         };
     }
+    // Either total > 50 (entries to drop) or pendingSummarization > 0 (rows
+    // 11-50 need ≤15-word summary formatting). Run compactTodoEntries and
+    // rewrite the Resolved section body.
     const compacted = compactTodoEntries(entries);
     const fullAfter = compacted.filter((e) => e.kind === "full").length;
     const onelineAfter = compacted.filter((e) => e.kind === "oneline").length;
@@ -227,7 +402,12 @@ function compactTodoResolved(p) {
         full_after: fullAfter,
         oneline_after: onelineAfter,
         dropped,
-        changed: normalized.changed || true,
+        // TODO has no lossless numbered archive: dropped resolved entries are
+        // recoverable only via project history (Git), and only if previously
+        // committed. Surface this honestly in the JSON result rather than
+        // implying a lossless projection.
+        ...(dropped > 0 ? { omission_reason: TODO_DROPPED_RECOVERY_GUIDANCE } : {}),
+        changed: true,
     };
 }
 export function compactFile(p, specName) {
@@ -263,7 +443,4 @@ export function detectOverflow(text, specName) {
     const onelineCount = entries.filter((e) => e.kind === "oneline").length;
     return [fullCount, onelineCount];
 }
-// Silence the re-export-only `_applyRetentionCaps` alias used by status.ts.
-void _applyRetentionCaps;
 void yamlSortEntries;
-//# sourceMappingURL=apply.js.map

package/dist/hooks/compaction/dryRun.js

@@ -167,11 +167,13 @@ export const COMPACTABLE_YAML_ARTIFACTS = {
     progress: ["cycles", "archive"],
     decisions: ["decisions", "archive"],
     health: ["audits", "archive"],
+    experiments: ["experiments", "archive"],
 };
 export const YAML_SPEC_BY_ARTIFACT = {
     progress: "progress",
     decisions: "decisions",
     health: "health",
+    experiments: "experiments",
 };
 export const NON_COMPACTABLE_ARTIFACTS = {
     changelog: ["exempt", "public release history is not compacted"],
@@ -180,4 +182,3 @@ export const NON_COMPACTABLE_ARTIFACTS = {
     vision: ["protected", "vision state is protected during execution cycles"],
     design: ["unsupported", "design is a human-facing identity artifact, not a uniform retained-entry log"],
 };
-//# sourceMappingURL=dryRun.js.map

package/dist/hooks/compaction/index.js

@@ -1,5 +1,5 @@
 /**
- * Public surface for the compaction hook.
+ * Public surface for the compaction engine.
  *
  * Re-exports the API consumed by `cli/commands/compact.ts` and the
  * test suite. The actual implementation lives in the per-
@@ -13,11 +13,10 @@
  *                 checkCompaction, fixCompaction, runCompaction)
  */
 import { applyRetentionCaps as _applyRetentionCaps } from "../common.js";
-import { compactFile, compactYamlFile, detectOverflow, compactEntries } from "./apply.js";
+import { compactFile, compactYamlBytes, compactYamlFile, detectOverflow, compactEntries, } from "./apply.js";
 import { checkCompaction, computeCompactionStatus, fixCompaction, runCompaction } from "./status.js";
-import { parseEntries, parseFullEntries, parseOnelineEntries, splitArchive, extractResolvedSection, parseTodoResolved, countTodoResolvedEntries, normalizeTodoResolvedLayout, } from "./parse.js";
+import { parseEntries, parseFullEntries, parseOnelineEntries, splitArchive, extractResolvedSection, parseTodoResolved, countTodoResolvedEntries, countTodoResolvedSectionHeadings, countTodoPendingSummarization, normalizeTodoResolvedLayout, TODO_DROPPED_RECOVERY_GUIDANCE, } from "./parse.js";
 import { SPECS, COMPACTABLE_YAML_ARTIFACTS, NON_COMPACTABLE_ARTIFACTS, YAML_SPEC_BY_ARTIFACT, formatTodoOneline } from "./dryRun.js";
-import { overLimitCount, stableSortBy, yamlArchiveEntry, yamlArchiveEntries, yamlRecentFullAndOlder, yamlSortEntries, decisionProtectedOverflowCount, selectDecisionActiveEntries, selectDecisionArchiveEntries, } from "./retention.js";
-export { compactFile, compactYamlFile, detectOverflow, compactEntries, checkCompaction, computeCompactionStatus, fixCompaction, runCompaction, parseEntries, parseFullEntries, parseOnelineEntries, splitArchive, extractResolvedSection, parseTodoResolved, SPECS, COMPACTABLE_YAML_ARTIFACTS, NON_COMPACTABLE_ARTIFACTS, YAML_SPEC_BY_ARTIFACT, formatTodoOneline, countTodoResolvedEntries, normalizeTodoResolvedLayout, overLimitCount, stableSortBy, yamlArchiveEntry, yamlArchiveEntries, yamlRecentFullAndOlder, yamlSortEntries, decisionProtectedOverflowCount, selectDecisionActiveEntries, selectDecisionArchiveEntries, };
+import { overLimitCount, stableSortBy, yamlArchiveEntry, yamlArchiveEntries, yamlRecentFullAndOlder, yamlSortEntries, yamlEntryNumber, decisionProtectedOverflowCount, decisionRequiresUserReview, selectDecisionActiveEntries, selectDecisionArchiveEntries, } from "./retention.js";
+export { compactFile, compactYamlBytes, compactYamlFile, detectOverflow, compactEntries, checkCompaction, computeCompactionStatus, fixCompaction, runCompaction, parseEntries, parseFullEntries, parseOnelineEntries, splitArchive, extractResolvedSection, parseTodoResolved, SPECS, COMPACTABLE_YAML_ARTIFACTS, NON_COMPACTABLE_ARTIFACTS, YAML_SPEC_BY_ARTIFACT, formatTodoOneline, countTodoResolvedEntries, countTodoResolvedSectionHeadings, countTodoPendingSummarization, TODO_DROPPED_RECOVERY_GUIDANCE, normalizeTodoResolvedLayout, overLimitCount, stableSortBy, yamlArchiveEntry, yamlArchiveEntries, yamlRecentFullAndOlder, yamlSortEntries, yamlEntryNumber, decisionProtectedOverflowCount, decisionRequiresUserReview, selectDecisionActiveEntries, selectDecisionArchiveEntries, };
 void _applyRetentionCaps;
-//# sourceMappingURL=index.js.map