peaks-loop 3.0.0

package/dist/src/services/context/threshold.js

@@ -0,0 +1,76 @@
+/**
+ * G9.3 — forced compression gate threshold constants + tier evaluation.
+ *
+ * 256K default context capacity is a conservative proxy. The LLM's real
+ * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
+ * inherited from slice #009); we use prompt size as the gate signal.
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
+ * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
+ */
+export const CONTEXT_CAPACITY_DEFAULT_BYTES = 256 * 1024; // 256K
+export const THRESHOLD_SOFT_WARN_RATIO = 0.5; // 50%
+export const THRESHOLD_NEAR_LIMIT_RATIO = 0.75; // 75% — user red line
+export const THRESHOLD_HARD_REJECT_RATIO = 0.80; // 80%
+export const THRESHOLD_EMERGENCY_RATIO = 0.90; // 90%
+/**
+ * Compute the threshold tier for a given prompt size. Pure function
+ * (no IO, no side effects). The `capacityBytes` parameter lets callers
+ * override the default 256K proxy (e.g. for testing or for a future
+ * per-IDE capacity override).
+ */
+export function evaluateThresholdTier(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
+    if (!Number.isFinite(promptSize) || promptSize < 0) {
+        throw new Error(`evaluateThresholdTier: promptSize must be ≥ 0 (got ${promptSize})`);
+    }
+    if (!Number.isFinite(capacityBytes) || capacityBytes <= 0) {
+        throw new Error(`evaluateThresholdTier: capacityBytes must be > 0 (got ${capacityBytes})`);
+    }
+    const ratio = promptSize / capacityBytes;
+    const warnings = [];
+    let tier;
+    if (ratio >= THRESHOLD_EMERGENCY_RATIO) {
+        tier = 'emergency';
+        warnings.push('PROMPT_EMERGENCY');
+    }
+    else if (ratio >= THRESHOLD_HARD_REJECT_RATIO) {
+        tier = 'hard-reject';
+        warnings.push('PROMPT_TOO_LARGE');
+    }
+    else if (ratio >= THRESHOLD_NEAR_LIMIT_RATIO) {
+        tier = 'near-limit';
+        warnings.push('CONTEXT_NEAR_LIMIT');
+    }
+    else if (ratio >= THRESHOLD_SOFT_WARN_RATIO) {
+        tier = 'soft-warn';
+        warnings.push('CONTEXT_SOFT_WARN');
+    }
+    else {
+        tier = 'ok';
+    }
+    return {
+        tier,
+        ratio,
+        bytesUsed: promptSize,
+        capacityBytes,
+        warnings
+    };
+}
+/**
+ * Convert a threshold tier to a machine-readable code suitable for the
+ * CLI envelope's `code` field. Used by both the CLI and the hook layer.
+ */
+export function tierToCode(tier) {
+    switch (tier) {
+        case 'ok':
+            return 'OK';
+        case 'soft-warn':
+            return 'CONTEXT_SOFT_WARN';
+        case 'near-limit':
+            return 'CONTEXT_NEAR_LIMIT';
+        case 'hard-reject':
+            return 'PROMPT_TOO_LARGE';
+        case 'emergency':
+            return 'PROMPT_EMERGENCY';
+    }
+}

package/dist/src/services/context/tokenizer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per spec §4.1 Step 3 — Tokenizer (non-mutating).
+ *
+ * Hard constraint H3: structured metadata > bare strings. Each collector
+ * artifact and each fetched doc gets a tokenized metadata record so
+ * peaks-rd/qa can do relative-anomaly detection later.
+ *
+ * Immutability H (common/coding-style): the output is frozen so callers
+ * cannot mutate it. Use spread to derive new outputs in future slices.
+ */
+import type { CollectorOutput, DocRetrieverOutput, TokenizerOutput } from './types.js';
+export declare function tokenize(collector: CollectorOutput, docRetriever: DocRetrieverOutput, now?: Date): TokenizerOutput;

package/dist/src/services/context/tokenizer.js

