peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/services/share/run-state-contract.js

@@ -0,0 +1,138 @@
+/**
+ * run-state-contract.ts — locked read-only shape for the desktop
+ * client (spec §7A.3 / §10 RL-9).
+ *
+ * The desktop client observes an in-flight bee through a single
+ * JSON file. This module locks the shape so the desktop can render
+ * progress without holding a lock on the asset:
+ *
+ *   {
+ *     bee_id:                    string,
+ *     status:                    "running" | "paused" | "done" | "failed" | "blocked",
+ *     current_step:              string,
+ *     started_at:                ISO8601 string,
+ *     updated_at:                ISO8601 string,
+ *     last_evaluator_verdict:    string | null,
+ *     last_user_choice:          string | null
+ *   }
+ *
+ * Hard rules (spec §7A.3):
+ *   - The contract is read-only for the desktop client. Only the
+ *     running bee (and peaks CLI) may write it.
+ *   - The shape is locked — adding a field is a schema-version
+ *     bump; removing or renaming a field is a breaking change.
+ *
+ * This module exposes:
+ *   - A Zod schema (`RunStateContractSchema`) that validates the
+ *     shape with strict rules (no extra keys, exact enum for
+ *     status).
+ *   - A type alias (`RunStateContract`).
+ *   - A constructor-like factory (for testing / fixtures).
+ *
+ * It does NOT expose any mutation helpers — there are no setters,
+ * because the contract is read-only at the desktop. The running
+ * bee writes the file via the existing dispatch flow; the desktop
+ * client reads via a separate channel.
+ */
+import { z } from "zod";
+/* ---------------------------------------------------------------------- */
+/* Shape contract                                                            */
+/* ---------------------------------------------------------------------- */
+/**
+ * The five status values an in-flight bee may report. The
+ * desktop-client UI renders the status badge; only the running bee
+ * transitions between them.
+ */
+export const RUN_STATE_STATUSES = [
+    "running",
+    "paused",
+    "done",
+    "failed",
+    "blocked",
+];
+/**
+ * RunStateContract — the locked read-only shape (spec §7A.3).
+ *
+ * Notes:
+ *   - `bee_id`, `current_step`: non-empty NL strings.
+ *   - `started_at`, `updated_at`: ISO8601; updated_at >= started_at
+ *     is the caller's job (the schema does not check ordering
+ *     because a clock skew between the dispatcher and the receiver
+ *     is a transient runtime issue, not a shape invariant).
+ *   - `last_evaluator_verdict`: optional NL string; null when no
+ *     evaluator has fired yet.
+ *   - `last_user_choice`: optional NL choice summary; null when
+ *     the user has not made a pick yet.
+ *
+ * `.strict()` rejects unknown keys — adding a field is a
+ * schema-version bump, not a quiet extension.
+ */
+export const RunStateContractSchema = z
+    .object({
+    /** Stable bee id (kebab-case). */
+    bee_id: z.string().min(1).max(64),
+    /** Current run status (running / paused / done / failed / blocked). */
+    status: z.enum(RUN_STATE_STATUSES),
+    /** Current step name; NL short label. */
+    current_step: z.string().min(1).max(256),
+    /** ISO8601 timestamp the run started. */
+    started_at: z.string().datetime(),
+    /** ISO8601 timestamp of the latest update. */
+    updated_at: z.string().datetime(),
+    /** NL summary of the latest evaluator verdict (or null when none). */
+    last_evaluator_verdict: z.string().max(4000).nullable(),
+    /** NL summary of the latest user choice (or null when none). */
+    last_user_choice: z.string().max(4000).nullable(),
+})
+    .strict();
+/* ---------------------------------------------------------------------- */
+/* Validation helpers (read-only at the surface)                              */
+/* ---------------------------------------------------------------------- */
+/**
+ * Strict-parse an unknown value as a RunStateContract. Throws
+ * `ZodError` on failure. The desktop client uses this at the read
+ * boundary; the running bee writes the file via the existing
+ * dispatch flow (separate write path).
+ */
+export function parseRunStateContract(input) {
+    return RunStateContractSchema.parse(input);
+}
+/**
+ * Safe-parse twin — same Result-like envelope shape used elsewhere.
+ */
+export function safeParseRunStateContract(input) {
+    const r = RunStateContractSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, contract: r.data };
+    return {
+        ok: false,
+        findings: r.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        })),
+    };
+}
+/* ---------------------------------------------------------------------- */
+/* Server-side writer (used by the dispatch flow)                            */
+/* ---------------------------------------------------------------------- */
+/**
+ * Server-side factory used by the dispatch flow to write the file.
+ * This helper is exported for testing purposes; the desktop client
+ * is read-only and SHOULD NOT call this.
+ *
+ * The function returns a brand-new `RunStateContract` value; it
+ * does NOT mutate any external state. Persistence is the caller's
+ * responsibility (the dispatch flow writes a JSON file at a
+ * well-known path under `.peaks/_runtime/<sid>/<role>/`).
+ */
+export function buildRunState(args) {
+    return RunStateContractSchema.parse({
+        bee_id: args.bee_id,
+        status: args.status,
+        current_step: args.current_step,
+        started_at: args.started_at,
+        updated_at: args.updated_at,
+        last_evaluator_verdict: args.last_evaluator_verdict ?? null,
+        last_user_choice: args.last_user_choice ?? null,
+    });
+}

