peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/scan/existing-system-service.js

@@ -0,0 +1,300 @@
+import { readdir, stat } from 'node:fs/promises';
+import { basename, join, relative } from 'node:path';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
+import { scanArchetype } from './archetype-service.js';
+const DEFAULT_MAX_TOKENS = 40;
+const DEFAULT_SAMPLES = 5;
+const COLOR_KEYWORDS = ['color', 'primary', 'success', 'warning', 'error', 'danger', 'info', 'bg', 'background', 'border', 'text'];
+const SPACING_KEYWORDS = ['spacing', 'gap', 'padding', 'margin', 'size'];
+const TYPO_KEYWORDS = ['font', 'text-size', 'line-height', 'letter-spacing', 'heading'];
+const RADIUS_KEYWORDS = ['radius', 'rounded'];
+const STYLE_DIRS = ['src/styles', 'src/style', 'styles', 'src/assets/styles', 'src/theme', 'theme'];
+const COMPONENT_DIRS = ['src/components', 'src/Components', 'components'];
+const SERVICE_DIRS = ['src/services', 'src/service', 'src/api', 'src/apis'];
+const HOOK_DIRS = ['src/hooks', 'src/hook', 'src/composables'];
+function classifyToken(name) {
+    const lower = name.toLowerCase();
+    if (RADIUS_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'radius';
+    if (TYPO_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'typography';
+    if (SPACING_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'spacing';
+    if (COLOR_KEYWORDS.some((kw) => lower.includes(kw)))
+        return 'color';
+    return null;
+}
+function parseLessOrSassVars(content, sourceRel) {
+    const tokens = [];
+    // Match `@var: value;` (Less) or `$var: value;` (Sass)
+    const regex = /^\s*[@$]([a-zA-Z][\w-]*)\s*:\s*([^;]+);/gm;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const [, rawName, rawValue] = match;
+        if (rawName === undefined || rawValue === undefined)
+            continue;
+        tokens.push({ name: rawName, value: rawValue.trim(), source: sourceRel });
+    }
+    return tokens;
+}
+function parseCssVars(content, sourceRel) {
+    const tokens = [];
+    const regex = /--([a-zA-Z][\w-]*)\s*:\s*([^;]+);/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const [, rawName, rawValue] = match;
+        if (rawName === undefined || rawValue === undefined)
+            continue;
+        tokens.push({ name: `--${rawName}`, value: rawValue.trim(), source: sourceRel });
+    }
+    return tokens;
+}
+async function walkStyleFiles(projectRoot) {
+    const found = [];
+    for (const candidate of STYLE_DIRS) {
+        const full = join(projectRoot, candidate);
+        if (!(await isDirectory(full)))
+            continue;
+        const queue = [full];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (current === undefined)
+                break;
+            let entries;
+            try {
+                entries = await readdir(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                    continue;
+                const entryPath = join(current, entry.name);
+                if (entry.isDirectory()) {
+                    queue.push(entryPath);
+                }
+                else if (/\.(less|scss|sass|css)$/i.test(entry.name)) {
+                    found.push(entryPath);
+                }
+            }
+        }
+    }
+    return found;
+}
+async function extractTailwindTokens(projectRoot) {
+    const candidates = ['tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.cjs', 'tailwind.config.mjs'];
+    for (const candidate of candidates) {
+        const full = join(projectRoot, candidate);
+        if (await pathExists(full)) {
+            const content = await readText(full);
+            const tokens = [];
+            // Heuristic: extract keys under theme.extend.* via simple regex.
+            const colorBlock = /colors\s*:\s*\{([\s\S]*?)\}/.exec(content);
+            if (colorBlock?.[1] !== undefined) {
+                const colorRegex = /([a-zA-Z_][\w-]*)\s*:\s*['"`]([^'"`]+)['"`]/g;
+                let match;
+                while ((match = colorRegex.exec(colorBlock[1])) !== null) {
+                    const [, name, value] = match;
+                    if (name !== undefined && value !== undefined) {
+                        tokens.push({ name, value, source: candidate });
+                    }
+                }
+            }
+            return { tokens, source: { path: candidate, kind: 'tailwind-config' } };
+        }
+    }
+    return { tokens: [], source: null };
+}
+async function listFilesByMtime(dir, exts, max) {
+    if (!(await isDirectory(dir)))
+        return [];
+    const collected = [];
+    const queue = [dir];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(full);
+            }
+            else if (exts.test(entry.name)) {
+                try {
+                    const stats = await stat(full);
+                    collected.push({ path: full, mtimeMs: stats.mtimeMs });
+                }
+                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    // skip unreadable
+                }
+            }
+        }
+    }
+    collected.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    return collected.slice(0, max);
+}
+function classifyComponentNaming(samples) {
+    if (samples.length === 0)
+        return 'unknown';
+    let pascal = 0;
+    let kebab = 0;
+    for (const sample of samples) {
+        const name = basename(sample.path).replace(/\.[^.]+$/, '');
+        if (/^[A-Z][a-zA-Z0-9]*$/.test(name))
+            pascal += 1;
+        else if (/^[a-z][a-z0-9-]*$/.test(name))
+            kebab += 1;
+    }
+    if (pascal > 0 && kebab === 0)
+        return 'PascalCase';
+    if (kebab > 0 && pascal === 0)
+        return 'kebab-case';
+    if (pascal > 0 || kebab > 0)
+        return 'mixed';
+    return 'unknown';
+}
+async function firstExistingDir(projectRoot, candidates) {
+    for (const candidate of candidates) {
+        if (await isDirectory(join(projectRoot, candidate))) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function dedupeTokens(tokens, max) {
+    const seen = new Set();
+    const out = [];
+    for (const token of tokens) {
+        const key = `${token.name}=${token.value}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(token);
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+function findInconsistencies(tokens) {
+    const issues = [];
+    const byName = new Map();
+    for (const token of tokens) {
+        const set = byName.get(token.name) ?? new Set();
+        set.add(token.value);
+        byName.set(token.name, set);
+    }
+    for (const [name, values] of byName.entries()) {
+        if (values.size > 1) {
+            issues.push(`token "${name}" has ${values.size} different values across sources: ${[...values].join(' | ')}`);
+        }
+    }
+    return issues;
+}
+export async function scanExistingSystem(options) {
+    const { projectRoot } = options;
+    const maxTokens = options.maxTokens ?? DEFAULT_MAX_TOKENS;
+    const maxSamples = options.maxSamplesPerKind ?? DEFAULT_SAMPLES;
+    const archetypeReport = await scanArchetype({ projectRoot });
+    if (archetypeReport.archetype === 'greenfield' || archetypeReport.archetype === 'unknown') {
+        return {
+            archetype: archetypeReport.archetype,
+            scanned: false,
+            scanSkippedReason: `archetype=${archetypeReport.archetype} — extraction only runs on legacy projects`,
+            visualTokens: { colors: [], spacing: [], typography: [], radii: [], sources: [] },
+            conventions: { componentNaming: 'unknown', componentDir: null, serviceDir: null, hookDir: null, samples: [] },
+            inconsistencies: []
+        };
+    }
+    const sources = [];
+    const rawTokens = [];
+    const styleFiles = await walkStyleFiles(projectRoot);
+    for (const file of styleFiles) {
+        const content = await readText(file);
+        const rel = relative(projectRoot, file).split(/[\\/]/).join('/');
+        if (/\.less$/i.test(file)) {
+            const lessTokens = parseLessOrSassVars(content, rel);
+            if (lessTokens.length > 0) {
+                sources.push({ path: rel, kind: 'less-vars' });
+                rawTokens.push(...lessTokens);
+            }
+        }
+        else if (/\.s[ac]ss$/i.test(file)) {
+            const sassTokens = parseLessOrSassVars(content, rel);
+            if (sassTokens.length > 0) {
+                sources.push({ path: rel, kind: 'sass-vars' });
+                rawTokens.push(...sassTokens);
+            }
+        }
+        const cssVars = parseCssVars(content, rel);
+        if (cssVars.length > 0) {
+            sources.push({ path: rel, kind: 'css-vars' });
+            rawTokens.push(...cssVars);
+        }
+    }
+    const tailwind = await extractTailwindTokens(projectRoot);
+    if (tailwind.source !== null) {
+        sources.push(tailwind.source);
+        rawTokens.push(...tailwind.tokens);
+    }
+    const colors = [];
+    const spacing = [];
+    const typography = [];
+    const radii = [];
+    for (const token of rawTokens) {
+        const category = classifyToken(token.name);
+        if (category === 'color')
+            colors.push(token);
+        else if (category === 'spacing')
+            spacing.push(token);
+        else if (category === 'typography')
+            typography.push(token);
+        else if (category === 'radius')
+            radii.push(token);
+    }
+    const componentDir = await firstExistingDir(projectRoot, COMPONENT_DIRS);
+    const serviceDir = await firstExistingDir(projectRoot, SERVICE_DIRS);
+    const hookDir = await firstExistingDir(projectRoot, HOOK_DIRS);
+    const componentSamples = componentDir !== null
+        ? await listFilesByMtime(join(projectRoot, componentDir), /\.(tsx|jsx|vue|svelte)$/i, maxSamples)
+        : [];
+    const serviceSamples = serviceDir !== null
+        ? await listFilesByMtime(join(projectRoot, serviceDir), /\.(ts|js)$/i, maxSamples)
+        : [];
+    const hookSamples = hookDir !== null
+        ? await listFilesByMtime(join(projectRoot, hookDir), /\.(ts|js)$/i, maxSamples)
+        : [];
+    const samples = [
+        ...componentSamples.map((sample) => ({ path: relative(projectRoot, sample.path).split(/[\\/]/).join('/'), kind: 'component' })),
+        ...serviceSamples.map((sample) => ({ path: relative(projectRoot, sample.path).split(/[\\/]/).join('/'), kind: 'service' })),
+        ...hookSamples.map((sample) => ({ path: relative(projectRoot, sample.path).split(/[\\/]/).join('/'), kind: 'hook' }))
+    ];
+    return {
+        archetype: archetypeReport.archetype,
+        scanned: true,
+        visualTokens: {
+            colors: dedupeTokens(colors, maxTokens),
+            spacing: dedupeTokens(spacing, maxTokens),
+            typography: dedupeTokens(typography, maxTokens),
+            radii: dedupeTokens(radii, maxTokens),
+            sources
+        },
+        conventions: {
+            componentNaming: classifyComponentNaming(componentSamples),
+            componentDir,
+            serviceDir,
+            hookDir,
+            samples
+        },
+        inconsistencies: findInconsistencies(rawTokens)
+    };
+}

package/dist/services/scan/file-size-scan.d.ts

@@ -0,0 +1,23 @@
+export declare const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+export type FileSizeViolation = {
+    file: string;
+    lines: number;
+};
+export type FileSizeScanResult = {
+    ok: boolean;
+    threshold: number;
+    checkedFiles: number;
+    /** Files that appeared in `git diff` but no longer exist on disk (e.g.
+     *  deleted in the working tree). Pre-#015 the scan crashed on these via
+     *  ENOENT; now they are reported here as informational data. */
+    deletedFiles: string[];
+    violations: FileSizeViolation[];
+};
+export type FileSizeScanOptions = {
+    projectRoot: string;
+    /** Compare working tree against this ref. Default 'HEAD'. */
+    baseRef?: string;
+    /** Line count threshold. Default 800. */
+    threshold?: number;
+};
+export declare function scanFileSize(options: FileSizeScanOptions): FileSizeScanResult;

package/dist/services/scan/file-size-scan.js

@@ -0,0 +1,68 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+export const DEFAULT_FILE_SIZE_THRESHOLD = 800;
+function getChangedFiles(projectRoot, baseRef) {
+    try {
+        // --diff-filter=AM keeps only Added + Modified entries. Deleted files
+        // (--diff-filter=D) are intentionally excluded: they have no on-disk
+        // body to count, and a refactor that deletes large files is exactly
+        // when the gate should NOT block. Slice #015 fix.
+        const trackedRaw = execFileSync('git', ['-C', projectRoot, 'diff', '--name-only', '--diff-filter=AM', baseRef], { encoding: 'utf8' });
+        const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
+        const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        return Array.from(new Set([...tracked, ...untracked]));
+    }
+    catch {
+        return [];
+    }
+}
+function countLines(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    return content.split(/\r?\n/).length;
+}
+export function scanFileSize(options) {
+    const baseRef = options.baseRef ?? 'HEAD';
+    const threshold = options.threshold ?? DEFAULT_FILE_SIZE_THRESHOLD;
+    const files = getChangedFiles(options.projectRoot, baseRef);
+    const violations = [];
+    const deletedFiles = [];
+    let checkedFiles = 0;
+    for (const file of files) {
+        const absolute = join(options.projectRoot, file);
+        // Pre-#015: readFileSync threw ENOENT for files that appear in
+        // `git diff --name-only` but no longer exist on disk (e.g. a refactor
+        // that deletes source files). That aborted the entire
+        // `peaks request transition rd → implemented` flow with
+        // `code: PREREQUISITES_MISSING`. Now we skip missing paths — a
+        // deleted file has no lines to count. Belt-and-braces: the
+        // `getChangedFiles` filter above already excludes `--diff-filter=D`,
+        // but a manually-passed `baseRef` (tests) or a path that was
+        // untracked-then-deleted still flows through here, so the
+        // existsSync guard stays as a second line of defense.
+        if (!existsSync(absolute)) {
+            try {
+                const st = statSync(absolute);
+                if (!st.isFile())
+                    continue;
+            }
+            catch {
+                deletedFiles.push(file);
+                continue;
+            }
+        }
+        checkedFiles += 1;
+        const lines = countLines(absolute);
+        if (lines > threshold) {
+            violations.push({ file, lines });
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        threshold,
+        checkedFiles,
+        deletedFiles,
+        violations
+    };
+}

package/dist/services/scan/karpathy-service.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Karpathy scan service (Slice 5/6 — karpathy-enforcement).
+ *
+ * Surface-level structural scan for the 4 Karpathy-guidelines
+ * sections. Detects simple textual signals in `rd/karpathy-review.md`
+ * (or a manually-supplied karpathy review blob) and reports
+ * violation counts per guideline. This is a STRUCTURAL scanner, not
+ * a semantic reviewer; the semantic review happens in the
+ * `karpathy-reviewer` sub-agent (5-way fanout). Pattern follows
+ * `orphan-service.ts` and `api-surface-service.ts`.
+ *
+ * karpathy §2: minimum code, no abstractions, no speculative
+ * features.
+ */
+export type KarpathyViolationKind = 'think-before-coding' | 'simplicity-first' | 'surgical-changes' | 'goal-driven-execution';
+export type KarpathyScanOptions = {
+    projectRoot: string;
+    /** Limit walk to the supplied review file path (default: rd/karpathy-review.md). */
+    reviewFile?: string;
+    /** Scope: working-tree (default) | all. working-tree emits a warning if the file is missing. */
+    scope?: 'working-tree' | 'all';
+};
+export type KarpathyViolation = {
+    kind: KarpathyViolationKind;
+    line: number;
+    snippet: string;
+    hint: string;
+};
+export type KarpathyScanReport = {
+    projectRoot: string;
+    reviewFile: string;
+    scannedAt: string;
+    present: boolean;
+    counts: Record<KarpathyViolationKind, number>;
+    totalViolations: number;
+    violations: KarpathyViolation[];
+    /** Section coverage: which of the 4 guidelines has its dedicated heading in the file. */
+    sectionCoverage: Record<KarpathyViolationKind, boolean>;
+    /** Gate action: pass when totalViolations === 0; warn when > 0; block when file missing under 'all' scope. */
+    gateAction: 'pass' | 'warn' | 'block';
+    warnings: string[];
+};
+export declare function scanKarpathy(options: KarpathyScanOptions): Promise<KarpathyScanReport>;
+/**
+ * Escape user-controlled strings before they are interpolated into the
+ * markdown report. Slice 2.6.1.C mitigation: prevents L1 LOW markdown
+ * injection when `projectRoot`, `reviewFile`, `v.snippet`, etc. contain
+ * characters that would alter rendered structure (backslashes, inline
+ * code fences, link/image syntax).
+ *
+ * The escape keeps the value readable but neutralises the four most
+ * common markdown structural chars. We deliberately do NOT escape every
+ * punctuation mark — the goal is structural safety, not full sanitisation.
+ * Note: a link `[text](url)` is fully neutralised by escaping just `[]`;
+ * the parens alone have no markdown meaning.
+ */
+export declare function escapeMarkdown(value: string): string;
+export declare function formatKarpathyMarkdown(report: KarpathyScanReport, opts?: {
+    title?: string;
+}): string;

package/dist/services/scan/karpathy-service.js

@@ -0,0 +1,228 @@
+/**
+ * Karpathy scan service (Slice 5/6 — karpathy-enforcement).
+ *
+ * Surface-level structural scan for the 4 Karpathy-guidelines
+ * sections. Detects simple textual signals in `rd/karpathy-review.md`
+ * (or a manually-supplied karpathy review blob) and reports
+ * violation counts per guideline. This is a STRUCTURAL scanner, not
+ * a semantic reviewer; the semantic review happens in the
+ * `karpathy-reviewer` sub-agent (5-way fanout). Pattern follows
+ * `orphan-service.ts` and `api-surface-service.ts`.
+ *
+ * karpathy §2: minimum code, no abstractions, no speculative
+ * features.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** 4 Karpathy-guidelines heading markers (case-insensitive, prefix-matched). */
+const GUIDELINE_MARKERS = {
+    'think-before-coding': /^#{1,3}\s*(?:§?\s*1\s*[-.)]?\s*)?think\s+before\s+coding/im,
+    'simplicity-first': /^#{1,3}\s*(?:§?\s*2\s*[-.)]?\s*)?simplicity\s+first/im,
+    'surgical-changes': /^#{1,3}\s*(?:§?\s*3\s*[-.)]?\s*)?surgical\s+changes/im,
+    'goal-driven-execution': /^#{1,3}\s*(?:§?\s*4\s*[-.)]?\s*)?goal[-\s]*driven\s+execution/im
+};
+/** Violation hints keyed by guideline. */
+const VIOLATION_HINTS = {
+    'think-before-coding': 'State assumptions explicitly. Surface tradeoffs. Do not hide confusion.',
+    'simplicity-first': 'If 200 lines could be 50, rewrite. No features beyond what was asked.',
+    'surgical-changes': 'Touch only what the user asked. Clean up only your own mess. Every changed line must trace to the request.',
+    'goal-driven-execution': 'Define verifiable success criteria. For multi-step work, state plan + verify checkpoints.'
+};
+const DEFAULT_REVIEW_FILE = 'rd/karpathy-review.md';
+export async function scanKarpathy(options) {
+    const reviewRel = options.reviewFile ?? DEFAULT_REVIEW_FILE;
+    const abs = join(options.projectRoot, reviewRel);
+    const scope = options.scope ?? 'working-tree';
+    const violations = [];
+    const counts = {
+        'think-before-coding': 0,
+        'simplicity-first': 0,
+        'surgical-changes': 0,
+        'goal-driven-execution': 0
+    };
+    const sectionCoverage = {
+        'think-before-coding': false,
+        'simplicity-first': false,
+        'surgical-changes': false,
+        'goal-driven-execution': false
+    };
+    const warnings = [];
+    let body;
+    try {
+        body = await readFile(abs, 'utf8');
+    }
+    catch {
+        // Per karpathy §1, "surface assumptions" — when the review file is missing
+        // we report the gap explicitly. Hard gate behaviour is determined by scope.
+        if (scope === 'all') {
+            return {
+                projectRoot: options.projectRoot,
+                reviewFile: reviewRel,
+                scannedAt: new Date().toISOString(),
+                present: false,
+                counts,
+                totalViolations: 0,
+                violations,
+                sectionCoverage,
+                gateAction: 'block',
+                warnings: [
+                    `Karpathy review file missing: ${reviewRel}`,
+                    'Per karpathy §1 Think Before Coding: state your assumptions. Without a review file, no 5-way fanout evidence is available.',
+                    'Per karpathy §3 Surgical Changes: touch only what the request requires. Create a minimal rd/karpathy-review.md stub before requesting qa-handoff.'
+                ]
+            };
+        }
+        return {
+            projectRoot: options.projectRoot,
+            reviewFile: reviewRel,
+            scannedAt: new Date().toISOString(),
+            present: false,
+            counts,
+            totalViolations: 0,
+            violations,
+            sectionCoverage,
+            gateAction: 'warn',
+            warnings: [
+                `Karpathy review file missing: ${reviewRel} (scope=${scope}; not blocking).`,
+                'Per karpathy §1 Think Before Coding: surface the missing file to the user.'
+            ]
+        };
+    }
+    // Section coverage: each of the 4 guidelines should have a heading.
+    for (const kind of Object.keys(GUIDELINE_MARKERS)) {
+        sectionCoverage[kind] = GUIDELINE_MARKERS[kind].test(body);
+        if (!sectionCoverage[kind]) {
+            violations.push({
+                kind,
+                line: 1,
+                snippet: '(missing section)',
+                hint: `Add a heading that matches ${VIOLATION_HINTS[kind]}`
+            });
+            counts[kind] += 1;
+        }
+    }
+    // Heuristic violation detection: any line that contains the
+    // anti-pattern markers. Single pass over the file; O(n) total.
+    const lines = body.split('\n');
+    const ANTI_PATTERNS = [
+        {
+            kind: 'surgical-changes',
+            re: /\b(?:TODO|FIXME|XXX|HACK)\b/i,
+            hint: 'Found an unresolved TODO/FIXME. Per karpathy §3, complete the work or remove the marker.'
+        },
+        {
+            kind: 'simplicity-first',
+            re: /\b(?:temporar(?:y|ily)|workaround|for now|just in case)\b/i,
+            hint: 'Found speculative-flexibility language. Per karpathy §2, remove unless the request asked for it.'
+        },
+        {
+            kind: 'goal-driven-execution',
+            re: /\b(?:maybe|perhaps|probably|should be fine|we'll see)\b/i,
+            hint: 'Weak success criteria. Per karpathy §4, replace with a verifiable check.'
+        }
+    ];
+    // Slice 2.6.1.B: skip lines inside fenced code blocks. Anti-pattern
+    // phrases like "TODO" or "should be fine" appear legitimately inside
+    // illustrative code snippets, and flagging them creates noise that
+    // erodes trust in the structural scanner.
+    let inFence = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (line.trim().startsWith('```')) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        for (const ap of ANTI_PATTERNS) {
+            if (ap.re.test(line)) {
+                violations.push({ kind: ap.kind, line: i + 1, snippet: line.trim().slice(0, 120), hint: ap.hint });
+                counts[ap.kind] += 1;
+            }
+        }
+    }
+    if (violations.length === 0) {
+        warnings.push('No anti-patterns detected. Karpathy-Gate passes.');
+    }
+    return {
+        projectRoot: options.projectRoot,
+        reviewFile: reviewRel,
+        scannedAt: new Date().toISOString(),
+        present: true,
+        counts,
+        totalViolations: violations.length,
+        violations,
+        sectionCoverage,
+        gateAction: violations.length === 0 ? 'pass' : 'warn',
+        warnings
+    };
+}
+/**
+ * Escape user-controlled strings before they are interpolated into the
+ * markdown report. Slice 2.6.1.C mitigation: prevents L1 LOW markdown
+ * injection when `projectRoot`, `reviewFile`, `v.snippet`, etc. contain
+ * characters that would alter rendered structure (backslashes, inline
+ * code fences, link/image syntax).
+ *
+ * The escape keeps the value readable but neutralises the four most
+ * common markdown structural chars. We deliberately do NOT escape every
+ * punctuation mark — the goal is structural safety, not full sanitisation.
+ * Note: a link `[text](url)` is fully neutralised by escaping just `[]`;
+ * the parens alone have no markdown meaning.
+ */
+export function escapeMarkdown(value) {
+    return value
+        .replace(/\\/g, '\\\\') // backslash first (order matters)
+        .replace(/`/g, '\\`') // inline code fence
+        .replace(/\[/g, '\\[') // link/image open
+        .replace(/\]/g, '\\]'); // link/image close
+}
+export function formatKarpathyMarkdown(report, opts = {}) {
+    const title = opts.title ?? '## Karpathy inventory';
+    const lines = [];
+    lines.push(title);
+    lines.push('');
+    lines.push(`- **Project:** ${escapeMarkdown(report.projectRoot)}`);
+    lines.push(`- **Review file:** ${escapeMarkdown(report.reviewFile)}`);
+    lines.push(`- **Present:** ${report.present ? 'yes' : 'no'}`);
+    lines.push(`- **Gate action:** ${report.gateAction}`);
+    lines.push(`- **Scanned at:** ${escapeMarkdown(report.scannedAt)}`);
+    lines.push('');
+    lines.push('### Section coverage (4 guidelines)');
+    lines.push('');
+    for (const kind of Object.keys(report.sectionCoverage)) {
+        const present = report.sectionCoverage[kind];
+        lines.push(`- **${kind}**: ${present ? 'present' : '**MISSING**'}`);
+    }
+    lines.push('');
+    lines.push('### Violation counts (4 guidelines)');
+    lines.push('');
+    for (const kind of Object.keys(report.counts)) {
+        lines.push(`- **${kind}**: ${report.counts[kind]}`);
+    }
+    lines.push('');
+    lines.push(`### Violations (total ${report.totalViolations})`);
+    lines.push('');
+    if (report.violations.length === 0) {
+        lines.push('_No violations detected. karpathy-guidelines 4 段全部 pass._');
+    }
+    else {
+        for (const v of report.violations) {
+            lines.push(`- **L${v.line} [${v.kind}]**: ${escapeMarkdown(v.snippet)}`);
+            lines.push(`  - _hint:_ ${escapeMarkdown(v.hint)}`);
+        }
+    }
+    lines.push('');
+    if (report.warnings.length > 0) {
+        lines.push('### Warnings');
+        lines.push('');
+        for (const w of report.warnings) {
+            lines.push(`- ${escapeMarkdown(w)}`);
+        }
+        lines.push('');
+    }
+    lines.push('### Karpathy-Gate');
+    lines.push('');
+    lines.push('Per `andrej-karpathy-skills:karpathy-guidelines` §1 Think Before Coding / §3 Surgical Changes, the hard Karpathy-Gate requires `rd/karpathy-review.md` to be present with all 4 guideline sections before `peaks request transition --state qa-handoff`.');
+    return lines.join('\n');
+}