peaks-loop 4.0.54 → 4.1.1

package/dist/services/job/job-progress-store.d.ts

@@ -11,16 +11,40 @@
  *   }
  *
  * The `peaks code gate-step-08` hook reads this file in its case-1 path
- * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
- * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * (job-shape.json says isJob=true) and surfaces the next-slice sentence built by
+ * {@link describeNextSlice} — `Next: slice #N of M (<label>)` only while the
+ * ledger has a slice pending — to stdout. The LLM cannot "wake up cold" — the
  * next-slice context is mechanically injected on every Bash call.
  *
- * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
- * reader. Schema is zod-validated on read so a stale on-disk copy
+ * Karpathy §2 (Simplicity First): one small file — write the mirror, read the
+ * mirror, and put the mirror into words (describeNextSlice).
+ * Schema is zod-validated on read so a stale on-disk copy
  * from an earlier peaks-loop release fails loud (no silent fallback).
  */
 import { z } from 'zod';
 export declare const JOB_PROGRESS_SCHEMA_VERSION: 1;
+/**
+ * D3 (rid 2026-10-03-job-ledger-truthfulness) — what the mirror says when the
+ * ledger has no pending slice.
+ *
+ * `currentSlice` is required by the schema below (it is a `string`, and readers
+ * such as `src/services/code/step-08-gate.ts` and
+ * `src/services/context/post-compact-reinjection.ts` print it inside the
+ * next-slice sentence), so a job with nothing left still has
+ * to put SOMETHING in the field. Until this slice the CLI invented an identity
+ * for it — `slice-${state.done + 1}` — and §2.38 caught the result:
+ * `currentSlice: "slice-2"` on a job whose only registered slice was
+ * `slice-001`, already done. A label that describes no slice in the ledger is not
+ * a placeholder, it is a false claim about the work.
+ *
+ * So the value is a sentence about the state, not a name: it matches no
+ * `sliceId`, no `label`, and no `slice-<digits>` shape a caller could mistake for
+ * one. Changing the FIELD (or making it optional) is out of scope — readers
+ * already consume it — this only decides what honest text goes in when there is
+ * no next slice. {@link describeNextSlice} is what turns that field into the line
+ * a reader sees; it recognises this value rather than printing it.
+ */
+export declare const NO_PENDING_SLICE_LABEL = "no slice pending";
 export declare const JobProgressSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     jobId: z.ZodString;
@@ -35,10 +59,56 @@ export interface WriteProgressInput {
     readonly jobId: string;
     readonly done: number;
     readonly total: number;
-    readonly currentSlice: string;
+    /**
+     * The next slice to work on, as the ledger names it.
+     *
+     * D3: `undefined` means the ledger has no pending slice — the writer then
+     * records `NO_PENDING_SLICE_LABEL`. It is deliberately NOT the caller's job to
+     * supply a stand-in: every caller that had to invent one invented a slice id.
+     */
+    readonly currentSlice: string | undefined;
     readonly lastCommitSha: string | null;
     readonly updatedAt?: string;
 }
 export declare function writeJobProgress(projectRoot: string, sessionId: string, input: WriteProgressInput): JobProgress;
 export declare function readJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress;
 export declare function tryReadJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress | null;
