agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/hooks/compaction/parse.js

@@ -0,0 +1,325 @@
+/**
+ * Markdown entry parsing for the compaction writer.
+ *
+ * Splits a markdown artifact into "full" and "oneline" entries by
+ * walking the spec's heading regex, then collects the trailing
+ * detail body up to the next heading. The TODO-resolved section
+ * uses indented detail lines as the body delimiter; open items stay
+ * in severity bands and resolved items belong only under
+ * `## ✓ Resolved`.
+ */
+import { parseTodoMarkdownListItem } from "../../cli/todoMarkdown.js";
+import { MAX_FULL_ENTRIES, MAX_TOTAL_ENTRIES } from "../common.js";
+import { SPECS, escapeRe, formatTodoOneline } from "./dryRun.js";
+const SEVERITY_HEADING_RE = /^##\s*(⇶|⇉|→|⇢)\s/m;
+const STRIKETHROUGH_ITEM_RE = /^(\s*)-\s+~~(.+?)~~\s*(.*)$/;
+// Shared case-insensitive resolved-heading matcher. Duplicate detection
+// (countTodoResolvedSectionHeadings), validation (markdown.ts), classification
+// (isTodoResolvedSectionHeading), and extraction (extractResolvedSection) all
+// use these so they accept the same variants: `## ✓ Resolved`, `## Resolved`,
+// `## resolved`, `## RESOLVED`. Formerly extractResolvedSection used `\s+`
+// (requiring a space after ##) without the `i` flag, silently rejecting
+// case variants and `##Resolved`; now unified.
+const TODO_RESOLVED_HEADING_RE = /^##\s*(?:✓\s+)?Resolved\s*$/im;
+const TODO_RESOLVED_HEADING_GLOBAL_RE = /^##\s*(?:✓\s+)?Resolved\s*$/gim;
+// TODO.md is a bounded human-facing queue, not a lossless numbered archive:
+// dropped resolved entries are recoverable only via project history (Git),
+// and only if previously committed. Surfaced in compaction diagnostics
+// alongside the `dropped` count.
+export const TODO_DROPPED_RECOVERY_GUIDANCE = "dropped resolved entries are not retained in a lossless archive; recover previously committed content via Git: `git log -p -- :/TODO.md` (non-Git projects have no historical recovery)";
+export function splitArchive(text, archiveHeading) {
+    if (!archiveHeading)
+        return [text, ""];
+    const pattern = new RegExp(`^${escapeRe(archiveHeading)}\\s*$`, "m");
+    const match = pattern.exec(text);
+    if (!match)
+        return [text, ""];
+    const pre = text.slice(0, match.index).replace(/\s+$/, "");
+    const after = text.slice(match.index + match[0].length);
+    const nextSection = /^##\s/m.exec(after);
+    if (nextSection) {
+        const archiveBody = after.slice(0, nextSection.index);
+        const trailing = after.slice(nextSection.index);
+        return [pre, archiveBody.trim() + (trailing ? "\n\n" + trailing : "")];
+    }
+    return [pre, after.trim()];
+}
+export function parseFullEntries(text, spec) {
+    const entries = [];
+    const re = new RegExp(spec.entryHeadingRe.source, "gm");
+    const matches = [...text.matchAll(re)];
+    for (let i = 0; i < matches.length; i++) {
+        const m = matches[i];
+        const lineStart = text.lastIndexOf("\n", m.index - 1) + 1;
+        let lineEnd = text.indexOf("\n", m.index);
+        if (lineEnd === -1)
+            lineEnd = text.length;
+        const headerLine = text.slice(lineStart, lineEnd).trim();
+        const glyphMatch = /^(■)\s*/.exec(headerLine);
+        const glyph = glyphMatch ? glyphMatch[1] + " " : "";
+        const remainder = glyphMatch ? headerLine.slice(glyphMatch[0].length) : headerLine;
+        const header = glyph + remainder.replace(/^#+/, "").trim();
+        const bodyStart = lineEnd + 1;
+        let bodyEnd;
+        if (i + 1 < matches.length) {
+            bodyEnd = text.lastIndexOf("\n", matches[i + 1].index - 1) + 1;
+        }
+        else {
+            bodyEnd = text.length;
+        }
+        const body = text.slice(bodyStart, bodyEnd).trim();
+        entries.push({ header, body, kind: "full" });
+    }
+    return entries;
+}
+export function parseOnelineEntries(text, spec) {
+    if (spec.onelineHeadingRe === null)
+        return [];
+    const entries = [];
+    const re = new RegExp(spec.onelineHeadingRe.source);
+    for (const line of text.split(/\r\n|\r|\n/)) {
+        if (re.test(line)) {
+            entries.push({ header: line.replace(/\s+$/, ""), body: "", kind: "oneline" });
+        }
+    }
+    return entries;
+}
+export function extractResolvedSection(text) {
+    const m = TODO_RESOLVED_HEADING_RE.exec(text);
+    if (!m)
+        return [-1, -1, ""];
+    const bodyStart = m.index + m[0].length + 1;
+    const nextSection = /^##\s/m.exec(text.slice(bodyStart));
+    const bodyEnd = nextSection ? bodyStart + nextSection.index : text.length;
+    return [m.index, bodyEnd, text.slice(bodyStart, bodyEnd)];
+}
+export function parseTodoResolved(text, spec) {
+    const [, , body] = extractResolvedSection(text);
+    if (!body)
+        return [];
+    const entries = [];
+    const lines = body.split(/\r\n|\r|\n/);
+    const headRe = new RegExp(spec.entryHeadingRe.source);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (headRe.test(line)) {
+            const detailLines = [];
+            let j = i + 1;
+            while (j < lines.length) {
+                const nxt = lines[j];
+                if (nxt.startsWith(" ") || nxt.startsWith("\t")) {
+                    detailLines.push(nxt);
+                    j += 1;
+                }
+                else if (nxt.trim() === "") {
+                    if (j + 1 < lines.length && (lines[j + 1].startsWith(" ") || lines[j + 1].startsWith("\t"))) {
+                        detailLines.push(nxt);
+                        j += 1;
+                    }
+                    else {
+                        break;
+                    }
+                }
+                else {
+                    break;
+                }
+            }
+            const bodyText = detailLines.join("\n").trim();
+            entries.push({ header: line.replace(/\s+$/, ""), body: bodyText, kind: bodyText ? "full" : "oneline" });
+            i = j;
+        }
+        else {
+            i += 1;
+        }
+    }
+    return entries;
+}
+export function isTodoSeveritySectionHeading(line) {
+    return SEVERITY_HEADING_RE.test(line.trim());
+}
+export function isTodoResolvedSectionHeading(line) {
+    return TODO_RESOLVED_HEADING_RE.test(line.trim());
+}
+/**
+ * Count `## ✓ Resolved` section headings in a TODO.md. A well-formed queue has
+ * exactly one; duplicates make parsing silently process only the first and
+ * hide the remaining entries from the compaction budget. Callers (validation,
+ * compaction status, compaction apply) refuse when this returns a value > 1.
+ */
+export function countTodoResolvedSectionHeadings(text) {
+    const matches = text.match(TODO_RESOLVED_HEADING_GLOBAL_RE);
+    return matches ? matches.length : 0;
+}
+export function classifyTodoSectionHeading(line) {
+    if (isTodoSeveritySectionHeading(line))
+        return "severity";
+    if (isTodoResolvedSectionHeading(line))
+        return "resolved";
+    if (/^##\s/.test(line.trim()))
+        return "other";
+    return "other";
+}
+export function strikethroughTodoLineToCheckbox(line) {
+    const m = STRIKETHROUGH_ITEM_RE.exec(line);
+    if (!m)
+        return null;
+    const tail = m[3]?.trim();
+    const body = m[2].trim();
+    return `${m[1]}- [x] ${body}${tail ? (tail.startsWith("·") ? ` ${tail}` : ` ${tail}`) : ""}`;
+}
+export function isLegacyStrikethroughTodoLine(line) {
+    return /^(\s*)-\s+~~/.test(line);
+}
+export function countTodoResolvedInSeverityBands(content) {
+    let count = 0;
+    let section = "other";
+    for (const line of content.split(/\r\n|\r|\n/)) {
+        const kind = classifyTodoSectionHeading(line);
+        if (kind !== "other" || /^##\s/.test(line.trim())) {
+            section = kind;
+            continue;
+        }
+        if (section !== "severity")
+            continue;
+        const trimmed = line.trim();
+        if (!trimmed.startsWith("-"))
+            continue;
+        const parsed = parseTodoMarkdownListItem(trimmed);
+        if (parsed?.status === "resolved" || isLegacyStrikethroughTodoLine(trimmed)) {
+            count += 1;
+        }
+    }
+    return count;
+}
+export function countTodoResolvedEntries(content) {
+    const spec = SPECS["todo-resolved"];
+    const resolvedSection = parseTodoResolved(content, spec);
+    const misplaced = countTodoResolvedInSeverityBands(content);
+    const total = resolvedSection.length + misplaced;
+    // Positional tiering per TC9: the first ten resolved rows are the
+    // recent/full-detail tier even when they have no indented body; rows
+    // 11+ are the summary tier. This keeps status reporting consistent
+    // with how compactTodoEntries assigns tiers (positional, not
+    // body-presence-based), so a compacted file with 10 header-only rows
+    // + 40 summaries reports 10/40 (not 0/50).
+    return {
+        full: Math.min(total, MAX_FULL_ENTRIES),
+        oneline: Math.max(0, total - MAX_FULL_ENTRIES),
+    };
+}
+/**
+ * Count resolved entries in positions 11-50 that need ≤15-word summarization
+ * but are not yet summaries. An entry needs summarization when:
+ *   - it has an indented body (should be stripped), or
+ *   - its kind is "full" (should be demoted to the summary tier), or
+ *   - its header differs from what `formatTodoOneline` would produce (i.e.
+ *     it is a long verbatim header, not a ≤15-word summary).
+ *
+ * Returns 0 when the Resolved section is already compacted (idempotent).
+ * `check compact` uses this to detect in-budget (≤50) TODOs that still need
+ * a formatting rewrite, so `--mode fix` is triggered before entries overflow.
+ */
+export function countTodoPendingSummarization(content) {
+    const spec = SPECS["todo-resolved"];
+    const entries = parseTodoResolved(content, spec);
+    if (entries.length <= MAX_FULL_ENTRIES)
+        return 0;
+    const summaryTier = entries.slice(MAX_FULL_ENTRIES, MAX_TOTAL_ENTRIES);
+    let count = 0;
+    for (const entry of summaryTier) {
+        if (entry.body) {
+            count++;
+            continue;
+        }
+        if (entry.kind === "full") {
+            count++;
+            continue;
+        }
+        // kind=oneline, no body: check if header matches the summary format
+        // by forcing kind="full" through formatTodoOneline (truncation path).
+        const expected = formatTodoOneline({ ...entry, kind: "full" });
+        if (entry.header.trim() !== expected.trim())
+            count++;
+    }
+    return count;
+}
+/**
+ * Move resolved rows from severity bands into `## ✓ Resolved`, creating the
+ * section when absent. Newly migrated rows are prepended (newest-first folds).
+ */
+export function normalizeTodoResolvedLayout(content) {
+    const lines = content.split(/\r\n|\r|\n/);
+    const beforeResolved = [];
+    const migratedResolved = [];
+    const existingResolved = [];
+    const afterResolved = [];
+    let section = "other";
+    let seenResolvedHeading = false;
+    for (const line of lines) {
+        const headingKind = classifyTodoSectionHeading(line);
+        if (headingKind === "resolved") {
+            seenResolvedHeading = true;
+            section = "resolved";
+            continue;
+        }
+        if (headingKind === "severity") {
+            section = "severity";
+            if (!seenResolvedHeading)
+                beforeResolved.push(line);
+            else
+                afterResolved.push(line);
+            continue;
+        }
+        if (/^##\s/.test(line.trim())) {
+            section = "other";
+            if (!seenResolvedHeading)
+                beforeResolved.push(line);
+            else
+                afterResolved.push(line);
+            continue;
+        }
+        const trimmed = line.trim();
+        if (section === "resolved") {
+            if (trimmed)
+                existingResolved.push(line);
+            continue;
+        }
+        if (section === "severity" && trimmed.startsWith("-")) {
+            const converted = strikethroughTodoLineToCheckbox(line) ?? line;
+            const parsed = parseTodoMarkdownListItem(converted.trim());
+            if (parsed?.status === "resolved" || isLegacyStrikethroughTodoLine(trimmed)) {
+                migratedResolved.push(converted.trim());
+                continue;
+            }
+        }
+        if (!seenResolvedHeading)
+            beforeResolved.push(line);
+        else
+            afterResolved.push(line);
+    }
+    if (migratedResolved.length === 0) {
+        return { text: content, changed: false };
+    }
+    const rebuilt = [...beforeResolved];
+    if (rebuilt.length > 0 && rebuilt[rebuilt.length - 1]?.trim() !== "")
+        rebuilt.push("");
+    rebuilt.push("## ✓ Resolved");
+    rebuilt.push(...migratedResolved, ...existingResolved);
+    if (afterResolved.length > 0) {
+        rebuilt.push("");
+        rebuilt.push(...afterResolved);
+    }
+    const text = rebuilt.join("\n").replace(/\n*$/, "\n");
+    return { text, changed: text !== content };
+}
+export function parseEntries(text, specName) {
+    const spec = SPECS[specName];
+    if (spec.name === "todo-resolved") {
+        return parseTodoResolved(text, spec);
+    }
+    const [pre, archiveBody] = splitArchive(text, spec.archiveHeading || "");
+    const fullEntries = parseFullEntries(pre, spec);
+    const onelineEntries = parseOnelineEntries(archiveBody, spec);
+    return [...fullEntries, ...onelineEntries];
+}

package/dist/hooks/compaction/retention.js

@@ -0,0 +1,202 @@
+/**
+ * Retention primitives for compaction: stable sort, recent-vs-older
+ * partitioning, archive sorting, and decision-specific entry
+ * selection (satisfaction-aware). The pure helpers here are reused
+ * by `apply.ts` (which writes the compacted result back to disk)
+ * and by `status.ts` (which counts overflow without writing).
+ */
+import { MAX_FULL_ENTRIES, MAX_ONELINE_ENTRIES, MAX_TOTAL_ENTRIES, applyRetentionCaps } from "../common.js";
+import { truncateWords } from "./dryRun.js";
+export function overLimitCount(activeCount, archiveCount) {
+    const totalCount = activeCount + archiveCount;
+    return Math.max(Math.max(activeCount - MAX_FULL_ENTRIES, 0), Math.max(archiveCount - MAX_ONELINE_ENTRIES, 0), Math.max(totalCount - MAX_TOTAL_ENTRIES, 0));
+}
+export function stableSortBy(arr, key, reverse = false) {
+    return arr
+        .map((x, i) => [x, i])
+        .sort((a, b) => {
+        const ka = key(a[0]);
+        const kb = key(b[0]);
+        let cmp = ka < kb ? -1 : ka > kb ? 1 : 0;
+        if (reverse)
+            cmp = -cmp;
+        return cmp !== 0 ? cmp : a[1] - b[1];
+    })
+        .map(([x]) => x);
+}
+export function yamlEntryNumber(entry) {
+    let summary;
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+        const number = entry.number;
+        if (typeof number === "number" && Number.isInteger(number))
+            return number;
+        if (typeof number === "string" && /^\d+$/.test(number))
+            return parseInt(number, 10);
+        summary = String(entry.summary ?? "");
+    }
+    else {
+        summary = String(entry);
+    }
+    const match = /(?:Cycle|Decision|Audit|Experiment|EXP-)\s*(\d+)/.exec(summary);
+    return match ? parseInt(match[1], 10) : 0;
+}
+function yamlEntryTimestamp(entry) {
+    if (entry && typeof entry === "object" && !Array.isArray(entry)) {
+        return String(entry.timestamp || entry.date || "");
+    }
+    return "";
+}
+function yamlSummaryText(entry, ...fields) {
+    for (const field of fields) {
+        const value = entry[field];
+        if (typeof value === "string" && value.trim()) {
+            return truncateWords(value.trim(), 15);
+        }
+        if (value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0) {
+            return truncateWords(Object.entries(value).map(([k, v]) => `${k}: ${v}`).join(", "), 15);
+        }
+    }
+    return "no summary";
+}
+function isEmptyish(v) {
+    return (v === null ||
+        v === undefined ||
+        v === "" ||
+        (Array.isArray(v) && v.length === 0) ||
+        (typeof v === "object" && v !== null && !Array.isArray(v) && Object.keys(v).length === 0));
+}
+export function yamlArchiveEntry(specName, entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+        return { summary: String(entry) };
+    }
+    const e = entry;
+    if (specName === "progress") {
+        const number = e.number ?? "?";
+        const date = String(e.timestamp ?? "").split(/\s+/)[0] || "";
+        const datePart = date ? ` (${date})` : "";
+        const summary = yamlSummaryText(e, "what", "type");
+        return { summary: `Cycle ${number}${datePart}: ${summary}` };
+    }
+    if (specName === "decisions") {
+        const number = e.number ?? "?";
+        const date = String(e.date ?? "");
+        const datePart = date ? ` (${date})` : "";
+        const choice = yamlSummaryText(e, "choice", "question");
+        const archiveEntry = { summary: `Decision ${number}${datePart}: ${choice}` };
+        for (const field of ["number", "date", "choice", "outcome", "feeds_into", "satisfaction"]) {
+            const value = e[field];
+            if (!isEmptyish(value))
+                archiveEntry[field] = value;
+        }
+        if (!("outcome" in archiveEntry) && !isEmptyish(archiveEntry.choice)) {
+            archiveEntry.outcome = archiveEntry.choice;
+        }
+        return archiveEntry;
+    }
+    if (specName === "health") {
+        const number = e.number ?? "?";
+        const date = String(e.date ?? "");
+        const datePart = date ? ` (${date})` : "";
+        const summary = yamlSummaryText(e, "trajectory", "grades");
+        return { summary: `Audit ${number}${datePart}: ${summary}` };
+    }
+    if (specName === "experiments") {
+        return { number: e.number, summary: yamlSummaryText(e, "conclusion", "label") };
+    }
+    if (specName === "session") {
+        return { timestamp: String(e.timestamp ?? ""), summary: yamlSummaryText(e, "summary") };
+    }
+    return { summary: yamlSummaryText(e, "summary") };
+}
+export function yamlSortEntries(entries, specName) {
+    if (specName === "decisions" || specName === "health" || specName === "experiments") {
+        return stableSortBy(entries, yamlEntryNumber);
+    }
+    if (specName === "session") {
+        return stableSortBy(entries, yamlEntryTimestamp, true);
+    }
+    return stableSortBy(entries, yamlEntryNumber, true);
+}
+export function yamlRecentFullAndOlder(entries, specName, fullCapacity = MAX_FULL_ENTRIES) {
+    const newestFirst = specName === "session"
+        ? stableSortBy(entries, yamlEntryTimestamp, true)
+        : stableSortBy(entries, yamlEntryNumber, true);
+    const recent = newestFirst.slice(0, fullCapacity);
+    const older = newestFirst.slice(fullCapacity);
+    return [yamlSortEntries(recent, specName), older];
+}
+function yamlArchiveSortKey(entry) {
+    const timestamp = yamlEntryTimestamp(entry);
+    if (timestamp)
+        return ["timestamp", timestamp];
+    return ["number", yamlEntryNumber(entry)];
+}
+export function yamlArchiveEntries(entries) {
+    // Sort by (tag, value) descending, mirroring Python tuple comparison.
+    return entries
+        .map((x, i) => [x, i])
+        .sort((a, b) => {
+        const ka = yamlArchiveSortKey(a[0]);
+        const kb = yamlArchiveSortKey(b[0]);
+        let cmp = 0;
+        if (ka[0] !== kb[0])
+            cmp = ka[0] < kb[0] ? -1 : 1;
+        else
+            cmp = ka[1] < kb[1] ? -1 : ka[1] > kb[1] ? 1 : 0;
+        cmp = -cmp;
+        return cmp !== 0 ? cmp : a[1] - b[1];
+    })
+        .map(([x]) => x);
+}
+function decisionSatisfactionState(entry) {
+    if (!entry || typeof entry !== "object")
+        return null;
+    // cast: decision record fields read from parsed decisions.yaml
+    const satisfaction = entry.satisfaction;
+    if (!satisfaction || typeof satisfaction !== "object")
+        return null;
+    const state = satisfaction.state;
+    return typeof state === "string" ? state : null;
+}
+export function decisionRequiresUserReview(entry) {
+    if (!entry || typeof entry !== "object")
+        return true;
+    // cast: decision record fields read from parsed decisions.yaml
+    const satisfaction = entry.satisfaction;
+    if (!satisfaction || typeof satisfaction !== "object")
+        return true;
+    const confirmation = satisfaction.user_confirmation;
+    const confirmedBy = confirmation && typeof confirmation === "object" ? confirmation.confirmed_by : null;
+    const confirmedAt = confirmation && typeof confirmation === "object" ? confirmation.confirmed_at : null;
+    return (decisionSatisfactionState(entry) !== "user_confirmed_satisfied" ||
+        !confirmation ||
+        typeof confirmation !== "object" ||
+        typeof confirmedBy !== "string" ||
+        confirmedBy.trim() === "" ||
+        typeof confirmedAt !== "string" ||
+        confirmedAt.trim() === "");
+}
+export function decisionSatisfiedActiveCount(active) {
+    return active.filter((e) => !decisionRequiresUserReview(e)).length;
+}
+export function decisionProtectedOverflowCount(active, archive) {
+    const protectedActive = active.filter((e) => decisionRequiresUserReview(e)).length;
+    const protectedArchive = archive.filter((e) => decisionRequiresUserReview(e)).length;
+    return Math.max(protectedActive - MAX_FULL_ENTRIES, protectedArchive - MAX_ONELINE_ENTRIES, protectedActive + protectedArchive - MAX_TOTAL_ENTRIES, 0);
+}
+export function selectDecisionActiveEntries(active, fullCapacity = MAX_FULL_ENTRIES) {
+    const protectedEntries = active.filter((e) => decisionRequiresUserReview(e));
+    const satisfied = active.filter((e) => !decisionRequiresUserReview(e));
+    const newestSatisfied = stableSortBy(satisfied, yamlEntryNumber, true);
+    const satisfiedCapacity = Math.max(fullCapacity - protectedEntries.length, 0);
+    const keepSatisfied = newestSatisfied.slice(0, satisfiedCapacity);
+    const compactSatisfied = newestSatisfied.slice(satisfiedCapacity);
+    return [yamlSortEntries([...protectedEntries, ...keepSatisfied], "decisions"), compactSatisfied];
+}
+export function selectDecisionArchiveEntries(archiveCandidates) {
+    // Review pressure is a projection concern, not a write failure. Capacity
+    // selection happens after archive recovery so protected records are never
+    // discarded merely because they are unresolved.
+    return yamlSortEntries(archiveCandidates, "decisions");
+}
+export { applyRetentionCaps };