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

package/dist/src/services/dispatch/sub-agent-dispatcher.js

@@ -1,382 +0,0 @@
-/**
- * Slice #009 — SubAgentDispatcher abstraction.
- *
- * 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a) added `awaitBatch` per
- * dispatcher: claude-code holds an in-process promise queue; trae / trae-cn
- * / codex / cursor return an `awaitByLlm: true` marker for the calling
- * LLM to hold the await itself (real per-IDE implementations land in
- * slice 1.3). The `nullSubAgentDispatcher` throws.
- *
- * Per-IDE contract: given a sub-agent role + prompt + request/session ids,
- * return a tool-call descriptor that the calling LLM should execute in
- * its native environment. The CLI is IDE-agnostic; per-IDE tool names
- * (Claude Code's `Task`, Trae's UNVERIFIED placeholder) are encapsulated
- * here, never leaked to SKILL.md.
- *
- * Why this exists:
- * - Prior SKILL.md hardcoded `Task(subagent_type="general-purpose", ...)`
- * which made peaks-loop depend on Claude Code's specific sub-agent
- * tool name. Adding a new IDE (Trae, future Cursor, etc.) required
- * editing every SKILL.md that mentioned sub-agent dispatch.
- * - This file (plus the per-IDE adapter wiring) collapses all
- * per-IDE sub-agent specifics to a single `SubAgentDispatcher`
- * instance per adapter. SKILL.md now only references
- * `peaks sub-agent dispatch <role>`, and the IDE-private tool
- * name flows through the returned `data.toolCall` at runtime.
- *
- * Cross-reference: PRD #002 G1 (AC-1..AC-5); RD tech-doc-002 §2.
- */
-import { existsSync, readFileSync } from 'node:fs';
-/**
- * Claude Code dispatcher. Real, byte-level implementation.
- *
- * - `supportsRole`: any non-empty string (Claude Code's
- * `general-purpose` sub-agent accepts any prompt).
- * - `buildToolCall`: returns `{name: 'Task', args: {subagent_type,
- * description, prompt}}` — the exact shape the `Task` tool
- * in Claude Code expects.
- */
-export const claudeCodeSubAgentDispatcher = {
-    label: 'claude-code',
-    supportsRole: (role) => role.length > 0,
-    buildToolCall: ({ role, prompt, requestId }) => ({
-        name: 'Task',
-        args: {
-            subagent_type: 'general-purpose',
-            description: `${role} for rid=${requestId}`,
-            prompt,
-        },
-        // Slice 2026-06-23-audit-4th #C2: stamp the IDE-arg shape
-        // version. When Claude Code changes the Task args shape (e.g.
-        // a new subagent_type value), bump this and the dispatch record
-        // propagates it so a future reader can detect a stale record.
-        toolCallVersion: '2.0.0',
-    }),
-    // 2.7.0 slice-dag-dispatcher MVP: real join barrier for claude-code.
-    // The MVP harness uses an in-process promise queue keyed by batchId.
-    // (1.2 阶段进程内 hold 即可;1.3 / 1.4 阶段若多进程 sub-agent 走共享文件 / heartbeat 轮询。)
-    awaitBatch: async (input) => awaitClaudeCodeBatch(input),
-};
-/**
- * Trae dispatcher. UNVERIFIED — Trae sub-agent tool name TBD on real
- * dogfood. Byte-level identical to claude-code by design so:
- * - The dispatcher's return shape is uniform across both adapters
- * — a single byte-equality test can verify the placeholder
- * contract.
- * - Future real Trae dogfood can replace the body of
- * `buildToolCall` without breaking the adapter contract.
- *
- * Slice #014: the legacy `subAgentToolMatcher: 'Task'` install entry
- * is gone — the field is removed from `IdeAdapter`. Slice #009+
- * dispatched sub-agents directly, not via a PreToolUse hook. The Trae
- * dispatcher remains a placeholder so the dispatch surface is uniform
- * across adapters.
- *
- * When real Trae dogfood lands, replace the body of `buildToolCall`
- * with Trae's actual sub-agent tool name + args shape. The interface
- * stays the same; only the per-IDE wiring breaks (intentionally).
- */
-export const traeSubAgentDispatcher = {
-    // UNVERIFIED — see file header
-    label: 'trae',
-    supportsRole: (role) => role.length > 0,
-    buildToolCall: ({ role, prompt, requestId }) => ({
-        name: 'Task',
-        args: {
-            subagent_type: 'general-purpose',
-            description: `${role} for rid=${requestId}`,
-            prompt,
-        },
-        toolCallVersion: '2.0.0',
-    }),
-    // 2.7.0 slice-dag-dispatcher (slice 1.3): real file-polling awaitBatch
-    // for Trae. Per-IDE wrapper around `pollDispatchRecords` with the
-    // Trae-default heartbeat (30s). The fallback `awaitByLlm` marker is
-    // gone — Trae now joins like claude-code.
-    awaitBatch: async (input) => pollDispatchRecords(input, {
-        ide: 'trae',
-        defaultTimeoutMs: 30_000,
-        notePrefix: 'trae 1.3 real awaitBatch'
-    })
-};
-/**
- * Trae-CN dispatcher. Mirrors Trae's shape with a separate label so
- * the CLI's IDE detection can distinguish a Trae install region
- * (Trae-CN differs in skill install path / log location only;
- * dispatch surface is identical per slice #011 framework rule).
- *
- * Slice 1.3: real `awaitBatch` — same polling core as Trae.
- */
-export const traeCnSubAgentDispatcher = {
-    label: 'trae-cn',
-    supportsRole: (role) => role.length > 0,
-    buildToolCall: ({ role, prompt, requestId }) => ({
-        name: 'Task',
-        args: {
-            subagent_type: 'general-purpose',
-            description: `${role} for rid=${requestId}`,
-            prompt,
-        },
-    }),
-    awaitBatch: async (input) => pollDispatchRecords(input, {
-        ide: 'trae-cn',
-        defaultTimeoutMs: 30_000,
-        notePrefix: 'trae-cn 1.3 real awaitBatch'
-    })
-};
-/**
- * Codex (OpenAI CLI IDE) dispatcher.
- *
- * Slice #13 noted Codex's sub-agent tool name is TBD; per slice #009
- * rationale, the dispatcher mirrors Claude Code's shape so the
- * adapter contract stays uniform. Slice 1.3 promotes Codex from
- * `awaitByLlmFallback` to a real `awaitBatch` (file-based polling,
- * Codex default 45s — Codex's documented heartbeat is slightly
- * slower per slice #13 R-3).
- */
-export const codexSubAgentDispatcher = {
-    label: 'codex',
-    supportsRole: (role) => role.length > 0,
-    buildToolCall: ({ role, prompt, requestId }) => ({
-        name: 'Task',
-        args: {
-            subagent_type: 'general-purpose',
-            description: `${role} for rid=${requestId}`,
-            prompt,
-        },
-        toolCallVersion: '2.0.0',
-    }),
-    awaitBatch: async (input) => pollDispatchRecords(input, {
-        ide: 'codex',
-        defaultTimeoutMs: 45_000,
-        notePrefix: 'codex 1.3 real awaitBatch'
-    })
-};
-/**
- * Cursor dispatcher. UNVERIFIED — Cursor sub-agent tool name TBD on
- * real dogfood. Byte-level identical to claude-code by design (slice
- * #012 framing).
- *
- * Slice 1.3: real `awaitBatch` — file-based polling, Cursor default
- * 30s.
- */
-export const cursorSubAgentDispatcher = {
-    label: 'cursor',
-    supportsRole: (role) => role.length > 0,
-    buildToolCall: ({ role, prompt, requestId }) => ({
-        name: 'Task',
-        args: {
-            subagent_type: 'general-purpose',
-            description: `${role} for rid=${requestId}`,
-            prompt,
-        },
-        toolCallVersion: '2.0.0',
-    }),
-    awaitBatch: async (input) => pollDispatchRecords(input, {
-        ide: 'cursor',
-        defaultTimeoutMs: 30_000,
-        notePrefix: 'cursor 1.3 real awaitBatch'
-    })
-};
-/**
- * Null dispatcher for IDEs that cannot dispatch sub-agents at all
- * (e.g. a CLI-only IDE that has no LLM tool surface). Used as the
- * fallback by future unsupported-IDE adapters. The CLI returns
- * `{ok: false, code: "IDE_NOT_SUPPORTED"}` when the dispatcher's
- * `supportsRole` returns false.
- */
-export const nullSubAgentDispatcher = {
-    label: 'null',
-    supportsRole: () => false,
-    buildToolCall: ({ role }) => {
-        throw new SubAgentNotSupportedError(role);
-    },
-    // 2.7.0 slice-dag-dispatcher MVP: null dispatcher never supports await either.
-    awaitBatch: async ({ batchId }) => {
-        throw new SubAgentNotSupportedError(`awaitBatch on batch ${batchId}`);
-    },
-};
-/**
- * Thrown by `nullSubAgentDispatcher.buildToolCall` and any future
- * dispatcher that does not support a given role. The CLI catches
- * this and returns the IDE_NOT_SUPPORTED error envelope.
- */
-export class SubAgentNotSupportedError extends Error {
-    role;
-    code = 'IDE_NOT_SUPPORTED';
-    constructor(role) {
-        super(`Sub-agent dispatch is not supported for role: ${role}`);
-        this.role = role;
-        this.name = 'SubAgentNotSupportedError';
-    }
-}
-/* ──────────────────────────────────────────────────────────────────────────
- * 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a) — awaitBatch implementation
- * ────────────────────────────────────────────────────────────────────────── */
-/**
- * In-process LRU promise queue for claude-code. Keyed by batchId.
- * Populated by `awaitClaudeCodeBatch` callers; consumed by the same.
- * MVP-scope only: 1.3 / 1.4 may replace with cross-process heartbeat polling.
- */
-const claudeCodeBatchAwaiters = new Map();
-/**
- * Real awaitBatch for claude-code (MVP). In 1.2, dispatch + await are
- * both in the same process; we record the batch size and resolve after
- * `dispatchCount` heartbeats land for the given `recordPaths`, or after
- * `timeoutMs` elapses (per-dispatch `timeout` status).
- *
- * Implementation contract (MVP):
- *  - We poll each `recordPaths[i]` for an `outcome: success | failed` or
- *    `status: done | failed` field; if absent after `timeoutMs`, that
- *    dispatch is reported as `timeout`.
- *  - The poll interval is 50ms (fast enough for unit tests, cheap enough
- *    for the MVP; the real cross-process version uses heartbeat polling).
- */
-export async function awaitClaudeCodeBatch(input) {
-    const { batchId, dispatchCount, recordPaths, timeoutMs } = input;
-    if (dispatchCount <= 0 || recordPaths.length === 0) {
-        return [];
-    }
-    const startedAt = Date.now();
-    const pollIntervalMs = 50;
-    const deadline = timeoutMs ?? 60_000;
-    const capped = Math.min(deadline, 120_000);
-    // MVP: race the deadline against a simple polling loop. Real per-IDE
-    // implementations land in slice 1.3.
-    const results = [];
-    const remaining = new Map();
-    for (let i = 0; i < recordPaths.length; i += 1) {
-        const recordPath = recordPaths[i] ?? '';
-        remaining.set(i, { recordPath, status: 'timeout', note: null, finishedAt: null });
-    }
-    while (remaining.size > 0 && Date.now() - startedAt < capped) {
-        for (const [idx, slot] of remaining) {
-            if (slot.finishedAt !== null)
-                continue;
-            const outcome = readDispatchOutcome(slot.recordPath);
-            if (outcome === null)
-                continue;
-            slot.status = outcome.status;
-            slot.note = outcome.note;
-            slot.finishedAt = Date.now();
-        }
-        if (Array.from(remaining.values()).every((s) => s.finishedAt !== null))
-            break;
-        await new Promise((r) => setTimeout(r, pollIntervalMs));
-    }
-    for (const [idx, slot] of remaining) {
-        const finishedAt = slot.finishedAt ?? startedAt + capped;
-        results.push({
-            dispatchIndex: idx,
-            recordPath: slot.recordPath,
-            status: slot.status,
-            durationMs: finishedAt - startedAt,
-            note: slot.note
-        });
-    }
-    results.sort((a, b) => a.dispatchIndex - b.dispatchIndex);
-    // Touch batchId so the parameter is "used" — keeps the linter happy when
-    // the in-process queue (claudeCodeBatchAwaiters) is later wired up.
-    void batchId;
-    return results;
-}
-/** Best-effort outcome read for a dispatch record. Returns null if pending. */
-function readDispatchOutcome(recordPath) {
-    if (!recordPath)
-        return null;
-    try {
-        if (!existsSync(recordPath))
-            return null;
-        const raw = readFileSync(recordPath, 'utf8');
-        const obj = JSON.parse(raw);
-        const s = obj.status;
-        if (s === 'done' || s === 'success')
-            return { status: 'done', note: null };
-        if (s === 'failed')
-            return { status: 'failed', note: obj.outcome ?? null };
-        if (s === 'cancelled')
-            return { status: 'cancelled', note: null };
-        if (s === 'stale')
-            return { status: 'timeout', note: 'stale' };
-        return null;
-    }
-    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
-    }
-}
-export async function pollDispatchRecords(input, opts) {
-    const { dispatchCount, recordPaths, timeoutMs } = input;
-    if (dispatchCount <= 0 || recordPaths.length === 0) {
-        return [];
-    }
-    const startedAt = Date.now();
-    const pollIntervalMs = 50;
-    const deadline = timeoutMs ?? opts.defaultTimeoutMs;
-    const capped = Math.min(Math.max(deadline, 0), 120_000);
-    const results = [];
-    const remaining = new Map();
-    for (let i = 0; i < recordPaths.length; i += 1) {
-        const recordPath = recordPaths[i] ?? '';
-        remaining.set(i, { recordPath, status: 'timeout', note: null, finishedAt: null });
-    }
-    while (remaining.size > 0 && Date.now() - startedAt < capped) {
-        for (const [idx, slot] of remaining) {
-            if (slot.finishedAt !== null)
-                continue;
-            const outcome = readDispatchOutcome(slot.recordPath);
-            if (outcome === null)
-                continue;
-            slot.status = outcome.status;
-            slot.note = outcome.note;
-            slot.finishedAt = Date.now();
-        }
-        if (Array.from(remaining.values()).every((s) => s.finishedAt !== null))
-            break;
-        await new Promise((r) => setTimeout(r, pollIntervalMs));
-    }
-    for (const [idx, slot] of remaining) {
-        const finishedAt = slot.finishedAt ?? startedAt + capped;
-        const baseNote = slot.status === 'timeout' ? `${opts.notePrefix} (timeout)` : opts.notePrefix;
-        results.push({
-            dispatchIndex: idx,
-            recordPath: slot.recordPath,
-            status: slot.status,
-            durationMs: finishedAt - startedAt,
-            note: slot.note !== null ? `${baseNote} — ${slot.note}` : baseNote
-        });
-    }
-    results.sort((a, b) => a.dispatchIndex - b.dispatchIndex);
-    return results;
-}
-/**
- * 1.2 fallback for trae / trae-cn / codex / cursor. Deprecated by
- * slice 1.3 — kept exported for legacy callers + back-compat tests
- * (the 1.2 marker is still a valid envelope shape; the 1.4 dogfood
- * tests can compare the marker note vs the 1.3 real note to verify
- * per-IDE attribution).
- */
-export async function awaitByLlmFallback(input, ide) {
-    const startedAt = Date.now();
-    return input.recordPaths.map((p, i) => ({
-        dispatchIndex: i,
-        recordPath: p,
-        status: 'timeout',
-        durationMs: 0,
-        note: `awaitByLlm: ${ide} 1.2 fallback (real impl in 1.3)`
-    }));
-    void startedAt;
-}
-/**
- * In-process awaiter registration hook (used by `peaks sub-agent dispatch`
- * to attach a resolver; not part of the dispatcher public surface).
- * Reserved for slice 1.3 cross-process upgrade.
- */
-export function registerClaudeCodeAwaiter(batchId, awaiter) {
-    claudeCodeBatchAwaiters.set(batchId, awaiter);
-    // Soft cap: keep at most 32 batches in memory; drop the oldest.
-    if (claudeCodeBatchAwaiters.size > 32) {
-        const oldest = claudeCodeBatchAwaiters.keys().next().value;
-        if (oldest !== undefined)
-            claudeCodeBatchAwaiters.delete(oldest);
-    }
-}