+/** What the next-slice sentence is allowed to reason about. */
+export interface NextSliceFacts {
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+}
+/**
+ * criterion (c) (rid 2026-10-03-job-ledger-repair1) — the one sentence the reader
+ * acts on, built from the mirror instead of guessed at.
+ *
+ * WHY THIS EXISTS. The parent slice made `currentSlice` honest (§2.38: it used to
+ * carry `slice-2` on a job whose only slice was `slice-001`), and left every reader
+ * of the mirror interpolating it into `slice #${done + 1} of ${total}`. Measured on
+ * the built tree, a finished two-slice job printed
+ *
+ *   next: Next: slice #3 of 2 (no slice pending)
+ *
+ * So the field said the truth and the line said something the ledger cannot
+ * support: an index for a slice that does not exist, in the one line a human or a
+ * resumed LLM actually reads. `done + 1` is only ever entitled to be an index when
+ * the ledger still has a slice pending, which is exactly the state
+ * {@link NO_PENDING_SLICE_LABEL} records.
+ *
+ * THE RULE, in the order the branches are taken:
+ * - nothing pending and every registered slice done → say none is registered left,
+ *   and name the command that changes that (`add-slice`), with the job id filled in;
+ * - nothing pending but registered slices unfinished (blocked / failed / skipped)
+ *   → say none is PENDING; claiming `slice #N` there would promote the index of a
+ *   slice the ledger has stopped queueing;
+ * - pending, and `done` has not yet consumed `total` → the ordinary
+ *   `slice #N of M`, and this is the only branch that may print an index;
+ * - pending, but the mirror already records `total` done → the mirror contradicts
+ *   itself (it is a file another process writes). Print no index, name the slice,
+ *   and send the reader to the authority — `peaks job status`.
+ *
+ * All three shipped readers call this, so the sentence and the command it advises
+ * cannot drift apart again.
+ */
+export declare function describeNextSlice(progress: NextSliceFacts, jobId?: string | null): string;

package/dist/services/job/job-progress-store.js

@@ -11,12 +11,14 @@
  *   }
  *
  * The `peaks code gate-step-08` hook reads this file in its case-1 path
- * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
- * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * (job-shape.json says isJob=true) and surfaces the next-slice sentence built by
+ * {@link describeNextSlice} — `Next: slice #N of M (<label>)` only while the
+ * ledger has a slice pending — to stdout. The LLM cannot "wake up cold" — the
  * next-slice context is mechanically injected on every Bash call.
  *
- * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
- * reader. Schema is zod-validated on read so a stale on-disk copy
+ * Karpathy §2 (Simplicity First): one small file — write the mirror, read the
+ * mirror, and put the mirror into words (describeNextSlice).
+ * Schema is zod-validated on read so a stale on-disk copy
  * from an earlier peaks-loop release fails loud (no silent fallback).
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -38,6 +40,28 @@ function jobProgressDir(projectRoot, sessionId, jobId) {
     return runtimeRoot(projectRoot).join(guardRuntimeSegment(sessionId, 'session id'), guardRuntimeSegment('job', 'role'), guardRuntimeSegment(jobId, 'job id'));
 }
 export const JOB_PROGRESS_SCHEMA_VERSION = 1;
+/**
+ * D3 (rid 2026-10-03-job-ledger-truthfulness) — what the mirror says when the
+ * ledger has no pending slice.
+ *
+ * `currentSlice` is required by the schema below (it is a `string`, and readers
+ * such as `src/services/code/step-08-gate.ts` and
+ * `src/services/context/post-compact-reinjection.ts` print it inside the
+ * next-slice sentence), so a job with nothing left still has
+ * to put SOMETHING in the field. Until this slice the CLI invented an identity
+ * for it — `slice-${state.done + 1}` — and §2.38 caught the result:
+ * `currentSlice: "slice-2"` on a job whose only registered slice was
+ * `slice-001`, already done. A label that describes no slice in the ledger is not
+ * a placeholder, it is a false claim about the work.
+ *
+ * So the value is a sentence about the state, not a name: it matches no
+ * `sliceId`, no `label`, and no `slice-<digits>` shape a caller could mistake for
+ * one. Changing the FIELD (or making it optional) is out of scope — readers
+ * already consume it — this only decides what honest text goes in when there is
+ * no next slice. {@link describeNextSlice} is what turns that field into the line
+ * a reader sees; it recognises this value rather than printing it.
+ */
+export const NO_PENDING_SLICE_LABEL = 'no slice pending';
 export const JobProgressSchema = z.object({
     schemaVersion: z.literal(JOB_PROGRESS_SCHEMA_VERSION),
     jobId: z.string(),
@@ -55,7 +79,7 @@ export function writeJobProgress(projectRoot, sessionId, input) {
         jobId: input.jobId,
         done: input.done,
         total: input.total,
-        currentSlice: input.currentSlice,
+        currentSlice: input.currentSlice ?? NO_PENDING_SLICE_LABEL,
         lastCommitSha: input.lastCommitSha,
         updatedAt: input.updatedAt ?? new Date().toISOString()
     };
@@ -79,7 +103,60 @@ export function tryReadJobProgress(projectRoot, sessionId, jobId) {
         const raw = readFileSync(path, 'utf8');
         return JobProgressSchema.parse(JSON.parse(raw));
     }
-    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)
         return null;
     }
 }