@@ -0,0 +1,43 @@
+function freshDecayScore(fetchedAt, now) {
+    const ageMs = now.getTime() - new Date(fetchedAt).getTime();
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    // Linear decay: 1.0 at day 0, 0.5 at day 30, 0.0 at day 60+
+    if (ageDays >= 60)
+        return 0;
+    return Math.max(0, 1 - ageDays / 60);
+}
+export function tokenize(collector, docRetriever, now = new Date()) {
+    const metadata = [];
+    for (const doc of docRetriever.fetchedDocs) {
+        metadata.push({
+            id: `doc:${doc.dep}@${doc.version}`,
+            kind: 'doc',
+            version: doc.version,
+            blastRadius: doc.sections.map((s) => s.title),
+            conflictScore: 0, // v1: no cross-source conflict detection yet
+            timeDecayScore: freshDecayScore(doc.fetchedAt, now),
+            tags: ['fetched', doc.source, doc.stale ? 'stale' : 'fresh'],
+        });
+    }
+    for (const mem of collector.memoryEntries) {
+        metadata.push({
+            id: `memory:${mem.path}`,
+            kind: 'memory',
+            blastRadius: [mem.title],
+            conflictScore: 0,
+            timeDecayScore: mem.relevanceScore,
+            tags: ['memory'],
+        });
+    }
+    for (const file of collector.files) {
+        metadata.push({
+            id: `code:${file.path}`,
+            kind: 'code',
+            blastRadius: [file.path],
+            conflictScore: 0,
+            timeDecayScore: 1,
+            tags: [file.kind],
+        });
+    }
+    return Object.freeze({ metadata: Object.freeze(metadata) });
+}

package/dist/src/services/context/types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Per spec §4.1 — the single source of truth for context.json shape.
+ * The Zod schema in context-schema.ts must mirror this interface exactly;
+ * the schema is the runtime validator, the interface is the compile-time contract.
+ *
+ * Hard constraint H8: Audit trail must be hashable. `sha256` is the field
+ * that lets peaks-state-lock chain signatures between stages.
+ */
+export type ContextVersion = '1.0';
+export type Audience = 'peaks-rd' | 'peaks-qa' | 'peaks-mut' | 'all';
+export type DepsMode = 'locked' | 'latest';
+export type FileKind = 'source' | 'test' | 'config' | 'doc';
+export interface CollectedFile {
+    readonly path: string;
+    readonly kind: FileKind;
+    readonly lines: number;
+    readonly hash: string;
+}
+export interface GitStatus {
+    readonly branch: string;
+    readonly lastCommit: string;
+    readonly dirty: boolean;
+}
+export interface MemoryEntry {
+    readonly path: string;
+    readonly title: string;
+    readonly relevanceScore: number;
+    readonly excerptHash: string;
+}
+export interface DepInfo {
+    readonly version: string;
+    readonly source: 'package.json' | 'pnpm-lock.yaml' | 'yarn.lock';
+    readonly resolved: string;
+}
+export interface DocSection {
+    readonly title: string;
+    readonly tokenEstimate: number;
+    readonly excerpt: string;
+}
+export interface FetchedDoc {
+    readonly dep: string;
+    readonly version: string;
+    readonly source: 'local-cache' | 'remote-fetch';
+    readonly url?: string;
+    readonly fetchedAt: string;
+    readonly contentHash: string;
+    readonly sections: ReadonlyArray<DocSection>;
+    readonly stale: boolean;
+}
+export interface SkippedDoc {
+    readonly dep: string;
+    readonly reason: 'unconfigured' | 'network_error' | 'version_unknown';
+}
+export type MetaKind = 'doc' | 'code' | 'memory' | 'git';
+export interface TokenizedItem {
+    readonly id: string;
+    readonly kind: MetaKind;
+    readonly version?: string;
+    readonly blastRadius: ReadonlyArray<string>;
+    readonly conflictScore: number;
+    readonly timeDecayScore: number;
+    readonly tags: ReadonlyArray<string>;
+}
+export interface CollectorOutput {
+    readonly files: ReadonlyArray<CollectedFile>;
+    readonly gitStatus: GitStatus;
+    readonly memoryEntries: ReadonlyArray<MemoryEntry>;
+    readonly deps: Readonly<Record<string, DepInfo>>;
+}
+export interface DocRetrieverOutput {
+    readonly fetchedDocs: ReadonlyArray<FetchedDoc>;
+    readonly skipped: ReadonlyArray<SkippedDoc>;
+}
+export interface TokenizerOutput {
+    readonly metadata: ReadonlyArray<TokenizedItem>;
+}
+export interface RendererOutput {
+    readonly audience: Audience;
+    readonly renderedAt: string;
+    readonly sizeBytes: number;
+    readonly truncated: boolean;
+    readonly truncatedReason?: 'doc_budget_exceeded' | 'section_count_exceeded';
+}
+export interface ContextJson {
+    readonly version: ContextVersion;
+    readonly goal: string;
+    readonly generatedAt: string;
+    readonly sha256: string;
+    readonly collector: CollectorOutput;
+    readonly docRetriever: DocRetrieverOutput;
+    readonly tokenizer: TokenizerOutput;
+    readonly renderer: RendererOutput;
+}

