usesteady 0.1.0-alpha.1

package/dist/src/understand/completion/completion.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Completion orchestrator.
+ *
+ * CONTRACT (written, not implied):
+ *   1. Completion is the sole authority on executability.
+ *   2. Disambiguation returning `unknown` does NOT block completion from
+ *      returning `complete`. The pipeline always reaches completion.
+ *   3. Context-dependent executable inputs ("run again") are resolved HERE
+ *      when ctx provides the required data. Completion receives full context.
+ *   4. Completion never guesses missing values. It returns guided_recovery or
+ *      incomplete with explicit next steps when values are absent.
+ *
+ * Flow:
+ *   1. Iterate rules in priority order.
+ *   2. First matching non-null result is returned.
+ *   3. If no rule matches, fallback guided_recovery is returned.
+ *
+ * The fallback ensures the function always returns a result — there is no
+ * "completion does not know" state. Unknown inputs become guided_recovery.
+ */
+import type { CompletionResult } from "./types.js";
+import type { UnderstandContext } from "../shared/types.js";
+import { ALL_COMPLETION_RULES } from "./rules.js";
+export declare function runCompletion(input: string, ctx: UnderstandContext): CompletionResult;
+export { ALL_COMPLETION_RULES as getCompletionRules };
+//# sourceMappingURL=completion.d.ts.map

package/dist/src/understand/completion/completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.d.ts","sourceRoot":"","sources":["../../../../src/understand/completion/completion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,iBAAiB,GACrB,gBAAgB,CAqBlB;AAED,OAAO,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,CAAC"}

package/dist/src/understand/completion/completion.js

@@ -0,0 +1,45 @@
+/**
+ * Completion orchestrator.
+ *
+ * CONTRACT (written, not implied):
+ *   1. Completion is the sole authority on executability.
+ *   2. Disambiguation returning `unknown` does NOT block completion from
+ *      returning `complete`. The pipeline always reaches completion.
+ *   3. Context-dependent executable inputs ("run again") are resolved HERE
+ *      when ctx provides the required data. Completion receives full context.
+ *   4. Completion never guesses missing values. It returns guided_recovery or
+ *      incomplete with explicit next steps when values are absent.
+ *
+ * Flow:
+ *   1. Iterate rules in priority order.
+ *   2. First matching non-null result is returned.
+ *   3. If no rule matches, fallback guided_recovery is returned.
+ *
+ * The fallback ensures the function always returns a result — there is no
+ * "completion does not know" state. Unknown inputs become guided_recovery.
+ */
+import { ALL_COMPLETION_RULES } from "./rules.js";
+export function runCompletion(input, ctx) {
+    for (const rule of ALL_COMPLETION_RULES) {
+        if (rule.matches(input, ctx)) {
+            const result = rule.evaluate(input, ctx);
+            if (result !== null)
+                return result;
+        }
+    }
+    // Fallback: no rule matched.
+    // Input is unrecognised — guide with explicit format options.
+    return {
+        kind: "guided_recovery",
+        reason: "Request does not match a supported deterministic format.",
+        missing: ["specific action", "target"],
+        nextSteps: [
+            { type: "use_exact_format", label: 'replace "" with "" in ""' },
+            { type: "use_exact_format", label: 'commit ""' },
+            { type: "use_exact_format", label: "run tests" },
+            { type: "use_exact_format", label: 'read ""' },
+        ],
+    };
+}
+export { ALL_COMPLETION_RULES as getCompletionRules };
+//# sourceMappingURL=completion.js.map

package/dist/src/understand/completion/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../../../src/understand/completion/completion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,UAAU,aAAa,CAC3B,KAAa,EACb,GAAsB;IAEtB,KAAK,MAAM,IAAI,IAAI,oBAAoB,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACzC,IAAI,MAAM,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;QACrC,CAAC;IACH,CAAC;IAED,6BAA6B;IAC7B,8DAA8D;IAC9D,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,MAAM,EAAE,0DAA0D;QAClE,OAAO,EAAE,CAAC,iBAAiB,EAAE,QAAQ,CAAC;QACtC,SAAS,EAAE;YACT,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,0BAA0B,EAAE;YAC/D,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,EAAE;YAChD,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,WAAW,EAAE;YAChD,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,SAAS,EAAE;SAC/C;KACF,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,oBAAoB,IAAI,kBAAkB,EAAE,CAAC"}

