peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/services/context/context-schema.d.ts

@@ -0,0 +1,415 @@
+/**
+ * Runtime validator for context.json. Per spec §4.1 + H8 (audit trail
+ * hashable). When this schema changes, version field must bump.
+ */
+import { z } from 'zod';
+export declare const ContextJsonSchema: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    goal: z.ZodString;
+    generatedAt: z.ZodString;
+    sha256: z.ZodString;
+    collector: z.ZodObject<{
+        files: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            kind: z.ZodEnum<["source", "test", "config", "doc"]>;
+            lines: z.ZodNumber;
+            hash: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }, {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }>, "many">;
+        gitStatus: z.ZodObject<{
+            branch: z.ZodString;
+            lastCommit: z.ZodString;
+            dirty: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        }, {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        }>;
+        memoryEntries: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            title: z.ZodString;
+            relevanceScore: z.ZodNumber;
+            excerptHash: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }, {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }>, "many">;
+        deps: z.ZodRecord<z.ZodString, z.ZodObject<{
+            version: z.ZodString;
+            source: z.ZodEnum<["package.json", "pnpm-lock.yaml", "yarn.lock"]>;
+            resolved: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    }, {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    }>;
+    docRetriever: z.ZodObject<{
+        fetchedDocs: z.ZodArray<z.ZodObject<{
+            dep: z.ZodString;
+            version: z.ZodString;
+            source: z.ZodEnum<["local-cache", "remote-fetch"]>;
+            url: z.ZodOptional<z.ZodString>;
+            fetchedAt: z.ZodString;
+            contentHash: z.ZodString;
+            sections: z.ZodArray<z.ZodObject<{
+                title: z.ZodString;
+                tokenEstimate: z.ZodNumber;
+                excerpt: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }, {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }>, "many">;
+            stale: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }, {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }>, "many">;
+        skipped: z.ZodArray<z.ZodObject<{
+            dep: z.ZodString;
+            reason: z.ZodEnum<["unconfigured", "network_error", "version_unknown"]>;
+        }, "strip", z.ZodTypeAny, {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }, {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    }, {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    }>;
+    tokenizer: z.ZodObject<{
+        metadata: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            kind: z.ZodEnum<["doc", "code", "memory", "git"]>;
+            version: z.ZodOptional<z.ZodString>;
+            blastRadius: z.ZodArray<z.ZodString, "many">;
+            conflictScore: z.ZodNumber;
+            timeDecayScore: z.ZodNumber;
+            tags: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            version?: string | undefined;
+        }, {
+            kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            version?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            version?: string | undefined;
+        }[];
+    }, {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            version?: string | undefined;
+        }[];
+    }>;
+    renderer: z.ZodObject<{
+        audience: z.ZodEnum<["peaks-rd", "peaks-qa", "peaks-mut", "all"]>;
+        renderedAt: z.ZodString;
+        sizeBytes: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        truncatedReason: z.ZodOptional<z.ZodEnum<["doc_budget_exceeded", "section_count_exceeded"]>>;
+    }, "strip", z.ZodTypeAny, {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    }, {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    sha256: string;
+    goal: string;
+    generatedAt: string;
+    collector: {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    };
+    docRetriever: {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    };
+    tokenizer: {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            version?: string | undefined;
+        }[];
+    };
+    renderer: {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    };
+}, {
+    version: "1.0";
+    sha256: string;
+    goal: string;
+    generatedAt: string;
+    collector: {
+        deps: Record<string, {
+            version: string;
+            source: "package.json" | "pnpm-lock.yaml" | "yarn.lock";
+            resolved: string;
+        }>;
+        gitStatus: {
+            dirty: boolean;
+            branch: string;
+            lastCommit: string;
+        };
+        files: {
+            path: string;
+            kind: "doc" | "source" | "test" | "config";
+            lines: number;
+            hash: string;
+        }[];
+        memoryEntries: {
+            path: string;
+            title: string;
+            relevanceScore: number;
+            excerptHash: string;
+        }[];
+    };
+    docRetriever: {
+        skipped: {
+            dep: string;
+            reason: "unconfigured" | "network_error" | "version_unknown";
+        }[];
+        fetchedDocs: {
+            version: string;
+            source: "local-cache" | "remote-fetch";
+            stale: boolean;
+            dep: string;
+            fetchedAt: string;
+            contentHash: string;
+            sections: {
+                title: string;
+                tokenEstimate: number;
+                excerpt: string;
+            }[];
+            url?: string | undefined;
+        }[];
+    };
+    tokenizer: {
+        metadata: {
+            kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
+            id: string;
+            blastRadius: string[];
+            conflictScore: number;
+            timeDecayScore: number;
+            version?: string | undefined;
+        }[];
+    };
+    renderer: {
+        sizeBytes: number;
+        audience: "all" | "peaks-rd" | "peaks-qa" | "peaks-mut";
+        renderedAt: string;
+        truncated: boolean;
+        truncatedReason?: "doc_budget_exceeded" | "section_count_exceeded" | undefined;
+    };
+}>;

package/dist/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 'peaks-loop-shared/paths';
+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('peaks-loop-doctor');
+    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/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 'peaks-loop-shared-channel';
+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 */
+        }
+    }
+}