peaks-loop 4.0.54 → 4.1.1

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

@@ -1,55 +1,15 @@
 import { readdir, stat } from 'node:fs/promises';
 import { basename, join, relative } from 'node:path';
-import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
+import { isDirectory, readText } from 'peaks-loop-shared/fs';
 import { scanArchetype } from './archetype-service.js';
 import { scanHookConvention } from './hook-convention-service.js';
+import { classifyToken, dedupeTokens, extractTailwindTokens, findInconsistencies, parseCssVars, parseLessOrSassVars } from './existing-system-visual-tokens.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) {
@@ -83,30 +43,6 @@ async function walkStyleFiles(projectRoot) {
     }
     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 [];
@@ -135,7 +71,8 @@ async function listFilesByMtime(dir, exts, max) {
                     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)
+                catch {
+                    // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
                     // skip unreadable
                 }
             }
@@ -172,35 +109,6 @@ async function firstExistingDir(projectRoot, candidates) {
     }
     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;
@@ -286,9 +194,18 @@ export async function scanExistingSystem(options) {
         ? 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' }))
+        ...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,

package/dist/services/scan/existing-system-visual-tokens.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Existing-system visual-token extraction (B wave-3 file-size split).
+ *
+ * Extracted verbatim from `existing-system-service.ts`: the visual
+ * token keyword lists, the Less/Sass/CSS/Tailwind parsers, the token
+ * classifier, the dedupe cap, and the cross-source inconsistency
+ * finder. Function bodies and literals are unchanged (verbatim move);
+ * the file walkers and the public `scanExistingSystem` entry stay in
+ * the sibling module.
+ */
+import type { VisualToken, VisualTokenSource } from './scan-types.js';
+export declare function classifyToken(name: string): 'color' | 'spacing' | 'typography' | 'radius' | null;
+export declare function parseLessOrSassVars(content: string, sourceRel: string): VisualToken[];
+export declare function parseCssVars(content: string, sourceRel: string): VisualToken[];
+export declare function extractTailwindTokens(projectRoot: string): Promise<{
+    tokens: VisualToken[];
+    source: VisualTokenSource | null;
+}>;
+export declare function dedupeTokens(tokens: VisualToken[], max: number): VisualToken[];
+export declare function findInconsistencies(tokens: VisualToken[]): string[];

package/dist/services/scan/existing-system-visual-tokens.js

@@ -0,0 +1,123 @@
+/**
+ * Existing-system visual-token extraction (B wave-3 file-size split).
+ *
+ * Extracted verbatim from `existing-system-service.ts`: the visual
+ * token keyword lists, the Less/Sass/CSS/Tailwind parsers, the token
+ * classifier, the dedupe cap, and the cross-source inconsistency
+ * finder. Function bodies and literals are unchanged (verbatim move);
+ * the file walkers and the public `scanExistingSystem` entry stay in
+ * the sibling module.
+ */
+import { join } from 'node:path';
+import { pathExists, readText } from 'peaks-loop-shared/fs';
+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'];
+export 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;
+}
+export 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;
+}
+export 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;
+}
+export 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 };
+}
+export 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;
+}
+export 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;
+}

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

