peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/perf/perf-baseline-service.js

@@ -0,0 +1,214 @@
+/**
+ * Performance baseline scaffolding for the RD stage.
+ *
+ * peaks-code's RD stage runs before the QA stage. The user-facing pain is
+ * that performance tests (lighthouse / k6 / project-local benches / etc.)
+ * have historically only been run at QA Gate A4 — too late in the loop,
+ * because a slow regression discovered at QA triggers a return-to-rd
+ * cycle, the RD ships another "fix", QA re-runs, and the same cycle
+ * repeats up to 3 times before the slice ships.
+ *
+ * `peaks perf baseline` is the user-visible artifact of a deliberate
+ * compromise: keep the heavy performance measurement as something the
+ * RD runs themselves (lighthouse is project-shape dependent and we
+ * don't want to bake a lighthouse dependency into the CLI), but capture
+ * the result in a stable, scaffolded file under
+ * `.peaks/_runtime/<sid>/rd/perf-baseline.md` so QA Gate A4 has a known-good
+ * reference to diff against. The CLI itself only writes the scaffold
+ * and records the path; the actual measurement is a project-local
+ * concern that lives in the README, not in peaks-loop.
+ *
+ * The four-grounds check (per the skill-primary-CLI-auxiliary dev
+ * preference):
+ *   1. hook/script/CI invokability  — yes, a hook can call this CLI
+ *                                     to scaffold the file on session
+ *                                     init, similar to session bootstrap.
+ *   2. JSON envelope that gates a downstream decision — yes,
+ *                                     peaks-rd reads the result and
+ *                                     attaches it to the handoff.
+ *   3. Destructive --apply side effect — yes, default dry-run.
+ *   4. Machine-enforced gate that prose cannot enforce — no, the
+ *                                     measurement still lives in
+ *                                     the LLM / project tools. We do
+ *                                     NOT add a lint gate here.
+ *
+ * Net: CLI is justified. The destructive --apply default is dry-run,
+ * matching the rest of peaks-loop's scaffolding pattern.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionId } from '../session/session-manager.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { findProjectRoot } from '../config/config-safety.js';
+const README_BODY = `# Performance baseline
+
+> Scaffolding for the RD-side performance baseline. Created by
+> \`peaks perf baseline\`. The actual measurement is the RD's
+> responsibility — see the "How to fill this in" section below.
+
+## Why this exists
+
+The QA stage's Gate A4 (performance check) compares the slice's
+performance against the most recent baseline. Without an RD-side
+baseline, the first time Gate A4 runs it has nothing to compare
+against and any regression it finds is a blind-side surprise.
+Capturing the baseline at the RD stage — right after the
+implementation lands and before QA picks it up — closes that
+gap and prevents the "QA returns 3 times for the same perf
+regression" loop.
+
+## What to capture
+
+For each performance-sensitive code path in the slice, record:
+
+- **Path / route** — which entry point (page, hook, API) the
+  measurement targets.
+- **Workload** — what you did with it (cold load, hot loop, the
+  exact N of records the slice introduces).
+- **Tool** — lighthouse / k6 / autocannon / project-local bench
+  script. Match the tool to the workload; do not introduce a new
+  one if the project already has a benchmark script.
+- **Metrics** — at minimum LCP / FCP / TBT / CLS for frontend,
+  p50/p95/p99 latency + rps for backend, rss / heap growth
+  for long-running services.
+- **Baseline value** — the number you measured, with units.
+- **Threshold** — what the slice's PRD / acceptance criteria
+  consider acceptable. If the PRD does not specify, leave this
+  field as \`TBD (ask PM)\` and surface it in the RD handoff.
+
+## How to fill this in
+
+1. Run the project's chosen performance tool against the
+   implementation you just landed. If the project does not have
+   a tool yet, the lightest first step is the chrome devtools
+   performance tab on the touched route.
+2. For each metric, copy the row from "What to capture" into
+   the "Results" table below and fill in the number.
+3. The threshold is the bar QA Gate A4 will compare against.
+   Be conservative — if the threshold is tighter than what the
+   tool reports, Gate A4 will fail.
+
+## Results
+
+| Path / route | Workload | Tool | Metric | Baseline | Threshold |
+|---|---|---|---|---|---|
+|  |  |  |  |  |  |
+
+## Notes
+
+- If the slice is documentation-only or has no user-visible
+  performance surface, write \`N/A — no perf surface\` here and
+  surface that fact in the RD handoff.
+- If the measurement exceeded the threshold on the first run,
+  do NOT loosen the threshold to make it pass. The right move
+  is to optimise the implementation and re-measure, or to
+  surface the trade-off to the PRD owner for a threshold bump.
+
+## Handoff
+
+- to peaks-qa: the \`Results\` table is the input to Gate A4.
+  Without it QA cannot establish a comparison baseline.
+- to peaks-sc: any threshold bumps captured here belong in the
+  release notes if the threshold moved.
+`;
+function renderBaselineTemplate() {
+    return README_BODY;
+}
+function buildPlan(projectRoot, apply) {
+    const sessionId = getSessionId(projectRoot);
+    const sessionRoot = sessionId !== null
+        ? getSessionDir(projectRoot, sessionId)
+        : null;
+    const perfBaselinePath = sessionRoot !== null
+        ? join(sessionRoot, 'rd', 'perf-baseline.md')
+        : null;
+    const plannedWrites = [];
+    if (sessionRoot !== null && perfBaselinePath !== null) {
+        plannedWrites.push({
+            path: join(sessionRoot, 'rd'),
+            kind: 'directory',
+            bytes: 0,
+            content: ''
+        });
+        plannedWrites.push({
+            path: perfBaselinePath,
+            kind: 'file',
+            bytes: 0,
+            content: renderBaselineTemplate()
+        });
+        for (const write of plannedWrites) {
+            if (write.kind === 'file') {
+                write.bytes = Buffer.byteLength(write.content, 'utf8');
+            }
+        }
+    }
+    return {
+        apply,
+        projectRoot,
+        sessionId,
+        perfBaselinePath,
+        plannedWrites,
+        alreadyInitialized: false,
+        existingFiles: []
+    };
+}
+/**
+ * Idempotency: skip writes for the perf-baseline file when it
+ * already exists. Re-running `peaks perf baseline` on the same
+ * session is a normal RD retry pattern (re-measurement, threshold
+ * adjustment, etc.); we must not blow away hand-edited content.
+ */
+async function planPerfBaselineInit(options) {
+    const plan = buildPlan(options.projectRoot, options.apply ?? false);
+    if (plan.perfBaselinePath !== null && existsSync(plan.perfBaselinePath)) {
+        plan.alreadyInitialized = true;
+        plan.existingFiles = [plan.perfBaselinePath];
+        plan.plannedWrites = [];
+    }
+    return plan;
+}
+export async function executePerfBaselineInit(options) {
+    const plan = await planPerfBaselineInit(options);
+    const writtenFiles = [];
+    const createdDirectories = [];
+    if (plan.sessionId === null) {
+        return {
+            ...plan,
+            ...(options.reason !== undefined ? { reason: options.reason } : {}),
+            writtenFiles,
+            createdDirectories
+        };
+    }
+    if (plan.apply && !plan.alreadyInitialized) {
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory') {
+                if (!existsSync(write.path)) {
+                    await mkdir(write.path, { recursive: true });
+                    createdDirectories.push(write.path);
+                }
+                continue;
+            }
+            if (write.content.length === 0)
+                continue;
+            await writeFile(write.path, write.content, 'utf8');
+            writtenFiles.push(write.path);
+        }
+    }
+    return {
+        ...plan,
+        ...(options.reason !== undefined ? { reason: options.reason } : {}),
+        writtenFiles,
+        createdDirectories
+    };
+}
+/**
+ * Re-exported so the CLI command can fall back to a project-root
+ * resolution when the caller did not pass --project. The CLI does
+ * the same findProjectRoot walk that `workspace init` does; this
+ * helper exists for the command layer to import without reaching
+ * into config-safety directly.
+ */
+export function resolveProjectRootFromCwd(cwd) {
+    return findProjectRoot(cwd) ?? cwd;
+}