package/dist/src/services/dispatch/test-tool-detection.d.ts

@@ -1,36 +0,0 @@
-/**
- * Slice 2026-06-24-test-tool-detection-injection.
- *
- * The Test Tool Detection block is prepended to every sub-agent prompt
- * dispatched by peaks-loop (both the single-dispatch chokepoint in
- * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
- * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
- * to read `package.json#scripts.test` first and use the project-local
- * runner — never `npx <runner>` — so it cannot bypass the lockfile or
- * spawn a network-bound tool call.
- *
- * Why a static constant (not a per-call detector):
- *  1. Predictable byte budget — the block is part of PROMPT_LIMIT_BYTES
- *     accounting (see dispatch-commands.ts line 113), and the size must
- *     be stable across calls.
- *  2. I/O-free — dispatch is a hot path; reading package.json here would
- *     add a filesystem hit per dispatch and run before the LLM has any
- *     context to act on the result.
- *  3. LLM does runtime lookup — the block itself instructs the sub-agent
- *     to introspect `package.json#scripts.test` (or `peaks test --json`)
- *     at run time, so the LLM gets the resolved framework + argv with
- *     its full context. The dispatch CLI just primes the instruction.
- *
- * Why every sub-agent gets the block (Karpathy #2 Simplicity First):
- *  the rule is machine-injected, not a prompt ritual. The LLM cannot
- *  "remove the redundancy" of a test-tool-detection instruction because
- *  the dispatch CLI always prepends it. This is a guarantee, not a
- *  suggestion.
- */
-export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nBefore running any test, read `package.json#scripts.test` to identify the project's test framework. Use the project-local runner \u2014 do NOT invoke `npx <runner>`:\n\n- **vitest** \u2192 `./node_modules/.bin/vitest run <file>` (or `pnpm test -- <file>`)\n- **jest**   \u2192 `./node_modules/.bin/jest <file>`   (or `pnpm test -- <file>`)\n- **mocha**  \u2192 `./node_modules/.bin/mocha <file>`  (or `pnpm test -- <file>`)\n\nIf unsure which framework the consumer project uses, run `peaks test --json` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command `peaks test <file>` already resolves the local binary for you (Windows-aware).";
-/**
- * Pure helper that returns the block. Exists as a function (not just an
- * exported constant) so future variants can take a runtime parameter
- * (e.g. projectRoot for context) without churning every call site.
- */
-export declare function formatTestToolDetection(): string;