@@ -0,0 +1,86 @@
+/** Raw-line cap for `src/`, `scripts/` and `packages/` — including a `tests` directory inside a package. */
+export declare const FILE_SIZE_CAP_DEFAULT = 300;
+/** Raw-line cap for the root `tests/` tree. A `tests/` dir inside a package keeps the 300 cap. */
+export declare const FILE_SIZE_CAP_TESTS = 500;
+/** Directories the policy measures, relative to the project root. */
+export declare const FILE_SIZE_SCOPE_DIRS: readonly ["src", "tests", "packages", "scripts"];
+/** The extensions it measures. The same seven the lint scope admits. */
+export declare const FILE_SIZE_SCOPE_EXTENSIONS: readonly ["ts", "tsx", "mts", "cts", "mjs", "cjs", "js"];
+/** The unit, stated in the artifact that carries the number rather than in prose. */
+export declare const FILE_SIZE_LINE_CONVENTION = "readFileSync(f,'utf8').split('\\n').length";
+/** The two caps, as the census reports them. */
+export type FileSizeCaps = {
+    readonly defaultCap: number;
+    readonly testsCap: number;
+};
+/** The caps this policy defines right now. */
+export declare function fileSizeCaps(): FileSizeCaps;
+/** Forward slashes, so a Windows-native path matches the same rule as a POSIX one. */
+export declare function normalizePolicyPath(file: string): string;
+/** True when `file` ends in an extension the policy measures. */
+export declare function hasPolicyExtension(file: string): boolean;
+/** True when `file` sits under one of the directories the policy measures. */
+export declare function inFileSizeScope(file: string): boolean;
+/**
+ * THE one definition of "a file the policy measures": under a scope directory AND
+ * of a scope extension. Both consumers read this instead of each carrying its own
+ * half of the rule.
+ *
+ * WHY IT MATTERS (F3 of the repair cycle, rid `2026-09-30-cap-unify-01`). The
+ * census enumerated its scope with `git ls-files <dirs>` plus the extension test,
+ * while the scan measured EVERY changed non-exempt file at `fileSizeCapFor`'s
+ * else-branch 300 — including paths in neither list. The two disagreed about the
+ * same policy, and the disagreement was not harmless: an out-of-scope file (e.g.
+ * under `.husky/`, or a `.json`) could redden a `request transition` at 300 lines
+ * while contributing nothing to `fileSizeOverCap`, so there was no ratchet row to
+ * descend and no split campaign that would ever clear it. Enforcement wider than
+ * the declared scope is enforcement nobody can satisfy.
+ */
+export declare function isPolicyMeasuredFile(file: string): boolean;
+/**
+ * The cap a path is measured against: 500 for the root `tests/` tree, 300 for
+ * everything else in scope — including a `tests` directory inside a package,
+ * which keeps its parent scope's cap by the reading decided 2026-09-30.
+ *
+ * PRECONDITION: `isPolicyMeasuredFile(file)`. The else-branch is `src`,
+ * `packages` and `scripts` ONLY because that is what the policy decided; handed a
+ * path outside the scope it would invent a cap for a file the row cannot see, so
+ * callers must gate on the predicate above first (`file-size-scan.ts` does).
+ */
+export declare function fileSizeCapFor(file: string): number;
+/**
+ * The policy's unit: raw lines counted by splitting on newlines. NOT `wc -l` —
+ * see the header. A file with no trailing newline still counts its last line;
+ * an empty file counts as one.
+ */
+export declare function countRawLines(content: string): number;
+/** The top-level directory a scoped path belongs to, as the census buckets it. */
+export declare function fileSizeScopeBucket(file: string): string;
+/** The second scope's directories, relative to the project root. */
+export declare const HOOKS_FILE_SIZE_SCOPE_DIRS: readonly [".husky"];
+/**
+ * The cap the hooks scope is measured against. It ALIASES `FILE_SIZE_CAP_DEFAULT`
+ * rather than restating 300: the 300 is one decision ("may this file be committed
+ * at this size?"), and a second literal here would be the second copy
+ * `tests/unit/standards/file-size-cap.test.ts` exists to report. Aliasing does NOT
+ * mean the hooks ceiling is unbound — the artifact records `hooksCap` as its own
+ * input and `.husky/peaks-gate-file-size.mjs` re-derives it from a live census, so
+ * re-deciding the default cap trips the hooks row's binding too, as a refusal
+ * rather than as a silent re-baseline.
+ */
+export declare const FILE_SIZE_CAP_HOOKS = 300;
+/** The hooks scope's cap, in the shape the census reports it. */
+export type HooksFileSizeCaps = {
+    readonly hooksCap: number;
+};
+/** The cap the hooks scope is measured against right now. */
+export declare function hooksFileSizeCaps(): HooksFileSizeCaps;
+/** True when `file` sits under one of the hooks scope's directories. */
+export declare function inHooksFileSizeScope(file: string): boolean;
+/**
+ * A file the hooks rows measure: under a hooks directory AND of a scope extension.
+ * The extension universe is the SAME seven as the main scope — it is one decision
+ * about what counts as code, and the hooks binding reports it as its own field so a
+ * change to it is named against both scopes.
+ */
+export declare function isHooksMeasuredFile(file: string): boolean;

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

