peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/fork/fork-sync-state.d.ts

@@ -0,0 +1,85 @@
+/**
+ * v2.15.0 follow-up — G11: fork sync state service.
+ *
+ * Tracks the local fork's relationship to its upstream: which tag the
+ * fork is based on, how many commits / files it has diverged, and a
+ * history of past syncs. Persistence: `.peaks/fork-state.json` in the
+ * project root.
+ *
+ * Pure functions on top of a typed state object. The CLI surfaces 5
+ * commands (status / upstream-check / sync-plan / sync / sync-verify)
+ * but the actual upstream fetch + merge is deferred to a follow-up
+ * slice; this slice ships the model + the dry-run / plan / record path.
+ */
+export interface ForkBaseline {
+    /** Upstream repo identifier (e.g. "github.com/xxx/hermes"). */
+    readonly upstream: string;
+    /** Tag or commit the fork is currently based on. */
+    readonly basedOn: string;
+    /** ISO timestamp when the baseline was recorded. */
+    readonly recordedAt: string;
+    /** Number of commits the local fork is ahead of the baseline. */
+    readonly commitsAhead: number;
+    /** Number of files the local fork has changed vs the baseline. */
+    readonly filesChanged: number;
+}
+export interface ForkSyncRecord {
+    /** Sync plan id (e.g. "sync-2026-06-28-v1.20.0"). */
+    readonly syncId: string;
+    /** Target upstream tag. */
+    readonly targetTag: string;
+    /** ISO timestamp when the sync plan was created. */
+    readonly plannedAt: string;
+    /** Predicted conflict points (file globs / paths). */
+    readonly predictedConflicts: readonly string[];
+    /** Business patches that need to be replayed after the sync. */
+    readonly businessPatches: readonly string[];
+    /** Sync status. */
+    readonly status: 'planned' | 'in-progress' | 'verified' | 'failed';
+    /** Optional verification notes. */
+    readonly verificationNotes?: string;
+}
+export interface ForkState {
+    /** Schema version (currently 1). */
+    readonly version: 1;
+    /** Current baseline (null when the project is not a fork). */
+    readonly baseline: ForkBaseline | null;
+    /** History of sync plans + results. */
+    readonly history: readonly ForkSyncRecord[];
+}
+export declare const EMPTY_FORK_STATE: ForkState;
+export declare function getForkStatePath(projectRoot: string): string;
+export declare function readForkState(projectRoot: string): ForkState;
+export declare function writeForkState(projectRoot: string, state: ForkState): void;
+/**
+ * Record a new sync plan. The state is immutable; the returned state
+ * has the new plan appended to `history`.
+ */
+export declare function appendSyncRecord(state: ForkState, record: ForkSyncRecord): ForkState;
+/**
+ * Update an existing sync record's status (e.g. planned → verified).
+ * Returns the state unchanged when the record is not found.
+ */
+export declare function updateSyncRecordStatus(state: ForkState, syncId: string, status: ForkSyncRecord['status'], notes?: string): ForkState;
+/**
+ * Generate a sync plan id from a target tag. Format:
+ * `sync-<ISO-date>-<tag-sanitized>`.
+ */
+export declare function makeSyncId(targetTag: string, now?: Date): string;
+/**
+ * Recommend stable tags to sync to, given a list of available tags.
+ * "Stable" = no pre-release suffix (no `-alpha`, `-beta`, `-rc`).
+ * Picks the latest stable tag that is NEWER than the current baseline.
+ */
+export declare function recommendStableTags(availableTags: readonly string[], currentBaseline: string | null): string[];
+/**
+ * Build a fork-status report from current state.
+ */
+export interface ForkStatusReport {
+    readonly hasBaseline: boolean;
+    readonly baseline: ForkBaseline | null;
+    readonly syncCount: number;
+    readonly lastSync: ForkSyncRecord | null;
+    readonly driftWarning: boolean;
+}
+export declare function buildForkStatusReport(state: ForkState): ForkStatusReport;

