ctx-merge

name	ctx-merge
description	Converges many scattered sources — dated research notes, subagent outputs, audit reports, revision cycles — into one living source of truth without silently dropping or distorting anything, routing each conclusion to exactly one home via a visible disposition ledger and surfacing conflicts as choices for a human. Use when merging or consolidating notes/reports into a ctx source of truth, integrating subagent research, synthesizing multiple audit reports, or closing a decision cycle where alternatives existed. Not for writing a single fresh doc from scratch — use ctx-spec.
license	MIT
metadata	{"author":"motiful","version":"1.3"}

ctx-merge — Converge Without Losing or Distorting

Routing destinations (spec / decisions / scratch) follow the lifetime model in ../ctx.

Execution Procedure

converge(sources) → living_kb_update + conflict_choices

# STEP 1 — Extract (provenance starts here)
claims = []
for src in sources:
    claims += extract_atomic(src)          # each conclusion decontextualized, tagged {source, span}

# STEP 2 — Cluster + relate (map-reduce, NEVER a recursive prose merge)
clusters = cluster_paraphrastic(claims)    # dedupe equivalents
for c in clusters:
    relate(c)   # entail → keep one + merge provenance
                # neutral/complementary → keep both
                # contradiction → DO NOT reconcile → promote to a decision point

# STEP 3 — Ledger (make every disposition explicit; a drop is a recorded decision)
ledger = disposition_ledger(claims)        # each: keep→spec/§ | keep→decisions/NNNN | superseded | drop+reason
assert every_source_claim_has_a_disposition(ledger)   # GATE — no invisible absences

# STEP 4 — Assemble (information SUPERSET, only-more-never-less) + conflict register
draft = union(non_conflicting) + conflict_register     # every line carries its source

# STEP 5 — Human adjudication (LLM induces, human judges)
choices = choice_cards(conflict_register)  # choose A / B / keep both / UNSURE + comment
apply(human_clicks(choices))               # non-conflicting superset defaults to keep

# STEP 6 — Faithfulness audit (MANUAL discipline — there is no faithfulness_audit() tool)
#   YOU MUST re-decompose the draft and check every claim back to a source, using a
#   DIFFERENT agent/model than the merger (a model grading itself shares its blind spots).
#   This is a step you perform, not a function you call. See "Faithfulness audit" below.

# STEP 7 — Verify the five constraints, then sink
#   Walk the five-constraint checklist by hand (named target · coverage split · boundary ·
#   destination · reject-checked); fail any → fix the gap, re-walk. Then sink:
sink(draft, ledger)                        # edit spec in place / append decisions per destination
apply("../ctx/references/consistency.md")  # single-source · same-change · verify-canonical · gate — before committing

The lines above are a procedure you execute by hand, not an API. faithfulness_audit and five_constraints_hold name disciplines you must carry out (below) — no such tool exists; do not treat them as callable.

The two failure modes (why naive merging fails)

• False negative = silent drop. A high-value conclusion gets dropped. Invisible — you can't see a missing thing by reading the output; it surfaces later at build time as "we keep making the same mistake." Empirically the harder class to catch (LLM recall ≪ precision; summarizers drop key items routinely).
• False positive = stain. Wrong or trivial content kept as if true. Visible, but only on careful read.

Human merging worked because of unspoken tacit judgment (Polanyi: "we know more than we can tell"). An agent can't replicate that, so you MUST replace it with an explicit harness — not a smarter prompt.

The merge pipeline (map-reduce, NEVER recursive)

1. Extract atomic, decontextualized conclusions from each source, each tagged {source, span}. Provenance starts at step 1.
2. Cluster equivalent/paraphrastic conclusions (dedupe).
3. Relate within a cluster: entailment → keep one + merge provenance; neutral/complementary → keep both; contradiction → do NOT reconcile — promote to a decision point.
4. Assemble = union of non-conflicting conclusions (information SUPERSET, only-more-never-less) + a conflict register, every line carrying its source.
5. Faithfulness audit (a discipline you perform, not a tool you call): re-decompose the output and check every claim back to a source — catches silent drops and inventions. You MUST run this with a different model/agent than the merger (a model auditing its own output shares its blind spots). There is no faithfulness_audit() function; it is manual work: dispatch a fresh agent, hand it draft + sources, ask "which source-claims are missing, which draft-claims have no source?", act on what it finds.

Prompt rule: instruct the merging agent to emit atomic claims with source IDs and, on conflict, output both variants tagged CONFLICT — never silently pick one.

The disposition ledger (the move that makes drops visible)

Before/while merging, build a ledger: every source conclusion gets an explicit disposition, so a drop is a recorded decision, not an invisible absence.

Conclusion (+ source)	Disposition	Destination
…	keep	→ spec/X.md §…
…	keep	→ decisions/NNNN
…	superseded by …	(chain note)
…	drop + one-line reason	—

