peaks-loop 4.0.0-beta.8 → 4.0.1

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

package/dist/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/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).
+ */
+export {};

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

package/dist/services/prd/prd-blocks-checker.js

@@ -0,0 +1,130 @@
+/**
+ * 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).
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+const BLOCK_HEADINGS = [
+    { block: 1, name: '业务场景', pattern: /^#{1,4}\s*(?:\d+\.\s*)?业务场景[^\n]*$/m, requiredByDefault: true },
+    { block: 2, name: '边界 case', pattern: /^#{1,4}\s*(?:\d+\.\s*)?边界\s*case[^\n]*$/mi, requiredByDefault: true },
+    { block: 3, name: 'UI 装配意图', pattern: /^#{1,4}\s*(?:\d+\.\s*)?UI\s*装配[^\n]*$/mi, requiredByDefault: true },
+    { block: 4, name: '上游基线', pattern: /^#{1,4}\s*(?:\d+\.\s*)?上游基线[^\n]*$/m, requiredByDefault: false }
+];
+const MIN_CONTENT_LENGTH = 50;
+export function findPrdArtifact(projectRoot, requestId) {
+    // Look under .peaks/_runtime/<session>/prd/requests/<rid>.md
+    // Use the first hit (the most common layout is single-session).
+    const candidates = [
+        join(projectRoot, '.peaks', '_runtime', 'prd', 'requests', `${requestId}.md`),
+        join(projectRoot, '.peaks', '_runtime', 'change', requestId, 'prd', 'requests', `${requestId}.md`)
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    // Fall back to a glob-like search through .peaks/_runtime/*/prd/requests/.
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
+    if (!existsSync(runtimeRoot))
+        return null;
+    for (const sessionOrChange of readdirSync(runtimeRoot)) {
+        for (const sub of ['prd/requests', 'change']) {
+            const dir = join(runtimeRoot, sessionOrChange, sub, requestId);
+            if (existsSync(dir) && statSync(dir).isFile())
+                return dir;
+        }
+    }
+    return null;
+}
+export function readPrdArtifact(artifactPath) {
+    return readFileSync(artifactPath, 'utf8');
+}
+/**
+ * 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 function detectForkProject(projectRoot) {
+    const forkStatePath = resolve(projectRoot, '.peaks/fork-state.json');
+    if (existsSync(forkStatePath))
+        return true;
+    // Future: also check the upcoming `peaks fork status` baseline.
+    return false;
+}
+export function checkPrdBlocks(projectRoot, requestId) {
+    const artifactPath = findPrdArtifact(projectRoot, requestId);
+    if (artifactPath === null) {
+        return {
+            projectRoot,
+            artifactPath: '(not found)',
+            isFork: false,
+            findings: BLOCK_HEADINGS.map((h) => ({
+                block: h.block,
+                name: h.name,
+                required: h.requiredByDefault,
+                present: false,
+                content: null,
+                issues: h.requiredByDefault
+                    ? ['PRD artifact not found — write the prd body first.']
+                    : []
+            })),
+            ok: false
+        };
+    }
+    const body = readPrdArtifact(artifactPath);
+    const isFork = detectForkProject(projectRoot);
+    const findings = BLOCK_HEADINGS.map((h) => {
+        const required = h.requiredByDefault || (h.block === 4 && isFork);
+        const match = body.match(h.pattern);
+        if (match === null) {
+            return {
+                block: h.block,
+                name: h.name,
+                required,
+                present: false,
+                content: null,
+                issues: required
+                    ? [`Missing required block: ${h.name}. Add a heading like "## ${h.name}" with at least ${MIN_CONTENT_LENGTH} chars of content.`]
+                    : []
+            };
+        }
+        // Extract content: from the matched heading to the next same-or-higher-level heading.
+        const headingStart = match.index ?? 0;
+        const headingLineEnd = body.indexOf('\n', headingStart);
+        const start = headingLineEnd === -1 ? body.length : headingLineEnd + 1;
+        const headingLevel = (match[0]?.match(/^#+/) ?? [''])[0]?.length ?? 2;
+        const restBody = body.slice(start);
+        const nextHeading = new RegExp(`^#{1,${headingLevel}}\\s+`, 'm').exec(restBody);
+        const end = nextHeading ? nextHeading.index : restBody.length;
+        const content = restBody.slice(0, end).trim();
+        const issues = [];
+        if (content.length < MIN_CONTENT_LENGTH) {
+            issues.push(`Block "${h.name}" is too short (${content.length} chars; minimum ${MIN_CONTENT_LENGTH}). Add more concrete details.`);
+        }
+        // Block 1: must include 业务禁区 (no-go areas) — anti-pattern guard.
+        if (h.block === 1 && !/业务禁区|non-goal|non goal|不\s*做\s*什么/i.test(content)) {
+            issues.push('Block "业务场景" missing "业务禁区" sub-section (the 12 Gaps positioning memory requires this).');
+        }
+        return {
+            block: h.block,
+            name: h.name,
+            required,
+            present: true,
+            content,
+            issues
+        };
+    });
+    const ok = findings.every((f) => f.issues.length === 0);
+    return { projectRoot, artifactPath, isFork, findings, ok };
+}

package/dist/services/prd/project-scan-bootstrap-service.d.ts

@@ -0,0 +1,52 @@
+/**
+ * project-scan bootstrap service — slice 2026-07-15-project-scan-bootstrap
+ * (PRD G1 + G2 + G4b / AC1-AC10 / R1-R4).
+ *
+ * Owns the "first time a project enters Peaks-Loop" bootstrap flow:
+ *   - 0-1 detection (no package.json OR no source files)
+ *   - writes `.peaks/project-scan/project-scan.md` with empty placeholders
+ *     for 0-1 projects, or with archetype + libraryVersions for existing
+ *     projects (calling `scanArchetype` + `scanLibraries` directly, not
+ *     forking a CLI process)
+ *   - boots the 4 audit/business templates (bundled in repo at
+ *     `src/services/workspace/templates/project-scan/`) into
+ *     `.peaks/project-scan/` (AC9)
+ *   - idempotent: skips re-writes when the existing file is at
+ *     schemaVersion:1 (AC3); --force / --force-templates override
+ *
+ * Called by:
+ *   - `peaks project context` (via `generateProjectContext`)
+ *   - `peaks workspace init` (main path)
+ *
+ * The "5 templates" count: 4 bundled audit/business files + the
+ * dynamically-generated `project-scan.md` produced by this service.
+ * `templatesBooted` reflects the count of files actually written;
+ * `templatesSkipped` reflects files already present (sediment-protected).
+ */
+export type BootstrapProjectScanOptions = {
+    readonly projectRoot: string;
+    /** Override the existing-file skip and rewrite project-scan.md. */
+    readonly force?: boolean;
+    /** Override the bundled-template skip and overwrite audit/business files. */
+    readonly forceTemplates?: boolean;
+};
+export type BootstrapProjectScanEnvelope = {
+    /** True iff project-scan.md was written by this call. */
+    readonly created: boolean;
+    /** True iff project-scan.md existed and was skipped (idempotent). */
+    readonly skipped: boolean;
+    /** Count of files written to .peaks/project-scan/ (1 project-scan.md + N templates). */
+    readonly templatesBooted: number;
+    /** Count of files already present and skipped (sediment-preserved). */
+    readonly templatesSkipped: number;
+    /** Absolute path to the project-scan.md file (whether written or pre-existing). */
+    readonly projectScanPath: string;
+    /** Resolved archetype (when existing-project path was taken). */
+    readonly archetype?: string;
+    /** Total wall-time of the bootstrap call. */
+    readonly durationMs: number;
+};
+/**
+ * Public entry point. See the file header for the full contract.
+ */
+export declare function bootstrapProjectScan(options: BootstrapProjectScanOptions): Promise<BootstrapProjectScanEnvelope>;