peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/openspec/openspec-archive-service.js

@@ -0,0 +1,340 @@
+import { mkdir, readFile, rename, readdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { isDirectory } from 'peaks-loop-shared/fs';
+import { validateChangeId } from './artifact-boundary.js';
+import { findStaleChangeFiles, parseCapabilityMapping, readC8Summary, resolveCoverageSummaryPath, validateCapabilityCoverage, } from './coverage-evidence-reader.js';
+export class OpenSpecArchiveError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail = {}) {
+        super(message);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'OpenSpecArchiveError';
+    }
+}
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+/**
+ * Parse the `## Coverage Evidence` block out of a proposal.md.
+ *
+ * Accepted shape (markdown table):
+ *
+ *     ## Coverage Evidence
+ *
+ *     | capability | requirement | status | testAnchor |
+ *     | --- | --- | --- | --- |
+ *     | quality-gates | 100% coverage for included modules | covered | tests/unit/quality-gates.test.ts |
+ *
+ * Returns `{ present: false }` when the heading is missing. Throws
+ * `OpenSpecArchiveError` with `code: 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED'`
+ * when the heading is present but no parsable rows are extracted.
+ */
+export async function parseCoverageEvidence(proposalPath) {
+    let raw;
+    try {
+        raw = await readFile(proposalPath, 'utf8');
+    }
+    catch {
+        return {
+            rows: [],
+            present: false,
+            capabilityRows: [],
+            summaryStatus: 'unavailable',
+            capabilityValidation: 'not-enforced',
+            staleFiles: [],
+            mismatches: [],
+        };
+    }
+    const lines = raw.split(/\r?\n/);
+    const headingIdx = lines.findIndex((line) => /^##\s+Coverage\s+Evidence\s*$/.test(line));
+    if (headingIdx === -1) {
+        return {
+            rows: [],
+            present: false,
+            capabilityRows: [],
+            summaryStatus: 'unavailable',
+            capabilityValidation: 'not-enforced',
+            staleFiles: [],
+            mismatches: [],
+        };
+    }
+    const rows = [];
+    let i = headingIdx + 1;
+    let inFence = false;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (line === undefined)
+            break;
+        if (!inFence && /^##\s+/.test(line))
+            break;
+        if (/^```/.test(line.trim())) {
+            inFence = !inFence;
+            i += 1;
+            continue;
+        }
+        const parsed = parseTableRow(line);
+        if (parsed !== null) {
+            rows.push({ ...parsed, line: i + 1 });
+        }
+        i += 1;
+    }
+    if (rows.length === 0) {
+        throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MALFORMED', `proposal.md contains a "## Coverage Evidence" heading but no parsable requirement rows`, { proposalPath });
+    }
+    return {
+        rows,
+        present: true,
+        capabilityRows: [],
+        summaryStatus: 'unavailable',
+        capabilityValidation: 'not-enforced',
+        staleFiles: [],
+        mismatches: [],
+    };
+}
+function parseTableRow(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith('|'))
+        return null;
+    const cells = trimmed.split('|').slice(1, -1).map((c) => c.trim());
+    if (cells.length < 3)
+        return null;
+    const capability = cells[0];
+    const requirement = cells[1];
+    const statusRaw = cells[2];
+    const testAnchor = cells[3];
+    if (capability === undefined || requirement === undefined || statusRaw === undefined)
+        return null;
+    if (capability.toLowerCase() === 'capability' && requirement.toLowerCase() === 'requirement')
+        return null;
+    if (/^-+$/.test(capability.replace(/\s+/g, '')))
+        return null;
+    const status = statusRaw.toLowerCase();
+    if (status !== 'covered' && status !== 'partial' && status !== 'uncovered')
+        return null;
+    const row = {
+        capability,
+        requirement,
+        status: status,
+    };
+    if (testAnchor !== undefined && testAnchor !== '') {
+        row.testAnchor = testAnchor;
+    }
+    return row;
+}
+/**
+ * Determine whether the change has any spec files (specs/<capability>/spec.md).
+ * When the change has zero spec files, there are no requirements to enforce,
+ * and the Pre-cond 2 gate is skipped — backward-compat for legacy spec-less
+ * changes (e.g. design-only or doc-only changes).
+ */
+async function changeHasSpecs(changeRoot) {
+    const specsRoot = join(changeRoot, 'specs');
+    if (!(await isDirectory(specsRoot)))
+        return false;
+    const entries = await readdir(specsRoot);
+    for (const entry of entries) {
+        const specPath = join(specsRoot, entry, 'spec.md');
+        if (await isDirectory(join(specsRoot, entry))) {
+            try {
+                await readFile(specPath, 'utf8');
+                return true;
+            }
+            catch {
+                // missing spec.md; keep scanning siblings
+            }
+        }
+    }
+    return false;
+}
+function evaluateGate(evidence) {
+    const failing = evidence.rows.filter((r) => r.status !== 'covered');
+    if (failing.length > 0) {
+        return {
+            ok: false,
+            reason: 'requirement-not-fully-covered',
+            failing,
+        };
+    }
+    if (evidence.rows.length === 0) {
+        return {
+            ok: false,
+            reason: 'no-coverage-evidence-block',
+            failing: [],
+        };
+    }
+    return { ok: true };
+}
+export async function archiveOpenSpecChange(changeId, options = {}) {
+    const changeIdResult = validateChangeId(changeId);
+    if (!changeIdResult.ok) {
+        throw new Error(`changeId ${changeId} does not match [A-Za-z0-9][A-Za-z0-9._-]*`);
+    }
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const archiveDir = options.archiveDirName ?? 'archive';
+    const from = join(openspecRoot, 'changes', changeId);
+    const to = join(openspecRoot, 'changes', archiveDir, changeId);
+    if (!(await isDirectory(from))) {
+        return null;
+    }
+    // Pre-cond 2 (Fix-6A + Fix-6B): Coverage Evidence gate.
+    // Only enforce when the change declares at least one spec (otherwise there
+    // are no requirements to gate on — backward-compat for design-only changes).
+    let coverage;
+    let coverageGateBypassed;
+    let coverageMismatchBypassed;
+    if (options.apply === true && (await changeHasSpecs(from))) {
+        const proposalPath = join(from, 'proposal.md');
+        // --- Fix-6A: parse Coverage Evidence block (declarative half) ---
+        const evidence = await parseCoverageEvidence(proposalPath);
+        coverage = evidence;
+        if (!evidence.present) {
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_GATE_FAILED', `Refusing to archive "${changeId}": proposal.md is missing a "## Coverage Evidence" block. ` +
+                'Add a Coverage Evidence table listing every Requirement from specs/*/spec.md with status covered/partial/uncovered, ' +
+                'or re-run with --force to bypass the gate.', { changeId, reason: 'no-coverage-evidence-block', coverage });
+        }
+        const verdict = evaluateGate(evidence);
+        if (!verdict.ok) {
+            if (options.force === true) {
+                coverageGateBypassed = true;
+            }
+            else {
+                throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_GATE_PARTIAL', `Refusing to archive "${changeId}": ${verdict.failing.length} requirement(s) not fully covered. ` +
+                    'Re-run with --force to bypass the gate, or update the Coverage Evidence table to mark each requirement as covered.', {
+                    changeId,
+                    reason: verdict.reason,
+                    failing: verdict.failing.map((r) => ({
+                        capability: r.capability,
+                        requirement: r.requirement,
+                        status: r.status,
+                        testAnchor: r.testAnchor,
+                        line: r.line,
+                    })),
+                    coverage,
+                });
+            }
+        }
+        // --- Fix-6B: parse Capability Mapping block + validate against c8 summary ---
+        const mapping = await parseCapabilityMapping(proposalPath);
+        coverage = {
+            ...coverage,
+            capabilityRows: mapping.rows,
+        };
+        if (mapping.rows.length === 0) {
+            // No mapping → cannot enforce per-capability. Refuse with the same
+            // gate-failed code but a distinct reason in detail (Fix-6B AC3).
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_GATE_FAILED', `Refusing to archive "${changeId}": proposal.md is missing a "## Capability Mapping" block. ` +
+                'Add a Capability Mapping table listing each declared capability alongside its source file or subtree, ' +
+                'or re-run with --force to bypass the gate.', { changeId, reason: 'no-capability-mapping-block', coverage });
+        }
+        // Discover coverage-summary.json
+        const projectRoot = resolve(openspecRoot, '..');
+        const summaryPathResult = await resolveCoverageSummaryPath({
+            projectRoot,
+            ...(options.coverageSummaryPath !== undefined ? { explicitPath: options.coverageSummaryPath } : {}),
+        });
+        if (!summaryPathResult.ok) {
+            // AC1: missing or not-readable
+            const triedPaths = summaryPathResult.error.code === 'missing' ? summaryPathResult.error.triedPaths : [summaryPathResult.error.path];
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MISSING', `Refusing to archive "${changeId}": no coverage-summary.json found at any of: ${triedPaths.join(', ')}. ` +
+                'Run `pnpm test:coverage` (which invokes scripts/coverage-c8.mjs) to generate one, ' +
+                'or pass --coverage-summary <path> to point at an existing summary, ' +
+                'or re-run with --force to bypass.', {
+                changeId,
+                triedPaths,
+                coverage,
+            });
+        }
+        // Parse summary + check freshness (AC2)
+        let summary;
+        try {
+            summary = await readC8Summary(summaryPathResult.value);
+        }
+        catch (error) {
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MISSING', `Refusing to archive "${changeId}": coverage-summary.json at ${summaryPathResult.value} is malformed (${error.message}). ` +
+                'Re-run `pnpm test:coverage` to regenerate, or pass --coverage-summary <path> to point at a valid summary.', { changeId, path: summaryPathResult.value, coverage });
+        }
+        coverage = {
+            ...coverage,
+            summaryPath: summary.path,
+        };
+        const staleFiles = await findStaleChangeFiles({
+            projectRoot,
+            openspecRoot,
+            changeId,
+            summary,
+        });
+        if (staleFiles.length > 0) {
+            coverage = {
+                ...coverage,
+                summaryStatus: 'stale',
+                staleFiles,
+            };
+            throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_STALE', `Refusing to archive "${changeId}": coverage-summary.json is older than ${staleFiles.length} change file(s). ` +
+                'Re-run `pnpm test:coverage` to refresh, or re-run with --force to bypass.', { changeId, staleFiles, summaryPath: summary.path, coverage });
+        }
+        coverage = {
+            ...coverage,
+            summaryStatus: 'fresh',
+        };
+        // Per-capability coverage check (AC4)
+        const validation = await validateCapabilityCoverage({
+            projectRoot,
+            summary,
+            rows: mapping.rows,
+        });
+        if (!validation.ok) {
+            coverage = {
+                ...coverage,
+                capabilityValidation: 'mismatch',
+                mismatches: validation.mismatches,
+            };
+            if (options.force === true) {
+                coverageMismatchBypassed = true;
+            }
+            else {
+                throw new OpenSpecArchiveError('OPENSPEC_COVERAGE_EVIDENCE_MISMATCH', `Refusing to archive "${changeId}": ${validation.mismatches.length} capability row(s) claim "covered" in proposal.md but c8 reports < 100% coverage. ` +
+                    'Re-run `pnpm test:coverage` after closing the gap, or re-run with --force to bypass.', {
+                    changeId,
+                    mismatches: validation.mismatches,
+                    coverage,
+                });
+            }
+        }
+        else {
+            coverage = {
+                ...coverage,
+                capabilityValidation: 'ok',
+            };
+        }
+    }
+    else if (options.apply === true) {
+        // Spec-less change — surface coverage evidence for visibility, never fail.
+        const proposalPath = join(from, 'proposal.md');
+        coverage = await parseCoverageEvidence(proposalPath);
+    }
+    if (options.apply !== true) {
+        return {
+            changeId,
+            from,
+            to,
+            applied: false,
+            ...(coverage !== undefined ? { coverage } : {}),
+        };
+    }
+    if (await isDirectory(to)) {
+        throw new Error(`Refusing to archive: target already exists at ${to}`);
+    }
+    await mkdir(dirname(to), { recursive: true });
+    await rename(from, to);
+    return {
+        changeId,
+        from,
+        to,
+        applied: true,
+        ...(coverage !== undefined ? { coverage } : {}),
+        ...(coverageGateBypassed === true ? { coverageGateBypassed: true } : {}),
+        ...(coverageMismatchBypassed === true ? { coverageMismatchBypassed: true } : {}),
+    };
+}

package/dist/services/openspec/openspec-bridge-service.d.ts

@@ -0,0 +1,16 @@
+import { type OpenSpecScanOptions } from './openspec-scan-service.js';
+export type OpenSpecCommitBoundary = {
+    heading: string;
+    todos: string[];
+    doneItems: string[];
+};
+export type OpenSpecRdInputProjection = {
+    changeId: string;
+    acceptance: string[];
+    whatChanges: string[];
+    dependencies: string[];
+    risks: string[];
+    outOfScope: string[];
+    commitBoundaries: OpenSpecCommitBoundary[];
+};
+export declare function projectOpenSpecToRdInput(changeId: string, options?: OpenSpecScanOptions): Promise<OpenSpecRdInputProjection | null>;

package/dist/services/openspec/openspec-bridge-service.js

@@ -0,0 +1,76 @@
+import { readText } from 'peaks-loop-shared/fs';
+import { loadOpenSpecChange } from './openspec-scan-service.js';
+function splitTaskSections(markdown) {
+    const sections = [];
+    let current = null;
+    for (const line of markdown.split(/\r?\n/)) {
+        if (line.startsWith('## ')) {
+            if (current !== null) {
+                sections.push(current);
+            }
+            current = { heading: line.slice(3).trim(), body: [] };
+        }
+        else if (current !== null) {
+            current.body.push(line);
+        }
+    }
+    if (current !== null) {
+        sections.push(current);
+    }
+    return sections;
+}
+const TODO_PATTERN = /^- \[ \] (.+?)\s*$/;
+const DONE_PATTERN = /^- \[[xX]\] (.+?)\s*$/;
+function extractItems(body) {
+    const todos = [];
+    const doneItems = [];
+    for (const rawLine of body) {
+        const line = rawLine.trim();
+        const todoMatch = TODO_PATTERN.exec(line);
+        if (todoMatch !== null) {
+            todos.push(todoMatch[1]);
+            continue;
+        }
+        const doneMatch = DONE_PATTERN.exec(line);
+        if (doneMatch !== null) {
+            doneItems.push(doneMatch[1]);
+        }
+    }
+    return { todos, doneItems };
+}
+async function buildCommitBoundaries(tasksPath) {
+    if (tasksPath === null) {
+        return [];
+    }
+    const markdown = await readText(tasksPath);
+    const boundaries = [];
+    for (const section of splitTaskSections(markdown)) {
+        const { todos, doneItems } = extractItems(section.body);
+        if (todos.length === 0 && doneItems.length === 0) {
+            continue;
+        }
+        boundaries.push({ heading: section.heading, todos, doneItems });
+    }
+    return boundaries;
+}
+export async function projectOpenSpecToRdInput(changeId, options = {}) {
+    const detail = await loadOpenSpecChange(changeId, options);
+    if (detail === null) {
+        return null;
+    }
+    const acceptance = detail.proposal?.acceptanceCriteria ?? [];
+    const whatChanges = detail.proposal?.whatChanges ?? [];
+    const dependencies = detail.proposal?.dependencies ?? [];
+    const risks = detail.proposal?.risks ?? [];
+    const outOfScope = detail.proposal?.outOfScope ?? [];
+    const commitBoundaries = await buildCommitBoundaries(detail.paths.tasks);
+    return {
+        changeId,
+        acceptance,
+        whatChanges,
+        dependencies,
+        risks,
+        outOfScope,
+        commitBoundaries
+    };
+}

package/dist/services/openspec/openspec-init-service.d.ts

@@ -0,0 +1,23 @@
+export type OpenSpecInitOptions = {
+    projectRoot: string;
+    apply?: boolean;
+};
+export type OpenSpecInitPlan = {
+    apply: boolean;
+    projectRoot: string;
+    openspecRoot: string;
+    plannedWrites: Array<{
+        path: string;
+        kind: 'directory' | 'file';
+        bytes: number;
+        content: string;
+    }>;
+    alreadyInitialized: boolean;
+    existingFiles: string[];
+};
+export type OpenSpecInitResult = OpenSpecInitPlan & {
+    writtenFiles: string[];
+    createdDirectories: string[];
+};
+export declare function planOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitPlan>;
+export declare function executeOpenSpecInit(options: OpenSpecInitOptions): Promise<OpenSpecInitResult>;

package/dist/services/openspec/openspec-init-service.js

@@ -0,0 +1,122 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists } from 'peaks-loop-shared/fs';
+const README_BODY = `# OpenSpec — change proposals for this project
+
+This directory hosts the \`peaks openspec\` change proposal lifecycle:
+
+  render → validate → show → to-rd → ... → archive
+
+Each in-flight proposal lives in \`changes/<id>/\` and contains:
+
+- \`proposal.md\`  — why, what, non-goals, impact
+- \`tasks.md\`     — concrete slices and commit boundaries (consumed by peaks-sc)
+- \`design.md\`   — optional, for non-trivial designs
+- \`specs/\`       — optional, delta-style spec changes (## ADDED / ## MODIFIED / ## REMOVED)
+- \`*.md\`         — any additional narrative the change needs
+
+When a change ships, \`peaks openspec archive <id> --apply\` moves it into
+\`changes/archive/<id>/\`. The archive is the historical record of what
+landed and why.
+
+To scaffold a fresh change in this project:
+
+  peaks openspec render --request <path-to-render-request.json> --apply
+
+For the full lifecycle see \`peaks openspec --help\` and the
+peaks-clause-code skill family.
+`;
+const CHANGES_INDEX_HEADER = `# OpenSpec — change log
+
+This file is the human-readable index of every change that has shipped in
+this project. New entries are added by \`peaks openspec archive\` (when
+\`.apply\` is used); do not hand-edit.
+
+| Date | Change | Status |
+|------|--------|--------|
+`;
+function renderReadme() {
+    return README_BODY;
+}
+function renderChangesIndex() {
+    return CHANGES_INDEX_HEADER;
+}
+function buildPlan(projectRoot, apply) {
+    const openspecRoot = join(projectRoot, 'openspec');
+    const changesRoot = join(openspecRoot, 'changes');
+    const archiveRoot = join(changesRoot, 'archive');
+    const plannedWrites = [
+        { path: openspecRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: changesRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: archiveRoot, kind: 'directory', bytes: 0, content: '' },
+        { path: join(openspecRoot, 'README.md'), kind: 'file', bytes: 0, content: renderReadme() },
+        { path: join(openspecRoot, 'CHANGES.md'), kind: 'file', bytes: 0, content: renderChangesIndex() }
+    ];
+    // Stamp byte counts now that content is finalised.
+    for (const write of plannedWrites) {
+        if (write.kind === 'file') {
+            write.bytes = Buffer.byteLength(write.content, 'utf8');
+        }
+    }
+    return {
+        apply,
+        projectRoot,
+        openspecRoot,
+        plannedWrites,
+        alreadyInitialized: false,
+        existingFiles: []
+    };
+}
+export async function planOpenSpecInit(options) {
+    const openspecRoot = join(options.projectRoot, 'openspec');
+    const plan = buildPlan(options.projectRoot, options.apply ?? false);
+    if (await isDirectory(openspecRoot)) {
+        // Already initialised. Report the existing files so the user can audit
+        // before re-running with --apply. We never overwrite an existing
+        // openspec/ — that is a destructive action and out of scope for init.
+        const existing = [];
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'file' && (await pathExists(write.path))) {
+                existing.push(write.path);
+            }
+        }
+        // Pre-compute which directory writes to keep (those whose target does
+        // not exist yet). .filter cannot be async, so resolve the boolean
+        // set up front.
+        const directoryKeep = new Set();
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory' && !(await isDirectory(write.path))) {
+                directoryKeep.add(write.path);
+            }
+        }
+        plan.plannedWrites = plan.plannedWrites.filter((write) => {
+            if (write.kind === 'directory')
+                return directoryKeep.has(write.path);
+            return !existing.includes(write.path);
+        });
+        plan.alreadyInitialized = existing.length > 0 || (await isDirectory(join(openspecRoot, 'changes')));
+        plan.existingFiles = existing;
+    }
+    return plan;
+}
+export async function executeOpenSpecInit(options) {
+    const plan = await planOpenSpecInit(options);
+    const writtenFiles = [];
+    const createdDirectories = [];
+    if (plan.apply && !plan.alreadyInitialized) {
+        for (const write of plan.plannedWrites) {
+            if (write.kind === 'directory') {
+                if (!(await isDirectory(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, writtenFiles, createdDirectories };
+}

package/dist/services/openspec/openspec-propose-from-doctor-service.d.ts

@@ -0,0 +1,31 @@
+/**
+ * openspec-propose-from-doctor-service (Slice L3.3) — generates a draft
+ * OpenSpec change record (proposal.md) from a doctor CRITICAL finding.
+ *
+ * Per L1+L2+L3 redesign §5.4: "CRITICAL → proposal 草稿生成". The doctor
+ * scans the project for issues; when a CRITICAL finding is surfaced,
+ * peaks-loop generates a draft `openspec/changes/<id>/proposal.md` so the
+ * LLM doesn't have to start from scratch.
+ *
+ * The draft proposal is INFORMATIONAL — it requires the LLM to review +
+ * edit before `peaks openspec validate` will accept it.
+ */
+export interface DoctorFinding {
+    readonly id: string;
+    readonly rule: string;
+    readonly detail: string;
+    readonly severity: 'pass' | 'warn' | 'fail';
+}
+export interface ProposeFromDoctorInput {
+    readonly projectRoot: string;
+    readonly finding: DoctorFinding;
+    /** Optional clock for testability. */
+    readonly clock?: () => string;
+}
+export interface ProposeFromDoctorResult {
+    readonly changeId: string;
+    readonly changeDir: string;
+    readonly proposalPath: string;
+    readonly created: boolean;
+}
+export declare function proposeFromDoctor(input: ProposeFromDoctorInput): ProposeFromDoctorResult;