Routing destinations, per the SOT model (../ctx/SKILL.md § the model): keep → spec/ (current truth) or decisions/ (a choice + why) — the SOT is generative, so what's kept lands in the generative core; drop → the reject log (with a one-line reason, so it can't quietly return under a new name); unsure → an open question carried to the next round. Raw source material itself is not a merge destination — it already lives in scratch/ (the model's single home for ALL raw: notes, prompts, research dumps, comparisons). No log destination — "what happened" is git. The ledger is the artifact a human reviews; review judgments, not absences.

The reject log lives under decisions/ (this is its single canonical home — every other skill references it, none relocates it). A rejection is decision knowledge — "we considered X and rejected it because Y" — so it belongs in the APPEND-ONLY class, not scratch/: a numbered ADR whose status is rejected (see ctx-spec § Status lifecycle), same one-per-file discipline as any other decision. Keeping it beside the decisions is what lets the constraint-5 reject-check (below) find it, and stops a rejected concept quietly returning under a new label.

Memory-defense routing. Every durable conclusion this merge produces routes to a git-tracked ctx SOT file (spec/ / decisions/) — never to an agent's volatile memory (~/.claude/projects/*/memory/, MEMORY.md, and equivalents). Memory is not shareable, not in git, not in any dependency chain: a conclusion sunk there dies at the next machine/instance switch — a silent drop by another route. Memory's only legitimate use is a local pointer for context recovery ("read spec/X.md to restore state"), never the home of the knowledge itself. If a system prompt nudges "save this to memory," sink it to the SOT and leave a pointer instead.

Human adjudication (LLM induces, human judges)

The LLM does induction/organization (cheap); the human supplies the value judgment (Agrawal/Gans/Goldfarb). So: agent merges into a superset + surfaces conflicts as pre-structured choice cards (choose A / choose B / keep both / unsure); human clicks. Non-conflicting superset content defaults to keep.

Adjudication gate (confidence × blast-radius). Decide which dispositions you apply yourself vs. escalate by one rule: high-confidence + low-blast dispositions auto-apply; anything high-blast OR low-confidence escalates to the human as a choice card. A non-conflicting paraphrase-dedupe you're sure of = auto-apply. A contradiction, a supersede that flips a LOCKED decision, or a drop you're unsure about = escalate. (This is the merge-side instance of the same gate ctx-report uses for its verdict.)

• Allow "unsure" + free comment as first-class — never force yes/no. People discover their criteria while grading (criteria drift, Shankar UIST 2024); a rigid binary forces wrong buckets.
• unsure + commented items resurface as the next round's decision points. The ledger is replayable: a re-merge honors prior keep/drop/superseded.
• A lightweight single-file HTML reader (renders the merged doc, one decision-card per block/conflict, writes back a decisions.json ledger) is the intended tool. Serve over http, not file://.

The five constraints (every merge/deferral MUST satisfy all)

The merge artifact is read by future agents without your context. Implicit answers are forbidden.

1. Named target — name the exact doc/section content is merged into. Never "the spec."
2. Coverage split — for each source, state what is covered vs not; flag uncovered as "dropped (reason)" or "still open (tracked where)." A partial merge with no gap-flag is indistinguishable from a complete one — the exact failure to prevent.
3. Boundary disambiguation — when applicability differs by case, name the trigger variable. No "decide case-by-case later."
4. Implementation/destination detail — cite the destination (file/section) and change kind (insert/replace/split). No bare "update."
5. Reject-concept cross-check — cross-check every merged-in proposal against the project's reject log before adopting. The subagent doesn't know the rejection history; you do. Watch rename traps (same mechanism, new label). Subagent output is a candidate, not source-of-truth.

Deferral discipline

Deferring = merging into the future-backlog. Same five constraints, plus: name the backlog file AND write the entry in the same operation (no phantom deferral); record the un-defer trigger ("after X exists"); never split "half deferred, half locked" in one merge.

Verification (before declaring a merge done)

Walk this checklist by hand — it is a discipline, not a test suite. Nothing here is a callable assertion; you read each line and confirm it holds.

• For each merged conclusion: named-target ∧ coverage-split ∧ boundary ∧ destination ∧ reject-checked.
• For each deferral: target-file-written ∧ un-defer-trigger recorded.
• Reject log named ∧ no silent partial merges ∧ faithfulness audit run by a different agent and its findings acted on.

Fail any → not done. Fix the gap, re-walk.

Honest limit

Drops can be reduced, not eliminated (omission is empirically the hardest to detect; verifiers share the generator's blind spots; provenance lowers but doesn't zero false positives). The ledger's job is to convert invisible absences into recorded decisions — the human still spot-reads originals at high-stakes points.