package/dist/src/services/dispatch/test-tool-detection.js

@@ -1,46 +0,0 @@
-/**
- * Slice 2026-06-24-test-tool-detection-injection.
- *
- * The Test Tool Detection block is prepended to every sub-agent prompt
- * dispatched by peaks-loop (both the single-dispatch chokepoint in
- * `src/cli/commands/dispatch-commands.ts` and the DAG-dispatch chokepoint
- * in `src/services/code/dag-orchestrator.ts`). It tells the sub-agent
- * to read `package.json#scripts.test` first and use the project-local
- * runner — never `npx <runner>` — so it cannot bypass the lockfile or
- * spawn a network-bound tool call.
- *
- * Why a static constant (not a per-call detector):
- *  1. Predictable byte budget — the block is part of PROMPT_LIMIT_BYTES
- *     accounting (see dispatch-commands.ts line 113), and the size must
- *     be stable across calls.
- *  2. I/O-free — dispatch is a hot path; reading package.json here would
- *     add a filesystem hit per dispatch and run before the LLM has any
- *     context to act on the result.
- *  3. LLM does runtime lookup — the block itself instructs the sub-agent
- *     to introspect `package.json#scripts.test` (or `peaks test --json`)
- *     at run time, so the LLM gets the resolved framework + argv with
- *     its full context. The dispatch CLI just primes the instruction.
- *
- * Why every sub-agent gets the block (Karpathy #2 Simplicity First):
- *  the rule is machine-injected, not a prompt ritual. The LLM cannot
- *  "remove the redundancy" of a test-tool-detection instruction because
- *  the dispatch CLI always prepends it. This is a guarantee, not a
- *  suggestion.
- */
-export const TEST_TOOL_DETECTION_BLOCK = `## Test Tool Detection (mandatory)
-
-Before running any test, read \`package.json#scripts.test\` to identify the project's test framework. Use the project-local runner — do NOT invoke \`npx <runner>\`:
-
-- **vitest** → \`./node_modules/.bin/vitest run <file>\` (or \`pnpm test -- <file>\`)
-- **jest**   → \`./node_modules/.bin/jest <file>\`   (or \`pnpm test -- <file>\`)
-- **mocha**  → \`./node_modules/.bin/mocha <file>\`  (or \`pnpm test -- <file>\`)
-
-If unsure which framework the consumer project uses, run \`peaks test --json\` first to introspect the resolved framework + argv. Only as a last resort, ask the user before assuming a runner. The CLI command \`peaks test <file>\` already resolves the local binary for you (Windows-aware).`;
-/**
- * Pure helper that returns the block. Exists as a function (not just an
- * exported constant) so future variants can take a runtime parameter
- * (e.g. projectRoot for context) without churning every call site.
- */
-export function formatTestToolDetection() {
-    return TEST_TOOL_DETECTION_BLOCK;
-}

