peaks-loop 3.0.0

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

package/dist/src/services/prd/project-scan-reader.js

@@ -0,0 +1,150 @@
+/**
+ * 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 { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+const PROJECT_SCAN_RELATIVE = join('.peaks', 'project-scan', 'project-scan.md');
+const BUSINESS_KNOWLEDGE_RELATIVE = join('.peaks', 'project-scan', 'business-knowledge.md');
+/** 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 async function readProjectScan(projectRoot) {
+    const content = await readOptionalFile(projectRoot, PROJECT_SCAN_RELATIVE);
+    if (content === null)
+        return null;
+    return parseProjectScanContent(content);
+}
+/** Read `.peaks/project-scan/business-knowledge.md`. Returns `null`
+ *  when absent. Throws on other IO failures or malformed YAML. */
+export async function readBusinessKnowledge(projectRoot) {
+    const content = await readOptionalFile(projectRoot, BUSINESS_KNOWLEDGE_RELATIVE);
+    if (content === null)
+        return null;
+    return parseBusinessKnowledgeContent(content);
+}
+/** 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 async function readProjectScanRaw(projectRoot) {
+    return readOptionalFile(projectRoot, PROJECT_SCAN_RELATIVE);
+}
+export async function readBusinessKnowledgeRaw(projectRoot) {
+    return readOptionalFile(projectRoot, BUSINESS_KNOWLEDGE_RELATIVE);
+}
+// ── internal helpers ─────────────────────────────────────────────────
+async function readOptionalFile(projectRoot, relativePath) {
+    const absolutePath = join(projectRoot, relativePath);
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch (error) {
+        if (isEnoent(error))
+            return null;
+        throw error;
+    }
+}
+function isEnoent(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}
+function parseProjectScanContent(content) {
+    const { frontmatter } = splitFrontmatter(content);
+    let parsed;
+    try {
+        parsed = parseYaml(frontmatter);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`project-scan: frontmatter YAML parse failed: ${message}`);
+    }
+    if (!isProjectScan(parsed)) {
+        throw new Error('project-scan: frontmatter shape validation failed');
+    }
+    return parsed;
+}
+function parseBusinessKnowledgeContent(content) {
+    const { frontmatter, body } = splitFrontmatter(content);
+    let parsed;
+    try {
+        parsed = parseYaml(frontmatter);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`business-knowledge: frontmatter YAML parse failed: ${message}`);
+    }
+    if (!isBusinessKnowledgeFrontmatter(parsed)) {
+        throw new Error('business-knowledge: frontmatter shape validation failed');
+    }
+    // Concepts live in the markdown TABLE in the body (not in the frontmatter
+    // YAML). The bootstrap template writes the table for human readability; the
+    // sediment step (Group C, Tier 5) appends new rows to the same table.
+    const concepts = parseConceptsFromMarkdownTable(body);
+    return { schemaVersion: 1, concepts };
+}
+/** Parse the markdown table rows under `# Business Knowledge` (or any H1).
+ *  Each row MUST have 5 cells: Concept | Definition | Source | Decided | Evidence.
+ *  Throws on rows that don't match the shape (we never silently drop a row). */
+function parseConceptsFromMarkdownTable(body) {
+    const lines = body.split(/\r?\n/);
+    const tableLines = lines.filter((line) => /^\s*\|/.test(line));
+    if (tableLines.length < 2) {
+        // No table at all (fresh file). Return empty; sediment writer will append.
+        return [];
+    }
+    // First row = header, second row = separator (---|---|---). Skip both.
+    const dataRows = tableLines.slice(2);
+    const concepts = [];
+    for (const row of dataRows) {
+        const cells = row
+            .split('|')
+            .map((cell) => cell.trim())
+            .filter((cell, idx, arr) => !(idx === 0 && cell === '') && !(idx === arr.length - 1 && cell === ''));
+        if (cells.length < 5)
+            continue;
+        const [concept, definition, sourceRid, decidedAt, evidence] = cells;
+        if (!concept || !definition || !sourceRid || !decidedAt || !evidence)
+            continue;
+        concepts.push({ concept, definition, sourceRid, decidedAt, evidence });
+    }
+    return concepts;
+}
+function splitFrontmatter(content) {
+    const match = /^---\n([\s\S]*?)\n---(?:\n([\s\S]*))?$/.exec(content);
+    if (!match) {
+        throw new Error('frontmatter block missing or malformed');
+    }
+    return { frontmatter: match[1] ?? '', body: match[2] ?? '' };
+}
+function isProjectScan(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    return (v.schemaVersion === 1 &&
+        typeof v.capturedAt === 'string' &&
+        !!v.techStack &&
+        typeof v.techStack === 'object' &&
+        !!v.libraryVersions &&
+        typeof v.libraryVersions === 'object' &&
+        typeof v.architecture === 'string' &&
+        !!v.karpathySelfCheck &&
+        typeof v.karpathySelfCheck === 'object');
+}
+function isBusinessKnowledgeFrontmatter(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const v = value;
+    // Frontmatter only carries `schemaVersion: 1`; concepts live in the
+    // markdown table in the body (see parseConceptsFromMarkdownTable).
+    return v.schemaVersion === 1;
+}