package/dist/src/services/context/types.js

@@ -0,0 +1,9 @@
+/**
+ * Per spec §4.1 — the single source of truth for context.json shape.
+ * The Zod schema in context-schema.ts must mirror this interface exactly;
+ * the schema is the runtime validator, the interface is the compile-time contract.
+ *
+ * Hard constraint H8: Audit trail must be hashable. `sha256` is the field
+ * that lets peaks-state-lock chain signatures between stages.
+ */
+export {};

package/dist/src/services/dashboard/project-dashboard-service.d.ts

@@ -0,0 +1,91 @@
+import { type RequestArtifactRole, type RequestArtifactSummary } from '../artifacts/request-artifact-service.js';
+import type { OpenSpecChangeSummary } from '../openspec/openspec-types.js';
+import type { CapabilityItem } from '../recommendations/recommendation-types.js';
+import { type SkillPresence } from '../skills/skill-presence-service.js';
+export type ProjectDashboardRequests = {
+    count: number;
+    byRole: Record<RequestArtifactRole, RequestArtifactSummary[]>;
+    byState: Record<string, number>;
+};
+export type ProjectDashboardOpenSpec = {
+    exists: boolean;
+    count: number;
+    changes: OpenSpecChangeSummary[];
+};
+export type ProjectDashboardUnderstand = {
+    exists: boolean;
+    graphExists: boolean;
+    graphPath: string;
+    parseError?: string;
+};
+export type ProjectDashboardDoctor = {
+    ok: boolean;
+    passed: number;
+    failed: number;
+    okCount?: number;
+    failCount?: number;
+    lastRunAt?: string;
+    checkIds?: string[];
+};
+export type DashboardOkPolicy = 'workspace-only' | 'strict';
+/**
+ * Resolves the user-facing `ok` field. `workspace-only` (default) returns true
+ * when the runbook / workspace layout is healthy, even if 1-2 non-blocking
+ * doctor checks fail. `strict` returns false when the doctor aggregate fails.
+ * The CLI default is `workspace-only`; `peaks project dashboard --strict`
+ * restores the legacy aggregate semantics.
+ */
+export declare function resolveDashboardOk(args: {
+    okPolicy: DashboardOkPolicy;
+    doctor: ProjectDashboardDoctor;
+    runbookHealth: ProjectDashboardRunbookHealth;
+}): {
+    ok: boolean;
+    okPolicy: DashboardOkPolicy;
+};
+export type ProjectDashboardRunbookHealth = {
+    ok: boolean;
+    required: number;
+    healthy: number;
+    missingRunbook: string[];
+    applyNoteFailed: string[];
+};
+export type ProjectDashboardCapabilities = {
+    count: number;
+    sample: Array<Pick<CapabilityItem, 'capabilityId' | 'name' | 'itemType' | 'category'>>;
+};
+export type ProjectDashboardSkillPresence = {
+    active: boolean;
+    fresh: boolean;
+    skill?: string;
+    mode?: string;
+    gate?: string;
+    setAt?: string;
+};
+export type ProjectDashboard = {
+    generatedAt: string;
+    projectRoot: string;
+    ok: boolean;
+    okPolicy: DashboardOkPolicy;
+    requests: ProjectDashboardRequests;
+    openspec: ProjectDashboardOpenSpec;
+    understand: ProjectDashboardUnderstand;
+    doctor: ProjectDashboardDoctor;
+    runbookHealth: ProjectDashboardRunbookHealth;
+    capabilities: ProjectDashboardCapabilities;
+    skillPresence: ProjectDashboardSkillPresence;
+};
+export type LoadProjectDashboardOptions = {
+    projectRoot: string;
+    sampleCapabilities?: number;
+    clock?: () => string;
+    doctorReport?: {
+        ok: boolean;
+        passed: number;
+        failed: number;
+    };
+    runbookHealth?: ProjectDashboardRunbookHealth;
+    skillPresence?: SkillPresence | null;
+    okPolicy?: DashboardOkPolicy;
+};
+export declare function loadProjectDashboard(options: LoadProjectDashboardOptions): Promise<ProjectDashboard>;