package/dist/src/services/doc/doc-generator.d.ts

@@ -1,38 +0,0 @@
-/**
- * v2.15.0 follow-up — G7: documentation auto-generator.
- *
- * Two CLI surfaces:
- *   1. `peaks doc generate-skill --from <code-path>` — produces a SKILL.md
- *      skeleton by scanning a code directory for command exports,
- *      with sections derived from JSDoc / signature.
- *   2. `peaks doc changelog-suggest --since <git-ref>` — diffs
- *      src/cli/commands/*.ts since the ref and emits a
- *      "## [Unreleased]" block describing the changes.
- *
- * Both are pragmatic / 80% solutions; the goal is to make the operator's
- * life easier, not to fully automate documentation.
- */
-export interface SkillSection {
-    readonly heading: string;
-    readonly bullets: readonly string[];
-}
-export interface SkillDoc {
-    readonly name: string;
-    readonly description: string;
-    readonly sections: readonly SkillSection[];
-}
-/** Generate a SKILL.md skeleton from a directory of CLI command files. */
-export declare function generateSkillFromCommands(skillName: string, commandsDir: string): SkillDoc;
-/** Render SkillDoc as markdown. */
-export declare function renderSkillMarkdown(doc: SkillDoc): string;
-export interface ChangelogEntry {
-    readonly kind: 'feat' | 'fix' | 'docs' | 'refactor' | 'chore';
-    readonly subject: string;
-    readonly file: string;
-}
-/** Parse a single commit subject line into a ChangelogEntry. */
-export declare function parseCommitSubject(subject: string, file: string): ChangelogEntry;
-/** Run `git log` for the given ref range, return parsed entries. */
-export declare function gitLogSince(projectRoot: string, since: string): ChangelogEntry[];
-/** Group entries by kind + render a "## [Unreleased]" block. */
-export declare function suggestChangelog(entries: readonly ChangelogEntry[]): string;