package/dist/src/understand/completion/rules.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Completion rules registry.
+ *
+ * Each rule owns a named, prioritised, testable pattern.
+ * Priority: lower number = runs first.
+ *
+ * Groups (by priority band):
+ *   1–20   Context-aware complete rules (require prior session)
+ *  21–50   Stateless complete rules (exact deterministic format)
+ *  51–70   Incomplete rules (intent clear, field missing)
+ *  71–100  Guided-recovery rules (vague intent)
+ *
+ * Rules MUST NOT guess or infer values.
+ * Rules MUST return null if the input is outside their scope.
+ */
+import type { CompletionRule } from "./types.js";
+/**
+ * "run again" / "redo" when a prior session with a known last input exists.
+ * Resolves the context-dependent request to complete — the effective command
+ * is ctx.lastInput, which the caller must use for execution.
+ */
+export declare const rerunPreviousRule: CompletionRule;
+export declare const runTestsRule: CompletionRule;
+export declare const readFileRule: CompletionRule;
+export declare const replaceExactRule: CompletionRule;
+export declare const commitWithMessageRule: CompletionRule;
+export declare const patchStructuredRule: CompletionRule;
+export declare const gitOpsRule: CompletionRule;
+/**
+ * "change bg-blue-500 to bg-red-500" — both old and new values are explicit
+ * (CSS class-name tokens), but a file path is missing. This is incomplete,
+ * not vague: the user has specified what to change but not where.
+ *
+ * Pattern: change / set <css-class> to <css-class>
+ * The CSS class token regex matches e.g. bg-red-500, text-blue-700, p-4, etc.
+ * Both sides of "to" must look like CSS tokens; otherwise falls through.
+ */
+export declare const changeCssClassMissingFileRule: CompletionRule;
+/**
+ * "commit my changes", "commit everything", "commit this" — intent is commit,
+ * message is missing. Not vague; just incomplete.
+ */
+export declare const commitMissingMessageRule: CompletionRule;
+/**
+ * "show latest change", "show recent change" — intent is show git history,
+ * but the exact target is underspecified. Missing: what specifically to show.
+ */
+export declare const showLatestChangeRule: CompletionRule;
+export declare const vagueStyleChangeRule: CompletionRule;
+/**
+ * "patch the file", "apply the patch" without structured params.
+ * Patch intent is present, but required fields are absent.
+ */
+export declare const vaguePatchRule: CompletionRule;
+/**
+ * "update the styles", "fix the bug", "improve the performance" — generic
+ * imperative with no concrete target. Too vague to prepare any deterministic action.
+ */
+export declare const vagueTaskRule: CompletionRule;
+export declare const ALL_COMPLETION_RULES: ReadonlyArray<CompletionRule>;
+//# sourceMappingURL=rules.d.ts.map

package/dist/src/understand/completion/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../../../src/understand/completion/rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,YAAY,CAAC;AAInE;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAe/B,CAAC;AAIF,eAAO,MAAM,YAAY,EAAE,cAS1B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,cAS1B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAS9B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,cASnC,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,cASjC,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cASxB,CAAC;AAKF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,EAAE,cAiB3C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,cAiBtC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,cAgBlC,CAAC;AAoBF,eAAO,MAAM,oBAAoB,EAAE,cAmBlC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,cAiB5B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,cAiB3B,CAAC;AAIF,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,cAAc,CActB,CAAC"}

package/dist/src/understand/completion/rules.js

