@davesheffer/hunch 1.46.0 → 1.47.0

package/dist/synthesis/provider.d.ts

@@ -111,8 +111,9 @@ export interface SynthProvider {
 }
 /** Every selectable synthesis mode. `auto` is a preference value rather than a
  * provider: it resolves the invocation's origin without choosing by availability.
- * "openai-compat" is the opt-in local/self-hosted HTTP provider (Ollama, vLLM,
- * LM Studio, ...) — not a subscription, but explicitly selectable like one. */
+ * "openai-compat" is the opt-in local or self-hosted HTTP provider (Ollama, vLLM,
+ * LM Studio and so on). It is not a subscription, but it can be selected
+ * explicitly like one. */
 export declare const SYNTH_PROVIDER_NAMES: readonly ["claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export declare const SYNTH_PREFERENCES: readonly ["auto", "claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export type SynthProviderName = (typeof SYNTH_PROVIDER_NAMES)[number];
@@ -172,8 +173,11 @@ export declare function safeModel(v: string | undefined, fallback: undefined): s
  * the explicit skip flag preserves that neutral-cwd isolation without loading a
  * target repo's agent rules or MCP configuration. */
 export declare function codexExecArgs(model?: string): string[];
+/** Sanitize HUNCH_SYNTH_TIMEOUT_MS: a finite number > 0, else `fallback`. */
 export declare function safeTimeout(v: string | undefined, fallback: number): number;
+/** Sanitize HUNCH_SYNTH_MAX_TOKENS: a finite number > 0, else `fallback`. */
 export declare function safeMaxTokens(v: string | undefined, fallback: number): number;
+/** True only when the user explicitly opted in to public (possibly metered) hosts. */
 export declare function meteredHostsAllowed(env?: NodeJS.ProcessEnv): boolean;
 export declare class OpenAICompatProvider extends PromptSynthProvider {
     readonly name = "openai-compat";
@@ -182,9 +186,10 @@ export declare class OpenAICompatProvider extends PromptSynthProvider {
 }
 /** Best-effort: does the configured openai-compat endpoint look like Ollama with
  *  an UNSET num_ctx? Returns
- *  an advisory warning string when so, or null when the endpoint isn't reachable,
- *  doesn't look like Ollama's /api/show shape, or already has num_ctx set — this
- *  is diagnostics only, never thrown, never blocking. Deliberately does NOT try to
+ *  a warning string when the model does not pin num_ctx, or null when the
+ *  endpoint is unreachable, does not look like Ollama's /api/show response shape,
+ *  or already has num_ctx set. Diagnostics only: it never throws and never blocks.
+ *  Deliberately does NOT try to
  *  report the model's effective context length: modern Ollama defaults may come
  *  from server configuration or VRAM tiers, and model_info keys are not a stable
  *  parse target. We therefore report only the observed fact — whether num_ctx is
@@ -203,19 +208,12 @@ export declare class DeterministicProvider implements SynthProvider {
  *  tagged. If nothing parses, hand the raw output to the mapper (→ it finds the JSON
  *  draft or throws → deterministic fallback). Tolerant by design: drift degrades, never crashes. */
 export declare function extractCodexText(out: string): string;
-/** Test-only: clears the availability memoization cache so a test that toggles
- *  env vars mid-process (e.g. HUNCH_SYNTH_BASE_URL) isn't served a stale result
- *  cached by an earlier call in the same process. Never call from production code. */
+/** Test-only: empty the availability cache so a test that changes env vars
+ *  mid-process is not served a stale cached result. */
 export declare function __resetAvailabilityCacheForTests(): void;
-/** "ollama" is accepted as an alias for "openai-compat" — the provider is not
- *  Ollama-specific (it speaks the OpenAI chat-completions format any self-hosted
- *  server can implement), but Ollama is the most common self-hosted target and
- *  users reach for that name first. Applied to the HUNCH_SYNTH_PROVIDER env var in
- *  resolveSynthesisProvider below, and exported so the `hunch provider <name>` CLI
- *  command (index.ts) normalizes it the same way before validating/persisting a
- *  local preference — the two paths must agree, or a user who sets one and reads
- *  the other back gets a confusing "unknown provider" message for a name that
- *  actually works. */
+/** The provider is not Ollama-specific, but Ollama is the name users try first, so
+ *  "ollama" is an alias for "openai-compat". The env var and `hunch provider <name>`
+ *  both normalize through here so the two paths agree. */
 export declare function normalizeProviderName(v: string | undefined): string | undefined;
 /** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
  * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
@@ -258,10 +256,10 @@ export declare class EnsembleProvider implements SynthProvider {
 export declare function selectEnsemble(opts?: ProviderSelectionOptions & {
     samples?: number;
 }): Promise<EnsembleProvider | null>;
-/** Pick a provider to run the Critic pass — the same resolved provider normal
- *  synthesis would use (subscription CLI or the opt-in openai-compat endpoint),
- *  honoring the same env/local-preference/auto policy. Returns null when that
- *  resolves to the deterministic fallback — verification then no-ops and the
+/** Pick the provider for the Critic pass: the same resolved provider normal
+ *  synthesis would use (a subscription CLI or the opt-in openai-compat endpoint),
+ *  under the same env / local-preference / auto policy. Returns null when that
+ *  resolves to the deterministic fallback, in which case verification does nothing. The
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
 export declare function selectVerifier(opts?: ProviderSelectionOptions): Promise<SynthProvider | null>;
 /** Map model text → RelevanceVerdict, or null when nothing usable parses (→ the

package/dist/synthesis/provider.js

@@ -13,9 +13,9 @@
  * child env wherever the CLI would otherwise prefer them. There is intentionally
  * NO direct API-key provider.
  *
- * A fourth, OPT-IN provider (name "openai-compat", alias "ollama") speaks the
- * OpenAI chat-completions format over HTTP to a self-hosted endpoint instead of a
- * subscription CLI. It stays off unless HUNCH_SYNTH_BASE_URL and HUNCH_SYNTH_MODEL
+ * Provider D (opt-in): "openai-compat" (alias "ollama") speaks the OpenAI
+ * chat-completions format over HTTP to a self-hosted endpoint instead of running
+ * a subscription CLI. It stays off unless HUNCH_SYNTH_BASE_URL and HUNCH_SYNTH_MODEL
  * are both explicitly set. Local/LAN endpoints work directly; every public remote
  * requires HUNCH_SYNTH_ALLOW_METERED=1 because billing cannot be inferred safely
  * from a hostname — con_2ce3f2a547's spirit is "never silently bill."
@@ -74,8 +74,9 @@ export async function pexecIn(cmd, args, opts = {}) {
 }
 /** Every selectable synthesis mode. `auto` is a preference value rather than a
  * provider: it resolves the invocation's origin without choosing by availability.
- * "openai-compat" is the opt-in local/self-hosted HTTP provider (Ollama, vLLM,
- * LM Studio, ...) — not a subscription, but explicitly selectable like one. */
+ * "openai-compat" is the opt-in local or self-hosted HTTP provider (Ollama, vLLM,
+ * LM Studio and so on). It is not a subscription, but it can be selected
+ * explicitly like one. */
 export const SYNTH_PROVIDER_NAMES = ["claude-cli", "codex-cli", "cursor-agent", "kimi-cli", "openai-compat", "deterministic"];
 export const SYNTH_PREFERENCES = ["auto", ...SYNTH_PROVIDER_NAMES];
 const PROVIDER_INFO = {
@@ -83,7 +84,7 @@ const PROVIDER_INFO = {
     "codex-cli": { label: "Codex", subscription: "ChatGPT subscription" },
     "cursor-agent": { label: "Cursor Agent", subscription: "Cursor subscription" },
     "kimi-cli": { label: "Kimi CLI", subscription: null },
-    "openai-compat": { label: "Self-hosted / local model (Ollama, vLLM, LM Studio, ...)", subscription: null },
+    "openai-compat": { label: "Self-hosted / local model (Ollama, vLLM, LM Studio)", subscription: null },
     deterministic: { label: "Deterministic local fallback", subscription: null },
 };
 const SYSTEM = `You are the synthesis engine of an Engineering Memory OS. You turn raw
@@ -250,23 +251,22 @@ export function safeModel(v, fallback) {
 export function codexExecArgs(model) {
     return ["exec", "--json", "--skip-git-repo-check", ...(model ? ["-m", model] : []), "-"];
 }
-// A timeout comes from a HUNCH_*_TIMEOUT_MS env var and feeds AbortController's
-// delay directly (never a shell argv token, unlike safeModel's model id) — but a
-// non-numeric or nonsensical value (negative, zero, NaN, Infinity) would either
-// abort immediately or never abort at all, so validate the same way: fall back to
-// the provider's default rather than propagate garbage.
-export function safeTimeout(v, fallback) {
+// The timeout drives an abort delay and max_tokens caps output length; neither is
+// a shell argv token. A garbage value would abort at once, never abort, or corrupt
+// the request body, so anything but a finite number > 0 falls back to the default.
+function positiveNumber(v, fallback) {
+    if (typeof v !== "string" || v.trim() === "")
+        return fallback;
     const n = Number(v);
-    return v && Number.isFinite(n) && n > 0 ? n : fallback;
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Sanitize HUNCH_SYNTH_TIMEOUT_MS: a finite number > 0, else `fallback`. */
+export function safeTimeout(v, fallback) {
+    return positiveNumber(v, fallback);
 }
-// max_tokens caps OUTPUT length (never a shell argv token, unlike safeModel's
-// model id) — same failure modes as a timeout, so validate the same way: fall
-// back to a safe default rather than propagate garbage into the request body
-// (issue #11; orthogonal to the context-window/truncation problem that issue
-// is mainly about — this only bounds how much the model is allowed to WRITE).
+/** Sanitize HUNCH_SYNTH_MAX_TOKENS: a finite number > 0, else `fallback`. */
 export function safeMaxTokens(v, fallback) {
-    const n = Number(v);
-    return v && Number.isFinite(n) && n > 0 ? n : fallback;
+    return positiveNumber(v, fallback);
 }
 // --------------------------------------------------------------------------
 // Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
@@ -392,21 +392,15 @@ class CursorCliProvider extends PromptSynthProvider {
     }
 }
 // --------------------------------------------------------------------------
-// Provider D: OpenAI-compatible / local model endpoint (Ollama, vLLM, LM
-// Studio, llama.cpp server, ...) — opt-in, NOT a subscription CLI. Speaks the
-// OpenAI chat-completions wire format over HTTP, so ONE implementation covers
-// any self-hosted server that implements it (Ollama's /v1 compatibility layer
-// included — no separate native /api/chat client). Off by default: available()
-// requires BOTH HUNCH_SYNTH_BASE_URL and HUNCH_SYNTH_MODEL, so an installation
-// with neither set behaves exactly as it did before this provider existed.
-//
-// Exported (unlike the CLI providers) so tests can construct fresh instances and
-// read process.env at CALL time — see run()/available() below, which read env
-// vars directly rather than caching them in constructor fields. That mirrors
-// selectProvider()'s own style (it re-reads HUNCH_SYNTH_PROVIDER on every call)
-// and avoids a stale-field trap: a module-level PROVIDERS singleton constructed
-// once at import time would otherwise never see env vars a test (or a long-lived
-// process) sets afterward.
+// Provider D: OpenAI-compatible / local model endpoint (opt-in, NOT a subscription CLI)
+// One implementation covers any server that implements the chat-completions
+// format, including Ollama's /v1 compatibility layer; there is no separate native
+// Ollama client. It is off by default: availability needs both HUNCH_SYNTH_BASE_URL
+// and HUNCH_SYNTH_MODEL, so an install with neither set behaves as if the provider
+// did not exist. Unlike the CLI providers the class is exported, so tests can
+// build fresh instances. It reads env vars at call time instead of caching them in
+// fields, avoiding a stale value in the module-level registry singleton, which is
+// created once at import time.
 // --------------------------------------------------------------------------
 // con_2ce3f2a547's boundary is "never silently bill." A denylist cannot enforce
 // that boundary: new OpenAI-compatible paid providers appear continually, and a
@@ -469,6 +463,7 @@ function isLocalOrPrivateHost(hostname) {
 function requiresMeteredOptIn(url) {
     return !isLocalOrPrivateHost(normalizedHostname(url));
 }
+/** True only when the user explicitly opted in to public (possibly metered) hosts. */
 export function meteredHostsAllowed(env = process.env) {
     return env.HUNCH_SYNTH_ALLOW_METERED === "1";
 }
@@ -484,8 +479,9 @@ export class OpenAICompatProvider extends PromptSynthProvider {
     async run(prompt, output = "json") {
         const baseUrl = process.env.HUNCH_SYNTH_BASE_URL;
         const model = safeModel(process.env.HUNCH_SYNTH_MODEL, undefined);
-        if (!baseUrl || !model)
-            throw new Error("openai-compat: HUNCH_SYNTH_BASE_URL/HUNCH_SYNTH_MODEL not set");
+        if (!baseUrl || !model) {
+            throw new Error("openai-compat: HUNCH_SYNTH_BASE_URL and HUNCH_SYNTH_MODEL are not set");
+        }
         const endpoint = parseOpenAICompatBaseUrl(baseUrl);
         if (!endpoint) {
             throw new Error("openai-compat: HUNCH_SYNTH_BASE_URL must be an http(s) base URL without credentials, a query, or a fragment");
@@ -495,7 +491,7 @@ export class OpenAICompatProvider extends PromptSynthProvider {
         }
         endpoint.pathname = `${endpoint.pathname.replace(/\/+$/, "")}/chat/completions`;
         const apiKey = process.env.HUNCH_SYNTH_API_KEY;
-        const timeoutMs = safeTimeout(process.env.HUNCH_SYNTH_TIMEOUT_MS, 300_000);
+        const timeoutMs = safeTimeout(process.env.HUNCH_SYNTH_TIMEOUT_MS, 300000);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
@@ -515,12 +511,14 @@ export class OpenAICompatProvider extends PromptSynthProvider {
                 signal: controller.signal,
             });
             if (!res.ok) {
-                throw new Error(`openai-compat endpoint returned ${res.status}: ${(await res.text()).slice(0, 300)}`);
+                const text = await res.text().catch(() => "");
+                throw new Error(`openai-compat: ${endpoint.origin}${endpoint.pathname} returned HTTP ${res.status}: ${text.slice(0, 300)}`);
+            }
+            const json = (await res.json());
+            const content = json.choices?.[0]?.message?.content;
+            if (typeof content !== "string" || !content) {
+                throw new Error("openai-compat: endpoint returned no message content");
             }
-            const body = (await res.json());
-            const content = body.choices?.[0]?.message?.content;
-            if (!content)
-                throw new Error("openai-compat endpoint returned no message content");
             return content;
         }
         finally {
@@ -530,9 +528,10 @@ export class OpenAICompatProvider extends PromptSynthProvider {
 }
 /** Best-effort: does the configured openai-compat endpoint look like Ollama with
  *  an UNSET num_ctx? Returns
- *  an advisory warning string when so, or null when the endpoint isn't reachable,
- *  doesn't look like Ollama's /api/show shape, or already has num_ctx set — this
- *  is diagnostics only, never thrown, never blocking. Deliberately does NOT try to
+ *  a warning string when the model does not pin num_ctx, or null when the
+ *  endpoint is unreachable, does not look like Ollama's /api/show response shape,
+ *  or already has num_ctx set. Diagnostics only: it never throws and never blocks.
+ *  Deliberately does NOT try to
  *  report the model's effective context length: modern Ollama defaults may come
  *  from server configuration or VRAM tiers, and model_info keys are not a stable
  *  parse target. We therefore report only the observed fact — whether num_ctx is
@@ -544,19 +543,19 @@ export async function probeOllamaNumCtx(baseUrl, model) {
             method: "POST",
             headers: { "content-type": "application/json" },
             body: JSON.stringify({ name: model }),
-            signal: AbortSignal.timeout(5_000),
+            signal: AbortSignal.timeout(5000),
         });
         if (!res.ok)
             return null;
-        const body = (await res.json());
-        if (typeof body.parameters !== "string")
+        const json = (await res.json());
+        if (typeof json.parameters !== "string")
+            return null;
+        if (/^num_ctx\s+\d+/m.test(json.parameters))
             return null;
-        if (/^num_ctx\s+\d+/m.test(body.parameters))
-            return null; // already configured — nothing to warn about
         return "⚠ This Ollama model does not pin num_ctx; its effective context depends on server/VRAM defaults. For stable large-diff synthesis, see https://www.hunchmemory.com/cookbook and pin num_ctx via a custom Modelfile.";
     }
     catch {
-        return null; // not Ollama, unreachable, or an unexpected response shape — advisory only, never throw
+        return null;
     }
 }
 // --------------------------------------------------------------------------
@@ -571,8 +570,7 @@ export class DeterministicProvider {
         const dirs = topDirs(input.files);
         const a = input.analysis;
         const summary = a ? summarizeDiff(a) : "";
-        // input.files can be markdown-only (issue #12) — don't claim "code" for a
-        // commit that touched none.
+        // A commit touching no code (issue #12) must not be described as "code".
         const noun = input.files.some((f) => languageFor(f) !== null) ? "code" : "content";
         const verb = /^(add|introduce|create|feat)/i.test(input.subject) ? "introduced"
             : /^(remove|delete|drop)/i.test(input.subject) ? "removed"
@@ -677,9 +675,8 @@ const PROVIDERS = [
 // Availability rarely changes within a process (a CLI doesn't get installed mid-run),
 // and selection runs on every sync/recordFailure. Cache by object identity rather than
 // name so injected test registries never inherit a stale result from another provider.
-// A plain Map (not WeakMap): __resetAvailabilityCacheForTests below needs .clear(),
-// which WeakMap doesn't support — the module's singleton PROVIDERS array is the only
-// thing that ever populates this in production, so there's no unbounded-growth risk.
+// A plain Map (not a WeakMap) so the test-only reset below can clear it. Only the
+// singleton registry fills it in production, so it cannot grow without bound.
 const availCache = new Map();
 function isAvailable(p) {
     let v = availCache.get(p);
@@ -689,21 +686,14 @@ function isAvailable(p) {
     }
     return v;
 }
-/** Test-only: clears the availability memoization cache so a test that toggles
- *  env vars mid-process (e.g. HUNCH_SYNTH_BASE_URL) isn't served a stale result
- *  cached by an earlier call in the same process. Never call from production code. */
+/** Test-only: empty the availability cache so a test that changes env vars
+ *  mid-process is not served a stale cached result. */
 export function __resetAvailabilityCacheForTests() {
     availCache.clear();
 }
-/** "ollama" is accepted as an alias for "openai-compat" — the provider is not
- *  Ollama-specific (it speaks the OpenAI chat-completions format any self-hosted
- *  server can implement), but Ollama is the most common self-hosted target and
- *  users reach for that name first. Applied to the HUNCH_SYNTH_PROVIDER env var in
- *  resolveSynthesisProvider below, and exported so the `hunch provider <name>` CLI
- *  command (index.ts) normalizes it the same way before validating/persisting a
- *  local preference — the two paths must agree, or a user who sets one and reads
- *  the other back gets a confusing "unknown provider" message for a name that
- *  actually works. */
+/** The provider is not Ollama-specific, but Ollama is the name users try first, so
+ *  "ollama" is an alias for "openai-compat". The env var and `hunch provider <name>`
+ *  both normalize through here so the two paths agree. */
 export function normalizeProviderName(v) {
     return v === "ollama" ? "openai-compat" : v;
 }
@@ -726,8 +716,8 @@ export function readSynthesisPreference(root) {
         if (!existsSync(file))
             return "auto";
         const parsed = JSON.parse(readFileSync(file, "utf8"));
-        const normalized = typeof parsed.synthProvider === "string" ? normalizeProviderName(parsed.synthProvider) : undefined;
-        return isSynthPreference(normalized) ? normalized : "auto";
+        const stored = typeof parsed.synthProvider === "string" ? normalizeProviderName(parsed.synthProvider) : undefined;
+        return isSynthPreference(stored) ? stored : "auto";
     }
     catch {
         return "auto";
@@ -781,7 +771,8 @@ export async function resolveSynthesisProvider(opts = {}) {
         const provider = find(name);
         return provider && await isAvailable(provider) ? provider : undefined;
     };
-    const environment = normalizeProviderName(env.HUNCH_SYNTH_PROVIDER?.trim());
+    const rawEnvironment = env.HUNCH_SYNTH_PROVIDER?.trim();
+    const environment = rawEnvironment ? normalizeProviderName(rawEnvironment) : undefined;
     // Explicit offline/privacy mode always wins: origin binding must never turn it into a model call.
     if (environment === "deterministic")
         return { provider: fallback, source: "environment", preference: "deterministic", statuses };
@@ -943,10 +934,10 @@ export async function selectEnsemble(opts = {}) {
     // construction stays passthrough. `--samples 1` opts back out.
     return workers.length ? new EnsembleProvider(workers, { samples: opts.samples ?? DEFAULT_SAMPLES }) : null;
 }
-/** Pick a provider to run the Critic pass — the same resolved provider normal
- *  synthesis would use (subscription CLI or the opt-in openai-compat endpoint),
- *  honoring the same env/local-preference/auto policy. Returns null when that
- *  resolves to the deterministic fallback — verification then no-ops and the
+/** Pick the provider for the Critic pass: the same resolved provider normal
+ *  synthesis would use (a subscription CLI or the opt-in openai-compat endpoint),
+ *  under the same env / local-preference / auto policy. Returns null when that
+ *  resolves to the deterministic fallback, in which case verification does nothing. The
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
 export async function selectVerifier(opts = {}) {
     const { provider } = await resolveSynthesisProvider(opts);

package/dist/synthesis/synthesize.d.ts

@@ -18,11 +18,11 @@ export interface SyncResult {
     decision?: Decision;
     provider?: string;
 }
-/** Trivial-subject commits (merge/revert/bump/format/...) are noise UNLESS the body
- *  carries real content — a squash/PR description often lands there, not on the
- *  subject. Gated on body length ALONE (not the full isSignificant() heuristic): a
- *  large auto-generated reformat or dependency-bump diff with no narrative must stay
- *  skipped even though it would trip isSignificant()'s line/file/structural checks. */
+/** Is this commit mechanical noise (merge/revert/bump/format/lint/wip, dependency
+ *  chores) with no narrative? Gates on body length alone, not the full significance
+ *  heuristic, so a large auto-generated reformat or dependency bump with no
+ *  narrative stays skipped, while a squash/PR description (a substantive body)
+ *  keeps a trivial-looking subject eligible. */
 export declare function isTrivialSubject(meta: {
     subject: string;
     body: string;
@@ -31,9 +31,9 @@ export declare function isTrivialSubject(meta: {
  *  deterministic. Any structural change (symbol/dependency delta), non-trivial
  *  churn, several files, OR an explanatory commit body signals a real decision
  *  worth the model. Everything below (typo/tweak/one-liner with no message) falls
- *  to the free deterministic draft — shallower but honestly low-confidence.
- *  `files` is whatever the caller is synthesizing from (code and/or markdown, per
- *  isSubstantive) — the line/file-count checks are format-agnostic. */
+ *  to the free deterministic draft. The line and file-count checks don't depend on
+ *  the file format; `files` is the explicit list being synthesized (code and/or
+ *  markdown). */
 export declare function isSignificant(meta: {
     body: string;
 }, a: DiffAnalysis, files: string[]): boolean;

package/dist/synthesis/synthesize.js

@@ -6,19 +6,20 @@ import { commitCoveredBy } from "../core/dupdetect.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { draftTripwires, knownRepoDeps } from "./tripwires.js";
 import { isSubstantive } from "../extractors/languages.js";
-// "chore(deps):" is anchored separately (not via \b) because \b requires a
-// word/non-word transition, and the character after the closing ")" is ":" or a
-// space — both non-word — so no boundary ever fires there.
-const SKIP_SUBJECT = /^(merge|revert|bump|format|lint|wip)\b|^chore\(deps\):/i;
+// Subjects that signal mechanical churn. `chore(deps):` is matched as a literal
+// prefix on its own: a word-boundary check after the closing parenthesis would
+// never fire (both ")" and ":" are non-word characters), so it cannot share the
+// `\b` alternative.
+const SKIP_SUBJECT = /^(?:(?:merge|revert|bump|format|lint|wip)\b|chore\(deps\):)/i;
 // Below this many changed code lines, a commit with no structural change and no
 // explanatory body isn't worth a paid LLM call. Tunable via HUNCH_SIG_MIN_LINES.
 const SIG_MIN_LINES = ((raw) => Number.isFinite(raw) && raw > 0 ? raw : 12)(Number(process.env.HUNCH_SIG_MIN_LINES));
 const SIG_MIN_BODY = 40;
-/** Trivial-subject commits (merge/revert/bump/format/...) are noise UNLESS the body
- *  carries real content — a squash/PR description often lands there, not on the
- *  subject. Gated on body length ALONE (not the full isSignificant() heuristic): a
- *  large auto-generated reformat or dependency-bump diff with no narrative must stay
- *  skipped even though it would trip isSignificant()'s line/file/structural checks. */
+/** Is this commit mechanical noise (merge/revert/bump/format/lint/wip, dependency
+ *  chores) with no narrative? Gates on body length alone, not the full significance
+ *  heuristic, so a large auto-generated reformat or dependency bump with no
+ *  narrative stays skipped, while a squash/PR description (a substantive body)
+ *  keeps a trivial-looking subject eligible. */
 export function isTrivialSubject(meta) {
     return SKIP_SUBJECT.test(meta.subject) && meta.body.trim().length < SIG_MIN_BODY;
 }
@@ -26,9 +27,9 @@ export function isTrivialSubject(meta) {
  *  deterministic. Any structural change (symbol/dependency delta), non-trivial
  *  churn, several files, OR an explanatory commit body signals a real decision
  *  worth the model. Everything below (typo/tweak/one-liner with no message) falls
- *  to the free deterministic draft — shallower but honestly low-confidence.
- *  `files` is whatever the caller is synthesizing from (code and/or markdown, per
- *  isSubstantive) — the line/file-count checks are format-agnostic. */
+ *  to the free deterministic draft. The line and file-count checks don't depend on
+ *  the file format; `files` is the explicit list being synthesized (code and/or
+ *  markdown). */
 export function isSignificant(meta, a, files) {
     const structural = a.addedSymbols.length + a.removedSymbols.length + a.changedSymbols.length + a.addedDeps.length + a.removedDeps.length;
     if (structural > 0)
@@ -52,27 +53,14 @@ export async function syncCommit(store, root, sha, opts = {}) {
         return { status: "skipped", reason: "commit not found" };
     if (isTrivialSubject(meta))
         return { status: "skipped", reason: `trivial subject: ${meta.subject}` };
-    // .hunch/** is Hunch's OWN store — commitDiff already excludes it from the diff
-    // CONTENT via DIFF_NOISE ("circular noise": re-synthesizing a commit that wrote
-    // it would draft a decision about Hunch's own bookkeeping). That guard never
-    // covered this file-LIST gate, and before #12 it didn't need to: languageFor()
-    // already returned null for .hunch/**'s JSON and for the .md grounding docs
-    // flushCapture regenerates alongside it (AGENTS.md/CLAUDE.md/copilot-instructions.md),
-    // so such a commit failed "no code files changed" by coincidence. Once markdown
-    // became substantive input those grounding docs alone made the commit eligible.
-    // Checked by PATH, not commit-message convention (flushCapture's exact subject
-    // wording lives as separate literals in mcp/server.ts/cli/index.ts and could
-    // drift independently of any subject regex here) — a human editing AGENTS.md on
-    // its own, with no .hunch/** change alongside it, stays fully synthesis-eligible.
+    // Hunch's own store is circular input. This checks the PATH, not the commit-message
+    // wording, and the decision is per path: a human editing AGENTS.md alone, with no
+    // .hunch change, stays eligible.
     if (meta.files.some((f) => pathMatchesGlob(f, "**/.hunch/**"))) {
-        return { status: "skipped", reason: "touches Hunch's own store (.hunch/**) — circular, never synthesis input" };
+        return { status: "skipped", reason: "commit touches Hunch's own store (.hunch/**), which is circular and never synthesis input" };
     }
-    // Substantive, not just parseable: markdown carries the *why* in a docs/ADR repo
-    // just as legitimately as a .ts diff does, even though it has no symbol graph
-    // (issue #12). languageFor() stays the parseability question for the symbol/dep
-    // extraction inside analyzeDiff below.
-    const substantiveFiles = meta.files.filter((f) => isSubstantive(f));
-    if (substantiveFiles.length === 0)
+    const substantiveFiles = meta.files.filter(isSubstantive);
+    if (!substantiveFiles.length)
         return { status: "skipped", reason: "no code or markdown files changed" };
     // Seed the id from the COMMIT (stable across runs), not the LLM-generated title
     // (which varies) — so re-syncing a commit updates rather than dupes.
@@ -132,7 +120,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
         ? new DeterministicProvider()
         : opts.deep
             ? (await selectEnsemble({ root, samples: opts.samples })) ?? await selectProvider({ root })
-            : opts.force || opts.verify || isSignificant(meta, analysis, substantiveFiles)
+            : opts.force || wantVerify || isSignificant(meta, analysis, substantiveFiles)
                 ? await selectProvider({ root })
                 : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: substantiveFiles, diff, analysis };
@@ -142,10 +130,8 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // grounding. No-ops when no assistant CLI is available; never raises trust (dec_9a2f2fe72a).
     if (wantVerify)
         draft = await verifyDecisionSafe(await selectVerifier({ root }), input, draft);
-    // The draft's own drafter, not merely the one selected — draftDecisionSafe sets
-    // fellBackTo when the selected provider threw and it silently substituted the
-    // deterministic heuristic. Every telemetry/return below must report THIS, since
-    // backfill's LLM-vs-heuristic tally reads it directly off the return value.
+    // Every telemetry/return value below must report the provider that ACTUALLY drafted
+    // the record (backfill's LLM-vs-heuristic tally reads it from the return value).
     const actualProvider = draft.fellBackTo ?? provider.name;
     // Advisory synthesis telemetry for `hunch review` — which provider ran, how many drafts
     // were reconciled, their agreement, and the verifier's grounding. Rides in `evidence`
@@ -270,8 +256,7 @@ export async function recordFailure(store, root, failure, opts = {}) {
         suspects: suspects.map((s) => `${s.name} @ ${s.file}`),
     };
     const draft = await draftBugSafe(provider, input);
-    // The draft's own drafter, not merely the one selected — see the identical
-    // comment in syncCommit above.
+    // Report the provider that actually drafted the bug (see syncCommit).
     const actualProvider = draft.fellBackTo ?? provider.name;
     // Seed the id from the test id (stable), not the LLM title — one bug per test.
     const id = bugId(failure.test);
@@ -535,26 +520,24 @@ export async function draftDecisionSafe(provider, input) {
     try {
         return await provider.draftDecision(input);
     }
-    catch (error) {
+    catch (err) {
         // A provider failure (network, bad creds, CLI crash, unparseable output) must
         // never abort the learning loop — fall back to the deterministic heuristic
         // draft, which is honestly labeled ("inferred") rather than a hollow llm_draft.
-        // fellBackTo/fallbackReason tell the caller what ACTUALLY drafted this, not
-        // merely what was selected — see syncCommit, which must report this instead
-        // of the originally-selected provider's name.
-        const draft = await new DeterministicProvider().draftDecision(input);
-        return { ...draft, fellBackTo: "deterministic", fallbackReason: error instanceof Error ? error.message : String(error) };
+        // Tell the caller a fallback happened (and why) so it reports the provider that
+        // actually drafted the record rather than the one that was selected.
+        const fallback = await new DeterministicProvider().draftDecision(input);
+        return { ...fallback, fellBackTo: "deterministic", fallbackReason: err instanceof Error ? err.message : String(err) };
     }
 }
 export async function draftBugSafe(provider, input) {
     try {
         return await provider.draftBug(input);
     }
-    catch (error) {
-        // See draftDecisionSafe above — the same fallback contract applies to bugs,
-        // and recordFailure must report the actual (fallback) provider likewise.
-        const draft = await new DeterministicProvider().draftBug(input);
-        return { ...draft, fellBackTo: "deterministic", fallbackReason: error instanceof Error ? error.message : String(error) };
+    catch (err) {
+        // Same contract as draftDecisionSafe: surface the fallback and its cause.
+        const fallback = await new DeterministicProvider().draftBug(input);
+        return { ...fallback, fellBackTo: "deterministic", fallbackReason: err instanceof Error ? err.message : String(err) };
     }
 }
 //# sourceMappingURL=synthesize.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -94,7 +94,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "@tree-sitter-grammars/tree-sitter-yaml": "^0.6.1",
     "commander": "^15.0.0",
     "cross-spawn": "^7.0.6",
     "smol-toml": "1.9.0",
@@ -103,6 +102,7 @@
     "tree-sitter-php": "0.23.12",
     "tree-sitter-python": "0.23.4",
     "tree-sitter-typescript": "^0.23.2",
+    "tree-sitter-yaml": "npm:@tree-sitter-grammars/tree-sitter-yaml@^0.6.1",
     "zod": "^4.6.6"
   },
   "devDependencies": {

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.46.0",
+  "version": "1.47.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.46.0",
+      "version": "1.47.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {