@event4u/agent-config 14.13.0 → 14.14.1

package/src/scripts/lint_code_comments.ts

@@ -0,0 +1,748 @@
+#!/usr/bin/env node
+/**
+ * lint_code_comments — the carrier `code-comment-discipline` and the
+ * "Code comments English" clause of `language-and-tone` never had.
+ *
+ * Both rules existed and neither could fire on the thing they govern.
+ * `language-and-tone` is a kernel rule and names one enforcer,
+ * `check_md_language.ts`, which rejects every path that is not `.md`
+ * (`check_md_language.ts:175`) — so the code clause carried an `enforced_by`
+ * entry that structurally cannot see a source file. `code-comment-discipline`
+ * is `type: auto` and matches PROMPT keywords, so a run that writes forty-five
+ * files without the user typing "comment", "refactor" or "implement" never
+ * loads it at all. Measured 2026-09-02 in a consumer repository: 40 of 45
+ * changed source files carried German comment lines, one of them a 101-line
+ * colour-analysis report inside a CSS file.
+ *
+ * Three classes, each keyed on STRUCTURE rather than on a judgement about
+ * prose, because a gate that has to decide whether a comment is "useful" is a
+ * gate nobody can predict:
+ *
+ *   1. `de-comment`      — a comment line carrying German. Two independent
+ *                          signals: a German-specific character, or two or
+ *                          more German function words on one line.
+ *   2. `report-comment`  — a comment block shaped like an analysis report.
+ *                          The five literal patterns are in REPORT_SIGNALS,
+ *                          named there rather than quoted here so this header
+ *                          does not trip its own gate. Length is deliberately
+ *                          NOT a signal; a long comment can be one long WHY.
+ *   3. `provenance-comment` — a comment explaining where the code came from:
+ *                          a roadmap path, a phase-and-step citation, a
+ *                          prototype or reference artefact path. Evidence
+ *                          belongs in the roadmap that asked for it, and a
+ *                          second copy in the source is the copy in the wrong
+ *                          place.
+ *
+ * Escape, per line or per file:
+ *   code-comment-allow <class> -- <reason>
+ * A reason is mandatory; the bare marker does not suppress.
+ *
+ * Scope is the DIFF by default, so a pre-existing tree does not turn red.
+ * `--paths` and `--root` exist for auditing a tree the gate does not own.
+ *
+ * STATED RECALL LIMIT, found by running the gate against its own first output
+ * rather than by reasoning about it. A straight `"` left unpaired on a line is
+ * ambiguous — it opens a quotation that continues, or closes one that began
+ * above — and the gate reads it as an opener and stops scanning the rest of
+ * the line. That is right for an English sentence introducing a German quote
+ * and wrong for a German continuation whose opener sits on an earlier line.
+ * Typographic marks carry direction and do not have the ambiguity. The cost is
+ * a miss, never a false positive, and the answer is a second instrument: a
+ * plain word sweep over every changed file with no comment detection at all
+ * caught three lines this classifier could not, and both were run to zero
+ * before the tree was called clean. A gate that has been wrong once is not a
+ * gate to verify with alone.
+ *
+ * Exit codes: 0 clean · 2 findings · 1 usage or internal error.
+ *
+ * `--self-test` drives this binary over {@link COMMENT_CASES}, the one fixture
+ * table the vitest suite also enumerates. A gate that reports a `scanned:`
+ * count has proven it read something; only a case that must REJECT proves the
+ * reading changes the verdict, and only a shared table keeps the two corpora
+ * from drifting apart.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+/** Extensions whose comment syntax the line classifier understands. */
+export const SCANNED_EXTENSIONS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+    '.css', '.scss', '.less',
+    '.php', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.rb',
+    '.vue', '.svelte',
+]);
+
+/** Paths that are generated, vendored, or otherwise not authored here. */
+const SKIP_SEGMENTS = ['node_modules/', 'dist/', 'build/', '.next/', 'vendor/', 'coverage/'];
+
+/** Header markers that mark a whole file as machine-written. */
+const GENERATED_MARKERS = [
+    'generated by', 'auto-generated', 'autogenerated', '@generated',
+    'do not edit', 'code generated by',
+];
+
+/**
+ * A comment line, in the languages above.
+ *
+ * Deliberately line-shaped rather than a parser: a parser would be more
+ * precise about a comment token inside a string literal, and would also be a
+ * dependency and a second definition of "what is a comment" for every language
+ * added later. The cost of the approximation is a false positive on a string
+ * that begins a line with `//` or `*`, which the escape marker answers.
+ */
+const COMMENT_LINE = /^\s*(\{\s*)?(\/\/|\/\*|\*(?!\/)|\*\/|#(?!!)|--)/;
+
+/**
+ * Does this line OPEN a `/* … *\/` block that stays open past its own end?
+ *
+ * The missed case that made this necessary: a block comment whose continuation
+ * lines carry no leading `*` at all —
+ *
+ *     /* Header line.
+ *        Continuation nobody marked.  *\/
+ *
+ * `COMMENT_LINE` matches the first line and nothing after it, so every
+ * continuation read as code and was never classified. Measured: a three-line
+ * German comment in a consumer repository survived a clean run of this gate,
+ * which is the failure that cost the gate its credibility on its first day.
+ */
+function opensBlock(line: string): boolean {
+    const lastOpen = line.lastIndexOf('/*');
+    if (lastOpen === -1) return false;
+    return line.indexOf('*/', lastOpen + 2) === -1;
+}
+
+/** Does this line CLOSE an open block? */
+function closesBlock(line: string): boolean {
+    return line.includes('*/');
+}
+
+/** German-specific characters. `ß` and the umlauts appear in no English word. */
+const DE_CHARS = /[äöüßÄÖÜ]/;
+
+/**
+ * German function words. Function words rather than nouns on purpose: a noun
+ * list is endless and collides with identifiers, while the closed class of
+ * articles, prepositions, conjunctions and auxiliaries is small, stable, and
+ * almost impossible to hit twice on one line of English.
+ *
+ * `die`, `man`, `hat`, `war`, `bei`, `im`, `am`, `so`, `ist` are deliberately
+ * ABSENT even though they are German: each is either an English word or a
+ * common identifier fragment, and the two-hit threshold is not enough
+ * protection when a single term is that ambiguous.
+ */
+const DE_WORDS = new RegExp(
+    '\\b(' + [
+        'der', 'das', 'dem', 'den', 'des',
+        'und', 'oder', 'aber', 'sondern', 'denn',
+        'nicht', 'kein', 'keine', 'keiner', 'keinen',
+        'wird', 'werden', 'wurde', 'worden', 'sind', 'waren',
+        'eine', 'einen', 'einem', 'einer', 'eines',
+        'dass', 'weil', 'damit', 'wenn', 'dann', 'sonst', 'obwohl',
+        'hier', 'dort', 'oben', 'unten', 'auch', 'nur', 'schon', 'noch',
+        'aus', 'fuer', 'ueber', 'durch', 'gegen', 'ohne', 'nach', 'vor',
+        'beim', 'zum', 'zur', 'vom', 'mit', 'sich', 'ihre', 'ihrer', 'seine',
+        'jede', 'jeder', 'jedes', 'alle', 'allen', 'aller',
+        'diese', 'dieser', 'dieses', 'diesem',
+        'steht', 'stehen', 'haben', 'kann', 'koennen', 'muss', 'muessen',
+        'soll', 'sollte', 'gibt', 'geht', 'macht', 'zeigt', 'liegt',
+        'deshalb', 'deswegen', 'trotzdem', 'bereits', 'immer', 'niemals',
+        'derselbe', 'dieselbe', 'dasselbe', 'denselben', 'demselben', 'derselben',
+        'andere', 'anderer', 'anderen', 'anderem', 'anderes',
+        'unter', 'ueber', 'zwischen', 'wegen', 'statt', 'ausser', 'seit',
+        'eigene', 'eigenen', 'eigener', 'jeweils', 'genau', 'etwa', 'sowohl',
+        'warum', 'wieso', 'welche', 'welcher', 'wobei', 'sowie',
+    ].join('|') + ')\\b',
+    'gi',
+);
+
+/** Structural report markers — a comment shaped like a document, not a note. */
+const REPORT_SIGNALS: ReadonlyArray<readonly [string, RegExp]> = [
+    ['markdown-table', /^\s*(?:\/\/|\*|#|--)?\s*\|[^|]*\|[^|]*\|/],
+    ['box-rule', /[─═━]{10,}/],
+    ['section-mark', /^\s*(?:\/\/|\*|#|--)?\s*§\s+\S/],
+    ['markdown-heading', /^\s*(?:\/\/|\*|#|--)?\s*#{2,}\s+\S/],
+    ['revisit-if', /\brevisit-if\b/i],
+];
+
+/** Provenance markers — the code explaining its own paper trail. */
+const PROVENANCE_SIGNALS: ReadonlyArray<readonly [string, RegExp]> = [
+    ['roadmap-path', /\bagents\/roadmaps?\//i],
+    ['reference-path', /\bagents\/(references|evidence|decisions)\//i],
+    ['phase-step', /\b(phase|phase)\s*\d+\s*,\s*(step|schritt)\s*\d+/i],
+    ['prototype-source', /\b(prototyp\w*|prototype)\b[^\n]{0,40}\.(html|fig|sketch|dc\.html)\b/i],
+];
+
+export type FindingClass = 'de-comment' | 'report-comment' | 'provenance-comment';
+
+export interface CommentFinding {
+    cls: FindingClass;
+    file: string;
+    line: number;
+    signal: string;
+    snippet: string;
+}
+
+/** An escape marker with a real reason, for `cls` or for every class. */
+function escapedFor(line: string, cls: FindingClass): boolean {
+    const m = /code-comment-allow\s+([a-z-]+|\*)\s*--\s*(\S.*)$/.exec(line);
+    if (!m) return false;
+    const target = m[1];
+    return target === '*' || target === cls;
+}
+
+/** Is the whole file exempt — a file-level marker, or a generator header? */
+export function fileIsExempt(text: string): boolean {
+    const head = text.slice(0, 2000).toLowerCase();
+    if (GENERATED_MARKERS.some((m) => head.includes(m))) return true;
+    return /code-comment-allow-file\s*--\s*\S/.test(text.slice(0, 2000));
+}
+
+/** Distinct German function words in a fragment. */
+function germanWordCount(s: string): number {
+    return new Set((s.match(DE_WORDS) ?? []).map((h) => h.toLowerCase())).size;
+}
+
+/** Strip the comment punctuation so a signal is matched against prose. */
+function commentProse(line: string): string {
+    return line.replace(/^\s*(\/\/+|\/\*+|\*+\/?|#+|--)/, ' ');
+}
+
+/**
+ * Prose with code spans removed.
+ *
+ * The umlaut signal is otherwise wrong on an English docstring that quotes a
+ * non-ASCII sample value — `café@exämple.com` in a scrubber's own
+ * documentation is the measured case, and it is data being illustrated rather
+ * than German being written. Backtick spans and quoted literals are where
+ * that data lives, so both come out before the character test.
+ */
+function prosePlain(line: string): string {
+    return commentProse(line)
+        .replace(/`[^`]*`/g, ' ')
+        .replace(/'[^']*'/g, ' ')
+        .replace(/"[^"]*"/g, ' ')
+        .replace(/[\u201c\u201e][^\u201c\u201d\u201e]*[\u201d\u201c]/g, ' ')
+        .replace(/[\u2018\u201a][^\u2018\u2019\u201a]*[\u2019\u2018]/g, ' ')
+        .replace(/\u00bb[^\u00ab\u00bb]*\u00ab/g, ' ')
+        // Whatever follows the last unpaired TYPOGRAPHIC opener continues as a
+        // quotation on the next line, so it is quoted data too.
+        //
+        // A straight `"` is deliberately excluded here, and the exclusion is a
+        // repair: a leftover straight quote is just as likely to be the CLOSE
+        // of a quotation that began on the previous line, and treating it as an
+        // opener swallowed the rest of the line. Measured — a German
+        // continuation line reading `oben" heissen. Der Prototyp dreht sie …`
+        // scored zero function words because everything after the quote was
+        // erased. Typographic marks carry their own direction and do not have
+        // this ambiguity.
+        .replace(/[\u201c\u201e][^\u201c\u201d\u201e]*$/, ' ')
+        // A leftover STRAIGHT quote is ambiguous — it may open a quotation that
+        // continues on the next line, or close one that began on the previous.
+        // Trimming to end-of-line is right for the opener and wrong for the
+        // closer, so the trim is applied only when the text BEFORE it is not
+        // itself German: an English sentence introducing a German quotation is
+        // the opener case, and it is the one this must stay silent on.
+        .replace(/"[^"]*$/, (m, offset: number, whole: string) =>
+            germanWordCount(whole.slice(0, offset)) >= 2 ? m : ' ',
+        );
+}
+
+/**
+ * Scan one file's text. Pure, so it answers for a buffer that is not on disk —
+ * which is what the write-time hook needs.
+ */
+export function scanText(file: string, text: string): CommentFinding[] {
+    if (fileIsExempt(text)) return [];
+    const out: CommentFinding[] = [];
+    const lines = text.split('\n');
+    // A quotation that spans lines is the normal way this tree records what a
+    // user actually said, and a per-line quote strip cannot see it: the
+    // opening mark is on one line and the closing mark two lines down, so
+    // every line between them reads as unquoted German. Carrying the open
+    // state across the block is what separates quoted DATA from German PROSE,
+    // and without it the six multi-line user quotations in this repository's
+    // own hooks are false positives.
+    let inQuote = false;
+    let inBlock = false;
+
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? '';
+        const isComment = inBlock || COMMENT_LINE.test(raw);
+        if (inBlock && closesBlock(raw)) inBlock = false;
+        else if (!inBlock && opensBlock(raw)) inBlock = true;
+        if (!isComment) { inQuote = false; continue; }
+        const prose = commentProse(raw);
+        const opensBefore = inQuote;
+        const marks = (commentProse(raw).match(/[\u201c\u201d\u201e"]/g) ?? []).length;
+        if (marks % 2 === 1) inQuote = !inQuote;
+        if (opensBefore) continue;
+        const at = i + 1;
+        const snip = raw.trim().slice(0, 100);
+
+        if (!escapedFor(raw, 'de-comment')) {
+            const plain = prosePlain(raw);
+            const distinct = new Set((plain.match(DE_WORDS) ?? []).map((h) => h.toLowerCase()));
+            const umlaut = DE_CHARS.test(plain);
+            // An umlaut ALONE proves nothing: `Robertson-Spärck-Jones`, a `Ü2`
+            // step label and a quoted sample value all carry one while the
+            // sentence around them is English. Two function words carry the
+            // sentence on their own; one is enough once a German character is
+            // also present. Measured over this repository's own source, both
+            // thresholds together leave zero findings on 402 files.
+            const isGerman = distinct.size >= 2 || (umlaut && distinct.size >= 1);
+            if (isGerman) {
+                out.push({
+                    cls: 'de-comment', file, line: at,
+                    signal: umlaut ? `umlaut+${[...distinct][0]}` : `function-words: ${[...distinct].slice(0, 4).join(' ')}`,
+                    snippet: snip,
+                });
+            }
+        }
+
+        if (!escapedFor(raw, 'report-comment')) {
+            for (const [name, re] of REPORT_SIGNALS) {
+                if (re.test(raw)) {
+                    out.push({ cls: 'report-comment', file, line: at, signal: name, snippet: snip });
+                    break;
+                }
+            }
+        }
+
+        if (!escapedFor(raw, 'provenance-comment')) {
+            for (const [name, re] of PROVENANCE_SIGNALS) {
+                if (re.test(prose)) {
+                    out.push({ cls: 'provenance-comment', file, line: at, signal: name, snippet: snip });
+                    break;
+                }
+            }
+        }
+    }
+    return out;
+}
+
+/** Should this path be scanned at all? */
+export function isScannable(rel: string): boolean {
+    if (SKIP_SEGMENTS.some((s) => rel.includes(s))) return false;
+    if (rel.endsWith('.d.ts')) return false;
+    return SCANNED_EXTENSIONS.has(path.extname(rel));
+}
+
+function changedFiles(root: string, base: string): string[] {
+    const r = spawnSync('git', ['diff', '--name-only', '--diff-filter=ACMR', `${base}...HEAD`], {
+        cwd: root, encoding: 'utf-8',
+    });
+    const tracked = r.status === 0 ? r.stdout.split('\n') : [];
+    const u = spawnSync('git', ['ls-files', '--others', '--exclude-standard'], {
+        cwd: root, encoding: 'utf-8',
+    });
+    const untracked = u.status === 0 ? u.stdout.split('\n') : [];
+    const m = spawnSync('git', ['diff', '--name-only', '--diff-filter=ACMR'], {
+        cwd: root, encoding: 'utf-8',
+    });
+    const dirty = m.status === 0 ? m.stdout.split('\n') : [];
+    return [...new Set([...tracked, ...untracked, ...dirty])].filter((f) => f.trim().length > 0);
+}
+
+/**
+ * Line numbers this diff ADDED, per file. `'all'` for an untracked file, whose
+ * every line is new.
+ *
+ * The gate is described in `.github/workflows/rule-backstops.yml` as
+ * *"diff-scoped, so a pre-existing tree does not turn red"*, and selecting the
+ * FILE set from the diff while scanning each file WHOLE only delivers that for
+ * files nobody touches. Measured 2026-09-02 on PR #1813, which added no
+ * flagged comment at all and was refused on eleven legacy lines — four
+ * provenance paths and seven box rules — in four files it edited for unrelated
+ * reasons. A gate that reds on debt in any file you open makes every edit to an
+ * old file carry an unbounded comment sweep, and the escape it offers per line
+ * turns into exactly the allowlist growth `autonomous-execution` forbids.
+ *
+ * Teeth are unchanged where they belong: a comment the diff writes is scanned
+ * on the line it writes. The explicit-path mode (`--files`) stays whole-file,
+ * because a caller naming a path is asking for that file, not for a diff.
+ *
+ * Parsed from `--unified=0` hunk headers rather than from a patch body: the
+ * header carries the post-image start and count directly, so no line of added
+ * content has to be counted by hand.
+ */
+export function addedLineMap(root: string, base: string): Map<string, Set<number> | 'all'> {
+    const out = new Map<string, Set<number> | 'all'>();
+    const u = spawnSync('git', ['ls-files', '--others', '--exclude-standard'], {
+        cwd: root, encoding: 'utf-8',
+    });
+    if (u.status === 0) {
+        for (const f of u.stdout.split('\n')) {
+            if (f.trim()) out.set(f.trim(), 'all');
+        }
+    }
+    for (const argv of [
+        ['diff', '--unified=0', '--diff-filter=ACMR', `${base}...HEAD`],
+        ['diff', '--unified=0', '--diff-filter=ACMR'],
+    ]) {
+        const r = spawnSync('git', argv, { cwd: root, encoding: 'utf-8' });
+        if (r.status !== 0) continue;
+        mergeAddedLines(out, parseAddedLines(r.stdout));
+    }
+    return out;
+}
+
+/**
+ * Added line numbers per file, from a `git diff --unified=0` patch.
+ *
+ * Split out from the git call so the parse is testable without a repository
+ * whose diff the test would have to manufacture. A `@@` header with no count
+ * means one line — `@@ -4 +4 @@` — and a `+++ /dev/null` header is a deletion,
+ * which adds nothing.
+ */
+export function parseAddedLines(diffText: string): Map<string, Set<number>> {
+    const out = new Map<string, Set<number>>();
+    let file: string | null = null;
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('+++ ')) {
+            const p = line.slice(4).trim();
+            file = p === '/dev/null' ? null : p.replace(/^b\//, '');
+            continue;
+        }
+        if (!file || !line.startsWith('@@')) continue;
+        const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (!m) continue;
+        const start = Number.parseInt(m[1] as string, 10);
+        const count = m[2] === undefined ? 1 : Number.parseInt(m[2], 10);
+        const set = out.get(file) ?? new Set<number>();
+        for (let n = start; n < start + count; n += 1) set.add(n);
+        out.set(file, set);
+    }
+    return out;
+}
+
+/** Fold one parsed patch into the accumulator; `'all'` always wins. */
+function mergeAddedLines(
+    into: Map<string, Set<number> | 'all'>,
+    from: Map<string, Set<number>>,
+): void {
+    for (const [file, lines] of from) {
+        const prev = into.get(file);
+        if (prev === 'all') continue;
+        const set = prev ?? new Set<number>();
+        for (const n of lines) set.add(n);
+        into.set(file, set);
+    }
+}
+
+/**
+ * Findings the diff is answerable for: those sitting on a line it added.
+ *
+ * `'all'` (an untracked file) keeps everything, `undefined` (a file the diff
+ * did not touch) keeps nothing — the two ends of the same rule.
+ */
+export function findingsOnAddedLines(
+    findings: readonly CommentFinding[],
+    lines: Set<number> | 'all' | undefined,
+): CommentFinding[] {
+    if (lines === undefined) return [];
+    if (lines === 'all') return [...findings];
+    return findings.filter((f) => lines.has(f.line));
+}
+
+/** One fixture: a file body and the classes the gate must report on it. */
+export interface CommentCase {
+    /** Printed by both consumers, so it reads as the assertion it makes. */
+    name: string;
+    /**
+     * The whole file body, written verbatim.
+     *
+     * Single-line literals with `\n` escapes rather than a template literal:
+     * a template whose lines began with a comment marker would be scanned as
+     * comments of THIS file, and the fixtures are deliberately violating.
+     */
+    source: string;
+    /** Classes the classifier must report. Empty means the gate stays silent. */
+    flags: readonly FindingClass[];
+}
+
+/**
+ * The polarity corpus, exported because two callers must read the SAME one.
+ *
+ * `tests/scripts/lint_code_comments.test.ts` enumerates it against
+ * {@link scanText} and asserts the exact class set; `--self-test` enumerates it
+ * against the real binary and asserts the exit code. A second table would be a
+ * second definition of what this gate catches, and the one nobody runs locally
+ * is the one that drifts.
+ *
+ * The silent half is the load-bearing half. A language heuristic is only usable
+ * once its near-misses are pinned, and these are the shapes this repository's
+ * own source actually contains: an umlauted proper name, a non-ASCII sample
+ * value inside a code span, an umlauted step label, and a German user
+ * quotation spanning two comment lines.
+ */
+export const COMMENT_CASES: readonly CommentCase[] = [
+    {
+        name: 'a block-comment continuation carrying no leading star is flagged',
+        source:
+            '  /* Hausform mit Objekt-`message`: derselbe Aufbau, anderer Schluessel.\n' +
+            '     `BaseException::render()` dekodiert eine JSON-Zeichenkette und legt das\n' +
+            '     Ergebnis unter `message` ab, bei Feldfehlern ist das ein Objekt. */\n' +
+            '  if (isRecord(payload.message)) {\n',
+        flags: ['de-comment'],
+    },
+    {
+        name: 'a JSX comment, which opens with a brace rather than a slash, is flagged',
+        source: '        {/* Der Titel traegt die Aktion, nicht die Zeile. */}\n',
+        flags: ['de-comment'],
+    },
+    {
+        name: 'a German comment line carrying two function words is flagged',
+        source: '// Hier stehen nur die Werte, die Bedeutung tragen\nconst a = 1;\n',
+        flags: ['de-comment'],
+    },
+    {
+        name: 'transliterated German with no umlaut at all is flagged',
+        source: '/* uebersetzt aus dem Prototyp, jeder Wert ist hier belegt */\n',
+        flags: ['de-comment'],
+    },
+    {
+        name: 'a German line whose only umlaut sits in ordinary prose is flagged',
+        source: '// Die Schriftstufen der kompakten Datenoberfläche\n',
+        flags: ['de-comment'],
+    },
+    {
+        name: 'an English comment quoting a non-ASCII sample value stays silent',
+        source: '/** so a `café@exämple.com` email or a `/Users/möchte/f` path masks */\n',
+        flags: [],
+    },
+    {
+        name: 'an English comment carrying an umlauted proper name stays silent',
+        source: '/** Robertson–Spärck-Jones IDF, floored at 0 so terms never subtract. */\n',
+        flags: [],
+    },
+    {
+        name: 'an umlauted step label in English prose stays silent',
+        source: '// ── Ü2 — orthogonal stance assignment per seat ──\n',
+        flags: [],
+    },
+    {
+        name: 'a single-line German user quotation used as data stays silent',
+        source: '// the phrase "nicht releasen. Warum nicht?" names no fault\n',
+        flags: [],
+    },
+    {
+        name: 'a German user quotation spanning two comment lines stays silent',
+        source:
+            '/**\n *   "Kein Council konfiguriert (keine `.agent-settings.yml`) — ich nutze\n' +
+            ' *    Subagenten-Fächer mit gegnerischen Linsen als Ersatz"\n */\n',
+        flags: [],
+    },
+    {
+        name: 'plain English prose stays silent',
+        source: '// The cap is a stated default, not a measured optimum.\n',
+        flags: [],
+    },
+    {
+        name: 'a markdown table inside a comment is flagged',
+        source: ' * | Prototype | Role | here |\n',
+        flags: ['report-comment'],
+    },
+    {
+        name: 'a box-drawing rule is flagged',
+        source: ' * ─────────────────────────────\n',
+        flags: ['report-comment'],
+    },
+    {
+        name: 'a revisit clause is flagged',
+        source: ' * Revisit-if: someone holds the new surface next to the sidebar.\n',
+        flags: ['report-comment'],
+    },
+    {
+        name: 'a short dash rule that is not a report stays silent',
+        source: '// --- setup ---\n',
+        flags: [],
+    },
+    {
+        name: 'a roadmap citation is flagged',
+        source: '// see agents/roadmaps/todos-task-module-frontend.md\n',
+        flags: ['provenance-comment'],
+    },
+    {
+        name: 'a phase-and-step citation is flagged',
+        source: '// Roadmap todos-task-module, Phase 1, Schritt 1.\n',
+        flags: ['provenance-comment'],
+    },
+    {
+        name: 'a plain code reference stays silent',
+        source: '// see src/lib/token.ts for the parser\n',
+        flags: [],
+    },
+    {
+        name: 'a per-line escape carrying a reason suppresses the class',
+        source: '// Hier stehen die Werte  code-comment-allow de-comment -- quoted spec text\n',
+        flags: [],
+    },
+    {
+        name: 'a bare escape with no reason suppresses nothing',
+        source: '// Hier stehen die Werte  code-comment-allow de-comment\n',
+        flags: ['de-comment'],
+    },
+];
+
+/**
+ * Drive the real binary over every fixture.
+ *
+ * Shells out rather than calling {@link scanText} in-process, because the
+ * thing a contributor runs is the CLI — its argv parsing, its scan-scope
+ * assertion and its exit codes included. The vitest suite covers the pure
+ * classifier; this covers the binary that ships.
+ *
+ * The floors are set just under the table's real size, so deleting a case to
+ * reach green fails instead, and any deliberate shrink shows up as a floor
+ * edit a reviewer reads in the diff.
+ */
+export function selfTest(): number {
+    const repoRoot = path.resolve(path.dirname(_HERE), '..', '..');
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'lcc-selftest-'));
+    const exercise = (testCase: CommentCase, index: number): number => {
+        const file = path.join(dir, `case-${String(index)}.ts`);
+        fs.writeFileSync(file, testCase.source, 'utf-8');
+        return runGateCli(repoRoot, 'src/scripts/lint_code_comments.ts', ['--paths', file], dir);
+    };
+    try {
+        return runSelfTest({
+            gate: 'lint_code_comments',
+            minCases: 16,
+            minRejectCases: 8,
+            cases: COMMENT_CASES.map((testCase, index) => ({
+                name: testCase.name,
+                expect: testCase.flags.length > 0 ? ('reject' as const) : ('accept' as const),
+                run: () => exercise(testCase, index),
+            })),
+        });
+    } finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+
+const HELP = `usage: lint_code_comments [--base <ref>] [--root <dir>] [--paths <f> …] [--report]
+
+  --base <ref>   diff against this ref (default: origin/main)
+  --root <dir>   run against another checkout (default: this repository)
+  --paths        scan exactly these files, ignoring the diff
+  --report       print every finding grouped by file and exit 0
+  --self-test    drive this binary over its own fixture table and exit 0 on pass
+
+Classes: de-comment · report-comment · provenance-comment
+Escape:  code-comment-allow <class|*> -- <reason>   (per line)
+         code-comment-allow-file -- <reason>        (first 2000 chars)
+`;
+
+export function main(argv: string[]): number {
+    // `--help` wins, and the recursion guard is not decoration: `runGateCli`
+    // sets GATE_SELF_TEST_CHILD precisely so a child cannot re-enter the suite.
+    // Latent today because the child's argv is `--paths <file>`, but any later
+    // change that forwards the parent's argv would recurse 18-way per level.
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (argv.includes('--self-test')) {
+        if (process.env['GATE_SELF_TEST_CHILD'] === '1') {
+            process.stderr.write('lint_code_comments: refusing to nest --self-test inside a self-test child\n');
+            return 2;
+        }
+        return selfTest();
+    }
+    let base = 'origin/main';
+    let root = path.resolve(path.dirname(_HERE), '..', '..');
+    let reportOnly = false;
+    const explicit: string[] = [];
+
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h') { process.stdout.write(HELP); return 0; }
+        else if (a === '--base') { base = argv[++i] ?? ''; }
+        else if (a === '--root') { root = path.resolve(argv[++i] ?? '.'); }
+        else if (a === '--report') { reportOnly = true; }
+        else if (a === '--paths') { while (i + 1 < argv.length && !argv[i + 1]!.startsWith('--')) explicit.push(argv[++i]!); }
+        else { process.stderr.write(`lint_code_comments: unknown argument ${a}\n${HELP}`); return 1; }
+    }
+    if (!base && explicit.length === 0) { process.stderr.write('--base needs a ref\n'); return 1; }
+
+    const candidates = (explicit.length > 0 ? explicit : changedFiles(root, base)).filter(isScannable);
+    // Whole file when a caller named the path; only the lines the diff added
+    // when the scope IS the diff — see `addedLineMap` for the measured reason.
+    const added = explicit.length > 0 ? null : addedLineMap(root, base);
+    const findings: CommentFinding[] = [];
+    for (const rel of candidates) {
+        const abs = path.isAbsolute(rel) ? rel : path.join(root, rel);
+        let text: string;
+        try { text = fs.readFileSync(abs, 'utf-8'); } catch { continue; }
+        const all = scanText(rel, text);
+        findings.push(...(added ? findingsOnAddedLines(all, added.get(rel)) : all));
+    }
+
+    try {
+        reportScanned({
+            gate: 'lint_code_comments',
+            scanned: candidates.length,
+            units: 'source file(s)',
+            roots: explicit.length > 0 ? explicit.slice(0, 4) : [`git diff ${base}...HEAD`],
+            allowEmpty:
+                'EMPTY_VALID: the scan root is a DIFF, and a diff with no source file in it is the ' +
+                'normal case for a docs-only or config-only change. git already answered for the ' +
+                'range: an unreadable ref yields no candidates AND no findings, which is ' +
+                'indistinguishable here from a clean docs commit, so this gate deliberately does ' +
+                'not treat zero as a dead scope. The scope failure this class exists to catch — a ' +
+                'moved source tree — cannot occur, because there is no committed path list to go ' +
+                'stale.',
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    process.stdout.write(`  against ${explicit.length > 0 ? 'an explicit path list' : base}\n`);
+    if (findings.length === 0) {
+        process.stdout.write('✅  lint_code_comments: no German, report-shaped or provenance comments.\n');
+        return 0;
+    }
+
+    const byFile = new Map<string, CommentFinding[]>();
+    for (const f of findings) { const l = byFile.get(f.file) ?? []; l.push(f); byFile.set(f.file, l); }
+    for (const [file, list] of [...byFile].sort()) {
+        process.stdout.write(`\n${file}  (${list.length})\n`);
+        for (const f of list.slice(0, 8)) {
+            process.stdout.write(`  ${String(f.line).padStart(5)}  ${f.cls}/${f.signal}  ${f.snippet}\n`);
+        }
+        if (list.length > 8) process.stdout.write(`  … ${list.length - 8} more in this file\n`);
+    }
+    const counts = new Map<string, number>();
+    for (const f of findings) counts.set(f.cls, (counts.get(f.cls) ?? 0) + 1);
+    process.stdout.write(`\n${[...counts].map(([c, n]) => `${c}: ${n}`).join(' · ')} across ${byFile.size} file(s)\n`);
+
+    if (reportOnly) return 0;
+    process.stderr.write(
+        '\n❌  lint_code_comments: comments carry language, evidence or report structure that does not belong in source.\n' +
+        '    A comment states a WHY or a constraint the code cannot show, in English. Evidence belongs in the\n' +
+        '    roadmap that asked for it. Rewrite the comment, delete it, or escape one line with\n' +
+        '    `code-comment-allow <class> -- <reason>`.\n',
+    );
+    return 2;
+}
+
+const _isMain = (() => {
+    const entry = process.argv[1];
+    if (!entry) return false;
+    try { return fs.realpathSync(entry) === fs.realpathSync(_HERE); } catch { return false; }
+})();
+
+if (_isMain) process.exit(main(process.argv.slice(2)));