peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/crystallization/evidence-brief-builder.js

@@ -0,0 +1,240 @@
+import { z } from "zod";
+import { EvidenceBriefSchema, } from "./crystallization-types.js";
+/**
+ * EvidenceBriefBuilder — spec §4.7 / §10 RL-7.
+ *
+ * The brief is a 4-section natural-language projection that MUST
+ * accompany every user-facing recommendation. The shape guard is
+ * encoded in `EvidenceBriefSchema` (see crystallization-types.ts);
+ * this module is the LLM-side entry point that PRODUCES the brief
+ * from a finished trace + evaluator summary and the validator that
+ * REFUSES to render a recommendation payload without all 4 sections.
+ *
+ * Hard rules (mirrored from spec):
+ *
+ *   1. Every section must be a non-empty NL string (1-2 sentences
+ *      for what_happened / why_it_matters / what_learned; 1
+ *      sentence for what_action). An empty section is a hard
+ *      `MISSING_BRIEF_SECTION` error.
+ *
+ *   2. The build path is lenient on raw prose and strict on the
+ *      final shape — `buildEvidenceBrief` calls
+ *      `EvidenceBriefSchema.parse(...)` so a partial brief throws
+ *      before reaching the database.
+ *
+ *   3. `renderRecommendationPayload` refuses to return a
+ *      recommendation envelope unless the brief passes the 4-section
+ *      guard. This is the CLI's single source of truth for "may I
+ *      show this to the user?".
+ *
+ *   4. The `evaluator_summary` is a separate field on the
+ *      crystallization_event row (spec §4.5) and is NOT part of the
+ *      brief. It feeds the broader recommendation envelope.
+ *
+ * Out of scope (deferred to later slices):
+ *   - LLM-authored brief generation from live trace evidence (M8 dogfood).
+ *   - brief rewrite-on-update semantics.
+ */
+/* ---------------------------------------------------------------------- */
+/* Input shapes — the builder is the only place these normalize.          */
+/* ---------------------------------------------------------------------- */
+/**
+ * The minimum viable trace shape that the builder needs to render
+ * a brief. The trace is the EVIDENCE; the builder is format-stable
+ * so a future slice can swap in a richer trace source without
+ * editing every caller.
+ */
+export const BriefTraceInputSchema = z.object({
+    trace_id: z.string().trim().min(1).max(256),
+    /**
+     * The full NL recap of the run. Required for what_happened.
+     * 1-2 sentences is the spec guidance; the builder does not
+     * truncate, but tests passing multi-paragraph input will be
+     * warned at the Zod boundary (max 4000 chars per section).
+     */
+    what_happened: z.string().trim().min(1).max(4000),
+    /**
+     * The "why this matters" recap. Required for why_it_matters.
+     */
+    why_it_matters: z.string().trim().min(1).max(4000),
+    /**
+     * Failure-mode and preference-extraction recap. Required for
+     * what_learned.
+     */
+    what_learned: z.string().trim().min(1).max(4000),
+    /**
+     * The recommended action. Required for what_action (1
+     * sentence per spec).
+     */
+    what_action: z.string().trim().min(1).max(4000),
+    /**
+     * Optional structured bullets (e.g. "4 phases, 3 gates passed,
+     * 1 evaluator verdict"). Counts are allowed at this layer; the
+     * brief section is the NL primary (RL-7).
+     */
+    bullets: z.array(z.string().trim().min(1).max(1000)).default([]),
+    /**
+     * Source trace ids backing the brief (the column on
+     * crystallization_event spec §4.5).
+     */
+    source_trace_pointers: z
+        .array(z.string().trim().min(1).max(256))
+        .default([]),
+});
+/**
+ * The summary emitted by the independent evaluators (spec §4.5
+ * `evaluator_summary` field). Optional for the brief builder — the
+ * brief can be built without it, but a filled evaluator_summary
+ * flows into the recommendation envelope.
+ */
+export const EvaluatorSummarySchema = z.object({
+    one_liner: z.string().trim().max(1000).default(""),
+    risk_tags: z.array(z.string().trim().min(1).max(200)).default([]),
+});
+/* ---------------------------------------------------------------------- */
+/* Recommendation envelope — the CLI renders this.                       */
+/* ---------------------------------------------------------------------- */
+export const RecommendationPayloadSchema = z.object({
+    brief: EvidenceBriefSchema,
+    bullets: z.array(z.string().trim().min(1).max(1000)).default([]),
+    source_trace_pointers: z
+        .array(z.string().trim().min(1).max(256))
+        .default([]),
+    evaluator_summary: EvaluatorSummarySchema.default({
+        one_liner: "",
+        risk_tags: [],
+    }),
+});
+/* ---------------------------------------------------------------------- */
+/* Errors                                                                 */
+/* ---------------------------------------------------------------------- */
+export class BriefSectionError extends Error {
+    code = "MISSING_BRIEF_SECTION";
+    findings;
+    constructor(message, findings = []) {
+        super(message);
+        this.name = "BriefSectionError";
+        this.findings = findings;
+    }
+}
+/* ---------------------------------------------------------------------- */
+/* Builder                                                                */
+/* ---------------------------------------------------------------------- */
+/**
+ * Build a 4-section EvidenceBrief from a finished trace recap.
+ *
+ * The function is STRICT: it parses the input trace through
+ * `BriefTraceInputSchema`, then parses the assembled brief through
+ * `EvidenceBriefSchema`. Any missing section throws
+ * `BriefSectionError(MISSING_BRIEF_SECTION)` — the same code that
+ * `safeParseEvidenceBrief` returns — so a single error code is the
+ * user-facing signal for "brief incomplete, do not render".
+ *
+ * Brief-section related ZodErrors (e.g. `min(1)` on a section) are
+ * translated to `BriefSectionError` so callers only handle one
+ * shape of failure. Non-section ZodErrors (e.g. invalid `trace_id`)
+ * are re-raised unchanged.
+ *
+ * NOTE: callers who already have raw NL strings can also call
+ * `parseEvidenceBrief` directly; this function is the opinionated
+ * shape for trace -> brief.
+ */
+export function buildEvidenceBrief(trace, evaluatorSummary) {
+    let parsedTrace;
+    try {
+        parsedTrace = BriefTraceInputSchema.parse(trace);
+    }
+    catch (err) {
+        throw translateBriefZodError(err);
+    }
+    // Assemble the 4 sections verbatim from the trace recap. The Zod
+    // parser below re-asserts the 4-section guard.
+    const candidate = {
+        what_happened: parsedTrace.what_happened,
+        why_it_matters: parsedTrace.why_it_matters,
+        what_learned: parsedTrace.what_learned,
+        what_action: parsedTrace.what_action,
+    };
+    const result = EvidenceBriefSchema.safeParse(candidate);
+    if (!result.success) {
+        const findings = result.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        }));
+        throw new BriefSectionError("evidence_brief must contain all 4 sections (what_happened, why_it_matters, what_learned, what_action) with non-empty content (spec §4.7 / RL-7)", findings);
+    }
+    // Silence the unused-var lint on evaluatorSummary at this layer —
+    // the builder currently does not consume it (the brief is NL
+    // primary), but the surface is preserved for callers via
+    // `renderRecommendationPayload` below.
+    void evaluatorSummary;
+    return result.data;
+}
+/**
+ * Translate a ZodError raised on a brief-section path into a
+ * `BriefSectionError`. Non-brief errors are re-raised.
+ */
+function translateBriefZodError(err) {
+    if (err instanceof z.ZodError) {
+        const issues = err.issues;
+        const allBrief = issues.every((i) => BRIEF_SECTION_KEYS.has(i.path.join(".")));
+        if (allBrief) {
+            const findings = issues.map((i) => ({
+                path: i.path.join("."),
+                message: i.message,
+            }));
+            throw new BriefSectionError("evidence_brief must contain all 4 sections (what_happened, why_it_matters, what_learned, what_action) with non-empty content (spec §4.7 / RL-7)", findings);
+        }
+    }
+    throw err;
+}
+const BRIEF_SECTION_KEYS = new Set([
+    "what_happened",
+    "why_it_matters",
+    "what_learned",
+    "what_action",
+]);
+/**
+ * Render the user-facing recommendation envelope (brief + bullets +
+ * trace pointers + evaluator summary). The function refuses to
+ * return a payload unless ALL 4 brief sections are present — this
+ * is the single CLI-facing gate per spec §10 RL-7.
+ *
+ * On success, returns the validated `RecommendationPayload`. On a
+ * missing-section brief, throws `BriefSectionError`.
+ */
+export function renderRecommendationPayload(trace, evaluatorSummary = { one_liner: "", risk_tags: [] }) {
+    const brief = buildEvidenceBrief(trace, evaluatorSummary);
+    const payload = RecommendationPayloadSchema.parse({
+        brief,
+        bullets: trace.bullets ?? [],
+        source_trace_pointers: trace.source_trace_pointers ?? [],
+        evaluator_summary: evaluatorSummary,
+    });
+    return payload;
+}
+/**
+ * Convenience: validate an arbitrary unknown payload AS IF it were a
+ * recommendation envelope. Returns a Result-like shape so the CLI can
+ * render a structured MISSING_BRIEF_SECTION error without try/catch
+ * noise.
+ */
+export function safeRenderRecommendationPayload(input) {
+    const r = RecommendationPayloadSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, payload: r.data };
+    const findings = r.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+    }));
+    // Map brief failures to MISSING_BRIEF_SECTION. A failure is
+    // recognized as brief iff (a) every issue points at the brief or
+    // its sections, OR (b) the explicit refine message is present.
+    const isBrief = r.error.issues.every((i) => i.message.includes("evidence_brief must contain all 4 sections") ||
+        BRIEF_SECTION_KEYS.has(i.path.join(".")) ||
+        i.path[0] === "brief" ||
+        (i.path.length >= 2 && i.path[0] === "brief"));
+    return isBrief
+        ? { ok: false, code: "MISSING_BRIEF_SECTION", findings }
+        : { ok: false, findings };
+}

