codecartographer-pi 0.19.6 → 0.21.0

package/dist/core/orchestrator-config.js

@@ -8,13 +8,19 @@
 //      workspace. Overrides individual keys from the user-global layer.
 //
 // Resolution order (top wins): per-workspace > user-global > defaults.
-// Missing files at either layer fall back to defaults; malformed YAML
-// at either layer is non-fatal (drops the layer, logs nothing).
+// A missing file at either layer falls back to defaults. A file that exists
+// but cannot be used — unparseable YAML, a section that is not a mapping, a
+// key of the wrong type, a relative `library.path` — is dropped at the
+// granularity of the fault and the fault is recorded in `problems`, so the
+// tools can say which file and which key rather than silently answering
+// from the wrong settings (#242, #243).
 //
-// `library.path` is returned tilde-expanded and absolute so consumers
-// don't have to expand themselves.
+// `library.path` is returned tilde-expanded and absolute. A relative value
+// is refused: it would resolve against wherever the MCP server or Pi was
+// launched, not against the config file, so the library would move with the
+// launch directory.
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { expandTilde, pathExists } from "./utils.js";
 import { loadYamlFile, parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
@@ -40,11 +46,12 @@ const DEFAULT_CONFIG = {
         publish_confirm: true,
         publish_confirm_configured: false,
     },
+    problems: [],
 };
 export async function loadCodecartoConfig(workspaceDir) {
-    const userRaw = await loadRawIfExists(resolveUserConfigPath());
-    const workspaceRaw = await loadRawIfExists(join(workspaceDir, CONFIG_RELATIVE_PATH));
-    return mergeLayered([userRaw, workspaceRaw]);
+    const user = await loadRawIfExists(resolveUserConfigPath());
+    const workspace = await loadRawIfExists(join(workspaceDir, CONFIG_RELATIVE_PATH));
+    return mergeLayered([user, workspace]);
 }
 /**
  * Read the user-global config directly. Exposed so wrappers can show
@@ -52,57 +59,113 @@ export async function loadCodecartoConfig(workspaceDir) {
  * load a workspace first.
  */
 export async function loadUserConfig() {
-    const userRaw = await loadRawIfExists(resolveUserConfigPath());
-    return mergeLayered([userRaw]);
+    return mergeLayered([await loadRawIfExists(resolveUserConfigPath())]);
 }
 async function loadRawIfExists(path) {
     if (!(await pathExists(path)))
-        return null;
+        return { path, raw: null };
     try {
-        return await loadYamlFile(path);
+        const parsed = await loadYamlFile(path);
+        if (parsed === null || parsed === undefined)
+            return { path, raw: null };
+        if (typeof parsed !== "object" || Array.isArray(parsed)) {
+            return { path, raw: null, problem: { path, message: "the file is not a YAML mapping; the whole file was ignored" } };
+        }
+        return { path, raw: parsed };
     }
-    catch {
-        return null;
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return { path, raw: null, problem: { path, message: `could not be parsed (${reason}); the whole file was ignored` } };
     }
 }
 function mergeLayered(layers) {
     let merged = cloneDefault();
-    for (const layer of layers)
-        merged = applyRaw(merged, layer);
+    for (const layer of layers) {
+        if (layer.problem) {
+            merged.problems.push(layer.problem);
+            continue;
+        }
+        merged = applyRaw(merged, layer.raw, layer.path);
+    }
     return merged;
 }
 /**
- * Apply one raw config layer over an existing config. Public so tests can
+ * Apply one raw config layer over the defaults. Public so tests can
  * exercise layering without filesystem fixtures, and so wrappers can mock
- * a layer in memory (e.g. "what if library_path were X").
+ * a layer in memory (e.g. "what if library_path were X"). `sourcePath`
+ * names the layer in any problem it produces.
  */
