peaks-loop 4.0.54 → 4.1.1

package/dist/services/comments/comment-hygiene.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Which comments are still worth their bytes to the next reader.
+ *
+ * Two categories are reported as hygiene debt, and they fail in different
+ * directions, so they are kept separate rather than summed into one number:
+ *
+ *   - `dead-reference` — the comment asserts that some file exists by naming a
+ *     path, and that path resolves nowhere the citation is allowed to mean. This
+ *     is checkable, and it is the class that has already cost this repository a
+ *     wrong decision: the header of `src/services/prd/handoff-gate-evidence.ts`
+ *     described a pre-existing "no producer" state in the same voice as the
+ *     current one, a reader took it as fact, and the fix was chased into
+ *     `dist/` instead of the source.
+ *   - `narrative` — the comment is about the work rather than the code: slice
+ *     and rid identifiers, `AC-3`, "F2 of `rid-…`", "this used to claim", "the
+ *     test named above was deleted". Legitimately valuable in a commit message
+ *     or `.peaks/docs/backlog.md`; in a source file it is re-read by every
+ *     later agent, at their token cost, and it rots silently the moment the
+ *     history it summarises moves.
+ *
+ * The narrative rule is a marker list, not a heuristic about length or
+ * sentence shape, precisely because a false positive here is worse than a false
+ * positive on `dead-reference`: a wrong `dead-reference` is visible in a diff as
+ * a removed path, while a wrong `narrative` deletes a reason someone wrote down
+ * on purpose. Every finding carries its matched marker for that reason — an
+ * unattributable finding is one nobody can review, and a rule nobody can review
+ * is a rule that will be widened until it stops mattering.
+ */
+/** Why a comment line was flagged. */
+export type CommentFindingKind = 'dead-reference' | 'narrative';
+export type CommentFinding = {
+    readonly file: string;
+    readonly line: number;
+    readonly kind: CommentFindingKind;
+    /** The path that does not resolve, or the marker that matched. Never prose. */
+    readonly matched: string;
+    readonly text: string;
+};
+/**
+ * Development-process markers. Each entry is a named rule so a report can say
+ * WHICH one fired — the failure mode this whole feature is modelled on is a
+ * refusal that could not name itself (the content scan in
+ * `src/services/memory/project-memory-service/store/atomic-write.ts` answered a
+ * ten-pattern `||` chain with `matchedTerm: null`).
+ *
+ * Order is significant and is the whole attribution: one line reports its FIRST
+ * match, so a specific marker must precede the general one that also fits it.
+ * `F2 of \`rid-…\`` is a finding reference, not a bare rid, and a list ordered
+ * the other way round would blame the wrong rule for every such line.
+ */
+export declare const NARRATIVE_MARKERS: ReadonlyArray<{
+    name: string;
+    pattern: RegExp;
+}>;
+export type CommentScanInput = {
+    /** Repo-relative path, e.g. `src/services/x/y.ts`. */
+    readonly file: string;
+    readonly source: string;
+};
+export type CommentScanOptions = {
+    /** Injected for tests; defaults to nothing-exists so a caller must decide. */
+    readonly exists?: (relPath: string) => boolean;
+    /** True for directories only; defaults to `exists`, which is true for both. */
+    readonly dirExists?: (relDir: string) => boolean;
+    /** Filesystem-only view of the tree, for the installed-package question.
+     *  Defaults to `exists`. */
+    readonly installed?: (relPath: string) => boolean;
+    readonly kinds?: readonly CommentFindingKind[];
+};
+/** Every finding in one file, in line order. */
+export declare function scanComments(input: CommentScanInput, options?: CommentScanOptions): CommentFinding[];
+/** Per-file totals, which is the shape the gate ratchets and the worklist sorts by. */
+export type CommentFileSummary = {
+    readonly file: string;
+    readonly commentLines: number;
+    readonly deadReferences: number;
+    readonly narrative: number;
+};
+export declare function summarize(input: CommentScanInput, findings: readonly CommentFinding[]): CommentFileSummary;

package/dist/services/comments/comment-hygiene.js

