peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -1,104 +0,0 @@
-/**
- * Type envelope for the `peaks slice check` CLI command.
- *
- * `peaks slice check` is the boundary check for the RD micro-cycle
- * (see `skills/peaks-solo/references/micro-cycle.md`). It bundles the
- * 4 self-checks that must pass at slice end before the slice is handed
- * off to peaks-qa:
- *
- *   1. typecheck (`npx tsc --noEmit`)
- *   2. unit tests — by default the **changed-only** suite
- *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
- *      full suite (`npx vitest run`); pass `--skip-tests` to skip
- *      entirely (e.g. docs-only or config-only slices).
- *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
- *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
- *
- * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
- * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
- * This command is for the BOUNDARY, not the inner loop.
- *
- * The unit-test stage emits a `unitTestsRunMode` field on the result
- * envelope so downstream tooling and the QA test-report can record
- * which mode actually ran: `"changed"` (default), `"full"` (with
- * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
- * (with `--allow-pre-existing-failures` when the run failed and the
- * stage was downgraded to `skipped` with a reason).
- */
-export type SliceCheckStageStatus = 'pass' | 'fail' | 'skipped';
-export type SliceCheckStage = {
-    /** Stable id for the stage (matches the runbook's check list). */
-    name: 'typecheck' | 'unit-tests' | 'review-fanout' | 'gate-verify-pipeline' | 'mock-placement' | 'audit-regression';
-    /** Human-readable description. */
-    description: string;
-    status: SliceCheckStageStatus;
-    /** Wall-clock duration in ms; null if skipped. */
-    durationMs: number | null;
-    /** Free-form detail (summary line + last error line). */
-    detail: string;
-    /** Optional structured data (e.g. test counts, gate counts). */
-    data?: Record<string, unknown>;
-};
-export type SliceCheckResult = {
-    /** Absolute project root the command operated on. */
-    projectRoot: string;
-    /** Request id the boundary check applies to; null if no slice is active. */
-    rid: string | null;
-    /** All stages in execution order. */
-    stages: SliceCheckStage[];
-    /**
-     * Which unit-test mode actually ran. One of:
-     * - `"changed"` — default: `npx vitest run --changed` (tests for git-changed files only)
-     * - `"full"` — opt-in via `--run-tests`: `npx vitest run` (full suite)
-     * - `"skipped"` — opt-in via `--skip-tests` (stage not executed)
-     * - `"overridden"` — full mode + `--allow-pre-existing-failures` and the run failed;
-     *   stage downgraded to `skipped` with the pre-existing-failure reason
-     */
-    unitTestsRunMode: 'changed' | 'full' | 'skipped' | 'overridden';
-    /** True iff every stage passed (or was skipped) and the boundary is OK to hand off. */
-    boundaryReady: boolean;
-    /** Total wall-clock duration in ms. */
-    totalDurationMs: number;
-    /** Next steps suggested when boundaryReady is false. */
-    nextActions: string[];
-};
-export type SliceCheckOptions = {
-    projectRoot: string;
-    /** When omitted, slice check inspects `.peaks/_runtime/current-change` to find the active rid. */
-    rid?: string;
-    /**
-     * When true, re-run the 3-way review fan-out (peaks-rd's code-review +
-     * security-review + perf-baseline sub-agents) even if the review files
-     * already exist. The default is to verify presence and skip if all 3 are present.
-     */
-    refreshFanout: boolean;
-    /**
-     * When true, run the **full** `npx vitest run` suite at the boundary.
-     * When false (the default), run the **changed-only** suite
-     * (`npx vitest run --changed`) which only exercises tests related to
-     * git-changed files. The changed-only mode is the new default as of
-     * run 017 — full suite costs 30s+ on this repo; the changed-only
-     * mode costs ~1-3s in steady state and is what catches the
-     * regressions that actually matter. The service treats `undefined`
-     * the same as `false`.
-     */
-    runTests?: boolean;
-    /**
-     * When true, skip the unit-test stage entirely. Useful when a slice
-     * has no test surface (e.g. a docs-only or config-only slice), or
-     * when the user wants a "typecheck + review + gate" boundary check
-     * without any test execution.
-     */
-    skipTests: boolean;
-    /**
-     * When true, an `unit-tests` stage that fails is reported as `skipped`
-     * (with a `reason` naming the pre-existing failure count) instead of
-     * `failed`. Used to opt in to bypassing the 28 pre-existing Windows
-     * test failures documented in dogfood-2-f1-f4.md F17. Only meaningful
-     * when the unit-test stage actually runs (i.e. not when `skipTests`
-     * is true). Does NOT affect the other 3 stages (typecheck /
-     * review-fanout / gate-verify-pipeline). Default: false. The service
-     * treats `undefined` the same as `false`.
-     */
-    allowPreExistingFailures?: boolean;
-};

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