-export function mergeConfig(raw) {
-    return applyRaw(cloneDefault(), raw);
+export function mergeConfig(raw, sourcePath = "(in-memory config)") {
+    return applyRaw(cloneDefault(), raw, sourcePath);
 }
-function applyRaw(base, raw) {
-    if (!raw || typeof raw !== "object")
-        return base;
+/**
+ * The lines both surfaces print for a config with problems: one header,
+ * then one line per fault naming its file. Empty when there are none.
+ */
+export function describeConfigProblems(config) {
+    if (config.problems.length === 0)
+        return [];
+    const noun = config.problems.length === 1 ? "problem" : "problems";
+    return [
+        `Config ${noun} (${config.problems.length}) — these settings are not in effect:`,
+        ...config.problems.map((problem) => `  - ${problem.path}: ${problem.message}`),
+    ];
+}
+function applyRaw(base, raw, sourcePath) {
     const out = {
         orchestrator: { ...base.orchestrator },
         library: { ...base.library },
+        problems: [...base.problems],
     };
+    if (!raw || typeof raw !== "object")
+        return out;
+    const problem = (message) => out.problems.push({ path: sourcePath, message });
+    const describe = (value) => (typeof value === "string" ? JSON.stringify(value) : String(value));
     const o = raw.orchestrator;
-    if (o && typeof o === "object") {
-        if (typeof o.llm_steer_next_phase === "boolean") {
-            out.orchestrator.llm_steer_next_phase = o.llm_steer_next_phase;
+    if (o !== undefined) {
+        if (!o || typeof o !== "object" || Array.isArray(o)) {
+            problem("orchestrator must be a mapping; the section was ignored");
+        }
+        else if (o.llm_steer_next_phase !== undefined) {
+            if (typeof o.llm_steer_next_phase === "boolean") {
+                out.orchestrator.llm_steer_next_phase = o.llm_steer_next_phase;
+            }
+            else {
+                problem(`orchestrator.llm_steer_next_phase must be true or false, got ${describe(o.llm_steer_next_phase)}; the key was ignored`);
+            }
         }
     }
     const l = raw.library;
-    if (l && typeof l === "object") {
-        if (typeof l.path === "string" && l.path.trim() !== "") {
-            out.library.path = resolve(expandTilde(l.path.trim()));
+    if (l !== undefined) {
+        if (!l || typeof l !== "object" || Array.isArray(l)) {
+            problem("library must be a mapping; the section was ignored");
         }
-        if (typeof l.namespace === "string" && l.namespace.trim() !== "") {
-            out.library.namespace = l.namespace.trim();
-        }
-        if (typeof l.publish_confirm === "boolean") {
-            out.library.publish_confirm = l.publish_confirm;
-            out.library.publish_confirm_configured = true;
+        else {
+            if (typeof l.path === "string" && l.path.trim() !== "") {
+                const expanded = expandTilde(l.path.trim());
+                if (isAbsolute(expanded)) {
+                    out.library.path = resolve(expanded);
+                }
+                else {
+                    problem(`library.path must be absolute or start with ~ (got ${describe(l.path.trim())}); the key was ignored`);
+                }
+            }
+            else if (l.path !== undefined && l.path !== null && typeof l.path !== "string") {
+                problem(`library.path must be a string, got ${describe(l.path)}; the key was ignored`);
+            }
+            if (typeof l.namespace === "string" && l.namespace.trim() !== "") {
+                out.library.namespace = l.namespace.trim();
+            }
+            else if (l.namespace !== undefined && l.namespace !== null && typeof l.namespace !== "string") {
+                problem(`library.namespace must be a string, got ${describe(l.namespace)}; the key was ignored`);
+            }
+            if (typeof l.publish_confirm === "boolean") {
+                out.library.publish_confirm = l.publish_confirm;
+                out.library.publish_confirm_configured = true;
+            }
+            else if (l.publish_confirm !== undefined) {
+                problem(`library.publish_confirm must be true or false, got ${describe(l.publish_confirm)}; the key was ignored`);
+            }
         }
     }
     return out;
@@ -111,25 +174,42 @@ function cloneDefault() {
     return {
         orchestrator: { ...DEFAULT_CONFIG.orchestrator },
         library: { ...DEFAULT_CONFIG.library },
+        problems: [],
     };
 }
 /**
- * Write a `library:` block into a config file (user-global or workspace).
- * Creates the file and parent directories if needed. Preserves any existing
- * `orchestrator:` block. Overwrites the `library:` block if present.
+ * Record a library in a config file (user-global or workspace): set
+ * `library.path`, and `library.namespace` when one is given. Every other key
+ * in the file, `library.publish_confirm` included, is left exactly as it was
+ * — library-init writes only what it was asked for, so it cannot switch the
+ * MCP confirm gate on behind the user's back (#244). Creates the file and
+ * parent directories if needed. A file that exists but does not parse is
+ * never overwritten: the caller is told to fix it first.
  */
-export async function writeLibraryConfig(configPath, libraryPath, namespace = null, publishConfirm = true) {
+export async function writeLibraryConfig(configPath, libraryPath, namespace = null) {
     let existing = {};
     if (await pathExists(configPath)) {
+        const raw = await readFile(configPath, "utf8");
+        let parsed;
         try {
-            const raw = await readFile(configPath, "utf8");
-            existing = parseSimpleYaml(raw);
+            parsed = parseSimpleYaml(raw);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Refusing to rewrite ${configPath}: it could not be parsed (${reason}). Fix or remove the file, then run library-init again.`);
         }
-        catch {
-            // Malformed file — start fresh
+        if (parsed !== null && parsed !== undefined) {
+            if (typeof parsed !== "object" || Array.isArray(parsed)) {
+                throw new Error(`Refusing to rewrite ${configPath}: it is not a YAML mapping. Fix or remove the file, then run library-init again.`);
+            }
+            existing = parsed;
         }
     }
-    const library = { path: libraryPath, publish_confirm: publishConfirm };
+    const previous = existing.library;
+    const library = previous && typeof previous === "object" && !Array.isArray(previous)
+        ? { ...previous }
+        : {};
+    library.path = libraryPath;
     if (namespace)
         library.namespace = namespace;
     const updated = { ...existing, library };

package/dist/core/pipeline.d.ts

@@ -4,7 +4,80 @@ export declare const DEFAULT_PIPELINE_PATH = "workflow/pipeline-full-with-deep-a
 export declare function getPhaseMap(pipeline: PipelineFile): Map<string, PipelinePhase>;
 export declare function getPipelineLabel(pipelinePath: string): string;
 export declare function getNextEligiblePhase(state: WorkspaceState): PipelinePhase | null;
+/** One phase the pipeline cannot reach, and the dependencies keeping it there. */
+export interface BlockedPhase {
+    phaseId: string;
+    /** Each unmet `depends_on` entry, with why it will not clear on its own. */
+    missing: Array<{
+        dependencyId: string;
+        reason: "not-in-pipeline" | "blocked";
+    }>;
+}
+/**
+ * What the pipeline can do next. `getNextEligiblePhase` returned null both
+ * when every phase was complete and when the remaining phases waited on a
+ * dependency that would never clear, and every consumer read null as
+ * complete: a DAG with an unmet dependency reported 1/2 complete and unlocked
+ * the post-pipeline skills (#228). The third outcome is the difference.
+ */
+export type PipelineOutcome = {
+    kind: "eligible";
+    phase: PipelinePhase;
+} | {
+    kind: "complete";
+} | {
+    kind: "stuck";
+    blocked: BlockedPhase[];
+};
+export declare function resolvePipelineOutcome(state: WorkspaceState): PipelineOutcome;
+/** True when every phase in the active pipeline is complete. */
+export declare function isPipelineComplete(state: WorkspaceState): boolean;
+/**
+ * One sentence both surfaces print for a stuck pipeline, naming each blocked
+ * phase and the dependency keeping it there. The pipeline file is the thing to
+ * fix — or switch away from — so the sentence says so.
+ */
+export declare function describeStuckPipeline(blocked: BlockedPhase[]): string;
+/**
+ * Point `current_phase` and `next_actions` at whatever the engine finds
+ * eligible now, at the terminal routing when every phase is complete, or at
+ * the first blocked phase with the stuck sentence when nothing can run.
+ * Completion and a pipeline switch both derive the cursor this way (#236), so
+ * status.yaml never disagrees with the phase records it sits beside. Returns
+ * the eligible phase, or null.
+ */
+export declare function recomputeCursor(state: WorkspaceState): PipelinePhase | null;
+/**
+ * Phases status.yaml records as complete whose primary output is not on disk.
+ * status.yaml is committed and the findings are ignored by default, so a fresh
+ * clone says "complete" about reports it does not have; both surfaces' status
+ * name the gap rather than let the two files disagree in silence (#259).
+ */
+export declare function listMissingCompletedOutputs(state: WorkspaceState): Promise<Array<{
+    phaseId: string;
+    path: string;
+}>>;
+/** The status lines both surfaces print for {@link listMissingCompletedOutputs}; empty when nothing is missing. */
+export declare function describeMissingCompletedOutputs(missing: Array<{
+    phaseId: string;
+    path: string;
+}>): string[];
 export declare function resolvePhase(state: WorkspaceState, phaseId?: string): PipelinePhase | null;
 export declare function resolvePipelineChoice(input: string): string | null;
+/** What an Overall line can say; MISSING is the validator's own word for an absent output. */
+type OverallVerdict = Exclude<ValidationResult["overall"], "MISSING">;
+/**
+ * Read the verdict off a `**Overall:**` line, tolerating decoration around
+ * it: `**Overall:** PASS (6/6)`, `**Overall:** **PASS WITH GAPS** — see §3`,
+ * `**Overall**: \`PASS\`.`, a leading list marker. The verdict is whatever the
+ * value starts with; anything after it is commentary. Returns null for a
+ * line that is not an Overall line at all, and `{ verdict: null }` for one
+ * whose value does not start with a verdict, so the caller can say which
+ * line it could not read rather than reporting a bare FAIL (#247).
+ */
+export declare function parseOverallLine(line: string): {
+    verdict: OverallVerdict | null;
+} | null;
 export declare function validatePhaseOutput(state: WorkspaceState, phaseId?: string): Promise<ValidationResult>;
 export declare function buildValidationSummary(validation: ValidationResult): string[];
+export {};

package/dist/core/pipeline.js

@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { pathExists } from "./utils.js";
 import { crossCheckFindings, findingsPairingGateActive } from "./findings.js";
+import { beginPhaseAction, buildTerminalNextActions } from "./status.js";
 export const PIPELINE_ALIASES = {
     "full-with-audit": "workflow/pipeline-full-with-audit.yaml",
     "full-with-deep-audit": "workflow/pipeline-full-with-deep-audit.yaml",
@@ -39,6 +40,100 @@ export function getNextEligiblePhase(state) {
     }
     return null;
 }
+export function resolvePipelineOutcome(state) {
+    const phase = getNextEligiblePhase(state);
+    if (phase)
+        return { kind: "eligible", phase };
+    const phaseMap = getPhaseMap(state.pipeline);
+    const isComplete = (phaseId) => state.status.phases[phaseId]?.status === "complete";
+    const incomplete = state.pipeline.phase_order.filter((phaseId) => !isComplete(phaseId));
+    if (incomplete.length === 0)
+        return { kind: "complete" };
+    // Nothing is eligible and something is incomplete, so every incomplete
+    // phase has an unmet dependency. Each one is either a phase this pipeline
+    // does not declare, or one of the blocked phases themselves (a cycle, or a
+    // chain back to one).
+    const blocked = incomplete.map((phaseId) => ({
+        phaseId,
+        missing: (phaseMap.get(phaseId)?.depends_on ?? [])
+            .filter((dependencyId) => !isComplete(dependencyId))
+            .map((dependencyId) => ({
+            dependencyId,
+            reason: state.pipeline.phase_order.includes(dependencyId) ? "blocked" : "not-in-pipeline",
+        })),
+    }));
+    return { kind: "stuck", blocked };
+}
+/** True when every phase in the active pipeline is complete. */
+export function isPipelineComplete(state) {
+    return resolvePipelineOutcome(state).kind === "complete";
+}
+/**
+ * One sentence both surfaces print for a stuck pipeline, naming each blocked
+ * phase and the dependency keeping it there. The pipeline file is the thing to
+ * fix — or switch away from — so the sentence says so.
+ */
+export function describeStuckPipeline(blocked) {
+    const parts = blocked.map((entry) => {
+        const deps = entry.missing.map((m) => m.reason === "not-in-pipeline" ? `${m.dependencyId}, which is not in this pipeline` : `${m.dependencyId}, which is itself blocked`);
+        return `${entry.phaseId} depends on ${deps.join(" and ") || "nothing it can reach"}`;
+    });
+    return `Pipeline is stuck: ${parts.join("; ")}. No phase can run until the pipeline file's depends_on is fixed (or switch pipelines with codecarto_switch_pipeline / /codecarto-switch-pipeline).`;
+}
+/**
+ * Point `current_phase` and `next_actions` at whatever the engine finds
+ * eligible now, at the terminal routing when every phase is complete, or at
+ * the first blocked phase with the stuck sentence when nothing can run.
+ * Completion and a pipeline switch both derive the cursor this way (#236), so
+ * status.yaml never disagrees with the phase records it sits beside. Returns
+ * the eligible phase, or null.
+ */
+export function recomputeCursor(state) {
+    const outcome = resolvePipelineOutcome(state);
+    if (outcome.kind === "eligible") {
+        state.status.current_phase = outcome.phase.id;
+        state.status.next_actions = [beginPhaseAction(outcome.phase)];
+        return outcome.phase;
+    }
+    if (outcome.kind === "stuck") {
+        // The cursor stays on the first phase that cannot run; "complete" is
+        // reserved for the state where nothing is left (#228).
+        state.status.current_phase = outcome.blocked[0]?.phaseId ?? "complete";
+        state.status.next_actions = [describeStuckPipeline(outcome.blocked)];
+        return null;
+    }
+    state.status.current_phase = "complete";
+    state.status.next_actions = buildTerminalNextActions(state.status);
+    return null;
+}
+/**
+ * Phases status.yaml records as complete whose primary output is not on disk.
+ * status.yaml is committed and the findings are ignored by default, so a fresh
+ * clone says "complete" about reports it does not have; both surfaces' status
+ * name the gap rather than let the two files disagree in silence (#259).
+ */
+export async function listMissingCompletedOutputs(state) {
+    const missing = [];
+    for (const phase of state.pipeline.phases) {
+        if (!phase.primary_output)
+            continue;
+        if (state.status.phases[phase.id]?.status !== "complete")
+            continue;
+        if (await pathExists(join(state.workspaceDir, phase.primary_output)))
+            continue;
+        missing.push({ phaseId: phase.id, path: phase.primary_output });
+    }
+    return missing;
+}
+/** The status lines both surfaces print for {@link listMissingCompletedOutputs}; empty when nothing is missing. */
+export function describeMissingCompletedOutputs(missing) {
+    if (missing.length === 0)
+        return [];
+    return [
+        `Outputs missing on disk for ${missing.length} complete phase(s) — findings are gitignored by default, so a clone carries the status but not the reports; re-run the phase here, or commit findings (see README, "What to commit"):`,
+        ...missing.map((entry) => `  - ${entry.phaseId}: .codecarto/${entry.path}`),
+    ];
+}
 export function resolvePhase(state, phaseId) {
     const trimmed = phaseId?.trim();
     if (!trimmed)
@@ -66,6 +161,28 @@ export function resolvePipelineChoice(input) {
         return PIPELINE_ALIASES[trimmed];
     return trimmed.endsWith(".yaml") ? trimmed : null;
 }
+/**
+ * Read the verdict off a `**Overall:**` line, tolerating decoration around
+ * it: `**Overall:** PASS (6/6)`, `**Overall:** **PASS WITH GAPS** — see §3`,
+ * `**Overall**: \`PASS\`.`, a leading list marker. The verdict is whatever the
+ * value starts with; anything after it is commentary. Returns null for a
+ * line that is not an Overall line at all, and `{ verdict: null }` for one
+ * whose value does not start with a verdict, so the caller can say which
+ * line it could not read rather than reporting a bare FAIL (#247).
+ */
+export function parseOverallLine(line) {
+    const match = /^(?:[-*>]\s+)?\*\*Overall(?::\*\*|\*\*:)\s*(.*)$/i.exec(line.trim());
+    if (!match)
+        return null;
+    const value = (match[1] ?? "").replace(/^[\s*_`]+/, "").toUpperCase();
+    if (/^PASS WITH GAPS(?![A-Z])/.test(value))
+        return { verdict: "PASS WITH GAPS" };
+    if (/^PASS(?![A-Z])/.test(value))
+        return { verdict: "PASS" };
+    if (/^FAIL(?![A-Z])/.test(value))
+        return { verdict: "FAIL" };
+    return { verdict: null };
+}
 export async function validatePhaseOutput(state, phaseId) {
     const phase = resolvePhase(state, phaseId);
     if (!phase) {
@@ -119,6 +236,10 @@ export async function validatePhaseOutput(state, phaseId) {
     const validationContent = content.slice(validationHeadingIndex);
     const rows = [];
     let overall = "FAIL";
+    const errors = [];
+    // The last **Overall:** line wins; what it said is remembered so the error
+    // can quote it when the verdict could not be read or was FAIL.
+    let overallLine = null;
     for (const rawLine of validationContent.split(/\r?\n/)) {
         const line = rawLine.trim();
         if (line.startsWith("|")) {
@@ -134,18 +255,21 @@ export async function validatePhaseOutput(state, phaseId) {
                 });
             }
         }
-        const overallMatch = line.match(/^\*\*Overall:\*\*\s*(.+)$/i);
-        if (overallMatch?.[1]) {
-            const normalizedOverall = overallMatch[1].trim().toUpperCase();
-            if (normalizedOverall === "PASS")
-                overall = "PASS";
-            else if (normalizedOverall === "PASS WITH GAPS")
-                overall = "PASS WITH GAPS";
-            else
-                overall = "FAIL";
+        const parsed = parseOverallLine(line);
+        if (parsed) {
+            overallLine = { text: line, verdict: parsed.verdict };
+            overall = parsed.verdict ?? "FAIL";
         }
     }
-    const errors = [];
+    if (!overallLine) {
+        errors.push("No **Overall:** line found in the ## Validation block. End the block with `**Overall:** PASS`, `**Overall:** PASS WITH GAPS`, or `**Overall:** FAIL`.");
+    }
+    else if (overallLine.verdict === null) {
+        errors.push(`Could not read the verdict on the Overall line: "${overallLine.text}". It must start with PASS, PASS WITH GAPS, or FAIL; anything after the verdict is ignored.`);
+    }
+    else if (overallLine.verdict === "FAIL") {
+        errors.push(`The Overall line says FAIL: "${overallLine.text}".`);
+    }
     const gaps = rows
         .filter((row) => row.result.toUpperCase().includes("PARTIAL"))
         .map((row) => `${row.criterion}: ${row.evidence}`);

package/dist/core/prompts.d.ts

@@ -1,5 +1,16 @@
 import type { CarryForwardEntry, OpenQuestionEntry, PipelinePhase, WorkspaceState } from "./types.ts";
 import { type PhasePreflightResult } from "./synthesis.ts";
+/** Chars of one spliced item shown before it is cut; the full text stays in its file. */
+export declare const SPLICED_TEXT_LIMIT = 400;
+/**
+ * Quote text an earlier session wrote — a routed item's description, a
+ * coverage bullet, a library headline — so it reads as data inside the next
+ * prompt, not as one of the framework's instructions (#253): one line, capped
+ * at {@link SPLICED_TEXT_LIMIT}, inside `«…»`, which the framework never uses
+ * for its own lines. Guillemets inside the text become single ones so the
+ * boundary stays unambiguous.
+ */
+export declare function quoteSpliced(text: string, limit?: number): string;
 export declare function describeEntry(entry: OpenQuestionEntry | CarryForwardEntry): string;
 export declare function collectRoutedCarryForward(state: WorkspaceState, targetPhaseId: string): CarryForwardEntry[];
 export interface BuildPhasePromptOptions {
@@ -23,4 +34,13 @@ export interface BuildPhasePromptOptions {
 export declare function buildPhasePrompt(state: WorkspaceState, phase: PipelinePhase, forced: boolean, options?: BuildPhasePromptOptions): Promise<string>;
 export declare function closeoutFileName(date: string, phaseOrModule: string): string;
 export declare function listSkillNames(workspaceDir: string): Promise<string[]>;
+/**
+ * Resolve a user-supplied skill name to an installed post-pipeline skill.
+ *
+ * The name is matched against `listSkillNames()` by exact directory name and
+ * is never joined onto a path, so `../findings/architecture` or any other
+ * traversal cannot reach a SKILL.md outside `skills/` and be spliced into the
+ * prompt. Returns the canonical name, or null when nothing installed matches.
+ */
+export declare function resolveSkillName(workspaceDir: string, name: string): Promise<string | null>;
 export declare function buildSkillPrompt(state: WorkspaceState, skillName: string): Promise<string>;