peaks-loop 3.0.0

package/dist/src/services/slice/slice-review-state.js

@@ -0,0 +1,109 @@
+/**
+ * v2.15.0 follow-up — G1: slice business review state.
+ *
+ * The 12 Gaps positioning memory: each slice completion triggers a
+ * business review by the user (not a technical review). The user
+ * evaluates 4-5 business / product items; technical metrics (coverage,
+ * P99, security scan) are AI auto-decided in `peaks-rd`'s fan-out.
+ *
+ * State persistence: `.peaks/_runtime/<sid>/slice-reviews/<slice-id>.json`.
+ *
+ *   reviewScore: 1-5 per item; overallOk when avg >= 3 AND no P0 fail
+ *   decision: pending | accepted | rejected
+ *   rejectionReason: only when decision = rejected
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** The 5 default review items per slice (the 12 Gaps memory checklist). */
+export const DEFAULT_REVIEW_ITEMS = [
+    { id: 'business-match', question: '这个 slice 做完,业务流程对吗?(跟产品最初给的需求匹配)' },
+    { id: 'boundary-cases', question: '边界 case 跟业务预期一致吗?(异常输入/错误提示/空/加载/失败状态)' },
+    { id: 'ui-assembly', question: 'UI 装配跟产品预期一致吗?(页面模式/关键交互/信息密度,非视觉设计)' },
+    { id: 'mergeable', question: '能合入下个业务版本吗?(业务风险/集成断点)' }
+];
+export function buildEmptySliceReview(sliceId, sessionId, now = new Date()) {
+    return {
+        sliceId,
+        sessionId,
+        createdAt: now.toISOString(),
+        updatedAt: now.toISOString(),
+        decision: 'pending',
+        items: DEFAULT_REVIEW_ITEMS.map((it) => ({ id: it.id, question: it.question, score: null }))
+    };
+}
+export function getReviewDir(projectRoot, sessionId) {
+    return resolve(projectRoot, '.peaks', '_runtime', sessionId, 'slice-reviews');
+}
+export function getReviewPath(projectRoot, sessionId, sliceId) {
+    return join(getReviewDir(projectRoot, sessionId), `${sliceId}.json`);
+}
+export function readSliceReview(projectRoot, sessionId, sliceId) {
+    const path = getReviewPath(projectRoot, sessionId, sliceId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn(`readSliceReview: failed to read or parse ${path}: ${err.message}`);
+        return null;
+    }
+}
+export function writeSliceReview(projectRoot, review) {
+    const path = getReviewPath(projectRoot, review.sessionId, review.sliceId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(review, null, 2), 'utf8');
+}
+/** Update a single item's score. Returns the new state. */
+export function scoreItem(review, itemId, score, note, now = new Date()) {
+    let found = false;
+    const items = review.items.map((it) => {
+        if (it.id !== itemId)
+            return it;
+        found = true;
+        return { id: it.id, question: it.question, score, ...(note !== undefined ? { note } : {}) };
+    });
+    if (!found)
+        return review;
+    return { ...review, items, updatedAt: now.toISOString() };
+}
+/** Compute the average score across all scored items. */
+export function averageScore(review) {
+    const scored = review.items.filter((it) => it.score !== null);
+    if (scored.length === 0)
+        return null;
+    return scored.reduce((sum, it) => sum + it.score, 0) / scored.length;
+}
+/** Decide accept/reject based on the 12 Gaps threshold:
+ *   - avg score >= 3 AND no item scored <= 2 → accepted
+ *   - any item scored 1 (P0 fail) or avg < 3 → rejected
+ */
+export function deriveDecision(review) {
+    if (review.items.some((it) => it.score === 1))
+        return 'rejected';
+    const avg = averageScore(review);
+    if (avg === null)
+        return 'pending';
+    if (avg < 3)
+        return 'rejected';
+    // Any item <= 2 also rejects.
+    if (review.items.some((it) => it.score !== null && it.score <= 2))
+        return 'rejected';
+    return 'accepted';
+}
+/** Apply the derived decision to a review (used by `peaks slice accept`). */
+export function acceptReview(review, now = new Date()) {
+    return { ...review, decision: 'accepted', updatedAt: now.toISOString() };
+}
+export function rejectReview(review, reason, now = new Date()) {
+    return { ...review, decision: 'rejected', rejectionReason: reason, updatedAt: now.toISOString() };
+}
+export function renderChecklist(review) {
+    return review.items.map((it) => ({
+        id: it.id,
+        question: it.question,
+        currentScore: it.score,
+        prompt: `  [ ] ${it.question} (current: ${it.score === null ? 'not scored' : it.score + '/5'})`
+    }));
+}

