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

package/dist/src/services/openspec/openspec-types.js

@@ -1 +0,0 @@
-export {};

package/dist/src/services/openspec/openspec-validate-service.d.ts

@@ -1,27 +0,0 @@
-import { type OpenSpecScanOptions } from './openspec-scan-service.js';
-export type OpenSpecValidationLevel = 'error' | 'warning';
-export type OpenSpecValidationIssue = {
-    level: OpenSpecValidationLevel;
-    rule: string;
-    message: string;
-};
-export type OpenSpecValidationSource = 'internal' | 'openspec-cli';
-export type OpenSpecValidationResult = {
-    changeId: string;
-    valid: boolean;
-    source: OpenSpecValidationSource;
-    issues: OpenSpecValidationIssue[];
-    cliOutput?: string;
-};
-export type ExternalRunnerOutcome = {
-    available: boolean;
-    exitCode: number | null;
-    stdout: string;
-    stderr: string;
-};
-export type ExternalRunner = (command: string, args: string[]) => Promise<ExternalRunnerOutcome>;
-export type OpenSpecValidateOptions = OpenSpecScanOptions & {
-    preferExternal?: boolean;
-    externalRunner?: ExternalRunner;
-};
-export declare function validateOpenSpecChange(changeId: string, options?: OpenSpecValidateOptions): Promise<OpenSpecValidationResult | null>;

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

@@ -1,77 +0,0 @@
-import { join } from 'node:path';
-import { isDirectory } from '../../shared/fs.js';
-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/src/services/perf/perf-baseline-service.d.ts

@@ -1,70 +0,0 @@
-/**
- * Performance baseline scaffolding for the RD stage.
- *
- * peaks-code's RD stage runs before the QA stage. The user-facing pain is
- * that performance tests (lighthouse / k6 / project-local benches / etc.)
- * have historically only been run at QA Gate A4 — too late in the loop,
- * because a slow regression discovered at QA triggers a return-to-rd
- * cycle, the RD ships another "fix", QA re-runs, and the same cycle
- * repeats up to 3 times before the slice ships.
- *
- * `peaks perf baseline` is the user-visible artifact of a deliberate
- * compromise: keep the heavy performance measurement as something the
- * RD runs themselves (lighthouse is project-shape dependent and we
- * don't want to bake a lighthouse dependency into the CLI), but capture
- * the result in a stable, scaffolded file under
- * `.peaks/_runtime/<sid>/rd/perf-baseline.md` so QA Gate A4 has a known-good
- * reference to diff against. The CLI itself only writes the scaffold
- * and records the path; the actual measurement is a project-local
- * concern that lives in the README, not in peaks-loop.
- *
- * The four-grounds check (per the skill-primary-CLI-auxiliary dev
- * preference):
- *   1. hook/script/CI invokability  — yes, a hook can call this CLI
- *                                     to scaffold the file on session
- *                                     init, similar to session bootstrap.
- *   2. JSON envelope that gates a downstream decision — yes,
- *                                     peaks-rd reads the result and
- *                                     attaches it to the handoff.
- *   3. Destructive --apply side effect — yes, default dry-run.
- *   4. Machine-enforced gate that prose cannot enforce — no, the
- *                                     measurement still lives in
- *                                     the LLM / project tools. We do
- *                                     NOT add a lint gate here.
- *
- * Net: CLI is justified. The destructive --apply default is dry-run,
- * matching the rest of peaks-loop's scaffolding pattern.
- */
-export type PerfBaselineInitOptions = {
-    projectRoot: string;
-    apply?: boolean;
-    reason?: string;
-};
-export type PerfBaselinePlan = {
-    apply: boolean;
-    projectRoot: string;
-    sessionId: string | null;
-    perfBaselinePath: string | null;
-    plannedWrites: Array<{
-        path: string;
-        kind: 'directory' | 'file';
-        bytes: number;
-        content: string;
-    }>;
-    alreadyInitialized: boolean;
-    existingFiles: string[];
-};
-export type PerfBaselineResult = PerfBaselinePlan & {
-    writtenFiles: string[];
-    createdDirectories: string[];
-    reason?: string;
-};
-export declare function executePerfBaselineInit(options: PerfBaselineInitOptions): Promise<PerfBaselineResult>;
-/**
- * Re-exported so the CLI command can fall back to a project-root
- * resolution when the caller did not pass --project. The CLI does
- * the same findProjectRoot walk that `workspace init` does; this
- * helper exists for the command layer to import without reaching
- * into config-safety directly.
- */
-export declare function resolveProjectRootFromCwd(cwd: string): string;

