peaks-loop 3.0.0

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

@@ -0,0 +1,214 @@
+/**
+ * Performance baseline scaffolding for the RD stage.
+ *
+ * peaks-solo'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-cli.
+ *
+ * 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-cli'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/src/services/prd/handoff-auto-regen.d.ts

@@ -0,0 +1,22 @@
+import { type RequestArtifactRole } from '../artifacts/request-artifact-service.js';
+export type HandoffAutoRegenResult = {
+    status: 'created';
+    path: string;
+    sha256: string;
+} | {
+    status: 'skipped-exists';
+    path: string;
+} | {
+    status: 'failed';
+    reason: string;
+};
+/**
+ * Auto-regen the prd/handoff.md under `.peaks/_runtime/<sid>/prd/`.
+ * Returns the outcome; never throws.
+ */
+export declare function autoRegenPrdHandoff(opts: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly requestId: string;
+    readonly role: RequestArtifactRole;
+}): Promise<HandoffAutoRegenResult>;

package/dist/src/services/prd/handoff-auto-regen.js

@@ -0,0 +1,73 @@
+/**
+ * v2.13.2 AC-4 — prd/handoff.md auto-regen on prd:handed-off.
+ *
+ * When `peaks request transition --role prd --state handed-off` succeeds
+ * and `prd/handoff.md` is missing, this helper writes a sha256-locked
+ * handoff (schemaVersion: 2) using the request artifact body as the
+ * handoff body. If the handoff already exists, it's NOT overwritten —
+ * the existing handoff is canonical (it may carry a richer body that
+ * peaks-prd produced in an earlier session).
+ *
+ * Karpathy §3 (Surgical Changes): this file only owns the auto-regen
+ * path. The other 11 transitions are untouched.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+import { sha256OfBody } from './handoff-service.js';
+/**
+ * Auto-regen the prd/handoff.md under `.peaks/_runtime/<sid>/prd/`.
+ * Returns the outcome; never throws.
+ */
+export async function autoRegenPrdHandoff(opts) {
+    if (opts.role !== 'prd') {
+        return { status: 'failed', reason: 'role must be prd' };
+    }
+    const handoffPath = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md');
+    if (existsSync(handoffPath)) {
+        return { status: 'skipped-exists', path: handoffPath };
+    }
+    const artifact = await showRequestArtifact({
+        projectRoot: opts.projectRoot,
+        role: 'prd',
+        requestId: opts.requestId,
+        sessionId: opts.sessionId
+    });
+    if (artifact === null || typeof artifact.content !== 'string') {
+        return { status: 'failed', reason: 'request artifact body not found' };
+    }
+    const body = artifact.content;
+    const sha256 = sha256OfBody(body);
+    // v2.13.3 AC-4 — align with `AUDIT_REQUIRES_HANDOFF` prereq which
+    // pins `mustContain: ['schemaVersion: 2', 'sha256:']`. The previous
+    // field name `handoffHash` made peaks-cli write a handoff that the
+    // own prereq resolver would reject with "missing section(s): sha256:".
+    // Primary field is now `sha256`; `handoffHash` is kept as a literal
+    // alias for back-compat with any consumer (UI / external scripts)
+    // that still reads the old key.
+    const frontmatter = [
+        '---',
+        `requestId: ${opts.requestId}`,
+        `sessionId: ${opts.sessionId}`,
+        `sessionId: ${opts.sessionId}`,
+        'schemaVersion: 2',
+        `sha256: ${sha256}`,
+        `handoffHash: ${sha256}`,
+        `writtenAt: ${new Date().toISOString()}`,
+        'goals: []',
+        'acceptanceCriteria: []',
+        'preservedBehavior: []',
+        `handoffPath: ${handoffPath.replace(opts.projectRoot, '').replace(/\\/g, '/').replace(/^\//, '')}`,
+        '---',
+        ''
+    ].join('\n');
+    const content = `${frontmatter}${body}`;
+    mkdirSync(dirname(handoffPath), { recursive: true });
+    writeFileSync(handoffPath, content, 'utf8');
+    const recomputed = createHash('sha256').update(body, 'utf8').digest('hex');
+    if (recomputed !== sha256) {
+        return { status: 'failed', reason: 'sha256 mismatch after write' };
+    }
+    return { status: 'created', path: handoffPath, sha256 };
+}