package/dist/services/fork/fork-sync-state.js

@@ -0,0 +1,130 @@
+/**
+ * v2.15.0 follow-up — G11: fork sync state service.
+ *
+ * Tracks the local fork's relationship to its upstream: which tag the
+ * fork is based on, how many commits / files it has diverged, and a
+ * history of past syncs. Persistence: `.peaks/fork-state.json` in the
+ * project root.
+ *
+ * Pure functions on top of a typed state object. The CLI surfaces 5
+ * commands (status / upstream-check / sync-plan / sync / sync-verify)
+ * but the actual upstream fetch + merge is deferred to a follow-up
+ * slice; this slice ships the model + the dry-run / plan / record path.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+export const EMPTY_FORK_STATE = {
+    version: 1,
+    baseline: null,
+    history: []
+};
+const STATE_FILE = '.peaks/fork-state.json';
+export function getForkStatePath(projectRoot) {
+    return resolve(projectRoot, STATE_FILE);
+}
+export function readForkState(projectRoot) {
+    const path = getForkStatePath(projectRoot);
+    if (!existsSync(path))
+        return EMPTY_FORK_STATE;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return EMPTY_FORK_STATE;
+        return {
+            version: 1,
+            baseline: parsed.baseline ?? null,
+            history: Array.isArray(parsed.history) ? parsed.history : []
+        };
+    }
+    catch {
+        return EMPTY_FORK_STATE;
+    }
+}
+export function writeForkState(projectRoot, state) {
+    const path = getForkStatePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2), 'utf8');
+}
+/**
+ * Record a new sync plan. The state is immutable; the returned state
+ * has the new plan appended to `history`.
+ */
+export function appendSyncRecord(state, record) {
+    return {
+        version: 1,
+        baseline: state.baseline,
+        history: [...state.history, record]
+    };
+}
+/**
+ * Update an existing sync record's status (e.g. planned → verified).
+ * Returns the state unchanged when the record is not found.
+ */
+export function updateSyncRecordStatus(state, syncId, status, notes) {
+    let found = false;
+    const history = state.history.map((r) => {
+        if (r.syncId !== syncId)
+            return r;
+        found = true;
+        return {
+            ...r,
+            status,
+            ...(notes !== undefined ? { verificationNotes: notes } : {})
+        };
+    });
+    if (!found)
+        return state;
+    return { ...state, history };
+}
+/**
+ * Generate a sync plan id from a target tag. Format:
+ * `sync-<ISO-date>-<tag-sanitized>`.
+ */
+export function makeSyncId(targetTag, now = new Date()) {
+    const date = now.toISOString().slice(0, 10);
+    const safeTag = targetTag.replace(/[^A-Za-z0-9._-]/g, '-');
+    return `sync-${date}-${safeTag}`;
+}
+/**
+ * Recommend stable tags to sync to, given a list of available tags.
+ * "Stable" = no pre-release suffix (no `-alpha`, `-beta`, `-rc`).
+ * Picks the latest stable tag that is NEWER than the current baseline.
+ */
+export function recommendStableTags(availableTags, currentBaseline) {
+    const isStable = (t) => !/(?:^|-)(?:alpha|beta|rc|dev|preview)/i.test(t);
+    const stable = availableTags.filter(isStable);
+    // Sort by semver-like order (best effort): split on '.', parse ints.
+    const cmp = (a, b) => {
+        // Strip leading 'v' before splitting on '.' or '-' so 'v1' → [1]
+        const toParts = (t) => t
+            .replace(/^v/i, '')
+            .split(/[.\-]/)
+            .map((s) => Number.parseInt(s, 10) || 0);
+        const pa = toParts(a);
+        const pb = toParts(b);
+        for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+            const da = pa[i] ?? 0;
+            const db = pb[i] ?? 0;
+            if (da !== db)
+                return da - db;
+        }
+        return 0;
+    };
+    stable.sort(cmp);
+    if (currentBaseline === null)
+        return stable;
+    const idx = stable.indexOf(currentBaseline);
+    return idx >= 0 ? stable.slice(idx + 1) : stable;
+}
+export function buildForkStatusReport(state) {
+    const lastSync = state.history.length > 0 ? state.history[state.history.length - 1] : null;
+    const drift = state.baseline !== null && state.baseline.commitsAhead > 30;
+    return {
+        hasBaseline: state.baseline !== null,
+        baseline: state.baseline,
+        syncCount: state.history.length,
+        lastSync,
+        driftWarning: drift
+    };
+}

