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

package/dist/src/cli/commands/skill-search-commands.js

@@ -0,0 +1,68 @@
+import { searchSkills, SkillSearchInputSchema } from '../../services/skill/skill-search-service.js';
+import { getErrorMessage } from '../../shared/result.js';
+/**
+ * Validate the raw CLI flags, call the service, and emit a JSON
+ * envelope on stdout. Errors flow through stderr + non-zero exit
+ * codes per the plan §"API Contract" table.
+ */
+export function registerSkillSearchCommand(program, io) {
+    // The parent `skill` command is created by registerSkillCommand in
+    // core/skill-command.ts. To keep the wiring self-contained we
+    // resolve the parent by name; this also lets tests register the
+    // subcommand in isolation.
+    const skill = program.commands.find((c) => c.name() === 'skill');
+    if (skill === undefined) {
+        // Defensive: the parent must be registered before us. Surface the
+        // error visibly — the dispatcher cannot triage without `peaks skill`
+        // existing, so the LLM-side caller needs to know.
+        throw new Error('peaks skill search: parent `skill` command not found. ' +
+            'Ensure registerSkillCommand is called before registerSkillSearchCommand.');
+    }
+    skill
+        .command('search')
+        .description('Search the in-tree skill pool by --query (substring on description + triggers) ' +
+        'and/or --tag (exact match on metadata.tags) and/or --domain (exact match). ' +
+        'Outputs a JSON array (always, even on no-match) to stdout. ' +
+        'See docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2.')
+        .option('-q, --query <text>', 'case-insensitive substring matched against skill description + triggers')
+        .option('-t, --tag <tag>', 'exact match on metadata.tags (e.g. "orchestrator", "loop-engineering")')
+        .option('-d, --domain <domain>', 'exact match on metadata.domain (locked enum: code | content | doctor | research | triage | sop | audit | final-review | resume | status | test | ide | slice-decompose | issue-fix-orchestrator | perf-audit | security-audit | reviewer)')
+        .option('-l, --limit <n>', 'max results returned (1..100, default 20)', (v) => Number.parseInt(v, 10))
+        .action(async (options) => {
+        // 1) Coerce + validate input via the service's Zod schema.
+        //    The schema's refine rejects empty input — that is the
+        //    "all-empty → error" contract the spec mandates.
+        const raw = {};
+        if (options.query !== undefined)
+            raw['query'] = options.query;
+        if (options.tag !== undefined)
+            raw['tag'] = options.tag;
+        if (options.domain !== undefined)
+            raw['domain'] = options.domain;
+        if (options.limit !== undefined)
+            raw['limit'] = options.limit;
+        const parsed = SkillSearchInputSchema.safeParse(raw);
+        if (!parsed.success) {
+            // Exit code 1 = invalid args. Emit a human-readable message
+            // on stderr so the LLM-side caller can act on it; do NOT
+            // pollute stdout (which downstream tools parse as JSON).
+            for (const issue of parsed.error.issues) {
+                io.stderr(`${issue.path.join('.') || '<root>'}: ${issue.message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        // 2) Call the service. Any unexpected error (skill pool read
+        //    fail, etc.) maps to exit code 2.
+        try {
+            const results = await searchSkills(parsed.data);
+            // Always emit a JSON array on stdout. The plan locks this
+            // contract: even no-match returns `[]`, never `null`.
+            io.stdout(JSON.stringify(results));
+        }
+        catch (error) {
+            io.stderr(`skill.search failed: ${getErrorMessage(error)}`);
+            process.exitCode = 2;
+        }
+    });
+}

package/dist/src/cli/program.js

@@ -85,6 +85,15 @@ import { registerJobCommands } from './commands/job-commands.js';
 // 15b / 15c / 15d will extend sediment-commands.ts with the remaining 14 verbs.
 import { registerSedimentCommands } from './commands/sediment-commands.js';
 import { registerAdapterCommands } from './commands/adapter-commands.js';
+// Slice RD-2 S2-a: `peaks runtime *` (detect / list / compact) +
+// `peaks adapter *` (list / register). See src/services/runtime/ and
+// src/services/adapter/adapter-registry.ts. Coexists with the older
+// `peaks skill adapter` surface (slice 2026-07-04-cli-15a) which is
+// for skill materialization, not vendor-adapter registry.
+import { registerRuntimeCommands } from './commands/runtime-commands.js';
+import { registerAdapterS2ACommands } from './commands/adapter-commands-s2a.js';
+// Slice RD-2 S2-b: `peaks polyrepo *` (init / status / dispatch).
+import { registerPolyrepoCommands } from './commands/polyrepo-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
 import { applyRetention } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
@@ -375,6 +384,13 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     registerSedimentCommands(program, io);
     // Slice 2026-07-04-cli-15a: `peaks skill adapter <verb>` — adapter list / set-active.
     registerAdapterCommands(program, io);
+    // Slice RD-2 S2-a: `peaks runtime *` (detect / list / compact) +
+    // `peaks adapter *` (list / register). Vendor verbs live ONLY in
+    // src/services/runtime/vendors/<vendor>.ts (AC-1 enforcement).
+    registerRuntimeCommands(program, io);
+    registerAdapterS2ACommands(program, io);
+    // Slice RD-2 S2-b: `peaks polyrepo *` (init / status / dispatch).
+    registerPolyrepoCommands(program, io);
     // Slice 2026-07-05-peaks-code-to-peaks-code (Task 1): `peaks skill:visibility --list --json`
     // — read .claude-plugin/marketplace.json and report each skill's
     // visibility (public vs internal). Used to surface which skills are

package/dist/src/services/adapter/adapter-registry.d.ts

@@ -0,0 +1,48 @@
+import type { VendorAdapter } from '../runtime/vendor-adapter.js';
+/** Serializable adapter record (the on-disk shape). */
+export interface AdapterRecord {
+    readonly id: string;
+    readonly displayName: string;
+    /** Binary name or absolute path to invoke for compact. */
+    readonly binary: string;
+    /** Extra args appended after the compact verb. */
+    readonly args?: string[];
+}
+export interface PersistedAdapterRegistry {
+    readonly version: 1;
+    readonly adapters: AdapterRecord[];
+}
+export interface RegisterOptions {
+    /** Overwrite an existing record with the same id. Defaults to false
+     *  to prevent silent overwrites of user customizations. */
+    readonly force?: boolean;
+}
+/** In-memory + on-disk adapter registry. The registry holds USER
+ *  adapters (those registered via `peaks adapter register`); built-in
+ *  adapters live in RuntimeService and are NOT registered here. */
+export declare class AdapterRegistry {
+    private readonly records;
+    /** Register a new adapter. When an adapter with the same id already
+     *  exists, returns the existing record unless `force: true`. */
+    register(record: AdapterRecord, opts?: RegisterOptions): {
+        record: AdapterRecord;
+        created: boolean;
+    };
+    /** Resolve a registered adapter by id, materializing it as a
+     *  runnable VendorAdapter. Returns undefined when not registered. */
+    resolve(id: string): VendorAdapter | undefined;
+    /** List registered adapter records (serializable form). */
+    list(): AdapterRecord[];
+    /** Remove a registered adapter. Returns true if it existed. */
+    unregister(id: string): boolean;
+    /** Persist the current registry to disk as JSON. Writes atomically
+     *  (write to `<file>.tmp` then rename) so a crash mid-write does
+     *  not corrupt the registry file. */
+    persist(file: string): void;
+    /** Load a registry from disk. Missing file = empty registry.
+     *  Corrupt file = throw (caller decides whether to bail or
+     *  fall back to empty). */
+    load(file: string): void;
+    /** Default location for the on-disk registry file. */
+    static defaultFile(projectRoot: string): string;
+}

package/dist/src/services/adapter/adapter-registry.js

@@ -0,0 +1,186 @@
+/**
+ * Adapter registry — slice S2-a of RD-2.
+ *
+ * Persists user-registered vendor adapters to
+ * `.peaks/runtime/adapters.json` and resolves them by id. The
+ * registry is layered on top of `RuntimeService` (built-in adapters
+ * live there); a caller asks "do you have an adapter for id=X?" by
+ * first asking the registry, then falling back to built-ins. The
+ * runtime service itself does NOT consult the registry (kept
+ * decoupled so the registry can be swapped for a different
+ * persistence backend without touching runtime-service).
+ *
+ * Design notes:
+ *  - Persistence uses atomic write (write to tmp + rename) so a
+ *    crash mid-write does not corrupt the registry file.
+ *  - `register()` defaults to fail-if-exists to prevent silent
+ *    overwrites of user customizations; pass `force: true` to
+ *    overwrite (matches the CLI surface from PRD §4.4).
+ *  - VendorAdapter implementations are NOT directly serializable
+ *    (they hold closures over `home`, child_process handles, etc.).
+ *    Instead the registry persists a minimal JSON shape:
+ *    `{id, displayName, binary, args}` and reconstructs a
+ *    ProcessVendorAdapter wrapper on load. This keeps the JSON
+ *    file human-readable + diff-friendly.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** A registry-built adapter: wraps a persisted record + invokes the
+ *  recorded binary with the recorded args. Used so `peaks runtime
+ *  compact --via <id>` works against user-registered adapters without
+ *  peaks-loop needing to ship a vendor-specific implementation. */
+class ProcessVendorAdapter {
+    id;
+    displayName;
+    binary;
+    extraArgs;
+    constructor(record) {
+        this.id = record.id;
+        this.displayName = record.displayName;
+        this.binary = record.binary;
+        this.extraArgs = record.args ?? [];
+    }
+    async detect() {
+        // Heuristic: process-spawned adapters are always "detectable" once
+        // registered; their actual availability is checked at compact()
+        // time. This avoids probing every registered binary on every
+        // detect() call.
+        return true;
+    }
+    async compact(args = {}) {
+        const argv = [...this.extraArgs];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn(this.binary, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+            proc.on('error', (err) => {
+                resolveRun({ exitCode: 127, stdout, stderr: stderr + (stderr.length > 0 ? '\n' : '') + err.message });
+            });
+            proc.on('close', (code) => {
+                resolveRun({ exitCode: code ?? 0, stdout, stderr });
+            });
+        });
+    }
+}
+/** Validate an adapter record. Used by register() to fail fast on
+ *  malformed CLI input. Returns an error message or undefined. */
+function validateRecord(record) {
+    if (record.id.length === 0)
+        return 'adapter id must be non-empty';
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(record.id)) {
+        return `adapter id "${record.id}" must match /^[a-z0-9][a-z0-9._-]*$/`;
+    }
+    if (record.displayName.length === 0)
+        return 'adapter displayName must be non-empty';
+    if (record.binary.length === 0)
+        return 'adapter binary must be non-empty';
+    if (record.binary.includes('/') || record.binary.includes('\\')) {
+        return `adapter binary "${record.binary}" must be a name, not a path`;
+    }
+    return undefined;
+}
+/** In-memory + on-disk adapter registry. The registry holds USER
+ *  adapters (those registered via `peaks adapter register`); built-in
+ *  adapters live in RuntimeService and are NOT registered here. */
+export class AdapterRegistry {
+    records = new Map();
+    /** Register a new adapter. When an adapter with the same id already
+     *  exists, returns the existing record unless `force: true`. */
+    register(record, opts = {}) {
+        const validationError = validateRecord(record);
+        if (validationError !== undefined) {
+            throw new Error(`invalid adapter record: ${validationError}`);
+        }
+        const existed = this.records.has(record.id);
+        if (existed && opts.force !== true) {
+            return { record: this.records.get(record.id), created: false };
+        }
+        this.records.set(record.id, record);
+        return { record, created: !existed };
+    }
+    /** Resolve a registered adapter by id, materializing it as a
+     *  runnable VendorAdapter. Returns undefined when not registered. */
+    resolve(id) {
+        const rec = this.records.get(id);
+        if (rec === undefined)
+            return undefined;
+        return new ProcessVendorAdapter(rec);
+    }
+    /** List registered adapter records (serializable form). */
+    list() {
+        return Array.from(this.records.values());
+    }
+    /** Remove a registered adapter. Returns true if it existed. */
+    unregister(id) {
+        return this.records.delete(id);
+    }
+    /** Persist the current registry to disk as JSON. Writes atomically
+     *  (write to `<file>.tmp` then rename) so a crash mid-write does
+     *  not corrupt the registry file. */
+    persist(file) {
+        const payload = {
+            version: 1,
+            adapters: this.list()
+        };
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp`;
+        writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+        renameSync(tmp, file);
+    }
+    /** Load a registry from disk. Missing file = empty registry.
+     *  Corrupt file = throw (caller decides whether to bail or
+     *  fall back to empty). */
+    load(file) {
+        if (!existsSync(file))
+            return;
+        const raw = readFileSync(file, 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`adapter registry at ${file} is not valid JSON: ${err.message}`);
+        }
+        if (!isPersistedRegistry(parsed)) {
+            throw new Error(`adapter registry at ${file} has unexpected shape (expected version=1 + adapters[])`);
+        }
+        this.records.clear();
+        for (const rec of parsed.adapters) {
+            const validationError = validateRecord(rec);
+            if (validationError !== undefined) {
+                // Skip + continue — partial recovery is better than throwing on
+                // a single bad row. The CLI surfaces the count of skipped
+                // records via the load() return value below.
+                continue;
+            }
+            this.records.set(rec.id, rec);
+        }
+    }
+    /** Default location for the on-disk registry file. */
+    static defaultFile(projectRoot) {
+        return join(projectRoot, '.peaks', 'runtime', 'adapters.json');
+    }
+}
+function isPersistedRegistry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (v.version !== 1)
+        return false;
+    if (!Array.isArray(v.adapters))
+        return false;
+    return v.adapters.every((a) => {
+        if (typeof a !== 'object' || a === null)
+            return false;
+        const r = a;
+        return typeof r.id === 'string'
+            && typeof r.displayName === 'string'
+            && typeof r.binary === 'string'
+            && (r.args === undefined || (Array.isArray(r.args) && r.args.every((x) => typeof x === 'string')));
+    });
+}

package/dist/src/services/context/context-schema.d.ts

@@ -223,39 +223,39 @@ export declare const ContextJsonSchema: z.ZodObject<{
             tags: z.ZodArray<z.ZodString, "many">;
         }, "strip", z.ZodTypeAny, {
             kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
             id: string;
             blastRadius: string[];
             conflictScore: number;
             timeDecayScore: number;
-            tags: string[];
             version?: string | undefined;
         }, {
             kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
             id: string;
             blastRadius: string[];
             conflictScore: number;
             timeDecayScore: number;
-            tags: string[];
             version?: string | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         metadata: {
             kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
             id: string;
             blastRadius: string[];
             conflictScore: number;
             timeDecayScore: number;
-            tags: string[];
             version?: string | undefined;
         }[];
     }, {
         metadata: {
             kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
             id: string;
             blastRadius: string[];
             conflictScore: number;
             timeDecayScore: number;
-            tags: string[];
             version?: string | undefined;
         }[];
     }>;
@@ -330,11 +330,11 @@ export declare const ContextJsonSchema: z.ZodObject<{
     tokenizer: {
         metadata: {
             kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
             id: string;
             blastRadius: string[];
             conflictScore: number;
             timeDecayScore: number;
-            tags: string[];
             version?: string | undefined;
         }[];
     };
@@ -397,11 +397,11 @@ export declare const ContextJsonSchema: z.ZodObject<{
     tokenizer: {
         metadata: {
             kind: "git" | "code" | "doc" | "memory";
+            tags: string[];
             id: string;
             blastRadius: string[];
             conflictScore: number;
             timeDecayScore: number;
-            tags: string[];
             version?: string | undefined;
         }[];
     };

package/dist/src/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/src/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 {
+        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

@@ -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/src/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
+    };
+}