@@ -0,0 +1,184 @@
+// src/services/scan/file-size-policy.ts
+//
+// THE ONE SOURCE OF TRUTH for the repo's file-size cap policy: the two caps,
+// the directories they cover, the extensions in scope, and the unit a "line" is
+// measured in. Everything that enforces the cap reads it from here —
+// `src/services/scan/file-size-scan.ts` (the diff-scoped CLI scan) and
+// `scripts/lint/file-size-census.ts` (the whole-tree count the husky gate
+// ratchets). Neither may restate a number.
+//
+// WHY ONE MODULE (rid 2026-09-30-cap-unify-01). The policy was written twice,
+// in two units: `max-lines: [error, {max: 400, skipBlankLines, skipComments}]`
+// in `config/eslint/.peaks-rules.cjs` and a raw `DEFAULT_FILE_SIZE_THRESHOLD`
+// of 800 here. Two spellings of one decision drift by construction, and the only
+// number anyone ratcheted was the eslint finding count — which measures a
+// DIFFERENT population (98 `max-lines` findings under 400-effective vs 174 files
+// over the decided 300/500 raw cap). The eslint rule value is deliberately
+// unchanged until the splits land; see `.peaks/docs/lint-gate.md` §4 slice 5.
+//
+// THE UNIT IS PART OF THE POLICY. A line is
+// `readFileSync(f, 'utf8').split('\n').length` — a split-newline count, which is
+// `wc -l` plus one per file. That is not a detail: on the same 174 files the
+// campaign recorded 60,982 excess lines with this convention and 60,808 with
+// `wc -l`, and a ratchet seeded from the other convention is off by exactly the
+// file count. `countRawLines` below is the only implementation of the word
+// "line" in this policy, and the census reports it in its envelope so a reader
+// of the number can see which unit produced it.
+//
+// `scripts/` IS IN SCOPE. The decided cap text named only `src`, `packages` and
+// `tests`, but the 174 the ceiling was seeded from counts 5 `scripts/` files.
+// A row that silently excluded them would not equal its own measurement — the
+// same class of hole as lint-gate §4b (a surface asserted but never counted).
+//
+// NUMBERS THIS MODULE DOES NOT OWN, DECIDED 2026-09-30 (F6 of the repair cycle).
+// A line-count constant elsewhere in the repo is a second copy of THIS policy only
+// if it decides the same question — "may this file be committed at this size?".
+// Three that do not, recorded here so the next reader does not re-litigate them:
+//   - `config/eslint/.peaks-rules.cjs` `max-lines: 400` EFFECTIVE lines: the same
+//     question in a different unit, deliberately left at 400 until the splits land
+//     (lint-gate §4 slice 5; 98 findings ≠ 174 files).
+//   - `src/services/legacy/legacy-detector.ts` `LARGE_FILE_LINES = 500`: a smell
+//     DETECTOR's "is this file big enough to look legacy?" threshold. It reports a
+//     suspicion, blocks nothing, and descends no ceiling, so it is NOT a copy of
+//     this cap and is NOT folded into it — folding it in would silently change what
+//     the legacy report says. Its name does not match the census's `CAP_NAME`
+//     second-copy rule on purpose; see lint-gate §4b row 7.
+//   - `src/services/skills/lint-reference-shape.ts` 800: the shape of an
+//     example lint report, not a cap.
+/** Raw-line cap for `src/`, `scripts/` and `packages/` — including a `tests` directory inside a package. */
+export const FILE_SIZE_CAP_DEFAULT = 300;
+/** Raw-line cap for the root `tests/` tree. A `tests/` dir inside a package keeps the 300 cap. */
+export const FILE_SIZE_CAP_TESTS = 500;
+/** Directories the policy measures, relative to the project root. */
+export const FILE_SIZE_SCOPE_DIRS = ['src', 'tests', 'packages', 'scripts'];
+/** The extensions it measures. The same seven the lint scope admits. */
+export const FILE_SIZE_SCOPE_EXTENSIONS = ['ts', 'tsx', 'mts', 'cts', 'mjs', 'cjs', 'js'];
+/** The unit, stated in the artifact that carries the number rather than in prose. */
+export const FILE_SIZE_LINE_CONVENTION = "readFileSync(f,'utf8').split('\\n').length";
+/** The caps this policy defines right now. */
+export function fileSizeCaps() {
+    return {
+        defaultCap: FILE_SIZE_CAP_DEFAULT,
+        testsCap: FILE_SIZE_CAP_TESTS
+    };
+}
+/** Forward slashes, so a Windows-native path matches the same rule as a POSIX one. */
+export function normalizePolicyPath(file) {
+    return file.split('\\').join('/');
+}
+/** True when `file` ends in an extension the policy measures. */
+export function hasPolicyExtension(file) {
+    const path = normalizePolicyPath(file);
+    const dot = path.lastIndexOf('.');
+    if (dot < 0)
+        return false;
+    return FILE_SIZE_SCOPE_EXTENSIONS.includes(path.slice(dot + 1));
+}
+/** True when `file` sits under one of the directories the policy measures. */
+export function inFileSizeScope(file) {
+    const path = normalizePolicyPath(file);
+    return FILE_SIZE_SCOPE_DIRS.some((dir) => path.startsWith(`${dir}/`));
+}
+/**
+ * THE one definition of "a file the policy measures": under a scope directory AND
+ * of a scope extension. Both consumers read this instead of each carrying its own
+ * half of the rule.
+ *
+ * WHY IT MATTERS (F3 of the repair cycle, rid `2026-09-30-cap-unify-01`). The
+ * census enumerated its scope with `git ls-files <dirs>` plus the extension test,
+ * while the scan measured EVERY changed non-exempt file at `fileSizeCapFor`'s
+ * else-branch 300 — including paths in neither list. The two disagreed about the
+ * same policy, and the disagreement was not harmless: an out-of-scope file (e.g.
+ * under `.husky/`, or a `.json`) could redden a `request transition` at 300 lines
+ * while contributing nothing to `fileSizeOverCap`, so there was no ratchet row to
+ * descend and no split campaign that would ever clear it. Enforcement wider than
+ * the declared scope is enforcement nobody can satisfy.
+ */
+export function isPolicyMeasuredFile(file) {
+    return inFileSizeScope(file) && hasPolicyExtension(file);
+}
+/**
+ * The cap a path is measured against: 500 for the root `tests/` tree, 300 for
+ * everything else in scope — including a `tests` directory inside a package,
+ * which keeps its parent scope's cap by the reading decided 2026-09-30.
+ *
+ * PRECONDITION: `isPolicyMeasuredFile(file)`. The else-branch is `src`,
+ * `packages` and `scripts` ONLY because that is what the policy decided; handed a
+ * path outside the scope it would invent a cap for a file the row cannot see, so
+ * callers must gate on the predicate above first (`file-size-scan.ts` does).
+ */
+export function fileSizeCapFor(file) {
+    return normalizePolicyPath(file).startsWith('tests/')
+        ? FILE_SIZE_CAP_TESTS
+        : FILE_SIZE_CAP_DEFAULT;
+}
+/**
+ * The policy's unit: raw lines counted by splitting on newlines. NOT `wc -l` —
+ * see the header. A file with no trailing newline still counts its last line;
+ * an empty file counts as one.
+ */
+export function countRawLines(content) {
+    return content.split('\n').length;
+}
+/** The top-level directory a scoped path belongs to, as the census buckets it. */
+export function fileSizeScopeBucket(file) {
+    const path = normalizePolicyPath(file);
+    const slash = path.indexOf('/');
+    return slash < 0 ? path : path.slice(0, slash);
+}
+// ---------------------------------------------------------------------------
+// THE SECOND SCOPE — `.husky/`, the directory the ratchet itself lives in
+// (backlog §2.32, rid 2026-10-02-hooks-size-rows)
+// ---------------------------------------------------------------------------
+//
+// WHAT WAS INVISIBLE. `FILE_SIZE_SCOPE_DIRS` names four directories, and `.husky`
+// is not one of them, so the files that IMPLEMENT this policy were measured by
+// nothing: `scanFileSize()` put them in `outOfScopeFiles`, the artifact's `files`
+// table has no entry for them, and the prettier leg never receives them. The guard
+// grew 456 → 750 and 265 → 662 raw lines in a single day with no ceiling watching
+// it — the exact shape of the hole this repo keeps closing (a surface asserted but
+// never counted).
+//
+// WHY A SECOND SCOPE AND NOT A FIFTH DIRECTORY IN THE FIRST ONE. Joining `.husky`
+// to `FILE_SIZE_SCOPE_DIRS` at the decided cap of 300 raises `fileSizeOverCap`
+// 162 → 165 and `fileSizeExcessLines` 54,318 → 55,834 (+1,516), and the monotonicity
+// guard refuses a raised ceiling by design — correctly, because that is a policy
+// re-decision wearing the clothes of a measurement. So the invisible set gets its
+// OWN two rows (`fileSizeHooksOverCap`, `fileSizeHooksExcessLines`), seeded from its
+// own measurement, ratcheted by the same leg off the same census run.
+//
+// DISJOINT BY CONSTRUCTION, and that is the property the disjointness arms test: no
+// directory is in both lists, so `isPolicyMeasuredFile` and `isHooksMeasuredFile`
+// cannot both answer true for one path, and growth under `.husky/` moves the hooks
+// rows and leaves the two main rows at their own numbers.
+/** The second scope's directories, relative to the project root. */
+export const HOOKS_FILE_SIZE_SCOPE_DIRS = ['.husky'];
+/**
+ * The cap the hooks scope is measured against. It ALIASES `FILE_SIZE_CAP_DEFAULT`
+ * rather than restating 300: the 300 is one decision ("may this file be committed
+ * at this size?"), and a second literal here would be the second copy
+ * `tests/unit/standards/file-size-cap.test.ts` exists to report. Aliasing does NOT
+ * mean the hooks ceiling is unbound — the artifact records `hooksCap` as its own
+ * input and `.husky/peaks-gate-file-size.mjs` re-derives it from a live census, so
+ * re-deciding the default cap trips the hooks row's binding too, as a refusal
+ * rather than as a silent re-baseline.
+ */
+export const FILE_SIZE_CAP_HOOKS = FILE_SIZE_CAP_DEFAULT;
+/** The cap the hooks scope is measured against right now. */
+export function hooksFileSizeCaps() {
+    return { hooksCap: FILE_SIZE_CAP_HOOKS };
+}
+/** True when `file` sits under one of the hooks scope's directories. */
+export function inHooksFileSizeScope(file) {
+    const path = normalizePolicyPath(file);
+    return HOOKS_FILE_SIZE_SCOPE_DIRS.some((dir) => path.startsWith(`${dir}/`));
+}
+/**
+ * A file the hooks rows measure: under a hooks directory AND of a scope extension.
+ * The extension universe is the SAME seven as the main scope — it is one decision
+ * about what counts as code, and the hooks binding reports it as its own field so a
+ * change to it is named against both scopes.
+ */
+export function isHooksMeasuredFile(file) {
+    return inHooksFileSizeScope(file) && hasPolicyExtension(file);
+}

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

