usesteady 0.1.0-alpha.1

package/dist/src/understand/context/types.js

@@ -0,0 +1,13 @@
+/**
+ * Context Alignment types.
+ *
+ * Context Alignment classifies whether an input makes sense to process given
+ * the current session context. It is the first subsystem of the Understand layer.
+ *
+ * Results:
+ *   aligned        — normal processable input
+ *   non_literal    — conversational/social input, not a task request
+ *   hard_mismatch  — input requires context that does not exist
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/understand/context/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/understand/context/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/src/understand/disambiguation/detectors/missing-context.detector.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Missing-context ambiguity detector.
+ *
+ * Detects inputs that contain underspecified references like "the file",
+ * "my project", "the config" without a concrete identifier.
+ *
+ * These inputs are ambiguous because it is not possible to determine
+ * which specific artifact is being referenced.
+ */
+import type { AmbiguityDetector } from "../types.js";
+export declare const missingContextDetector: AmbiguityDetector;
+//# sourceMappingURL=missing-context.detector.d.ts.map

package/dist/src/understand/disambiguation/detectors/missing-context.detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-context.detector.d.ts","sourceRoot":"","sources":["../../../../../src/understand/disambiguation/detectors/missing-context.detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwB,MAAM,aAAa,CAAC;AA4C3E,eAAO,MAAM,sBAAsB,EAAE,iBAiBpC,CAAC"}

package/dist/src/understand/disambiguation/detectors/missing-context.detector.js