package/dist/services/fuzzy-matching/fuzzy-match-service.d.ts

@@ -0,0 +1,15 @@
+import type { FuzzyMatchOptions, FuzzyMatchResult } from './types.js';
+/**
+ * String-overload: when `items` is an array of strings, the searchable text
+ * is the string itself. No keyFn is required.
+ */
+export declare function fuzzyMatch<T extends string>(query: string, items: T[], options?: FuzzyMatchOptions): FuzzyMatchResult<T>[];
+/**
+ * Object-overload: caller provides a `keyFn` that extracts the searchable
+ * text from each item. The keyFn is invoked once per item per call; the
+ * caller is responsible for ensuring the result is stable (e.g., don't
+ * concatenate mutable fields).
+ */
+export declare function fuzzyMatchWithKey<T>(query: string, items: T[], options: FuzzyMatchOptions & {
+    keyFn: (item: T) => string;
+}): FuzzyMatchResult<T>[];

package/dist/services/fuzzy-matching/fuzzy-match-service.js

@@ -0,0 +1,56 @@
+import { Fzf } from 'fzf';
+/**
+ * Default limit for fuzzy-match. Aligned with the spec's "--limit default 6".
+ */
+const DEFAULT_LIMIT = 6;
+/**
+ * String-overload: when `items` is an array of strings, the searchable text
+ * is the string itself. No keyFn is required.
+ */
+export function fuzzyMatch(query, items, options = {}) {
+    return fuzzyMatchWithKey(query, items, { ...options, keyFn: (item) => item });
+}
+/**
+ * Object-overload: caller provides a `keyFn` that extracts the searchable
+ * text from each item. The keyFn is invoked once per item per call; the
+ * caller is responsible for ensuring the result is stable (e.g., don't
+ * concatenate mutable fields).
+ */
+export function fuzzyMatchWithKey(query, items, options) {
+    const { keyFn } = options;
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    if (items.length === 0)
+        return [];
+    // Empty query: surface all items (capped at limit) with neutral score and
+    // empty positions. Useful for "list" or "preview" use cases where the
+    // caller wants a deterministic top-N without a query.
+    if (query === '') {
+        return items.slice(0, limit).map((item) => ({ item, score: 0, positions: [] }));
+    }
+    const fzf = new Fzf(items, {
+        selector: keyFn,
+        limit,
+        // Per spec: default is case-insensitive (NOT fzf's smart-case).
+        // The user explicitly opts into case-sensitive via caseSensitive:true.
+        casing: options.caseSensitive === true ? 'case-sensitive' : 'case-insensitive',
+        // normalize:true (default) strips diacritics; fzf returns more matches
+        // for non-ASCII text this way, which is what we want for
+        // bilingual (zh-CN + en) memory entries.
+    });
+    const raw = fzf.find(query);
+    if (raw.length === 0)
+        return [];
+    // fzf-for-js score is "higher = better". Normalize so the top of the
+    // current batch is exactly 1.0 and others are in [0, 1].
+    // When the top score is 0 (degenerate — exact-character-only query that
+    // still matched somehow), fall back to 1.0 to avoid divide-by-zero.
+    const topScore = raw[0]?.score ?? 1;
+    const denom = topScore > 0 ? topScore : 1;
+    return raw.slice(0, limit).map((entry) => {
+        const score = topScore > 0 ? Number((entry.score / denom).toFixed(4)) : 1;
+        // positions is a Set<number> in fzf-for-js; convert to a sorted array
+        // so the JSON envelope is stable and human-readable.
+        const positions = [...entry.positions].sort((a, b) => a - b);
+        return { item: entry.item, score, positions };
+    });
+}

