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

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

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1,150 +0,0 @@
-/**
- * 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

@@ -1,97 +0,0 @@
-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>;