peaks-loop 4.1.0 → 4.1.2

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

@@ -0,0 +1,66 @@
+/**
+ * Comment-only views of a source file, and whether a citation it makes holds.
+ *
+ * The shape and candidate rules live in `citation-rules.ts`, shared with the
+ * repository's citation guard; this module holds the two things that rule needs in
+ * order to be applied: the comment lines of a file, and the probes that answer
+ * "does this path resolve here".
+ *
+ * Deliberately NOT `ts.getLeadingCommentRanges`:
+ * `src/services/qa/bdd-test-style-verifier.ts` records that the API returns zero
+ * ranges for comment-only blocks, which would silently read a header comment as no
+ * comment at all. The spans come from `comment-spans.ts` instead, which keeps both
+ * order and line numbers — what the worklist and the prune both need — and knows
+ * what character it is inside, which a per-line rule cannot.
+ */
+import { type Citation } from './citation-rules.js';
+/** One source line, with its 1-based number, as the classifier sees it. */
+export type CommentLine = {
+    readonly line: number;
+    readonly text: string;
+};
+/**
+ * The comment lines of a file: full-line comments, plus the trailing comment of a
+ * code line. Non-comment lines are omitted but their numbers survive, so a report
+ * can point at the code a comment is attached to.
+ *
+ * Derived from `commentSpans`, which reads the text as a stream. The previous version
+ * decided per line and was wrong in both directions at once: a `//` inside a template
+ * literal became a comment (and then a deletion that cut the literal open), while a
+ * block comment's interior line that does not start with `*` was missed.
+ */
+export declare function commentLines(source: string): CommentLine[];
+/**
+ * The path-shaped backtick spans in a line, in order, with their bounds kept.
+ *
+ * The bounds are not decoration: two of the candidate rules read the text OUTSIDE
+ * the span — an illustration cue sits immediately before it, a `<…>` fill-in wraps
+ * it — so a caller that discards positions cannot apply them.
+ */
+export declare function citations(text: string): Citation[];
+/** Every path-shaped span in a line, without its bounds. */
+export declare function citedPaths(text: string): string[];
+/**
+ * The workspace package a citing file belongs to, or null at the repository root.
+ *
+ * In a pnpm workspace, `src/x.ts` written inside `packages/<name>/src/` names that
+ * package's own file, not a repository-root one: three comments in this repository cite
+ * `packages/peaks-loop-internal-runtime/src/status-protocol.ts` and
+ * `packages/peaks-loop-shared-channel/src/index.ts` by their package-relative spelling,
+ * and both files exist. Treating those as dead references would seed a ratchet with
+ * findings that refuse the next honest package-internal citation, so the package root is
+ * an origin — for a citing file that is itself inside a package, and never for a
+ * top-level one.
+ */
+export declare function packageRootOf(citingFileRel: string): string | null;
+/**
+ * Does this path-shaped citation resolve anywhere it is allowed to resolve?
+ *
+ * `installed` must be a filesystem-only probe, not the ignore-widened one:
+ * `node_modules` is itself in `.gitignore`, so an ignore-aware answer here is
+ * "yes, installed" for every first segment, and the whole dead-reference count
+ * collapses to zero while looking perfectly healthy. Measured, not theorised.
+ */
+export declare function citationResolves(citation: string, citingFileRel: string, exists: (relPath: string) => boolean, installed?: (relPath: string) => boolean): boolean;
+/** The default existence probe, against a real working tree. */
+export declare function treeExists(repoRoot: string): (relPath: string) => boolean;

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