package/dist/src/services/slice/slice-topology-types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Type envelope for v2 multi-pass slice decomposition.
+ *
+ * v2 extends the v1 `DecompositionResult` with a `passes[]` array (one entry
+ * per decomposition pass) and `crossPassEdges[]` (edges that span passes),
+ * plus an `llmArbitrations[]` trace for any LLM calls made during
+ * decomposition. The new schema is what `peaks-slice-decompose` (and the
+ * new `MultiPassOrchestrator`) emit; v1 files remain readable via the
+ * `SchemaRouter` (Task 8) so existing `peaks slice pick` / `peaks slice plan`
+ * flows do not break.
+ *
+ * Conventions:
+ * - All fields are `readonly` to enforce immutable construction.
+ * - Literal unions (`SchemaVersion`, `PassNumber`, etc.) are preferred over
+ *   `enum` so the JSON serialisation is the literal string, not a number.
+ * - `CrossPassEdge.confidence` extends the structural|semantic union with
+ *   `'llm'` because LLM-arbitrated edges are neither — they were guessed
+ *   by an LLM and must carry the arbitration trace via `arbitratedBy`.
+ */
+import type { CodegraphEnvelope, UnderstandAnythingEnvelope } from './slice-decompose-types.js';
+/** Schema discriminator. v1 files do NOT carry a `schemaVersion` field. */
+export type SchemaVersion = 'v1' | 'v2';
+/** How coarse a slice is. */
+export type SliceGranularity = 'service' | 'file' | 'sub-file';
+/** Pass index. v2 only goes up to Pass 3 (sub-file is reserved for future). */
+export type PassNumber = 1 | 2 | 3;
+/** Edge source confidence. */
+export type EdgeConfidence = 'structural' | 'semantic';
+/** LLM-reported confidence of a single arbitration. */
+export type LlmConfidence = 'high' | 'medium' | 'low';
+/** Edge kinds for edges within a single pass. */
+export type InternalEdgeKind = 'imports' | 'calls' | 'depends_on' | 'contains_flow' | 'flow_step';
+/** Edge kinds for edges that connect two different passes. */
+export type CrossPassEdgeKind = 'type-shares' | 'fixture-shares' | 'import-re-export' | 'llm-arbitrated';
+/** Configuration for a single decomposition pass. */
+export interface PassConfig {
+    readonly passNumber: PassNumber;
+    readonly granularity: SliceGranularity;
+    /** Optional list of files (or semantic anchors) to scope this pass to. */
+    readonly scopeFilter?: readonly string[];
+}
+/** A single v2 slice, scoped to one pass. */
+export interface SliceV2 {
+    /** Stable id within this pass (e.g. "S1" for Pass 1, "S1.3" for Pass 2 child of S1). */
+    readonly id: string;
+    /** Human-readable label; shown in `peaks slice pick` fzf list. */
+    readonly label: string;
+    readonly granularity: SliceGranularity;
+    readonly files: readonly string[];
+    /** Total LoC across all `files`. */
+    readonly loc: number;
+    /** Parent slice id from the previous pass, or null for Pass 1. */
+    readonly parentSliceId: string | null;
+    /** Domain anchor; "domain:<name>" if understand-anything indexed, else "file:<path>". */
+    readonly semanticAnchor: string;
+}
+/** Edge connecting two slices within the same pass. */
+export interface InternalEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: InternalEdgeKind;
+    /** Edge weight for downstream min-cut / dispatch-ordering heuristics. */
+    readonly weight: number;
+    /** Human-readable evidence: the actual import statement or graph edge. */
+    readonly evidence: string;
+    readonly confidence: EdgeConfidence;
+}
+/** Edge connecting a slice in one pass to a slice in another pass. */
+export interface CrossPassEdge {
+    readonly fromPass: PassNumber;
+    readonly toPass: PassNumber;
+    readonly fromSliceId: string;
+    readonly toSliceId: string;
+    readonly kind: CrossPassEdgeKind;
+    /** `llm` is only valid for `kind: 'llm-arbitrated'`. */
+    readonly confidence: EdgeConfidence | 'llm';
+    /** Human-readable evidence: the import line, shared fixture id, etc. */
+    readonly evidence: string;
+    /** The `LlmArbitration.callId` that produced this edge, or null. */
+    readonly arbitratedBy: string | null;
+}
+/** Record of one LLM call made during decomposition. */
+export interface LlmArbitration {
+    readonly callId: string;
+    /** sha256 hex of the prompt (used for content-hash cache lookup). */
+    readonly promptHash: string;
+    readonly input: string;
+    readonly output: string;
+    readonly confidence: LlmConfidence;
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+}
+/** The slices + internal edges produced by one decomposition pass. */
+export interface PassResult {
+    readonly passNumber: PassNumber;
+    readonly granularity: SliceGranularity;
+    readonly slices: readonly SliceV2[];
+    readonly internalEdges: readonly InternalEdge[];
+}
+/** Top-level v2 decomposition result. */
+export interface DecompositionResultV2 {
+    readonly schemaVersion: 'v2';
+    readonly rid: string;
+    /** ISO 8601 UTC, e.g. "2026-06-25T12:00:00.000Z". */
+    readonly generatedAt: string;
+    readonly passes: readonly PassResult[];
+    readonly crossPassEdges: readonly CrossPassEdge[];
+    readonly llmArbitrations: readonly LlmArbitration[];
+    readonly codegraph: CodegraphEnvelope;
+    readonly understandAnything: UnderstandAnythingEnvelope;
+    /** True iff any pass failed to complete and the result is a partial. */
+    readonly partial: boolean;
+}