@@ -1,28 +0,0 @@
-/**
- * Type envelope for the `peaks slice check` CLI command.
- *
- * `peaks slice check` is the boundary check for the RD micro-cycle
- * (see `skills/peaks-solo/references/micro-cycle.md`). It bundles the
- * 4 self-checks that must pass at slice end before the slice is handed
- * off to peaks-qa:
- *
- *   1. typecheck (`npx tsc --noEmit`)
- *   2. unit tests — by default the **changed-only** suite
- *      (`npx vitest run --changed`). Pass `--run-tests` to opt in to the
- *      full suite (`npx vitest run`); pass `--skip-tests` to skip
- *      entirely (e.g. docs-only or config-only slices).
- *   3. 3-way review fan-out (code-review + security-review + perf-baseline)
- *   4. gate machinery (`peaks workflow verify-pipeline --rid <rid>`)
- *
- * The micro-cycle itself (per-bug TDD) runs OUTSIDE slice check — only
- * single-test runs (`vitest -t "<name>"`) are allowed in micro-cycles.
- * This command is for the BOUNDARY, not the inner loop.
- *
- * The unit-test stage emits a `unitTestsRunMode` field on the result
- * envelope so downstream tooling and the QA test-report can record
- * which mode actually ran: `"changed"` (default), `"full"` (with
- * `--run-tests`), `"skipped"` (with `--skip-tests`), or `"overridden"`
- * (with `--allow-pre-existing-failures` when the run failed and the
- * stage was downgraded to `skipped` with a reason).
- */
-export {};

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