@@ -0,0 +1,133 @@
+/**
+ * Which comments are still worth their bytes to the next reader.
+ *
+ * Two categories are reported as hygiene debt, and they fail in different
+ * directions, so they are kept separate rather than summed into one number:
+ *
+ *   - `dead-reference` — the comment asserts that some file exists by naming a
+ *     path, and that path resolves nowhere the citation is allowed to mean. This
+ *     is checkable, and it is the class that has already cost this repository a
+ *     wrong decision: the header of `src/services/prd/handoff-gate-evidence.ts`
+ *     described a pre-existing "no producer" state in the same voice as the
+ *     current one, a reader took it as fact, and the fix was chased into
+ *     `dist/` instead of the source.
+ *   - `narrative` — the comment is about the work rather than the code: slice
+ *     and rid identifiers, `AC-3`, "F2 of `rid-…`", "this used to claim", "the
+ *     test named above was deleted". Legitimately valuable in a commit message
+ *     or `.peaks/docs/backlog.md`; in a source file it is re-read by every
+ *     later agent, at their token cost, and it rots silently the moment the
+ *     history it summarises moves.
+ *
+ * The narrative rule is a marker list, not a heuristic about length or
+ * sentence shape, precisely because a false positive here is worse than a false
+ * positive on `dead-reference`: a wrong `dead-reference` is visible in a diff as
+ * a removed path, while a wrong `narrative` deletes a reason someone wrote down
+ * on purpose. Every finding carries its matched marker for that reason — an
+ * unattributable finding is one nobody can review, and a rule nobody can review
+ * is a rule that will be widened until it stops mattering.
+ */
+import { citationResolves, citations, commentLines } from './comment-citations.js';
+import { isCitationCandidate } from './citation-rules.js';
+/**
+ * Development-process markers. Each entry is a named rule so a report can say
+ * WHICH one fired — the failure mode this whole feature is modelled on is a
+ * refusal that could not name itself (the content scan in
+ * `src/services/memory/project-memory-service/store/atomic-write.ts` answered a
+ * ten-pattern `||` chain with `matchedTerm: null`).
+ *
+ * Order is significant and is the whole attribution: one line reports its FIRST
+ * match, so a specific marker must precede the general one that also fits it.
+ * `F2 of \`rid-…\`` is a finding reference, not a bare rid, and a list ordered
+ * the other way round would blame the wrong rule for every such line.
+ */
+export const NARRATIVE_MARKERS = [
+    { name: 'finding-id', pattern: /\b[DF]\d+\s+of\b/ },
+    { name: 'acceptance-id', pattern: /\bAC-\d+\b/ },
+    {
+        name: 'slice-id',
+        pattern: /\bslice\s+(?:`?)?(?:20\d\d-\d\d-\d\d|rid-|change-|S\d+\b|0\d\d\b)/i
+    },
+    { name: 'change-folder', pattern: /\b20\d\d-\d\d-\d\d-[a-z]+-[a-z-]+/ },
+    { name: 'rid-id', pattern: /\brid-[a-z0-9][a-z0-9._-]*\b/i },
+    {
+        name: 'historical-voice',
+        pattern: /\b(used to (?:say|claim|read|write)|previously (?:named|said)|no longer (?:exists|ships|carries)|which never existed|did not exist)\b/i
+    },
+    { name: 'deleted-test-ref', pattern: /\b(?:tests?|specs?)\b[^.]{0,48}\b(?:was|were) deleted\b/i },
+    {
+        name: 'guard-self-reference',
+        pattern: /\bthis (?:comment|header|paragraph|note) (?:says|claimed|documents|is )/i
+    }
+];
+function deadReferenceFindings(entry, judge) {
+    const ctx = { file: judge.file, dirExists: judge.dirExists };
+    const out = [];
+    for (const citation of citations(entry.text)) {
+        if (!isCitationCandidate(citation, entry.text, ctx))
+            continue;
+        if (citationResolves(citation.span, judge.file, judge.exists, judge.installed))
+            continue;
+        out.push({
+            file: judge.file,
+            line: entry.line,
+            kind: 'dead-reference',
+            matched: citation.span,
+            text: entry.text.trim()
+        });
+    }
+    return out;
+}
+/**
+ * One line, both readings. A line reports at most ONE narrative marker — its
+ * first — because the list is ordered specific-before-general, and a line that
+ * named every rule it matches would multiply the count without naming anything
+ * a reader could not already see.
+ */
+function classifyLine(entry, judge) {
+    const out = judge.kinds.has('dead-reference')
+        ? deadReferenceFindings(entry, judge)
+        : [];
+    if (!judge.kinds.has('narrative'))
+        return out;
+    for (const marker of NARRATIVE_MARKERS) {
+        const hit = marker.pattern.exec(entry.text);
+        if (hit === null)
+            continue;
+        out.push({
+            file: judge.file,
+            line: entry.line,
+            kind: 'narrative',
+            matched: `${marker.name}:${hit[0].trim()}`,
+            text: entry.text.trim()
+        });
+        break;
+    }
+    return out;
+}
+/** Every finding in one file, in line order. */
+export function scanComments(input, options = {}) {
+    const exists = options.exists ?? (() => false);
+    const judge = {
+        file: input.file,
+        exists,
+        installed: options.installed ?? exists,
+        dirExists: options.dirExists ?? exists,
+        kinds: new Set(options.kinds ?? ['dead-reference', 'narrative'])
+    };
+    const out = [];
+    for (const entry of commentLines(input.source)) {
+        out.push(...classifyLine(entry, judge));
+    }
+    return out;
+}
+function countKind(findings, kind) {
+    return findings.filter((finding) => finding.kind === kind).length;
+}
+export function summarize(input, findings) {
+    return {
+        file: input.file,
+        commentLines: commentLines(input.source).length,
+        deadReferences: countKind(findings, 'dead-reference'),
+        narrative: countKind(findings, 'narrative')
+    };
+}

package/dist/services/comments/comment-prune.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Remove the comments the scan says are debt — and prove nothing else moved.
+ *
+ * The actuator is the dangerous half of this feature: a classifier that is 86%
+ * precise only misinforms, but a pruner that is 86% precise deletes. So the
+ * deliverable here is not the deletion, it is the PROOF, and the proof is a
+ * structural check run on every file before it is written:
+ *
+ *   - the diff is computed line-by-line against the plan, so a changed line that
+ *     the scan never named is a violation, not a surprise;
+ *   - every removed line must be a comment line, and a stripped trailing comment
+ *     must leave its code byte-identical;
+ *   - a line that carries a block-comment delimiter opening or closing ELSEWHERE
+ *     is never removed, because deleting it would turn the rest of the comment into
+ *     code — the one failure mode that makes this a compile error rather than a
+ *     lost sentence;
+ *   - a file whose line endings are mixed is left alone, since re-joining it would
+ *     rewrite every line and the proof would stop meaning anything.
+ *
+ * Anything that fails the check is reported and NOT written. The ledger records
+ * every line removed, with the rule that fired, so a prune is reviewable after the
+ * fact instead of only before it.
+ */
+import type { CommentFinding, CommentFindingKind } from './comment-hygiene.js';
+/** What the pruner will do to one line. */
+export type PruneAction = {
+    readonly file: string;
+    readonly line: number;
+    readonly kind: CommentFindingKind;
+    readonly matched: string;
+    /** `drop-line` deletes the whole comment line; `strip-trailing` keeps the code. */
+    readonly mode: 'drop-line' | 'strip-trailing';
+    /** The full text of the line as it sits on disk right now. */
+    readonly lineText: string;
+    /** The comment as the SCAN saw it — for a trailing comment, not the whole line. */
+    readonly comment: string;
+};
+/** A finding the pruner refused to act on, with the reason. */
+export type PruneSkip = {
+    readonly file: string;
+    readonly line: number;
+    readonly reason: string;
+    readonly text: string;
+};
+export type PruneOptions = {
+    readonly projectRoot: string;
+    /** Narrow to one category; the default is both, which is the accepted boundary. */
+    readonly kinds?: readonly CommentFindingKind[];
+    /** Restrict to one file, repo-relative — how a single-case proof is run. */
+    readonly onlyFile?: string;
+    /** Write the files. False (the default) plans and proves without touching disk. */
+    readonly apply?: boolean;
+};
+export type PruneResult = {
+    readonly scannedFiles: number;
+    readonly planned: number;
+    readonly dropped: number;
+    readonly stripped: number;
+    readonly skipped: number;
+    readonly touchedFiles: readonly string[];
+    readonly notWritten: readonly string[];
+    readonly ledgerPath: string;
+    readonly actions: readonly PruneAction[];
+    readonly skips: readonly PruneSkip[];
+    readonly applied: boolean;
+};
+/**
+ * Decide the fate of every finding.
+ *
+ * The line is re-read here and passed back through `commentLines`, the scan's own
+ * extractor, rather than compared against the whole line: a trailing comment's
+ * recorded text is the comment, not the code before it, and an equality test on the
+ * raw line would reject every one of them. Re-using the extractor is what makes the
+ * plan and the scan agree BY CONSTRUCTION instead of by two copies of a rule — the
+ * defect class this whole feature is a reply to.
+ */
+export declare function planPrune(options: PruneOptions, findings: readonly CommentFinding[]): {
+    actions: PruneAction[];
+    skips: PruneSkip[];
+};
+/**
+ * Plan, prove, and (on `apply`) write.
+ *
+ * The scan runs through `auditComments`, so a pruned line is one the worklist
+ * already showed a human; the pruner adds no rule of its own about what counts as
+ * debt.
+ */
+export declare function pruneComments(options: PruneOptions): PruneResult;

package/dist/services/comments/comment-prune.js

@@ -0,0 +1,148 @@
+/**
+ * Remove the comments the scan says are debt — and prove nothing else moved.
+ *
+ * The actuator is the dangerous half of this feature: a classifier that is 86%
+ * precise only misinforms, but a pruner that is 86% precise deletes. So the
+ * deliverable here is not the deletion, it is the PROOF, and the proof is a
+ * structural check run on every file before it is written:
+ *
+ *   - the diff is computed line-by-line against the plan, so a changed line that
+ *     the scan never named is a violation, not a surprise;
+ *   - every removed line must be a comment line, and a stripped trailing comment
+ *     must leave its code byte-identical;
+ *   - a line that carries a block-comment delimiter opening or closing ELSEWHERE
+ *     is never removed, because deleting it would turn the rest of the comment into
+ *     code — the one failure mode that makes this a compile error rather than a
+ *     lost sentence;
+ *   - a file whose line endings are mixed is left alone, since re-joining it would
+ *     rewrite every line and the proof would stop meaning anything.
+ *
+ * Anything that fails the check is reported and NOT written. The ledger records
+ * every line removed, with the rule that fired, so a prune is reviewable after the
+ * fact instead of only before it.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { getSessionId } from '../session/session-manager.js';
+import { auditComments } from './comment-audit.js';
+import { commentLines } from './comment-citations.js';
+import { actionsByFile, executePlan, readFileSafe, splitLines } from './prune-apply.js';
+const FULL_LINE_PREFIXES = ['//', '/*', '/**', '*'];
+function isFullLineComment(text) {
+    const trimmed = text.trim();
+    return FULL_LINE_PREFIXES.some((prefix) => trimmed.startsWith(prefix));
+}
+/**
+ * Can this line be deleted without breaking the syntax around it?
+ *
+ * A line that OPENS a block (`/* …` with no close on the same line) or CLOSES one
+ * (a bare `* /`) is load-bearing for the comment's extent, not for its prose.
+ * Removing it leaves the remainder of the block as code — a compile error is the
+ * mildest thing that follows. Checked for both modes, because the strip below also
+ * cuts text out of a line: a code line carrying an unterminated `/*` would have its
+ * "trailing comment" extracted from inside the block, and cutting there is a syntax
+ * edit, not a comment edit.
+ */
+function removalWouldBreakTheComment(text) {
+    const opens = text.includes('/*');
+    const closes = text.includes('*/');
+    return opens !== closes;
+}
+function actionFor(finding, text, comment) {
+    return {
+        file: finding.file,
+        line: finding.line,
+        kind: finding.kind,
+        matched: finding.matched,
+        mode: isFullLineComment(text) ? 'drop-line' : 'strip-trailing',
+        lineText: text,
+        comment
+    };
+}
+function skipFor(finding, reason) {
+    return { file: finding.file, line: finding.line, reason, text: finding.text };
+}
+/**
+ * Decide the fate of every finding.
+ *
+ * The line is re-read here and passed back through `commentLines`, the scan's own
+ * extractor, rather than compared against the whole line: a trailing comment's
+ * recorded text is the comment, not the code before it, and an equality test on the
+ * raw line would reject every one of them. Re-using the extractor is what makes the
+ * plan and the scan agree BY CONSTRUCTION instead of by two copies of a rule — the
+ * defect class this whole feature is a reply to.
+ */
+export function planPrune(options, findings) {
+    const actions = [];
+    const skips = [];
+    for (const finding of findings) {
+        const source = readFileSafe(options.projectRoot, finding.file);
+        if (source === null) {
+            skips.push(skipFor(finding, 'file-not-readable'));
+            continue;
+        }
+        const text = splitLines(source).lines[finding.line - 1] ?? '';
+        const comment = commentLines(text)[0]?.text ?? '';
+        if (comment.trim() !== finding.text) {
+            skips.push(skipFor(finding, 'line-moved-since-scan'));
+            continue;
+        }
+        if (removalWouldBreakTheComment(text)) {
+            skips.push(skipFor(finding, 'carries-a-block-delimiter'));
+            continue;
+        }
+        actions.push(actionFor(finding, text, comment));
+    }
+    return { actions, skips };
+}
+function ledgerPathFor(projectRoot, stamp) {
+    const sessionId = getSessionId(projectRoot) ?? '_nonsession';
+    const dir = join(getSessionDir(projectRoot, sessionId), 'comments');
+    mkdirSync(dir, { recursive: true });
+    return join(dir, `prune-${stamp}.json`);
+}
+/**
+ * Plan, prove, and (on `apply`) write.
+ *
+ * The scan runs through `auditComments`, so a pruned line is one the worklist
+ * already showed a human; the pruner adds no rule of its own about what counts as
+ * debt.
+ */
+export function pruneComments(options) {
+    const kinds = options.kinds ?? ['dead-reference', 'narrative'];
+    const audit = auditComments({ projectRoot: options.projectRoot });
+    const inScope = audit.findings.filter((finding) => kinds.includes(finding.kind) &&
+        (options.onlyFile === undefined || finding.file === options.onlyFile));
+    const { actions, skips } = planPrune(options, inScope);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const ledgerPath = ledgerPathFor(options.projectRoot, stamp);
+    const outcome = executePlan(options.projectRoot, actionsByFile(actions), options.apply === true);
+    const skipsAll = [...skips, ...outcome.fileSkips];
+    // Written on a dry run too: the plan IS the reviewable artifact, and a reviewer
+    // who only sees stdout has nothing to diff a later apply against.
+    writeFileSync(ledgerPath, `${JSON.stringify({
+        projectRoot: options.projectRoot,
+        at: new Date().toISOString(),
+        applied: options.apply === true,
+        kinds,
+        onlyFile: options.onlyFile ?? null,
+        removed: actions,
+        skipped: skipsAll,
+        touchedFiles: outcome.touched,
+        notWritten: outcome.notWritten
+    }, null, 2)}\n`);
+    return {
+        scannedFiles: audit.scannedFiles,
+        planned: actions.length,
+        dropped: actions.filter((action) => action.mode === 'drop-line').length,
+        stripped: actions.filter((action) => action.mode === 'strip-trailing').length,
+        skipped: skipsAll.length,
+        touchedFiles: outcome.touched,
+        notWritten: outcome.notWritten,
+        ledgerPath,
+        actions,
+        skips: skipsAll,
+        applied: options.apply === true
+    };
+}

package/dist/services/comments/prune-apply.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The line mechanics of a comment prune, and the proof that gates every write.
+ *
+ * Split from `comment-prune.ts` because the two change for different reasons: that
+ * module decides WHAT is debt (and follows the classifier), this one decides how a
+ * line is removed from a file without damaging the file (and follows the language).
+ * Keeping them apart is also what lets the proof be tested on a text array, with no
+ * filesystem and no scan in the room.
+ */
+import type { PruneAction, PruneSkip } from './comment-prune.js';
+/** What the write phase decided, per file. */
+export type WriteOutcome = {
+    touched: string[];
+    notWritten: string[];
+    fileSkips: PruneSkip[];
+};
+/**
+ * Read a file, or report that it is not there — a prune never creates one.
+ *
+ * `existsSync` first, and NO catch: a `catch { return null }` answers "present but
+ * unreadable" (permissions, a locked handle, a directory named as a file) with the same
+ * `null` as "absent", and that conflation is the defect this repository already
+ * ratchets under `silentWarningCatchReturnNull` — this very helper was counted by it.
+ * An absent path is a state the caller handles; an unreadable one should be a crash an
+ * operator sees.
+ */
+export declare function readFileSafe(root: string, rel: string): string | null;
+/**
+ * Split a source into lines, remembering what separated them.
+ *
+ * `mixed` is the signal to leave a file alone rather than a detail to paper over: a
+ * file with both CRLF and LF endings cannot be re-joined from one delimiter without
+ * rewriting every line, and a rewrite of every line is not a comment edit — it would
+ * also make the proof below vacuous, because all the lines would differ.
+ */
+export declare function splitLines(source: string): {
+    lines: string[];
+    eol: string;
+    mixed: boolean;
+};
+/** Group a plan by file, in first-seen order. */
+export declare function actionsByFile(actions: readonly PruneAction[]): Map<string, PruneAction[]>;
+/**
+ * The proof, as data: compare kept lines against the original.
+ *
+ * One string per violation; empty means every difference between the two texts is a
+ * line this plan named, and every line it named that was kept is byte-identical to
+ * what was there before. This is computed whether or not the caller intends to write,
+ * so a dry run reports the refusals a real run would hit.
+ */
+export declare function proofViolations(before: readonly string[], after: readonly string[], actions: readonly PruneAction[]): string[];
+/** Apply one file's actions to its lines, in the plan's own terms. */
+export declare function pruneFileLines(lines: readonly string[], actions: readonly PruneAction[]): string[];
+/**
+ * Run the proof on every planned file, and write only the files that passed it.
+ *
+ * A file that fails is reported and left alone — never written "mostly", because a
+ * partially-pruned file is exactly the state the proof exists to make unreachable.
+ */
+export declare function executePlan(projectRoot: string, byFile: Map<string, PruneAction[]>, apply: boolean): WriteOutcome;

package/dist/services/comments/prune-apply.js

@@ -0,0 +1,150 @@
+/**
+ * The line mechanics of a comment prune, and the proof that gates every write.
+ *
+ * Split from `comment-prune.ts` because the two change for different reasons: that
+ * module decides WHAT is debt (and follows the classifier), this one decides how a
+ * line is removed from a file without damaging the file (and follows the language).
+ * Keeping them apart is also what lets the proof be tested on a text array, with no
+ * filesystem and no scan in the room.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Read a file, or report that it is not there — a prune never creates one.
+ *
+ * `existsSync` first, and NO catch: a `catch { return null }` answers "present but
+ * unreadable" (permissions, a locked handle, a directory named as a file) with the same
+ * `null` as "absent", and that conflation is the defect this repository already
+ * ratchets under `silentWarningCatchReturnNull` — this very helper was counted by it.
+ * An absent path is a state the caller handles; an unreadable one should be a crash an
+ * operator sees.
+ */
+export function readFileSafe(root, rel) {
+    const abs = join(root, rel);
+    return existsSync(abs) ? readFileSync(abs, 'utf8') : null;
+}
+/**
+ * Split a source into lines, remembering what separated them.
+ *
+ * `mixed` is the signal to leave a file alone rather than a detail to paper over: a
+ * file with both CRLF and LF endings cannot be re-joined from one delimiter without
+ * rewriting every line, and a rewrite of every line is not a comment edit — it would
+ * also make the proof below vacuous, because all the lines would differ.
+ */
+export function splitLines(source) {
+    const crlf = source.includes('\r\n');
+    const lfOnly = /\n(?!\r)/.test(source.replace(/\r\n/g, '\n')) || /\n[^\r]/.test(source);
+    return {
+        lines: source.split(/\r?\n/),
+        eol: crlf ? '\r\n' : '\n',
+        mixed: crlf && lfOnly
+    };
+}
+/** Group a plan by file, in first-seen order. */
+export function actionsByFile(actions) {
+    const byFile = new Map();
+    for (const action of actions) {
+        const list = byFile.get(action.file);
+        if (list === undefined)
+            byFile.set(action.file, [action]);
+        else
+            list.push(action);
+    }
+    return byFile;
+}
+/**
+ * The proof, as data: compare kept lines against the original.
+ *
+ * One string per violation; empty means every difference between the two texts is a
+ * line this plan named, and every line it named that was kept is byte-identical to
+ * what was there before. This is computed whether or not the caller intends to write,
+ * so a dry run reports the refusals a real run would hit.
+ */
+export function proofViolations(before, after, actions) {
+    const dropped = new Set(actions.filter((a) => a.mode === 'drop-line').map((a) => a.line));
+    const stripped = new Set(actions.filter((a) => a.mode === 'strip-trailing').map((a) => a.line));
+    const violations = [];
+    let afterAt = 0;
+    before.forEach((original, index) => {
+        const line = index + 1;
+        if (dropped.has(line))
+            return; // deleted on purpose
+        if (stripped.has(line)) {
+            // The only thing a strip may do is reveal the code that was already there, so
+            // what survives must be a PREFIX of the original line — that is what makes it a
+            // comment edit, and anything else is a code edit wearing its clothes.
+            const kept = after[afterAt] ?? '';
+            afterAt += 1;
+            if (!original.startsWith(kept))
+                violations.push(`line ${line}: code text changed`);
+            return;
+        }
+        if (after[afterAt] !== original)
+            violations.push(`line ${line}: untouched line differs`);
+        afterAt += 1;
+    });
+    if (afterAt !== after.length)
+        violations.push(`produced ${after.length - afterAt} extra line(s)`);
+    return violations;
+}
+/** Apply one file's actions to its lines, in the plan's own terms. */
+export function pruneFileLines(lines, actions) {
+    const drop = new Set(actions.filter((a) => a.mode === 'drop-line').map((a) => a.line));
+    const strip = new Map(actions.filter((a) => a.mode === 'strip-trailing').map((a) => [a.line, a.comment]));
+    const out = [];
+    lines.forEach((original, index) => {
+        const line = index + 1;
+        if (drop.has(line))
+            return;
+        if (strip.has(line)) {
+            // Cut where the scan's comment text starts, not at the first `//` in the line:
+            // `const url = "https://example.com"; // Slice 1 kept it` has its `//` inside a
+            // string literal, and slicing there would delete code.
+            const comment = strip.get(line) ?? '';
+            const at = original.indexOf(comment);
+            out.push(at > 0 ? original.slice(0, at).trimEnd() : comment.trimEnd());
+            return;
+        }
+        out.push(original);
+    });
+    return out;
+}
+/**
+ * Run the proof on every planned file, and write only the files that passed it.
+ *
+ * A file that fails is reported and left alone — never written "mostly", because a
+ * partially-pruned file is exactly the state the proof exists to make unreachable.
+ */
+export function executePlan(projectRoot, byFile, apply) {
+    const touched = [];
+    const notWritten = [];
+    const fileSkips = [];
+    for (const [file, fileActions] of byFile) {
+        const source = readFileSafe(projectRoot, file);
+        if (source === null) {
+            notWritten.push(file);
+            continue;
+        }
+        const parts = splitLines(source);
+        if (parts.mixed) {
+            fileSkips.push({
+                file,
+                line: 0,
+                reason: 'mixed-line-endings',
+                text: `${parts.lines.length} line(s) left untouched`
+            });
+            notWritten.push(file);
+            continue;
+        }
+        const after = pruneFileLines(parts.lines, fileActions);
+        const violations = proofViolations(parts.lines, after, fileActions);
+        if (violations.length > 0) {
+            notWritten.push(`${file} (${violations[0]})`);
+            continue;
+        }
+        touched.push(file);
+        if (apply)
+            writeFileSync(join(projectRoot, file), after.join(parts.eol));
+    }
+    return { touched, notWritten, fileSkips };
+}