package/dist/src/services/dashboard/project-dashboard-service.js

@@ -0,0 +1,147 @@
+import { listRequestArtifacts } from '../artifacts/request-artifact-service.js';
+import { scanOpenSpec } from '../openspec/openspec-scan-service.js';
+import { scanUnderstandAnything } from '../understand/understand-scan-service.js';
+import { seedCapabilityItems } from '../recommendations/capability-seed-items.js';
+import { requiredSkillNames } from '../../shared/paths.js';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+const SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+/**
+ * Resolves the user-facing `ok` field. `workspace-only` (default) returns true
+ * when the runbook / workspace layout is healthy, even if 1-2 non-blocking
+ * doctor checks fail. `strict` returns false when the doctor aggregate fails.
+ * The CLI default is `workspace-only`; `peaks project dashboard --strict`
+ * restores the legacy aggregate semantics.
+ */
+export function resolveDashboardOk(args) {
+    if (args.okPolicy === 'strict') {
+        return { ok: args.doctor.ok && args.runbookHealth.ok, okPolicy: 'strict' };
+    }
+    return { ok: args.runbookHealth.ok, okPolicy: 'workspace-only' };
+}
+function defaultClock() {
+    return new Date().toISOString();
+}
+function groupRequestsByRole(items) {
+    const byRole = { prd: [], ui: [], rd: [], qa: [], sc: [] };
+    for (const item of items) {
+        byRole[item.role].push(item);
+    }
+    return byRole;
+}
+function countRequestsByState(items) {
+    const counts = {};
+    for (const item of items) {
+        counts[item.state] = (counts[item.state] ?? 0) + 1;
+    }
+    return counts;
+}
+async function loadDoctorAndRunbookHealth(doctorOverride, runbookOverride) {
+    if (doctorOverride !== undefined && runbookOverride !== undefined) {
+        return { doctor: doctorOverride, runbookHealth: runbookOverride };
+    }
+    if (doctorOverride !== undefined) {
+        return {
+            doctor: doctorOverride,
+            runbookHealth: { ok: true, required: 0, healthy: 0, missingRunbook: [], applyNoteFailed: [] }
+        };
+    }
+    const { runDoctor } = await import('../doctor/doctor-service.js');
+    const report = await runDoctor();
+    return {
+        doctor: { ok: report.summary.ok, passed: report.summary.passed, failed: report.summary.failed },
+        runbookHealth: runbookOverride ?? summarizeRunbookHealth(report.checks)
+    };
+}
+function summarizeRunbookHealth(checks) {
+    const missingRunbook = [];
+    const applyNoteFailed = [];
+    for (const check of checks) {
+        if (!check.ok && check.id.startsWith('skill-runbook:')) {
+            missingRunbook.push(check.id.slice('skill-runbook:'.length));
+        }
+        if (!check.ok && check.id.startsWith('skill-apply-note:')) {
+            applyNoteFailed.push(check.id.slice('skill-apply-note:'.length));
+        }
+    }
+    const required = requiredSkillNames.length;
+    const healthy = Math.max(0, required - missingRunbook.length - applyNoteFailed.length);
+    return {
+        ok: missingRunbook.length === 0 && applyNoteFailed.length === 0,
+        required,
+        healthy,
+        missingRunbook,
+        applyNoteFailed
+    };
+}
+function buildCapabilitiesSummary(sampleSize) {
+    const items = seedCapabilityItems;
+    return {
+        count: items.length,
+        sample: items.slice(0, sampleSize).map((item) => ({
+            capabilityId: item.capabilityId,
+            name: item.name,
+            itemType: item.itemType,
+            category: item.category
+        }))
+    };
+}
+function buildSkillPresenceSummary(presence, projectRoot) {
+    // When the caller doesn't supply presence, resolve it from the dashboard's
+    // project root rather than the process cwd.
+    const resolved = presence === undefined ? getSkillPresence(projectRoot) : presence;
+    if (resolved === null) {
+        return { active: false, fresh: true };
+    }
+    const setAtMs = Date.parse(resolved.setAt);
+    const fresh = !Number.isNaN(setAtMs) && Date.now() - setAtMs <= SKILL_PRESENCE_FRESHNESS_THRESHOLD_MS;
+    return {
+        active: true,
+        fresh,
+        skill: resolved.skill,
+        ...(resolved.mode !== undefined ? { mode: resolved.mode } : {}),
+        ...(resolved.gate !== undefined ? { gate: resolved.gate } : {}),
+        setAt: resolved.setAt
+    };
+}
+export async function loadProjectDashboard(options) {
+    const clock = options.clock ?? defaultClock;
+    const sampleSize = options.sampleCapabilities ?? 8;
+    const okPolicy = options.okPolicy ?? 'workspace-only';
+    const [items, openspecReport, understandReport, doctorAndRunbook] = await Promise.all([
+        listRequestArtifacts({ projectRoot: options.projectRoot }),
+        scanOpenSpec({ openspecRoot: `${options.projectRoot}/openspec` }),
+        scanUnderstandAnything({ projectRoot: options.projectRoot }),
+        loadDoctorAndRunbookHealth(options.doctorReport, options.runbookHealth)
+    ]);
+    const okVerdict = resolveDashboardOk({
+        okPolicy,
+        doctor: doctorAndRunbook.doctor,
+        runbookHealth: doctorAndRunbook.runbookHealth
+    });
+    return {
+        generatedAt: clock(),
+        projectRoot: options.projectRoot,
+        ok: okVerdict.ok,
+        okPolicy: okVerdict.okPolicy,
+        requests: {
+            count: items.length,
+            byRole: groupRequestsByRole(items),
+            byState: countRequestsByState(items)
+        },
+        openspec: {
+            exists: openspecReport.exists,
+            count: openspecReport.changes.length,
+            changes: openspecReport.changes
+        },
+        understand: {
+            exists: understandReport.exists,
+            graphExists: understandReport.graph.exists,
+            graphPath: understandReport.graph.path,
+            ...(understandReport.graph.parseError !== undefined ? { parseError: understandReport.graph.parseError } : {})
+        },
+        doctor: doctorAndRunbook.doctor,
+        runbookHealth: doctorAndRunbook.runbookHealth,
+        capabilities: buildCapabilitiesSummary(sampleSize),
+        skillPresence: buildSkillPresenceSummary(options.skillPresence, options.projectRoot)
+    };
+}