@@ -1,263 +0,0 @@
-/**
- * Type envelope for `peaks slice decompose` and its outputs.
- *
- * The slice-decomposition algorithm is a 6-stage deterministic function
- * (see `peaks-solo/references/slice-algorithm.md` for the full spec):
- *
- *   1. workUnitResolution  -- codegraph.query + knowledge_graph.grep
- *   2. buildDependencyDAG  -- real import edges + codegraph.affected fallback
- *   3. scc + criticalPath  -- Tarjan + longest_path on the condensation
- *   4. minCut              -- Stoer-Wagner with semantic-preference weights
- *   5. estimateWork        -- calibration-store (LoC+test heuristic v1)
- *   6. emit                -- serialise DecompositionResult to JSON
- *
- * The pure function is `decomposeSlices(rid, prdMarkdown, projectRoot, options)`
- * (exported from `slice-decompose-service.ts`). All types in this file are
- * stable input/output contracts; do not change field names without a
- * migration path because the JSON envelope is consumed by:
- *
- *   - `peaks slice pick` (reads candidates, spawns fzf)
- *   - `peaks slice plan` (reads picked batch, calls peaks request init)
- *   - `peaks-rd` and `peaks-qa` in unit tests
- *   - user inspection via `cat .peaks/sc/slice-decomposition/<rid>.json`
- *
- * Codegraph is local project-analysis evidence; its output is
- * **untrusted supporting evidence**, never authoritative for QA verdict.
- * DecompositionResult fields derived from codegraph are tagged with
- * `confidence: 'semantic' | 'structural'` so downstream consumers can
- * discount structural-only cuts.
- */
-export type EdgeKind = 'imports' | 'depends_on' | 'calls' | 'contains_flow' | 'flow_step';
-export interface WorkUnit {
-    /** Stable id within the decomposition; usually "W1".."Wn". */
-    id: string;
-    /** Human-readable label; shown in `peaks slice pick` fzf list. */
-    label: string;
-    /** Primary files this work unit touches (1-N). */
-    files: readonly string[];
-    /** Total LoC across all `files`. */
-    loc: number;
-    /** Number of test files this work unit adds (0 if none). */
-    testsAdded: number;
-    /** If any file in `files` pre-existed, the sum of delta-LoC; undefined if all files are new. */
-    deltaLoc?: number;
-    /** The primary file path; the algorithm picks the largest file as primary. */
-    filePath: string;
-    /** Graph node ids (file:<path> | function:<path>:<name>) that resolved this work unit. */
-    candidates: readonly string[];
-}
-export interface DependencyEdge {
-    from: string;
-    to: string;
-    kind: EdgeKind;
-    /**
-     * Edge weight for Stoer-Wagner. Lower weight = prefer to cut here.
-     * Locked values: flow_step=0.05, contains_flow=0.1, depends_on=5.0, calls=8.0, imports=10.0.
-     */
-    weight: number;
-    /** Human-readable evidence: the actual import statement or graph edge. */
-    evidence: string;
-    /** True iff kind is contains_flow or flow_step (i.e. from understand-anything). */
-    isSemantic: boolean;
-    /** 'semantic' if the edge came from understand-anything; 'structural' if from import-grep or codegraph. */
-    confidence: 'semantic' | 'structural';
-}
-export interface WorkEstimate {
-    complexitySum: number;
-    testCount: number;
-    locSum: number;
-    minutesP50: number;
-    minutesP90: number;
-    confidence: 'low' | 'medium' | 'high';
-    rationale: string;
-}
-export interface SliceCandidate {
-    rid: string;
-    label: string;
-    files: readonly string[];
-    testsAdded?: readonly string[];
-    estimate: WorkEstimate;
-    /** Domain anchor; "domain:<name>" if understand-anything indexed, else "file:<path>". */
-    semanticAnchor: string;
-}
-export interface ParallelBatch {
-    batch: number;
-    dependsOn: readonly number[];
-    slices: readonly SliceCandidate[];
-    parallelizableWithinBatch: boolean;
-}
-export interface SccAnalysis {
-    sccCount: number;
-    trivialSCCs: readonly string[];
-    nonTrivialSCCs: readonly string[];
-    condensationEdges: number;
-}
-export interface CriticalPath {
-    nodes: readonly string[];
-    edges: readonly string[];
-    totalLoc: number;
-    totalDeltaLoc: number;
-    rationale: string;
-}
-export interface MinCutEdge {
-    from: string;
-    to: string;
-    kind: EdgeKind;
-    weight: number;
-    isSemantic: boolean;
-    confidence: 'semantic' | 'structural';
-}
-export interface MinCutPartition {
-    name: string;
-    nodes: readonly string[];
-}
-export interface MinCutResult {
-    algorithm: string;
-    cutEdges: readonly MinCutEdge[];
-    partitions: readonly MinCutPartition[];
-}
-export interface CodegraphEnvelope {
-    nodes: number;
-    edges: number;
-    dbMB: number;
-    /** Git commit SHA at which the codegraph index was built, or 'unindexed'. */
-    freshness: string;
-    /** True iff codegraph.affected returned > 0 cross-file dependents. */
-    affectedCrossFile: boolean;
-    note: string;
-}
-export interface UnderstandAnythingEnvelope {
-    kgNodes: number;
-    kgEdges: number;
-    available: boolean;
-    fallback: 'semantic' | 'structural-only';
-    note: string;
-}
-export interface DecompositionResult {
-    rid: string;
-    /** ISO 8601 UTC, e.g. "2026-06-13T12:00:00.000Z". */
-    generatedAt: string;
-    codegraph: CodegraphEnvelope;
-    understandAnything: UnderstandAnythingEnvelope;
-    workUnits: readonly WorkUnit[];
-    dependencyDAG: {
-        edges: readonly DependencyEdge[];
-    };
-    sccAnalysis: SccAnalysis;
-    criticalPath: CriticalPath;
-    minCutResult: MinCutResult;
-    parallelBatches: readonly ParallelBatch[];
-    /** Free-form operator hint; e.g. "split into multiple pick sessions" when N > 10. */
-    pickHint?: string;
-}
-/**
- * Per-run metrics for the 2.1.1 algorithm. Emitted only when
- * `peaks slice decompose --benchmark` is passed. The shape is stable
- * across algorithm versions so it can be diffed across runs.
- */
-export interface SliceBenchmark {
-    rid: string;
-    totalMs: number;
-    /** Codegraph calls observed during the run (query + status + affected). */
-    codegraphQueries: number;
-    /** Distribution of slice estimate.confidence across all batches. */
-    p50ConfidenceDistribution: {
-        low: number;
-        mid: number;
-        high: number;
-    };
-    /** Approximate input bytes (PRD body + work-units + codegraph hits, post-load). */
-    inputApproxBytes: {
-        prd: number;
-    };
-    /** Bytes of the serialized decomposition JSON. */
-    outputJsonBytes: number;
-    capturedAt: string;
-}
-export interface DecomposeOptions {
-    /** When true, re-run `peaks codegraph index` before reading. */
-    refresh?: boolean;
-    /**
-     * Inject a codegraph-shell replacement. The default uses `peaks codegraph` CLI.
-     * Tests pass a function-returning-promise fake.
-     */
-    codegraphRunner?: CodegraphRunner;
-    /**
-     * Inject an understand-anything shell replacement. Default reads
-     * `.understand-anything/knowledge-graph.json` if present.
-     */
-    understandRunner?: UnderstandRunner;
-    /**
-     * Inject a function that returns the real import-edge set for a list of files.
-     * Default: spawns `git grep` + parses output. Tests pass a synchronous fake.
-     */
-    importEdgeRunner?: ImportEdgeRunner;
-}
-export interface CodegraphRunner {
-    query(text: string, projectRoot: string): Promise<readonly CodegraphQueryHit[]>;
-    affected(files: readonly string[], projectRoot: string): Promise<CodegraphAffectedResult>;
-    status(projectRoot: string): Promise<{
-        indexed: boolean;
-        nodes: number;
-        edges: number;
-        dbMB: number;
-        freshness: string;
-    }>;
-}
-export interface CodegraphQueryHit {
-    id: string;
-    kind: string;
-    name: string;
-    filePath: string;
-    score: number;
-    /** Optional LoC, when codegraph can report it; used for work estimates. */
-    loc?: number;
-}
-export interface CodegraphAffectedResult {
-    changedFiles: readonly string[];
-    affectedTests: readonly string[];
-    totalDependentsTraversed: number;
-}
-export interface UnderstandRunner {
-    /** Returns the parsed knowledge graph, or null if not indexed. */
-    read(projectRoot: string): Promise<KnowledgeGraph | null>;
-}
-export interface KnowledgeGraph {
-    nodes: readonly KgNode[];
-    edges: readonly KgEdge[];
-    layers: readonly {
-        id: string;
-        name: string;
-        nodeIds: readonly string[];
-    }[];
-}
-export type KgNodeType = 'file' | 'function' | 'class' | 'module' | 'concept' | 'config' | 'document' | 'service' | 'table' | 'endpoint' | 'pipeline' | 'schema' | 'resource' | 'domain' | 'flow' | 'step';
-export interface KgNode {
-    id: string;
-    type: KgNodeType;
-    name: string;
-    filePath?: string;
-    summary?: string;
-    tags: readonly string[];
-    complexity?: number;
-}
-export interface KgEdge {
-    source: string;
-    target: string;
-    type: string;
-    weight?: number;
-}
-export interface ImportEdgeRunner {
-    /**
-     * Returns real static import edges for the given file paths.
-     * For each file, parses the `import ... from '...'` statements and resolves
-     * relative paths to project-relative paths.
-     * Output: array of {from, to, evidence} where `evidence` is the import line.
-     */
-    importsOf(projectRoot: string, files: readonly string[]): Promise<readonly ImportEdge[]>;
-}
-export interface ImportEdge {
-    from: string;
-    to: string;
-    evidence: string;
-}

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

