@davesheffer/hunch 0.12.2 → 0.13.0

package/README.md

@@ -195,6 +195,31 @@ The hook never breaks your flow: any error or unrecognized input emits nothing a
 none, every level degrades to context-only. Opt out of the hooks entirely with `hunch init
 --no-agent-hooks`.
 
+## Never Twice: corrections become enforced invariants
+
+The most expensive failure in AI coding is being corrected and then *re-corrected* — you
+tell the agent "no, never call the pay-per-token API here," it complies once, and next
+session it does it again because the feedback was stored as advisory text, not enforced.
+
+Hunch closes that loop. When you correct the agent, it captures the rule as a **first-class
+Constraint** (provenance `human_confirmed`) via the `hunch_record_correction` MCP tool — and
+from then on the **same pre-edit hook + CI Constraint Guard** hold *every* assistant to it:
+
+```text
+You:   "no — never import lodash, we ship our own utils"
+Agent: calls hunch_record_correction({ rule: "never import lodash; use src/utils",
+                                       scope_hint_file: "src/cart.ts", severity: "blocking" })
+→ con_… recorded. A later edit that adds `import _ from "lodash"` to that scope is DENIED
+  (strict firmness) and the PR fails CI — in Cursor, Copilot, Windsurf, or Claude Code alike.
+```
+
+The `UserPromptSubmit` hook nudges the agent to persist a rule whenever your prompt reads
+like a correction ("no…", "that's wrong", "never do X"), so capture is one frictionless step
+rather than a discipline. Scoping is conservative by default (the file you were in); a
+repo-wide (`**`) rule is only blocking when you pass `applies_to_all`, so one correction
+can't silently gate the whole tree. Because it's the *same* constraint machinery, a
+correction is enforced exactly like a hand-authored invariant — see firmness above.
+
 ## Semantic search (optional)
 
 By default `hunch query` and the `hunch_query` MCP tool use fast keyword (FTS) search —

package/dist/cli/index.js

@@ -18,6 +18,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { relative } from "node:path";
 import { Command } from "commander";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { indexRepo } from "../extractors/indexer.js";
@@ -736,7 +737,11 @@ program
         if (firmness === "off")
             return;
         if (evt.hook_event_name === "UserPromptSubmit") {
-            emitContext("UserPromptSubmit", HOOK_REMINDER);
+            // When the prompt reads like a correction ("no / that's wrong / never X"),
+            // nudge the agent to PERSIST it as an enforced constraint (Never Twice) —
+            // not just obey it this once and forget it next session.
+            const text = looksLikeCorrection(evt.prompt) ? `${HOOK_REMINDER}\n\n${CORRECTION_NUDGE}` : HOOK_REMINDER;
+            emitContext("UserPromptSubmit", text);
             return;
         }
         if (evt.hook_event_name !== "PreToolUse")

package/dist/core/correction.js

