peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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>;

package/dist/services/prd/project-scan-bootstrap-service.js

@@ -0,0 +1,445 @@
+/**
+ * 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).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { scanArchetype } from '../scan/archetype-service.js';
+import { scanLibraries } from '../scan/libraries-service.js';
+import { TEMPLATE_FILES, readTemplateStrict } from '../workspace/templates/project-scan/index.js';
+const PROJECT_SCAN_DIR = join('.peaks', 'project-scan');
+const PROJECT_SCAN_FILENAME = 'project-scan.md';
+const PROJECT_SCAN_PATH = join(PROJECT_SCAN_DIR, PROJECT_SCAN_FILENAME);
+const SOURCE_FILE_EXTENSIONS = /\.(tsx?|jsx?|vue|svelte)$/;
+/**
+ * Monorepo layout sentinels. A project is monorepo-shaped if it carries
+ * one of these config files at its root, even when `src/` is absent.
+ * Slice 2026-07-15 hot-fix (ice-cola real-world test, 2026-07-15):
+ *   `pnpm-workspace.yaml` is the most common signal; `turbo.json`
+ *   (Turborepo) and `nx.json` (Nx) are the others the ecosystem
+ *   reaches for. lerna.json is legacy-only and intentionally omitted
+ *   here — those projects should be detected via `package.json`
+ *   workspaces[] field below.
+ */
+const MONOREPO_ROOT_CONFIGS = [
+    'pnpm-workspace.yaml',
+    'turbo.json',
+    'nx.json'
+];
+/** True iff the project root declares pnpm / yarn / npm workspaces. */
+function projectHasWorkspacesInPackageJson(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return false;
+    let raw;
+    try {
+        raw = readFileSync(pkgPath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (Array.isArray(pkg.workspaces))
+        return pkg.workspaces.length > 0;
+    if (pkg.workspaces && typeof pkg.workspaces === 'object') {
+        // Yarn classic shape: { packages: ['packages/*'] }
+        const obj = pkg.workspaces;
+        if (Array.isArray(obj.packages))
+            return obj.packages.length > 0;
+    }
+    return false;
+}
+/** True iff the project root is a monorepo by any of the 3 root-config signals. */
+function projectIsMonorepo(projectRoot) {
+    for (const cfg of MONOREPO_ROOT_CONFIGS) {
+        if (existsSync(join(projectRoot, cfg)))
+            return true;
+    }
+    return projectHasWorkspacesInPackageJson(projectRoot);
+}
+/**
+ * Recursive file-existence check for a single root dir, capped at MAX_DEPTH.
+ * Returns true the first time it encounters a file matching
+ * SOURCE_FILE_EXTENSIONS. Skips dot-dirs and node_modules.
+ */
+function directoryContainsSourceFiles(rootDir) {
+    if (!existsSync(rootDir))
+        return false;
+    const queue = [rootDir];
+    const MAX_DEPTH = 6;
+    let depth = 0;
+    while (queue.length > 0 && depth <= MAX_DEPTH) {
+        const current = queue.shift();
+        if (current === undefined)
+            break;
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || entry.name === 'node_modules')
+                continue;
+            const full = join(current, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(full);
+            }
+            else if (entry.isFile() && SOURCE_FILE_EXTENSIONS.test(entry.name)) {
+                return true;
+            }
+        }
+        depth += 1;
+    }
+    return false;
+}
+/**
+ * Heuristic for "this directory holds source code".
+ *
+ * 1. `src/` at the root (single-package layout).
+ * 2. Any of the monorepo source roots: `packages/`, `apps/`, `libs/`,
+ *    `services/`, `workspaces/` — each is checked recursively for at
+ *    least one matching source file. Slice 2026-07-15 hot-fix (ice-cola
+ *    test, 2026-07-15): the original implementation only looked at
+ *    `src/` and mis-classified monorepos as 0-1 (pnpm-workspace layout
+ *    puts source under `packages/<pkg>/src/`, not `<root>/src/`).
+ *
+ * Returns true on the first hit. False when none of the candidate
+ * roots contain source files (genuine 0-1).
+ */
+function projectHasSourceFiles(projectRoot) {
+    if (directoryContainsSourceFiles(join(projectRoot, 'src')))
+        return true;
+    const monorepoSourceRoots = ['packages', 'apps', 'libs', 'services', 'workspaces'];
+    for (const candidate of monorepoSourceRoots) {
+        const dir = join(projectRoot, candidate);
+        if (!existsSync(dir))
+            continue;
+        if (directoryContainsSourceFiles(dir))
+            return true;
+    }
+    return false;
+}
+/** Detect 0-1: no package.json OR no source files.
+ *  Slice 2026-07-15 hot-fix (ice-cola test, 2026-07-15): monorepos with
+ *  source under packages/<pkg>/ are no longer mis-classified as 0-1. */
+function isZeroToOneProject(projectRoot) {
+    const hasPackageJson = existsSync(join(projectRoot, 'package.json'));
+    if (!hasPackageJson)
+        return true;
+    if (projectIsMonorepo(projectRoot)) {
+        // Monorepo: a package.json at root + workspace config is enough
+        // signal that this is NOT a 0-1 project — even if we couldn't find
+        // source files at the expected roots (workspace packages may be
+        // missing locally, behind a sparse-checkout, etc.). Trust the
+        // workspace layout and let `scanArchetype` decide the real shape.
+        return false;
+    }
+    return !projectHasSourceFiles(projectRoot);
+}
+/**
+ * Parse the frontmatter `schemaVersion` from an existing project-scan.md.
+ * Returns `null` when the file is absent, malformed, or has no version.
+ * The reader in `services/prd/project-scan-reader.ts` is the canonical
+ * parser; we re-implement the minimum here to avoid coupling the
+ * bootstrap path to that reader's strict shape validation.
+ */
+function readExistingSchemaVersion(absPath) {
+    if (!existsSync(absPath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(absPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const match = /^---\n([\s\S]*?)\n---/.exec(raw);
+    if (!match)
+        return null;
+    const frontmatter = match[1] ?? '';
+    const versionMatch = /^\s*schemaVersion:\s*(\d+)/m.exec(frontmatter);
+    if (!versionMatch)
+        return null;
+    const parsed = Number(versionMatch[1]);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+/** Build the project-scan.md content for a 0-1 project (empty placeholders). */
+function buildZeroToOneProjectScan() {
+    const now = new Date().toISOString();
+    return [
+        '---',
+        'schemaVersion: 1',
+        `capturedAt: ${now}`,
+        'archetype: unknown',
+        'confidence: low',
+        'techStack: {}',
+        'libraryVersions: {}',
+        'architecture: ""',
+        'karpathySelfCheck: {}',
+        '---',
+        '',
+        '# Project Scan (0-1 bootstrap)',
+        '',
+        `> Auto-generated by \`peaks workspace init\` / \`peaks project context\` on ${now}. ` +
+            'Refresh with `peaks project context --project <repo>` once the project has a `package.json` + source files.',
+        '',
+        '## Archetype',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        '| Type | `unknown` |',
+        '| Confidence | `low` |',
+        '| Reason | 0-1 project, no package.json or source files |',
+        '| Frontend-only | `false` |',
+        '',
+        '## Project mode',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        '| Mode | unknown |',
+        '| Reason | 0-1 bootstrap — refresh after the first source file lands |',
+        '',
+        '## Tech stack',
+        '',
+        '| Concern | Value |',
+        '|---|---|',
+        '| Language | (empty) |',
+        '| Package manager | (empty) |',
+        '| Node runtime | (empty) |',
+        '| Build | (empty) |',
+        '| Tests | (empty) |',
+        '',
+        '## Library versions',
+        '',
+        '| Package | Pinned range | Major | Scope | Ecosystem |',
+        '|---|---|---|---|---|',
+        '| (empty) | — | — | — | — |',
+        '',
+        '## Architecture',
+        '',
+        '_No architecture recorded yet — refresh with `peaks project context --project <repo>` once the project has source files._',
+        '',
+        '## Karpathy self-check',
+        '',
+        '| Guideline | Where enforced |',
+        '|---|---|',
+        '| §1 Think Before Coding | (empty) |',
+        '| §2 Simplicity First | (empty) |',
+        '| §3 Surgical Changes | (empty) |',
+        '| §4 Goal-Driven Execution | (empty) |',
+        '',
+        '## Refresh procedure',
+        '',
+        '1. Add a `package.json` (with `pnpm init` or equivalent).',
+        '2. Add at least one TypeScript/JavaScript/Vue/Svelte source file under `src/`.',
+        '3. Re-run `peaks project context --project <repo>` — the empty placeholders are replaced with real archetype + libraryVersions.',
+        ''
+    ].join('\n');
+}
+/** Render a LibraryReport as a markdown table body (header row included). */
+function renderLibraryTable(libraryReport) {
+    const header = '| Package | Pinned range | Major | Scope | Ecosystem |';
+    const sep = '|---|---|---|---|---|';
+    if (libraryReport.libraries.length === 0) {
+        return [header, sep, '| (empty) | — | — | — | — |'].join('\n');
+    }
+    const rows = libraryReport.libraries.map((entry) => {
+        const major = entry.major === null ? '—' : String(entry.major);
+        return `| \`${entry.name}\` | \`${entry.version}\` | ${major} | ${entry.scope} | ${entry.ecosystem} |`;
+    });
+    return [header, sep, ...rows].join('\n');
+}
+/** Build the project-scan.md content for an existing project. */
+async function buildExistingProjectScan(args) {
+    const { archetypeReport, libraryReport } = args;
+    const now = new Date().toISOString();
+    const runtime = (process.versions.node ?? 'unknown').trim();
+    // Library versions snapshot: a flat {name: version} map. Mirrors the
+    // shape consumed by `services/prd/project-scan-types.ts`
+    // `ProjectScanLibraryVersions`.
+    const libraryVersionsMap = {};
+    for (const entry of libraryReport.libraries) {
+        libraryVersionsMap[entry.name] = entry.version;
+    }
+    const lines = [
+        '---',
+        'schemaVersion: 1',
+        `capturedAt: ${now}`,
+        `archetype: ${archetypeReport.archetype}`,
+        `confidence: ${archetypeReport.confidence}`,
+        'techStack: {}',
+        `libraryVersions: ${JSON.stringify(libraryVersionsMap, null, 2)
+            .split('\n')
+            .map((line, idx) => (idx === 0 ? line : '  ' + line))
+            .join('\n')}`,
+        'architecture: ""',
+        'karpathySelfCheck: {}',
+        '---',
+        '',
+        `# Project Scan (refreshed ${now})`,
+        '',
+        '> Auto-generated by `peaks workspace init` / `peaks project context`.',
+        '',
+        '## Archetype',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| Type | \`${archetypeReport.archetype}\` |`,
+        `| Confidence | \`${archetypeReport.confidence}\` |`,
+        `| Frontend-only | \`${String(archetypeReport.frontendOnly)}\` |`,
+        `| Reason | ${archetypeReport.frontendOnlyReason} |`,
+        '',
+        '## Project mode',
+        '',
+        '| Field | Value |',
+        '|---|---|',
+        `| Mode | ${archetypeReport.frontendOnly ? 'frontend-only' : 'full-stack-or-unknown'} |`,
+        `| Reason | ${archetypeReport.frontendOnlyReason} |`,
+        '',
+        '## Tech stack',
+        '',
+        '| Concern | Value |',
+        '|---|---|',
+        '| Language | TypeScript (best-effort — re-confirm via package.json devDeps) |',
+        '| Package manager | pnpm (best-effort) |',
+        `| Node runtime | node ${runtime} |`,
+        '| Build | tsc / package.json `build` script |',
+        '| Tests | vitest (best-effort) |',
+        '',
+        '## Library versions',
+        '',
+        renderLibraryTable(libraryReport),
+        '',
+        '## Architecture',
+        '',
+        `_Auto-generated from \`scanArchetype\` signals — see archetypeReport.backendFrameworks / .backendDirsPresent / .swaggerPaths in \`.peaks/_runtime/<sid>/rd/project-scan.md\` (legacy) or \`.peaks/project-scan/project-scan.md\` (this file) for the raw facts._`,
+        '',
+        '## Karpathy self-check',
+        '',
+        '| Guideline | Where enforced |',
+        '|---|---|',
+        '| §1 Think Before Coding | (refresh with LLM review) |',
+        '| §2 Simplicity First | (refresh with LLM review) |',
+        '| §3 Surgical Changes | (refresh with LLM review) |',
+        '| §4 Goal-Driven Execution | (refresh with LLM review) |',
+        '',
+        '## Refresh procedure',
+        '',
+        '1. Re-run `peaks scan archetype --project <repo> --json` and `peaks scan libraries --project <repo> --json` after any dependency / archetype change.',
+        '2. Re-run `peaks project context --project <repo>` to refresh this file.',
+        '3. Commit the regenerated project-scan.md alongside the dependency bump.',
+        ''
+    ];
+    return lines.join('\n');
+}
+/**
+ * Ensure `.peaks/project-scan/` exists. Idempotent.
+ */
+function ensureProjectScanDir(projectRoot) {
+    const dir = join(projectRoot, PROJECT_SCAN_DIR);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Copy one bundled template into the project. Returns `true` when
+ * the file was written, `false` when it was skipped (already present
+ * without `--force-templates`).
+ */
+async function bootTemplate(args) {
+    const destPath = join(args.projectRoot, PROJECT_SCAN_DIR, args.name);
+    if (existsSync(destPath) && !args.force) {
+        return false;
+    }
+    const content = await readTemplateStrict(args.name);
+    writeFileSync(destPath, content, 'utf8');
+    return true;
+}
+/**
+ * Public entry point. See the file header for the full contract.
+ */
+export async function bootstrapProjectScan(options) {
+    const startedAt = Date.now();
+    ensureProjectScanDir(options.projectRoot);
+    const projectScanAbsPath = join(options.projectRoot, PROJECT_SCAN_PATH);
+    const existingVersion = readExistingSchemaVersion(projectScanAbsPath);
+    // Decide whether project-scan.md is created or skipped. Idempotency:
+    // when an existing file already declares schemaVersion:1 we honor
+    // sediment unless `force=true`.
+    let created = false;
+    let skipped = false;
+    let archetype;
+    if (existingVersion === 1 && options.force !== true) {
+        skipped = true;
+    }
+    else {
+        const zeroToOne = isZeroToOneProject(options.projectRoot);
+        if (zeroToOne) {
+            archetype = 'unknown';
+            writeFileSync(projectScanAbsPath, buildZeroToOneProjectScan(), 'utf8');
+        }
+        else {
+            const archetypeReport = await scanArchetype({ projectRoot: options.projectRoot });
+            const libraryReport = await scanLibraries({ projectRoot: options.projectRoot });
+            archetype = archetypeReport.archetype;
+            const content = await buildExistingProjectScan({ archetypeReport, libraryReport });
+            writeFileSync(projectScanAbsPath, content, 'utf8');
+        }
+        created = true;
+    }
+    // Boot the 4 bundled templates (AC9). The project-scan.md we just
+    // wrote (or preserved) is also counted as 1 template.
+    let templatesBooted = created ? 1 : 0;
+    let templatesSkipped = created ? 0 : 1;
+    for (const name of TEMPLATE_FILES) {
+        const wrote = await bootTemplate({
+            projectRoot: options.projectRoot,
+            name,
+            force: options.forceTemplates === true
+        });
+        if (wrote) {
+            templatesBooted += 1;
+        }
+        else {
+            templatesSkipped += 1;
+        }
+    }
+    return {
+        created,
+        skipped,
+        templatesBooted,
+        templatesSkipped,
+        projectScanPath: projectScanAbsPath,
+        ...(archetype !== undefined ? { archetype } : {}),
+        durationMs: Date.now() - startedAt
+    };
+}

package/dist/services/prd/project-scan-reader.d.ts

@@ -0,0 +1,24 @@
+/**
+ * peaks-prd project-scan reader — v2.11.0 (D3 in
+ * `v2-11-rm-rd-techdoc-immutable-handoff`).
+ *
+ * Reads the git-tracked project-level artifacts at
+ * `.peaks/project-scan/{project-scan.md, business-knowledge.md}`.
+ *
+ * Both readers swallow `ENOENT` (return `null`) — peaks-prd's gate
+ * uses the `null` return to decide whether to bootstrap. Other IO
+ * errors propagate (no silent failures).
+ */
+import type { BusinessKnowledge, ProjectScan } from './project-scan-types.js';
+/** Read `.peaks/project-scan/project-scan.md`. Returns `null` when the
+ *  file or its parent dir is absent (fresh project). Throws on other
+ *  IO failures or malformed YAML. */
+export declare function readProjectScan(projectRoot: string): Promise<ProjectScan | null>;
+/** Read `.peaks/project-scan/business-knowledge.md`. Returns `null`
+ *  when absent. Throws on other IO failures or malformed YAML. */
+export declare function readBusinessKnowledge(projectRoot: string): Promise<BusinessKnowledge | null>;
+/** Read the raw markdown content of a project-scan file. Returns
+ *  `null` when absent. Used by bootstrap flows (peaks-prd Step 0.8
+ *  first-run templates). */
+export declare function readProjectScanRaw(projectRoot: string): Promise<string | null>;
+export declare function readBusinessKnowledgeRaw(projectRoot: string): Promise<string | null>;