package/dist/src/services/prd/project-scan-sediment.d.ts

@@ -0,0 +1,97 @@
+import type { BusinessConcept } from './project-scan-types.js';
+export interface SedimentAppendOptions {
+    readonly projectRoot: string;
+    readonly concept: BusinessConcept;
+}
+export interface SedimentAppendResult {
+    /** `true` when the file was rewritten; `false` when the (concept, sourceRid) tuple was already present. */
+    readonly written: boolean;
+    /** `true` when a new file was created (vs. appended to an existing file). */
+    readonly created: boolean;
+    /** Total concept rows after the operation. */
+    readonly totalConcepts: number;
+}
+/**
+ * Single row of the audit-template inventory tables. The 4-tuple shape
+ * mirrors the table layout in `.peaks/project-scan/{security-template,
+ * perf-template, audit-output-schema}.md`:
+ *
+ *   security-template.md  Known risks inventory    Risk pattern
+ *   perf-template.md      Known baselines inventory Baseline description
+ *   audit-output-schema.md Known schema variants    Variant description
+ *
+ * The `status` enum follows each template's own status vocabulary:
+ *   - security:   active | mitigated | accepted | deprecated
+ *   - perf:       active | superseded | deprecated
+ *   - audit-schema: active | superseded | deprecated
+ *
+ * Callers pass the field set appropriate for the table they're
+ * appending to; the writer does not enforce which `status` values are
+ * legal (the audit skill that wrote the row is authoritative).
+ */
+export interface AuditPatternRow {
+    /** Natural-language description of the pattern (the second column). */
+    readonly value: string;
+    /** Request-id that first surfaced / established the pattern. */
+    readonly sourceRid: string;
+    /** Human-readable source pointer (e.g. memory file path). */
+    readonly source: string;
+    /** Status enum value (template-specific — see docstring above). */
+    readonly status: string;
+}
+export interface AuditPatternAppendOptions {
+    readonly projectRoot: string;
+    readonly row: AuditPatternRow;
+}
+export interface AuditPatternAppendResult {
+    /** `true` when the file was rewritten; `false` when the (value, sourceRid) tuple was already present. */
+    readonly written: boolean;
+    /** `true` when a new file was created (vs. appended to an existing file). */
+    readonly created: boolean;
+    /** Auto-incremented row number assigned to the new row. */
+    readonly assignedIndex: number;
+    /** Total inventory rows after the operation (excludes the placeholder `| (empty) |` row). */
+    readonly totalRows: number;
+}
+/**
+ * Append (or create) a business concept row in
+ * `.peaks/project-scan/business-knowledge.md`.
+ *
+ * Idempotency contract (matches the bootstrap file's design intent):
+ * - same `(concept, sourceRid)` tuple → skip (return `written: false`)
+ * - same `concept`, DIFFERENT `sourceRid` → append (re-definition from a new source)
+ * - new concept → append
+ *
+ * Throws when the existing file has malformed frontmatter or markdown
+ * table (no silent corruption). Caller should fix the file before retrying.
+ */
+export declare function appendBusinessConcept(opts: SedimentAppendOptions): Promise<SedimentAppendResult>;
+/**
+ * Append (or create) a security-audit risk-pattern row in
+ * `.peaks/project-scan/security-template.md` "Known risks inventory".
+ *
+ * The on-disk format is a 5-column markdown table (auto-incremented `#`
+ * + 4 string fields). Idempotency: same `(value, sourceRid)` tuple is a
+ * no-op; the frontmatter is preserved verbatim. The first append replaces
+ * the `| (empty) |` placeholder row; subsequent appends go after the
+ * table footer.
+ */
+export declare function appendSecurityPattern(opts: AuditPatternAppendOptions): Promise<AuditPatternAppendResult>;
+/**
+ * Append (or create) a perf-audit baseline row in
+ * `.peaks/project-scan/perf-template.md` "Known baselines inventory".
+ *
+ * Same contract as `appendSecurityPattern` (5-column markdown table,
+ * auto-incremented `#`, idempotent on `(value, sourceRid)`,
+ * frontmatter preserved verbatim).
+ */
+export declare function appendPerfPattern(opts: AuditPatternAppendOptions): Promise<AuditPatternAppendResult>;
+/**
+ * Append (or create) an audit-output-schema variant row in
+ * `.peaks/project-scan/audit-output-schema.md` "Known schema variants".
+ *
+ * Same contract as `appendSecurityPattern` (5-column markdown table,
+ * auto-incremented `#`, idempotent on `(value, sourceRid)`,
+ * frontmatter preserved verbatim).
+ */
+export declare function appendAuditSchemaVariant(opts: AuditPatternAppendOptions): Promise<AuditPatternAppendResult>;