package/dist/src/services/slice/slice-topology-types.js

@@ -0,0 +1,20 @@
+/**
+ * Type envelope for v2 multi-pass slice decomposition.
+ *
+ * v2 extends the v1 `DecompositionResult` with a `passes[]` array (one entry
+ * per decomposition pass) and `crossPassEdges[]` (edges that span passes),
+ * plus an `llmArbitrations[]` trace for any LLM calls made during
+ * decomposition. The new schema is what `peaks-slice-decompose` (and the
+ * new `MultiPassOrchestrator`) emit; v1 files remain readable via the
+ * `SchemaRouter` (Task 8) so existing `peaks slice pick` / `peaks slice plan`
+ * flows do not break.
+ *
+ * Conventions:
+ * - All fields are `readonly` to enforce immutable construction.
+ * - Literal unions (`SchemaVersion`, `PassNumber`, etc.) are preferred over
+ *   `enum` so the JSON serialisation is the literal string, not a number.
+ * - `CrossPassEdge.confidence` extends the structural|semantic union with
+ *   `'llm'` because LLM-arbitrated edges are neither — they were guessed
+ *   by an LLM and must carry the arbitration trace via `arbitratedBy`.
+ */
+export {};

package/dist/src/services/smoke/smoke-paths-state.d.ts