@@ -1,30 +0,0 @@
-/**
- * Type envelope for `peaks slice decompose` and its outputs.
- *
- * The slice-decomposition algorithm is a 6-stage deterministic function
- * (see `peaks-solo/references/slice-algorithm.md` for the full spec):
- *
- *   1. workUnitResolution  -- codegraph.query + knowledge_graph.grep
- *   2. buildDependencyDAG  -- real import edges + codegraph.affected fallback
- *   3. scc + criticalPath  -- Tarjan + longest_path on the condensation
- *   4. minCut              -- Stoer-Wagner with semantic-preference weights
- *   5. estimateWork        -- calibration-store (LoC+test heuristic v1)
- *   6. emit                -- serialise DecompositionResult to JSON
- *
- * The pure function is `decomposeSlices(rid, prdMarkdown, projectRoot, options)`
- * (exported from `slice-decompose-service.ts`). All types in this file are
- * stable input/output contracts; do not change field names without a
- * migration path because the JSON envelope is consumed by:
- *
- *   - `peaks slice pick` (reads candidates, spawns fzf)
- *   - `peaks slice plan` (reads picked batch, calls peaks request init)
- *   - `peaks-rd` and `peaks-qa` in unit tests
- *   - user inspection via `cat .peaks/sc/slice-decomposition/<rid>.json`
- *
- * Codegraph is local project-analysis evidence; its output is
- * **untrusted supporting evidence**, never authoritative for QA verdict.
- * DecompositionResult fields derived from codegraph are tagged with
- * `confidence: 'semantic' | 'structural'` so downstream consumers can
- * discount structural-only cuts.
- */
-export {};

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

@@ -1,98 +0,0 @@
-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-loop 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 };