package/dist/src/services/prd/handoff-service.d.ts

@@ -0,0 +1,54 @@
+/**
+ * peaks-prd handoff service — v2.11.0 (D1 in
+ * `v2-11-rm-rd-techdoc-immutable-handoff`).
+ *
+ * Owns the immutable handoff at
+ * `.peaks/_runtime/<sessionId>/prd/handoff.md`:
+ *
+ *   - `initHandoff` — pure; computes sha256 of the body and returns
+ *     a Handoff whose frontmatter `handoffHash` matches.
+ *   - `writeHandoff` — writes the file under `.peaks/_runtime/<sid>/prd/`,
+ *     creating the dir if missing.
+ *   - `readHandoff` — reads + parses; throws on malformed input.
+ *   - `verifyHandoff` — re-reads + recomputes hash; returns a
+ *     `HandoffProbe` (never throws on hash mismatch — that's a
+ *     verification outcome, not a fatal error).
+ *   - `showHandoff` — returns the raw markdown content (frontmatter
+ *     + body verbatim) for human display via `peaks prd handoff show`.
+ *
+ * Hash contract (D1): `handoffHash` is the lowercase hex sha256 of
+ * the body content as UTF-8 bytes. The body MUST be the literal
+ * markdown source — no normalization, no trailing-newline padding.
+ */
+import type { Handoff, HandoffProbe } from './handoff-types.js';
+/** Compute the lowercase hex sha256 of a UTF-8 string. */
+export declare function sha256OfBody(body: string): string;
+/** Pure: produce a Handoff with the frontmatter populated. Hash is
+ *  computed here; callers MUST NOT pre-populate `handoffHash`. */
+export declare function initHandoff(opts: {
+    requestId: string;
+    sessionId: string;
+    body: string;
+    writtenAt: string;
+    goals: readonly string[];
+    acceptanceCriteria: readonly string[];
+    preservedBehavior: readonly string[];
+    /** Override path; defaults to `.peaks/_runtime/<sid>/prd/handoff.md`. */
+    handoffPath?: string;
+}): Handoff;
+/** Write a Handoff to disk. `projectRoot` is the absolute project
+ *  root (so the `.peaks/_runtime/...` path is resolved absolutely).
+ *  Creates intermediate dirs. */
+export declare function writeHandoff(handoff: Handoff, projectRoot: string): Promise<{
+    path: string;
+    hash: string;
+}>;
+/** Read + parse a handoff from disk. Throws on missing file or
+ *  malformed frontmatter. */
+export declare function readHandoff(filePath: string): Promise<Handoff>;
+/** Verify a handoff by re-reading and re-hashing. Returns a probe
+ *  (never throws on hash mismatch — that's the outcome). */
+export declare function verifyHandoff(filePath: string): Promise<HandoffProbe>;
+/** Return the raw markdown content of a handoff file (frontmatter +
+ *  body verbatim). For human display. */
+export declare function showHandoff(filePath: string): Promise<string>;

package/dist/src/services/prd/handoff-service.js