@@ -0,0 +1,73 @@
+/**
+ * v2.15.0 follow-up — G14: smoke regression state service.
+ *
+ * Tracks the project's "critical paths" — the 5-10 paths the user
+ * (or the QA agent) must verify in 5-10 minutes before shipping.
+ * Persistence: `.peaks/smoke-paths.json` in the project root.
+ *
+ * The actual path execution (Playwright / curl / manual) is OUT OF
+ * SCOPE for this slice — this ships the model + the run-result
+ * record path. A follow-up slice wires real Playwright integration.
+ */
+export type CriticalPathSource = 'prd-business-scenario' | 'boss-stated' | 'historical-incident' | 'impact-must-check' | 'manual';
+export type CriticalPathStatus = 'pending' | 'pass' | 'fail';
+export interface CriticalPath {
+    /** Unique id. */
+    readonly id: string;
+    /** Human-readable name / description. */
+    readonly name: string;
+    /** Where this path came from. */
+    readonly source: CriticalPathSource;
+    /** When it was registered (ISO). */
+    readonly registeredAt: string;
+    /** Optional category tag (e.g. "登录", "权限", "数据列表"). */
+    readonly category?: string;
+    /** Latest status + when it was last run. */
+    readonly status: CriticalPathStatus;
+    readonly lastRunAt?: string;
+    readonly lastRunNote?: string;
+    /** Optional run history (last 5 runs, oldest first). */
+    readonly history: readonly {
+        readonly at: string;
+        readonly status: CriticalPathStatus;
+        readonly note?: string;
+    }[];
+}
+export interface SmokeState {
+    readonly version: 1;
+    readonly paths: readonly CriticalPath[];
+}
+export declare const EMPTY_SMOKE_STATE: SmokeState;
+export declare function getSmokeStatePath(projectRoot: string): string;
+export declare function readSmokeState(projectRoot: string): SmokeState;
+export declare function writeSmokeState(projectRoot: string, state: SmokeState): void;
+/** Sources accepted by the CLI's --source flag. */
+export declare const CRITICAL_PATH_SOURCES: readonly CriticalPathSource[];
+export declare function isCriticalPathSource(value: string): value is CriticalPathSource;
+/** Generate a stable id from a name (lowercase, hyphens). */
+export declare function makeCriticalPathId(name: string): string;
+/** Add a critical path. Deduplicates by id. */
+export declare function addCriticalPath(state: SmokeState, path: CriticalPath): SmokeState;
+/** Add a run result to a path's history. Keeps the last 5. */
+export declare function recordRun(state: SmokeState, id: string, status: CriticalPathStatus, note?: string, now?: Date): SmokeState;
+/** Convert peaks impact must-check items to critical paths. */
+export declare function impactMustChecksToCriticalPaths(items: readonly {
+    scenario: string;
+    category: string;
+    priority: string;
+}[], now?: Date): CriticalPath[];
+/** Run summary for `peaks smoke run`. */
+export interface SmokeRunResult {
+    readonly totalPaths: number;
+    readonly passedPaths: number;
+    readonly failedPaths: number;
+    readonly pendingPaths: number;
+    readonly failedDetails: readonly {
+        id: string;
+        name: string;
+        lastRunNote?: string;
+    }[];
+    readonly durationMs: number;
+}
+/** Compute run summary from current state. */
+export declare function summarizeState(state: SmokeState): SmokeRunResult;

package/dist/src/services/smoke/smoke-paths-state.js

