peaks-loop 4.0.0-beta.3 → 4.0.0-beta.31

package/dist/services/memory/project-context-service.js

@@ -0,0 +1,161 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listSessionMetas } from '../session/session-manager.js';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { bootstrapProjectScan } from '../prd/project-scan-bootstrap-service.js';
+const PROJECT_CONTEXT_FILE = '.peaks/PROJECT.md';
+const CONTEXT_HEADER = `# Peaks Project Context
+
+> Auto-generated project memory. Peaks reads this at the start of each session to understand
+> the project's history, tech stack, conventions, and past decisions.
+> Last updated: `;
+const MANAGED_BLOCK_START = '<!-- peaks-managed:session-history-start -->';
+const MANAGED_BLOCK_END = '<!-- peaks-managed:session-history-end -->';
+function projectName(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.name ?? projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return projectRoot.split(/[\\/]/).pop() ?? 'unknown';
+    }
+}
+function listMdFiles(dir, maxDepth = 3) {
+    const results = [];
+    if (!existsSync(dir) || maxDepth <= 0)
+        return results;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return results;
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...listMdFiles(full, maxDepth - 1));
+        }
+        else if (entry.isFile() && entry.name.endsWith('.md')) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function extractOneLineSummary(sessionRoot) {
+    const artifacts = listMdFiles(sessionRoot, 4);
+    for (const artifact of artifacts.slice(0, 5)) {
+        try {
+            const content = readFileSync(artifact, 'utf8');
+            // Grab the first non-heading, non-empty line after the front section
+            const lines = content.split(/\r?\n/);
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('-') || trimmed.startsWith('`'))
+                    continue;
+                if (trimmed.length > 10 && trimmed.length < 200)
+                    return trimmed;
+                break;
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip unreadable
+        }
+    }
+    return null;
+}
+function buildSessionHistory(projectRoot) {
+    const metas = listSessionMetas(projectRoot);
+    if (metas.length === 0) {
+        return `${MANAGED_BLOCK_START}\n\n_No sessions recorded yet._\n\n${MANAGED_BLOCK_END}`;
+    }
+    const maxSessions = 15;
+    // Sort by createdAt descending (most recent first)
+    const sorted = [...metas].sort((a, b) => (b.createdAt || '').localeCompare(a.createdAt || ''));
+    const recent = sorted.slice(0, maxSessions);
+    let body = `${MANAGED_BLOCK_START}\n\n## Timeline (${metas.length} sessions`;
+    if (metas.length > maxSessions)
+        body += `, showing last ${maxSessions}`;
+    body += ')\n\n';
+    // Human-readable timeline: date | name | brief
+    body += `| Date | Directory | Title | What |\n`;
+    body += `|------|-----------|-------|------|\n`;
+    for (const meta of recent) {
+        const date = meta.createdAt ? meta.createdAt.slice(0, 10) : '?';
+        const dir = meta.sessionId;
+        const title = (meta.title ?? 'Untitled').slice(0, 40);
+        const skill = meta.skill ?? '-';
+        // Extract one-line summary from artifacts for the "What" column
+        const sessionRoot = getSessionDir(projectRoot, meta.sessionId);
+        const summary = extractOneLineSummary(sessionRoot);
+        const brief = summary ? summary.slice(0, 70) : skill;
+        body += `| ${date} | \`${dir}\` | ${title} | ${brief} |\n`;
+    }
+    body += `\n${MANAGED_BLOCK_END}`;
+    return body;
+}
+export async function generateProjectContext(projectRoot) {
+    const peaksDir = join(projectRoot, '.peaks');
+    if (!existsSync(peaksDir)) {
+        mkdirSync(peaksDir, { recursive: true });
+    }
+    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
+    const name = projectName(projectRoot);
+    const now = new Date().toISOString();
+    const sessionHistory = buildSessionHistory(projectRoot);
+    const header = `${CONTEXT_HEADER}${now}\n\n## Project: ${name}\n`;
+    let content;
+    if (existsSync(contextPath)) {
+        const existing = readFileSync(contextPath, 'utf8');
+        const startIdx = existing.indexOf(MANAGED_BLOCK_START);
+        const endIdx = existing.indexOf(MANAGED_BLOCK_END);
+        // Update the Last-updated timestamp in the header
+        const updatedExisting = existing.replace(/Last updated: .*/, `Last updated: ${now}`);
+        if (startIdx >= 0 && endIdx > startIdx) {
+            // Replace managed block, preserve user content outside it
+            const before = updatedExisting.slice(0, startIdx);
+            const after = updatedExisting.slice(endIdx + MANAGED_BLOCK_END.length);
+            content = before + sessionHistory + after;
+        }
+        else {
+            // No managed block found — append
+            content = updatedExisting.trimEnd() + '\n\n' + sessionHistory + '\n';
+        }
+    }
+    else {
+        content = header + '\n' + sessionHistory + '\n';
+    }
+    writeFileSync(contextPath, content, 'utf8');
+    // Slice 2026-07-15-project-scan-bootstrap (G1 + G2):
+    // After writing PROJECT.md, also bootstrap `.peaks/project-scan/`
+    // (project-scan.md + 4 bundled audit/business templates). Idempotent
+    // — re-running this call does not overwrite existing files (unless
+    // the caller passes `force` / `forceTemplates`, which we do NOT do
+    // here; peaks workspace init owns the force variants).
+    const projectScan = await bootstrapProjectScan({ projectRoot });
+    return {
+        path: contextPath,
+        content,
+        sessionCount: listSessionMetas(projectRoot).length,
+        projectScan
+    };
+}
+export function readProjectContext(projectRoot) {
+    const contextPath = join(projectRoot, PROJECT_CONTEXT_FILE);
+    if (!existsSync(contextPath))
+        return null;
+    try {
+        return readFileSync(contextPath, 'utf8');
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function getProjectContextPath(projectRoot) {
+    return join(projectRoot, PROJECT_CONTEXT_FILE);
+}

package/dist/services/migrate-skill-name/schema.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * Result shape for `peaks session migrate-skill-name`.
+ *
+ * Counters:
+ *   - `scannedFiles` — every .json / .md under `.peaks/_runtime/**` (excluding
+ *     skip dirs below).
+ *   - `modifiedFiles` — files whose contents would change (dry-run reports
+ *     the predicted count; --apply reports the actually-written count).
+ *   - `keyValueReplacements` — `"skill": "<old>"` → `"skill": "<new>"`.
+ *   - `stringReplacements` — `/<old>` → `/<new>` slash-trigger mentions.
+ *
+ * Errors are surfaced per-file with `errors: [ "<absPath>: <message>", … ]`;
+ * the tool never silently skips a broken JSON file (Karpathy §4 honesty:
+ * silence on bad data is the worst kind of fake-green).
+ */
+export declare const MigrateResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    scannedFiles: z.ZodNumber;
+    modifiedFiles: z.ZodNumber;
+    keyValueReplacements: z.ZodNumber;
+    stringReplacements: z.ZodNumber;
+    skipped: z.ZodArray<z.ZodString, "many">;
+    errors: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    skipped: string[];
+    ok: boolean;
+    scannedFiles: number;
+    modifiedFiles: number;
+    keyValueReplacements: number;
+    stringReplacements: number;
+    errors: string[];
+}, {
+    skipped: string[];
+    ok: boolean;
+    scannedFiles: number;
+    modifiedFiles: number;
+    keyValueReplacements: number;
+    stringReplacements: number;
+    errors: string[];
+}>;
+export type MigrateResult = z.infer<typeof MigrateResultSchema>;

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

@@ -0,0 +1,28 @@
+import { mkdir, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isDirectory } from 'peaks-loop-shared/fs';
+const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+export async function archiveOpenSpecChange(changeId, options = {}) {
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+        throw new Error(`Invalid changeId: ${changeId} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    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;
+    }
+    if (options.apply !== true) {
+        return { changeId, from, to, applied: false };
+    }
+    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 };
+}

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.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.js

@@ -0,0 +1,95 @@
+/**
+ * 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.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from 'peaks-loop-shared/result';
+const SLUGIFY = /[^a-z0-9]+/g;
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(SLUGIFY, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+function formatProposal(input) {
+    return `# Doctor Finding: ${input.finding.rule}
+
+**Date**: ${input.date}
+**Change ID**: ${input.changeId}
+**Source**: \`peaks doctor\` finding (CRITICAL severity: ${input.finding.severity})
+
+## Why
+
+A \`peaks doctor\` scan flagged the following issue at \`${input.finding.id}\`:
+
+> ${input.finding.detail}
+
+The current behavior is broken or degraded. This proposal outlines a fix.
+
+## What Changes
+
+- Address the doctor finding at \`${input.finding.id}\`.
+- See the Why section above for the original error message.
+- Acceptance criteria below describe the success conditions.
+
+## Acceptance Criteria
+
+- \`peaks doctor --json\` returns \`ok: true\` for the \`${input.finding.id}\` check.
+- Re-running the audit does not regress other findings.
+
+## Out of Scope
+
+- Other doctor findings (each is tracked in its own OpenSpec change).
+- Refactors that don't fix this specific issue.
+
+## Risks
+
+- Low: this is a doctor-flagged issue with a clear acceptance criterion.
+
+## Status
+
+- created: ${input.date}
+- last update: ${input.date}
+- state: draft
+- state reason: auto-generated from peaks doctor; LLM must review + edit before validate
+`;
+}
+function makeChangeId(finding, date) {
+    return `${date}-fix-${slugify(finding.id)}`;
+}
+export function proposeFromDoctor(input) {
+    const date = (input.clock ?? (() => new Date().toISOString()))().slice(0, 10);
+    const changeId = makeChangeId(input.finding, date);
+    const changeDir = join(input.projectRoot, 'openspec/changes', changeId);
+    const proposalPath = join(changeDir, 'proposal.md');
+    let created = false;
+    try {
+        if (!existsSync(changeDir)) {
+            mkdirSync(changeDir, { recursive: true });
+        }
+        if (!existsSync(proposalPath)) {
+            const content = formatProposal({
+                changeId,
+                finding: input.finding,
+                title: `Fix ${input.finding.rule}`,
+                date,
+            });
+            writeFileSync(proposalPath, content);
+            created = true;
+        }
+    }
+    catch (error) {
+        throw new Error(`proposeFromDoctor: ${getErrorMessage(error)}`);
+    }
+    return { changeId, changeDir, proposalPath, created };
+}

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

@@ -0,0 +1,130 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isDirectory, pathExists } from 'peaks-loop-shared/fs';
+import { validateAgainstSchema } from '../../shared/json-schema-mini.js';
+const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+function defaultSchemaPath() {
+    const here = fileURLToPath(import.meta.url);
+    return resolve(here, '..', '..', '..', '..', 'schemas', 'openspec-render-request.schema.json');
+}
+let cachedSchema = null;
+let cachedSchemaPath = null;
+async function loadSchema(schemaPath) {
+    if (cachedSchema !== null && cachedSchemaPath === schemaPath) {
+        return cachedSchema;
+    }
+    if (!(await pathExists(schemaPath))) {
+        return null;
+    }
+    const raw = await readFile(schemaPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    cachedSchema = parsed;
+    cachedSchemaPath = schemaPath;
+    return parsed;
+}
+function formatSchemaIssue(issue) {
+    return `${issue.path}: ${issue.message}`;
+}
+export class OpenSpecRenderRequestInvalidError extends Error {
+    issues;
+    constructor(issues) {
+        const summary = issues.map(formatSchemaIssue).join('; ');
+        super(`OpenSpec render request failed schema validation: ${summary}`);
+        this.name = 'OpenSpecRenderRequestInvalidError';
+        this.issues = issues;
+    }
+}
+function renderBullets(items) {
+    if (items === undefined || items.length === 0) {
+        return '_None_\n';
+    }
+    return `${items.map((item) => `- ${item}`).join('\n')}\n`;
+}
+function renderProposal(request) {
+    const lines = [];
+    lines.push(`# Change: ${request.changeId}`);
+    lines.push('');
+    lines.push('## Why');
+    lines.push('');
+    lines.push(request.why.length > 0 ? request.why : '_None_');
+    lines.push('');
+    lines.push('## What Changes');
+    lines.push('');
+    lines.push(renderBullets(request.whatChanges));
+    lines.push('## Out of Scope');
+    lines.push('');
+    lines.push(renderBullets(request.outOfScope));
+    lines.push('## Dependencies');
+    lines.push('');
+    lines.push(renderBullets(request.dependencies));
+    lines.push('## Risks');
+    lines.push('');
+    lines.push(renderBullets(request.risks));
+    lines.push('## Acceptance Criteria');
+    lines.push('');
+    lines.push(renderBullets(request.acceptanceCriteria));
+    return lines.join('\n');
+}
+function renderTasks(tasks) {
+    const sections = ['# Tasks', ''];
+    for (const task of tasks) {
+        sections.push(`## ${task.heading}`);
+        sections.push('');
+        for (const todo of task.todos) {
+            sections.push(`- [ ] ${todo}`);
+        }
+        if (task.doneItems !== undefined) {
+            for (const done of task.doneItems) {
+                sections.push(`- [x] ${done}`);
+            }
+        }
+        sections.push('');
+    }
+    return sections.join('\n');
+}
+function buildFiles(request, changeRoot) {
+    const files = [
+        { path: join(changeRoot, 'proposal.md'), content: renderProposal(request) }
+    ];
+    if (request.tasks !== undefined && request.tasks.length > 0) {
+        files.push({ path: join(changeRoot, 'tasks.md'), content: renderTasks(request.tasks) });
+    }
+    if (request.design !== undefined) {
+        files.push({ path: join(changeRoot, 'design.md'), content: request.design });
+    }
+    return files;
+}
+async function writeRenderedFiles(files) {
+    for (const file of files) {
+        await mkdir(dirname(file.path), { recursive: true });
+        await writeFile(file.path, file.content, 'utf8');
+    }
+}
+export async function renderOpenSpecChange(request, options = {}) {
+    const schemaPath = options.schemaPath ?? defaultSchemaPath();
+    const schema = await loadSchema(schemaPath);
+    if (schema !== null) {
+        const result = validateAgainstSchema(request, schema);
+        if (!result.valid) {
+            throw new OpenSpecRenderRequestInvalidError(result.errors);
+        }
+    }
+    else if (!CHANGE_ID_PATTERN.test(request.changeId)) {
+        throw new Error(`Invalid changeId: ${request.changeId} (expected letters, digits, dots, underscores, or dashes)`);
+    }
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const changeRoot = join(openspecRoot, 'changes', request.changeId);
+    const files = buildFiles(request, changeRoot);
+    if (options.apply !== true) {
+        return { changeId: request.changeId, changeRoot, files, applied: false };
+    }
+    if (options.overwrite !== true && (await isDirectory(changeRoot))) {
+        throw new Error(`Refusing to render: change directory already exists at ${changeRoot}. Re-run with overwrite to replace it.`);
+    }
+    await writeRenderedFiles(files);
+    return { changeId: request.changeId, changeRoot, files, applied: true };
+}