@oscharko-dev/keiko-workflows 0.2.0

package/dist/planner/index.d.ts

@@ -0,0 +1,11 @@
+export type { AnchorExtractionInput, AnchorExtractionResult, SearchAnchor, SearchAnchorKind, } from "./anchors.js";
+export { extractAnchors } from "./anchors.js";
+export type { RetrievalIntent, RetrievalIntentClassification } from "./intent.js";
+export { classifyRetrievalIntent } from "./intent.js";
+export type { ClarificationPrompt, ClarificationReason, CreatePlanDeps, CreatePlanInput, ExplorationPlan, ExplorationPlanState, RetrievalRing, RetrievalRingKind, } from "./plan.js";
+export { createExplorationPlan } from "./plan.js";
+export type { GovernorState, GovernorStatus } from "./governor.js";
+export { advanceRing, applyUsage, canContinue, complete, createGovernor } from "./governor.js";
+export type { PlanAndGovernResult } from "./explorationPlanner.js";
+export { planAndGovern, planExploration } from "./explorationPlanner.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/planner/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/planner/index.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,YAAY,EAAE,eAAe,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAEtD,YAAY,EACV,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,aAAa,EACb,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/planner/index.js

@@ -0,0 +1,8 @@
+// Public sub-barrel for the exploration planner and budget governor (Epic #177, Issue #181).
+// External consumers import every planner symbol through this module; internal modules
+// (anchors.ts, plan.ts, governor.ts, explorationPlanner.ts) are implementation detail.
+export { extractAnchors } from "./anchors.js";
+export { classifyRetrievalIntent } from "./intent.js";
+export { createExplorationPlan } from "./plan.js";
+export { advanceRing, applyUsage, canContinue, complete, createGovernor } from "./governor.js";
+export { planAndGovern, planExploration } from "./explorationPlanner.js";

package/dist/planner/intent.d.ts

@@ -0,0 +1,8 @@
+import type { SelectedScope } from "@oscharko-dev/keiko-contracts/connected-context";
+export type RetrievalIntent = "project-metadata" | "repository-overview" | "targeted-code-search" | "diagnostic-search" | "clarification-needed";
+export interface RetrievalIntentClassification {
+    readonly intent: RetrievalIntent;
+    readonly normalizedTerms: readonly string[];
+}
+export declare function classifyRetrievalIntent(queryText: string, _scope?: SelectedScope): RetrievalIntentClassification;
+//# sourceMappingURL=intent.d.ts.map

package/dist/planner/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../../src/planner/intent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iDAAiD,CAAC;AAErF,MAAM,MAAM,eAAe,GACvB,kBAAkB,GAClB,qBAAqB,GACrB,sBAAsB,GACtB,mBAAmB,GACnB,sBAAsB,CAAC;AAE3B,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAuJD,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,aAAa,GACrB,6BAA6B,CAqB/B"}

package/dist/planner/intent.js