package/dist/src/services/perf/perf-baseline-service.js

@@ -1,214 +0,0 @@
-/**
- * Performance baseline scaffolding for the RD stage.
- *
- * peaks-code's RD stage runs before the QA stage. The user-facing pain is
- * that performance tests (lighthouse / k6 / project-local benches / etc.)
- * have historically only been run at QA Gate A4 — too late in the loop,
- * because a slow regression discovered at QA triggers a return-to-rd
- * cycle, the RD ships another "fix", QA re-runs, and the same cycle
- * repeats up to 3 times before the slice ships.
- *
- * `peaks perf baseline` is the user-visible artifact of a deliberate
- * compromise: keep the heavy performance measurement as something the
- * RD runs themselves (lighthouse is project-shape dependent and we
- * don't want to bake a lighthouse dependency into the CLI), but capture
- * the result in a stable, scaffolded file under
- * `.peaks/_runtime/<sid>/rd/perf-baseline.md` so QA Gate A4 has a known-good
- * reference to diff against. The CLI itself only writes the scaffold
- * and records the path; the actual measurement is a project-local
- * concern that lives in the README, not in peaks-loop.
- *
- * The four-grounds check (per the skill-primary-CLI-auxiliary dev
- * preference):
- *   1. hook/script/CI invokability  — yes, a hook can call this CLI
- *                                     to scaffold the file on session
- *                                     init, similar to session bootstrap.
- *   2. JSON envelope that gates a downstream decision — yes,
- *                                     peaks-rd reads the result and
- *                                     attaches it to the handoff.
- *   3. Destructive --apply side effect — yes, default dry-run.
- *   4. Machine-enforced gate that prose cannot enforce — no, the
- *                                     measurement still lives in
- *                                     the LLM / project tools. We do
- *                                     NOT add a lint gate here.
- *
- * Net: CLI is justified. The destructive --apply default is dry-run,
- * matching the rest of peaks-loop's scaffolding pattern.
- */
-import { mkdir, writeFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { getSessionId } from '../session/session-manager.js';
-import { getSessionDir } from '../session/getSessionDir.js';
-import { findProjectRoot } from '../config/config-safety.js';
-const README_BODY = `# Performance baseline
-
-> Scaffolding for the RD-side performance baseline. Created by
-> \`peaks perf baseline\`. The actual measurement is the RD's
-> responsibility — see the "How to fill this in" section below.
-
-## Why this exists
-
-The QA stage's Gate A4 (performance check) compares the slice's
-performance against the most recent baseline. Without an RD-side
-baseline, the first time Gate A4 runs it has nothing to compare
-against and any regression it finds is a blind-side surprise.
-Capturing the baseline at the RD stage — right after the
-implementation lands and before QA picks it up — closes that
-gap and prevents the "QA returns 3 times for the same perf
-regression" loop.
-
-## What to capture
-
-For each performance-sensitive code path in the slice, record:
-
-- **Path / route** — which entry point (page, hook, API) the
-  measurement targets.
-- **Workload** — what you did with it (cold load, hot loop, the
-  exact N of records the slice introduces).
-- **Tool** — lighthouse / k6 / autocannon / project-local bench
-  script. Match the tool to the workload; do not introduce a new
-  one if the project already has a benchmark script.
-- **Metrics** — at minimum LCP / FCP / TBT / CLS for frontend,
-  p50/p95/p99 latency + rps for backend, rss / heap growth
-  for long-running services.
-- **Baseline value** — the number you measured, with units.
-- **Threshold** — what the slice's PRD / acceptance criteria
-  consider acceptable. If the PRD does not specify, leave this
-  field as \`TBD (ask PM)\` and surface it in the RD handoff.
-
-## How to fill this in
-
-1. Run the project's chosen performance tool against the
-   implementation you just landed. If the project does not have
-   a tool yet, the lightest first step is the chrome devtools
-   performance tab on the touched route.
-2. For each metric, copy the row from "What to capture" into
-   the "Results" table below and fill in the number.
-3. The threshold is the bar QA Gate A4 will compare against.
-   Be conservative — if the threshold is tighter than what the
-   tool reports, Gate A4 will fail.
-
-## Results
-
-| Path / route | Workload | Tool | Metric | Baseline | Threshold |
-|---|---|---|---|---|---|
-|  |  |  |  |  |  |
-
-## Notes
-
-- If the slice is documentation-only or has no user-visible
-  performance surface, write \`N/A — no perf surface\` here and
-  surface that fact in the RD handoff.
-- If the measurement exceeded the threshold on the first run,
-  do NOT loosen the threshold to make it pass. The right move
-  is to optimise the implementation and re-measure, or to
-  surface the trade-off to the PRD owner for a threshold bump.
-
-## Handoff
-
-- to peaks-qa: the \`Results\` table is the input to Gate A4.
-  Without it QA cannot establish a comparison baseline.
-- to peaks-sc: any threshold bumps captured here belong in the
-  release notes if the threshold moved.
-`;
-function renderBaselineTemplate() {
-    return README_BODY;
-}
-function buildPlan(projectRoot, apply) {
-    const sessionId = getSessionId(projectRoot);
-    const sessionRoot = sessionId !== null
-        ? getSessionDir(projectRoot, sessionId)
-        : null;
-    const perfBaselinePath = sessionRoot !== null
-        ? join(sessionRoot, 'rd', 'perf-baseline.md')
-        : null;
-    const plannedWrites = [];
-    if (sessionRoot !== null && perfBaselinePath !== null) {
-        plannedWrites.push({
-            path: join(sessionRoot, 'rd'),
-            kind: 'directory',
-            bytes: 0,
-            content: ''
-        });
-        plannedWrites.push({
-            path: perfBaselinePath,
-            kind: 'file',
-            bytes: 0,
-            content: renderBaselineTemplate()
-        });
-        for (const write of plannedWrites) {
-            if (write.kind === 'file') {
-                write.bytes = Buffer.byteLength(write.content, 'utf8');
-            }
-        }
-    }
-    return {
-        apply,
-        projectRoot,
-        sessionId,
-        perfBaselinePath,
-        plannedWrites,
-        alreadyInitialized: false,
-        existingFiles: []
-    };
-}
-/**
- * Idempotency: skip writes for the perf-baseline file when it
- * already exists. Re-running `peaks perf baseline` on the same
- * session is a normal RD retry pattern (re-measurement, threshold
- * adjustment, etc.); we must not blow away hand-edited content.
- */
-async function planPerfBaselineInit(options) {
-    const plan = buildPlan(options.projectRoot, options.apply ?? false);
-    if (plan.perfBaselinePath !== null && existsSync(plan.perfBaselinePath)) {
-        plan.alreadyInitialized = true;
-        plan.existingFiles = [plan.perfBaselinePath];
-        plan.plannedWrites = [];
-    }
-    return plan;
-}
-export async function executePerfBaselineInit(options) {
-    const plan = await planPerfBaselineInit(options);
-    const writtenFiles = [];
-    const createdDirectories = [];
-    if (plan.sessionId === null) {
-        return {
-            ...plan,
-            ...(options.reason !== undefined ? { reason: options.reason } : {}),
-            writtenFiles,
-            createdDirectories
-        };
-    }
-    if (plan.apply && !plan.alreadyInitialized) {
-        for (const write of plan.plannedWrites) {
-            if (write.kind === 'directory') {
-                if (!existsSync(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,
-        ...(options.reason !== undefined ? { reason: options.reason } : {}),
-        writtenFiles,
-        createdDirectories
-    };
-}
-/**
- * Re-exported so the CLI command can fall back to a project-root
- * resolution when the caller did not pass --project. The CLI does
- * the same findProjectRoot walk that `workspace init` does; this
- * helper exists for the command layer to import without reaching
- * into config-safety directly.
- */
-export function resolveProjectRootFromCwd(cwd) {
-    return findProjectRoot(cwd) ?? cwd;
-}

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

@@ -1,34 +0,0 @@
-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/src/services/polyrepo/polyrepo-dispatcher.js

@@ -1,119 +0,0 @@
-/**
- * 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 {
-        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/src/services/polyrepo/polyrepo-scanner.d.ts

@@ -1,9 +0,0 @@
-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/src/services/polyrepo/polyrepo-scanner.js

@@ -1,94 +0,0 @@
-/**
- * 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
-    };
-}