package/dist/src/services/dispatch/batch-counter.d.ts

@@ -0,0 +1,27 @@
+export declare const BATCH_LIMIT = 6;
+export declare const BATCH_OVER_LIMIT_CODE = "BATCH_OVER_LIMIT";
+export type BatchCounterWarning = {
+    readonly code: typeof BATCH_OVER_LIMIT_CODE;
+    readonly batchId: string;
+    readonly dispatched: number;
+    readonly limit: number;
+    readonly message: string;
+};
+/** Build the per-batch counter file path. */
+export declare function batchCounterPath(projectRoot: string, sid: string, batchId: string): string;
+/** A single batch counter record. */
+export interface BatchCounterRecord {
+    readonly batchId: string;
+    readonly sessionId: string;
+    readonly createdAt: string;
+    readonly count: number;
+}
+/** Read the current counter; returns 0 if no file yet. */
+export declare function readBatchCount(projectRoot: string, sid: string, batchId: string): number;
+/** Increment the counter and return the new value (with any warning). */
+export declare function noteDispatched(projectRoot: string, sid: string, batchId: string, now?: () => Date): {
+    count: number;
+    warning: BatchCounterWarning | null;
+};
+/** Reset a batch counter (called by the reducer when starting a new batch). */
+export declare function resetBatch(projectRoot: string, sid: string, batchId: string): void;