package/dist/services/fuzzy-matching/fzf-pick-service.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Generic fzf binary picker (slice 2026-06-14-fzf-headroom-rollout).
+ *
+ * Promoted from `src/services/slice/slice-pick-service.ts` (which is
+ * the only prior caller). Encapsulates the canonical fzf integration
+ * pattern: format items as one-line text, spawn `fzf --multi`, parse
+ * the multi-selection, write a `<list-id>-picked.json` artifact.
+ *
+ * Two distinct things live in `src/services/fuzzy-matching/`:
+ *  - `fuzzy-match-service.ts` — in-process fzf *npm package* (the
+ *    Fzf class). Used by `memory search` / `retrospective search`.
+ *  - `fzf-pick-service.ts`    — spawns the fzf *binary* for
+ *    interactive TTY multi-select. Used by `peaks slice pick`,
+ *    `peaks memory list --pick`, `peaks retrospective index --pick`.
+ *
+ * The two are independent (one is a library, the other spawns a CLI);
+ * do not merge them. fzf-for-js returns positions; the binary returns
+ * raw lines. Different output shapes → different consumers.
+ *
+ * Source-of-truth: the binary is the *consumer* of the formatter
+ * output, not an input. Each caller injects its own `formatLine` and
+ * `parseLine` so a future swap to skim/peco is a one-line change per
+ * caller, not a refactor of this service.
+ */
+export interface FzfPickOptions<T> {
+    readonly items: readonly T[];
+    /** Render a single item as one line of fzf input. Must round-trip with parseLine. */
+    readonly formatLine: (item: T) => string;
+    /** Reconstruct an item from a fzf output line. Return null to drop the line. */
+    readonly parseLine: (line: string) => T | null;
+    /** Absolute path for the output artifact. Caller decides the directory layout. */
+    readonly outputPath: string;
+    /** Metadata to embed in the picked artifact (rid, parentId, etc). */
+    readonly meta: Record<string, unknown>;
+    /** Run `fzf --preview 'cat'` (recommended; needs fzf >= 0.38). */
+    readonly preview?: boolean;
+    /** Override fzf binary path (default: 'fzf'). Useful for tests. */
+    readonly fzfBin?: string;
+    /** Override stdin content for tests; bypasses the actual spawning. */
+    readonly overrideStdin?: string;
+    /** Working directory for the fzf spawn. */
+    readonly projectRoot: string;
+    /** fzf --multi toggle (default true; pass false for single-select). */
+    readonly multi?: boolean;
+    /** Custom fzf prompt string (default "pick> "). */
+    readonly prompt?: string;
+}
+export interface FzfPickResult<T> {
+    readonly picked: readonly T[];
+    readonly outputPath: string;
+    readonly fzfVersion: string;
+}
+export declare const MIN_FZF_VERSION = "0.38";
+/**
+ * Pick a subset of `items` interactively via fzf. The full flow:
+ *   1. Check fzf presence + version.
+ *   2. Format items as one-line text (caller's formatLine).
+ *   3. Spawn `fzf --multi` (or test override).
+ *   4. Parse the multi-selection back into T[] (caller's parseLine).
+ *   5. Write `<outputPath>` with the picked + meta + fzfVersion.
+ *
+ * Failure modes:
+ *   - fzf missing → throws with `brew install fzf | apt-get install fzf` hint.
+ *   - fzf version too old → throws.
+ *   - fzf exits 130 (Esc) → returns `{ picked: [], outputPath, fzfVersion }` (NOT thrown).
+ *   - parseLine returns null for a line → silently dropped (line ignored).
+ */
+export declare function pickFromList<T>(options: FzfPickOptions<T>): Promise<FzfPickResult<T>>;