package/dist/services/polyrepo/polyrepo-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import type { PolyrepoDispatch, PolyrepoManifest } from './polyrepo-types.js';
+export interface DispatchOptions {
+    /** Manifest returned by scanPolyrepo (root + children list). */
+    readonly manifest: PolyrepoManifest;
+    /** Session id this dispatch belongs to. */
+    readonly sid: string;
+    /** Request id (used in the on-disk filename). */
+    readonly rid: string;
+    /** Target child ids. Empty = root-only dispatch. Unknown ids are
+     *  recorded as warnings in the result, NOT raised as errors. */
+    readonly targets: readonly string[];
+    /** Artifact body — the role + source path on the parent side. */
+    readonly artifact: PolyrepoDispatch['artifact'];
+}
+export interface ChildDispatchResult {
+    readonly childId: string;
+    readonly path: string;
+    readonly ok: boolean;
+    readonly error?: string;
+    /** Where the artifact was mirrored to (child-side path). */
+    readonly mirroredTo?: string;
+}
+export interface DispatchResult {
+    readonly dispatch: PolyrepoDispatch;
+    readonly perChild: ChildDispatchResult[];
+    readonly warnings: string[];
+}
+export declare function dispatchArtifact(opts: DispatchOptions): DispatchResult;
+/** Default location of the polyrepo manifest on disk. */
+export declare function manifestPath(root: string): string;
+/** Read a persisted manifest from disk. Returns null when missing. */
+export declare function readManifest(root: string): PolyrepoManifest | null;
+/** Write a manifest atomically. */
+export declare function writeManifest(root: string, manifest: PolyrepoManifest): void;