package/dist/src/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-solo'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/src/services/dispatch/contract-store.d.ts

@@ -0,0 +1,63 @@
+/** Public surface of a finished slice. */
+export interface SliceContract {
+    readonly sliceId: string;
+    readonly sessionId: string;
+    readonly completedAt: string;
+    /** Public exports (function / class / const / var names). */
+    readonly exports: readonly string[];
+    /** Public type names. */
+    readonly types: readonly string[];
+    /** Public function / method signatures, e.g. `"validateDag(dag: SliceDag): void"`. */
+    readonly publicSignatures: readonly string[];
+    /** Optional: which downstream slice IDs the contract is broadcast-ready for. */
+    readonly broadcastTo?: readonly string[];
+    /** SHA-256 hash of the contract payload (key-sorted, JSON-canonicalized). */
+    readonly contractHash: string;
+}
+export type WriteContractInput = Omit<SliceContract, 'completedAt' | 'contractHash'> & {
+    readonly completedAt?: string;
+};
+/** Thrown when contract IO fails. */
+export declare class ContractStoreError extends Error {
+    readonly code: "CONTRACT_STORE_ERROR";
+    constructor(message: string);
+}
+/** Slice 2026-06-23-audit-4th #A3: default TTL for slice contracts. */
+export declare const CONTRACT_TTL_DAYS = 30;
+/**
+ * Slice 2026-06-23-audit-4th #A3: is this contract an orphan
+ * (older than CONTRACT_TTL_DAYS or already GC'd)? Mirrors
+ * `isOrphanChannel` and `isOrphanDispatchRecord` so a future
+ * `peaks sub-agent cleanup` umbrella can run all three sweeps
+ * (shared channel + dispatch record + contract) in one pass.
+ */
+export declare function isOrphanContract(opts: {
+    projectRoot: string;
+    sessionId: string;
+    sliceId: string;
+    now?: Date;
+}): boolean;
+/** Resolve the contracts directory for a session. */
+export declare function contractsDir(projectRoot: string, sessionId: string): string;
+/** Resolve a single contract file path. */
+export declare function contractPath(projectRoot: string, sessionId: string, sliceId: string): string;
+/** Hash a contract payload. */
+export declare function hashContract(c: WriteContractInput | SliceContract): string;
+/**
+ * Persist a slice's public contract. Returns the absolute path on disk.
+ * Idempotent: re-writing the same contract overwrites in place.
+ */
+export declare function writeContract(projectRoot: string, sessionId: string, input: WriteContractInput): {
+    path: string;
+    contract: SliceContract;
+};
+/** Read a contract from disk. Returns null if missing. */
+export declare function readContract(projectRoot: string, sessionId: string, sliceId: string): SliceContract | null;
+/** List all contracts for a session. */
+export declare function listContracts(projectRoot: string, sessionId: string): readonly SliceContract[];
+/**
+ * Format a prompt-injection block from a set of contracts. The block is a
+ * stable, human-readable summary suitable for splicing into a downstream
+ * slice's dispatch prompt.
+ */
+export declare function formatContractInjection(contracts: readonly SliceContract[]): string;