@@ -0,0 +1,142 @@
+/**
+ * peaks-prd handoff service — v2.11.0 (D1 in
+ * `v2-11-rm-rd-techdoc-immutable-handoff`).
+ *
+ * Owns the immutable handoff at
+ * `.peaks/_runtime/<sessionId>/prd/handoff.md`:
+ *
+ *   - `initHandoff` — pure; computes sha256 of the body and returns
+ *     a Handoff whose frontmatter `handoffHash` matches.
+ *   - `writeHandoff` — writes the file under `.peaks/_runtime/<sid>/prd/`,
+ *     creating the dir if missing.
+ *   - `readHandoff` — reads + parses; throws on malformed input.
+ *   - `verifyHandoff` — re-reads + recomputes hash; returns a
+ *     `HandoffProbe` (never throws on hash mismatch — that's a
+ *     verification outcome, not a fatal error).
+ *   - `showHandoff` — returns the raw markdown content (frontmatter
+ *     + body verbatim) for human display via `peaks prd handoff show`.
+ *
+ * Hash contract (D1): `handoffHash` is the lowercase hex sha256 of
+ * the body content as UTF-8 bytes. The body MUST be the literal
+ * markdown source — no normalization, no trailing-newline padding.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+/** Required schema version for new handoffs. */
+const HANDOFF_SCHEMA_VERSION = '2';
+/** Compute the lowercase hex sha256 of a UTF-8 string. */
+export function sha256OfBody(body) {
+    return createHash('sha256').update(body, 'utf8').digest('hex');
+}
+/** Pure: produce a Handoff with the frontmatter populated. Hash is
+ *  computed here; callers MUST NOT pre-populate `handoffHash`. */
+export function initHandoff(opts) {
+    const handoffPath = opts.handoffPath ??
+        join('.peaks', '_runtime', opts.sessionId, 'prd', 'handoff.md');
+    const handoffHash = sha256OfBody(opts.body);
+    const frontmatter = {
+        requestId: opts.requestId,
+        sessionId: opts.sessionId,
+        schemaVersion: HANDOFF_SCHEMA_VERSION,
+        handoffHash,
+        writtenAt: opts.writtenAt,
+        goals: [...opts.goals],
+        acceptanceCriteria: [...opts.acceptanceCriteria],
+        preservedBehavior: [...opts.preservedBehavior],
+        handoffPath,
+    };
+    return { frontmatter, body: opts.body };
+}
+/** Write a Handoff to disk. `projectRoot` is the absolute project
+ *  root (so the `.peaks/_runtime/...` path is resolved absolutely).
+ *  Creates intermediate dirs. */
+export async function writeHandoff(handoff, projectRoot) {
+    const absolutePath = join(projectRoot, handoff.frontmatter.handoffPath);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    const content = serializeHandoff(handoff);
+    await writeFile(absolutePath, content, 'utf8');
+    return { path: absolutePath, hash: handoff.frontmatter.handoffHash };
+}
+/** Read + parse a handoff from disk. Throws on missing file or
+ *  malformed frontmatter. */
+export async function readHandoff(filePath) {
+    const content = await readFile(filePath, 'utf8');
+    return parseHandoffContent(content);
+}
+/** Verify a handoff by re-reading and re-hashing. Returns a probe
+ *  (never throws on hash mismatch — that's the outcome). */
+export async function verifyHandoff(filePath) {
+    let handoff;
+    try {
+        handoff = await readHandoff(filePath);
+    }
+    catch {
+        return { ok: false, reason: 'file-missing' };
+    }
+    if (handoff.frontmatter.schemaVersion !== HANDOFF_SCHEMA_VERSION) {
+        return {
+            ok: false,
+            reason: 'schema-version-mismatch',
+            actualHash: handoff.frontmatter.handoffHash,
+        };
+    }
+    const actualHash = sha256OfBody(handoff.body);
+    if (actualHash !== handoff.frontmatter.handoffHash) {
+        return {
+            ok: false,
+            reason: 'hash-mismatch',
+            actualHash,
+            expectedHash: handoff.frontmatter.handoffHash,
+        };
+    }
+    return { ok: true, actualHash, expectedHash: actualHash };
+}
+/** Return the raw markdown content of a handoff file (frontmatter +
+ *  body verbatim). For human display. */
+export async function showHandoff(filePath) {
+    return readFile(filePath, 'utf8');
+}
+// ── internal helpers ─────────────────────────────────────────────────
+/** Split raw content into `{ frontmatter, body }`. Throws if the
+ *  frontmatter block is missing or malformed. */
+function parseHandoffContent(content) {
+    const match = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/.exec(content);
+    if (!match) {
+        throw new Error('handoff: frontmatter block missing or malformed');
+    }
+    const yamlBlock = match[1];
+    const body = match[2] ?? '';
+    let parsed;
+    try {
+        parsed = parseYaml(yamlBlock);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`handoff: frontmatter YAML parse failed: ${message}`);
+    }
+    if (!isHandoffFrontmatter(parsed)) {
+        throw new Error('handoff: frontmatter shape validation failed');
+    }
+    return { frontmatter: parsed, body };
+}
+function serializeHandoff(handoff) {
+    const yamlStr = stringifyYaml(handoff.frontmatter).trimEnd();
+    return `---\n${yamlStr}\n---\n${handoff.body}`;
+}
+function isHandoffFrontmatter(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (typeof v.requestId === 'string' &&
+        typeof v.sessionId === 'string' &&
+        typeof v.sessionId === 'string' &&
+        typeof v.schemaVersion === 'string' &&
+        typeof v.handoffHash === 'string' &&
+        typeof v.writtenAt === 'string' &&
+        Array.isArray(v.goals) &&
+        Array.isArray(v.acceptanceCriteria) &&
+        Array.isArray(v.preservedBehavior) &&
+        typeof v.handoffPath === 'string');
+}