package/dist/services/fuzzy-matching/fzf-pick-service.js

@@ -0,0 +1,158 @@
+/**
+ * Generic fzf binary picker (slice 2026-06-14-fzf-headroom-rollout).
+ *
+ * Promoted from `src/services/slice/slice-pick-service.ts` (which is
+ * the only prior caller). Encapsulates the canonical fzf integration
+ * pattern: format items as one-line text, spawn `fzf --multi`, parse
+ * the multi-selection, write a `<list-id>-picked.json` artifact.
+ *
+ * Two distinct things live in `src/services/fuzzy-matching/`:
+ *  - `fuzzy-match-service.ts` — in-process fzf *npm package* (the
+ *    Fzf class). Used by `memory search` / `retrospective search`.
+ *  - `fzf-pick-service.ts`    — spawns the fzf *binary* for
+ *    interactive TTY multi-select. Used by `peaks slice pick`,
+ *    `peaks memory list --pick`, `peaks retrospective index --pick`.
+ *
+ * The two are independent (one is a library, the other spawns a CLI);
+ * do not merge them. fzf-for-js returns positions; the binary returns
+ * raw lines. Different output shapes → different consumers.
+ *
+ * Source-of-truth: the binary is the *consumer* of the formatter
+ * output, not an input. Each caller injects its own `formatLine` and
+ * `parseLine` so a future swap to skim/peco is a one-line change per
+ * caller, not a refactor of this service.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const MIN_FZF_VERSION = '0.38';
+const SPAWN_TIMEOUT_MS = 60_000;
+const MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+/**
+ * Pick a subset of `items` interactively via fzf. The full flow:
+ *   1. Check fzf presence + version.
+ *   2. Format items as one-line text (caller's formatLine).
+ *   3. Spawn `fzf --multi` (or test override).
+ *   4. Parse the multi-selection back into T[] (caller's parseLine).
+ *   5. Write `<outputPath>` with the picked + meta + fzfVersion.
+ *
+ * Failure modes:
+ *   - fzf missing → throws with `brew install fzf | apt-get install fzf` hint.
+ *   - fzf version too old → throws.
+ *   - fzf exits 130 (Esc) → returns `{ picked: [], outputPath, fzfVersion }` (NOT thrown).
+ *   - parseLine returns null for a line → silently dropped (line ignored).
+ */
+export async function pickFromList(options) {
+    const fzfBin = options.fzfBin ?? 'fzf';
+    const fzfVersion = checkFzfVersion(fzfBin);
+    if (options.items.length === 0) {
+        // Nothing to pick from. Still write an empty picked artifact so
+        // downstream commands have a stable file contract.
+        const emptyPayload = { ...options.meta, pickedAt: new Date().toISOString(), fzfVersion, picked: [] };
+        writeArtifact(options.outputPath, emptyPayload);
+        return { picked: [], outputPath: options.outputPath, fzfVersion };
+    }
+    const fzfInput = options.items.map(options.formatLine).join('\n');
+    const args = [];
+    args.push(options.multi === false ? '--no-multi' : '--multi');
+    args.push(`--prompt=${options.prompt ?? 'pick> '}`);
+    if (options.preview === true) {
+        args.push('--preview', 'cat');
+    }
+    let stdout;
+    if (options.overrideStdin !== undefined) {
+        stdout = options.overrideStdin;
+    }
+    else {
+        try {
+            stdout = execFileSync(fzfBin, args, {
+                input: fzfInput,
+                cwd: options.projectRoot,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                shell: false,
+                timeout: SPAWN_TIMEOUT_MS,
+                maxBuffer: MAX_BUFFER_BYTES
+            }).toString('utf8');
+        }
+        catch (error) {
+            const err = error;
+            if (err.status === 130) {
+                stdout = ''; // user pressed Esc
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    const selectedLines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const seen = new Set();
+    const picked = [];
+    for (const line of selectedLines) {
+        const item = options.parseLine(line);
+        if (item === null)
+            continue;
+        // Dedup by JSON serialization (caller's T may not be hashable otherwise).
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        picked.push(item);
+    }
+    const payload = { ...options.meta, pickedAt: new Date().toISOString(), fzfVersion, picked };
+    writeArtifact(options.outputPath, payload);
+    return { picked, outputPath: options.outputPath, fzfVersion };
+}
+function checkFzfVersion(fzfBin) {
+    let stdout;
+    try {
+        stdout = execFileSync(fzfBin, ['--version'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
+            timeout: 5_000
+        }).toString('utf8');
+    }
+    catch (error) {
+        if (isEnoent(error) || isCommandNotFound(error)) {
+            throw new Error(`fzf binary not found. Install with: brew install fzf  (or apt: apt-get install fzf). ` +
+                `fzf >= ${MIN_FZF_VERSION} is required for interactive list picking.`);
+        }
+        throw error;
+    }
+    const version = stdout.trim().split('\n')[0] ?? '';
+    if (compareVersions(version, MIN_FZF_VERSION) < 0) {
+        throw new Error(`fzf version ${version} is older than required ${MIN_FZF_VERSION}`);
+    }
+    return version;
+}
+function compareVersions(a, b) {
+    const aParts = a.split('.').map((p) => parseInt(p, 10) || 0);
+    const bParts = b.split('.').map((p) => parseInt(p, 10) || 0);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i += 1) {
+        const av = aParts[i] ?? 0;
+        const bv = bParts[i] ?? 0;
+        if (av < bv)
+            return -1;
+        if (av > bv)
+            return 1;
+    }
+    return 0;
+}
+function isEnoent(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    return error.code === 'ENOENT';
+}
+function isCommandNotFound(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    const msg = error.message ?? '';
+    return /command not found|not found/i.test(msg);
+}
+function writeArtifact(outputPath, payload) {
+    const dir = dirname(outputPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(outputPath, JSON.stringify(payload, null, 2), 'utf8');
+}

package/dist/services/fuzzy-matching/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Options for the generic fuzzy-match kernel.
+ */
+export interface FuzzyMatchOptions {
+    /** Maximum number of matches to return. Default 6. */
+    limit?: number;
+    /** When true, matching is case-sensitive. Default false (smart-case). */
+    caseSensitive?: boolean;
+}
+/**
+ * A single fuzzy-match hit. `item` is the original entry; `score` is
+ * normalized to [0, 1] with the top of the current batch at 1.0;
+ * `positions` is the set of char indices in the searchable text that
+ * contributed to the match.
+ */
+export interface FuzzyMatchResult<T> {
+    item: T;
+    score: number;
+    positions: number[];
+}

package/dist/services/fuzzy-matching/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/handoff/handoff-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Handoff frontmatter — parser.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Reads a markdown handoff file from disk and splits it into:
+ *   - `frontmatter`: structured `HandoffFrontmatter` (parsed from YAML)
+ *   - `body`:        the trailing prose
+ *
+ * Backward compat: legacy handoffs without a `---` frontmatter block are
+ * returned with `schema_version: '0'` and `status: 'unknown'` so older
+ * artifacts remain readable without any migration step.
+ *
+ * Required-field enforcement: any `HandoffFrontmatter` with schema_version
+ * `'1'` MUST carry all six required fields. Missing fields raise
+ * `IncompleteHandoffError` rather than silently substituting defaults.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+export declare class IncompleteHandoffError extends Error {
+    readonly code: "INCOMPLETE_HANDOFF";
+    constructor(message: string);
+}
+export interface ParsedHandoff {
+    readonly frontmatter: HandoffFrontmatter;
+    readonly body: string;
+}
+export declare function parseHandoff(filePath: string): ParsedHandoff;

package/dist/services/handoff/handoff-parser.js

@@ -0,0 +1,69 @@
+/**
+ * Handoff frontmatter — parser.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Reads a markdown handoff file from disk and splits it into:
+ *   - `frontmatter`: structured `HandoffFrontmatter` (parsed from YAML)
+ *   - `body`:        the trailing prose
+ *
+ * Backward compat: legacy handoffs without a `---` frontmatter block are
+ * returned with `schema_version: '0'` and `status: 'unknown'` so older
+ * artifacts remain readable without any migration step.
+ *
+ * Required-field enforcement: any `HandoffFrontmatter` with schema_version
+ * `'1'` MUST carry all six required fields. Missing fields raise
+ * `IncompleteHandoffError` rather than silently substituting defaults.
+ */
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+export class IncompleteHandoffError extends Error {
+    code = 'INCOMPLETE_HANDOFF';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompleteHandoffError';
+    }
+}
+const REQUIRED_FIELDS = [
+    'rid',
+    'slice_id',
+    'agent_id',
+    'schema_version',
+    'status',
+    'created_at'
+];
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+export function parseHandoff(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match) {
+        return legacyDefaults(content);
+    }
+    const [, yamlContent, body] = match;
+    const parsed = parseYaml(yamlContent ?? '');
+    if (parsed === null || parsed === undefined) {
+        return legacyDefaults(content);
+    }
+    const missing = REQUIRED_FIELDS.filter((f) => parsed[f] === undefined);
+    if (missing.length > 0) {
+        throw new IncompleteHandoffError(`Missing required frontmatter fields: ${missing.join(', ')}`);
+    }
+    return {
+        frontmatter: parsed,
+        body: body ?? ''
+    };
+}
+function legacyDefaults(content) {
+    return {
+        frontmatter: {
+            rid: 'unknown',
+            slice_id: 'unknown',
+            agent_id: 'unknown',
+            schema_version: '0',
+            status: 'unknown',
+            created_at: new Date(0).toISOString()
+        },
+        body: content
+    };
+}

package/dist/services/handoff/handoff-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Handoff frontmatter schema — types.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4 (Handoff frontmatter types + parser + writer).
+ *
+ * A handoff artifact is a markdown file with a YAML frontmatter block
+ * carrying structured fields (rid, slice_id, status, ...) followed by a
+ * prose body. The frontmatter is the source of truth for downstream
+ * automation (peaks-rd, peaks-qa); the body is human/agent prose.
+ *
+ * Two schema versions exist:
+ *   - "0" — legacy handoff (no frontmatter block). Fields default to
+ *           `rid='unknown'`, `slice_id='unknown'`, `agent_id='unknown'`,
+ *           `status='unknown'`, `created_at=epoch`.
+ *   - "1" — current schema. All required fields must be present; the
+ *           parser throws `IncompleteHandoffError` if any are missing.
+ */
+export type HandoffStatus = 'done' | 'failed' | 'partial' | 'blocked' | 'unknown';
+export type HandoffTestResult = 'pass' | 'fail' | 'inconclusive' | null;
+export type HandoffSchemaVersion = '0' | '1';
+export interface HandoffFrontmatter {
+    readonly rid: string;
+    readonly slice_id: string;
+    readonly agent_id: string;
+    readonly schema_version: HandoffSchemaVersion;
+    readonly status: HandoffStatus;
+    readonly created_at: string;
+    readonly duration_seconds?: number;
+    readonly files_changed?: readonly string[];
+    readonly lines_added?: number;
+    readonly lines_removed?: number;
+    readonly test_result?: HandoffTestResult;
+    readonly coverage?: number;
+    readonly errors?: readonly string[];
+    readonly warnings?: readonly string[];
+    readonly blockers?: readonly string[];
+    readonly upstream_dependencies?: readonly string[];
+}