package/dist/services/dispatch/batch-counter.js

@@ -0,0 +1,102 @@
+/**
+ * G5.1 / RL-1 — batch size counter.
+ *
+ * Empirical upper bound for one Dispatcher × one batch: 6 sub-agents.
+ * Above 6, the LLM / human is encouraged to split into multiple
+ * batches with an explicit reducer step in between. peaks-code's
+ * swarm phase dispatches 3; peaks-rd's 4-way fan-out dispatches 4;
+ * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves headroom
+ * for "qa-business-api" / "qa-business-frontend" / "qa-business-regression"
+ * subdivisions (3-way + 3-way = 6) without crossing the line.
+ *
+ * The counter is in-memory per process. The Dispatcher is expected
+ * to call `noteDispatched` once per `peaks sub-agent dispatch` and
+ * reset between batches. The CLI also persists a small per-sid
+ * counter file so that sub-agent spawns invoked across multiple
+ * `peaks sub-agent dispatch` processes within the same batch can be
+ * tallied (the batch id ties them together).
+ *
+ * `BATCH_OVER_LIMIT` is a warning, not a hard fail. The user has been
+ * explicit: "RL-1 is empirical; if you have a real reason to go to 7,
+ * that's your call". A warning is the right surface — let the LLM /
+ * human read the reason and decide.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { withFileLockSync } from '../filesystem/file-lock.js';
+export const BATCH_LIMIT = 6;
+export const BATCH_OVER_LIMIT_CODE = 'BATCH_OVER_LIMIT';
+/** Build the per-batch counter file path. */
+export function batchCounterPath(projectRoot, sid, batchId) {
+    return resolve(projectRoot, '.peaks', '_sub_agents', sid, `batch-${batchId}.counter.json`);
+}
+/** Read the current counter; returns 0 if no file yet. */
+export function readBatchCount(projectRoot, sid, batchId) {
+    const path = batchCounterPath(projectRoot, sid, batchId);
+    if (!existsSync(path))
+        return 0;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return typeof parsed.count === 'number' && parsed.count >= 0 ? parsed.count : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Increment the counter and return the new value (with any warning). */
+export function noteDispatched(projectRoot, sid, batchId, now = () => new Date()) {
+    const path = batchCounterPath(projectRoot, sid, batchId);
+    // Slice 2026-06-23-audit-4th #A1: wrap the read-modify-write in a
+    // file lock. Two concurrent `peaks sub-agent dispatch` invocations
+    // for the same (sid, batchId) would otherwise race — both call
+    // readBatchCount first, both see the same N, both write N+1, and
+    // the second write clobbers the first (lost update). The BATCH_OVER_LIMIT
+    // warning fires for the wrong threshold when this happens. The lock
+    // serializes the writes; contention is rare (only when a single
+    // batch is dispatched in parallel from the same LLM) so the spin-wait
+    // cost is bounded by MAX_LOCK_RETRIES * LOCK_RETRY_MAX_MS.
+    return withFileLockSync(path, () => {
+        const previous = readBatchCount(projectRoot, sid, batchId);
+        const next = {
+            batchId,
+            sessionId: sid,
+            createdAt: now().toISOString(),
+            count: previous + 1
+        };
+        // mkdirSync is conditional via the lock helper (it ensures the
+        // parent dir exists), but the counter file may live in a session
+        // sub-dir that the lock helper's recursive mkdir handles. Belt +
+        // suspenders: keep the explicit mkdir here so the path resolves
+        // even if withFileLockSync's mkdir is bypassed in the future.
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+        if (next.count > BATCH_LIMIT) {
+            return {
+                count: next.count,
+                warning: {
+                    code: BATCH_OVER_LIMIT_CODE,
+                    batchId,
+                    dispatched: next.count,
+                    limit: BATCH_LIMIT,
+                    message: `per RL-1, batch size 6 is empirical upper bound; you have ` +
+                        `${next.count}. If you need more, split into multiple batches ` +
+                        `with an explicit reducer step between them.`
+                }
+            };
+        }
+        return { count: next.count, warning: null };
+    });
+}
+/** Reset a batch counter (called by the reducer when starting a new batch). */
+export function resetBatch(projectRoot, sid, batchId) {
+    const path = batchCounterPath(projectRoot, sid, batchId);
+    if (existsSync(path)) {
+        try {
+            const { unlinkSync } = require('node:fs');
+            unlinkSync(path);
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort; counter file is informational */
+        }
+    }
+}

package/dist/services/dispatch/leak-detector.js

@@ -0,0 +1,72 @@
+/**
+ * Slice #009 / G5 RL-7 — dispatch record leak detector.
+ *
+ * After peaks-code's reducer consumes a batch, any dispatch record that
+ * is still `disposed === false` AND was created more than `thresholdMs`
+ * ago is a **leak**. This helper scans the on-disk records under
+ * `.peaks/_sub_agents/<sid>/` and returns the leaked ones. The CLI or
+ * the reducer's next-batch step emits a user-visible warning when the
+ * list is non-empty.
+ *
+ * Threshold: 1h (configurable). Rationale: the longest empirical
+ * peaks-rd / peaks-qa fan-out + reducer cycle is < 60s; the threshold
+ * gives slow slices headroom without hiding leaks for the next session.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDispatchStatus, isOutcome } from './dispatch-record-writer.js';
+export const DEFAULT_LEAK_THRESHOLD_MS = 60 * 60 * 1000; // 1 hour
+export function findLeakedDispatchRecords(projectRoot, sessionId, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const thresholdMs = options.thresholdMs ?? DEFAULT_LEAK_THRESHOLD_MS;
+    const nowMs = now().getTime();
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sessionId);
+    if (!existsSync(dir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+            continue;
+        const fullPath = join(dir, entry);
+        let raw;
+        try {
+            raw = readFileSync(fullPath, 'utf8');
+        }
+        catch {
+            continue; // skip unreadable files
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            continue; // skip malformed files
+        }
+        if (!isRecordShape(parsed))
+            continue;
+        if (parsed.disposed === true)
+            continue;
+        const createdMs = Date.parse(parsed.createdAt);
+        if (Number.isNaN(createdMs))
+            continue;
+        const ageMs = nowMs - createdMs;
+        if (ageMs < thresholdMs)
+            continue;
+        out.push({ path: fullPath, record: parsed, ageMs });
+    }
+    return out;
+}
+function isRecordShape(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const obj = v;
+    return (typeof obj.createdAt === 'string' &&
+        typeof obj.role === 'string' &&
+        typeof obj.requestId === 'string' &&
+        typeof obj.sessionId === 'string' &&
+        typeof obj.prompt === 'string' &&
+        isOutcome(obj.outcome) &&
+        isDispatchStatus(obj.status) &&
+        typeof obj.disposed === 'boolean' &&
+        Array.isArray(obj.artifactPaths));
+}

package/dist/services/dispatch/slice-dag.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Slice complexity tier (v2.15.0 follow-up, G2 in 12 Gaps).
+ * Used by Code to schedule complex slices during user-attended hours
+ * and trivial / simple slices overnight.
+ */
+export type SliceComplexity = 'trivial' | 'simple' | 'complex';
+export declare const SLICE_COMPLEXITIES: readonly SliceComplexity[];
+export declare function isSliceComplexity(value: string): value is SliceComplexity;
+export interface SliceNode {
+    readonly id: string;
+    readonly role: string;
+    /** Human-readable label, optional. */
+    readonly label?: string;
+    /** Optional prompt override; dispatch falls back to a default placeholder. */
+    readonly prompt?: string;
+    /**
+     * v2.15.0 follow-up — G12: foundation slice. Foundation slices run before
+     * business slices in the layered DAG. Business slices do NOT wait for
+     * ALL foundation slices — they wait only for the foundation subset
+     * they declare as `dependsOn`. Optional; default false.
+     */
+    readonly foundation?: boolean;
+    /**
+     * v2.15.0 follow-up — G11: upstream sync slice. Marks a slice that
+     * syncs an upstream fork (e.g. hermes) to a new tag. UpstreamSync
+     * slices take priority within their topological level. Optional.
+     */
+    readonly upstreamSync?: boolean;
+    /**
+     * v2.15.0 follow-up — G2: complexity tier. Drives Code's scheduling
+     * (complex = user-attended, simple/trivial = overnight). Optional.
+     */
+    readonly complexity?: SliceComplexity;
+}
+export interface DependsOn {
+    readonly from: string;
+    readonly to: string;
+}
+export interface SliceDag {
+    readonly nodes: readonly SliceNode[];
+    readonly edges: readonly DependsOn[];
+}
+/** Thrown by `validateDag` when the graph violates one of the constraints. */
+export declare class InvalidSliceDagError extends Error {
+    readonly path?: readonly string[] | undefined;
+    readonly code: "INVALID_SLICE_DAG";
+    constructor(message: string, path?: readonly string[] | undefined);
+}
+/** Thrown by `topologicalLevels` when the graph has a cycle (defensive). */
+export declare class SliceDagCycleError extends Error {
+    readonly cyclePath: readonly string[];
+    readonly code: "SLICE_DAG_CYCLE";
+    constructor(cyclePath: readonly string[]);
+}
+/**
+ * Validate a SliceDag. Throws `InvalidSliceDagError` on the first violation.
+ * Pure. Cheap. No I/O.
+ */
+export declare function validateDag(dag: SliceDag): void;
+/**
+ * Compute topological levels. Each level is an array of node IDs that can
+ * run in parallel. Throws `SliceDagCycleError` on cycle (defensive;
+ * `validateDag` should have caught it).
+ *
+ * Algorithm: Kahn's algorithm. O(V + E).
+ */
+export declare function topologicalLevels(dag: SliceDag): readonly (readonly string[])[];
+/**
+ * Return the next set of node IDs that are ready to run given the set of
+ * completed node IDs. A node is ready when all of its `from` predecessors
+ * are in `completed`.
+ */
+export declare function sliceReadyToRun(dag: SliceDag, completed: ReadonlySet<string>): readonly string[];
+/**
+ * Serialize the DAG into a deterministic JSON string. Node IDs are sorted;
+ * edges are sorted by `(from, to)`. The result is suitable for SHA-256
+ * hashing and for byte-stable diffs.
+ */
+export declare function serializeDag(dag: SliceDag): string;
+/** SHA-256 hash of the serialized DAG. Stable across runs. */
+export declare function hashDag(dag: SliceDag): string;

package/dist/services/dispatch/test-tool-detection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Slice 2026-06-24-test-tool-detection-injection.
+ *
+ * The Test Tool Detection block is prepended to every sub-agent prompt
+ * dispatched by peaks-loop (both the single-dispatch chokepoint in
+ * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
+ * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
+ * to read `package.json#scripts.test` first and use the project-local
+ * runner — never `npx <runner>` — so it cannot bypass the lockfile or
+ * spawn a network-bound tool call.
+ *
+ * Why a static constant (not a per-call detector):
+ *  1. Predictable byte budget — the block is part of PROMPT_LIMIT_BYTES
+ *     accounting (see dispatch-commands.ts line 113), and the size must
+ *     be stable across calls.
+ *  2. I/O-free — dispatch is a hot path; reading package.json here would
+ *     add a filesystem hit per dispatch and run before the LLM has any
+ *     context to act on the result.
+ *  3. LLM does runtime lookup — the block itself instructs the sub-agent
+ *     to introspect `package.json#scripts.test` (or `peaks test --json`)
+ *     at run time, so the LLM gets the resolved framework + argv with
+ *     its full context. The dispatch CLI just primes the instruction.
+ *
+ * Why every sub-agent gets the block (Karpathy #2 Simplicity First):
+ *  the rule is machine-injected, not a prompt ritual. The LLM cannot
+ *  "remove the redundancy" of a test-tool-detection instruction because
+ *  the dispatch CLI always prepends it. This is a guarantee, not a
+ *  suggestion.
+ */
+export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
+/**
+ * Pure helper that returns the block. Exists as a function (not just an
+ * exported constant) so future variants can take a runtime parameter
+ * (e.g. projectRoot for context) without churning every call site.
+ */
+export declare function formatTestToolDetection(): string;

package/dist/services/dispatch/test-tool-detection.js

@@ -0,0 +1,46 @@
+/**
+ * Slice 2026-06-24-test-tool-detection-injection.
+ *
+ * The Test Tool Detection block is prepended to every sub-agent prompt
+ * dispatched by peaks-loop (both the single-dispatch chokepoint in
+ * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
+ * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
+ * to read `package.json#scripts.test` first and use the project-local
+ * runner — never `npx <runner>` — so it cannot bypass the lockfile or
+ * spawn a network-bound tool call.
+ *
+ * Why a static constant (not a per-call detector):
+ *  1. Predictable byte budget — the block is part of PROMPT_LIMIT_BYTES
+ *     accounting (see dispatch-commands.ts line 113), and the size must
+ *     be stable across calls.
+ *  2. I/O-free — dispatch is a hot path; reading package.json here would
+ *     add a filesystem hit per dispatch and run before the LLM has any
+ *     context to act on the result.
+ *  3. LLM does runtime lookup — the block itself instructs the sub-agent
+ *     to introspect `package.json#scripts.test` (or `peaks test --json`)
+ *     at run time, so the LLM gets the resolved framework + argv with
+ *     its full context. The dispatch CLI just primes the instruction.
+ *
+ * Why every sub-agent gets the block (Karpathy #2 Simplicity First):
+ *  the rule is machine-injected, not a prompt ritual. The LLM cannot
+ *  "remove the redundancy" of a test-tool-detection instruction because
+ *  the dispatch CLI always prepends it. This is a guarantee, not a
+ *  suggestion.
+ */
+export const TEST_TOOL_DETECTION_BLOCK = `## Test Tool Detection (mandatory)
+
+Before running any test, read \`package.json#scripts.test\` to identify the project's test framework. Use the project-local runner — do NOT invoke \`npx <runner>\`:
+
+- **vitest** → \`./node_modules/.bin/vitest run <file>\` (or \`pnpm test -- <file>\`)
+- **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
+- **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
+
+If unsure which framework the consumer project uses, run \`peaks test --json\` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command \`peaks test <file>\` already resolves the local binary for you (Windows-aware).`;
+/**
+ * Pure helper that returns the block. Exists as a function (not just an
+ * exported constant) so future variants can take a runtime parameter
+ * (e.g. projectRoot for context) without churning every call site.
+ */
+export function formatTestToolDetection() {
+    return TEST_TOOL_DETECTION_BLOCK;
+}