package/dist/services/signal/cancel-handler.js

@@ -0,0 +1,76 @@
+/**
+ * Slice #009 / G5 RL-9 — user cancel must dispose in-flight dispatch records.
+ *
+ * When Code's main loop receives SIGINT (Ctrl-C) or the user runs
+ * `peaks workflow cancel --rid <rid>`, the loop MUST mark in-flight
+ * dispatch records as `outcome: "cancelled"` + `disposed: true` +
+ * `disposedAt: now()` BEFORE exiting.
+ *
+ * "In-flight" = a record with `createdAt` populated AND
+ * `completedAt: null`. Those are the ones that the LLM got a toolCall
+ * for but did not (yet) confirm completion.
+ *
+ * This module is the helper Code calls. The wiring (signal listener,
+ * cancel command side-effect) is the Code main loop's responsibility;
+ * this module is the pure data operation.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const CANCELLED_OUTCOME = 'cancelled';
+const CANCELLED_STATUS = 'cancelled';
+/**
+ * Walk `.peaks/_sub_agents/<sid>/`, mark every in-flight record as
+ * `cancelled + disposed`, write back atomically (tmp + rename), and
+ * return the count. Records that already have `completedAt` set are
+ * skipped (they were already finished by the time cancel fired).
+ */
+export function cancelInFlightDispatches(projectRoot, sessionId, options = {}) {
+    const now = options.now ?? (() => new Date());
+    const dir = join(projectRoot, '.peaks', '_sub_agents', sessionId);
+    if (!existsSync(dir)) {
+        return { cancelled: 0, scanned: 0, paths: [] };
+    }
+    let scanned = 0;
+    const cancelledPaths = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.startsWith('dispatch-') || !entry.endsWith('.json'))
+            continue;
+        const fullPath = join(dir, entry);
+        scanned += 1;
+        const record = readRecordOrNull(fullPath);
+        if (record === null)
+            continue;
+        if (record.completedAt !== null)
+            continue; // already finished
+        const cancelled = {
+            ...record,
+            completedAt: now().toISOString(),
+            outcome: CANCELLED_OUTCOME,
+            status: CANCELLED_STATUS,
+            disposed: true,
+            disposedAt: now().toISOString()
+        };
+        writeFileSync(fullPath, JSON.stringify(cancelled, null, 2) + '\n', 'utf8');
+        cancelledPaths.push(fullPath);
+    }
+    return { cancelled: cancelledPaths.length, scanned, paths: cancelledPaths };
+}
+function readRecordOrNull(path) {
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        const obj = parsed;
+        if (typeof obj.createdAt !== 'string')
+            return null;
+        if (typeof obj.completedAt !== 'string' && obj.completedAt !== null)
+            return null;
+        if (typeof obj.role !== 'string')
+            return null;
+        return obj;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

package/dist/services/skill/resume-detector.js

@@ -0,0 +1,334 @@
+/**
+ * Peaks-Loop Code Step 0.7 — Resume-mode detector.
+ *
+ * Mirrors the classification table in
+ * `skills/peaks-code/SKILL.md` "Peaks-Loop Step 0.7: Detect unfinished work
+ * and offer resume". The function is a pure read of session artifacts;
+ * it performs no side effects and is safe to call from hooks, scripts,
+ * and skills.
+ *
+ * Two classification sources are merged:
+ *   1. State-based (PRD / RD / QA request artifact `state:` field) →
+ *      determines the *deepest completed gate*.
+ *   2. File-presence ("Other resume triggers" table) → if a required
+ *      artifact is missing for a gate that state says is complete, the
+ *      classifier emits a `resume:<earlier-point>` verdict AND a
+ *      `warnings[]` entry flagging the inconsistency.
+ *
+ * Primary vs. abandoned filter: when multiple RD/QA request artifacts
+ * exist for the same session (the 8-slice governance pass leaves
+ * `deferred`/`abandoned` artifacts alongside the active one), the
+ * classifier filters out files whose `state: blocked` field is paired
+ * with a `user-requested-abandon` transition note. The remaining
+ * artifacts are sorted by filename (alphabetical) and the first is the
+ * primary.
+ *
+ * Legacy path fallback: prefers the canonical
+ * `.peaks/_runtime/<sid>/` layout introduced in slice
+ * `2026-06-05-peaks-runtime-layer`; falls back to the pre-migration
+ * `.peaks/_runtime/<sid>/` for one minor release so older trees do not show as
+ * false "fresh". The `usedLegacyPath` field reports which path was
+ * read.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const MID_IMPL_RD_STATES = new Set([
+    'spec-locked',
+    'implemented',
+    'running',
+    'blocked'
+]);
+/**
+ * Classify a session's resume state. Pure function — does not write
+ * files, does not call any peaks CLI.
+ *
+ * @param sid        The session id (e.g. `2026-06-06-session-22f08c`).
+ * @param peaksRoot  The canonical peaks runtime root, i.e. the
+ *                   directory containing `<sid>/` subdirs. For the
+ *                   v1.3.2 layout this is `<repo>/.peaks/_runtime`.
+ *                   The legacy `<repo>/.peaks` layout is also accepted
+ *                   for one minor release (see `usedLegacyPath`).
+ */
+export function classifyResume(sid, peaksRoot) {
+    const resolved = resolveSessionDir(sid, peaksRoot);
+    if (resolved === null) {
+        return {
+            kind: 'fresh',
+            point: null,
+            state: null,
+            missingArtifacts: [],
+            warnings: [],
+            abandonedRequestCount: 0,
+            usedLegacyPath: false
+        };
+    }
+    const { sessionDir, usedLegacyPath } = resolved;
+    const prdStates = readRequestStates(sessionDir, 'prd');
+    const rdStatesRaw = readRequestStates(sessionDir, 'rd');
+    const qaStatesRaw = readRequestStates(sessionDir, 'qa');
+    // Filter abandoned (state=blocked + user-requested-abandon note).
+    const abandonedRd = rdStatesRaw.filter((s) => s.abandoned);
+    const abandonedQa = qaStatesRaw.filter((s) => s.abandoned);
+    const abandonedCount = abandonedRd.length + abandonedQa.length;
+    // Primary selection filter: when there are MULTIPLE RD/QA requests,
+    // the abandoned ones are excluded from the candidate set so the
+    // classifier surfaces the active slice, not the audit-only trail.
+    // When there is only ONE request, the abandoned flag is informational
+    // only — a single blocked RD with an abandoned note is still the
+    // primary, because the user might want to unblock and continue.
+    const rdStates = rdStatesRaw.length > 1 ? rdStatesRaw.filter((s) => !s.abandoned) : rdStatesRaw;
+    const qaStates = qaStatesRaw.length > 1 ? qaStatesRaw.filter((s) => !s.abandoned) : qaStatesRaw;
+    const primaryPrd = pickPrimary(prdStates);
+    const primaryRd = pickPrimary(rdStates);
+    const primaryQa = pickPrimary(qaStates);
+    // Phase 1: TXT handoff present → workflow complete. Always wins.
+    if (existsSync(join(sessionDir, 'txt', 'handoff.md'))) {
+        return {
+            kind: 'complete',
+            point: null,
+            state: null,
+            missingArtifacts: [],
+            warnings: [],
+            abandonedRequestCount: abandonedCount,
+            usedLegacyPath
+        };
+    }
+    // Phase 2: every RD/QA request is abandoned (filtered out) AND
+    // there were multiple to begin with. The slice is effectively
+    // dead — return fresh so the user can start over without
+    // re-attaching to the abandoned work.
+    if (primaryRd === null &&
+        primaryQa === null &&
+        abandonedCount > 0 &&
+        (rdStatesRaw.length > 1 || qaStatesRaw.length > 1)) {
+        return {
+            kind: 'fresh',
+            point: null,
+            state: null,
+            missingArtifacts: [],
+            warnings: [],
+            abandonedRequestCount: abandonedCount,
+            usedLegacyPath
+        };
+    }
+    // Phase 3: mid-implementation RD states (spec-locked / implemented /
+    // running / blocked). Wins over the PRD-handed-off branch because
+    // the slice IS in flight — the LLM should not be told to "re-run
+    // the swarm" when an RD artifact is already mid-edit.
+    if (primaryRd !== null && MID_IMPL_RD_STATES.has(primaryRd.state)) {
+        return {
+            kind: 'in-flight',
+            point: null,
+            state: primaryRd.state,
+            missingArtifacts: [],
+            warnings: [],
+            abandonedRequestCount: abandonedCount,
+            usedLegacyPath
+        };
+    }
+    // Phase 4: terminal gates (QA verdict-issued / RD qa-handoff / PRD
+    // handed-off, with file-presence overrides).
+    const terminal = classifyTerminalGates(sessionDir, {
+        primaryPrd,
+        primaryRd,
+        primaryQa,
+        usedLegacyPath,
+        abandonedCount
+    });
+    if (terminal !== null)
+        return terminal;
+    // Phase 5: PRD exists with a non-handed-off state — treat as
+    // in-flight:spec-locked placeholder. The user can confirm whether
+    // they want to advance the PRD or start fresh.
+    if (primaryPrd !== null && primaryPrd.state.length > 0) {
+        return {
+            kind: 'in-flight',
+            point: null,
+            state: 'spec-locked',
+            missingArtifacts: [],
+            warnings: [],
+            abandonedRequestCount: abandonedCount,
+            usedLegacyPath
+        };
+    }
+    return {
+        kind: 'fresh',
+        point: null,
+        state: null,
+        missingArtifacts: [],
+        warnings: [],
+        abandonedRequestCount: abandonedCount,
+        usedLegacyPath
+    };
+}
+function classifyTerminalGates(sessionDir, ctx) {
+    // QA verdict-issued → deepest gate is D. If the test-report is
+    // missing the state is inconsistent; fall back to qa-execution.
+    if (ctx.primaryQa !== null && ctx.primaryQa.state === 'verdict-issued') {
+        const reportPath = join(sessionDir, 'qa', 'test-reports', ctx.primaryQa.filename);
+        if (!existsSync(reportPath)) {
+            return {
+                kind: 'resume',
+                point: 'qa-execution',
+                state: null,
+                missingArtifacts: [`qa/test-reports/${ctx.primaryQa.filename}`],
+                warnings: [
+                    'inconsistent: qa verdict-issued but no qa/test-reports/<rid>.md; CLI gate should have blocked the transition'
+                ],
+                abandonedRequestCount: ctx.abandonedCount,
+                usedLegacyPath: ctx.usedLegacyPath
+            };
+        }
+        return {
+            kind: 'resume',
+            point: 'txt-handoff',
+            state: null,
+            missingArtifacts: ['txt/handoff.md'],
+            warnings: [],
+            abandonedRequestCount: ctx.abandonedCount,
+            usedLegacyPath: ctx.usedLegacyPath
+        };
+    }
+    // RD qa-handoff → deepest gate is C. If the review artifacts are
+    // missing the state is inconsistent; fall back to rd-review-fanout.
+    if (ctx.primaryRd !== null && ctx.primaryRd.state === 'qa-handoff') {
+        const codeReviewPath = join(sessionDir, 'rd', 'code-review.md');
+        const securityReviewPath = join(sessionDir, 'rd', 'security-review.md');
+        const missing = [];
+        if (!existsSync(codeReviewPath))
+            missing.push('rd/code-review.md');
+        if (!existsSync(securityReviewPath))
+            missing.push('rd/security-review.md');
+        if (missing.length > 0) {
+            return {
+                kind: 'resume',
+                point: 'rd-review-fanout',
+                state: null,
+                missingArtifacts: missing,
+                warnings: [
+                    'inconsistent: rd qa-handoff but review artifacts missing; CLI gate should have blocked the transition'
+                ],
+                abandonedRequestCount: ctx.abandonedCount,
+                usedLegacyPath: ctx.usedLegacyPath
+            };
+        }
+        return {
+            kind: 'resume',
+            point: 'qa-validation',
+            state: null,
+            missingArtifacts: ctx.primaryQa === null
+                ? [`qa/test-cases/${ctx.primaryRd.filename}`]
+                : [],
+            warnings: [],
+            abandonedRequestCount: ctx.abandonedCount,
+            usedLegacyPath: ctx.usedLegacyPath
+        };
+    }
+    // PRD handed-off → deepest gate is B. Walk "Other resume triggers"
+    // in priority order: tech-doc > qa/test-cases > in-flight (swarm
+    // converged, RD impl not yet started).
+    if (ctx.primaryPrd !== null && ctx.primaryPrd.state === 'handed-off') {
+        const missing = [];
+        if (!existsSync(join(sessionDir, 'rd', 'tech-doc.md'))) {
+            missing.push('rd/tech-doc.md');
+        }
+        // QA test-cases path: use the RD rid if present, else fall back
+        // to the PRD rid. The rid is shared across roles.
+        const qaCasesRid = ctx.primaryRd !== null
+            ? ctx.primaryRd.filename
+            : ctx.primaryPrd !== null
+                ? ctx.primaryPrd.filename
+                : null;
+        if (qaCasesRid !== null) {
+            const qaCasesPath = join(sessionDir, 'qa', 'test-cases', qaCasesRid);
+            if (!existsSync(qaCasesPath)) {
+                missing.push(`qa/test-cases/${qaCasesRid}`);
+            }
+        }
+        if (missing.includes('rd/tech-doc.md')) {
+            return {
+                kind: 'resume',
+                point: 'rd-planning',
+                state: null,
+                missingArtifacts: missing,
+                warnings: [],
+                abandonedRequestCount: ctx.abandonedCount,
+                usedLegacyPath: ctx.usedLegacyPath
+            };
+        }
+        if (missing.some((m) => m.startsWith('qa/test-cases/'))) {
+            return {
+                kind: 'resume',
+                point: 'qa-test-cases',
+                state: null,
+                missingArtifacts: missing,
+                warnings: [],
+                abandonedRequestCount: ctx.abandonedCount,
+                usedLegacyPath: ctx.usedLegacyPath
+            };
+        }
+        // All post-PRD artifacts present. Either the RD is mid-impl
+        // (handled upstream in Phase 3) or the swarm converged but the
+        // implementation has not yet started. Report the latter as
+        // in-flight:spec-locked so the user can confirm.
+        return {
+            kind: 'in-flight',
+            point: null,
+            state: 'spec-locked',
+            missingArtifacts: [],
+            warnings: [],
+            abandonedRequestCount: ctx.abandonedCount,
+            usedLegacyPath: ctx.usedLegacyPath
+        };
+    }
+    return null;
+}
+/**
+ * Resolve the session directory. Prefers the canonical
+ * `.peaks/_runtime/<sid>/`; falls back to the legacy
+ * `.peaks/_runtime/<sid>/` (one level up from the runtime root) for one
+ * minor release. Returns `null` when neither path exists.
+ */
+function resolveSessionDir(sid, peaksRoot) {
+    const canonical = join(peaksRoot, sid);
+    if (existsSync(canonical)) {
+        return { sessionDir: canonical, usedLegacyPath: false };
+    }
+    const legacy = join(peaksRoot, '..', sid);
+    if (existsSync(legacy)) {
+        return { sessionDir: legacy, usedLegacyPath: true };
+    }
+    return null;
+}
+function readRequestStates(sessionDir, role) {
+    const dir = join(sessionDir, role, 'requests');
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => typeof f === 'string' && f.endsWith('.md'))
+        .sort()
+        .map((filename) => {
+        const full = join(dir, filename);
+        const content = readFileSync(full, 'utf8');
+        return {
+            filename,
+            state: extractState(content),
+            abandoned: hasAbandonedTransitionNote(content)
+        };
+    });
+}
+function extractState(content) {
+    const match = /^-\s*state:\s*(\S+)|^state:\s*(\S+)/m.exec(content);
+    if (match === null)
+        return '';
+    const captured = match[1] ?? match[2] ?? '';
+    return captured.trim();
+}
+function hasAbandonedTransitionNote(content) {
+    return /user-requested-abandon/.test(content);
+}
+function pickPrimary(states) {
+    if (states.length === 0)
+        return null;
+    return states[0] ?? null;
+}