@@ -0,0 +1,184 @@
+/**
+ * Comment-only views of a source file, and whether a citation it makes holds.
+ *
+ * The shape and candidate rules live in `citation-rules.ts`, shared with the
+ * repository's citation guard; this module holds the two things that rule needs in
+ * order to be applied: the comment lines of a file, and the probes that answer
+ * "does this path resolve here".
+ *
+ * Deliberately NOT `ts.getLeadingCommentRanges`:
+ * `src/services/qa/bdd-test-style-verifier.ts` records that the API returns zero
+ * ranges for comment-only blocks, which would silently read a header comment as no
+ * comment at all. The spans come from `comment-spans.ts` instead, which keeps both
+ * order and line numbers — what the worklist and the prune both need — and knows
+ * what character it is inside, which a per-line rule cannot.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LINE_SUFFIX, PATH_SHAPED, REPO_ANCHORS, SESSION_WORKSPACE_DIRS, SYNTHETIC_SEGMENT } from './citation-rules.js';
+import { commentSpans } from './comment-spans.js';
+/** Repo-relative paths are POSIX even on a Windows host, or every lookup below
+ *  compares a `src\a.ts` against the forward-slash keys and the answer is always "no". */
+function toPosix(path) {
+    return path.replace(/\\/g, '/');
+}
+/**
+ * The comment lines of a file: full-line comments, plus the trailing comment of a
+ * code line. Non-comment lines are omitted but their numbers survive, so a report
+ * can point at the code a comment is attached to.
+ *
+ * Derived from `commentSpans`, which reads the text as a stream. The previous version
+ * decided per line and was wrong in both directions at once: a `//` inside a template
+ * literal became a comment (and then a deletion that cut the literal open), while a
+ * block comment's interior line that does not start with `*` was missed.
+ */
+export function commentLines(source) {
+    const out = [];
+    const rows = source.split(/\r?\n/);
+    for (const span of commentSpans(source)) {
+        for (let line = span.line; line <= span.endLine; line += 1) {
+            const row = rows[line - 1];
+            if (row === undefined)
+                continue;
+            // The first line of a block comment that opens mid-code keeps only its own tail,
+            // so a caller never reads the code before `/*` as part of the comment.
+            const from = line === span.line ? span.start - lineStart(source, line) : 0;
+            out.push({ line, text: row.slice(Math.max(0, from)) });
+        }
+    }
+    return out;
+}
+/** The offset `source` has advanced by the start of 1-based `line`. */
+function lineStart(source, line) {
+    let at = 0;
+    for (let n = 1; n < line; n += 1) {
+        const next = source.indexOf('\n', at);
+        if (next < 0)
+            return source.length;
+        at = next + 1;
+    }
+    return at;
+}
+/**
+ * The path-shaped backtick spans in a line, in order, with their bounds kept.
+ *
+ * The bounds are not decoration: two of the candidate rules read the text OUTSIDE
+ * the span — an illustration cue sits immediately before it, a `<…>` fill-in wraps
+ * it — so a caller that discards positions cannot apply them.
+ */
+export function citations(text) {
+    const found = [];
+    for (const match of text.matchAll(/`([^`\s]+)`/g)) {
+        const span = match[1] ?? '';
+        const from = match.index ?? 0;
+        if (PATH_SHAPED.test(span)) {
+            found.push({ span, from, to: from + span.length + 2 });
+        }
+    }
+    return found;
+}
+/** Every path-shaped span in a line, without its bounds. */
+export function citedPaths(text) {
+    return citations(text).map((citation) => citation.span);
+}
+/**
+ * Is this span a module specifier rather than a repo path? `peaks-loop-shared/result`
+ * in prose names an import, and no rule about files applies to it. Decided through
+ * the dependency tree instead of an allowlist: the first segment is checked against
+ * installed packages, so a new dependency needs no edit here. An allowlist of
+ * today's package names would turn every future one into a false finding — and a
+ * rule that is wrong the moment the repository grows is a rule that gets widened
+ * until it stops meaning anything.
+ */
+function isInstalledPackageName(head, second, installed) {
+    const name = head.startsWith('@') && second !== undefined ? `${head}/${second}` : head;
+    return installed(`node_modules/${name}`);
+}
+/**
+ * The two shapes a citation may clear without touching the tree: an installed
+ * package's module specifier, and a session-runtime dir abbreviated in prose.
+ */
+function resolvesOutsideTheTree(stripped, exists, installed) {
+    const [head, second] = stripped.split('/');
+    if (head === undefined)
+        return false;
+    if (isInstalledPackageName(head, second, installed))
+        return true;
+    return SESSION_WORKSPACE_DIRS.has(head) && !REPO_ANCHORS.test(stripped);
+}
+/**
+ * The workspace package a citing file belongs to, or null at the repository root.
+ *
+ * In a pnpm workspace, `src/x.ts` written inside `packages/<name>/src/` names that
+ * package's own file, not a repository-root one: three comments in this repository cite
+ * `packages/peaks-loop-internal-runtime/src/status-protocol.ts` and
+ * `packages/peaks-loop-shared-channel/src/index.ts` by their package-relative spelling,
+ * and both files exist. Treating those as dead references would seed a ratchet with
+ * findings that refuse the next honest package-internal citation, so the package root is
+ * an origin — for a citing file that is itself inside a package, and never for a
+ * top-level one.
+ */
+export function packageRootOf(citingFileRel) {
+    const segments = citingFileRel.split('/');
+    if (segments[0] !== 'packages' || segments[1] === undefined)
+        return null;
+    return `packages/${segments[1]}`;
+}
+/**
+ * Does the citation point at a file inside the citing file's OWN workspace package?
+ *
+ * `join` is POSIX-normalised on the way through, because a `packages\alpha/src/x.ts`
+ * key matches nothing on the host this repository is developed on.
+ */
+function resolvesInOwnPackage(stripped, citingFileRel, exists) {
+    const pkg = packageRootOf(citingFileRel);
+    return pkg !== null && exists(toPosix(join(pkg, stripped)));
+}
+/**
+ * The two origins a repo-anchored citation may be satisfied at: the repository root,
+ * or the workspace package the citing file itself lives in.
+ *
+ * Extracted because `citationResolves` is at the complexity ceiling the shipped rule
+ * sets, and an inlined `||` there would have been the second branch this file cannot
+ * afford — a limit that forces a helper out is the limit working, not the limit being
+ * in the way.
+ */
+function resolvesAtARootOrigin(stripped, citingFileRel, exists) {
+    return exists(stripped) || resolvesInOwnPackage(stripped, citingFileRel, exists);
+}
+/**
+ * Does this path-shaped citation resolve anywhere it is allowed to resolve?
+ *
+ * `installed` must be a filesystem-only probe, not the ignore-widened one:
+ * `node_modules` is itself in `.gitignore`, so an ignore-aware answer here is
+ * "yes, installed" for every first segment, and the whole dead-reference count
+ * collapses to zero while looking perfectly healthy. Measured, not theorised.
+ */
+export function citationResolves(citation, citingFileRel, exists, installed = exists) {
+    const stripped = citation.replace(LINE_SUFFIX, '');
+    if (stripped.length === 0 || SYNTHETIC_SEGMENT.test(stripped))
+        return true;
+    if (resolvesOutsideTheTree(stripped, exists, installed))
+        return true;
+    if (resolvesAtARootOrigin(stripped, citingFileRel, exists))
+        return true;
+    // An anchored citation claims the repo root and nowhere else; anything that did
+    // not resolve above is dead.
+    if (REPO_ANCHORS.test(stripped))
+        return false;
+    // No repo anchor: read from the citing file's own directory and each ancestor
+    // below the repo root, which is where a sibling reference (a subdirectory path
+    // written by the file sitting next to it) actually points.
+    for (let dir = dirname(citingFileRel); dir.length > 0 && dir !== dirname(dir);) {
+        if (exists(toPosix(join(dir, stripped))))
+            return true;
+        dir = dirname(dir);
+        if (dir === '.')
+            return false;
+    }
+    return false;
+}
+/** The default existence probe, against a real working tree. */
+export function treeExists(repoRoot) {
+    return (relPath) => existsSync(join(repoRoot, relPath));
+}

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

@@ -0,0 +1,105 @@
+/**
+ * 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
+ *     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.
+ * the other way round would blame the wrong rule for every such line.
+ */
+export declare const NARRATIVE_MARKERS: ReadonlyArray<{
+    name: string;
+    pattern: RegExp;
+}>;
+/**
+ * Comments that are LOAD-BEARING: text some program parses as data, not prose it reads.
+ *
+ * These are exempt from BOTH kinds, because the prune acts on a finding of either kind and
+ * deleting any of them does not reduce debt — it removes an enforcement mechanism, or
+ * adds a finding to a gated row. Each shape names the reader that consumes it; a shape
+ * with no reader to point at is a guess, and guesses are what the 4.1.1 prune learned from
+ * `HARD_FLOOR_CATEGORIES` member in `src/services/code/mode-gate.ts`, which is the only
+ * thing backing this repo's one real layer-C promotion, and the gate-H backing check went
+ * red — `feedback-promotion-artifact.test.ts` AC5).
+ *
+ *   - `promotion-evidence` — `src/services/feedback/promotion-source-comments.ts:79`
+ *     (`citedMemories`) feeds `promotion-artifact-evidence.ts:214`, which decides whether a
+ *     promoted rule is actually backed.
+ *   - `grace-marker` — `scripts/lint/silent-warning-detector.mjs:149` subtracts a
+ *     silent-warning finding for any line the offending node spans that carries
+ *     `TODO(g2)`. Deleting the marker therefore RAISES `silentWarningCatchReturnNull` /
+ *     `…EmptyCatch`, both of which may only go down.
+ *   - `toolchain-directive` — `@ts-expect-error` and friends are read by the compiler (an
+ *     unused one is itself an error) and `eslint-disable` by the lint leg; a paired disable
+ *     like `src/services/compact-statusline/compact-statusline-cell-table.ts:72`+`:99`
+ *     must move as a pair or the file starts reporting.
+ */
+export declare const LOAD_BEARING_SHAPES: ReadonlyArray<{
+    name: string;
+    pattern: RegExp;
+}>;
+/** Is this comment text consumed by a program? */
+export declare function isLoadBearing(text: string): boolean;
+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,170 @@
+/**
+ * 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
+ *     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.
+ * 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
+    }
+];
+/**
+ * Comments that are LOAD-BEARING: text some program parses as data, not prose it reads.
+ *
+ * These are exempt from BOTH kinds, because the prune acts on a finding of either kind and
+ * deleting any of them does not reduce debt — it removes an enforcement mechanism, or
+ * adds a finding to a gated row. Each shape names the reader that consumes it; a shape
+ * with no reader to point at is a guess, and guesses are what the 4.1.1 prune learned from
+ * `HARD_FLOOR_CATEGORIES` member in `src/services/code/mode-gate.ts`, which is the only
+ * thing backing this repo's one real layer-C promotion, and the gate-H backing check went
+ * red — `feedback-promotion-artifact.test.ts` AC5).
+ *
+ *   - `promotion-evidence` — `src/services/feedback/promotion-source-comments.ts:79`
+ *     (`citedMemories`) feeds `promotion-artifact-evidence.ts:214`, which decides whether a
+ *     promoted rule is actually backed.
+ *   - `grace-marker` — `scripts/lint/silent-warning-detector.mjs:149` subtracts a
+ *     silent-warning finding for any line the offending node spans that carries
+ *     `TODO(g2)`. Deleting the marker therefore RAISES `silentWarningCatchReturnNull` /
+ *     `…EmptyCatch`, both of which may only go down.
+ *   - `toolchain-directive` — `@ts-expect-error` and friends are read by the compiler (an
+ *     unused one is itself an error) and `eslint-disable` by the lint leg; a paired disable
+ *     like `src/services/compact-statusline/compact-statusline-cell-table.ts:72`+`:99`
+ *     must move as a pair or the file starts reporting.
+ */
+export const LOAD_BEARING_SHAPES = [
+    { name: 'promotion-evidence', pattern: /\.peaks\/memory\/[^\s`]+\.md/ },
+    { name: 'grace-marker', pattern: /\bTODO\(g2\)/ },
+    {
+        name: 'toolchain-directive',
+        pattern: /(?:eslint-disable|prettier-ignore|@ts-[a-z-]+|@type\b|@vitest-slow|@covers\b)/
+    }
+];
+/** Is this comment text consumed by a program? */
+export function isLoadBearing(text) {
+    return LOAD_BEARING_SHAPES.some((shape) => shape.pattern.test(text));
+}
+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) {
+    // Before either kind: a load-bearing line is not debt under any reading, so it must not
+    // be reported as a dead reference either — the path it cites is evidence, not a claim
+    // about where a file lives.
+    if (isLoadBearing(entry.text))
+        return [];
+    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;