@@ -0,0 +1,140 @@
+// Deterministic retrieval-intent classification for connected-context planning.
+// This module is intentionally pure: no IO, no clock, no model calls.
+const BASIC_STOP_WORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "of",
+    "in",
+    "on",
+    "at",
+    "to",
+    "a",
+    "an",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "do",
+    "does",
+    "did",
+    "how",
+    "why",
+    "what",
+    "which",
+    "where",
+    "when",
+    "who",
+    "das",
+    "dass",
+    "der",
+    "die",
+    "ein",
+    "eine",
+    "einer",
+    "einem",
+    "einen",
+    "ist",
+    "sind",
+    "und",
+    "oder",
+    "welche",
+    "welcher",
+    "welches",
+    "welchen",
+    "wie",
+    "wo",
+    "wird",
+    "werden",
+    "zu",
+]);
+const PROJECT_METADATA_PATTERNS = [
+    { term: "typescript", pattern: /\btype[\s_-]?script\b/iu },
+    { term: "javascript", pattern: /\bjava[\s_-]?script\b/iu },
+    { term: "node", pattern: /\bnode(?:\.js)?\b/iu },
+    { term: "package-json", pattern: /\bpackage\.json\b/iu },
+    { term: "package-manager", pattern: /\bpackage[\s_-]?manager\b/iu },
+    { term: "package-manager", pattern: /\bpaket[\s_-]?manager\b/iu },
+    { term: "tsconfig", pattern: /\btsconfig(?:\.[a-z0-9]+)?\b/iu },
+    { term: "dependency", pattern: /\bdevdependencies\b|\bdependencies\b|\bdependency\b/iu },
+    { term: "dependency", pattern: /\babhaengigkeit(?:en)?\b|\babhängigkeit(?:en)?\b/iu },
+    { term: "script", pattern: /\bscripts?\b|\bskripte?\b/iu },
+    { term: "version", pattern: /\bversion(?:en)?\b/iu },
+    { term: "framework", pattern: /\bframeworks?\b/iu },
+    { term: "test-runner", pattern: /\btest[\s_-]?runner\b|\btestumgebung\b/iu },
+    { term: "build", pattern: /\bbuild\b|\bgebaut\b|\bbauen\b/iu },
+    { term: "npm", pattern: /\bnpm\b/iu },
+    { term: "pnpm", pattern: /\bpnpm\b/iu },
+    { term: "yarn", pattern: /\byarn\b/iu },
+    { term: "vite", pattern: /\bvite\b/iu },
+    { term: "vitest", pattern: /\bvitest\b/iu },
+    { term: "jest", pattern: /\bjest\b/iu },
+    { term: "playwright", pattern: /\bplaywright\b/iu },
+    { term: "cypress", pattern: /\bcypress\b/iu },
+    { term: "nextjs", pattern: /\bnext(?:\.js)?\b/iu },
+    { term: "react", pattern: /\breact\b/iu },
+    { term: "eslint", pattern: /\beslint\b/iu },
+];
+const REPOSITORY_OVERVIEW_PATTERNS = [
+    { term: "architecture", pattern: /\barchitecture\b|\barchitektur\b/iu },
+    { term: "overview", pattern: /\boverview\b|\bueberblick\b|\büberblick\b/iu },
+    { term: "structure", pattern: /\bstructure\b|\bstruktur\b|\baufbau\b/iu },
+    { term: "repository", pattern: /\brepository\b|\brepo\b|\bcodebase\b/iu },
+    { term: "modules", pattern: /\bmodules?\b|\bmodule\b|\bpakete\b|\bpackages\b/iu },
+    { term: "components", pattern: /\bcomponents?\b|\bkomponenten\b/iu },
+];
+const DIAGNOSTIC_PATTERNS = [
+    { term: "error", pattern: /\berror\b|\bfehler\b|\bexception\b|\btraceback\b/iu },
+    { term: "stacktrace", pattern: /\bstack[\s_-]?trace\b|\bstacktrace\b/iu },
+    { term: "failure", pattern: /\bfail(?:ed|ing|ure)?\b|\bscheitert\b|\bkaputt\b/iu },
+    { term: "bug", pattern: /\bbug\b|\bdefect\b|\bregression\b/iu },
+    { term: "http-status", pattern: /\b[45]\d{2}\b|\bhttp\b/iu },
+];
+const TARGETED_CODE_PATTERNS = [
+    { term: "path", pattern: /(?:[\w.-]+\/)+[\w.-]+/u },
+    { term: "quoted", pattern: /"[^"\n]+"|'[^'\n]+'|`[^`\n]+`/u },
+    { term: "identifier", pattern: /\b[A-Za-z_$][A-Za-z0-9_$]*[A-Z][A-Za-z0-9_$]*\b/u },
+    { term: "symbol", pattern: /\b(function|class|interface|type|const|let|var)\s+[A-Za-z_]/iu },
+];
+function normalizeQueryText(queryText) {
+    return queryText.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase();
+}
+function searchableTokens(normalized) {
+    return (normalized
+        .split(/[^a-z0-9_.-]+/u)
+        .filter((token) => token.length >= 3 && !BASIC_STOP_WORDS.has(token))
+        // `.`, `-` and `_` are kept inside tokens (so `package.json`/`tsconfig.base` survive), but a
+        // token built only from those separators (e.g. `...`, `--`, `__`) is not searchable. Require at
+        // least one alphanumeric character so a pure-punctuation prompt resolves to clarification-needed.
+        .filter((token) => /[a-z0-9]/u.test(token)));
+}
+function matchedTerms(queryText, normalized, patterns) {
+    const terms = new Set();
+    for (const entry of patterns) {
+        if (entry.pattern.test(queryText) || entry.pattern.test(normalized)) {
+            terms.add(entry.term);
+        }
+    }
+    return [...terms].sort();
+}
+function classifyByPatterns(queryText, normalized, patterns, intent) {
+    const terms = matchedTerms(queryText, normalized, patterns);
+    return terms.length === 0 ? undefined : { intent, normalizedTerms: terms };
+}
+export function classifyRetrievalIntent(queryText, _scope) {
+    const trimmed = queryText.trim();
+    const normalized = normalizeQueryText(trimmed);
+    if (trimmed.length === 0 || searchableTokens(normalized).length === 0) {
+        return { intent: "clarification-needed", normalizedTerms: [] };
+    }
+    return (classifyByPatterns(trimmed, normalized, PROJECT_METADATA_PATTERNS, "project-metadata") ??
+        classifyByPatterns(trimmed, normalized, DIAGNOSTIC_PATTERNS, "diagnostic-search") ??
+        classifyByPatterns(trimmed, normalized, TARGETED_CODE_PATTERNS, "targeted-code-search") ??
+        classifyByPatterns(trimmed, normalized, REPOSITORY_OVERVIEW_PATTERNS, "repository-overview") ?? {
+        intent: "targeted-code-search",
+        normalizedTerms: searchableTokens(normalized).slice(0, 8),
+    });
+}

