peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,263 @@
+/**
+ * Type envelope for `peaks slice decompose` and its outputs.
+ *
+ * The slice-decomposition algorithm is a 6-stage deterministic function
+ * (see `peaks-code/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/services/slice/slice-decompose-types.js

@@ -0,0 +1,30 @@
+/**
+ * Type envelope for `peaks slice decompose` and its outputs.
+ *
+ * The slice-decomposition algorithm is a 6-stage deterministic function
+ * (see `peaks-code/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/services/slice/slice-integration.d.ts

@@ -0,0 +1,43 @@
+/**
+ * v2.15.0 follow-up — G6: slice cross-integration verifier.
+ *
+ * The 12 Gaps memory: in the layered-parallel execution model (G12), multiple
+ * slices can complete out of order. The question is: do their public
+ * contracts still line up when integrated together?
+ *
+ * This service takes a list of slice contracts (already written via
+ * `peaks contract write`) and produces a cross-integration report:
+ *   - missing exports: an export declared by slice A but not consumed by slice B
+ *   - type mismatches: types used across slice boundaries
+ *   - signature drift: function signatures changed
+ *
+ * Pure function. No I/O. The CLI is `peaks slice integrate`.
+ */
+import type { SliceContract } from '../dispatch/contract-store.js';
+export interface IntegrationFinding {
+    /** Severity: 'error' (blocks integration), 'warning' (informational), 'info' (noted). */
+    readonly severity: 'error' | 'warning' | 'info';
+    /** The slice that owns the export. */
+    readonly ownerSliceId: string;
+    /** The slice that consumes the export. */
+    readonly consumerSliceId: string;
+    /** Type of finding. */
+    readonly kind: 'missing-export' | 'type-mismatch' | 'signature-drift' | 'duplicate-export';
+    /** Human-readable description. */
+    readonly message: string;
+}
+export interface IntegrationReport {
+    readonly sliceIds: readonly string[];
+    readonly totalContracts: number;
+    readonly findings: readonly IntegrationFinding[];
+    readonly summary: {
+        readonly errors: number;
+        readonly warnings: number;
+        readonly info: number;
+    };
+    readonly ok: boolean;
+}
+export interface IntegrateOptions {
+    readonly contracts: readonly SliceContract[];
+}
+export declare function integrateSlices(opts: IntegrateOptions): IntegrationReport;

package/dist/services/slice/slice-integration.js

@@ -0,0 +1,106 @@
+/**
+ * v2.15.0 follow-up — G6: slice cross-integration verifier.
+ *
+ * The 12 Gaps memory: in the layered-parallel execution model (G12), multiple
+ * slices can complete out of order. The question is: do their public
+ * contracts still line up when integrated together?
+ *
+ * This service takes a list of slice contracts (already written via
+ * `peaks contract write`) and produces a cross-integration report:
+ *   - missing exports: an export declared by slice A but not consumed by slice B
+ *   - type mismatches: types used across slice boundaries
+ *   - signature drift: function signatures changed
+ *
+ * Pure function. No I/O. The CLI is `peaks slice integrate`.
+ */
+/** Build a quick map: export name → owning slice + contract. */
+function buildExportIndex(contracts) {
+    const index = new Map();
+    for (const c of contracts) {
+        for (const exp of c.exports) {
+            index.set(exp, { sliceId: c.sliceId, contract: c });
+        }
+        for (const t of c.types) {
+            index.set(t, { sliceId: c.sliceId, contract: c });
+        }
+    }
+    return index;
+}
+export function integrateSlices(opts) {
+    const contracts = opts.contracts;
+    const findings = [];
+    const index = buildExportIndex(contracts);
+    // 1. duplicate exports: the same export name declared by multiple slices.
+    const seen = new Map(); // export → [sliceIds]
+    for (const c of contracts) {
+        for (const exp of c.exports) {
+            if (!seen.has(exp))
+                seen.set(exp, []);
+            seen.get(exp).push(c.sliceId);
+        }
+    }
+    for (const [exp, owners] of seen) {
+        if (owners.length > 1) {
+            findings.push({
+                severity: 'error',
+                ownerSliceId: owners[0],
+                consumerSliceId: owners[1],
+                kind: 'duplicate-export',
+                message: `export "${exp}" is declared by multiple slices: ${owners.join(', ')}`
+            });
+        }
+    }
+    // 2. signature drift: same export, different publicSignatures across slices.
+    const signatureByExport = new Map(); // exp → signature → [sliceIds]
+    for (const c of contracts) {
+        for (const sig of c.publicSignatures) {
+            // sig format: "exportName:signature"
+            const colonIdx = sig.indexOf(':');
+            if (colonIdx < 0)
+                continue;
+            const name = sig.slice(0, colonIdx);
+            const sigValue = sig.slice(colonIdx + 1);
+            if (!signatureByExport.has(name))
+                signatureByExport.set(name, new Map());
+            const m = signatureByExport.get(name);
+            if (!m.has(sigValue))
+                m.set(sigValue, []);
+            m.get(sigValue).push(c.sliceId);
+        }
+    }
+    for (const [exp, sigMap] of signatureByExport) {
+        if (sigMap.size > 1) {
+            const allSlices = new Set();
+            for (const sl of sigMap.values())
+                for (const s of sl)
+                    allSlices.add(s);
+            findings.push({
+                severity: 'warning',
+                ownerSliceId: Array.from(allSlices)[0],
+                consumerSliceId: Array.from(allSlices)[0],
+                kind: 'signature-drift',
+                message: `export "${exp}" has ${sigMap.size} different signatures across slices: ${Array.from(allSlices).join(', ')}`
+            });
+        }
+    }
+    // 3. info: total export count (for visibility).
+    if (index.size > 0) {
+        findings.push({
+            severity: 'info',
+            ownerSliceId: contracts[0]?.sliceId ?? '<none>',
+            consumerSliceId: '<all>',
+            kind: 'missing-export',
+            message: `${index.size} unique exports / types indexed across ${contracts.length} contracts`
+        });
+    }
+    const errors = findings.filter((f) => f.severity === 'error').length;
+    const warnings = findings.filter((f) => f.severity === 'warning').length;
+    const info = findings.filter((f) => f.severity === 'info').length;
+    return {
+        sliceIds: contracts.map((c) => c.sliceId),
+        totalContracts: contracts.length,
+        findings,
+        summary: { errors, warnings, info },
+        ok: errors === 0
+    };
+}

package/dist/services/slice/slice-pick-service.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Slice Pick Service — thin wrapper around the generic fzf picker.
+ *
+ * v2 (slice 2026-06-14-fzf-headroom-rollout): the actual fzf
+ * integration is now in `src/services/fuzzy-matching/fzf-pick-service.ts`.
+ * This file only knows how to format / parse SliceCandidate rows and
+ * pick the output path. The algorithm itself (slice-decompose-service)
+ * is fzf-free; fzf is the *consumer* of the algorithm output, not an
+ * input to it. v3 can swap fzf for a different selector (skim, peco)
+ * by replacing this file — the algorithm is unaffected.
+ */
+import type { DecompositionResult, SliceCandidate } from './slice-decompose-types.js';
+export interface PickOptions {
+    /** When true, render side-by-side preview in fzf (recommended; needs fzf >= 0.38). */
+    preview?: boolean;
+    /** Override fzf binary path (default: 'fzf'). Useful for tests. */
+    fzfBin?: string;
+    /** Override stdin content for tests; bypasses the actual spawning. */
+    overrideStdin?: string;
+}
+export interface PickedResult {
+    picked: readonly SliceCandidate[];
+    outputPath: string;
+    fzfVersion: string;
+}
+export declare function pickSlicesInteractive(rid: string, decomposition: DecompositionResult, projectRoot: string, options?: PickOptions): Promise<PickedResult>;
+/**
+ * Re-export the fzf pick-service primitives for callers that want to
+ * build their own pickers without depending on the slice namespace.
+ */
+export { pickFromList } from '../fuzzy-matching/fzf-pick-service.js';
+export type { FzfPickOptions, FzfPickResult } from '../fuzzy-matching/fzf-pick-service.js';

package/dist/services/slice/slice-pick-service.js

@@ -0,0 +1,75 @@
+/**
+ * Slice Pick Service — thin wrapper around the generic fzf picker.
+ *
+ * v2 (slice 2026-06-14-fzf-headroom-rollout): the actual fzf
+ * integration is now in `src/services/fuzzy-matching/fzf-pick-service.ts`.
+ * This file only knows how to format / parse SliceCandidate rows and
+ * pick the output path. The algorithm itself (slice-decompose-service)
+ * is fzf-free; fzf is the *consumer* of the algorithm output, not an
+ * input to it. v3 can swap fzf for a different selector (skim, peco)
+ * by replacing this file — the algorithm is unaffected.
+ */
+import { join } from 'node:path';
+import { pickFromList } from '../fuzzy-matching/fzf-pick-service.js';
+/**
+ * Parse one formatted fzf output line into its slice rid. The
+ * formatter writes `B<batch> | <rid> | <label> | <minutesP50>m | <fileList>`,
+ * so the rid is the second `|`-delimited field.
+ */
+function parseSliceLine(line) {
+    const parts = line.split('|').map((p) => p.trim());
+    if (parts.length < 2)
+        return null;
+    const rid = parts[1];
+    if (rid === undefined || rid.length === 0)
+        return null;
+    return { rid };
+}
+export async function pickSlicesInteractive(rid, decomposition, projectRoot, options = {}) {
+    // Flatten candidates from all batches (preserves fzf line order).
+    const candidates = [];
+    for (const batch of decomposition.parallelBatches) {
+        for (const slice of batch.slices) {
+            candidates.push({ batch: batch.batch, slice });
+        }
+    }
+    // Map rid → candidate for O(1) parse lookups instead of O(n) scan per line.
+    const byRid = new Map();
+    for (const c of candidates) {
+        byRid.set(c.slice.rid, c);
+    }
+    const formatLine = ({ batch, slice }) => {
+        const fileList = slice.files.join(',');
+        return `B${batch} | ${slice.rid} | ${slice.label} | ${slice.estimate.minutesP50}m | ${fileList}`;
+    };
+    const outputPath = join(projectRoot, '.peaks', 'sc', 'slice-decomposition', `${rid}-picked.json`);
+    const result = await pickFromList({
+        items: candidates,
+        formatLine,
+        parseLine: (line) => {
+            const parsed = parseSliceLine(line);
+            if (parsed === null)
+                return null;
+            const candidate = byRid.get(parsed.rid);
+            return candidate ?? null;
+        },
+        outputPath,
+        meta: { rid, parentRid: decomposition.rid },
+        ...(options.preview !== undefined ? { preview: options.preview } : {}),
+        ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
+        ...(options.overrideStdin !== undefined ? { overrideStdin: options.overrideStdin } : {}),
+        projectRoot,
+        multi: true,
+        prompt: 'slice> '
+    });
+    return {
+        picked: result.picked.map((c) => c.slice),
+        outputPath: result.outputPath,
+        fzfVersion: result.fzfVersion
+    };
+}
+/**
+ * Re-export the fzf pick-service primitives for callers that want to
+ * build their own pickers without depending on the slice namespace.
+ */
+export { pickFromList } from '../fuzzy-matching/fzf-pick-service.js';

package/dist/services/slice/slice-review-state.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 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
+ */
+export type SliceReviewDecision = 'pending' | 'accepted' | 'rejected';
+export interface SliceReviewItem {
+    /** Item identifier (e.g. "business-match", "boundary-cases", "ui-assembly", "mergeable"). */
+    readonly id: string;
+    /** Human-readable question / check. */
+    readonly question: string;
+    /** User's score 1-5, or null when not yet reviewed. */
+    readonly score: number | null;
+    /** Optional user note (especially on rejection). */
+    readonly note?: string;
+}
+export interface SliceReview {
+    readonly sliceId: string;
+    /** Session id this review belongs to. */
+    readonly sessionId: string;
+    /** ISO when the review was first opened (or the slice completed). */
+    readonly createdAt: string;
+    /** ISO when the user last updated (accepted/rejected). */
+    readonly updatedAt: string;
+    /** Current decision. */
+    readonly decision: SliceReviewDecision;
+    /** The 4-5 review items. */
+    readonly items: readonly SliceReviewItem[];
+    /** Optional reason when decision = rejected. */
+    readonly rejectionReason?: string;
+}
+/** The 5 default review items per slice (the 12 Gaps memory checklist). */
+export declare const DEFAULT_REVIEW_ITEMS: readonly {
+    id: string;
+    question: string;
+}[];
+export declare function buildEmptySliceReview(sliceId: string, sessionId: string, now?: Date): SliceReview;
+export declare function getReviewDir(projectRoot: string, sessionId: string): string;
+export declare function getReviewPath(projectRoot: string, sessionId: string, sliceId: string): string;
+export declare function readSliceReview(projectRoot: string, sessionId: string, sliceId: string): SliceReview | null;
+export declare function writeSliceReview(projectRoot: string, review: SliceReview): void;
+/** Update a single item's score. Returns the new state. */
+export declare function scoreItem(review: SliceReview, itemId: string, score: number, note?: string, now?: Date): SliceReview;
+/** Compute the average score across all scored items. */
+export declare function averageScore(review: SliceReview): number | null;
+/** 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 declare function deriveDecision(review: SliceReview): SliceReviewDecision;
+/** Apply the derived decision to a review (used by `peaks slice accept`). */
+export declare function acceptReview(review: SliceReview, now?: Date): SliceReview;
+export declare function rejectReview(review: SliceReview, reason: string, now?: Date): SliceReview;
+/** Render the review as a user-facing checklist (for `peaks slice review`). */
+export interface ReviewChecklistItem {
+    readonly id: string;
+    readonly question: string;
+    readonly currentScore: number | null;
+    readonly prompt: string;
+}
+export declare function renderChecklist(review: SliceReview): readonly ReviewChecklistItem[];