# codedouble **Repository Path**: ziruichen12138/codedouble ## Basic Information - **Project Name**: codedouble - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-06-25 - **Last Updated**: 2026-07-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CodeDouble β€” your double, watching your AI **Your AI coding agent drifts.** It forgets the goal mid-session, re-litigates decisions you already made, and confidently does the exact thing you rejected an hour ago. Telling it again doesn't stick β€” and babysitting it defeats the point. **CodeDouble is an external monitor that sits beside the session and acts on your behalf β€” toward the AI, never interrupting you.** It carries your intent as a maintained memory and holds the AI to it, so the agent stays *like you* even when you step away. ## What it does - 🎯 **Carries your intent, every turn.** Goal, constraints, decisions, todos, and rejected approaches are maintained per session (Mem0-style incremental memory β€” edited in place, never re-derived, never wiped) and injected into the AI's context each turn to steer it. - ↩️ **Sends bad changes back β€” with the receipt.** In enforce mode, a change that contradicts something you established is denied *before it lands*, and the AI is told exactly which anchor it violated, verbatim, plus how to redo it. You only ever talk to the AI; the double argues with it for you. - 🧭 **Catches drift.** Actions that stray from the session's goal or touch your avoid-list are redirected on the spot β€” including approaches you rejected in *other* sessions of the project. - βœ… **Todos clear themselves.** Completed actions stream back into the memory as evidence, so finished work drops off the list and stale intent doesn't accumulate. - πŸͺž **Learns you without labelling.** It watches what you actually do β€” accept, edit, revert, correct β€” across sessions, projects, and one global tier. Session goals stay private to their session; only habits that recur across projects graduate to global. - πŸ“ **Measures itself.** A send-back you route around is auto-labelled a false positive (no labelling work), and the gates ship with a frozen calibration suite reporting FP/FN rates β€” so "does it actually help?" is a number, not a vibe. - πŸ–₯️ **VS Code panel.** This session's goal, its full anchors, and every send-back β€” what the AI tried β†’ why it was rejected β€” paired to the session running in your window's folder. ## Get started β€” one command ```bash ./setup.sh # wires the AI-harness hooks (enforce + QC), installs the package, # pulls the local model, builds the VS Code panel. Idempotent. ./setup.sh --shadow # observe-only mode: see what it WOULD do, block nothing codedouble scope off # run in any folder: the double goes fully dark there β€” codedouble scope on # no capture, no memory, no gating. One command back on. ``` > **Icon not on the Activity Bar?** On profiles with many extensions, VS Code can race view > registration and drop the panel into Explorer (it does the same to Copilot and Python on such > setups). One-time fix: drag the **"This session"** view from Explorer onto the Activity Bar β€” > that pins it permanently. The panel is fully functional from Explorer either way. Smart dispatch keeps it cheap: a local model (qwen2.5-coder) handles the frequent per-edit checks as a rough filter; the remote judge (GLM) is consulted only where the verdict matters β€” confirming a send-back before it fires. Plain allows never leave your machine. **Two modules, one product:** 1. **The memory spine (built β€” the core).** Session-keyed anchors maintained incrementally, graduating to per-project and global distills; gateway hooks inject + gate against them (drift, quality). This is what makes the double *be you*: explicit intent, enforced. 2. **The taste module (later β€” the add-on).** Learning code-style and edit *precedent* from passive reactions (override / revert / accept), signature-matched. In scope, deliberately deferred: intent > inferred taste, and the spine must be solid first. > **Endgame vision β€” a market for doubles.** A double trained on your behavior lives *outside* > any one tool: an asset you own, portable across executors, repos, and time β€” eventually sold. > But the gate before everything is empirical: **prove the loop works on a real human first.** > The marketplace is what that unlocks, not what we build first. The rest of this page is the living design record. Open questions are marked **[OPEN]**. --- ## The spine, in one screen β€” what is built and live - **Capture** β€” editor reactions + git + chat corrections β†’ `~/.codedouble/interactions.jsonl`; gateway hooks (`UserPromptSubmit` / `PreToolUse` / `PostToolUse`) wired into the AI harness. - **Session anchors** (key = **session id** β€” same project, different goals per conversation): goal / constraints / decisions / todos / avoid in `sessions/.anchors.json`, maintained **incrementally** (Mem0-style ADD/UPDATE/DELETE/NOOP over only the new notes; never re-derived, never wiped on LLM failure; injected IDE/system blocks stripped β€” *a goal is never a selection*). - **Distills** β€” session anchors graduate (goal-free) to a per-project bucket (repo root of `cwd`) and rules recurring across β‰₯2 projects to one global distill; fresh sessions are primed from their own project's distill + global, never a foreign goal. - **Steering + gating** β€” each turn the anchors are injected to steer the AI; enforce mode gates actions: **known-bad precedent β†’ send back with the pinpoint fix; drift from the session's own anchors β†’ deny + redirect; quality check β†’ redo.** QC judges **consistency, not sufficiency**: it denies only when a change *contradicts one nameable anchor* (cited verbatim in the send-back β€” no nameable violation β‡’ allow; an atomic/mechanical step is never "insufficient"). Judging is **cascaded**: comment-only edits pass deterministically; the local model is the rough filter; the remote judge confirms only where the verdict matters β€” every would-be send-back, and allows that lexically brush an anchor. Plain allows never pay a remote call. Never blocks the never-seen; never prompts the developer. - **Smart dispatch** β€” frequent per-edit checks β†’ local model first (qwen2.5-coder); hard session-wide work β†’ remote (GLM); heuristic fallback. Empirical model floor: incremental anchor ops are local-safe; consolidation needs the remote tier; LLM prune tested and **rejected** (unreliable both tiers). - **Panel (VS Code)** β€” this session's goal + full anchors + send-backs (what the AI tried β†’ why it was rejected), paired to the AI session running in the window's folder. - **The numbers that now gate the spine** β€” *anchor fidelity* (do the injected anchors match what you'd say your goal/constraints are?) and *send-back precision* (send-backs you endorse vs fight). These replace Β§8's override-rate, which measured the deferred taste module. Send-back precision **measures itself**: a denied change that lands anyway via another path is auto-labelled a fought send-back (no user labelling). The gates are also **calibrated against a frozen fixture suite** (`tests/calibration.py`, 22 cases mutated from real failures + an adversarial set) reporting FP/FN per gate β€” local-7B-only baseline: QC FP 12% / FN 19%, drift FP 17% / FN 0%; every miss was judge capability (the remote judge got all of them right), which is what motivated the cascade. - **Outcome loop** β€” completed actions (PostToolUse) stream into per-session outcomes; the maintainer digests them as `[outcomes]` *evidence* (never intent), so finished todos self-clear and unevidenced ones are kept (verified selective on live runs). - **Per-folder control** β€” `codedouble scope off|on|status`: opt any repo out entirely (no capture, no notes, no injection, no gating β€” verified nothing is written while off), via a central off-list or a `.codedouble.off` marker committed in the repo. Default: on. - **Known limits (open, honest)** β€” QC/drift gate only Edit/Write (Bash bypasses β€” measured via the fought-send-back labels, but not yet closed); a *paraphrased* violation sharing no vocabulary with its anchor can slip the local filter without triggering remote confirmation; redaction of secrets in stored diffs still open (per-repo opt-out now exists); anchor fidelity has no automated measure yet. --- ## Original design map β€” one screen (Β§0–§12) *The sections below are the original design record, kept intact. The ask/act–preference and signature/Β§8 leg (Β§1, Β§3, Β§5–§9) describes the **taste module β€” in scope, built later**; the spine above is the product today.* - **Β§0 What a double is** β€” an external *self-learning Β· reusable Β· forceful* double of your judgment; must clear two bars: no agent can do it **and** it's a real pain. - **Β§1 Core principle** β€” detect where the agent is confident-but-wrong, route to the cheapest fix (repo β†’ history β†’ human); *index, not intelligence*. Two of three sources are commoditizing β€” the double lives in the third. - **Β§2 External supervisor** β€” a *separate* agent watches intent; it cannot be a prompt to the executor (61.2% self-reflect vs 69.4% external; RLHF killed self-calibration). - **Β§3 Ask Β· act Β· preference** β€” preference *resolves*, ask/act *gates*; every answered ask becomes a preference that lets it act next time. That loop is the learning. Escalation: your index β†’ cohort β†’ frontier LLM β†’ human. - **Β§4 Reversibility** β€” `git` makes undo ~free, so act-first/revert-wrong beats ask-on-everything; be *forceful only* when under-determined **and** irreversible. Correctness *is* convenience once you count cleanup. - **Β§5 Defensibility** β€” the moat is the *combination* A+B+C+D (external Β· ask/act+preference Β· passive behavior Β· transparent+measured); nobody has all four. Plus three structural moats: git-as-label, per-user flywheel, cross-user network effect. - **Β§6 Data layer** β€” log `resolution_event`s; `situation_signature` is make-or-break; *every user intervention (interrupt / correct / reject / revert) is a failure signal* β€” drive **preventable** to zero, make **irreducible** ("I'll know it when I see it") cheap (Β§4); `git revert` cleanest, not primary; never count never-viewed. **Positives matter too** β€” *confirmed-good* (reviewed wholesale accept) is the signal that lowers the threshold. Record faithfully per-decision; reflect (label + distill) at session end. **Calibrated reflection:** distill a rule only from repeated / consistent signal β€” confidently learning the wrong lesson = an automated mask *inside* the loop. - **Β§7 Cold start** β€” never *fully* cold (the repo **and its git history** are a prior); retrieval not training β†’ useful from the first event; mine commit history to pre-warm; **configurable cohort prior** (clean start / average / bought-expert). - **Β§8 Proof gate** β€” the one number that gates everything: *does a real human's override-rate fall?* Nobody has it. Prove it before the marketplace; it later becomes the trust certificate. - **Β§9 Path to a market** β€” prove on top coders β†’ sell B2B (institutional memory) β†’ consumer marketplace **last** (a sold double = copyable preset; IP risk). - **Β§10 First artifact** β€” a logger that resolves nothing; check whether signatures cluster before building anything. - **Β§11 How it fits** β€” three processes (executor Β· monitor Β· capture), one shared index; the index *is* the double. - **Β§12 Literature** β€” the field converged on this architecture in 2025–26; the real-human curve is the open gap. --- ## The problem, in one real example While drafting *this very document*, the assistant was given a plain instruction: **stop referencing a parked topic.** It acknowledged β€” and in the same breath referenced that topic a dozen times. Told *exactly* that, it then confidently misread the correction as being about something else and answered the wrong question. Two clean instances of the failure in two turns. Note what did **not** save it: - It is a frontier model β†’ **capability didn't help.** - It had been *told* the preference, and had even **written it to memory** β†’ **having the data didn't help.** That is the whole problem in one anecdote. The gap is not missing intelligence and not missing information β€” it is an executor that **won't recognize its own under-determined intent, and won't apply what it already knows at the moment of acting.** A smarter model doesn't fix it (capability wasn't the gap); a memory store doesn't fix it (the memory existed). What's missing is an **external monitor** that, *before the agent acts*, recalls the relevant preference and flags the ambiguity β€” which is exactly what the rest of this document designs. --- ## 0. What a double is β€” and the bar it must clear Four words, each load-bearing β€” and each a thing no shipped code agent can claim *together*: - **Self-learning** β€” learns, from your behavior (overrides, `git revert`), both *what* you'd want (**preference**) and *whether to bother you* (**ask vs. act** calibration) β€” not from hand-written rules. The commoditized slice is *static* content prefs (tabs, async); the unclaimed slice is *situation-keyed* resolution preference **+** the calibration gate (Β§3). - **Reusable** β€” it is *external* to the executor, so it is portable across models, tools, and repos. An asset **you own**, not a feature locked to one vendor. - **Forceful** β€” a supervisor with teeth: it can *halt* the executor and *inject* what the executor missed β€” but only where intervention is genuinely worth it. - **Double** β€” of *your judgment*, kept **transparent**: every assumption it makes is visible and vetoable. Not an opaque twin. **Positioning:** *not another assistant that writes code β€” a double that learns your judgment about when to ask, and that you keep.* **The bar (two gating criteria).** Every design choice must clear both: 1. **No existing code agent can resolve it** β€” a genuine unsolved gap, not something Cursor / Claude Code / Copilot / Devin already do. 2. **It is a real pain point** β€” actually felt, not hypothetical. The intersection is narrow on purpose: the famous pains attract everyone, so the target is *real-but-under-attacked*. (See Β§5 for why this design sits in that intersection β€” and Β§9 for the one move that would push it back out.) --- ## 1. The core principle > **Detect where the agent is confident but shouldn't be, and either resolve it from an index or > escalate to the human β€” exhausting cheap provable resolution before spending the human's > attention.** The agent under-uses three sources of truth because it doesn't recognize its own ignorance: 1. **The codebase** β€” under-used because it won't search. β†’ a monitor *injects* from the index. 2. **The user's prior decisions** β€” under-used because it doesn't recall. β†’ *resolve silently* from history. 3. **The user themselves** β€” under-used because it doesn't know what to ask. β†’ a monitor *queries* the human. One meta-pattern governs all three: **an external monitor that detects the agent's unrecognized ignorance and routes it to the cheapest source that can fix it.** The human is the last resort β€” the most expensive index β€” but for irreducible ambiguity, the only one with the answer. **Index, not intelligence.** The double is *retrieval over a logged index*, not a trained model of the person. This is what keeps it transparent ("I assumed X because last week you…"), dodges the data-volume ceiling, and avoids "precedent wearing a mask." **Two of these three are already commoditizing β€” the double lives in the third.** Modern agents *do* grep the repo (source 1) and *do* store content preferences via rules/memory files (source 3, weakly). What survives criterion 1 is **source 2 in its hard form**: learning *your ask/act calibration* from *passive behavior*. Everything below is built around that. --- ## 2. The double is an external supervisor It is not the executor in critic mode. It is a **separate agent** watching the executor's declared intent before it acts. Two monitors, both detecting *false confidence*: | | Code monitor | User monitor | |---|---|---| | **The gap** | agent doesn't know a helper exists | agent doesn't know what to ask the user | | **Why search fails** | won't grep for what it doesn't suspect | won't ask about intent it doesn't suspect is ambiguous | | **Fires when** | agent intent diverges from what artifacts prove (too sure, and *wrong*) | agent intent is under-determined by what the user said (too sure, and *can't know yet*) | | **Ground truth** | present & queryable (grep the repo) | **absent** β€” what the user *meant* exists nowhere | | **Resolution** | inject from code | ask the human | **Why the symmetry leaks (and how the double fixes it):** the code monitor works because its ground truth is present and queryable. The user's intent is absent β€” that's what makes it ambiguous. The bare user monitor can therefore only detect *"interpretation space is visibly plural,"* not *"wrong-for-this-user."* **The double's whole job is to make the absent oracle present** β€” turn "what the user meant" into a queryable index β€” the same move that made the code monitor work, applied to the missing oracle. **The supervisor MUST be external β€” not a prompt to the executor.** This is non-negotiable, and empirical: a *separate* supervising process recovers **69.4%** vs. only **61.2%** for telling the executor to "be careful" (Β§12, arXiv 2603.26233). The reason is structural β€” RLHF destroyed the executor's self-calibration; it is confidently wrong and *cannot feel it* (Β§12, arXiv 2505.22655). An agent cannot supervise its own confidence. That single fact is why this is a separate product and can never be a system prompt. --- ## 3. The escalation ladder β€” ask, act, preference The double runs on three primitives: **ask**, **act**, and **preference**. **Preference** is the *resolver* (what you'd want); **ask** and **act** are the *gate* (whether to bother you). They are layered, not competing: the double tries to resolve from preference, and its *confidence in that preference-match* picks act vs. ask. The three form a **loop** β€” every **ask** that gets answered becomes a new **preference**, which lets the double **act** silently next time. That loop *is* the self-learning. **Two kinds of preference β€” only one is yours to defend.** *Static content* prefs (tabs, async, naming) are stateless and commoditized (rules/memory files). *Resolution* preference β€” how **you** resolve **this class** of ambiguity, keyed to the `situation_signature` and learned from overrides/reverts β€” is the behavioral, uncopyable kind. The double needs both; the moat is the second, plus the gate. ``` agent intent under-determined (the monitor's trigger) β”‚ [1] situation resolves it? (failing test, open file, diff, repo structure) β†’ act β”‚ no [2] YOUR index resolves it WITH HIGH calibrated confidence? β†’ act, LOG assumption visibly β”‚ (this user's recent decisions, distilled prefs, how THIS repo does it) β”‚ no / low confidence [2b] cohort resolves it? (cross-user prior β€” in-scope, abstracted, low trust) β†’ act, LOG ("borrowed") β”‚ no / low confidence (configurable β€” Β§7) [2c] frontier LLM reasons it out WITH HIGH confidence? β†’ act, LOG β”‚ (escalate COMPUTE before the human β€” tokens are cheaper than attention) β”‚ no / still under-determined / IRREDUCIBLE [3] ASK the human β†’ AND write the answer back into the index └─ the back-arrow is the whole game: every escalation is a training example; the threshold drops FOR THIS SIGNATURE next time. ``` **Rungs [2b] and [2c] are both cheaper than the human β€” spend them first.** [2c] escalates *compute*: a hard case a frontier model can derive shouldn't cost an interruption β€” but only for **preventable** hardness (the answer exists, just hard to reach); **never** burn compute on **irreducible** ambiguity (Β§8), where no reasoning manufactures absent intent. [2b] borrows from the **cohort** (cross-user prior, Β§7): a fallback used only at low personal coverage, kept low-confidence and logged as *borrowed*, yielding instantly to your own signal, and **in-scope only** (free within an org/team; cross-org = abstracted patterns + consent, Β§9). **The trap to engineer against (rung 2):** "resolve silently from history" is the code-monitor's strength turned into the user-monitor's trap. Precedent ("how they fixed it before") is not current intent ("what they want now"). A double is *precedent compiled into a model* β€” more persuasive precedent, wearing the user's voice. Mitigations: - keep the double as **transparent retrieval**, not an opaque twin β†’ you can show & log the assumption; - **calibrated confidence gates rung 2** β€” only high-confidence reads resolve silently; - **log the assumption visibly** so the user can catch a bad silent resolution. --- ## 4. Reversibility (act-first, revert-later) β€” how the double escapes the tradeoff The whole thing lives on the **convenience ↔ correctness** axis. The bet is to *escape* the tradeoff, not balance it. A second instrument, with inverted economics: - **Ask-before-act:** pay `C_ask` (user attention) on *every* ambiguous action. - **Bypass-then-revert:** pay `p Β· C_revert` β€” only on the wrong fraction. - **Bypass wins when `p Β· C_revert < C_ask`** β€” actions usually right *and* cheaply reversible. **Coding has the lowest `C_revert` of any domain** because `git` is a universal, free, perfect undo. This is why act-first is *especially* viable here β€” the reversal infrastructure already exists. (It is also why the domain is *locked*: in coding, `git revert` is **both** the undo **and** the training label β€” see Β§5.) The two instruments combine into a **2Γ—2** the monitor selects within β€” and this is exactly how the double rations its **forcefulness**: ``` LOW reversibility cost HIGH reversibility cost (leaf, git-undoable) (foundational, entangled) HIGH confidence β”‚ BYPASS, log assumption β”‚ ACT, but flag for review (index dense) β”‚ β”‚ LOW confidence β”‚ BYPASS, loud + trivially revert β”‚ ASK FIRST ← the only real ask quadrant (under-det.) β”‚ β”‚ ``` **Forceful only in the bottom-right** β€” under-determined *and* hard to undo. Everywhere else the double is passive (act-first, log, revert-if-wrong). Be forceful everywhere and you've rebuilt the "always ask" strawman the whole design exists to beat. Teeth that bite only where it matters. **Reversibility is mechanically estimable** (clean git boundary? downstream deps? leaf edit vs. foundational type change?) β€” a *far more tractable* signal than calibrated intent. This is the good news: it lowers the asking rate where safe without lowering it where dangerous. **Failure modes of naive bypass-everything (must engineer against):** 1. **Detection latency** β€” `C_revert` grows with time-to-notice; a bug caught in 10s is free, three commits deep is expensive. 2. **Compounding/entanglement** β€” action B depends on wrong action A; reverting becomes untangling a dependency graph, not one `git revert`. 3. **Silent-accept poison** β€” the system mistakes *unnoticed* for *endorsed*, grows confident, and trains its own blind spot deeper. **"Never viewed" must be NO signal, not a positive.** **Authorization caveat:** "act-first on reversible edits in a branch/worktree/sandbox" is defensible (that's what branches are *for*). A forceful double must **not** bypass permission gates that guard irreversible or outward-facing actions. The 2Γ—2 keeps genuinely irreversible actions in the ask-first quadrant. **The kicker:** past a point, convenience and correctness *align* β€” a confident-wrong agent is the *most* inconvenient outcome (debugging its mess three commits deep). **Correctness IS convenience, once you count the cleanup.** --- ## 5. Why no one can copy this (defensibility) Don't argue feature-by-feature β€” you lose, because each feature exists *somewhere*. Argue the **combination**: it takes four pieces, they only work *together*, and **every existing product has at most one.** | Piece | What it means | Who has it | Who doesn't | |---|---|---|---| | **A β€” External** | a *separate* agent judges confidence, not the executor self-reflecting | reviewer/critic agents | Cursor, Copilot, "be careful" prompts | | **B β€” Right object** | learns the **ask/act decision + situation-keyed preference**, not static content prefs | arXiv 2603.26233 | Cursor Memories, all rules files | | **C β€” Right signal** | learns from **passive behavior** (overrides, `git revert`), not chat / manual rules | ~nobody | everyone (chat / manual) | | **D β€” Provable** | **transparent + measured** β€” visible/vetoable + a falling override-rate curve | ~nobody | everyone | - Cursor/Copilot memory = content prefs, from chat/manual β†’ **B and C missing.** - Code reviewers = external, but stateless, review *output* not *intent* β†’ **B and learning missing.** - Closest research (arXiv 2603.26233) = A + B, but **no cross-task persistence** β†’ **C and D missing.** **Nobody has A+B+C+D.** The rebuttal in one line: *"yes, each piece exists β€” and a car exists as a pile of parts. The product is the assembly, and no one has assembled it on a real user."* **The hardest objection, with the hardest rebuttal.** *"Just prompt the agent to be careful."* Answer with the number: self-reflection **61.2%** vs. external supervisor **69.4%** (Β§12). Not a tuning gap β€” structural. **Three moats that survive even if a competitor copies the architecture tomorrow:** 1. **Domain-locked.** It works because `git revert` is *both* the free undo *and* the training label β€” the same action that fixes the mistake teaches the double. No other domain hands you that. Durable *because* it's coding-specific. 2. **Per-user data flywheel.** Even a perfect clone of your code ships cold. Your double has *your* months of resolution history β€” uncopyable, and the switching cost compounds with use. "The more you use it, the better" is also "the more you use it, the more locked-in you are." 3. **Cross-user network effect.** With many users, a new user's cold start is warmed by a *data-driven cohort prior* (Β§7), and each resolution can improve similar users' doubles β€” so the product gets better with *total* users, not just your own history. A stronger flywheel than #2 (Waze, not a private notebook). Bounded by the IP line: free within an org/team, abstracted patterns only across orgs (Β§9). --- ## 6. Data layer β€” what to log The atomic unit is a **resolution event**: a moment where intent was under-determined and got resolved. You generate this data for free β€” capture decisions already happening, no labeling effort required. *(This "for free, from behavior" capture is piece C β€” the right signal.)* **Git history is the same schema, retrospective.** Commits β€” especially reverts and fix-ups β€” are resolution events you can mine *before* the user ever runs the double live; the single strongest cold-start accelerant (Β§7). Caveat: git gives you the `resolution` and (for reverts) the `outcome`, but the `situation_signature` and `interpretation_space` must be **inferred** from the diff, not read off β€” a wrong inference pollutes the index. ``` resolution_event { situation_signature: what made this ambiguous (THE RETRIEVAL KEY) interpretation_space: the plausible readings resolution: which reading won source: situation | double | human (which rung) reversibility_est: low | high (the 2Γ—2 axis) outcome: accepted | overridden | reverted | answered (THE LABEL) } ``` **The `situation_signature` is the make-or-break decision.** It is the retrieval key. For coding it is unusually rich & cheap to extract: failing test/error type, files & symbols in play, repo conventions touched (**reuse the code monitor's index**), phrasing class of the request ("fix it" / "clean this up" / "make it like X"), prior art in this repo. - Too coarse β†’ confidently misapplies last week's resolution (automated mask). - Too fine β†’ coverage always sparse, never exits cold start, asks forever. This same coarse/fine knife-edge governs **generalization**: turning one event ("remove this comment") into a principle ("stop writing obvious comments") = choosing a coarser signature. The LLM *proposes* a generalization; the user's later behavior *corrects the altitude* (an over-broad generalization shows up as an override spike, Β§8). Generalize aggressively for coverage; let behavior pull it back. **Labels come from behavior, not surveys β€” and the unit is *intervention*.** A perfectly calibrated double would need **zero** user intervention; so *every* intervention β€” an interrupt, a "no, do it this way," a re-prompt, a rejected diff, a hand-edit, a `git revert` β€” is a deviation from perfect: a **failure signal**. The cheapest arrive *seconds* after the mistake, before commit, before compounding (Β§4); `git revert` is the *cleanest* but the *latest*. **Treat intervention as the unit you count and drive down.** *Negatives (raise the threshold β€” "be more careful here"):* - **interrupt** β€” user *halts* the agent mid-execution. The **earliest and among the strongest** negatives β€” they couldn't even let it finish. - **override** β€” agent silently resolved an under-determined point as X; user corrected to Y (Xβ†’Y). The **primary, highest-volume** label β€” *any* in-conversation change request counts. The "confident-and-wrong" event. - **revert** β€” user undid a *committed* change (`git revert`/`checkout`). The *cleanest* unambiguous negative (timestamped, free from the medium β€” the moat, Β§5), but the **latest**: it only fires after the user shipped and lived with the mistake. *Positives (lower the threshold β€” "you got this right, act silently next time"):* - **confirmed-good** β€” the double reasoned it out, **laid the breakdown out legibly**, and the user **reviewed and accepted it wholesale** (accept-all on a diff/plan, merged unchanged, "yes, all of that"). The **confident-and-RIGHT** event β€” the mirror of `override`, and the strongest *calibration* positive: acting silently was vindicated β†’ the threshold drops for this signature. - **answered** β€” human answered a clarifying question. The strongest *content* positive (gives the right reading directly) and confirms the ask was warranted; rarest, worth ~100Γ— a silent-accept. - **accepted (silent)** β€” weak positive **only if `viewed`**; **down-weight hard, time-decay, and never count never-viewed as positive** (that's silent-accept poison, Β§4, not endorsement). **Why positives are not optional.** Negatives alone only ever say "be more careful" β†’ the threshold drifts *up* β†’ the double regresses to the "always ask" tool. **Positives are what make the threshold come *down*** β€” the Β§8 "rate falling" claim is impossible without them. A positive's strength scales with **evidence of review**: reviewed-wholesale-accept is gold, never-viewed is *zero*. And **legibility earns it** β€” the double's clear breakdown is what turns a wholesale accept into a real endorsement rather than a rubber stamp (the transparency of Β§3 paying off as signal). **Granularity: capture per *decision*, label and learn per *session*.** The raw `resolution_event` is logged **per decision** β€” it must be, because the index is keyed by `situation_signature` and retrieval matches a new situation to past *decisions*, not whole sessions. But **outcomes and the reflection/distillation pass run per session** (best defined git-aligned: a branch / PR / task), because that's how users actually react β€” they don't grade each answer, they merge the PR, ship it, or redo it. **Credit assignment:** explicit interventions label *their* decision (override at turn 5, revert of file X = precise negatives); the **session outcome labels the rest** (merged-clean β†’ `confirmed-good` for the un-intervened decisions; reverted / abandoned β†’ negative). Session is also the natural **measurement window** for Β§8. Trade-off: session labels are coarser (they can't pin *which* decision mattered) β€” which is exactly why the precise per-decision interventions carry the fine signal and the session outcome only fills the gaps. **Two phases: faithful record (hot path) β†’ reflect (session end).** During the session, *record faithfully and judge nothing* β€” log the raw event stream (intents, actions, interventions, `viewed`, diffs, SHAs, timestamps) losslessly and unopinionated. All interpretation waits for a single **reflection pass at session end**: credit assignment, correction-vs-iteration classification, distillation of raw events β†’ stable preference statements, signature extraction, index/persona update, and (if opted in) abstract-then-contribute to the cohort (Β§7 β€” reflection is the single chokepoint where the IP boundary is enforced). Two payoffs: the hot path stays cheap and never slows the executor; and because the raw log is **event-sourced ground truth**, a wrong signature or labeling rule is fixed by **re-reflecting over the faithful log, not re-collecting** β€” which de-risks the make-or-break signature design (Β§10). Durable learning lands only at reflection; *within* a session the double still won't repeat a just-corrected mistake, because the recent raw events sit in its live context β€” that's ephemeral, not an index commit. **Calibrated reflection β€” the double must not learn the *wrong* thing.** Reflection faces two *under-determined* inferences β€” the Β§2 problem turned inward: - **Credit assignment** β€” many decisions, one fuzzy outcome: which decision earned the merge, which caused the revert three commits later? - **Distillation** β€” "user changed Xβ†’Y" could mean *prefers Y* (a rule), *this file needed Y* (narrow), or *changed their mind once* (nothing). Same behavior, multiple lessons. **The danger:** if reflection **confidently extracts the wrong lesson**, it bakes an *automated mask of the user* into the index (Β§1, Β§3) β€” the double becomes confidently-wrong *about you*, the exact failure it exists to prevent, now living **inside the learning loop**. So the make-or-break is not "can it learn" but "**can it avoid learning the wrong thing.**" **The fix is self-similar β€” point the double's own discipline back at reflection:** - **Calibrated lesson-extraction** β€” one Xβ†’Y stays a *raw event* (weak, retrievable); only **repeated, consistent** signals distill into a **preference rule**. (The Β§3 "high confidence gates silent action" rule, applied to *what becomes a rule*.) - **Generalization is a hypothesis, not a fact** β€” reflection *proposes* the altitude; later behavior confirms or narrows it (Β§6 above). Never commit an altitude from one event. - **Transparency + veto** β€” every distilled rule is visible ("the double now thinks you prefer Y") and deletable. A wrong lesson is correctable precisely because it's a *record, not a weight* β€” which is the whole reason the model stays frozen and learning lives in the index. - **Escalate when genuinely ambiguous** β€” keep it raw, or (rarely) ask: "a preference, or just this once?" Same escalation ladder, pointed at the learning step; the answer is a gold label. **The payoff:** one discipline runs at *both* layers β€” **advising** the user (don't act confidently on under-determined intent) and **learning** from the user (don't learn confidently from under-determined behavior). The thing that makes the double safe is the same thing that makes its learning safe. **"All intervention is failure" is the right lens β€” but failure splits two ways.** Default-assume every intervention was preventable; that keeps the double honest (the opposite of silent-accept complacency). Then classify: - **Preventable** β€” the double should have *asked* or *known* (the right reading was recoverable from repo / history / preference, or the point was under-determined and it should have flagged it). These are the failures its job is to drive to zero. **Gold negative β€” learn (Xβ†’Y).** - **Irreducible** β€” intent that only crystallizes once the user *sees* a concrete attempt ("I'll know it when I see it"). No amount of asking prevents it; asking upfront would just annoy. The answer here is **not** "ask more" β€” it's Β§4's bottom-left quadrant: act fast, make the iteration *trivially cheap to revert*. Don't penalize the double; this floor is structural. The trap is collapsing the two β€” count irreducible iteration as the double's fault and it concludes it fails constantly β†’ confidence collapses β†’ it asks about everything β†’ it becomes the "always ask" tool you were beating. **Drive preventable intervention to zero; make irreducible intervention cheap.** --- ## 7. Cold start β€” four layers, four costs It's not one problem. - **Layer 0 β€” the situation index is never cold.** On a brand-new user, the double still has the **repo**. "How does this codebase resolve this kind of ambiguity?" is answerable from the code β€” the **same index the code monitor already built.** Rung [1] works day zero. *This is why coding is the right scope.* - **Layer 1 β€” population prior, *configurable*.** For repo-unresolvable cases, fall back to a prior β€” and let the user pick its strength (this is the Β§4 convenience↔correctness tradeoff applied to cold start): - **Clean start** β€” no cohort borrowing; pure personal + repo. Max privacy, purest *you*, slow ramp. - **Average good** β€” start from a **data-driven cohort prior** ("developers like you"). Fast ramp, decent defaults, but crowd-flavored early. - **Bought expert** β€” seed from a *specific* expert's double (the marketplace premium tier, Β§9). The knob sets the **ramp and the long tail, not the destination**: for any situation you personally cover, your signal overrides the cohort, so clean and average *converge* on the head and differ only on the rarely-hit tail. Two **independent consent toggles** β€” *receive* a cohort prior / *contribute* your resolutions (cross-org contribute = abstracted patterns only, Β§9). Defaults: within-team β†’ cohort on (institutional memory); individual / cross-org β†’ clean by default, cohort opt-in. *(Advanced: set it per situation-class β€” borrow the crowd for common/low-stakes, stay clean for your distinctive, high-stakes judgment.)* - **Layer 2 β€” fast personalization, not training.** The double is **in-context/retrieval, not fine-tuned** β†’ a *single* resolution event is usable immediately. Cold start ends not after N examples but after the *first* resolution **per situation-class**. *Verified backing (Β§12):* in-context preference-following **collapses below 10% by ~10 turns** (PrefEval, ICLR'25) and retrieval is the best non-fine-tuning fix β€” so the double must **retrieve**, never ride the executor's context window. - **Layer 3 β€” explicit bootstrap (optional accelerant).** Show 5–10 real ambiguous coding situations, let the user resolve them, seed high-confidence events. Optional. **The biggest accelerant: mine the git history (user-provided).** A repo's commit log is a *retrospective stream of resolution events* β€” real decisions the author already made, for free, before the double is ever used live: - **revert commits** β†’ historical *revert* labels (the cleanest negative, Β§6); - **fix-up / follow-up commits** ("use the existing helper instead") β†’ historical *override* (Xβ†’Y); - **review-driven changes** β†’ what this team treats as wrong β†’ resolution preference; - **recurring diff patterns + `git blame`** β†’ per-author preference (the portable layer) and team consensus (the repo-scoped layer). Ingesting history upgrades "never cold" (Layer 0) from *the repo as it stands* to *the repo's whole history of decisions* β€” a far denser prior. **Caveats (same discipline as live capture):** - git shows the **resolution, not the interpretation_space** β€” you must *infer* the `situation_signature` each commit resolved; a wrong inference pollutes the index; - **committed β‰  endorsed** β€” shipped code can be a deadline hack or a reviewer's demand; treating every committed line as a positive repeats silent-accept poison (Β§4) at historical scale. Up-weight explicit reverts/fix-ups; down-weight "merely committed"; - **time-decay** β€” a 3-year-old preference may be stale; the codebase and author both moved on; - it **warms the prior, doesn't end cold start** (still per-situation-class) β€” the live override/revert/answered loop stays the gold label. *Literature status (2026 verified sweep, Β§12):* mining git/PR history to seed a **per-developer** double *before* live interaction is essentially **unstudied** β€” a genuine opening, not a solved technique. The closest work, **CodeFavor** (arXiv 2410.03837, "Commit-Instruct"), extracts *population-level* code preferences from commit pairs (not a personal double); **CIPHER** learns latent preference from a user's *edits* but on text, not code. So the per-developer git-seeding lever is ours to invent. **Reusability half-solves cold start in a new repo.** Because the double is portable and owned, a *new* project is not fully cold: the user's **personal layer** (e.g. "I hate obvious comments") transfers; only the **repo-specific layer** starts from zero. The discipline is keeping these two tiers separate β€” a repo-specific resolution must **not** leak into the portable layer, or it misfires (confident-wrong) in the next repo. **Policy: ask more when you have less.** The asking threshold is a function of how much resolution-history covers the *current signature*. Cold start isn't a phase you exit β€” it's a per-situation coverage number. A *new kind* of ambiguity correctly re-triggers asking even for an experienced user. --- ## 8. The proof gate β€” the one number that must come first *Scope note (2026-07): this Β§8 number gates the **taste module** (precedent/confidence), which is deferred. The **spine** is gated by different numbers β€” **anchor fidelity** and **send-back precision** (see "The spine, in one screen"). Kept here unchanged as the taste module's gate for when it's built.* > **Of the times the index said "high confidence, stay silent," how often did the user > override/revert β€” and is that rate falling over time?** This is the sharpest *slice* of a broader health number: the **total intervention rate** (Β§6) β€” every interrupt / correction / rejection / revert per unit of work β€” trending toward its *irreducible floor* (the "I'll know it when I see it" residue no calibration can remove). The double is working when **preventable** intervention falls and only the structural floor remains. Measure it over **reviewed** decisions only β€” a never-viewed accept is neither success nor failure (Β§6); the positive complement is **confirmed-good** (reviewed wholesale acceptance), and a healthy curve shows that *rising* as override/revert *falls*. **This is the gate before the marketplace.** Everything in Β§9 is worthless if this curve is flat. Every published paper measures this against a *simulated* user β€” and a 2026 real-human study (**Lost in Simulation**, arXiv 2601.17087) shows simulated users are *unreliable proxies* for real ones on agentic tasks, so the gap **can't be closed with a better simulator** (Β§12). **Nobody has the real-human longitudinal number.** Building this on a real developer's coding history would contribute exactly what the literature can't β€” *and* it is the precise thing that makes the double sellable later. **Later, the same curve becomes the marketplace's trust certificate.** You don't sell "trust me, it's an expert's double" β€” you sell "this double's override-rate on a held-out suite is X%." The metric that *proves it works* (now) is the metric that *makes it tradeable* (later). Build it once. --- ## 9. The path to a market for doubles The vision is double-selling; the discipline is sequence. Do **not** lead with the marketplace β€” it is the most exciting slide and the most copyable product. **Step 1 β€” Prove the loop on top coders (the wedge experiment).** Put elite engineers on it for weeks. Triple win: (a) it produces the Β§8 real-human curve nobody has; (b) it seeds the first sellable double; (c) it proves the thesis β€” the curve bends or it doesn't, and no model quality saves a flat one (Β§10). Top coders are the *right* subjects because they **override** β€” overrides/ reverts are the highest-quality labels (Β§6); novices silent-accept garbage and poison the index. **Pre-warm each coder's double from their commit history before the week starts (Β§7)**, so the curve measures *learning on top of a real prior*, not cold flailing. **Step 2 β€” Monetize B2B first.** A team's double = **institutional memory**: a new hire inherits the team's judgment on day one. Clear buyer, real budget, retention via the flywheel β€” and the double **stays in-house**, which sidesteps the marketplace's worst problem (IP, below). **Step 3 β€” The consumer marketplace (the future, last).** People sell their doubles online: a top engineer's judgment, packaged and bought. Compelling β€” and the natural endpoint of *reusable + owned*. It is also the **premium tier of the cross-user spectrum** (Β§7): *clean start* β†’ free *average cohort* prior β†’ *bought specific-expert* double β€” the marketplace just sells a **named** prior instead of the anonymous average (same axis, higher price, same IP problems in sharper form). But three hard problems make it phase-3, not the wedge: 1. **Personal doesn't transfer β€” a *sold* double is a weaker, more copyable product.** The moat was "learns *your* judgment from *your* behavior." A *bought* double learns from someone else's, so it degrades into an **expert preset** β€” which is far more copyable (a competitor ships "Senior Staff Eng rule-pack" next quarter) and **re-weakens criterion 1**. Worse, it imposes the *seller's* ask/act anxieties on the buyer β€” "precedent wearing a mask" (Β§3), but someone else's, that you paid for. 2. **IP / privacy minefield.** A double trained over weeks at a day job encodes employer conventions, proprietary patterns, secrets-by-inference. "Sell your double" can mean "sell your employer's code judgment." (Second reason B2B-first is safer β€” the double stays inside the org.) 3. **Provenance** β€” solved by Β§8's curve-as-certificate, but only if the metric exists first. **The discipline, restated:** lead with the personal learning loop (uncopyable β€” it's *your* behavior over time), not the marketplace (a sold double is a copyable preset). The marketplace is what the proven loop **unlocks**, not what we build first. --- ## 10. First artifact (buildable this week) **A logger that captures resolution events β€” and resolves nothing yet.** Rides on top of the existing code agent. Run a week. Then check: *did similar signatures actually get consistent resolutions?* - If yes β†’ the signature design works, the double is viable, build the monitor. - If no β†’ the signature is wrong, and no model quality saves it. Fix the signature first. **Measure before building the resolver.** The signature function is the single make-or-break engineering decision; validate it empirically before investing in the monitor or the resolver. This logger is also Step 1 of Β§9 β€” it is what you run on the top coders. --- ## 11. How the pieces fit Three processes, one shared index. The double is **external** to the executor β€” never in its head (post-training corrupts the executor's own confidence; calibration must be externalized). Being external is also what makes it **reusable**: a layer that wraps any executor, owned by the user. ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ WORKING AGENT (executor) β€” does the coding. Never judges its own β”‚ β”‚ intent-confidence. Emits intent before acting. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ "about to do X because..." β”‚ acts / user reacts β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ MONITOR (the supervisor) β”‚ β”‚ CAPTURE β”‚ β”‚ external. per intent: β”‚ β”‚ watches outcome: β”‚ β”‚ signature β†’ query index β”‚ β”‚ override / revert / β”‚ β”‚ β†’ coverage + confidence β”‚ β”‚ accept / answer β”‚ β”‚ + reversibility estimate β”‚ β”‚ β†’ writes resolution eventβ”‚ β”‚ β†’ select 2Γ—2 quadrant β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ human answer (gold label) β”‚ β–Ό β–Ό β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ THE INDEX ("the double") β”‚ β”‚ resolution events keyed by situation_signature. β”‚ β”‚ SHARES the code monitor's repo index as its prior. β”‚ β”‚ retrieval, not a trained twin β†’ transparent. β”‚ β”‚ portable + user-owned β†’ reusable, sellable later. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` **Same architecture as the code monitor, not a new one:** both are an external process that signs a situation, queries a shared index, acts on divergence. **One index infrastructure, two query patterns, two triggers.** --- ## 12. Relevant literature (2025–2026) The field converged on this architecture this year β€” which both validates the design and leaves the real-human longitudinal metric (the proof gate, Β§8) open. - **Ask or Assume? Uncertainty-Aware Clarification-Seeking in Coding Agents** (arXiv 2603.26233) β€” the closest built version. Separate "Intent Agent" watches execution history and halts on under-determination. Monitored multi-agent recovers **69.4%** resolve vs **70.8%** fully-specified; single-agent "be careful" only **61.2%** β†’ **the monitor must be a separate process, not a prompt to the executor.** Calibration is real & coarse (queries 62% of easy tasks β†’ 100% of hardest). Caveats: GPT-5.1 *simulator* not human; needs frontier model; prompt-scaffolded not native; cost ~2Γ— (~$3.50 vs $1.63/task). **No cross-task persistence β€” they sidestep cold start entirely** (i.e. they have A+B, not C+D β€” Β§5). - **Training Proactive and Personalized LLM Agents** (arXiv 2511.02208) β€” the *trained* fork. RL on the consequences of asking; per-user calibrated threshold **beats both "always ask" and "never ask."** The retrain back-arrow made concrete. - **T-POP: Test-Time Personalization with Online Preference Feedback** (arXiv 2509.24696) β€” build the double **at test time from recent exchanges**, not by fine-tuning. The "retrieval not training" mechanism; efficacy with modest feedback. - **PersonaAgent** (NeurIPS'25, arXiv 2506.06254) β€” two-tier **episodic + semantic** memory, per-user persona prompt, **no weight updates** β†’ the memory architecture for the double. *(Verified 3-0. The separate* Survey on Personalized & Pluralistic Preference Alignment *is arXiv 2504.07070.)* - **Position: UQ Needs Reassessment for LLM Agents** (arXiv 2505.22655) β€” base-LLM likelihoods are calibrated, **but RLHF destroys it; single-turn RLHF encourages overconfidence.** β†’ *why* calibration must live in an external monitor, not the executor. *(Not in the 2026 sweep's corpus β€” the "fine-tuning corrupts calibration" claim is asserted by motivation across the corpus, not independently re-measured here.)* - **Learning to Ask: When LLM Agents Meet Unclear Instruction** (EMNLP 2025) β€” SOTA LLMs default to assuming intent rather than asking on ambiguous requests. **Fast-personalization mechanisms (2026 verified sweep β€” 24/25 claims passed 3-vote adversarial check):** - **PrefEval** (ICLR'25 Oral, arXiv 2502.09597) β€” in-context preference-following **collapses below 10% by ~10 turns**, ~zero by 30–300; **retrieval (RAG) is the best non-fine-tuning fix** β†’ hard evidence the double must *retrieve*, not ride the executor's context (Β§7, Β§11). *(3-0.)* - **CIPHER / PRELUDE** (arXiv 2404.15269) β€” learns a user's latent preference from their **edits**, frozen model, interpretable & user-editable β†’ closest analogue to learning from diffs/reverts. *(3-0.)* - **SAGE-Agent** (arXiv 2511.08798) β€” ask-vs-act as a POMDP with a Bayesian **EVPI** objective: ask only when expected info value > interaction cost; 7–39% more coverage with 1.5–2.7Γ— fewer questions. The formal version of the Β§4 ask-gate. *(3-0.)* - **Verified ramp (ALL simulated, NONE coding):** test-time personalization is useful in **~2–10 feedback signals** (TPO ~2 steps; T-POP ~5; response-feedback RFM/PReF/LoRe ~3–30 examples). A specific "~20 interactions" figure was **refuted (0-3)** β€” don't cite it. **No real-human, coding-domain ramp exists** β€” exactly the Β§8 gap.