package/dist/planner/plan.d.ts

@@ -0,0 +1,43 @@
+import { CONNECTED_CONTEXT_SCHEMA_VERSION, type ExplorationBudget, type RetrievalQuery, type SelectedScope } from "@oscharko-dev/keiko-contracts/connected-context";
+import type { SearchLimits } from "@oscharko-dev/keiko-workspace";
+import { type SearchAnchor } from "./anchors.js";
+import { type RetrievalIntent } from "./intent.js";
+export type ExplorationPlanState = "ready" | "completed" | "budget-exhausted" | "clarification-needed" | "scope-invalid";
+export type RetrievalRingKind = "lexical" | "structural" | "git-history";
+export interface RetrievalRing {
+    readonly kind: RetrievalRingKind;
+    readonly label: string;
+    readonly anchorTerms: readonly string[];
+    readonly searchLimits: SearchLimits;
+    readonly rationale: string;
+}
+export type ClarificationReason = "no-anchors" | "too-generic" | "scope-empty" | "scope-invalid";
+export interface ClarificationPrompt {
+    readonly reason: ClarificationReason;
+    readonly suggestedQuestions: readonly string[];
+    readonly minimumAnchorCount: number;
+}
+export interface ExplorationPlan {
+    readonly schemaVersion: typeof CONNECTED_CONTEXT_SCHEMA_VERSION;
+    readonly planId: string;
+    readonly state: ExplorationPlanState;
+    readonly retrievalIntent: RetrievalIntent;
+    readonly scope: SelectedScope;
+    readonly query: RetrievalQuery;
+    readonly anchors: readonly SearchAnchor[];
+    readonly rings: readonly RetrievalRing[];
+    readonly budget: ExplorationBudget;
+    readonly clarification: ClarificationPrompt | undefined;
+    readonly createdAtMs: number;
+}
+export interface CreatePlanInput {
+    readonly scope: SelectedScope;
+    readonly query: RetrievalQuery;
+    readonly budget?: ExplorationBudget;
+    readonly maxAnchors?: number;
+}
+export interface CreatePlanDeps {
+    readonly nowMs?: () => number;
+}
+export declare function createExplorationPlan(input: CreatePlanInput, deps?: CreatePlanDeps): ExplorationPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/planner/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/planner/plan.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,gCAAgC,EAGhC,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,iDAAiD,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,OAAO,EAAkB,KAAK,YAAY,EAAyB,MAAM,cAAc,CAAC;AACxF,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,aAAa,CAAC;AAQrB,MAAM,MAAM,oBAAoB,GAC5B,OAAO,GACP,WAAW,GACX,kBAAkB,GAClB,sBAAsB,GACtB,eAAe,CAAC;AAEpB,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC;AAEzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,mBAAmB,GAAG,YAAY,GAAG,aAAa,GAAG,aAAa,GAAG,eAAe,CAAC;AAEjG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,gCAAgC,CAAC;IAChE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AA2QD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,eAAe,EACtB,IAAI,CAAC,EAAE,cAAc,GACpB,eAAe,CAqCjB"}

package/dist/planner/plan.js