package/dist/services/polyrepo/polyrepo-dispatcher.js

@@ -0,0 +1,119 @@
+/**
+ * Polyrepo dispatcher — slice S2-b of RD-2.
+ *
+ * Takes a parent root + a list of target child ids + a PRD/RD/QA
+ * artifact, and mirrors the artifact into each target child's
+ * `.peaks/_runtime/<sid>/<role>/` directory. Mirroring is
+ * best-effort + atomic per child: a failure in one child does NOT
+ * block the others (the dispatcher collects per-child results and
+ * returns them all so the caller can surface partial successes).
+ *
+ * Design notes:
+ *  - Per the project's two-axis convention, the parent's reviewable
+ *    artifact lives under `.peaks/_runtime/<sid>/<role>/`, not as a
+ *    sibling of `.peaks/_runtime/`. We mirror the same shape into
+ *    each child (the child does NOT inherit the parent's session
+ *    id verbatim — it gets the same one, which is fine because the
+ *    sid is the project's binding, not the parent's transient
+ *    pid).
+ *  - The dispatcher does NOT spawn any vendor verb — vendor
+ *    neutrality is preserved. If a child has no peaks-loop binary
+ *    on PATH, the dispatcher writes the artifact to disk and notes
+ *    a `peaksInstalled: false` warning; the user / a future slice
+ *    can pick it up. Per PRD §5 mitigation for "child has no
+ *    peaks-loop installed".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Compute the child-side path where the artifact should be mirrored.
+ *  Mirrors the parent shape exactly: `.peaks/_runtime/<sid>/<role>/`. */
+function childArtifactPath(childRoot, sid, role, sourcePath) {
+    const filename = sourcePath.split(/[\\/]/).pop() ?? 'artifact.md';
+    return join(childRoot, '.peaks', '_runtime', sid, role, filename);
+}
+function ensureDirFor(file) {
+    mkdirSync(dirname(file), { recursive: true });
+}
+export function dispatchArtifact(opts) {
+    const warnings = [];
+    const perChild = [];
+    // Validate targets against the manifest.
+    const knownIds = new Set(opts.manifest.children.map((c) => c.id));
+    const validTargets = [];
+    for (const t of opts.targets) {
+        if (knownIds.has(t)) {
+            validTargets.push(t);
+        }
+        else {
+            warnings.push(`unknown target id "${t}" — ignored`);
+        }
+    }
+    // Read the source artifact body once (so we can mirror to N children).
+    let sourceBody;
+    try {
+        sourceBody = readFileSync(opts.artifact.path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`source artifact unreadable at ${opts.artifact.path}: ${err.message}`);
+    }
+    // Per-child write.
+    for (const targetId of validTargets) {
+        const child = opts.manifest.children.find((c) => c.id === targetId);
+        if (child === undefined)
+            continue; // already filtered above
+        const dest = childArtifactPath(child.path, opts.sid, opts.artifact.role, opts.artifact.path);
+        try {
+            ensureDirFor(dest);
+            writeFileSync(dest, sourceBody, 'utf8');
+            perChild.push({
+                childId: targetId,
+                path: child.path,
+                ok: true,
+                mirroredTo: dest
+            });
+            if (!child.peaksInstalled) {
+                warnings.push(`child "${targetId}" has no peaks-loop install — artifact mirrored but not picked up by a running peaks process`);
+            }
+        }
+        catch (err) {
+            perChild.push({
+                childId: targetId,
+                path: child.path,
+                ok: false,
+                error: err.message
+            });
+        }
+    }
+    const dispatch = {
+        rid: opts.rid,
+        sid: opts.sid,
+        root: opts.manifest.root,
+        targets: validTargets,
+        dispatchedAt: new Date().toISOString(),
+        artifact: opts.artifact
+    };
+    return { dispatch, perChild, warnings };
+}
+/** Default location of the polyrepo manifest on disk. */
+export function manifestPath(root) {
+    return join(root, '.peaks', 'polyrepo.json');
+}
+/** Read a persisted manifest from disk. Returns null when missing. */
+export function readManifest(root) {
+    const p = manifestPath(root);
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = readFileSync(p, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch { // TODO(g2): fail-closed JSON parse — null is the documented contract, caller checks via existsSync
+        return null;
+    }
+}
+/** Write a manifest atomically. */
+export function writeManifest(root, manifest) {
+    const p = manifestPath(root);
+    ensureDirFor(p);
+    writeFileSync(p, JSON.stringify(manifest, null, 2), 'utf8');
+}

package/dist/services/polyrepo/polyrepo-scanner.d.ts

@@ -0,0 +1,9 @@
+import type { PolyrepoManifest } from './polyrepo-types.js';
+export interface ScanOptions {
+    /** Explicit list of child directory names (relative to root). When
+     *  provided, the scanner uses these instead of auto-discovery.
+     *  Matches the `peaks polyrepo init --children <dir1,dir2>` shape. */
+    readonly explicitChildren?: readonly string[];
+}
+/** Walk the parent root at depth 1 and return discovered children. */
+export declare function scanPolyrepo(root: string, opts?: ScanOptions): PolyrepoManifest;

package/dist/services/polyrepo/polyrepo-scanner.js

@@ -0,0 +1,94 @@
+/**
+ * Polyrepo scanner — slice S2-b of RD-2.
+ *
+ * Walks a parent directory looking for child git repos. A "child
+ * git repo" is defined as: a directory that contains a `.git`
+ * entry (file or directory — worktrees + submodules both qualify),
+ * is NOT the root itself, and sits at depth 1 from the root.
+ *
+ * Depth is intentionally bounded to 1 (per the PRD §4.3 model):
+ *   parent/
+ *     .peaks/
+ *     frontend/.git
+ *     backend/.git
+ * We do not recurse into nested monorepos in this slice — that is
+ * a future-slice concern.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+function isGitRoot(dir) {
+    // A `.git` directory (normal repo) OR a `.git` file (worktree +
+    // submodule pointer) both count. statSync follows the pointer for
+    // a `.git` file, so the existence check is the same.
+    return existsSync(join(dir, '.git'));
+}
+function childHasPeaks(dir) {
+    return existsSync(join(dir, '.peaks'));
+}
+/** Sanitize a candidate child id: lowercase, dash-joined, no
+ *  leading dots or dashes. Used when the dir name itself is the id
+ *  (the common case). */
+function sanitizeId(name) {
+    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+}
+/** Walk the parent root at depth 1 and return discovered children. */
+export function scanPolyrepo(root, opts = {}) {
+    const absRoot = resolve(root);
+    if (!existsSync(absRoot)) {
+        throw new Error(`polyrepo root does not exist: ${absRoot}`);
+    }
+    const rootStat = statSync(absRoot);
+    if (!rootStat.isDirectory()) {
+        throw new Error(`polyrepo root is not a directory: ${absRoot}`);
+    }
+    const children = [];
+    if (opts.explicitChildren !== undefined && opts.explicitChildren.length > 0) {
+        // Explicit mode: only consider the named subdirs. This matches
+        // `peaks polyrepo init --children ./frontend,./backend`.
+        for (const name of opts.explicitChildren) {
+            const childPath = resolve(absRoot, name);
+            if (!existsSync(childPath)) {
+                throw new Error(`polyrepo child directory does not exist: ${childPath}`);
+            }
+            const s = statSync(childPath);
+            if (!s.isDirectory()) {
+                throw new Error(`polyrepo child path is not a directory: ${childPath}`);
+            }
+            children.push({
+                id: sanitizeId(basename(childPath)),
+                path: childPath,
+                gitRoot: isGitRoot(childPath),
+                peaksScope: childHasPeaks(childPath) ? 'root+child' : 'child-only',
+                peaksInstalled: childHasPeaks(childPath)
+            });
+        }
+    }
+    else {
+        // Auto-discovery mode: list immediate entries, filter to dirs with
+        // `.git`. This is intentionally narrow — see the file-level
+        // rationale at the top of this file.
+        const entries = readdirSync(absRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.'))
+                continue; // skip .git, .peaks, .vscode, etc.
+            const childPath = join(absRoot, entry.name);
+            if (!isGitRoot(childPath))
+                continue;
+            children.push({
+                id: sanitizeId(entry.name),
+                path: childPath,
+                gitRoot: true,
+                peaksScope: childHasPeaks(childPath) ? 'root+child' : 'child-only',
+                peaksInstalled: childHasPeaks(childPath)
+            });
+        }
+    }
+    return {
+        version: 1,
+        root: absRoot,
+        detectedAt: new Date().toISOString(),
+        children
+    };
+}

package/dist/services/polyrepo/polyrepo-service.d.ts

@@ -0,0 +1,34 @@
+import type { PolyrepoChild, PolyrepoManifest } from './polyrepo-types.js';
+export interface PolyrepoInitOptions {
+    readonly root: string;
+    readonly children?: readonly string[];
+}
+export interface PolyrepoInitResult {
+    readonly manifest: PolyrepoManifest;
+    readonly created: boolean;
+}
+export interface PolyrepoStatusResult {
+    readonly root: string;
+    readonly manifestExists: boolean;
+    readonly children: PolyrepoChild[];
+    readonly detectedAt: string | null;
+}
+export declare class PolyrepoService {
+    /** Run a scan and persist the manifest. Returns the manifest + a
+     *  `created` flag indicating whether a new manifest was written
+     *  (false = existing manifest was overwritten). */
+    init(opts: PolyrepoInitOptions): PolyrepoInitResult;
+    /** Read the persisted manifest + report children. */
+    status(root: string): PolyrepoStatusResult;
+    /** Dispatch an artifact to the named child targets. Wrapper
+     *  around dispatchArtifact that resolves the manifest from disk
+     *  first. Throws when no manifest exists (caller should run init
+     *  first). */
+    dispatch(root: string, params: {
+        sid: string;
+        rid: string;
+        targets: readonly string[];
+        role: 'prd' | 'rd' | 'qa';
+        artifactPath: string;
+    }): import("./polyrepo-dispatcher.js").DispatchResult;
+}

package/dist/services/polyrepo/polyrepo-service.js

@@ -0,0 +1,49 @@
+/**
+ * Polyrepo service — slice S2-b of RD-2.
+ *
+ * Thin orchestrator wrapping the scanner + dispatcher. CLI commands
+ * call into this service so they don't need to know about the
+ * individual helpers.
+ */
+import { dispatchArtifact, readManifest, writeManifest, manifestPath } from './polyrepo-dispatcher.js';
+import { scanPolyrepo } from './polyrepo-scanner.js';
+export class PolyrepoService {
+    /** Run a scan and persist the manifest. Returns the manifest + a
+     *  `created` flag indicating whether a new manifest was written
+     *  (false = existing manifest was overwritten). */
+    init(opts) {
+        const existing = readManifest(opts.root);
+        const manifest = opts.children === undefined
+            ? scanPolyrepo(opts.root)
+            : scanPolyrepo(opts.root, { explicitChildren: opts.children });
+        writeManifest(opts.root, manifest);
+        return { manifest, created: existing === null };
+    }
+    /** Read the persisted manifest + report children. */
+    status(root) {
+        const m = readManifest(root);
+        return {
+            root,
+            manifestExists: m !== null,
+            children: m?.children ?? [],
+            detectedAt: m?.detectedAt ?? null
+        };
+    }
+    /** Dispatch an artifact to the named child targets. Wrapper
+     *  around dispatchArtifact that resolves the manifest from disk
+     *  first. Throws when no manifest exists (caller should run init
+     *  first). */
+    dispatch(root, params) {
+        const manifest = readManifest(root);
+        if (manifest === null) {
+            throw new Error(`no polyrepo manifest at ${manifestPath(root)} — run \`peaks polyrepo init\` first`);
+        }
+        return dispatchArtifact({
+            manifest,
+            sid: params.sid,
+            rid: params.rid,
+            targets: params.targets,
+            artifact: { role: params.role, path: params.artifactPath }
+        });
+    }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Polyrepo types — slice S2-b of RD-2.
+ *
+ * Models a parent directory that hosts one or more child git repos,
+ * each of which may carry its own `.peaks/` state. The root `.peaks/`
+ * is the source of truth for cross-child orchestration; child
+ * `.peaks/` are subsets that mirror only the artifacts the child
+ * needs (PRD §4.3).
+ */
+export type PeaksScope = 'root+child' | 'child-only';
+/** A single child repo discovered under the parent root. */
+export interface PolyrepoChild {
+    /** Stable id derived from the basename (e.g. `frontend`, `backend`). */
+    readonly id: string;
+    /** Absolute path to the child directory. */
+    readonly path: string;
+    /** Whether `.git` exists at the child root (true git repo, not just a subdir). */
+    readonly gitRoot: boolean;
+    /** Whether the child carries its own `.peaks/` artifact subset. */
+    readonly peaksScope: PeaksScope;
+    /** Whether the child has peaks-loop installed (peaks binary on PATH
+     *  is NOT checked here — that's done at dispatch time). */
+    readonly peaksInstalled: boolean;
+}
+/** The polyrepo manifest, written to `.peaks/polyrepo.json` on init. */
+export interface PolyrepoManifest {
+    /** Schema version — increment on breaking changes. */
+    readonly version: 1;
+    /** Absolute path to the parent (root) directory. */
+    readonly root: string;
+    /** ISO-8601 timestamp of when this manifest was generated. */
+    readonly detectedAt: string;
+    /** Children discovered under the root. */
+    readonly children: PolyrepoChild[];
+}
+/** A dispatch record — written to `.peaks/_runtime/<sid>/sc/dispatch/<rid>.json`
+ *  AND mirrored to each target child's
+ *  `.peaks/_runtime/<sid>/sc/dispatch/<rid>.json`. The two-axis
+ *  convention from .peaks/standards/ is preserved: reviewable
+ *  artifacts live under `.peaks/_runtime/<sid>/<role>/`, never as
+ *  top-level siblings of `.peaks/_runtime/`. */
+export interface PolyrepoDispatch {
+    readonly rid: string;
+    readonly sid: string;
+    readonly root: string;
+    /** Child ids targeted by this dispatch. Empty array = root-only. */
+    readonly targets: string[];
+    /** ISO timestamp. */
+    readonly dispatchedAt: string;
+    /** Source-of-truth for the artifact body. */
+    readonly artifact: {
+        readonly role: 'prd' | 'rd' | 'qa';
+        readonly path: string;
+    };
+}

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

@@ -0,0 +1,64 @@
+/**
+ * peaks-prd handoff — frontmatter schema (v2.11.0, schemaVersion: 2).
+ *
+ * The handoff is the **immutable** single source of truth that all
+ * downstream consumers (peaks-rd main loop + 4 audit sub-agents +
+ * peaks-qa) read. It is written by peaks-prd AFTER user confirmation
+ * (per `skills/bee/peaks-prd/SKILL.md` Step 5.5) and replaces the legacy
+ * peaks-rd tech-doc handoff (v2.10.0 and earlier).
+ *
+ * Frontmatter invariant: `handoffHash` MUST equal the lowercase hex
+ * sha256 of the body content (UTF-8, no BOM, no frontmatter prefix).
+ * The hash is computed by `services/prd/handoff-service.ts` at write
+ * time and re-verified by every consumer before reading the body
+ * (D1 in `v2-11-rm-rd-techdoc-immutable-handoff`).
+ *
+ * Path convention: the file lands at
+ * `.peaks/_runtime/<sessionId>/prd/handoff.md` (gitignored session
+ * artifact; the binding to `<sessionId>` lives in
+ * `.peaks/_runtime/current-change`). NEVER write under
+ * `.peaks/_runtime/<change-id>/...` directly (slice 2.8.3 hard ban).
+ */
+/** Schema version 2 — bumped from v1 (which had no sha256 + no AC/goal
+ *  IDs in frontmatter). Every consumer MUST refuse a handoff whose
+ *  frontmatter is missing or carries `schemaVersion !== '2'`. */
+export type HandoffSchemaVersion = '2';
+/**
+ * Handoff frontmatter — the structured header block between the
+ * leading and trailing `---` fences. `readonly` enforces D1's
+ * immutability: once written, peaks-rd / peaks-qa / sub-agents MUST
+ * NOT mutate the on-disk copy.
+ */
+export interface HandoffFrontmatter {
+    readonly requestId: string;
+    readonly sessionId: string;
+    readonly schemaVersion: HandoffSchemaVersion;
+    /** Lowercase hex sha256 of the body content. Recomputed by
+     *  `verifyHandoff`; mismatch means tampering → refuse to read. */
+    readonly handoffHash: string;
+    /** ISO 8601 timestamp at write time. */
+    readonly writtenAt: string;
+    /** PRD goal IDs the handoff binds to (e.g. `['G1', 'G2']`). */
+    readonly goals: readonly string[];
+    /** PRD acceptance-criteria IDs (e.g. `['AC-1', 'AC-2']`). */
+    readonly acceptanceCriteria: readonly string[];
+    /** PRD preserved-behavior IDs (e.g. `['P1', 'P12']`). */
+    readonly preservedBehavior: readonly string[];
+    /** Absolute path to the handoff file on disk (for re-verify). */
+    readonly handoffPath: string;
+}
+/** Handoff — frontmatter + body. The body is the markdown source of
+ *  truth that sub-agents and downstream consumers parse. */
+export interface Handoff {
+    readonly frontmatter: HandoffFrontmatter;
+    readonly body: string;
+}
+/** Result of `verifyHandoff`. `ok: true` means the frontmatter's
+ *  `handoffHash` matches the recomputed sha256 of the body. */
+export interface HandoffProbe {
+    readonly ok: boolean;
+    readonly reason?: HandoffProbeReason;
+    readonly actualHash?: string;
+    readonly expectedHash?: string;
+}
+export type HandoffProbeReason = 'file-missing' | 'frontmatter-malformed' | 'hash-mismatch' | 'schema-version-mismatch';