@@ -0,0 +1,117 @@
+/**
+ * v2.15.0 follow-up — G14: smoke regression state service.
+ *
+ * Tracks the project's "critical paths" — the 5-10 paths the user
+ * (or the QA agent) must verify in 5-10 minutes before shipping.
+ * Persistence: `.peaks/smoke-paths.json` in the project root.
+ *
+ * The actual path execution (Playwright / curl / manual) is OUT OF
+ * SCOPE for this slice — this ships the model + the run-result
+ * record path. A follow-up slice wires real Playwright integration.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+export const EMPTY_SMOKE_STATE = { version: 1, paths: [] };
+const STATE_FILE = '.peaks/smoke-paths.json';
+export function getSmokeStatePath(projectRoot) {
+    return resolve(projectRoot, STATE_FILE);
+}
+export function readSmokeState(projectRoot) {
+    const path = getSmokeStatePath(projectRoot);
+    if (!existsSync(path))
+        return EMPTY_SMOKE_STATE;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return EMPTY_SMOKE_STATE;
+        return { version: 1, paths: Array.isArray(parsed.paths) ? parsed.paths : [] };
+    }
+    catch {
+        return EMPTY_SMOKE_STATE;
+    }
+}
+export function writeSmokeState(projectRoot, state) {
+    const path = getSmokeStatePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2), 'utf8');
+}
+/** Sources accepted by the CLI's --source flag. */
+export const CRITICAL_PATH_SOURCES = [
+    'prd-business-scenario',
+    'boss-stated',
+    'historical-incident',
+    'impact-must-check',
+    'manual'
+];
+export function isCriticalPathSource(value) {
+    return CRITICAL_PATH_SOURCES.includes(value);
+}
+/** Generate a stable id from a name (lowercase, hyphens). */
+export function makeCriticalPathId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+/** Add a critical path. Deduplicates by id. */
+export function addCriticalPath(state, path) {
+    const filtered = state.paths.filter((p) => p.id !== path.id);
+    return { version: 1, paths: [...filtered, path] };
+}
+/** Add a run result to a path's history. Keeps the last 5. */
+export function recordRun(state, id, status, note, now = new Date()) {
+    let found = false;
+    const paths = state.paths.map((p) => {
+        if (p.id !== id)
+            return p;
+        found = true;
+        const newHistory = [...p.history, { at: now.toISOString(), status, ...(note !== undefined ? { note } : {}) }].slice(-5);
+        return {
+            ...p,
+            status,
+            lastRunAt: now.toISOString(),
+            ...(note !== undefined ? { lastRunNote: note } : {}),
+            history: newHistory
+        };
+    });
+    if (!found)
+        return state;
+    return { version: 1, paths };
+}
+/** Convert peaks impact must-check items to critical paths. */
+export function impactMustChecksToCriticalPaths(items, now = new Date()) {
+    return items.map((item) => ({
+        id: makeCriticalPathId(item.scenario),
+        name: item.scenario,
+        source: 'impact-must-check',
+        registeredAt: now.toISOString(),
+        category: item.category,
+        status: 'pending',
+        history: []
+    }));
+}
+/** Compute run summary from current state. */
+export function summarizeState(state) {
+    let passed = 0, failed = 0, pending = 0;
+    const failedDetails = [];
+    for (const p of state.paths) {
+        if (p.status === 'pass')
+            passed++;
+        else if (p.status === 'fail') {
+            failed++;
+            failedDetails.push({ id: p.id, name: p.name, ...(p.lastRunNote !== undefined ? { lastRunNote: p.lastRunNote } : {}) });
+        }
+        else
+            pending++;
+    }
+    return {
+        totalPaths: state.paths.length,
+        passedPaths: passed,
+        failedPaths: failed,
+        pendingPaths: pending,
+        failedDetails,
+        durationMs: 0 // CLI measures wall time; the service itself is instant
+    };
+}

package/dist/src/services/solo/auto-compact-orchestrator.d.ts