@@ -0,0 +1,60 @@
+/**
+ * Missing-context ambiguity detector.
+ *
+ * Detects inputs that contain underspecified references like "the file",
+ * "my project", "the config" without a concrete identifier.
+ *
+ * These inputs are ambiguous because it is not possible to determine
+ * which specific artifact is being referenced.
+ */
+const MISSING_CONTEXT_TERMS = [
+    {
+        pattern: /\bthe\s+file\b(?!\s*["'])/i,
+        reference: "the file",
+        reason: "'the file' does not specify which file. Use a concrete path.",
+        options: [
+            'read "path/to/file"',
+            'replace "..." with "..." in "path/to/file"',
+        ],
+    },
+    {
+        pattern: /\bmy\s+project\b/i,
+        reference: "my project",
+        reason: "'my project' does not specify a path. Use a concrete workspace or file path.",
+        options: [
+            "read src/index.ts",
+            "list src/",
+        ],
+    },
+    {
+        pattern: /\bthe\s+config\b(?!\s*[".])/i,
+        reference: "the config",
+        reason: "'the config' does not specify which config file.",
+        options: [
+            'read "tsconfig.json"',
+            'read "package.json"',
+            'replace "..." with "..." in "config.json"',
+        ],
+    },
+];
+function findMatch(input) {
+    return MISSING_CONTEXT_TERMS.find((entry) => entry.pattern.test(input)) ?? null;
+}
+export const missingContextDetector = {
+    id: "missing_context",
+    priority: 30,
+    supports(input) {
+        return findMatch(input) !== null;
+    },
+    detect(input) {
+        const entry = findMatch(input);
+        if (entry === null)
+            return null;
+        return {
+            kind: "ambiguous",
+            reason: entry.reason,
+            options: entry.options,
+        };
+    },
+};
+//# sourceMappingURL=missing-context.detector.js.map

package/dist/src/understand/disambiguation/detectors/missing-context.detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-context.detector.js","sourceRoot":"","sources":["../../../../../src/understand/disambiguation/detectors/missing-context.detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,MAAM,qBAAqB,GAAuC;IAChE;QACE,OAAO,EAAE,4BAA4B;QACrC,SAAS,EAAE,UAAU;QACrB,MAAM,EAAE,8DAA8D;QACtE,OAAO,EAAE;YACP,qBAAqB;YACrB,4CAA4C;SAC7C;KACF;IACD;QACE,OAAO,EAAE,mBAAmB;QAC5B,SAAS,EAAE,YAAY;QACvB,MAAM,EAAE,8EAA8E;QACtF,OAAO,EAAE;YACP,mBAAmB;YACnB,WAAW;SACZ;KACF;IACD;QACE,OAAO,EAAE,8BAA8B;QACvC,SAAS,EAAE,YAAY;QACvB,MAAM,EAAE,kDAAkD;QAC1D,OAAO,EAAE;YACP,sBAAsB;YACtB,qBAAqB;YACrB,2CAA2C;SAC5C;KACF;CACF,CAAC;AAEF,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC;AAClF,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAsB;IACvD,EAAE,EAAE,iBAAiB;IACrB,QAAQ,EAAE,EAAE;IAEZ,QAAQ,CAAC,KAAa;QACpB,OAAO,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/src/understand/disambiguation/detectors/overloaded-term.detector.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Overloaded term detector.
+ *
+ * Detects inputs that contain terms with multiple well-known meanings
+ * in a development/tooling context.
+ *
+ * Examples:
+ *   "latest change"  → latest git commit? latest file modification? latest test run?
+ *   "change button"  → change button text? change button color? change button behavior?
+ */
+import type { AmbiguityDetector } from "../types.js";
+export declare const overloadedTermDetector: AmbiguityDetector;
+//# sourceMappingURL=overloaded-term.detector.d.ts.map

package/dist/src/understand/disambiguation/detectors/overloaded-term.detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overloaded-term.detector.d.ts","sourceRoot":"","sources":["../../../../../src/understand/disambiguation/detectors/overloaded-term.detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwB,MAAM,aAAa,CAAC;AAwC3E,eAAO,MAAM,sBAAsB,EAAE,iBAiBpC,CAAC"}

package/dist/src/understand/disambiguation/detectors/overloaded-term.detector.js

@@ -0,0 +1,57 @@
+/**
+ * Overloaded term detector.
+ *
+ * Detects inputs that contain terms with multiple well-known meanings
+ * in a development/tooling context.
+ *
+ * Examples:
+ *   "latest change"  → latest git commit? latest file modification? latest test run?
+ *   "change button"  → change button text? change button color? change button behavior?
+ */
+const OVERLOADED_TERMS = [
+    // NOTE: "latest change" / "show latest change" was removed from here.
+    // Completion handles it deterministically as `incomplete` with a specific
+    // next step ("show last commit"). Disambiguation should not intercept inputs
+    // that completion can resolve with a concrete path.
+    {
+        // Only fire when the user has NOT specified what to change (e.g. not "change button text"
+        // or "change button color") — those are partially resolved and fall through to guided_recovery.
+        pattern: /\bchange\s+(the\s+)?button\b(?!\s+(?:text|color|colour|label|style|class))/i,
+        term: "change button",
+        reason: "'change button' is ambiguous: text, color, behavior, or handler are all valid targets.",
+        options: [
+            'replace "old text" with "new text" in button component',
+            'replace "old-class" with "new-class" in button component',
+        ],
+    },
+    {
+        pattern: /\b(update|modify|change)\s+(the\s+)?config\b/i,
+        term: "change config",
+        reason: "'change config' is ambiguous: which config file and which field are unspecified.",
+        options: [
+            'replace "old-value" with "new-value" in config.json',
+            'replace "old-value" with "new-value" in tsconfig.json',
+        ],
+    },
+];
+function findMatch(input) {
+    return OVERLOADED_TERMS.find((entry) => entry.pattern.test(input)) ?? null;
+}
+export const overloadedTermDetector = {
+    id: "overloaded_term",
+    priority: 20,
+    supports(input) {
+        return findMatch(input) !== null;
+    },
+    detect(input) {
+        const entry = findMatch(input);
+        if (entry === null)
+            return null;
+        return {
+            kind: "ambiguous",
+            reason: entry.reason,
+            options: entry.options,
+        };
+    },
+};
+//# sourceMappingURL=overloaded-term.detector.js.map

package/dist/src/understand/disambiguation/detectors/overloaded-term.detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overloaded-term.detector.js","sourceRoot":"","sources":["../../../../../src/understand/disambiguation/detectors/overloaded-term.detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,MAAM,gBAAgB,GAAuC;IAC3D,sEAAsE;IACtE,0EAA0E;IAC1E,6EAA6E;IAC7E,oDAAoD;IACpD;QACE,0FAA0F;QAC1F,gGAAgG;QAChG,OAAO,EAAE,6EAA6E;QACtF,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,wFAAwF;QAChG,OAAO,EAAE;YACP,wDAAwD;YACxD,0DAA0D;SAC3D;KACF;IACD;QACE,OAAO,EAAE,+CAA+C;QACxD,IAAI,EAAE,eAAe;QACrB,MAAM,EAAE,kFAAkF;QAC1F,OAAO,EAAE;YACP,qDAAqD;YACrD,uDAAuD;SACxD;KACF;CACF,CAAC;AAEF,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC;AAC7E,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAsB;IACvD,EAAE,EAAE,iBAAiB;IACrB,QAAQ,EAAE,EAAE;IAEZ,QAAQ,CAAC,KAAa;QACpB,OAAO,SAAS,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/src/understand/disambiguation/detectors/typo-adjacent.detector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Typo-adjacent ambiguity detector.
+ *
+ * Detects inputs where a word closely resembles another word with a
+ * significantly different meaning in a UseSteady context.
+ *
+ * This is NOT a generic spellchecker. Only well-known, high-risk pairs
+ * are registered. The pair must change the semantic meaning materially.
+ *
+ * Example pair: "loops" vs "loopholes"
+ *   "fix the loops in the code" → code loop (clear programming construct)
+ *   "loops" near "approval"/"rule" → might mean loopholes (policy bypass)
+ */
+import type { AmbiguityDetector } from "../types.js";
+export declare const typoAdjacentDetector: AmbiguityDetector;
+//# sourceMappingURL=typo-adjacent.detector.d.ts.map

package/dist/src/understand/disambiguation/detectors/typo-adjacent.detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typo-adjacent.detector.d.ts","sourceRoot":"","sources":["../../../../../src/understand/disambiguation/detectors/typo-adjacent.detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAwB,MAAM,aAAa,CAAC;AAoC3E,eAAO,MAAM,oBAAoB,EAAE,iBAiBlC,CAAC"}

package/dist/src/understand/disambiguation/detectors/typo-adjacent.detector.js

@@ -0,0 +1,56 @@
+/**
+ * Typo-adjacent ambiguity detector.
+ *
+ * Detects inputs where a word closely resembles another word with a
+ * significantly different meaning in a UseSteady context.
+ *
+ * This is NOT a generic spellchecker. Only well-known, high-risk pairs
+ * are registered. The pair must change the semantic meaning materially.
+ *
+ * Example pair: "loops" vs "loopholes"
+ *   "fix the loops in the code" → code loop (clear programming construct)
+ *   "loops" near "approval"/"rule" → might mean loopholes (policy bypass)
+ */
+const TYPO_ADJACENT_PAIRS = [
+    {
+        // "loops" near policy/rule/approval language → could mean loopholes
+        pattern: /\bloops?\b.{0,40}(rule|policy|approval|bypass)/i,
+        word: "loops",
+        alternatives: [
+            "code loops (programming construct)",
+            "loopholes (policy bypass attempt — blocked)",
+        ],
+        reason: "'loops' near policy language may mean code loops or loopholes.",
+    },
+    {
+        // Standalone "loops" could go either way in ambiguous context
+        pattern: /\b(approval|rule|policy).{0,40}\bloops?\b/i,
+        word: "loops",
+        alternatives: [
+            "code loops (programming construct)",
+            "loopholes (policy bypass attempt — blocked)",
+        ],
+        reason: "'loops' near policy language may mean code loops or loopholes.",
+    },
+];
+function matches(input) {
+    return TYPO_ADJACENT_PAIRS.find((pair) => pair.pattern.test(input)) ?? null;
+}
+export const typoAdjacentDetector = {
+    id: "typo_adjacent",
+    priority: 10,
+    supports(input) {
+        return matches(input) !== null;
+    },
+    detect(input) {
+        const pair = matches(input);
+        if (pair === null)
+            return null;
+        return {
+            kind: "ambiguous",
+            reason: pair.reason,
+            options: pair.alternatives,
+        };
+    },
+};
+//# sourceMappingURL=typo-adjacent.detector.js.map

package/dist/src/understand/disambiguation/detectors/typo-adjacent.detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typo-adjacent.detector.js","sourceRoot":"","sources":["../../../../../src/understand/disambiguation/detectors/typo-adjacent.detector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAWH,MAAM,mBAAmB,GAAiC;IACxD;QACE,oEAAoE;QACpE,OAAO,EAAE,iDAAiD;QAC1D,IAAI,EAAE,OAAO;QACb,YAAY,EAAE;YACZ,oCAAoC;YACpC,6CAA6C;SAC9C;QACD,MAAM,EAAE,gEAAgE;KACzE;IACD;QACE,8DAA8D;QAC9D,OAAO,EAAE,4CAA4C;QACrD,IAAI,EAAE,OAAO;QACb,YAAY,EAAE;YACZ,oCAAoC;YACpC,6CAA6C;SAC9C;QACD,MAAM,EAAE,gEAAgE;KACzE;CACF,CAAC;AAEF,SAAS,OAAO,CAAC,KAAa;IAC5B,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,EAAE,EAAE,eAAe;IACnB,QAAQ,EAAE,EAAE;IAEZ,QAAQ,CAAC,KAAa;QACpB,OAAO,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;IACjC,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC/B,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,YAAY;SAC3B,CAAC;IACJ,CAAC;CACF,CAAC"}

package/dist/src/understand/disambiguation/registry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Disambiguation detector registry.
+ *
+ * Detectors are sorted by priority ascending (lower number = runs first).
+ */
+import type { AmbiguityDetector } from "./types.js";
+export declare function getDisambiguationDetectors(): ReadonlyArray<AmbiguityDetector>;
+/**
+ * Run all disambiguation detectors in priority order.
+ * Returns the first non-null result, or { kind: "unknown" } if none match.
+ */
+import type { DisambiguationResult } from "./types.js";
+export declare function runDisambiguation(input: string): DisambiguationResult;
+//# sourceMappingURL=registry.d.ts.map

package/dist/src/understand/disambiguation/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../../src/understand/disambiguation/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAWpD,wBAAgB,0BAA0B,IAAI,aAAa,CAAC,iBAAiB,CAAC,CAE7E;AAED;;;GAGG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,CAQrE"}

package/dist/src/understand/disambiguation/registry.js

@@ -0,0 +1,27 @@
+/**
+ * Disambiguation detector registry.
+ *
+ * Detectors are sorted by priority ascending (lower number = runs first).
+ */
+import { typoAdjacentDetector } from "./detectors/typo-adjacent.detector.js";
+import { overloadedTermDetector } from "./detectors/overloaded-term.detector.js";
+import { missingContextDetector } from "./detectors/missing-context.detector.js";
+const REGISTERED_DETECTORS = [
+    typoAdjacentDetector,
+    overloadedTermDetector,
+    missingContextDetector,
+].sort((a, b) => a.priority - b.priority);
+export function getDisambiguationDetectors() {
+    return REGISTERED_DETECTORS;
+}
+export function runDisambiguation(input) {
+    for (const detector of getDisambiguationDetectors()) {
+        if (detector.supports(input)) {
+            const result = detector.detect(input);
+            if (result !== null)
+                return result;
+        }
+    }
+    return { kind: "unknown" };
+}
+//# sourceMappingURL=registry.js.map

package/dist/src/understand/disambiguation/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../../../src/understand/disambiguation/registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,yCAAyC,CAAC;AAEjF,MAAM,oBAAoB,GAAqC;IAC7D,oBAAoB;IACpB,sBAAsB;IACtB,sBAAsB;CACvB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;AAE1C,MAAM,UAAU,0BAA0B;IACxC,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAQD,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,KAAK,MAAM,QAAQ,IAAI,0BAA0B,EAAE,EAAE,CAAC;QACpD,IAAI,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC"}

package/dist/src/understand/disambiguation/types.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Intent Disambiguation types.
+ *
+ * Disambiguation identifies whether an input has a single clear meaning
+ * or multiple competing interpretations.
+ *
+ * Results:
+ *   clear      — single unambiguous meaning; normalized form provided
+ *   ambiguous  — multiple valid interpretations; bounded options provided
+ *   unknown    — no registered detector matched; no interpretation available
+ *
+ * Detectors may NOT silently rewrite input. If ambiguous, they MUST return options.
+ */
+export type DisambiguationResult = {
+    readonly kind: "clear";
+    readonly normalized: string;
+} | {
+    readonly kind: "ambiguous";
+    readonly reason: string;
+    readonly options: readonly string[];
+} | {
+    readonly kind: "unknown";
+};
+/**
+ * An AmbiguityDetector examines an input and returns a DisambiguationResult
+ * if it recognizes a pattern, or null if the input is outside its scope.
+ */
+export type AmbiguityDetector = {
+    readonly id: string;
+    readonly priority: number;
+    supports(input: string): boolean;
+    detect(input: string): DisambiguationResult | null;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/understand/disambiguation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/understand/disambiguation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC5F;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAAC;CACpD,CAAC"}

package/dist/src/understand/disambiguation/types.js

@@ -0,0 +1,15 @@
+/**
+ * Intent Disambiguation types.
+ *
+ * Disambiguation identifies whether an input has a single clear meaning
+ * or multiple competing interpretations.
+ *
+ * Results:
+ *   clear      — single unambiguous meaning; normalized form provided
+ *   ambiguous  — multiple valid interpretations; bounded options provided
+ *   unknown    — no registered detector matched; no interpretation available
+ *
+ * Detectors may NOT silently rewrite input. If ambiguous, they MUST return options.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/understand/disambiguation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/understand/disambiguation/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/src/understand/intent-interpretation/intent-interpretation.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Intent Interpretation Bridge — main entry point.
+ *
+ * ── What this layer is ────────────────────────────────────────────────────────
+ *
+ * The Intent Interpretation Bridge sits between Completion and Response Planner.
+ * It runs ONLY when CompletionResult.kind === "guided_recovery" — i.e. the input
+ * is safe, not executable yet, but a safe next-step path exists.
+ *
+ * Its job is to make guided recovery feel more helpful without guessing.
+ * It classifies the broad category of what the user appears to be trying to do,
+ * then rewrites guidance labels to be context-aware.
+ *
+ * ── Pipeline position ─────────────────────────────────────────────────────────
+ *
+ *   Completion
+ *       ↓  (guided_recovery only)
+ *   Intent Interpretation Bridge      ← this module
+ *       ↓
+ *   Response Planner
+ *
+ * ── Hard invariant (locked) ──────────────────────────────────────────────────
+ *
+ *   Interpretation can improve guidance, but it can never manufacture executability.
+ *
+ *   This means the bridge:
+ *     MAY  → classify broad intent (visual_color, text_change, config_change, workflow_operation)
+ *     MAY  → rewrite step labels with category-aware language
+ *     MAY  → add rationale for "read first" steps
+ *     MAY  → run for both guided_recovery and incomplete completions (both become guide mode)
+ *     MUST NOT → guess file paths
+ *     MUST NOT → guess current or new values
+ *     MUST NOT → turn guided_recovery or incomplete into complete
+ *     MUST NOT → change the mode decision
+ *     MUST NOT → downgrade safety
+ *
+ * ── Two interpretation families (keep separate) ───────────────────────────────
+ *
+ *   Change Interpretation (src/understand/interpretation/)
+ *     → For executable, structured patch commands: replace "X" with "Y" in <file>
+ *     → Runs when mode === "execute", describes what the change means after the fact
+ *
+ *   Intent Interpretation Bridge (this module)
+ *     → For vague, incomplete requests: "make the button blue"
+ *     → Runs when mode === "guide" (guided_recovery), describes what the user
+ *       appears to be trying to do
+ */
+import type { IntentInterpretation, GuidancePayload } from "./types.js";
+import type { CompletionResult } from "../completion/types.js";
+import type { UnderstandContext } from "../shared/types.js";
+/**
+ * Run the interpreter registry against the input.
+ *
+ * Returns the first safe, non-null interpretation (registry is priority-ordered).
+ * Returns null if no interpreter claims the input.
+ *
+ * CONTRACT: null means "no safe classification exists" — not "unknown".
+ * The `unknown` category exists in the type system but the registry never
+ * returns it; callers should treat null as "no interpretation available."
+ */
+export declare function runIntentInterpretation(input: string): IntentInterpretation | null;
+/**
+ * Bridge function: call after completion returns guided_recovery or incomplete.
+ *
+ * Both guided_recovery and incomplete lead to `guide` response mode, so both
+ * can benefit from interpretation-enriched step labels.
+ *
+ * @param input      Original user input string
+ * @param completion The completion result — acts on guided_recovery and incomplete
+ * @param _ctx       UnderstandContext — reserved for future context-aware enrichment
+ * @returns          GuidancePayload for guided_recovery / incomplete; null for all other kinds
+ *
+ * When interpretation is found:
+ *   → attaches interpretation to guidance
+ *   → rewrites nextSteps labels to be category-aware
+ *   → never fills in missing[] values
+ *
+ * When no interpretation is found:
+ *   → returns original guidance unchanged (no interpretation field attached)
+ *
+ * Hard invariant:
+ *   Interpretation can improve guidance, but it can never manufacture executability.
+ *   This function MUST NOT return complete or change the mode decision.
+ */
+export declare function enrichGuidance(input: string, completion: CompletionResult, _ctx: UnderstandContext): GuidancePayload | null;
+//# sourceMappingURL=intent-interpretation.d.ts.map

package/dist/src/understand/intent-interpretation/intent-interpretation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-interpretation.d.ts","sourceRoot":"","sources":["../../../../src/understand/intent-interpretation/intent-interpretation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAsB,MAAM,wBAAwB,CAAC;AACnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAK5D;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAQlF;AA2DD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,iBAAiB,GACtB,eAAe,GAAG,IAAI,CAiBxB"}

package/dist/src/understand/intent-interpretation/intent-interpretation.js

@@ -0,0 +1,141 @@
+/**
+ * Intent Interpretation Bridge — main entry point.
+ *
+ * ── What this layer is ────────────────────────────────────────────────────────
+ *
+ * The Intent Interpretation Bridge sits between Completion and Response Planner.
+ * It runs ONLY when CompletionResult.kind === "guided_recovery" — i.e. the input
+ * is safe, not executable yet, but a safe next-step path exists.
+ *
+ * Its job is to make guided recovery feel more helpful without guessing.
+ * It classifies the broad category of what the user appears to be trying to do,
+ * then rewrites guidance labels to be context-aware.
+ *
+ * ── Pipeline position ─────────────────────────────────────────────────────────
+ *
+ *   Completion
+ *       ↓  (guided_recovery only)
+ *   Intent Interpretation Bridge      ← this module
+ *       ↓
+ *   Response Planner
+ *
+ * ── Hard invariant (locked) ──────────────────────────────────────────────────
+ *
+ *   Interpretation can improve guidance, but it can never manufacture executability.
+ *
+ *   This means the bridge:
+ *     MAY  → classify broad intent (visual_color, text_change, config_change, workflow_operation)
+ *     MAY  → rewrite step labels with category-aware language
+ *     MAY  → add rationale for "read first" steps
+ *     MAY  → run for both guided_recovery and incomplete completions (both become guide mode)
+ *     MUST NOT → guess file paths
+ *     MUST NOT → guess current or new values
+ *     MUST NOT → turn guided_recovery or incomplete into complete
+ *     MUST NOT → change the mode decision
+ *     MUST NOT → downgrade safety
+ *
+ * ── Two interpretation families (keep separate) ───────────────────────────────
+ *
+ *   Change Interpretation (src/understand/interpretation/)
+ *     → For executable, structured patch commands: replace "X" with "Y" in <file>
+ *     → Runs when mode === "execute", describes what the change means after the fact
+ *
+ *   Intent Interpretation Bridge (this module)
+ *     → For vague, incomplete requests: "make the button blue"
+ *     → Runs when mode === "guide" (guided_recovery), describes what the user
+ *       appears to be trying to do
+ */
+import { ALL_INTENT_INTERPRETERS } from "./registry.js";
+// ─── runIntentInterpretation ──────────────────────────────────────────────────
+/**
+ * Run the interpreter registry against the input.
+ *
+ * Returns the first safe, non-null interpretation (registry is priority-ordered).
+ * Returns null if no interpreter claims the input.
+ *
+ * CONTRACT: null means "no safe classification exists" — not "unknown".
+ * The `unknown` category exists in the type system but the registry never
+ * returns it; callers should treat null as "no interpretation available."
+ */
+export function runIntentInterpretation(input) {
+    for (const interpreter of ALL_INTENT_INTERPRETERS) {
+        if (interpreter.matches(input)) {
+            const result = interpreter.interpret(input);
+            if (result !== null)
+                return result;
+        }
+    }
+    return null;
+}
+const ENRICHED_STEP_LABELS = {
+    visual_color: {
+        read_first: 'Read the component file first to find the current color value: read "<file>"',
+        use_exact_format: 'Then patch it: replace "<current color>" with "<new color>" in "<file>"',
+        add_missing_field: "Add the specific color value that should change.",
+    },
+    text_change: {
+        read_first: 'Read the file first to find the current text: read "<file>"',
+        use_exact_format: 'Then patch it: replace "<current text>" with "<new text>" in "<file>"',
+        add_missing_field: "Add the specific text string that should change.",
+    },
+    config_change: {
+        read_first: 'Read the config file first to find the current setting: read "<file>"',
+        use_exact_format: 'Then update the config: replace "<current value>" with "<new value>" in "<file>"',
+        add_missing_field: "Add the specific configuration value that should change.",
+    },
+    workflow_operation: {
+        read_first: "Review the current state before committing: show git status",
+        use_exact_format: 'Then commit with a descriptive message: commit "<message>"',
+        add_missing_field: "Add a specific commit message that describes the change.",
+    },
+};
+function enrichNextSteps(steps, interpretation) {
+    const labels = ENRICHED_STEP_LABELS[interpretation.category];
+    if (labels === undefined)
+        return steps;
+    return steps.map((step) => {
+        const enriched = labels[step.type];
+        return enriched !== undefined ? { ...step, label: enriched } : step;
+    });
+}
+// ─── enrichGuidance ────────────────────────────────────────────────────────────
+/**
+ * Bridge function: call after completion returns guided_recovery or incomplete.
+ *
+ * Both guided_recovery and incomplete lead to `guide` response mode, so both
+ * can benefit from interpretation-enriched step labels.
+ *
+ * @param input      Original user input string
+ * @param completion The completion result — acts on guided_recovery and incomplete
+ * @param _ctx       UnderstandContext — reserved for future context-aware enrichment
+ * @returns          GuidancePayload for guided_recovery / incomplete; null for all other kinds
+ *
+ * When interpretation is found:
+ *   → attaches interpretation to guidance
+ *   → rewrites nextSteps labels to be category-aware
+ *   → never fills in missing[] values
+ *
+ * When no interpretation is found:
+ *   → returns original guidance unchanged (no interpretation field attached)
+ *
+ * Hard invariant:
+ *   Interpretation can improve guidance, but it can never manufacture executability.
+ *   This function MUST NOT return complete or change the mode decision.
+ */
+export function enrichGuidance(input, completion, _ctx) {
+    if (completion.kind !== "guided_recovery" && completion.kind !== "incomplete")
+        return null;
+    const interpretation = runIntentInterpretation(input);
+    if (interpretation === null) {
+        return {
+            missing: completion.missing,
+            nextSteps: completion.nextSteps,
+        };
+    }
+    return {
+        missing: completion.missing,
+        nextSteps: enrichNextSteps(completion.nextSteps, interpretation),
+        interpretation,
+    };
+}
+//# sourceMappingURL=intent-interpretation.js.map

package/dist/src/understand/intent-interpretation/intent-interpretation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent-interpretation.js","sourceRoot":"","sources":["../../../../src/understand/intent-interpretation/intent-interpretation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,OAAO,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAExD,iFAAiF;AAEjF;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,KAAK,MAAM,WAAW,IAAI,uBAAuB,EAAE,CAAC;QAClD,IAAI,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;QACrC,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAUD,MAAM,oBAAoB,GAAyC;IACjE,YAAY,EAAE;QACZ,UAAU,EACR,8EAA8E;QAChF,gBAAgB,EACd,yEAAyE;QAC3E,iBAAiB,EACf,kDAAkD;KACrD;IACD,WAAW,EAAE;QACX,UAAU,EACR,6DAA6D;QAC/D,gBAAgB,EACd,uEAAuE;QACzE,iBAAiB,EACf,kDAAkD;KACrD;IACD,aAAa,EAAE;QACb,UAAU,EACR,uEAAuE;QACzE,gBAAgB,EACd,kFAAkF;QACpF,iBAAiB,EACf,0DAA0D;KAC7D;IACD,kBAAkB,EAAE;QAClB,UAAU,EACR,6DAA6D;QAC/D,gBAAgB,EACd,4DAA4D;QAC9D,iBAAiB,EACf,0DAA0D;KAC7D;CACF,CAAC;AAEF,SAAS,eAAe,CACtB,KAAoC,EACpC,cAAoC;IAEpC,MAAM,MAAM,GAAG,oBAAoB,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAC7D,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACvC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kFAAkF;AAElF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAa,EACb,UAA4B,EAC5B,IAAuB;IAEvB,IAAI,UAAU,CAAC,IAAI,KAAK,iBAAiB,IAAI,UAAU,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,IAAI,CAAC;IAE3F,MAAM,cAAc,GAAG,uBAAuB,CAAC,KAAK,CAAC,CAAC;IAEtD,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO;YACL,OAAO,EAAI,UAAU,CAAC,OAAO;YAC7B,SAAS,EAAE,UAAU,CAAC,SAAS;SAChC,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAS,UAAU,CAAC,OAAO;QAClC,SAAS,EAAO,eAAe,CAAC,UAAU,CAAC,SAAS,EAAE,cAAc,CAAC;QACrE,cAAc;KACf,CAAC;AACJ,CAAC"}

package/dist/src/understand/intent-interpretation/interpreters/color-intent.interpreter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Color intent interpreter.
+ *
+ * Scope: detect inputs that appear to be visual/color style changes.
+ * Priority 20 — runs after config (which owns toggle/enable verbs).
+ *
+ * Color signal words: named colors, comparative terms (darker/lighter), and
+ * the generic words "color" / "colour".
+ *
+ * UI target terms: component names that contextualize the color signal and
+ * raise confidence from "low" (color word only) to "medium" (color + target).
+ *
+ * Noun-context guard — DARK MODE:
+ *   "dark mode" as a compound noun refers to a UI theme variant, not a shade/color
+ *   change. The word "dark" alone would otherwise trigger this interpreter (false
+ *   positive). If the input contains the phrase "dark mode", the interpreter returns
+ *   null and yields to the config interpreter or bridge silence.
+ *
+ *   Examples of the guard in action:
+ *     "I want to add dark mode"   → null  (feature request, not color change)
+ *     "add a dark mode option"    → null  (same: feature request)
+ *     "make the background dark"  → visual_color  (shade change — guard does NOT fire)
+ *     "darker shade of blue"      → visual_color  (no "dark mode" phrase — guard OK)
+ *     "enable dark mode"          → config_change (config fires first at priority 10)
+ *
+ * Language contract:
+ *   Summary says "appears to be a color/style change request" — medium confidence.
+ *   Never says "background becomes blue" or infers the component type.
+ *   basis[] reports the exact matched token so the result is inspectable.
+ */
+import type { IntentInterpreter } from "../types.js";
+export declare const colorIntentInterpreter: IntentInterpreter;
+//# sourceMappingURL=color-intent.interpreter.d.ts.map