+/** The advice command's label slot: a shape to fill in, never a made-up slice name. */
+const ADD_SLICE_LABEL_SLOT = '"<label>"';
+function addSliceAdvice(jobId) {
+    return `peaks job add-slice --job-id ${jobId ?? '<job-id>'} --slice-label ${ADD_SLICE_LABEL_SLOT}`;
+}
+/**
+ * criterion (c) (rid 2026-10-03-job-ledger-repair1) — the one sentence the reader
+ * acts on, built from the mirror instead of guessed at.
+ *
+ * WHY THIS EXISTS. The parent slice made `currentSlice` honest (§2.38: it used to
+ * carry `slice-2` on a job whose only slice was `slice-001`), and left every reader
+ * of the mirror interpolating it into `slice #${done + 1} of ${total}`. Measured on
+ * the built tree, a finished two-slice job printed
+ *
+ *   next: Next: slice #3 of 2 (no slice pending)
+ *
+ * So the field said the truth and the line said something the ledger cannot
+ * support: an index for a slice that does not exist, in the one line a human or a
+ * resumed LLM actually reads. `done + 1` is only ever entitled to be an index when
+ * the ledger still has a slice pending, which is exactly the state
+ * {@link NO_PENDING_SLICE_LABEL} records.
+ *
+ * THE RULE, in the order the branches are taken:
+ * - nothing pending and every registered slice done → say none is registered left,
+ *   and name the command that changes that (`add-slice`), with the job id filled in;
+ * - nothing pending but registered slices unfinished (blocked / failed / skipped)
+ *   → say none is PENDING; claiming `slice #N` there would promote the index of a
+ *   slice the ledger has stopped queueing;
+ * - pending, and `done` has not yet consumed `total` → the ordinary
+ *   `slice #N of M`, and this is the only branch that may print an index;
+ * - pending, but the mirror already records `total` done → the mirror contradicts
+ *   itself (it is a file another process writes). Print no index, name the slice,
+ *   and send the reader to the authority — `peaks job status`.
+ *
+ * All three shipped readers call this, so the sentence and the command it advises
+ * cannot drift apart again.
+ */
+export function describeNextSlice(progress, jobId) {
+    const id = jobId ?? '<job-id>';
+    if (progress.currentSlice === NO_PENDING_SLICE_LABEL) {
+        return progress.done >= progress.total
+            ? `no further slice is registered — add one with: ${addSliceAdvice(id)}`
+            : `no slice is pending — ${progress.done} of ${progress.total} registered slices are ` +
+                `done and the rest are not pending; add one with: ${addSliceAdvice(id)}`;
+    }
+    if (progress.done >= progress.total) {
+        return (`the progress mirror names pending slice "${progress.currentSlice}" while recording ` +
+            `${progress.done} of ${progress.total} slices done — trust the ledger: ` +
+            `peaks job status --job-id ${id}`);
+    }
+    return `slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`;
+}

package/dist/services/job/job-rotation.d.ts