@@ -0,0 +1,98 @@
+import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
+import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
+export interface AutoCompactInput {
+    /** Project root for context (default cwd). */
+    readonly projectRoot: string;
+    /** Caller-provided in-flight batch probe (default false). */
+    readonly inFlightBatch?: InFlightBatchProbe | undefined;
+    /**
+     * Force execute even when ratio < threshold (test seam). In
+     * production this is always `false` — peaks-cli drives compact
+     * autonomously at 0.85+ with zero human / zero LLM intervention.
+     */
+    readonly force?: boolean | undefined;
+    /** Skip the 95% red-line gate (test seam — never true in production). */
+    readonly bypassRedLine?: boolean | undefined;
+    /** Current session id (default = resolve via session-id-service). */
+    readonly sessionId?: string | undefined;
+    /** Injectable env for IDE detection (test seam). */
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Injectable clock for mtime checks (test seam). */
+    readonly now?: Date | undefined;
+    /**
+     * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): which session
+     * the compact should target. Default `'main'` — the orchestrator
+     * (peaks-solo body) runs in the main-session Claude Code window and
+     * wants to compress *its* context. Sub-agent shells pass
+     * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
+     */
+    readonly target?: CompactTarget | undefined;
+}
+/**
+ * Map a context ratio to a `CompactTrigger` action. Pure; the side
+ * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
+ * tiers:
+ *
+ *   - ratio < 0.85 → 'none' or 'soft-warn'
+ *   - ratio ≥ 0.85 → 'pre-compact' (async-friendly path)
+ *   - ratio ≥ 0.95 → 'red-line' (synchronous gate)
+ */
+export declare function evaluateCompactTrigger(ratio: number): CompactTrigger;
+/**
+ * Decide whether to run the auto-compact flow. Pure function for the
+ * decision; side effects (checkpoint + IDE dispatch) live in
+ * `runAutoCompact` below. Zero human / zero LLM intervention:
+ *
+ *   - ratio < 0.85           → skip (LLM keeps working; no action)
+ *   - 0.85 ≤ ratio < 0.95    → pre-compact; if in-flight batch
+ *                                present, defer (D6.e); else dispatch
+ *                                IDE compact asynchronously.
+ *   - ratio ≥ 0.95           → red-line; ALWAYS dispatch synchronously
+ *                                regardless of in-flight batch.
+ */
+export declare function evaluateAutoCompactDecision(input: {
+    ratio: number;
+    inFlightBatch?: InFlightBatchProbe | undefined;
+    force?: boolean | undefined;
+    bypassRedLine?: boolean | undefined;
+}): {
+    shouldCompact: boolean;
+    reason: 'below-threshold' | 'in-flight-batch' | 'pre-compact' | 'red-line';
+    trigger: CompactTrigger;
+};
+/**
+ * Build the convergence plan that D7's post-compact-detect will read
+ * back. Includes the current plan, open questions, recent decisions,
+ * todo state, and recent artifact paths — strictly more than what a
+ * raw `/compact` would preserve.
+ */
+export declare function buildConvergencePlan(input: {
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly ratio: number;
+    readonly checkpointPath: string;
+    readonly nextActions: readonly string[];
+    readonly redLine?: boolean;
+}): ConvergencePlan;
+/**
+ * Execute the auto-compact flow.
+ *
+ * Steps (orchestration):
+ *   1. Resolve session id.
+ *   2. Read current ratio via AC-1 (`readContextPercent`).
+ *   3. Evaluate trigger via `evaluateCompactTrigger`.
+ *   4. If trigger.kind === 'none' / 'soft-warn' → return skip.
+ *   5. If trigger.kind === 'pre-compact' AND in-flight batch → wait.
+ *   6. If trigger.kind === 'pre-compact' → async dispatch (write
+ *      checkpoint + IDE compact; orchestrator returns immediately).
+ *   7. If trigger.kind === 'red-line' → synchronous gate: refuse
+ *      sub-agent dispatch, dispatch IDE compact, mark `redLineGated`.
+ *
+ * The caller (CLI or skill body) handles the actual return — D7's
+ * post-compact-detect will pick up the checkpoint on the next turn.
+ * For red-line, the caller MUST block further tool calls until the
+ * post-compact probe confirms ratio < 0.85.
+ */
+export declare function runAutoCompact(input: AutoCompactInput): Promise<AutoCompactResult>;
+/** Re-export for callers that need to surface the trigger shape. */
+export type { CompactTrigger, ConvergencePlan, InFlightBatchProbe, AutoCompactResult };