peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

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

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

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import { isDirectory, listDirectories, pathExists, readText } from 'peaks-loop-shared/fs';
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+function parseMarkdownSections(markdown) {
+    const sections = new Map();
+    const lines = markdown.split(/\r?\n/);
+    let currentHeading = null;
+    let buffer = [];
+    const flush = () => {
+        if (currentHeading !== null) {
+            sections.set(currentHeading, buffer.join('\n').trim());
+        }
+    };
+    for (const line of lines) {
+        if (line.startsWith('## ')) {
+            flush();
+            currentHeading = line.slice(3).trim();
+            buffer = [];
+        }
+        else if (currentHeading !== null) {
+            buffer.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+function parseBullets(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('- ') || line === '-')
+        .map((line) => line.replace(/^-\s*/, '').trim())
+        .filter((line) => line.length > 0 && !line.startsWith('[ ]') && !line.startsWith('[x]') && !line.startsWith('[X]'));
+}
+function parseProposal(markdown) {
+    const sections = parseMarkdownSections(markdown);
+    const why = sections.get('Why') ?? '';
+    return {
+        why,
+        whatChanges: parseBullets(sections.get('What Changes') ?? ''),
+        outOfScope: parseBullets(sections.get('Out of Scope') ?? ''),
+        dependencies: parseBullets(sections.get('Dependencies') ?? ''),
+        risks: parseBullets(sections.get('Risks') ?? ''),
+        acceptanceCriteria: parseBullets(sections.get('Acceptance Criteria') ?? '')
+    };
+}
+function parseTaskProgress(markdown) {
+    const sections = parseMarkdownSections(markdown);
+    const sectionEntries = [];
+    let totalTodo = 0;
+    let doneTodo = 0;
+    for (const [heading, body] of sections.entries()) {
+        let sectionTotal = 0;
+        let sectionDone = 0;
+        for (const line of body.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (/^- \[[ xX]\]/.test(trimmed)) {
+                sectionTotal += 1;
+                if (/^- \[[xX]\]/.test(trimmed)) {
+                    sectionDone += 1;
+                }
+            }
+        }
+        if (sectionTotal > 0) {
+            sectionEntries.push({ heading, total: sectionTotal, done: sectionDone });
+            totalTodo += sectionTotal;
+            doneTodo += sectionDone;
+        }
+    }
+    return { totalTodo, doneTodo, sections: sectionEntries };
+}
+async function listSpecs(changeRoot) {
+    const specsRoot = join(changeRoot, 'specs');
+    if (!(await isDirectory(specsRoot))) {
+        return [];
+    }
+    return listDirectories(specsRoot);
+}
+async function resolvePaths(changeRoot) {
+    const proposalPath = join(changeRoot, 'proposal.md');
+    const tasksPath = join(changeRoot, 'tasks.md');
+    const designPath = join(changeRoot, 'design.md');
+    return {
+        root: changeRoot,
+        proposal: (await pathExists(proposalPath)) ? proposalPath : null,
+        tasks: (await pathExists(tasksPath)) ? tasksPath : null,
+        design: (await pathExists(designPath)) ? designPath : null
+    };
+}
+async function buildSummary(id, changeRoot) {
+    const paths = await resolvePaths(changeRoot);
+    const specs = await listSpecs(changeRoot);
+    let taskProgress = null;
+    if (paths.tasks !== null) {
+        taskProgress = parseTaskProgress(await readText(paths.tasks));
+    }
+    return { id, paths, specs, taskProgress };
+}
+export async function scanOpenSpec(options = {}) {
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const changesRoot = join(openspecRoot, 'changes');
+    if (!(await isDirectory(openspecRoot))) {
+        return { openspecRoot, changesRoot, exists: false, changes: [] };
+    }
+    if (!(await isDirectory(changesRoot))) {
+        return { openspecRoot, changesRoot, exists: true, changes: [] };
+    }
+    const ids = await listDirectories(changesRoot);
+    const changes = await Promise.all(ids.map((id) => buildSummary(id, join(changesRoot, id))));
+    return { openspecRoot, changesRoot, exists: true, changes };
+}
+export async function loadOpenSpecChange(changeId, options = {}) {
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const changeRoot = join(openspecRoot, 'changes', changeId);
+    if (!(await isDirectory(changeRoot))) {
+        return null;
+    }
+    const summary = await buildSummary(changeId, changeRoot);
+    const proposal = summary.paths.proposal === null ? null : parseProposal(await readText(summary.paths.proposal));
+    return { ...summary, proposal };
+}

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

@@ -0,0 +1,77 @@
+import { join } from 'node:path';
+import { isDirectory } from 'peaks-loop-shared/fs';
+import { loadOpenSpecChange } from './openspec-scan-service.js';
+const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+async function defaultExternalRunner(_command, _args) {
+    return { available: false, exitCode: null, stdout: '', stderr: '' };
+}
+function buildInternalIssues(changeId, detail) {
+    const issues = [];
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+        issues.push({
+            level: 'error',
+            rule: 'change-id-format',
+            message: `changeId ${changeId} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+        });
+    }
+    if (detail === null || detail.proposal === null) {
+        issues.push({ level: 'error', rule: 'proposal-exists', message: 'proposal.md is missing' });
+        return issues;
+    }
+    const proposal = detail.proposal;
+    if (proposal.why.length === 0) {
+        issues.push({ level: 'warning', rule: 'why-non-empty', message: 'Why section is empty' });
+    }
+    if (proposal.whatChanges.length === 0) {
+        issues.push({ level: 'error', rule: 'what-changes-non-empty', message: 'What Changes section has no bullets' });
+    }
+    if (proposal.acceptanceCriteria.length === 0) {
+        issues.push({ level: 'error', rule: 'acceptance-non-empty', message: 'Acceptance Criteria section has no bullets' });
+    }
+    return issues;
+}
+function hasErrors(issues) {
+    return issues.some((issue) => issue.level === 'error');
+}
+async function runInternal(changeId, openspecRoot) {
+    const changeRoot = join(openspecRoot, 'changes', changeId);
+    if (!(await isDirectory(changeRoot))) {
+        return null;
+    }
+    const detail = await loadOpenSpecChange(changeId, { openspecRoot });
+    const issues = buildInternalIssues(changeId, detail);
+    return {
+        changeId,
+        valid: !hasErrors(issues),
+        source: 'internal',
+        issues
+    };
+}
+export async function validateOpenSpecChange(changeId, options = {}) {
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const runner = options.externalRunner ?? defaultExternalRunner;
+    if (options.preferExternal === true) {
+        const outcome = await runner('openspec', ['validate', changeId]);
+        if (outcome.available) {
+            const cliOutput = [outcome.stdout, outcome.stderr].filter((part) => part.length > 0).join('\n').trim();
+            const passed = outcome.exitCode === 0;
+            const issues = passed
+                ? []
+                : [{ level: 'error', rule: 'openspec-cli-failed', message: `openspec validate exited with code ${outcome.exitCode ?? 'null'}` }];
+            return { changeId, valid: passed, source: 'openspec-cli', issues, cliOutput };
+        }
+        const internal = await runInternal(changeId, openspecRoot);
+        if (internal === null) {
+            return null;
+        }
+        internal.issues = [
+            { level: 'warning', rule: 'openspec-cli-unavailable', message: 'openspec CLI not found, fell back to internal lint' },
+            ...internal.issues
+        ];
+        return internal;
+    }
+    return runInternal(changeId, openspecRoot);
+}

package/dist/services/polyrepo/polyrepo-dispatcher.d.ts

@@ -0,0 +1,34 @@
+import type { PolyrepoDispatch, PolyrepoManifest } from './polyrepo-types.js';
+export interface DispatchOptions {
+    /** Manifest returned by scanPolyrepo (root + children list). */
+    readonly manifest: PolyrepoManifest;
+    /** Session id this dispatch belongs to. */
+    readonly sid: string;
+    /** Request id (used in the on-disk filename). */
+    readonly rid: string;
+    /** Target child ids. Empty = root-only dispatch. Unknown ids are
+     *  recorded as warnings in the result, NOT raised as errors. */
+    readonly targets: readonly string[];
+    /** Artifact body — the role + source path on the parent side. */
+    readonly artifact: PolyrepoDispatch['artifact'];
+}
+export interface ChildDispatchResult {
+    readonly childId: string;
+    readonly path: string;
+    readonly ok: boolean;
+    readonly error?: string;
+    /** Where the artifact was mirrored to (child-side path). */
+    readonly mirroredTo?: string;
+}
+export interface DispatchResult {
+    readonly dispatch: PolyrepoDispatch;
+    readonly perChild: ChildDispatchResult[];
+    readonly warnings: string[];
+}
+export declare function dispatchArtifact(opts: DispatchOptions): DispatchResult;
+/** Default location of the polyrepo manifest on disk. */
+export declare function manifestPath(root: string): string;
+/** Read a persisted manifest from disk. Returns null when missing. */
+export declare function readManifest(root: string): PolyrepoManifest | null;
+/** Write a manifest atomically. */
+export declare function writeManifest(root: string, manifest: PolyrepoManifest): void;

package/dist/services/polyrepo/polyrepo-dispatcher.js

@@ -0,0 +1,119 @@
+/**
+ * Polyrepo dispatcher — slice S2-b of RD-2.
+ *
+ * Takes a parent root + a list of target child ids + a PRD/RD/QA
+ * artifact, and mirrors the artifact into each target child's
+ * `.peaks/_runtime/<sid>/<role>/` directory. Mirroring is
+ * best-effort + atomic per child: a failure in one child does NOT
+ * block the others (the dispatcher collects per-child results and
+ * returns them all so the caller can surface partial successes).
+ *
+ * Design notes:
+ *  - Per the project's two-axis convention, the parent's reviewable
+ *    artifact lives under `.peaks/_runtime/<sid>/<role>/`, not as a
+ *    sibling of `.peaks/_runtime/`. We mirror the same shape into
+ *    each child (the child does NOT inherit the parent's session
+ *    id verbatim — it gets the same one, which is fine because the
+ *    sid is the project's binding, not the parent's transient
+ *    pid).
+ *  - The dispatcher does NOT spawn any vendor verb — vendor
+ *    neutrality is preserved. If a child has no peaks-loop binary
+ *    on PATH, the dispatcher writes the artifact to disk and notes
+ *    a `peaksInstalled: false` warning; the user / a future slice
+ *    can pick it up. Per PRD §5 mitigation for "child has no
+ *    peaks-loop installed".
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Compute the child-side path where the artifact should be mirrored.
+ *  Mirrors the parent shape exactly: `.peaks/_runtime/<sid>/<role>/`. */
+function childArtifactPath(childRoot, sid, role, sourcePath) {
+    const filename = sourcePath.split(/[\\/]/).pop() ?? 'artifact.md';
+    return join(childRoot, '.peaks', '_runtime', sid, role, filename);
+}
+function ensureDirFor(file) {
+    mkdirSync(dirname(file), { recursive: true });
+}
+export function dispatchArtifact(opts) {
+    const warnings = [];
+    const perChild = [];
+    // Validate targets against the manifest.
+    const knownIds = new Set(opts.manifest.children.map((c) => c.id));
+    const validTargets = [];
+    for (const t of opts.targets) {
+        if (knownIds.has(t)) {
+            validTargets.push(t);
+        }
+        else {
+            warnings.push(`unknown target id "${t}" — ignored`);
+        }
+    }
+    // Read the source artifact body once (so we can mirror to N children).
+    let sourceBody;
+    try {
+        sourceBody = readFileSync(opts.artifact.path, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`source artifact unreadable at ${opts.artifact.path}: ${err.message}`);
+    }
+    // Per-child write.
+    for (const targetId of validTargets) {
+        const child = opts.manifest.children.find((c) => c.id === targetId);
+        if (child === undefined)
+            continue; // already filtered above
+        const dest = childArtifactPath(child.path, opts.sid, opts.artifact.role, opts.artifact.path);
+        try {
+            ensureDirFor(dest);
+            writeFileSync(dest, sourceBody, 'utf8');
+            perChild.push({
+                childId: targetId,
+                path: child.path,
+                ok: true,
+                mirroredTo: dest
+            });
+            if (!child.peaksInstalled) {
+                warnings.push(`child "${targetId}" has no peaks-loop install — artifact mirrored but not picked up by a running peaks process`);
+            }
+        }
+        catch (err) {
+            perChild.push({
+                childId: targetId,
+                path: child.path,
+                ok: false,
+                error: err.message
+            });
+        }
+    }
+    const dispatch = {
+        rid: opts.rid,
+        sid: opts.sid,
+        root: opts.manifest.root,
+        targets: validTargets,
+        dispatchedAt: new Date().toISOString(),
+        artifact: opts.artifact
+    };
+    return { dispatch, perChild, warnings };
+}
+/** Default location of the polyrepo manifest on disk. */
+export function manifestPath(root) {
+    return join(root, '.peaks', 'polyrepo.json');
+}
+/** Read a persisted manifest from disk. Returns null when missing. */
+export function readManifest(root) {
+    const p = manifestPath(root);
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = readFileSync(p, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch { // TODO(g2): fail-closed JSON parse — null is the documented contract, caller checks via existsSync
+        return null;
+    }
+}
+/** Write a manifest atomically. */
+export function writeManifest(root, manifest) {
+    const p = manifestPath(root);
+    ensureDirFor(p);
+    writeFileSync(p, JSON.stringify(manifest, null, 2), 'utf8');
+}

package/dist/services/polyrepo/polyrepo-scanner.d.ts

@@ -0,0 +1,9 @@
+import type { PolyrepoManifest } from './polyrepo-types.js';
+export interface ScanOptions {
+    /** Explicit list of child directory names (relative to root). When
+     *  provided, the scanner uses these instead of auto-discovery.
+     *  Matches the `peaks polyrepo init --children <dir1,dir2>` shape. */
+    readonly explicitChildren?: readonly string[];
+}
+/** Walk the parent root at depth 1 and return discovered children. */
+export declare function scanPolyrepo(root: string, opts?: ScanOptions): PolyrepoManifest;

package/dist/services/polyrepo/polyrepo-scanner.js

@@ -0,0 +1,94 @@
+/**
+ * Polyrepo scanner — slice S2-b of RD-2.
+ *
+ * Walks a parent directory looking for child git repos. A "child
+ * git repo" is defined as: a directory that contains a `.git`
+ * entry (file or directory — worktrees + submodules both qualify),
+ * is NOT the root itself, and sits at depth 1 from the root.
+ *
+ * Depth is intentionally bounded to 1 (per the PRD §4.3 model):
+ *   parent/
+ *     .peaks/
+ *     frontend/.git
+ *     backend/.git
+ * We do not recurse into nested monorepos in this slice — that is
+ * a future-slice concern.
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+function isGitRoot(dir) {
+    // A `.git` directory (normal repo) OR a `.git` file (worktree +
+    // submodule pointer) both count. statSync follows the pointer for
+    // a `.git` file, so the existence check is the same.
+    return existsSync(join(dir, '.git'));
+}
+function childHasPeaks(dir) {
+    return existsSync(join(dir, '.peaks'));
+}
+/** Sanitize a candidate child id: lowercase, dash-joined, no
+ *  leading dots or dashes. Used when the dir name itself is the id
+ *  (the common case). */
+function sanitizeId(name) {
+    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+}
+/** Walk the parent root at depth 1 and return discovered children. */
+export function scanPolyrepo(root, opts = {}) {
+    const absRoot = resolve(root);
+    if (!existsSync(absRoot)) {
+        throw new Error(`polyrepo root does not exist: ${absRoot}`);
+    }
+    const rootStat = statSync(absRoot);
+    if (!rootStat.isDirectory()) {
+        throw new Error(`polyrepo root is not a directory: ${absRoot}`);
+    }
+    const children = [];
+    if (opts.explicitChildren !== undefined && opts.explicitChildren.length > 0) {
+        // Explicit mode: only consider the named subdirs. This matches
+        // `peaks polyrepo init --children ./frontend,./backend`.
+        for (const name of opts.explicitChildren) {
+            const childPath = resolve(absRoot, name);
+            if (!existsSync(childPath)) {
+                throw new Error(`polyrepo child directory does not exist: ${childPath}`);
+            }
+            const s = statSync(childPath);
+            if (!s.isDirectory()) {
+                throw new Error(`polyrepo child path is not a directory: ${childPath}`);
+            }
+            children.push({
+                id: sanitizeId(basename(childPath)),
+                path: childPath,
+                gitRoot: isGitRoot(childPath),
+                peaksScope: childHasPeaks(childPath) ? 'root+child' : 'child-only',
+                peaksInstalled: childHasPeaks(childPath)
+            });
+        }
+    }
+    else {
+        // Auto-discovery mode: list immediate entries, filter to dirs with
+        // `.git`. This is intentionally narrow — see the file-level
+        // rationale at the top of this file.
+        const entries = readdirSync(absRoot, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith('.'))
+                continue; // skip .git, .peaks, .vscode, etc.
+            const childPath = join(absRoot, entry.name);
+            if (!isGitRoot(childPath))
+                continue;
+            children.push({
+                id: sanitizeId(entry.name),
+                path: childPath,
+                gitRoot: true,
+                peaksScope: childHasPeaks(childPath) ? 'root+child' : 'child-only',
+                peaksInstalled: childHasPeaks(childPath)
+            });
+        }
+    }
+    return {
+        version: 1,
+        root: absRoot,
+        detectedAt: new Date().toISOString(),
+        children
+    };
+}