peaks-loop 4.0.53 → 4.1.0

package/dist/cli/commands/retrospective-search-command.js

@@ -0,0 +1,97 @@
+/**
+ * `peaks retrospective search` — the search command, hoisted out of
+ * `retrospective-commands.ts` so that file clears the 300 raw-line cap.
+ *
+ * Identical control flow: same filter predicates (in the same order), the
+ * same optional-spread into `searchRetrospective`, the same envelope
+ * fields, the same suggestion texts, the same `process.exitCode = 1`, and
+ * the same catch shape (the failure is reported, never swallowed). The
+ * filter checks and the failure envelope were split into single-purpose
+ * helpers so no function here carries a `max-lines-per-function` or
+ * `complexity` finding; nothing else was rewritten.
+ *
+ * `runRetrospectiveSearch` and `RetrospectiveSearchCommandOptions` stay
+ * importable from `retrospective-commands.js` (public surface unchanged).
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { searchRetrospective } from '../../services/retrospective/retrospective-search-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { resolveRetrospectiveProjectRoot } from './retrospective-project-root.js';
+const VALID_RETRO_TYPES = [
+    'refactor',
+    'feature',
+    'bugfix',
+    'config',
+    'docs',
+    'chore'
+];
+const VALID_RETRO_OUTCOMES = [
+    'shipped',
+    'blocked',
+    'in-flight',
+    'cancelled'
+];
+function resolveTypeFilter(type) {
+    return type !== undefined && VALID_RETRO_TYPES.includes(type)
+        ? type
+        : undefined;
+}
+function resolveOutcomeFilter(outcome) {
+    return outcome !== undefined && VALID_RETRO_OUTCOMES.includes(outcome)
+        ? outcome
+        : undefined;
+}
+function printSearchFailure(io, options, projectRoot, error) {
+    const message = getErrorMessage(error);
+    const code = error.code ?? 'RETROSPECTIVE_SEARCH_FAILED';
+    const suggestions = [];
+    if (code === 'INDEX_MISSING') {
+        suggestions.push('Build a retrospective index.json in .peaks/retrospective/');
+    }
+    if (code === 'EMPTY_QUERY') {
+        suggestions.push('Use `peaks retrospective index` to list all entries');
+    }
+    printResult(io, fail('retrospective.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
+    process.exitCode = 1;
+}
+export function runRetrospectiveSearch(io, options) {
+    const projectRoot = resolveRetrospectiveProjectRoot(options.project);
+    const typeFilter = resolveTypeFilter(options.type);
+    const outcomeFilter = resolveOutcomeFilter(options.outcome);
+    try {
+        const matches = searchRetrospective({
+            query: options.query,
+            projectRoot,
+            ...(typeFilter !== undefined ? { type: typeFilter } : {}),
+            ...(outcomeFilter !== undefined ? { outcome: outcomeFilter } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {})
+        });
+        printResult(io, ok('retrospective.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: []
+        }, []), options.json);
+    }
+    catch (error) {
+        printSearchFailure(io, options, projectRoot, error);
+    }
+}
+export function registerRetrospectiveSearchCommand(retrospective, io) {
+    addJsonOption(retrospective
+        .command('search <query>')
+        .description('Fuzzy-search the retrospective index (deterministic, local, zero-token). Default --limit 6.')
+        .option('--type <type>', `filter by retrospective type (one of: ${VALID_RETRO_TYPES.join(', ')})`)
+        .option('--outcome <outcome>', `filter by retrospective outcome (one of: ${VALID_RETRO_OUTCOMES.join(', ')})`)
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        runRetrospectiveSearch(io, {
+            query,
+            ...(options.type !== undefined ? { type: options.type } : {}),
+            ...(options.outcome !== undefined ? { outcome: options.outcome } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.project !== undefined ? { project: options.project } : {}),
+            ...(options.json !== undefined ? { json: options.json } : {})
+        });
+    });
+}

package/dist/cli/commands/retrospective-show-command.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `peaks retrospective show <id>` — the show command, hoisted out of
+ * `retrospective-commands.ts` so that file clears the 300 raw-line cap.
+ *
+ * Identical control flow: same project-root resolution, the same
+ * `--pretty` → format ternary, the same `!result.ok` branch first (its
+ * three suggestion checks in the same order with the same texts, then
+ * `process.exitCode = 1`, then `return`), the same success envelope field
+ * order, and the same catch with its own code / suggestion text / exit
+ * code. The suggestion list, the failure `data` object and the success
+ * payload became one-builder-each so the action itself is under
+ * `max-lines-per-function` and `complexity`; the builders are pure and
+ * emit the same bytes.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface RetrospectiveShowCommandOptions {
+    project?: string;
+    pretty?: boolean;
+    json?: boolean;
+}
+export declare function runRetrospectiveShowAction(io: ProgramIO, id: string, options: RetrospectiveShowCommandOptions): void;
+export declare function registerRetrospectiveShowCommand(retrospective: Command, io: ProgramIO): void;

package/dist/cli/commands/retrospective-show-command.js

@@ -0,0 +1,80 @@
+/**
+ * `peaks retrospective show <id>` — the show command, hoisted out of
+ * `retrospective-commands.ts` so that file clears the 300 raw-line cap.
+ *
+ * Identical control flow: same project-root resolution, the same
+ * `--pretty` → format ternary, the same `!result.ok` branch first (its
+ * three suggestion checks in the same order with the same texts, then
+ * `process.exitCode = 1`, then `return`), the same success envelope field
+ * order, and the same catch with its own code / suggestion text / exit
+ * code. The suggestion list, the failure `data` object and the success
+ * payload became one-builder-each so the action itself is under
+ * `max-lines-per-function` and `complexity`; the builders are pure and
+ * emit the same bytes.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { resolveRetrospectiveProjectRoot } from './retrospective-project-root.js';
+function buildShowFailureSuggestions(result) {
+    const suggestions = [];
+    if (result.code === 'INDEX_MISSING')
+        suggestions.push('Build a retrospective index.json in .peaks/retrospective/');
+    if (result.code === 'NOT_FOUND')
+        suggestions.push('Run `peaks retrospective index --json` to see available ids');
+    if (result.code === 'ARTIFACT_MISSING' || result.missingArtifacts !== undefined) {
+        suggestions.push('Restore the missing artifact at the path listed under missingArtifacts');
+    }
+    return suggestions;
+}
+function buildShowFailureData(id, projectRoot, result) {
+    return {
+        id,
+        projectRoot,
+        ...(result.missingArtifacts !== undefined ? { missingArtifacts: result.missingArtifacts } : {})
+    };
+}
+function buildShowSuccessPayload(result) {
+    return {
+        id: result.entry.id,
+        sessionId: result.entry.sessionId,
+        sliceId: result.entry.sliceId ?? null,
+        type: result.entry.type,
+        title: result.entry.title,
+        summary: result.entry.summary,
+        outcome: result.entry.outcome,
+        keyDecisions: result.entry.keyDecisions,
+        lessonsLearned: result.entry.lessonsLearned,
+        artifactPaths: result.entry.artifactPaths,
+        updatedAt: result.entry.updatedAt,
+        body: result.body,
+        format: result.format
+    };
+}
+export function runRetrospectiveShowAction(io, id, options) {
+    const projectRoot = resolveRetrospectiveProjectRoot(options.project);
+    try {
+        const format = options.pretty === true ? 'pretty' : 'compact';
+        const result = showRetrospective({ projectRoot, id, format });
+        if (!result.ok) {
+            const suggestions = buildShowFailureSuggestions(result);
+            printResult(io, fail('retrospective.show', result.code, result.message, buildShowFailureData(id, projectRoot, result), suggestions), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('retrospective.show', buildShowSuccessPayload(result), result.warnings), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('retrospective.show', 'RETROSPECTIVE_SHOW_FAILED', getErrorMessage(error), { id, projectRoot }, ['Check the project path and id']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRetrospectiveShowCommand(retrospective, io) {
+    addJsonOption(retrospective
+        .command('show <id>')
+        .description('Show one retrospective entry by id. Default format is `compact` (LLM-primary); pass --pretty to get the disk / re-hydrated pretty form.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--pretty', 'return the pretty form (re-hydrated from source artifacts); overrides the compact default')).action((id, options) => {
+        runRetrospectiveShowAction(io, id, options);
+    });
+}

package/dist/cli/commands/reviewer-commands.d.ts

@@ -9,6 +9,6 @@
  * has no `reviewer` section, both commands emit a structured skip envelope
  * and exit 0 (consistent with A4.3 fallbackOnError=skip).
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerReviewerCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/role-commands.js

@@ -23,7 +23,9 @@ export function registerRoleCommands(program, io) {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         const registry = readRoleRegistry(projectRoot);
         printResult(io, ok('role.list', { projectRoot, roles: registry.roles, count: registry.roles.length }, [], [
-            registry.roles.length === 0 ? 'No roles registered. Run `peaks role add <name>` to start.' : ''
+            registry.roles.length === 0
+                ? 'No roles registered. Run `peaks role add <name>` to start.'
+                : ''
         ].filter(Boolean)), opts.json ?? false);
     });
     addJsonOption(role
@@ -38,7 +40,12 @@ export function registerRoleCommands(program, io) {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
         let newRole;
         if (opts.preset === 'senior-fe') {
-            newRole = { ...DEFAULT_SENIOR_FE_ROLE, name, description: opts.description ?? DEFAULT_SENIOR_FE_ROLE.description, permissions: [...DEFAULT_SENIOR_FE_ROLE.permissions, ...opts.permission] };
+            newRole = {
+                ...DEFAULT_SENIOR_FE_ROLE,
+                name,
+                description: opts.description ?? DEFAULT_SENIOR_FE_ROLE.description,
+                permissions: [...DEFAULT_SENIOR_FE_ROLE.permissions, ...opts.permission]
+            };
         }
         else {
             newRole = { name, description: opts.description ?? '', permissions: opts.permission };
@@ -46,9 +53,7 @@ export function registerRoleCommands(program, io) {
         const registry = readRoleRegistry(projectRoot);
         const next = upsertRole(registry, newRole);
         writeRoleRegistry(projectRoot, next);
-        printResult(io, ok('role.add', { projectRoot, role: newRole }, [], [
-            `Role "${name}" registered with ${newRole.permissions.length} permission(s).`
-        ]), opts.json ?? false);
+        printResult(io, ok('role.add', { projectRoot, role: newRole }, [], [`Role "${name}" registered with ${newRole.permissions.length} permission(s).`]), opts.json ?? false);
     });
     addJsonOption(role
         .command('grant <role> <permission>')
@@ -63,9 +68,7 @@ export function registerRoleCommands(program, io) {
         }
         const next = grantPermission(registry, roleName, permission);
         writeRoleRegistry(projectRoot, next);
-        printResult(io, ok('role.grant', { projectRoot, role: roleName, permission, granted: true }, [], [
-            `Granted "${permission}" to role "${roleName}".`
-        ]), opts.json ?? false);
+        printResult(io, ok('role.grant', { projectRoot, role: roleName, permission, granted: true }, [], [`Granted "${permission}" to role "${roleName}".`]), opts.json ?? false);
     });
     addJsonOption(role
         .command('check <role> <permission>')
@@ -77,7 +80,9 @@ export function registerRoleCommands(program, io) {
         const registry = readRoleRegistry(projectRoot);
         const granted = roleHasPermission(registry, roleName, permission);
         printResult(io, ok('role.check', { projectRoot, role: roleName, permission, granted }, [], [
-            granted ? `Role "${roleName}" has permission "${permission}".` : `Role "${roleName}" does NOT have permission "${permission}".`
+            granted
+                ? `Role "${roleName}" has permission "${permission}".`
+                : `Role "${roleName}" does NOT have permission "${permission}".`
         ]), opts.json ?? false);
         if (!granted)
             process.exitCode = 1;

package/dist/cli/commands/runtime-commands.js

@@ -29,7 +29,9 @@ export function registerRuntimeCommands(program, io) {
             ]), options.json);
         }
         catch (error) {
-            printResult(io, fail('runtime.detect', 'RUNTIME_DETECT_FAILED', getErrorMessage(error), {}, ['Retry with a clean env']), options.json);
+            printResult(io, fail('runtime.detect', 'RUNTIME_DETECT_FAILED', getErrorMessage(error), {}, [
+                'Retry with a clean env'
+            ]), options.json);
             process.exitCode = 1;
         }
     });
@@ -41,7 +43,9 @@ export function registerRuntimeCommands(program, io) {
         .description('List the built-in vendor adapters registered by RuntimeService')).action((options) => {
         try {
             const svc = new RuntimeService();
-            const adapters = svc.listBuiltInAdapters().map((a) => ({ id: a.id, displayName: a.displayName }));
+            const adapters = svc
+                .listBuiltInAdapters()
+                .map((a) => ({ id: a.id, displayName: a.displayName }));
             printResult(io, ok('runtime.list', { builtIn: adapters }, [], [
                 `Run \`peaks adapter register --id <vendor> --binary <cmd>\` to add a custom adapter (persists to .peaks/runtime/adapters.json).`
             ]), options.json);
@@ -67,9 +71,7 @@ export function registerRuntimeCommands(program, io) {
                 // No explicit --via: try to detect first, then fall back.
                 const detected = detectRuntime();
                 if (detected.vendor === 'unknown') {
-                    printResult(io, fail('runtime.compact', 'NO_VENDOR_SPECIFIED', 'No --via <id> provided and no vendor detected.', { detected }, [
-                        'Pass --via <vendor-id>, or run `peaks runtime detect` to see what was detected.'
-                    ]), options.json);
+                    printResult(io, fail('runtime.compact', 'NO_VENDOR_SPECIFIED', 'No --via <id> provided and no vendor detected.', { detected }, ['Pass --via <vendor-id>, or run `peaks runtime detect` to see what was detected.']), options.json);
                     process.exitCode = 1;
                     return;
                 }
@@ -92,7 +94,8 @@ async function runCompact(projectRoot, viaId, force, io, asJson) {
         try {
             registry.load(registryFile);
         }
-        catch { // TODO(g2): vendor-neutrality — corrupt adapter registry must NOT block peaks runtime
+        catch {
+            // TODO(g2): vendor-neutrality — corrupt adapter registry must NOT block peaks runtime
             // Treat corrupt registry as empty — vendor-neutrality: a corrupt
             // .peaks/runtime/adapters.json must NOT block peaks runtime.
             // We still try the built-in path below.
@@ -123,7 +126,11 @@ async function runCompact(projectRoot, viaId, force, io, asJson) {
     if (r.exitCode === 127) {
         warnings.push(`built-in adapter "${viaId}" binary not found on PATH; compact is a no-op`);
     }
-    printResult(io, ok('runtime.compact', { via: viaId, source: 'built-in', compact: { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr } }, warnings, [
+    printResult(io, ok('runtime.compact', {
+        via: viaId,
+        source: 'built-in',
+        compact: { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr }
+    }, warnings, [
         r.exitCode === 0
             ? 'Compact completed.'
             : `Compact exited with code ${r.exitCode}. Check stderr above.`

package/dist/cli/commands/sc-commands.d.ts

@@ -1,3 +1,3 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerSCCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/sc-commands.js

@@ -27,7 +27,11 @@ function registerSCArtifactCommands(sc, io) {
     // longer accepted on `peaks sc impact`. The CLI surfaces a
     // per-`(module, file)` impact report without a top-level
     // change-id binding.
-    addJsonOption(sc.command('impact').description('Generate change impact artifact').option('--module <module>', 'affected module', multipleOption).option('--file <file>', 'affected file', multipleOption)).action((options) => {
+    addJsonOption(sc
+        .command('impact')
+        .description('Generate change impact artifact')
+        .option('--module <module>', 'affected module', multipleOption)
+        .option('--file <file>', 'affected file', multipleOption)).action((options) => {
         const impactOptions = {
             sessionId: '',
             ...(options.module ? { affectedModules: options.module } : {}),
@@ -35,13 +39,42 @@ function registerSCArtifactCommands(sc, io) {
         };
         printResult(io, ok('sc.impact', createChangeImpact(impactOptions)), options.json);
     });
-    addJsonOption(sc.command('retention').description('Create artifact retention report').requiredOption('--slice-id <id>', 'slice identifier').option('--prd <artifact>', 'PRD artifact path', multipleOption).option('--rd <artifact>', 'RD artifact path', multipleOption).option('--qa <artifact>', 'QA artifact path', multipleOption).option('--coverage <artifact>', 'coverage artifact path', multipleOption).option('--review <artifact>', 'review artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
-        printResult(io, ok('sc.retention', createArtifactRetentionReport({ sliceId: options.sliceId, ...(options.prd ? { prdArtifacts: options.prd } : {}), ...(options.rd ? { rdArtifacts: options.rd } : {}), ...(options.qa ? { qaArtifacts: options.qa } : {}), ...(options.coverage ? { coverageArtifacts: options.coverage } : {}), ...(options.review ? { reviewArtifacts: options.review } : {}), ...(options.code ? { codeChanges: options.code } : {}) })), options.json);
+    addJsonOption(sc
+        .command('retention')
+        .description('Create artifact retention report')
+        .requiredOption('--slice-id <id>', 'slice identifier')
+        .option('--prd <artifact>', 'PRD artifact path', multipleOption)
+        .option('--rd <artifact>', 'RD artifact path', multipleOption)
+        .option('--qa <artifact>', 'QA artifact path', multipleOption)
+        .option('--coverage <artifact>', 'coverage artifact path', multipleOption)
+        .option('--review <artifact>', 'review artifact path', multipleOption)
+        .option('--code <file>', 'code file path', multipleOption)).action((options) => {
+        printResult(io, ok('sc.retention', createArtifactRetentionReport({
+            sliceId: options.sliceId,
+            ...(options.prd ? { prdArtifacts: options.prd } : {}),
+            ...(options.rd ? { rdArtifacts: options.rd } : {}),
+            ...(options.qa ? { qaArtifacts: options.qa } : {}),
+            ...(options.coverage ? { coverageArtifacts: options.coverage } : {}),
+            ...(options.review ? { reviewArtifacts: options.review } : {}),
+            ...(options.code ? { codeChanges: options.code } : {})
+        })), options.json);
     });
-    addJsonOption(sc.command('validate').description('Validate artifact retention for a slice').requiredOption('--slice-id <id>', 'slice identifier')).action((options) => {
+    addJsonOption(sc
+        .command('validate')
+        .description('Validate artifact retention for a slice')
+        .requiredOption('--slice-id <id>', 'slice identifier')).action((options) => {
         printResult(io, ok('sc.validate', validateArtifactRetention(options.sliceId)), options.json);
     });
-    addJsonOption(sc.command('boundary').description('Record retention boundary for a slice').requiredOption('--slice-id <id>', 'slice identifier').option('--artifact <path>', 'artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
-        printResult(io, ok('sc.boundary', recordCommitBoundary({ sliceId: options.sliceId, ...(options.artifact ? { artifacts: options.artifact } : {}), ...(options.code ? { codeFiles: options.code } : {}) })), options.json);
+    addJsonOption(sc
+        .command('boundary')
+        .description('Record retention boundary for a slice')
+        .requiredOption('--slice-id <id>', 'slice identifier')
+        .option('--artifact <path>', 'artifact path', multipleOption)
+        .option('--code <file>', 'code file path', multipleOption)).action((options) => {
+        printResult(io, ok('sc.boundary', recordCommitBoundary({
+            sliceId: options.sliceId,
+            ...(options.artifact ? { artifacts: options.artifact } : {}),
+            ...(options.code ? { codeFiles: options.code } : {})
+        })), options.json);
     });
 }

package/dist/cli/commands/scan-commands.js

@@ -4,7 +4,8 @@ import { scanExistingSystem } from '../../services/scan/existing-system-service.
 import { checkTypeSanity } from '../../services/scan/type-sanity-service.js';
 import { getAcceptanceCoverage, isAcceptanceCoverageError } from '../../services/scan/acceptance-coverage-service.js';
 import { getDiffVsScope, isDiffScopeError } from '../../services/scan/diff-scope-service.js';
-import { scanFileSize, DEFAULT_FILE_SIZE_THRESHOLD } from '../../services/scan/file-size-scan.js';
+import { scanFileSize } from '../../services/scan/file-size-scan.js';
+import { FILE_SIZE_CAP_DEFAULT, FILE_SIZE_CAP_TESTS } from '../../services/scan/file-size-policy.js';
 import { scanLibraries } from '../../services/scan/libraries-service.js';
 import { scanApiSurface, formatApiSurfaceMarkdown } from '../../services/scan/api-surface-service.js';
 import { scanOrphans, formatOrphanMarkdown } from '../../services/scan/orphan-service.js';
@@ -27,7 +28,9 @@ function parseRequestType(value) {
     return value;
 }
 export function registerScanCommands(program, io) {
-    const scan = program.command('scan').description('Deterministic project scans (archetype, existing system) for Peaks workflows');
+    const scan = program
+        .command('scan')
+        .description('Deterministic project scans (archetype, existing system) for Peaks workflows');
     addJsonOption(scan
         .command('archetype')
         .description('Detect project archetype, integration mode (three scenarios), frontend-only mode, and supporting signals from the filesystem (read-only)')
@@ -38,7 +41,9 @@ export function registerScanCommands(program, io) {
             if (report.archetype === 'unknown') {
                 nextActions.push('Archetype could not be determined; surface to user before proceeding.');
             }
-            else if (report.archetype === 'legacy-frontend' || report.archetype === 'legacy-fullstack' || report.archetype === 'frontend-monorepo') {
+            else if (report.archetype === 'legacy-frontend' ||
+                report.archetype === 'legacy-fullstack' ||
+                report.archetype === 'frontend-monorepo') {
                 nextActions.push('Run `peaks scan existing-system --project <path>` to extract visual tokens and conventions.');
             }
             printResult(io, ok('scan.archetype', report, [], nextActions), options.json);
@@ -81,7 +86,10 @@ export function registerScanCommands(program, io) {
         .requiredOption('--type <type>', `declared request type (${VALID_REQUEST_TYPES.join(' | ')})`, parseRequestType)
         .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')).action((options) => {
         try {
-            const serviceOptions = { projectRoot: options.project, declaredType: options.type };
+            const serviceOptions = {
+                projectRoot: options.project,
+                declaredType: options.type
+            };
             if (options.baseRef !== undefined) {
                 serviceOptions.baseRef = options.baseRef;
             }
@@ -113,7 +121,10 @@ export function registerScanCommands(program, io) {
         .requiredOption('--project <path>', 'target project root')
         .option('--session-id <session>', 'restrict to a specific session id')).action(async (options) => {
         try {
-            const coverageOptions = { projectRoot: options.project, requestId: options.rid };
+            const coverageOptions = {
+                projectRoot: options.project,
+                requestId: options.rid
+            };
             if (options.sessionId !== undefined) {
                 coverageOptions.sessionId = options.sessionId;
             }
@@ -162,7 +173,10 @@ export function registerScanCommands(program, io) {
         .option('--session-id <session>', 'restrict to a specific session id')
         .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')).action(async (options) => {
         try {
-            const scopeOptions = { projectRoot: options.project, requestId: options.rid };
+            const scopeOptions = {
+                projectRoot: options.project,
+                requestId: options.rid
+            };
             if (options.sessionId !== undefined)
                 scopeOptions.sessionId = options.sessionId;
             if (options.baseRef !== undefined)
@@ -201,7 +215,7 @@ export function registerScanCommands(program, io) {
         .description('Check git diff for files exceeding a line count threshold (karpathy-skills "Simplicity First"; tool output, lockfiles and append-only records such as CHANGELOG.md excluded)')
         .requiredOption('--project <path>', 'target project root')
         .option('--base-ref <ref>', 'compare working tree against this git ref (default: HEAD)')
-        .option('--threshold <n>', `line count threshold (default: ${DEFAULT_FILE_SIZE_THRESHOLD})`)).action((options) => {
+        .option('--threshold <n>', `line count applied to EVERY file (default: the file-size policy's per-directory cap — ${FILE_SIZE_CAP_DEFAULT} raw lines, ${FILE_SIZE_CAP_TESTS} under root tests/)`)).action((options) => {
         try {
             const threshold = options.threshold !== undefined && /^\d+$/.test(options.threshold)
                 ? Number(options.threshold)
@@ -213,7 +227,7 @@ export function registerScanCommands(program, io) {
             });
             const nextActions = [];
             if (!result.ok) {
-                nextActions.push(`${result.violations.length} file(s) exceed ${result.threshold} lines. Split into smaller modules.`);
+                nextActions.push(`${result.violations.length} file(s) exceed their file-size cap. Split into smaller modules.`);
             }
             printResult(io, ok('scan.file-size', result, [], nextActions), options.json);
             if (!result.ok) {
@@ -325,7 +339,7 @@ export function registerScanCommands(program, io) {
     // endpoint. Read-only; never writes. karpathy §3 Surgical Changes.
     addJsonOption(scan
         .command('orphan')
-        .description("Detect 4 kinds of orphans (export / import / CLI subcommand / doc endpoint) — karpathy §3 Surgical Changes")
+        .description('Detect 4 kinds of orphans (export / import / CLI subcommand / doc endpoint) — karpathy §3 Surgical Changes')
         .requiredOption('--project <path>', 'target project root')
         .option('--format <fmt>', 'output format: md (default) | json', (v) => {
         if (v !== 'md' && v !== 'json') {
@@ -347,7 +361,10 @@ export function registerScanCommands(program, io) {
                 ...(options.strict !== undefined ? { strict: options.strict } : {})
             });
             const nextActions = [];
-            const totalOrphans = report.counts.export + report.counts.import + report.counts.cliSubcommand + report.counts.docEndpoint;
+            const totalOrphans = report.counts.export +
+                report.counts.import +
+                report.counts.cliSubcommand +
+                report.counts.docEndpoint;
             if (totalOrphans === 0) {
                 nextActions.push('No orphans detected in the requested scope. RD may proceed to commit.');
             }
@@ -378,7 +395,10 @@ export function registerScanCommands(program, io) {
         catch (error) {
             if (error instanceof InvalidArgumentError)
                 throw error;
-            printResult(io, fail('scan.orphan', 'SCAN_ORPHAN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable', 'Verify the project is a git repository (working-tree scope)']), options.json);
+            printResult(io, fail('scan.orphan', 'SCAN_ORPHAN_FAILED', getErrorMessage(error), { projectRoot: options.project }, [
+                'Verify the project path exists and is readable',
+                'Verify the project is a git repository (working-tree scope)'
+            ]), options.json);
             process.exitCode = 1;
         }
     });
@@ -387,7 +407,7 @@ export function registerScanCommands(program, io) {
     // the 4 Karpathy-guidelines. Read-only; never writes. karpathy §3.
     addJsonOption(scan
         .command('karpathy')
-        .description("Surface-level scan of rd/karpathy-review.md for the 4 Karpathy guidelines (Think / Simplicity / Surgical / Goal) — karpathy §1 + §3")
+        .description('Surface-level scan of rd/karpathy-review.md for the 4 Karpathy guidelines (Think / Simplicity / Surgical / Goal) — karpathy §1 + §3')
         .requiredOption('--project <path>', 'target project root')
         .option('--format <fmt>', 'output format: md (default) | json', (v) => {
         if (v !== 'md' && v !== 'json') {
@@ -438,7 +458,10 @@ export function registerScanCommands(program, io) {
         catch (error) {
             if (error instanceof InvalidArgumentError)
                 throw error;
-            printResult(io, fail('scan.karpathy', 'SCAN_KARPATHY_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is readable', 'Verify the project is a readable directory']), options.json);
+            printResult(io, fail('scan.karpathy', 'SCAN_KARPATHY_FAILED', getErrorMessage(error), { projectRoot: options.project }, [
+                'Verify the project path exists and is readable',
+                'Verify the project is a readable directory'
+            ]), options.json);
             process.exitCode = 1;
         }
     });

package/dist/cli/commands/security-audit-commands.d.ts

@@ -18,6 +18,6 @@
  * This CLI is the I/O + validation shell, mirroring the ecc-bridge
  * pattern (slice 7 Group D).
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerSecurityAuditCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/security-audit-commands.js

@@ -1,5 +1,5 @@
 import { readFileSync } from 'node:fs';
-import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit, } from '../../services/audit-independent/index.js';
+import { detectSecurityAudit, isSecurityAuditEnvelope, runSecurityAudit } from '../../services/audit-independent/index.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 function resolveEnvelope(envelopePath) {
@@ -48,7 +48,10 @@ export function registerSecurityAuditCommands(program, io) {
         const sid = options.sid;
         const rid = options.rid;
         if (sid === undefined || sid.length === 0) {
-            printResult(io, fail('security-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.detect', { state: 'sid-missing' }, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)', 'Run `peaks session info --active --json` to find the active sid.']), options.json);
+            printResult(io, fail('security-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for security-audit.detect', { state: 'sid-missing' }, [
+                'Pass --sid <session-id> (e.g. 2026-06-27-session-...)',
+                'Run `peaks session info --active --json` to find the active sid.'
+            ]), options.json);
             process.exitCode = 1;
             return;
         }
@@ -56,7 +59,7 @@ export function registerSecurityAuditCommands(program, io) {
             const detect = detectSecurityAudit({
                 projectRoot,
                 sessionId: sid,
-                ...(rid !== undefined ? { requestId: rid } : {}),
+                ...(rid !== undefined ? { requestId: rid } : {})
             });
             const envelope = detect.state === 'ready'
                 ? ok('security-audit.detect', detect, [...detect.warnings], [...detect.nextActions])
@@ -72,7 +75,7 @@ export function registerSecurityAuditCommands(program, io) {
                 handoffPresent: false,
                 templatePresent: false,
                 warnings: [],
-                nextActions: [],
+                nextActions: []
             }, ['Re-run with --project <path> pointing at a known-good project root.']), options.json);
             process.exitCode = 1;
         }
@@ -112,7 +115,7 @@ export function registerSecurityAuditCommands(program, io) {
                 sessionId: sid,
                 rid,
                 generatedAt: new Date().toISOString(),
-                envelope: envelopeValue,
+                envelope: envelopeValue
             });
             if (result.detect.state !== 'ready' || result.artifactPath === null) {
                 printResult(io, fail('security-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `security-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]), options.json);
@@ -123,11 +126,13 @@ export function registerSecurityAuditCommands(program, io) {
                 detect: result.detect,
                 artifactPath: result.artifactPath,
                 violationsCount: result.violationsCount,
-                verdict: result.verdict,
+                verdict: result.verdict
             }, [...result.detect.warnings], [...result.detect.nextActions]), options.json);
         }
         catch (error) {
-            printResult(io, fail('security-audit.run', 'RUN_SECURITY_AUDIT_FAILED', getErrorMessage(error), {}, ['Verify the envelope JSON is well-formed and matches the strict-shape contract.']), options.json);
+            printResult(io, fail('security-audit.run', 'RUN_SECURITY_AUDIT_FAILED', getErrorMessage(error), {}, [
+                'Verify the envelope JSON is well-formed and matches the strict-shape contract.'
+            ]), options.json);
             process.exitCode = 1;
         }
     });

package/dist/cli/commands/sediment-commands.d.ts

@@ -1,5 +1,5 @@
-import type { Command } from "commander";
-import { type ProgramIO } from "../cli-helpers.js";
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
 export interface CliResult {
     ok: boolean;
     error?: string;