@@ -0,0 +1,79 @@
+/** "Never Twice" — turn a human correction of the agent into a first-class,
+ *  enforced Constraint (DESIGN: Correction Capture → Enforced Constraint).
+ *
+ *  Two pure, client-agnostic pieces, factored out of the MCP server and the
+ *  agent hook so they are unit-testable without spinning either up:
+ *   - looksLikeCorrection(): does a user prompt read like "no / that's wrong /
+ *     never do X" — the cue to nudge the agent to persist it.
+ *   - buildCorrectionConstraint(): mint the Constraint record (human-confirmed,
+ *     scoped conservatively) that the pre-edit hook + CI guard then enforce.
+ */
+import { constraintId } from "./ids.js";
+import { toPosixTarget } from "./paths.js";
+/** Correction cues. Deliberately conservative — anchored to imperative/rebuke
+ *  phrasing, not bare "no", so ordinary conversational negation ("no idea",
+ *  "no problem") doesn't train users to ignore the nudge (research risk #5). */
+const CORRECTION_PATTERNS = [
+    // OPENS with a rebuke — but exclude benign "no problem / no idea / no test exists…".
+    // The exclusion list guards against stateful conversational negation ("no tests pass",
+    // "no way to fix this") firing the nudge and training users to ignore it.
+    /^\s*no\b(?!\s+(problem|worries|idea|rush|need|biggie|thanks|thank|prob|clue|luck|difference|harm|reason|point|test|tests|way|ways|chance|context|functions?|method|file|files|change|changes|diff|other|more))/i,
+    /^\s*(nope|stop)\b/i,
+    /\b(that'?s|that is|this is) (wrong|incorrect|not right|not what)\b/i,
+    /\b(never|do not ever|don'?t ever) (do|use|call|add|write|put|import|commit|touch)\b/i,
+    /\b(don'?t|do not) (do|use|call|add|write|put|commit) (that|this|it)\b/i,
+    /\b(you must|must always|you should always|make sure (to|you|that you))\b/i,
+    /\b(i (already )?told you|i said|as i said|like i said)\b/i,
+    /\b(undo|revert) (that|this|it|your)\b/i,
+    /\b(not like that|don'?t do (that|this)( again)?|stop doing (that|this))\b/i,
+];
+export function looksLikeCorrection(prompt) {
+    if (!prompt || typeof prompt !== "string")
+        return false;
+    return CORRECTION_PATTERNS.some((re) => re.test(prompt));
+}
+/** One-line nudge appended to the UserPromptSubmit hook context when a prompt
+ *  reads like a correction — surfaces the write tool so the rule gets ENFORCED,
+ *  not merely remembered. Client-agnostic (no Claude-only wording). */
+export const CORRECTION_NUDGE = "This looks like a correction. If it's a rule the agent should never break again, " +
+    "call hunch_record_correction({ rule, scope_hint_file, severity, applies_to_all }) so it " +
+    "becomes an enforced, scoped constraint (held at edit-time and in CI) — not a one-off the next session forgets. " +
+    "Use severity:\"blocking\" only when the human said never/must; set applies_to_all:true only if the rule is genuinely repo-wide.";
+/**
+ * Build the Constraint a correction mints. Pure (caller passes `now`), so the
+ * scope/severity policy is testable in isolation. Key safety rule (research
+ * risk #2 — the scope footgun): a repo-wide ("**") constraint may only be
+ * BLOCKING when the caller explicitly set applies_to_all; otherwise a single
+ * mis-scoped correction would deny every edit under strict firmness, so we
+ * down-rank it to a warning.
+ */
+export function buildCorrectionConstraint(input, now) {
+    const rule = input.rule.trim();
+    if (!rule)
+        throw new Error("rule must not be empty");
+    // A blank/"." scope hint would mint a meaningless or repo-wide constraint by
+    // accident, so fall back to "**" (which the severity guard below then keeps
+    // non-blocking unless applies_to_all was explicitly set).
+    const hinted = input.scope_hint_file ? toPosixTarget(input.scope_hint_file) : "";
+    const scope = input.applies_to_all || !hinted || hinted === "." ? ["**"] : [hinted];
+    const repoWide = scope.length === 1 && scope[0] === "**";
+    let severity = input.severity ?? "warning";
+    if (severity === "blocking" && repoWide && !input.applies_to_all)
+        severity = "warning";
+    return {
+        id: constraintId(rule),
+        type: input.type ?? "correctness",
+        statement: rule,
+        scope,
+        severity,
+        enforcement: "advisory_v1",
+        rationale: input.rationale ?? "Captured from a human correction of the agent (Never Twice).",
+        source_decision: input.source_decision ?? null,
+        violations: [],
+        status: "active",
+        valid_from: now,
+        valid_to: null,
+        provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now },
+    };
+}
+//# sourceMappingURL=correction.js.map

package/dist/core/ids.js

@@ -32,8 +32,10 @@ export function decisionId(seed) {
 export function bugId(seed) {
     return "bug_" + shortHash(seed);
 }
-/** Constraint id seeded by its statement. */
+/** Constraint id seeded by its statement. Trim + lowercase so trivial
+ *  whitespace/case variants of the same rule collapse to one id (idempotent
+ *  re-capture), instead of minting a duplicate constraint. */
 export function constraintId(statement) {
-    return "con_" + shortHash(statement.toLowerCase());
+    return "con_" + shortHash(statement.trim().toLowerCase());
 }
 //# sourceMappingURL=ids.js.map

package/dist/mcp/server.js

@@ -13,6 +13,7 @@ import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
+import { buildCorrectionConstraint } from "../core/correction.js";
 import { revParse, asOfDate } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
@@ -286,6 +287,36 @@ export function buildServer(root) {
             return err(`Failed to record decision: ${e.message}`);
         }
     });
+    // -- hunch_record_correction (write-back: "Never Twice") ------------------
+    server.registerTool("hunch_record_correction", {
+        title: "Capture a correction as an enforced constraint (Never Twice)",
+        description: "When a human corrects the agent ('no, do it this way' / 'never call X here'), persist that correction as a first-class, SCOPED Constraint with provenance — so the pre-edit hook and the CI Constraint Guard hold EVERY assistant to it from now on, instead of it being forgotten next session. Writes to the shared .hunch/ graph (client-agnostic). Set severity:'blocking' only when the human said never/must; set applies_to_all:true only when the rule is genuinely repo-wide (otherwise it is scoped to scope_hint_file).",
+        inputSchema: {
+            rule: z.string().describe("The invariant in the human's words, e.g. \"never call the pay-per-token API here\"."),
+            scope_hint_file: z.string().optional().describe("A file the correction was about; scopes the constraint to it (the conservative default)."),
+            severity: z.enum(["advisory", "warning", "blocking"]).optional().describe("Default 'warning'. Use 'blocking' only for a hard never/must rule."),
+            applies_to_all: z.boolean().optional().describe("True ONLY if the rule is genuinely repo-wide (scopes to **); required to make a repo-wide rule blocking."),
+            type: z.enum(["security", "performance", "correctness", "architecture", "compliance"]).optional(),
+            rationale: z.string().optional().describe("Why it must hold."),
+            source_decision: z.string().optional().describe("id of a decision this correction derives from."),
+        },
+    }, async (input) => {
+        try {
+            if (!input.rule || !input.rule.trim())
+                return err("rule is required — state the invariant in plain words.");
+            const rec = buildCorrectionConstraint(input, new Date().toISOString());
+            const existing = store.json.get("constraints", rec.id);
+            store.json.put("constraints", rec);
+            store.reindex();
+            const enforce = rec.severity === "blocking"
+                ? "blocks a DIRECT edit to its scope at strict firmness, and fails a PR whose diff touches that scope (CI guard); blast-radius hits and lower firmness stay advisory"
+                : "flags violating edits and PRs (advisory)";
+            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}). It now ${enforce}.`);
+        }
+        catch (e) {
+            return err(`Failed to record correction: ${e.message}`);
+        }
+    });
     return server;
 }
 function provLine(record) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",