@@ -1,4 +1,3 @@
-export declare const DEFAULT_FILE_SIZE_THRESHOLD = 800;
 /**
  * Paths exempt from the file-size cap. The cap is Karpathy's "Simplicity
  * First": it exists to make a human *simplify* an over-long file. A path is
@@ -27,10 +26,16 @@ export declare function isSizeCapExempt(file: string): boolean;
 export type FileSizeViolation = {
     file: string;
     lines: number;
+    /** The cap this file was measured against, resolved per path by the policy
+     *  module (300 raw lines; 500 under root `tests/`), or the caller's override. */
+    cap: number;
 };
 export type FileSizeScanResult = {
     ok: boolean;
-    threshold: number;
+    /** The caller's `threshold` override, or `null` when every file was measured
+     *  against its own policy cap. One number cannot describe a two-cap policy,
+     *  so the number that decided a file travels on that file's violation. */
+    threshold: number | null;
     checkedFiles: number;
     /** Paths skipped by SIZE_CAP_EXEMPT_PATTERNS (tool output + append-only
      *  records). Reported so the exemption is auditable rather than a silent
@@ -40,13 +45,35 @@ export type FileSizeScanResult = {
      *  deleted in the working tree). Pre-#015 the scan crashed on these via
      *  ENOENT; now they are reported here as informational data. */
     deletedFiles: string[];
+    /** Changed files the file-size policy does not measure at all: outside its
+     *  four scope directories, or with an extension it does not count. Reported
+     *  rather than silently skipped, for the same reason `exemptFiles` is.
+     *
+     *  WHY THEY ARE NOT VIOLATIONS (F3, rid 2026-09-30-cap-unify-01). Every file
+     *  the scan checked used to be measured against `fileSizeCapFor`, whose
+     *  else-branch is 300 — a number that is only defined for `src`/`packages`/
+     *  `scripts`. So an out-of-scope path (a `.md`, a file under `.husky/`) could
+     *  redden `request transition` at 301 lines while contributing nothing to the
+     *  `fileSizeOverCap` row that ratchets the policy: no ceiling to descend, no
+     *  split campaign with a duty to clear it, and no verdict a contributor could
+     *  act on. Enforcing the cap wider than the declared scope is not a stricter
+     *  gate, it is an unauditable one.
+     *
+     *  A caller that names `threshold` explicitly opts out of the scope rule —
+     *  "apply this number to every changed file" is the documented meaning of the
+     *  flag — and then nothing is out of scope. */
+    outOfScopeFiles: string[];
     violations: FileSizeViolation[];
 };
 export type FileSizeScanOptions = {
     projectRoot: string;
     /** Compare working tree against this ref. Default 'HEAD'. */
     baseRef?: string;
-    /** Line count threshold. Default 800. */
+    /**
+     * Line count threshold applied to EVERY file. When omitted, each file is
+     * measured against the cap `file-size-policy.ts` defines for its directory —
+     * the policy is the default, this option only overrides it.
+     */
     threshold?: number;
 };
 export declare function scanFileSize(options: FileSizeScanOptions): FileSizeScanResult;