package/dist/src/services/doc/doc-generator.js

@@ -1,122 +0,0 @@
-/**
- * v2.15.0 follow-up — G7: documentation auto-generator.
- *
- * Two CLI surfaces:
- *   1. `peaks doc generate-skill --from <code-path>` — produces a SKILL.md
- *      skeleton by scanning a code directory for command exports,
- *      with sections derived from JSDoc / signature.
- *   2. `peaks doc changelog-suggest --since <git-ref>` — diffs
- *      src/cli/commands/*.ts since the ref and emits a
- *      "## [Unreleased]" block describing the changes.
- *
- * Both are pragmatic / 80% solutions; the goal is to make the operator's
- * life easier, not to fully automate documentation.
- */
-import { readFileSync, readdirSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-const COMMAND_PATTERN = /program\s*\.\s*command\(\s*['"]([^'"]+)['"]/g;
-const DESC_PATTERN = /\.description\(\s*['"]([^'"]+)['"]\)/g;
-/** Generate a SKILL.md skeleton from a directory of CLI command files. */
-export function generateSkillFromCommands(skillName, commandsDir) {
-    const sections = [];
-    let description = `Auto-generated SKILL.md skeleton for ${skillName}.`;
-    if (!existsSync(commandsDir)) {
-        return { name: skillName, description, sections: [] };
-    }
-    const commandMap = new Map();
-    for (const file of readdirSync(commandsDir)) {
-        if (!file.endsWith('.ts') && !file.endsWith('.js'))
-            continue;
-        const path = join(commandsDir, file);
-        let content;
-        try {
-            content = readFileSync(path, 'utf8');
-        }
-        catch {
-            continue;
-        }
-        const commands = [...content.matchAll(COMMAND_PATTERN)].map((m) => m[1]).filter((c) => c.length > 0);
-        const descs = [...content.matchAll(DESC_PATTERN)].map((m) => m[1]);
-        for (const cmd of commands) {
-            if (!commandMap.has(cmd))
-                commandMap.set(cmd, []);
-            commandMap.get(cmd).push(descs[0] ?? '(no description)');
-        }
-    }
-    if (commandMap.size === 0) {
-        return { name: skillName, description, sections: [] };
-    }
-    const bullets = [];
-    let firstDescription = null;
-    for (const [cmd, descs] of [...commandMap.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-        const desc = descs[0] ?? '(no description)';
-        bullets.push(`- \`peaks ${cmd}\` — ${desc}`);
-        if (firstDescription === null)
-            firstDescription = desc;
-    }
-    sections.push({ heading: 'Commands', bullets });
-    if (firstDescription !== null) {
-        description = firstDescription.slice(0, 200);
-    }
-    return { name: skillName, description, sections };
-}
-/** Render SkillDoc as markdown. */
-export function renderSkillMarkdown(doc) {
-    const lines = [];
-    lines.push(`# ${doc.name}`);
-    lines.push('');
-    lines.push(doc.description);
-    lines.push('');
-    for (const sec of doc.sections) {
-        lines.push(`## ${sec.heading}`);
-        lines.push('');
-        for (const b of sec.bullets)
-            lines.push(b);
-        lines.push('');
-    }
-    return lines.join('\n');
-}
-/** Parse a single commit subject line into a ChangelogEntry. */
-export function parseCommitSubject(subject, file) {
-    const conventionalMatch = /^(feat|fix|docs|refactor|chore)(?:\([^)]+\))?:\s*(.+)$/i.exec(subject);
-    if (conventionalMatch) {
-        return { kind: conventionalMatch[1].toLowerCase(), subject: conventionalMatch[2].trim(), file };
-    }
-    return { kind: 'chore', subject, file };
-}
-/** Run `git log` for the given ref range, return parsed entries. */
-export function gitLogSince(projectRoot, since) {
-    try {
-        const out = execSync(`git log --pretty=format:"%s" ${since}..HEAD`, {
-            cwd: projectRoot,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore']
-        });
-        if (out.trim().length === 0)
-            return [];
-        return out.split('\n').filter((s) => s.length > 0).map((s) => parseCommitSubject(s, 'git log'));
-    }
-    catch {
-        return [];
-    }
-}
-/** Group entries by kind + render a "## [Unreleased]" block. */
-export function suggestChangelog(entries) {
-    if (entries.length === 0)
-        return '## [Unreleased]\n\n(no changes since the reference)';
-    const groups = { feat: [], fix: [], docs: [], refactor: [], chore: [] };
-    for (const e of entries)
-        groups[e.kind].push(e);
-    const lines = ['## [Unreleased]', ''];
-    for (const k of ['feat', 'fix', 'refactor', 'docs', 'chore']) {
-        if (groups[k].length === 0)
-            continue;
-        lines.push(`### ${k.charAt(0).toUpperCase() + k.slice(1)}`);
-        lines.push('');
-        for (const e of groups[k])
-            lines.push(`- ${e.subject}`);
-        lines.push('');
-    }
-    return lines.join('\n');
-}