@@ -0,0 +1,237 @@
+// Exploration plan factory and retrieval-ring composition (Epic #177, Issue #181).
+// Consumes #178 contracts and #179 search-limits surface. Produces a JSON-safe ExplorationPlan
+// BEFORE any retrieval work runs. Deterministic planId via node:crypto SHA-256. No IO, no
+// network. Execution and persistence of plans land in #182/#183/#187.
+import { createHash } from "node:crypto";
+import { CONNECTED_CONTEXT_SCHEMA_VERSION, DEFAULT_EXPLORATION_BUDGET, validateSelectedScope, } from "@oscharko-dev/keiko-contracts/connected-context";
+import { extractAnchors } from "./anchors.js";
+import { classifyRetrievalIntent, } from "./intent.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_ANCHORS = 8;
+const RING_WEIGHTS = {
+    lexical: 0.55,
+    structural: 0.3,
+    "git-history": 0.15,
+};
+// Lexical/structural scanning is transient — each candidate file is read to match lines, then
+// discarded — so its breadth is bounded by elapsedMsMax, NOT by the excerpt-byte budget the model
+// context is built from. Deriving maxFilesScanned from the excerpt slice capped the scan at ~4
+// files and starved multi-file connected scopes (Epic #177 retrieval defect): the search could
+// never reach the file a question was actually about. These ceilings let a ring examine the
+// connected scope broadly while the excerpt READ phase keeps enforcing filesReadMax/excerptBytesMax.
+const SCAN_FILE_CEILING = 2048;
+// Evidence atoms returned for ranking. With the search facade's per-file match cap this represents
+// many candidate files (well beyond filesReadMax) so the ranker has real choice before the excerpt
+// phase reads the top files.
+const MATCH_RETURN_CEILING = 256;
+// Per-file scan read cap (2 MiB). A connected file up to this size is fully read and matched so it
+// is never skipped as size-exceeded regardless of format; only files larger than this are omitted.
+// This bounds the transient per-file read during line matching, NOT the excerpt content that enters
+// the pack (Epic #177 retrieval fix — the prior excerpt-byte-derived cap of ~18 KiB silently dropped
+// larger files from the search entirely).
+const SCAN_BYTES_PER_FILE = 2_097_152;
+const RING_LABELS = {
+    lexical: "Lexical scan across the selected scope",
+    structural: "Structural lookups around identifier and path anchors",
+    "git-history": "Recent git-history signal across the workspace",
+};
+const RING_RATIONALES = {
+    lexical: "Lexical anchors are always cheap to scan first and bound the working set.",
+    structural: "Identifier or path anchors warrant structural lookups so callers are reached without a full text scan.",
+    "git-history": "Workspace-level queries benefit from recency signal because no sub-scope was preselected.",
+};
+const NO_ANCHOR_QUESTIONS = [
+    "Which file or symbol should I focus on?",
+    "What error message did you see?",
+    "Name a function or class to start from.",
+];
+const TOO_GENERIC_QUESTIONS = [
+    "Can you name the file, class, or function this should touch?",
+    "Is there a recent error message or log line that anchors the question?",
+];
+const SCOPE_EMPTY_QUESTIONS = [
+    "Which folder or files within the workspace should I look at?",
+    "Is this question about the whole workspace, or a specific module?",
+];
+const SCOPE_INVALID_QUESTIONS = [
+    "The selected scope did not validate; please reselect files or a directory.",
+];
+// ─── Budget slicing ───────────────────────────────────────────────────────────
+function atLeastOne(value) {
+    return Math.max(1, Math.floor(value));
+}
+function sliceLimits(budget, weight) {
+    // Scanning is transient — each file is read to match lines, then discarded — and is bounded by
+    // elapsedMsMax, NOT by the excerpt-byte budget the model context is built from. Both the per-file
+    // read cap and the scan breadth are therefore decoupled from excerptBytesMax (Epic #177 retrieval
+    // fix); deriving them from the excerpt slice capped scanning at ~4 files of ~18 KiB and silently
+    // skipped any larger or later-sorted file. The excerpt READ phase still enforces filesReadMax /
+    // excerptBytesMax when it incorporates file content into the pack.
+    return {
+        maxFilesScanned: atLeastOne(SCAN_FILE_CEILING * weight),
+        maxMatchesReturned: atLeastOne(MATCH_RETURN_CEILING * weight),
+        maxBytesPerFileScanned: SCAN_BYTES_PER_FILE,
+        elapsedMsMax: atLeastOne(budget.elapsedMsMax * weight),
+    };
+}
+// ─── Ring composition ─────────────────────────────────────────────────────────
+function anchorTerms(anchors) {
+    return anchors.map((a) => a.term);
+}
+function hasKind(anchors, kind) {
+    return anchors.some((a) => a.kind === kind);
+}
+function buildRing(kind, anchors, budget) {
+    return {
+        kind,
+        label: RING_LABELS[kind],
+        anchorTerms: anchorTerms(anchors),
+        searchLimits: sliceLimits(budget, RING_WEIGHTS[kind]),
+        rationale: RING_RATIONALES[kind],
+    };
+}
+function composeRings(anchors, scope, budget) {
+    const rings = [buildRing("lexical", anchors, budget)];
+    if (hasKind(anchors, "identifier") || hasKind(anchors, "path")) {
+        rings.push(buildRing("structural", anchors, budget));
+    }
+    if (scope.relativePaths.length === 0) {
+        rings.push(buildRing("git-history", anchors, budget));
+    }
+    return rings;
+}
+// ─── Clarification helpers ────────────────────────────────────────────────────
+function maxAnchorWeight(anchors) {
+    let max = 0;
+    for (const a of anchors) {
+        if (a.weight > max) {
+            max = a.weight;
+        }
+    }
+    return max;
+}
+function buildClarification(reason, suggestedQuestions, minimumAnchorCount) {
+    return { reason, suggestedQuestions, minimumAnchorCount };
+}
+function explicitConnectionIsReady(scope, intent) {
+    if (scope.explicitConnection !== true) {
+        return false;
+    }
+    if (scope.kind !== "workspace-root") {
+        return true;
+    }
+    return intent === "project-metadata" || intent === "repository-overview";
+}
+function decideClarification(anchors, scope, intent) {
+    if (anchors.length === 0) {
+        return {
+            state: "clarification-needed",
+            clarification: buildClarification("no-anchors", NO_ANCHOR_QUESTIONS, 1),
+        };
+    }
+    // When the user EXPLICITLY connected a folder/files to the chat (a Files↔Chat edge or a scope
+    // pill), they have already narrowed the search to a bounded area. The "too-generic" and
+    // "scope-empty" gates exist to stop vague questions burning budget over the broad workspace;
+    // keep those gates for workspace-root connections even when they were explicitly selected.
+    if (explicitConnectionIsReady(scope, intent)) {
+        return { state: "ready", clarification: undefined };
+    }
+    // Threshold is <= literal weight so a prompt yielding only `literal` anchors (weight 0.5,
+    // i.e. no quoted/path/identifier signal) requests clarification before any retrieval runs.
+    if (maxAnchorWeight(anchors) <= 0.5) {
+        return {
+            state: "clarification-needed",
+            clarification: buildClarification("too-generic", TOO_GENERIC_QUESTIONS, 1),
+        };
+    }
+    if (scope.relativePaths.length === 0 && anchors.length < 2) {
+        return {
+            state: "clarification-needed",
+            clarification: buildClarification("scope-empty", SCOPE_EMPTY_QUESTIONS, 2),
+        };
+    }
+    return { state: "ready", clarification: undefined };
+}
+function canonicalize(seed) {
+    // JSON.stringify with sorted keys via explicit ordering — never relies on object key order.
+    return JSON.stringify([
+        seed.scopeId,
+        seed.queryKind,
+        seed.queryText,
+        seed.retrievalIntent,
+        [...seed.anchorTerms].sort(),
+        [...seed.ringKinds].sort(),
+    ]);
+}
+function derivePlanId(seed) {
+    const hash = createHash("sha256").update(canonicalize(seed)).digest("hex");
+    return `pl-${hash.slice(0, 16)}`;
+}
+function resolveInputs(input, deps) {
+    return {
+        budget: input.budget ?? DEFAULT_EXPLORATION_BUDGET,
+        maxAnchors: input.maxAnchors ?? DEFAULT_MAX_ANCHORS,
+        nowMs: deps?.nowMs ?? Date.now,
+    };
+}
+function buildScopeInvalidPlan(input, resolved, classification) {
+    const clarification = buildClarification("scope-invalid", SCOPE_INVALID_QUESTIONS, 0);
+    const seed = {
+        scopeId: input.scope.scopeId,
+        queryKind: input.query.kind,
+        queryText: input.query.text,
+        retrievalIntent: classification.intent,
+        anchorTerms: [],
+        ringKinds: [],
+    };
+    return {
+        schemaVersion: CONNECTED_CONTEXT_SCHEMA_VERSION,
+        planId: derivePlanId(seed),
+        state: "scope-invalid",
+        retrievalIntent: classification.intent,
+        scope: input.scope,
+        query: input.query,
+        anchors: [],
+        rings: [],
+        budget: resolved.budget,
+        clarification,
+        createdAtMs: resolved.nowMs(),
+    };
+}
+export function createExplorationPlan(input, deps) {
+    const resolved = resolveInputs(input, deps);
+    const classification = classifyRetrievalIntent(input.query.text, input.scope);
+    const scopeResult = validateSelectedScope(input.scope);
+    if (!scopeResult.ok) {
+        return buildScopeInvalidPlan(input, resolved, classification);
+    }
+    const extraction = extractAnchors({
+        text: input.query.text,
+        maxAnchors: resolved.maxAnchors,
+    });
+    const decision = decideClarification(extraction.anchors, input.scope, classification.intent);
+    const rings = decision.state === "ready"
+        ? composeRings(extraction.anchors, input.scope, resolved.budget)
+        : [];
+    const seed = {
+        scopeId: input.scope.scopeId,
+        queryKind: input.query.kind,
+        queryText: input.query.text,
+        retrievalIntent: classification.intent,
+        anchorTerms: extraction.anchors.map((a) => a.term),
+        ringKinds: rings.map((r) => r.kind),
+    };
+    return {
+        schemaVersion: CONNECTED_CONTEXT_SCHEMA_VERSION,
+        planId: derivePlanId(seed),
+        state: decision.state,
+        retrievalIntent: classification.intent,
+        scope: input.scope,
+        query: input.query,
+        anchors: extraction.anchors,
+        rings,
+        budget: resolved.budget,
+        clarification: decision.clarification,
+        createdAtMs: resolved.nowMs(),
+    };
+}