@@ -1,4 +1,4 @@
-import { JobStateStore } from './job-state-store.js';
+import type { JobStateStore } from './job-state-store.js';
 export interface CycleOutcome {
     rotated: boolean;
     reason?: string;

package/dist/services/job/job-rotation.js

@@ -24,7 +24,11 @@ export class JobRotation {
         if (!outcome.rotated)
             return { rotated: false, reason: 'session-rotate-refused' };
         const nextCycle = state.mainSessionCycle + 1;
-        this.store.save({ ...state, mainSessionCycle: nextCycle, lastCheckpointAt: new Date().toISOString() });
+        this.store.save({
+            ...state,
+            mainSessionCycle: nextCycle,
+            lastCheckpointAt: new Date().toISOString()
+        });
         return { rotated: true, reason: `cycle-${nextCycle} (${summary.cycle})` };
     }
 }

package/dist/services/job/job-state-store.js

@@ -31,8 +31,8 @@ export class JobStateStore {
                 sliceId: `slice-${String(i + 1).padStart(3, '0')}`,
                 label,
                 status: 'pending',
-                repairCycles: 0,
-            })),
+                repairCycles: 0
+            }))
         });
         this.save(state);
         return state;

package/dist/services/job/job-types.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { commitVerificationRefusal, verifyCommitSha } from './job-commit-verification.js';
 // ── Spec §4.2, verbatim from spec ────────────────────────────────────────
 export const SliceStateSchema = z
     .object({
@@ -9,28 +10,28 @@ export const SliceStateSchema = z
     finishedAt: z.string().datetime().optional(),
     failureReason: z.string().optional(), // required when status=failed
     repairCycles: z.number().int().gte(0).default(0),
-    blockedReason: z.string().optional(), // required when status=blocked
+    blockedReason: z.string().optional() // required when status=blocked
 })
     .superRefine((v, ctx) => {
     if (v.status === 'done' && !(v.commitSha && v.commitSha.length >= 7)) {
         ctx.addIssue({
             code: 'custom',
             path: ['commitSha'],
-            message: 'commitSha required (≥7 hex) when status=done',
+            message: 'commitSha required (≥7 hex) when status=done'
         });
     }
     if (v.status === 'failed' && !(v.failureReason && v.failureReason.length >= 1)) {
         ctx.addIssue({
             code: 'custom',
             path: ['failureReason'],
-            message: 'failureReason required when status=failed',
+            message: 'failureReason required when status=failed'
         });
     }
     if (v.status === 'blocked' && !(v.blockedReason && v.blockedReason.length >= 1)) {
         ctx.addIssue({
             code: 'custom',
             path: ['blockedReason'],
-            message: 'blockedReason required when status=blocked',
+            message: 'blockedReason required when status=blocked'
         });
     }
 });
@@ -49,17 +50,17 @@ export const JobStateSchema = z.object({
         from: z.literal('rotating'),
         to: z.literal('single'),
         reason: z.string().min(10),
-        at: z.string().datetime(),
+        at: z.string().datetime()
     })
         .optional(),