package/dist/src/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/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';

package/dist/src/services/prd/handoff-types.js

@@ -0,0 +1,22 @@
+/**
+ * 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/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).
+ */
+export {};

package/dist/src/services/prd/prd-blocks-checker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * v2.15.0 follow-up — G3: prd 4 必填块 checker.
+ *
+ * Validates that a PRD artifact body contains the 4 mandatory sections
+ * required by the 12 Gaps positioning memory:
+ *
+ *   1. 业务场景(目标用户 / 业务流程 / 性能 / 现有系统 / 业务禁区)
+ *   2. 边界 case 清单
+ *   3. UI 装配意图(页面模式 / 关键交互 / 信息密度)
+ *   4. 上游基线(仅 fork 场景必填)
+ *
+ * Returns a structured report; the CLI surfaces it as a lint
+ * complement to `peaks request lint` (which checks placeholders).
+ * `peaks prd check-blocks` ensures the design quality is locked at
+ * the prd stage (the principle: 质量杠杆前置到 prd).
+ */
+export interface PrdBlockFinding {
+    /** Block identifier (1-4). */
+    readonly block: 1 | 2 | 3 | 4;
+    /** Block name (Chinese). */
+    readonly name: string;
+    /** Whether the block is required (block 4 only required for fork projects). */
+    readonly required: boolean;
+    /** Whether the block was found in the document. */
+    readonly present: boolean;
+    /** The content under the heading, or null when not found. */
+    readonly content: string | null;
+    /** Issues detected (empty array when the block is OK). */
+    readonly issues: readonly string[];
+}
+export interface PrdBlocksReport {
+    /** Project root. */
+    readonly projectRoot: string;
+    /** Path to the artifact. */
+    readonly artifactPath: string;
+    /** Whether this is a fork project (controls block 4 required flag). */
+    readonly isFork: boolean;
+    /** Findings for each of the 4 blocks. */
+    readonly findings: readonly PrdBlockFinding[];
+    /** Overall pass/fail: all required blocks present + no issues. */
+    readonly ok: boolean;
+}
+export declare function findPrdArtifact(projectRoot: string, requestId: string): string | null;
+export declare function readPrdArtifact(artifactPath: string): string;
+/**
+ * Detect whether the project is a fork by looking for `.peaks/fork-state.json`
+ * (the G11 CLI's state file) or `.peaks/release-state.json` history entries
+ * that reference an upstream. Lightweight heuristic.
+ */
+export declare function detectForkProject(projectRoot: string): boolean;
+export declare function checkPrdBlocks(projectRoot: string, requestId: string): PrdBlocksReport;