package/dist/promptEnhancer/index.d.ts

@@ -0,0 +1,23 @@
+import { type PromptEnhancementWireRequest, type PromptEnhancementWireResponse } from "@oscharko-dev/keiko-contracts";
+import { type ConfiguredCapabilitySource, type GatewayConfig } from "@oscharko-dev/keiko-model-gateway";
+import type { PromptEnhancementRecordInput } from "@oscharko-dev/keiko-evidence";
+export declare class PromptEnhancementInputError extends Error {
+    readonly errors: readonly string[];
+    constructor(errors: readonly string[]);
+}
+export declare class PromptEnhancementCancelledError extends Error {
+    constructor();
+}
+export interface RunPromptEnhancementDeps {
+    readonly gatewayRoutingConfig: ConfiguredCapabilitySource | undefined;
+    readonly signal?: AbortSignal | undefined;
+}
+export type PromptEnhancementGatewayRoutingConfig = ConfiguredCapabilitySource;
+export declare function promptEnhancementGatewayRoutingConfig(config: GatewayConfig | undefined): PromptEnhancementGatewayRoutingConfig | undefined;
+export declare function runPromptEnhancement(request: PromptEnhancementWireRequest, deps: RunPromptEnhancementDeps): PromptEnhancementWireResponse;
+export declare function buildPromptEnhancementRecordInput(options: {
+    readonly rawInput: string;
+    readonly result: PromptEnhancementWireResponse;
+    readonly recordedAt: string;
+}): PromptEnhancementRecordInput;
+//# sourceMappingURL=index.d.ts.map

package/dist/promptEnhancer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/promptEnhancer/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAYL,KAAK,4BAA4B,EACjC,KAAK,6BAA6B,EAEnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAGL,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EACnB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,8BAA8B,CAAC;AAMjF,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,SAAgB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;gBACvB,MAAM,EAAE,SAAS,MAAM,EAAE;CAK7C;AAKD,qBAAa,+BAAgC,SAAQ,KAAK;;CAKzD;AAED,MAAM,WAAW,wBAAwB;IAGvC,QAAQ,CAAC,oBAAoB,EAAE,0BAA0B,GAAG,SAAS,CAAC;IAEtE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,MAAM,qCAAqC,GAAG,0BAA0B,CAAC;AAE/E,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,qCAAqC,GAAG,SAAS,CAQnD;AA8ND,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,4BAA4B,EACrC,IAAI,EAAE,wBAAwB,GAC7B,6BAA6B,CA6B/B;AAyCD,wBAAgB,iCAAiC,CAAC,OAAO,EAAE;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,GAAG,4BAA4B,CA4B/B"}