@@ -0,0 +1,268 @@
+/**
+ * Completion rules registry.
+ *
+ * Each rule owns a named, prioritised, testable pattern.
+ * Priority: lower number = runs first.
+ *
+ * Groups (by priority band):
+ *   1–20   Context-aware complete rules (require prior session)
+ *  21–50   Stateless complete rules (exact deterministic format)
+ *  51–70   Incomplete rules (intent clear, field missing)
+ *  71–100  Guided-recovery rules (vague intent)
+ *
+ * Rules MUST NOT guess or infer values.
+ * Rules MUST return null if the input is outside their scope.
+ */
+// ─── Context-aware complete rules (priority 1–20) ─────────────────────────────
+/**
+ * "run again" / "redo" when a prior session with a known last input exists.
+ * Resolves the context-dependent request to complete — the effective command
+ * is ctx.lastInput, which the caller must use for execution.
+ */
+export const rerunPreviousRule = {
+    id: "rerun_previous",
+    priority: 5,
+    matches(input, ctx) {
+        return (/\b(run\s+again|redo|repeat\s+last)\b/i.test(input) &&
+            ctx.hasPriorSession === true &&
+            ctx.lastInput !== undefined &&
+            ctx.lastInput.length > 0);
+    },
+    evaluate(_input, ctx) {
+        if (!ctx.hasPriorSession || !ctx.lastInput)
+            return null;
+        return { kind: "complete" };
+    },
+};
+// ─── Stateless complete rules (priority 21–50) ────────────────────────────────
+export const runTestsRule = {
+    id: "run_tests",
+    priority: 21,
+    matches(input) {
+        return /^\s*(run\s+(?:the\s+)?(?:tests?|test\s+suite|unit\s+tests?|specs?|vitest)|vitest)\s*$/i.test(input);
+    },
+    evaluate() {
+        return { kind: "complete" };
+    },
+};
+export const readFileRule = {
+    id: "read_file",
+    priority: 22,
+    matches(input) {
+        return /^\s*read\s+["']?[^\s"']+/i.test(input);
+    },
+    evaluate() {
+        return { kind: "complete" };
+    },
+};
+export const replaceExactRule = {
+    id: "replace_exact",
+    priority: 23,
+    matches(input) {
+        return /^\s*replace\s+"[^"]+"\s+with\s+"[^"]+"\s+in\s+/i.test(input);
+    },
+    evaluate() {
+        return { kind: "complete" };
+    },
+};
+export const commitWithMessageRule = {
+    id: "commit_with_message",
+    priority: 24,
+    matches(input) {
+        return /^\s*(commit|git\s+commit)\s+"[^"]+"\s*$/i.test(input);
+    },
+    evaluate() {
+        return { kind: "complete" };
+    },
+};
+export const patchStructuredRule = {
+    id: "patch_structured",
+    priority: 25,
+    matches(input) {
+        return /^\s*patch\s+\S+\s+search="[^"]+"\s+replace="[^"]+"/i.test(input);
+    },
+    evaluate() {
+        return { kind: "complete" };
+    },
+};
+export const gitOpsRule = {
+    id: "git_ops",
+    priority: 26,
+    matches(input) {
+        return /^\s*(git\s+status|show\s+git\s+status|git\s+log\b|git\s+show\b|show\s+last\s+commit|show\s+(recent|last|latest)\s+commits?|show\s+commit\b|list\s*$|ls\b|stat\b|info\b)/i.test(input);
+    },
+    evaluate() {
+        return { kind: "complete" };
+    },
+};
+// ─── Incomplete rules (priority 51–70) ────────────────────────────────────────
+// Intent is clear; a specific required field is absent.
+/**
+ * "change bg-blue-500 to bg-red-500" — both old and new values are explicit
+ * (CSS class-name tokens), but a file path is missing. This is incomplete,
+ * not vague: the user has specified what to change but not where.
+ *
+ * Pattern: change / set <css-class> to <css-class>
+ * The CSS class token regex matches e.g. bg-red-500, text-blue-700, p-4, etc.
+ * Both sides of "to" must look like CSS tokens; otherwise falls through.
+ */
+export const changeCssClassMissingFileRule = {
+    id: "change_css_class_missing_file",
+    priority: 51,
+    matches(input) {
+        return /\b(change|set)\s+[a-z][\w-]*-\d+\s+to\s+[a-z][\w-]*-\d+\b/i.test(input);
+    },
+    evaluate() {
+        return {
+            kind: "incomplete",
+            reason: "The old and new values are clear, but a file path is required.",
+            missing: ["file path"],
+            nextSteps: [
+                { type: "read_first", label: 'read ""' },
+                { type: "use_exact_format", label: 'replace "" with "" in ""' },
+            ],
+        };
+    },
+};
+/**
+ * "commit my changes", "commit everything", "commit this" — intent is commit,
+ * message is missing. Not vague; just incomplete.
+ */
+export const commitMissingMessageRule = {
+    id: "commit_missing_message",
+    priority: 55,
+    matches(input) {
+        // Commit intent without a quoted message string
+        return /\b(commit|git\s+commit)\b(?!\s*")/i.test(input);
+    },
+    evaluate() {
+        return {
+            kind: "incomplete",
+            reason: "A commit message is required.",
+            missing: ["commit message"],
+            nextSteps: [
+                { type: "use_exact_format", label: 'commit ""' },
+            ],
+        };
+    },
+};
+/**
+ * "show latest change", "show recent change" — intent is show git history,
+ * but the exact target is underspecified. Missing: what specifically to show.
+ */
+export const showLatestChangeRule = {
+    id: "show_latest_change",
+    priority: 60,
+    matches(input) {
+        return /\bshow\s+(latest|recent|last)\s+change\b/i.test(input);
+    },
+    evaluate() {
+        return {
+            kind: "incomplete",
+            reason: "'show latest change' requires a specific target.",
+            missing: ["specific target"],
+            nextSteps: [
+                { type: "use_exact_format", label: "show last commit" },
+            ],
+        };
+    },
+};
+// ─── Guided-recovery rules (priority 71–100) ──────────────────────────────────
+// Intent is vague; the system provides a safe path without guessing values.
+/**
+ * "make button blue", "change color to dark", "set header red" — vague visual
+ * change. File path, current value, and new value are all unknown.
+ *
+ * Exclusions (must not fire):
+ *   1. "dark mode" compound noun — config concept, not a shade change.
+ *      Consistent with the dark-mode guard in color-intent.interpreter.ts.
+ *   2. Inputs whose values are explicit CSS class-name tokens (e.g., bg-red-500,
+ *      text-blue-700). These have exact values but are missing only a file path;
+ *      they should fall through to the completionFallback or a more specific
+ *      incomplete rule — not be labelled "values unknown".
+ */
+const DARK_MODE_COMPOUND_RE = /\bdark\s+mode\b/i;
+const CSS_CLASS_TOKEN_RE = /\b[a-z]+-[a-z0-9]+-\d{2,3}\b/i; // e.g. bg-red-500, text-blue-700
+export const vagueStyleChangeRule = {
+    id: "vague_style_change",
+    priority: 75,
+    matches(input) {
+        if (DARK_MODE_COMPOUND_RE.test(input))
+            return false;
+        if (CSS_CLASS_TOKEN_RE.test(input))
+            return false;
+        return /\b(make|change|set|update)\b.{0,40}\b(blue|red|green|dark|light|white|black|color)\b/i.test(input);
+    },
+    evaluate() {
+        return {
+            kind: "guided_recovery",
+            reason: "Visual style changes require an exact file path and search/replace values.",
+            missing: ["file path", "current value", "new value"],
+            nextSteps: [
+                { type: "read_first", label: 'read ""' },
+                { type: "use_exact_format", label: 'replace "" with "" in ""' },
+            ],
+        };
+    },
+};
+/**
+ * "patch the file", "apply the patch" without structured params.
+ * Patch intent is present, but required fields are absent.
+ */
+export const vaguePatchRule = {
+    id: "vague_patch",
+    priority: 80,
+    matches(input) {
+        return /\b(patch|apply\s+patch)\b(?!\s+\S+\s+search=)/i.test(input);
+    },
+    evaluate() {
+        return {
+            kind: "guided_recovery",
+            reason: "Patch requires a file path and exact search/replace values.",
+            missing: ["file path", "search value", "replace value"],
+            nextSteps: [
+                { type: "read_first", label: 'read ""' },
+                { type: "use_exact_format", label: 'replace "" with "" in ""' },
+            ],
+        };
+    },
+};
+/**
+ * "update the styles", "fix the bug", "improve the performance" — generic
+ * imperative with no concrete target. Too vague to prepare any deterministic action.
+ */
+export const vagueTaskRule = {
+    id: "vague_task",
+    priority: 90,
+    matches(input) {
+        return /^\s*(update|fix|improve|refactor|clean\s+up)\b/i.test(input);
+    },
+    evaluate() {
+        return {
+            kind: "guided_recovery",
+            reason: "The request is too vague to prepare a deterministic action.",
+            missing: ["exact target", "specific change"],
+            nextSteps: [
+                { type: "read_first", label: 'read ""' },
+                { type: "use_exact_format", label: 'replace "" with "" in ""' },
+            ],
+        };
+    },
+};
+// ─── Ordered registry ─────────────────────────────────────────────────────────
+export const ALL_COMPLETION_RULES = [
+    rerunPreviousRule,
+    runTestsRule,
+    readFileRule,
+    replaceExactRule,
+    commitWithMessageRule,
+    patchStructuredRule,
+    gitOpsRule,
+    changeCssClassMissingFileRule,
+    commitMissingMessageRule,
+    showLatestChangeRule,
+    vagueStyleChangeRule,
+    vaguePatchRule,
+    vagueTaskRule,
+].sort((a, b) => a.priority - b.priority);
+//# sourceMappingURL=rules.js.map

package/dist/src/understand/completion/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../../../../src/understand/completion/rules.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,68 @@
+/**
+ * Intent Completion types.
+ *
+ * ── Result kinds ──────────────────────────────────────────────────────────────
+ *
+ *   complete        — input is deterministically actionable
+ *
+ *   incomplete      — intent is unambiguous, a required field is MISSING
+ *                     e.g. "commit my changes" → missing commit message
+ *                     The user knows what they want; the system knows what's needed.
+ *
+ *   guided_recovery — intent is vague; system can offer a safe path forward
+ *                     e.g. "make button blue" → read file first, then replace
+ *                     The user may not know the exact form; the system guides.
+ *
+ * ── Semantic contract ─────────────────────────────────────────────────────────
+ *
+ *   incomplete      ≠ guided_recovery
+ *
+ *   incomplete:       commit my changes → missing message → commit ""
+ *   guided_recovery:  make button blue  → vague intent   → read "" then replace "" with "" in ""
+ *
+ * ── CompletionRule ────────────────────────────────────────────────────────────
+ *
+ *   Completion is registry-driven. Each rule owns a named, testable pattern.
+ *   Rules receive UnderstandContext so context-dependent inputs
+ *   ("run again", "same as before") can be resolved when prior session exists.
+ *
+ *   CONTRACT: Completion is the sole authority on executability.
+ *   Disambiguation returning unknown does NOT block completion from returning complete.
+ *   Context-dependent executable intent is resolved HERE, not upstream.
+ */
+import type { UnderstandContext } from "../shared/types.js";
+export type CompletionNextStep = {
+    readonly type: "read_first" | "use_exact_format" | "add_missing_field";
+    readonly label: string;
+};
+export type CompletionResult = {
+    readonly kind: "complete";
+} | {
+    readonly kind: "incomplete";
+    readonly reason: string;
+    readonly missing: readonly string[];
+    readonly nextSteps: readonly CompletionNextStep[];
+} | {
+    readonly kind: "guided_recovery";
+    readonly reason: string;
+    readonly missing: readonly string[];
+    readonly nextSteps: readonly CompletionNextStep[];
+};
+/**
+ * A CompletionRule owns a named, prioritised, testable completion pattern.
+ *
+ * Rules MUST:
+ *   - Be deterministic (same input + ctx → same output, always)
+ *   - Return null only when the input is outside the rule's scope
+ *   - Never guess or infer missing values
+ *
+ * Priority: lower number = runs first.
+ * First matching non-null result wins.
+ */
+export type CompletionRule = {
+    readonly id: string;
+    readonly priority: number;
+    matches(input: string, ctx: UnderstandContext): boolean;
+    evaluate(input: string, ctx: UnderstandContext): CompletionResult | null;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/understand/completion/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD,CAAC;AAEN;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,IAAI,CAAC;CAC1E,CAAC"}

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

@@ -0,0 +1,34 @@
+/**
+ * Intent Completion types.
+ *
+ * ── Result kinds ──────────────────────────────────────────────────────────────
+ *
+ *   complete        — input is deterministically actionable
+ *
+ *   incomplete      — intent is unambiguous, a required field is MISSING
+ *                     e.g. "commit my changes" → missing commit message
+ *                     The user knows what they want; the system knows what's needed.
+ *
+ *   guided_recovery — intent is vague; system can offer a safe path forward
+ *                     e.g. "make button blue" → read file first, then replace
+ *                     The user may not know the exact form; the system guides.
+ *
+ * ── Semantic contract ─────────────────────────────────────────────────────────
+ *
+ *   incomplete      ≠ guided_recovery
+ *
+ *   incomplete:       commit my changes → missing message → commit ""
+ *   guided_recovery:  make button blue  → vague intent   → read "" then replace "" with "" in ""
+ *
+ * ── CompletionRule ────────────────────────────────────────────────────────────
+ *
+ *   Completion is registry-driven. Each rule owns a named, testable pattern.
+ *   Rules receive UnderstandContext so context-dependent inputs
+ *   ("run again", "same as before") can be resolved when prior session exists.
+ *
+ *   CONTRACT: Completion is the sole authority on executability.
+ *   Disambiguation returning unknown does NOT block completion from returning complete.
+ *   Context-dependent executable intent is resolved HERE, not upstream.
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

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

package/dist/src/understand/context/context-alignment.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Context Alignment — semantic classification of input vs. session context.
+ *
+ * CONTRACT (PRV / Context Alignment boundary):
+ *   Context Alignment is SEMANTIC. It handles context-reference patterns that are
+ *   too specific or phrase-dependent for PRV's lexical approach.
+ *
+ *   PRV handles: again, continue, previous, same as
+ *   Context Alignment handles: same file, use same, that file, my project, the config
+ *
+ *   Both layers may detect context-dependency, but for different reasons:
+ *     PRV:               "is this input lexically dependent on missing state?"
+ *     Context Alignment: "does this input reference a specific artifact that requires context?"
+ */
+import type { ContextAlignmentResult } from "./types.js";
+import type { UnderstandContext } from "../shared/types.js";
+export declare function runContextAlignment(input: string, ctx: UnderstandContext): ContextAlignmentResult;
+//# sourceMappingURL=context-alignment.d.ts.map

package/dist/src/understand/context/context-alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-alignment.d.ts","sourceRoot":"","sources":["../../../../src/understand/context/context-alignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAwC5D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,iBAAiB,GACrB,sBAAsB,CAgBxB"}

package/dist/src/understand/context/context-alignment.js

@@ -0,0 +1,61 @@
+/**
+ * Context Alignment — semantic classification of input vs. session context.
+ *
+ * CONTRACT (PRV / Context Alignment boundary):
+ *   Context Alignment is SEMANTIC. It handles context-reference patterns that are
+ *   too specific or phrase-dependent for PRV's lexical approach.
+ *
+ *   PRV handles: again, continue, previous, same as
+ *   Context Alignment handles: same file, use same, that file, my project, the config
+ *
+ *   Both layers may detect context-dependency, but for different reasons:
+ *     PRV:               "is this input lexically dependent on missing state?"
+ *     Context Alignment: "does this input reference a specific artifact that requires context?"
+ */
+// ─── Non-literal patterns (social / conversational) ───────────────────────────
+const NON_LITERAL_PATTERNS = [
+    /^\s*good\s+(morning|afternoon|evening|night)\b/i,
+    /^\s*(hello|hi|hey)\b/i,
+    /^\s*let'?s?\s+(?:get\s+)?start(?:ed)?\b/i,
+    /^\s*how\s+are\s+you\b/i,
+    /^\s*thanks?\b/i,
+    /^\s*thank\s+you\b/i,
+    /^\s*ok(ay)?\b/i,
+    /^\s*great\b/i,
+    /^\s*sounds\s+good\b/i,
+];
+// ─── Context-reference patterns ────────────────────────────────────────────────
+// Specific semantic references to prior session artifacts or state.
+// These are narrower than PRV's lexical markers — they identify the OBJECT
+// being referenced, not just the existence of a reference word.
+const CONTEXT_REFERENCE_PATTERNS = [
+    // File / artifact references
+    /\bsame\s+file\b/i,
+    /\bthat\s+file\b/i,
+    /\bthat\s+result\b/i,
+    /\bthat\s+approach\b/i,
+    // Session / execution references
+    /\bprevious\s+run\b/i,
+    /\bcontinue\s+from\s+before\b/i,
+    /\buse\s+the\s+same\b/i,
+    /\buse\s+same\b/i, // "use same file" (without "the")
+    // Config / project references without concrete identifiers
+    // (these are moved here from disambiguation to keep responsibility clear)
+    /\bmy\s+project\b/i,
+    /\bthe\s+config\b(?![\s".])/i, // "the config" without a following path/quote
+];
+export function runContextAlignment(input, ctx) {
+    if (NON_LITERAL_PATTERNS.some((p) => p.test(input))) {
+        return { kind: "non_literal" };
+    }
+    if (CONTEXT_REFERENCE_PATTERNS.some((p) => p.test(input))) {
+        if (!ctx.hasPriorSession) {
+            return {
+                kind: "hard_mismatch",
+                reason: "Input references a prior session or result, but no prior context is available.",
+            };
+        }
+    }
+    return { kind: "aligned" };
+}
+//# sourceMappingURL=context-alignment.js.map

package/dist/src/understand/context/context-alignment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-alignment.js","sourceRoot":"","sources":["../../../../src/understand/context/context-alignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,iFAAiF;AAEjF,MAAM,oBAAoB,GAA0B;IAClD,iDAAiD;IACjD,uBAAuB;IACvB,0CAA0C;IAC1C,wBAAwB;IACxB,gBAAgB;IAChB,oBAAoB;IACpB,gBAAgB;IAChB,cAAc;IACd,sBAAsB;CACvB,CAAC;AAEF,kFAAkF;AAClF,oEAAoE;AACpE,2EAA2E;AAC3E,gEAAgE;AAEhE,MAAM,0BAA0B,GAA0B;IACxD,6BAA6B;IAC7B,kBAAkB;IAClB,kBAAkB;IAClB,oBAAoB;IACpB,sBAAsB;IAEtB,iCAAiC;IACjC,qBAAqB;IACrB,+BAA+B;IAC/B,uBAAuB;IACvB,iBAAiB,EAAY,kCAAkC;IAE/D,2DAA2D;IAC3D,0EAA0E;IAC1E,mBAAmB;IACnB,6BAA6B,EAAG,8CAA8C;CAC/E,CAAC;AAEF,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,GAAsB;IAEtB,IAAI,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC;IACjC,CAAC;IAED,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,eAAe;gBACrB,MAAM,EACJ,gFAAgF;aACnF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC7B,CAAC"}

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

@@ -0,0 +1,20 @@
+/**
+ * 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 type ContextAlignmentResult = {
+    readonly kind: "aligned";
+} | {
+    readonly kind: "non_literal";
+} | {
+    readonly kind: "hard_mismatch";
+    readonly reason: string;
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/understand/context/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC"}