-    slices: z.array(SliceStateSchema),
+    slices: z.array(SliceStateSchema)
 });
 export const ResourceSnapshotSchema = z.object({
     capturedAt: z.string().datetime(),
     cpuPercent: z.number().min(0).max(100),
     memMb: z.number().gte(0),
     diskMb: z.number().gte(0),
-    contextRatio: z.number().min(0).max(1),
+    contextRatio: z.number().min(0).max(1)
 });
 export const JobStatusSummarySchema = z.object({
     total: z.number().int(),
@@ -72,7 +73,7 @@ export const JobStatusSummarySchema = z.object({
     mainLoopStrategy: z.enum(['single', 'rotating']),
     mainSessionCycle: z.number().int(),
     etaSec: z.number().int().optional(),
-    resourcesNow: ResourceSnapshotSchema.optional(),
+    resourcesNow: ResourceSnapshotSchema.optional()
 });
 // ── Spec §4.1 CLI input schemas (used by M3) ─────────────────────────────
 export const JobInitInputSchema = z.object({
@@ -84,7 +85,7 @@ export const JobInitInputSchema = z.object({
     mainLoopStrategy: z.enum(['single', 'rotating']).default('rotating'),
     rotateEvery: z.number().int().gt(0).default(3),
     project: z.string(),
-    json: z.boolean().default(true),
+    json: z.boolean().default(true)
 });
 export const JobCheckpointInputSchema = z
     .object({
@@ -94,22 +95,50 @@ export const JobCheckpointInputSchema = z
     commitSha: z.string().optional(),
     reason: z.string().optional(),
     project: z.string(),
-    json: z.boolean().default(true),
+    json: z.boolean().default(true)
 })
     .superRefine((v, ctx) => {
-    if (v.state === 'done' && !(v.commitSha && v.commitSha.length >= 7)) {
-        ctx.addIssue({
-            code: 'custom',
-            path: ['commitSha'],
-            message: 'commitSha required (≥7 hex) when state=done',
-        });
+    if (v.state === 'done') {
+        // D2 (rid 2026-10-03-job-ledger-truthfulness). Two rules, in this order,
+        // both on the same claim about the same field.
+        //
+        // 1. THE SHAPE RULE. It stays exactly where the defect was measured
+        //    (`job-orchestrator.ts:55` checked only `length >= 7`), and it is the
+        //    PRE-FILTER: a string that is not even sha-shaped is refused here and
+        //    is never paid a `git` call.
+        // 2. THE EXISTENCE RULE. Past the shape rule, the sha must resolve to a
+        //    commit in the project repository. Length and alphabet say the string
+        //    is sha-shaped; only git says whether the commit exists — and a ledger
+        //    keyed to a commit that is not in the repository will be trusted later.
+        //
+        // WHY HERE AND NOT IN THE ACTION. This refine runs at
+        // `JobCheckpointInputSchema.safeParse`, the first thing the `checkpoint`
+        // command does: it is therefore before `resolveJobStateRoot`, before the
+        // lock, and before either file is opened, so a refusal leaves the ledger
+        // byte-unchanged rather than merely unwritten — and it rides the
+        // command's existing refusal channel (`INVALID_CHECKPOINT`) instead of
+        // needing a new reporting site in `job-commands.ts`. The project root
+        // `v.project` is already part of this input, and it is the same value the
+        // command passes to `--project`/cwd resolution.
+        if (!v.commitSha || v.commitSha.length < 7) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['commitSha'],
+                message: 'commitSha required (≥7 hex) when state=done'
+            });
+        }
+        else {
+            const refusal = commitVerificationRefusal(verifyCommitSha(v.project, v.commitSha), v.project, v.commitSha);
+            if (refusal !== null) {
+                ctx.addIssue({ code: 'custom', path: ['commitSha'], message: refusal });
+            }
+        }
     }
-    if ((v.state === 'failed' || v.state === 'skipped') &&
-        !(v.reason && v.reason.length >= 3)) {
+    if ((v.state === 'failed' || v.state === 'skipped') && !(v.reason && v.reason.length >= 3)) {
         ctx.addIssue({
             code: 'custom',
             path: ['reason'],
-            message: 'reason required (≥3 chars) when state=failed|skipped',
+            message: 'reason required (≥3 chars) when state=failed|skipped'
         });
     }
 });
@@ -118,5 +147,5 @@ export const JobBlockInputSchema = z.object({
     sliceId: z.string(),
     reason: z.string().min(3),
     project: z.string(),
-    json: z.boolean().default(true),
+    json: z.boolean().default(true)
 });

package/dist/services/job/subagent-job-wrapper.d.ts

@@ -1,4 +1,4 @@
-import { JobStateStore } from './job-state-store.js';
+import type { JobStateStore } from './job-state-store.js';
 export interface WrapInput {
     jobId: string;
     role: 'prd' | 'rd' | 'qa' | 'ui' | 'txt' | 'sc' | 'agent';

package/dist/services/job/subagent-job-wrapper.js

@@ -9,7 +9,11 @@ export class SubAgentJobWrapper {
     async wrap(input) {
         const budgetMb = input.budgetMb ?? 512;
         const candidateBatchId = `batch-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
-        const result = await this.dispatch(input.role, input.prompt, { budgetMb, jobScope: true, batchId: candidateBatchId });
+        const result = await this.dispatch(input.role, input.prompt, {
+            budgetMb,
+            jobScope: true,
+            batchId: candidateBatchId
+        });
         const batchId = result.batchId;
         if (!this.dispatchedBatches.has(input.jobId))
             this.dispatchedBatches.set(input.jobId, new Set());

package/dist/services/job-snapshot/snapshot.js

@@ -23,7 +23,7 @@ export function collectResourceSnapshot(jobDir) {
         cpuPercent,
         memMb,
         diskMb,
-        contextRatio,
+        contextRatio
     };
 }
 // Non-enumerable internal attachment for test-time access via
@@ -34,7 +34,7 @@ Object.defineProperty(collectResourceSnapshot, 'dirSizeMb', {
     value: dirSizeMb,
     enumerable: false,
     writable: false,
-    configurable: false,
+    configurable: false
 });
 /**
  * Best-effort, non-recursive size of one directory level, in rounded megabytes.

package/dist/services/karpathy-cost/karpathy-cost-check-service.js

@@ -35,9 +35,9 @@ export function decideKarpathyCostCheck(input) {
             decision: {
                 kind: '24h-mode-active',
                 gateAction: null,
-                reason: 'peaks session 24h-mode state = 24H_ACTIVE; cost-check is the OVERRIDE, not the constrained side',
+                reason: 'peaks session 24h-mode state = 24H_ACTIVE; cost-check is the OVERRIDE, not the constrained side'
             },
-            reasonLine: 'karpathy-cost-check: skipped (24h-mode active)',
+            reasonLine: 'karpathy-cost-check: skipped (24h-mode active)'
         };
     }
     let envelope;
@@ -47,7 +47,7 @@ export function decideKarpathyCostCheck(input) {
     catch {
         return {
             decision: { kind: 'no-cost-data', gateAction: null, reason: 'envelope-not-json' },
-            reasonLine: 'karpathy-cost-check: skipped (envelope not JSON)',
+            reasonLine: 'karpathy-cost-check: skipped (envelope not JSON)'
         };
     }
     if (!envelope.evaluationCost || typeof envelope.costRatio !== 'number') {
@@ -55,9 +55,9 @@ export function decideKarpathyCostCheck(input) {
             decision: {
                 kind: 'no-cost-data',
                 gateAction: envelope.gateAction ?? null,
-                reason: 'envelope-missing-evaluationCost',
+                reason: 'envelope-missing-evaluationCost'
             },
-            reasonLine: 'karpathy-cost-check: skipped (envelope missing evaluationCost/costRatio)',
+            reasonLine: 'karpathy-cost-check: skipped (envelope missing evaluationCost/costRatio)'
         };
     }
     const costRatio = envelope.costRatio;
@@ -69,20 +69,30 @@ export function decideKarpathyCostCheck(input) {
                 originalGateAction: 'block',
                 newGateAction: 'warn',
                 costRatio,
-                evaluationCost,
+                evaluationCost
             },
-            reasonLine: `karpathy-cost-check: downgraded block → warn (costRatio=${costRatio.toFixed(2)} > ${KARPATHY_COST_DOWNGRADE_THRESHOLD})`,
+            reasonLine: `karpathy-cost-check: downgraded block → warn (costRatio=${costRatio.toFixed(2)} > ${KARPATHY_COST_DOWNGRADE_THRESHOLD})`
         };
     }
     if (costRatio > KARPATHY_COST_REPORT_THRESHOLD) {
         return {
-            decision: { kind: 'reported', gateAction: envelope.gateAction ?? 'pass', costRatio, evaluationCost },
-            reasonLine: `karpathy-cost-check: costRatio=${costRatio.toFixed(2)} > ${KARPATHY_COST_REPORT_THRESHOLD} (sediment appended)`,
+            decision: {
+                kind: 'reported',
+                gateAction: envelope.gateAction ?? 'pass',
+                costRatio,
+                evaluationCost
+            },
+            reasonLine: `karpathy-cost-check: costRatio=${costRatio.toFixed(2)} > ${KARPATHY_COST_REPORT_THRESHOLD} (sediment appended)`
         };
     }
     return {
-        decision: { kind: 'unchanged', gateAction: envelope.gateAction ?? 'pass', costRatio, evaluationCost },
-        reasonLine: `karpathy-cost-check: unchanged (costRatio=${costRatio.toFixed(2)})`,
+        decision: {
+            kind: 'unchanged',
+            gateAction: envelope.gateAction ?? 'pass',
+            costRatio,
+            evaluationCost
+        },
+        reasonLine: `karpathy-cost-check: unchanged (costRatio=${costRatio.toFixed(2)})`
     };
 }
 /** Convenience: load the review file from disk and run the decision. */
@@ -94,12 +104,12 @@ export function runKarpathyCostCheck(opts) {
     catch {
         return {
             decision: { kind: 'no-cost-data', gateAction: null, reason: 'file-missing' },
-            reasonLine: `karpathy-cost-check: skipped (file missing: ${opts.reviewFilePath})`,
+            reasonLine: `karpathy-cost-check: skipped (file missing: ${opts.reviewFilePath})`
         };
     }
     return decideKarpathyCostCheck({
         reviewFileContent: content,
-        is24hModeActive: opts.is24hModeActive,
+        is24hModeActive: opts.is24hModeActive
     });
 }
 /** Envelope-shape return for the CLI. */

package/dist/services/legacy/legacy-detector.js

@@ -23,6 +23,25 @@ const PATTERNS = [
     { kind: 'any-type', regex: /\b(?:as\s+any|:\s*any\b|<any>)/ },
     { kind: 'ts-ignore', regex: /@ts-(?:ignore|expect-error|nocheck)/ }
 ];
+/**
+ * NOT the file-size cap, and NOT a second copy of it — decided 2026-09-30, rid
+ * `2026-09-30-cap-unify-01` repair cycle (F6), and recorded in
+ * `.peaks/docs/lint-gate.md` §4b row 7 so the next reader does not re-litigate it.
+ *
+ * This is a legacy SMELL heuristic: a number above which a file is big enough to
+ * be worth a second look. It reports a suspicion; it blocks nothing, reddens no
+ * gate, and descends no ceiling — whereas `src/services/scan/file-size-policy.ts`
+ * (300 raw for `src`/`packages`/`scripts`, 500 for root `tests/`) decides whether
+ * a file may be COMMITTED, and its whole-tree count is ratcheted by
+ * `fileSizeOverCap`. Two constants answering two questions.
+ *
+ * FOLDING IT IN WAS CONSIDERED AND REJECTED: lowering this to 300 would make
+ * every one of the 134 over-cap `src/` files also a "legacy" finding, i.e. it
+ * would silently change what `peaks scan legacy` reports in order to satisfy a
+ * naming rule. The census's `CAP_NAME` rule cannot see this constant — the name
+ * does not match — which is exactly why the decision is written here instead of
+ * being left for the rule to make.
+ */
 const LARGE_FILE_LINES = 500;
 function scanFile(file) {
     let content;
@@ -44,7 +63,12 @@ function scanFile(file) {
         }
     }
     if (lines.length > LARGE_FILE_LINES) {
-        findings.push({ kind: 'large-file', file, line: null, excerpt: `${lines.length} lines (> ${LARGE_FILE_LINES})` });
+        findings.push({
+            kind: 'large-file',
+            file,
+            line: null,
+            excerpt: `${lines.length} lines (> ${LARGE_FILE_LINES})`
+        });
     }
     return findings;
 }
@@ -61,12 +85,20 @@ function walkFiles(root, maxDepth = 8) {
             return;
         }
         for (const e of entries) {
-            if (e.name === 'node_modules' || e.name === '.git' || e.name === 'dist' || e.name === 'node_modules' || e.name.startsWith('.'))
+            if (e.name === 'node_modules' ||
+                e.name === '.git' ||
+                e.name === 'dist' ||
+                e.name === 'node_modules' ||
+                e.name.startsWith('.'))
                 continue;
             const full = join(dir, e.name);
             if (e.isDirectory())
                 walk(full, depth + 1);
-            else if (e.isFile() && (e.name.endsWith('.ts') || e.name.endsWith('.js') || e.name.endsWith('.tsx') || e.name.endsWith('.jsx'))) {
+            else if (e.isFile() &&
+                (e.name.endsWith('.ts') ||
+                    e.name.endsWith('.js') ||
+                    e.name.endsWith('.tsx') ||
+                    e.name.endsWith('.jsx'))) {
                 out.push(full);
             }
         }
@@ -77,7 +109,15 @@ function walkFiles(root, maxDepth = 8) {
 export function detectLegacy(projectRoot, dir = 'src') {
     const root = resolve(projectRoot, dir);
     if (!existsSync(root)) {
-        const empty = { todo: 0, 'console-log': 0, 'any-type': 0, 'large-file': 0, 'ts-ignore': 0, fixme: 0, hack: 0 };
+        const empty = {
+            todo: 0,
+            'console-log': 0,
+            'any-type': 0,
+            'large-file': 0,
+            'ts-ignore': 0,
+            fixme: 0,
+            hack: 0
+        };
         return { projectRoot, scannedFiles: 0, findings: [], summary: empty, smells: 'low' };
     }
     const files = walkFiles(root);
@@ -88,7 +128,13 @@ export function detectLegacy(projectRoot, dir = 'src') {
     // Re-key console-log to match the union
     const mapped = findings.map((f) => f.kind === 'console-log' ? { ...f, kind: 'console-log' } : f);
     const summary = {
-        todo: 0, 'console-log': 0, 'any-type': 0, 'large-file': 0, 'ts-ignore': 0, fixme: 0, hack: 0
+        todo: 0,
+        'console-log': 0,
+        'any-type': 0,
+        'large-file': 0,
+        'ts-ignore': 0,
+        fixme: 0,
+        hack: 0
     };
     for (const f of mapped) {
         // The todo pattern catches both TODO and FIXME/HACK; reflect into fixme/hack as well when applicable

package/dist/services/lint/detect-eslint.js

@@ -13,9 +13,12 @@ const PACKAGES_TO_PROBE = [
 ];
 function packageNameFor(key) {
     switch (key) {
-        case 'eslint': return 'eslint';
-        case 'typescriptEslintParser': return '@typescript-eslint/parser';
-        case 'typescriptEslintPlugin': return '@typescript-eslint/eslint-plugin';
+        case 'eslint':
+            return 'eslint';
+        case 'typescriptEslintParser':
+            return '@typescript-eslint/parser';
+        case 'typescriptEslintPlugin':
+            return '@typescript-eslint/eslint-plugin';
     }
 }
 function probeNpx() {
@@ -50,7 +53,10 @@ export function detectEslint() {
             npxAvailable: false,
             pinnedVersions: ESLINT_PACKAGE_PINS,
             warnings: ['npx is not on PATH'],
-            nextActions: ['Install Node.js ≥ 20 with npm to enable `npx --package`.', 'Or run `peaks code lint --no-npx` (future slice).']
+            nextActions: [
+                'Install Node.js ≥ 20 with npm to enable `npx --package`.',
+                'Or run `peaks code lint --no-npx` (future slice).'
+            ]
         };
     }
     for (const key of PACKAGES_TO_PROBE) {