package/dist/services/skill/skill-search-service.d.ts

@@ -0,0 +1,88 @@
+/**
+ * peaks skill search — service-layer primitive for S0 of the
+ * 4.0.0-beta.5 peaks-solo dispatcher release.
+ *
+ * Spec: docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+ * Plan: docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s0-skill-search-cli.md
+ *
+ * This service is the single source of truth for skill pool retrieval
+ * and is reused by the `peaks skill search` CLI. It is intentionally
+ * pure (synchronous frontmatter parse + substring scoring) so the
+ * dispatcher (`peaks-solo`, S1) can call it without paying for any
+ * async I/O during the triage decision flow.
+ *
+ * v1 scope (locked, see plan §"Match rules (v1)"):
+ *   - --query: case-insensitive substring match on description + triggers
+ *   - --tag:   case-insensitive exact match on `metadata.tags`
+ *   - --domain: exact match on `metadata.domain` (locked enum)
+ *   - All three compose with AND; at least one filter is required
+ *   - No match → `[]` (not error, not null)
+ *   - --limit truncates to the top N by matchScore desc
+ *
+ * Out of v1 scope (deferred, see plan §"Goal"): fuzzy / FTS5 / semantic
+ * matching, ML-based ranking, pagination, i18n, caching.
+ */
+import { z } from 'zod';
+import { skillsDir } from '../../shared/paths.js';
+export declare const SkillSearchInputSchema: z.ZodEffects<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodEnum<["code", "content", "doctor", "research", "triage", "sop", "audit", "final-review", "resume", "status", "test", "ide", "slice-decompose", "issue-fix-orchestrator", "perf-audit", "security-audit", "reviewer"]>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    limit?: number | undefined;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}>, {
+    limit: number;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    limit?: number | undefined;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}>;
+export type SkillSearchInput = z.input<typeof SkillSearchInputSchema>;
+export declare const SkillSearchResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    triggers: z.ZodArray<z.ZodString, "many">;
+    tags: z.ZodArray<z.ZodString, "many">;
+    domain: z.ZodString;
+    matchScore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    domain: string;
+    triggers: string[];
+    tags: string[];
+    matchScore: number;
+}, {
+    name: string;
+    description: string;
+    domain: string;
+    triggers: string[];
+    tags: string[];
+    matchScore: number;
+}>;
+export type SkillSearchResult = z.infer<typeof SkillSearchResultSchema>;
+/**
+ * Search the in-tree skill pool. Validates `input` against
+ * `SkillSearchInputSchema`; the schema's refine rejects empty input
+ * with a ZodError, which is the contract test U-7 / I-3 rely on.
+ *
+ * @param input  One of `query | tag | domain` is required.
+ *               All provided filters compose with AND.
+ * @returns      Matching skills sorted by matchScore desc, name asc.
+ *               Empty array (not error, not null) when nothing matches.
+ */
+export declare function searchSkills(rawInput: SkillSearchInput): Promise<SkillSearchResult[]>;
+export { skillsDir as __skillsDirForTests };