fix(wiki): first-occurrence wins when heading normalization collides pre-existing duplicates

Review of PR #130 found a real bug in the new normalizeHeading matching:
idx was built with idx[normalizeHeading(s.heading)] = i, plain map
assignment while iterating secsA — last write wins. A page that already
carries two on-disk sections differing only by case or whitespace (real,
pre-existing corpus drift, the exact pattern #106 itself cites) never
collided in idx before this normalization existed, since it keyed on the
exact string. After normalization they collide, and every future update
silently, deterministically routes to whichever duplicate happens to
sort last in the file — the first one is frozen forever, never
receiving an update again, with nothing to say so. Same bug class
parseSections's own doc comment already warns about (two keys sharing
one map slot means one loses lookup visibility), reintroduced here.

Fixed by keeping only the first occurrence's index when a collision
happens while building idx — deterministic, and matches "earliest is
canonical," the same reasoning behind every other on-disk-wins default
in this file.

New test reproduces the exact review finding with a positional
assertion (the fresh bullet must land adjacent to the first
occurrence's own content, not the second) — a Contains-only version of
this test would have passed even with the bug present, since nothing is
literally deleted, a bullet just silently routes to the wrong of two
still-present sections.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -100,8 +100,21 @@ review gate.
 Re-ingesting unchanged content is **byte-identical** — no diff, so brain-sync
 does not commit noise that hides real edits.
 
-Known limitation: because the on-disk frontmatter wins, `last_updated` keeps its
+Two fields are **generator-owned** and do get refreshed on a revise:
-first-ingest date on a revised page.
+`last_updated` and `source_hash`. Everything else on disk wins. The boundary is
+an explicit allowlist, so a field nobody has thought about stays human-owned.
+
+## Re-ingesting an unchanged source is skipped
+
+Ingest stores `source_hash` — sha256 of the ingested **body**, frontmatter
+excluded — on the source page. A later ingest of the same source compares it
+first and skips extraction entirely when it matches, reporting the skip rather
+than doing it silently.
+
+Body-only is deliberate: a re-crawl that stamps a new fetch date has not changed
+the source, and treating that as drift would re-extract the corpus every time a
+crawler ran. A missing or unreadable hash always means "extract" — a missed skip
+costs one extraction, a wrong skip loses an update.
 
 ## Phase 1 tools (available now)
 

ingestion/internal/pipeline/build.go

@@ -76,6 +76,9 @@ func buildFrontmatter(rp RawPage, date string) string {
 		}
 		fmt.Fprintf(&sb, "date_ingested: %s\n", date)
 		fmt.Fprintf(&sb, "last_updated: %s\n", date)
+		if rp.SourceHash != "" {
+			fmt.Fprintf(&sb, "source_hash: %s\n", rp.SourceHash)
+		}
 		if rp.Source != "" {
 			fmt.Fprintf(&sb, "source: %s\n", yamlScalar(rp.Source))
 		}

ingestion/internal/pipeline/parse.go

@@ -20,6 +20,10 @@ type RawPage struct {
 	// ingested content's own frontmatter (see parseContentFrontmatter) — never
 	// set by the LLM. json:"-" keeps them immune to same-named keys the LLM
 	// might emit. Only meaningful for Type == "source".
+	// SourceHash is sha256 of the ingested BODY (frontmatter excluded), stamped
+	// so the next ingest of the same source can tell "unchanged" from "edited"
+	// without re-running extraction (#105).
+	SourceHash string `json:"-"`
 	Source     string `json:"-"`
 	Author     string `json:"-"`
 	Published  string `json:"-"`
@@ -112,6 +116,11 @@ type sourceMeta struct {
 	Source    string
 	Author    string
 	Published string
+	// BodyHash is sha256 of the content with any leading frontmatter removed.
+	// Body-only on purpose: a re-crawl that stamps a new fetch date has not
+	// changed the source, and treating that as drift would re-extract the
+	// whole corpus every time a crawler ran (#105).
+	BodyHash string
 }
 
 // parseContentFrontmatter extracts source/author/published from a leading
@@ -154,6 +163,7 @@ func applySourceMeta(pages []RawPage, meta sourceMeta) {
 		if pages[i].Type != "source" {
 			continue
 		}
+		pages[i].SourceHash = meta.BodyHash
 		pages[i].Source = meta.Source
 		pages[i].Author = meta.Author
 		pages[i].Published = meta.Published

ingestion/internal/pipeline/pipeline.go

@@ -3,6 +3,8 @@ package pipeline
 
 import (
 	"context"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -26,6 +28,11 @@ type Config struct {
 type Result struct {
 	Pages    []string // relative paths written (or would-be written in dry-run)
 	Warnings []string
+	// Skipped reports that the source was byte-identical to the last ingest,
+	// so no extraction ran and nothing was written. Reported rather than
+	// silent: a run that does nothing must say so, or "the pipeline is fine"
+	// and "the pipeline stopped working" look the same (#105, #107).
+	Skipped bool
 }
 
 // Run ingests content and writes structured wiki pages to brainDir/wiki/.
@@ -43,13 +50,32 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 
 	sourceSlug := wiki.Slug(source)
 	date := time.Now().UTC().Format("2006-01-02")
+
+	// Drift check BEFORE any extraction: an unchanged source costs a full LLM
+	// pass over every chunk to produce a result that merges to nothing (#105).
+	// The merge is already idempotent (#103), so this is cost and signal, not
+	// correctness — which is why it is safe for it to be an early return.
+	bodyHash := hashBody(content)
+	if !dryRun && bodyHash != "" && bodyHash == storedSourceHash(brainDir, sourceSlug) {
+		return Result{Skipped: true, Warnings: []string{
+			fmt.Sprintf("source %q unchanged since last ingest (hash %s) — extraction skipped", source, bodyHash[:12]),
+		}}, nil
+	}
+
+	// The source's own page path is deterministic (sourceSlug, computed above)
+	// even before extraction runs, unlike a concept/entity page's path, which
+	// only exists once the model has produced a title. So page-aware
+	// extraction (#106) is scoped to the source page: it's the one page every
+	// chunk's prompt can be given in advance.
+	existingPage := readSourcePage(brainDir, sourceSlug)
+
 	chunks := Chunk(content, cfg.ChunkSize)
 
 	var allRaw []RawPage
 	var allWarnings []string
 
 	for _, chunk := range chunks {
-		userPrompt := BuildPrompt(schema, source, chunk, inventory)
+		userPrompt := BuildPrompt(schema, source, chunk, inventory, existingPage)
 		output, err := cfg.Complete(ctx, systemPrompt, userPrompt)
 		if err != nil {
 			return Result{}, fmt.Errorf("LLM call: %w", err)
@@ -59,7 +85,9 @@ func Run(ctx context.Context, cfg Config, brainDir, content, source string, dryR
 		allWarnings = append(allWarnings, warnings...)
 	}
 
-	applySourceMeta(allRaw, parseContentFrontmatter(content))
+	meta := parseContentFrontmatter(content)
+	meta.BodyHash = bodyHash
+	applySourceMeta(allRaw, meta)
 
 	return buildAndWrite(allRaw, sourceSlug, date, brainDir, source, inventory, allWarnings, dryRun)
 }
@@ -119,6 +147,51 @@ func buildAndWrite(rawPages []RawPage, sourceSlug, date, brainDir, source string
 	return Result{Pages: written, Warnings: warnings}, nil
 }
 
+// hashBody returns sha256 of content with any leading frontmatter block
+// removed, or "" for empty content.
+//
+// Body-only on purpose: a re-crawl that stamps a new fetch date has not changed
+// the source, and treating that as drift would re-extract the corpus every time
+// a crawler ran (#105).
+func hashBody(content string) string {
+	body := content
+	if strings.HasPrefix(body, "---\n") {
+		if _, rest, found := strings.Cut(body[4:], "\n---"); found {
+			body = strings.TrimPrefix(rest, "\n")
+		}
+	}
+	if strings.TrimSpace(body) == "" {
+		return ""
+	}
+	sum := sha256.Sum256([]byte(body))
+	return hex.EncodeToString(sum[:])
+}
+
+// readSourcePage returns the full on-disk content of the source page at
+// wiki/sources/<sourceSlug>.md, or "" when it doesn't exist yet.
+func readSourcePage(brainDir, sourceSlug string) string {
+	raw, err := os.ReadFile(filepath.Join(brainDir, "wiki", "sources", sourceSlug+".md"))
+	if err != nil {
+		return ""
+	}
+	return string(raw)
+}
+
+// storedSourceHash reads source_hash from the source page a previous ingest
+// wrote, or "" when there is no such page or no such field.
+//
+// Absence always means "extract". That is the fail-safe direction: a missed
+// skip costs one extraction, while a wrong skip loses an update silently — and
+// silence is the failure mode this repo keeps paying for.
+func storedSourceHash(brainDir, sourceSlug string) string {
+	for _, line := range strings.Split(readSourcePage(brainDir, sourceSlug), "\n") {
+		if key, value, found := strings.Cut(line, ":"); found && strings.TrimSpace(key) == "source_hash" {
+			return strings.TrimSpace(value)
+		}
+	}
+	return ""
+}
+
 // reviseOrCreate returns the bytes to write for one extracted page: merged into
 // whatever is already on disk, or the page as-is when the path is new.
 //

ingestion/internal/pipeline/pipeline_test.go

@@ -233,3 +233,161 @@ func TestRunRaw_ReIngestingUnchangedContentIsByteIdentical(t *testing.T) {
 	assert.Equal(t, string(first), string(second),
 		"re-ingesting unchanged content must leave the page byte-identical")
 }
+
+// --- #105: source drift — an unchanged re-ingest must not re-extract --------
+
+func TestRun_SkipsExtractionWhenTheSourceIsUnchanged(t *testing.T) {
+	// #103 made a re-ingest harmless (byte-identical merge). It is still not
+	// free: the full LLM extraction runs over every chunk to produce a result
+	// that merges to nothing. This is the cost half.
+	dir := t.TempDir()
+	var calls int
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		calls++
+		return `[{"title":"Shape Up","type":"source","subtype":"book","domain":"product","content":"## Summary\n\nA book.\n"}]`, nil
+	}}
+
+	content := "---\nsource: https://example.com/shape-up\n---\n\nThe body of the article.\n"
+
+	first, err := Run(context.Background(), cfg, dir, content, "shape-up", false)
+	require.NoError(t, err)
+	require.Equal(t, 1, calls, "first ingest must extract")
+	assert.False(t, first.Skipped)
+
+	second, err := Run(context.Background(), cfg, dir, content, "shape-up", false)
+	require.NoError(t, err)
+	assert.Equal(t, 1, calls, "unchanged content must not be extracted again")
+	assert.True(t, second.Skipped, "the skip must be reported, not silent")
+}
+
+func TestRun_ReExtractsWhenTheSourceBodyChanged(t *testing.T) {
+	dir := t.TempDir()
+	var calls int
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		calls++
+		return `[{"title":"Shape Up","type":"source","subtype":"book","domain":"product","content":"## Summary\n\nA book.\n"}]`, nil
+	}}
+
+	_, err := Run(context.Background(), cfg, dir, "---\nsource: x\n---\n\nversion one\n", "shape-up", false)
+	require.NoError(t, err)
+	_, err = Run(context.Background(), cfg, dir, "---\nsource: x\n---\n\nversion two — the source was edited\n", "shape-up", false)
+	require.NoError(t, err)
+
+	assert.Equal(t, 2, calls, "changed content must be re-extracted")
+}
+
+// --- #106: page-aware extraction — the model sees the page it is revising --
+
+func TestRun_ExistingSourcePageIsIncludedInTheExtractionPrompt(t *testing.T) {
+	// #103 made the merge asymmetric (on-disk wins); #106 is the other half —
+	// the extraction itself gets to see what's already there instead of
+	// producing a page blind and letting the merge reconcile it afterwards.
+	// This only proves the existing page reaches the prompt; the byte-identical
+	// guarantee for an echoed-back revision is a separate test below.
+	dir := t.TempDir()
+	for _, sub := range []string{"wiki/concepts", "wiki/entities", "wiki/sources"} {
+		require.NoError(t, os.MkdirAll(filepath.Join(dir, sub), 0o755))
+	}
+
+	seeded := "---\ntitle: 'Shape Up'\n---\n\n## Summary\n\nA book about shaping product work.\n\n## Key Claims\n\n- Appetite beats estimation.\n"
+	page := filepath.Join(dir, "wiki", "sources", "shape-up.md")
+	require.NoError(t, os.WriteFile(page, []byte(seeded), 0o644))
+
+	var gotPrompt string
+	cfg := Config{Complete: func(_ context.Context, _, user string) (string, error) {
+		gotPrompt = user
+		return mustJSON([]RawPage{{
+			Title: "Shape Up", Type: "source", Subtype: "book",
+			Content: "## Summary\n\nA book about shaping product work.\n",
+		}}), nil
+	}}
+
+	// Deliberately does not mention "Appetite beats estimation." — that phrase
+	// can only reach the prompt via the existing on-disk page, not the source
+	// content, so its presence proves the page was threaded through.
+	content := "A short editorial update to the book's listing. No new claims here."
+	_, err := Run(context.Background(), cfg, dir, content, "shape-up", false)
+	require.NoError(t, err)
+
+	assert.Contains(t, gotPrompt, "Appetite beats estimation.",
+		"the existing page's content must be visible to the extraction prompt")
+	assert.Contains(t, gotPrompt, "revis", "the prompt must ask for a revision, not a fresh page")
+}
+
+func TestRun_NewSourceHasNoExistingPageInThePrompt(t *testing.T) {
+	// The other side of the same behavior: a source with no page on disk yet
+	// must not get an "existing page" section injected into its prompt at all.
+	dir := t.TempDir()
+	for _, sub := range []string{"wiki/concepts", "wiki/entities", "wiki/sources"} {
+		require.NoError(t, os.MkdirAll(filepath.Join(dir, sub), 0o755))
+	}
+
+	var gotPrompt string
+	cfg := Config{Complete: func(_ context.Context, _, user string) (string, error) {
+		gotPrompt = user
+		return mustJSON([]RawPage{{
+			Title: "New Thing", Type: "source", Subtype: "article",
+			Content: "## Summary\n\nBrand new.\n",
+		}}), nil
+	}}
+
+	_, err := Run(context.Background(), cfg, dir, "Brand new content.", "new-thing", false)
+	require.NoError(t, err)
+
+	assert.NotContains(t, gotPrompt, "Current page",
+		"a source with no page on disk yet must not get a revision section in its prompt")
+}
+
+func TestRun_RevisionEchoingExistingPageStaysByteIdentical(t *testing.T) {
+	// The issue's explicit risk: a model given the current page will sometimes
+	// echo it back verbatim. That must not duplicate content or otherwise
+	// perturb the page — the deterministic merge is still the backstop.
+	dir := t.TempDir()
+	for _, sub := range []string{"wiki/concepts", "wiki/entities", "wiki/sources"} {
+		require.NoError(t, os.MkdirAll(filepath.Join(dir, sub), 0o755))
+	}
+
+	seeded := "---\ntitle: 'Shape Up'\n---\n\n## Summary\n\nA book about shaping product work.\n\n## Key Claims\n\n- Appetite beats estimation.\n"
+	page := filepath.Join(dir, "wiki", "sources", "shape-up.md")
+	require.NoError(t, os.WriteFile(page, []byte(seeded), 0o644))
+
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		return mustJSON([]RawPage{{
+			Title: "Shape Up", Type: "source", Subtype: "book",
+			Content: "## Summary\n\nA book about shaping product work.\n\n## Key Claims\n\n- Appetite beats estimation.\n",
+		}}), nil
+	}}
+
+	content := "A short editorial update to the book's listing. No new claims here."
+	result, err := Run(context.Background(), cfg, dir, content, "shape-up", false)
+	require.NoError(t, err)
+	require.False(t, result.Skipped)
+
+	got, err := os.ReadFile(page)
+	require.NoError(t, err)
+
+	want := "---\ntitle: 'Shape Up'\nlast_updated: " + time.Now().UTC().Format("2006-01-02") +
+		"\nsource_hash: " + hashBody(content) + "\n---\n\n" +
+		"## Summary\n\nA book about shaping product work.\n\n" +
+		"## Key Claims\n\n- Appetite beats estimation.\n"
+	assert.Equal(t, want, string(got),
+		"a revision pass that echoes the existing page back must not duplicate or alter its content")
+}
+
+func TestRun_FrontmatterOnlyChangeIsNotDrift(t *testing.T) {
+	// The hash covers the body, so re-fetching a page whose metadata moved
+	// (a re-crawl stamping a new date) is not treated as the source changing.
+	dir := t.TempDir()
+	var calls int
+	cfg := Config{Complete: func(_ context.Context, _, _ string) (string, error) {
+		calls++
+		return `[{"title":"Shape Up","type":"source","subtype":"book","domain":"product","content":"## Summary\n\nA book.\n"}]`, nil
+	}}
+
+	_, err := Run(context.Background(), cfg, dir, "---\nsource: x\nfetched: monday\n---\n\nsame body\n", "shape-up", false)
+	require.NoError(t, err)
+	_, err = Run(context.Background(), cfg, dir, "---\nsource: x\nfetched: tuesday\n---\n\nsame body\n", "shape-up", false)
+	require.NoError(t, err)
+
+	assert.Equal(t, 1, calls, "only the body counts as the source")
+}

ingestion/internal/pipeline/prompt.go

@@ -22,8 +22,18 @@ Each element must have exactly these fields:
 Wikilinks in content: [[Display Name]] — just the display name, no slug, no pipe separator.
 Only link to pages listed in the inventory or pages you are creating in this response.`
 
-// BuildPrompt constructs the user prompt for a single chunk.
+// BuildPrompt constructs the user prompt for a single chunk. existingPage is
-func BuildPrompt(schema, source, content string, inventory map[wiki.PageType][]wiki.Entry) string {
+// the full current content (frontmatter + body) of the source's own wiki page
+// when one already exists on disk, or "" for a source being ingested for the
+// first time. When non-empty, the model is asked to revise that page rather
+// than write a fresh one — see hyperguild#106. The deterministic merge in
+// wiki.Merge remains the backstop regardless of what the model returns: an
+// on-disk section the model doesn't touch survives untouched, and a section
+// it does touch only takes effect where Merge's strategy allows the fresh
+// side to change anything (bullet union, append) — never for an ordinary
+// section, so the model proposing a revision is never how a page gets
+// overwritten.
+func BuildPrompt(schema, source, content string, inventory map[wiki.PageType][]wiki.Entry, existingPage string) string {
 	var sb strings.Builder
 
 	fmt.Fprintf(&sb, "Today's date is %s.\n\n", time.Now().UTC().Format("2006-01-02"))
@@ -49,6 +59,18 @@ func BuildPrompt(schema, source, content string, inventory map[wiki.PageType][]w
 		sb.WriteString("\n")
 	}
 
+	if existingPage != "" {
+		sb.WriteString("## Current page for this source — revise it, don't restart\n\n")
+		sb.WriteString("This source has already been ingested and has the wiki page shown below.\n")
+		sb.WriteString("You are revising that page, not writing a fresh one:\n")
+		sb.WriteString("  - Add sections or claims the source below supports that this page doesn't have yet.\n")
+		sb.WriteString("  - Strengthen a claim where the source gives more detail, evidence, or nuance than what's already there.\n")
+		sb.WriteString("  - Leave unchanged whatever the source doesn't affect — reuse the existing wording verbatim rather than paraphrasing it, so an unchanged claim is recognized as unchanged.\n")
+		sb.WriteString("  - A merge step keeps this page's on-disk content for any section you don't return, so it's fine to omit a section you aren't revising.\n\n")
+		sb.WriteString(existingPage)
+		sb.WriteString("\n\n")
+	}
+
 	sb.WriteString("## Non-negotiable rules\n\n")
 	sb.WriteString("1. Output ONLY a valid JSON array — no prose, no fences.\n")
 	sb.WriteString("2. Fields: title, type, subtype (if applicable), domain (if applicable), content.\n")

ingestion/internal/wiki/merge.go

@@ -3,6 +3,7 @@ package wiki
 
 import (
 	"fmt"
+	"sort"
 	"strings"
 )
 
@@ -38,30 +39,213 @@ type section struct {
 // not present in a are appended.
 func Merge(a, b Page) Page {
 	fmA, preambleA, secsA := parseSections(a.Content)
-	_, _, secsB := parseSections(b.Content)
+	fmB, _, secsB := parseSections(b.Content)
 
+	// First occurrence wins on a collision — a page can already carry two
+	// on-disk sections that only differ by case or whitespace (the exact
+	// corpus drift this normalization exists to catch going forward, found
+	// pre-existing in review of PR #130): a plain last-write assignment
+	// here would silently and deterministically route every future update
+	// to whichever duplicate happens to sort last in the file, freezing
+	// the other one forever with nothing to say so.
 	idx := make(map[string]int, len(secsA))
 	for i, s := range secsA {
-		idx[s.heading] = i
+		key := normalizeHeading(s.heading)
+		if _, exists := idx[key]; !exists {
+			idx[key] = i
+		}
 	}
 
 	for _, sB := range secsB {
-		i, exists := idx[sB.heading]
+		key := normalizeHeading(sB.heading)
+		i, exists := idx[key]
 		if !exists {
-			idx[sB.heading] = len(secsA)
+			idx[key] = len(secsA)
 			secsA = append(secsA, sB)
 			continue
 		}
 		sA := secsA[i]
 		switch {
-		case bulletSections[sB.heading]:
+		case bulletSectionsNorm[key]:
 			secsA[i].content = mergeBullets(sA.content, sB.content)
-		case appendSections[sB.heading]:
+		case appendSectionsNorm[key]:
 			secsA[i].content = appendNew(sA.content, sB.content)
 		}
 	}
 
-	return Page{Path: a.Path, Content: rebuildContent(fmA, preambleA, secsA)}
+	return Page{Path: a.Path, Content: rebuildContent(refreshOwned(fmA, fmB), preambleA, secsA)}
+}
+
+// normalizeHeading returns the key Merge uses to decide "is this the same
+// section" — trimmed and case-folded, so "Key Claims" and "Key claims" match
+// (hyperguild#106: heading casing drift must not fork a section). It is used
+// only for that comparison; the on-disk section's original heading text
+// (secsA[i].heading, untouched here) is what actually gets written out, so a
+// human's heading casing is never silently rewritten by a merge.
+func normalizeHeading(h string) string {
+	return strings.ToLower(strings.TrimSpace(h))
+}
+
+// bulletSectionsNorm and appendSectionsNorm are bulletSections/appendSections
+// keyed by normalizeHeading instead of exact text, so a section's merge
+// strategy (union bullets, append) is chosen by the same normalized identity
+// Merge uses to match it — otherwise a heading that matched an on-disk
+// section (case-insensitively) could still fail the exact-string strategy
+// lookup and silently fall through to "keep a's version," dropping b's
+// content instead of unioning or appending it.
+var bulletSectionsNorm = normalizeSet(bulletSections)
+var appendSectionsNorm = normalizeSet(appendSections)
+
+func normalizeSet(names map[string]bool) map[string]bool {
+	out := make(map[string]bool, len(names))
+	for k := range names {
+		out[normalizeHeading(k)] = true
+	}
+	return out
+}
+
+// generatorOwned names the frontmatter fields the ingest pipeline may refresh
+// on a page it is revising. Everything else on disk wins.
+//
+// #103 made the on-disk frontmatter win wholesale, which is what stops a
+// regenerating writer from overwriting human-set metadata — a title someone
+// fixed, or the claim-property envelope (brain#21). The cost was that fields
+// the generator legitimately owns froze at their first-ingest values: when it
+// last ran, and what it last saw.
+//
+// An explicit allowlist rather than a carve-out: the ownership boundary is
+// nameable, and a field nobody has thought about stays human-owned by default,
+// which is the safe direction.
+var generatorOwned = map[string]bool{
+	"last_updated": true,
+	"source_hash":  true,
+}
+
+// fmLine is one line of a frontmatter block: a parsed key/value pair, or a
+// raw line (blank, comment, or anything else that isn't a simple "key:
+// value") kept verbatim. Same shape as api.frontmatter's fmLine — this
+// package doesn't import that one (it's unexported there, and a's/b's
+// frontmatter here always arrives as a string, not a parsed struct), so the
+// small, already-proven set()-appends-if-absent behavior is reproduced
+// locally rather than string-index surgery reinvented per call site.
+type fmLine struct {
+	key, value, raw string
+}
+
+// parseFrontmatterBlock parses a "---\n...\n---\n" fenced block (the shape
+// parseSections produces) into an ordered line list. A block with no
+// opening/closing fence — including the empty string, a page with no
+// frontmatter at all — returns nil, ok=false: there is nothing to update in
+// place, only something to potentially create.
+func parseFrontmatterBlock(block string) (lines []fmLine, ok bool) {
+	if !strings.HasPrefix(block, "---\n") {
+		return nil, false
+	}
+	rest := block[len("---\n"):]
+	end := strings.Index(rest, "\n---\n")
+	if end < 0 {
+		return nil, false
+	}
+	for _, line := range strings.Split(rest[:end], "\n") {
+		// An indented line is a continuation (a YAML block-list item, a
+		// wrapped value) never a top-level key, regardless of whether it
+		// happens to contain a colon — "  - 'Chapter 3: The Reckoning'"
+		// is not a key named "- 'Chapter 3". Checked before Cut so a
+		// colon inside one never reaches the key/value path at all.
+		if line != "" && (line[0] == ' ' || line[0] == '\t') {
+			lines = append(lines, fmLine{raw: line})
+			continue
+		}
+		key, val, found := strings.Cut(line, ":")
+		key = strings.TrimSpace(key)
+		if !found || key == "" || strings.HasPrefix(strings.TrimSpace(line), "#") {
+			lines = append(lines, fmLine{raw: line})
+			continue
+		}
+		lines = append(lines, fmLine{key: key, value: strings.TrimSpace(val)})
+	}
+	return lines, true
+}
+
+// setLine updates key's value in place if lines already has it, or appends
+// a new entry if it doesn't — the one behavior the original refreshOwned
+// got wrong (PR #126 review, round 2: it only ever updated in place).
+func setLine(lines []fmLine, key, value string) []fmLine {
+	for i := range lines {
+		if lines[i].key == key {
+			lines[i].value = value
+			return lines
+		}
+	}
+	return append(lines, fmLine{key: key, value: value})
+}
+
+func renderFrontmatterBlock(lines []fmLine) string {
+	if len(lines) == 0 {
+		return ""
+	}
+	var sb strings.Builder
+	sb.WriteString("---\n")
+	for _, l := range lines {
+		switch {
+		case l.key == "":
+			sb.WriteString(l.raw)
+		case l.value == "":
+			// A key with nothing after the colon (the YAML block-list shape:
+			// "aliases:" followed by indented "- item" lines on their own
+			// raw lines) must stay bare — "key: " with a trailing space
+			// is a different, if invisible, byte sequence, and this file's
+			// whole purpose is byte-stability across an unrelated merge.
+			sb.WriteString(l.key)
+			sb.WriteByte(':')
+		default:
+			sb.WriteString(l.key)
+			sb.WriteString(": ")
+			sb.WriteString(l.value)
+		}
+		sb.WriteByte('\n')
+	}
+	sb.WriteString("---\n")
+	return sb.String()
+}
+
+// refreshOwned returns a's frontmatter with the generator-owned fields taken
+// from b where b supplies them. Fields absent from b keep a's value, so a
+// generator that stops emitting a field cannot blank it.
+//
+// A field b supplies that a doesn't have yet — every page ingested before
+// this mechanism existed has no source_hash line at all — is appended, not
+// dropped (round 1 of review: dropping it silently meant source_hash never
+// populated for the pre-existing corpus). If a has no frontmatter fence at
+// all, one is created to hold the new fields rather than splicing raw
+// "key: value" text into the body (round 2: that corrupted the page and the
+// fields would duplicate on every subsequent merge, since unfenced text
+// isn't recognized as frontmatter by parseSections on the next pass).
+func refreshOwned(a, b string) string {
+	bLines, _ := parseFrontmatterBlock(b)
+	bVals := make(map[string]string)
+	for _, l := range bLines {
+		if l.key != "" && generatorOwned[l.key] {
+			bVals[l.key] = l.value
+		}
+	}
+	if len(bVals) == 0 {
+		return a
+	}
+
+	aLines, _ := parseFrontmatterBlock(a) // ok==false (no fence) -> aLines nil, same as "start fresh"
+
+	// Sorted for a deterministic, byte-stable result when more than one
+	// field is appended in the same call — map iteration order isn't.
+	keys := make([]string, 0, len(bVals))
+	for k := range bVals {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, k := range keys {
+		aLines = setLine(aLines, k, bVals[k])
+	}
+	return renderFrontmatterBlock(aLines)
 }
 
 // parseSections splits markdown into its frontmatter, its preamble (content

ingestion/internal/wiki/merge_test.go

@@ -174,3 +174,223 @@ title: X
 	assert.Contains(t, got, "Does this converge?", "existing question must survive")
 	assert.Contains(t, got, "What happens under load?", "new question must be added")
 }
+
+func TestMerge_GeneratorOwnedFrontmatterFieldsAreRefreshed(t *testing.T) {
+	// #103 made on-disk frontmatter win wholesale, which is what protects
+	// human-set fields from a regenerating writer. The cost was that fields the
+	// generator legitimately owns — when it last ran, what it last saw — froze
+	// at their first-ingest values. An explicit owned-set is the boundary:
+	// named fields the generator may refresh, everything else human-owned.
+	existing := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+last_updated: 2026-01-01
+source_hash: aaaa
+half_life: durable
+claim_provenance: asserted
+---
+
+## Summary
+
+Original.
+`}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'Renamed by the model'
+last_updated: 2026-08-22
+source_hash: bbbb
+---
+
+## Summary
+
+Rewritten by the model.
+`}
+
+	got := Merge(existing, fresh).Content
+
+	assert.Contains(t, got, "last_updated: 2026-08-22", "generator owns last_updated")
+	assert.Contains(t, got, "source_hash: bbbb", "generator owns source_hash")
+	assert.Contains(t, got, "title: 'X'", "a human-set title must survive regeneration")
+	assert.Contains(t, got, "half_life: durable", "the claim envelope must survive regeneration")
+	assert.Contains(t, got, "claim_provenance: asserted")
+	assert.Contains(t, got, "Original.", "an existing section still wins over the model's rewrite")
+	assert.NotContains(t, got, "Renamed by the model")
+}
+
+func TestMerge_GeneratorOwnedFieldsAreAppendedWhenAPageNeverHadThemBefore(t *testing.T) {
+	// Found in review of PR #126: refreshOwned only replaced a generator-owned
+	// line that already existed in a's frontmatter — it never appended one a
+	// didn't have. Every page ingested before this feature shipped has no
+	// source_hash line at all, so on its first re-ingest after deploy, the
+	// fresh hash was silently dropped and the skip-on-unchanged feature this
+	// PR exists to build would never engage for the entire pre-existing
+	// corpus, permanently, with nothing telling anyone.
+	existing := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+---
+
+## Summary
+
+Original.
+`}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'Renamed by the model'
+last_updated: 2026-08-22
+source_hash: bbbb
+---
+
+## Summary
+
+Rewritten by the model.
+`}
+
+	got := Merge(existing, fresh).Content
+
+	// Exact frontmatter block, not Contains: the second review round found
+	// that a substring check doesn't prove the fields landed inside a valid
+	// fence, in the right order, or that the fence itself wasn't corrupted —
+	// two independent mutations (closeIdx targeting the wrong fence, reversed
+	// sort) both survived a Contains-only version of this test.
+	want := "---\ntitle: 'X'\nlast_updated: 2026-08-22\nsource_hash: bbbb\n---\n\n## Summary\n\nOriginal.\n"
+	assert.Equal(t, want, got)
+}
+
+func TestMerge_GeneratorOwnedFieldsCreateAFrontmatterBlockWhenThePageHadNoneAtAll(t *testing.T) {
+	// Second review round on PR #126: when a has no frontmatter fence at all,
+	// the append fallback spliced raw, unfenced "key: value" lines straight
+	// into the body -- worse than the original bug, because the next
+	// parseSections call wouldn't recognize them as frontmatter (they don't
+	// start with `---`), so they'd be absorbed as ordinary preamble text and
+	// re-duplicate on every subsequent merge instead of updating in place.
+	existing := Page{Path: "wiki/sources/x.md", Content: "## Summary\n\nOriginal.\n"}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+last_updated: 2026-08-22
+source_hash: bbbb
+---
+
+## Summary
+
+Rewritten by the model.
+`}
+
+	got := Merge(existing, fresh).Content
+
+	want := "---\nlast_updated: 2026-08-22\nsource_hash: bbbb\n---\n\n## Summary\n\nOriginal.\n"
+	assert.Equal(t, want, got)
+}
+
+func TestMerge_GeneratorOwnedFieldsMixedReplaceAndAppend(t *testing.T) {
+	// a already has last_updated (replace in place) but not source_hash
+	// (append) -- the two code paths in the same call, together.
+	existing := Page{Path: "wiki/sources/x.md", Content: `---
+title: 'X'
+last_updated: 2026-01-01
+---
+
+## Summary
+
+Original.
+`}
+	fresh := Page{Path: "wiki/sources/x.md", Content: `---
+last_updated: 2026-08-22
+source_hash: bbbb
+---
+
+## Summary
+
+Rewritten by the model.
+`}
+
+	got := Merge(existing, fresh).Content
+
+	want := "---\ntitle: 'X'\nlast_updated: 2026-08-22\nsource_hash: bbbb\n---\n\n## Summary\n\nOriginal.\n"
+	assert.Equal(t, want, got)
+}
+
+// --- hyperguild#106: heading casing drift must not fork a section ----------
+// Page-aware extraction asks the model to revise the page it's given, but
+// nothing guarantees the model reproduces a heading's exact on-disk casing
+// ("Key Claims" vs "Key claims"). Without normalizing the match key, that
+// drift silently creates a near-duplicate section instead of updating the
+// original — the failure mode #106 exists to close.
+
+func TestMerge_HeadingCaseDriftMatchesSameSection(t *testing.T) {
+	a := Page{Path: "p.md", Content: "---\ntitle: X\n---\n\n## Key Claims\n\n- Appetite beats estimation.\n"}
+	b := Page{Path: "p.md", Content: "---\ntitle: X\n---\n\n## Key claims\n\n- New pattern holds under load.\n"}
+
+	got := Merge(a, b).Content
+
+	assert.Equal(t, 1, strings.Count(got, "## Key"),
+		"casing drift in the heading must not create a second section")
+	assert.Contains(t, got, "Appetite beats estimation.")
+	assert.Contains(t, got, "New pattern holds under load.",
+		"the differently-cased section's content must still be unioned in")
+	assert.Contains(t, got, "## Key Claims",
+		"the on-disk heading's original casing must be preserved in the output")
+	assert.NotContains(t, got, "## Key claims",
+		"the fresh extraction's heading casing must not overwrite the on-disk display text")
+}
+
+func TestMerge_HeadingWhitespaceDriftMatchesSameSection(t *testing.T) {
+	a := Page{Path: "p.md", Content: "---\ntitle: X\n---\n\n## Open Questions \n\n- Does appetite scale?\n"}
+	b := Page{Path: "p.md", Content: "---\ntitle: X\n---\n\n##  Open Questions\n\n- What about remote teams?\n"}
+
+	got := Merge(a, b).Content
+
+	assert.Equal(t, 1, strings.Count(got, "## Open Questions"),
+		"surrounding whitespace drift in the heading must not create a second section")
+	assert.Contains(t, got, "Does appetite scale?")
+	assert.Contains(t, got, "What about remote teams?")
+}
+
+func TestMerge_PreExistingCaseDuplicateHeadingsRouteToTheFirstOccurrence(t *testing.T) {
+	// Found in review of PR #130: normalizeHeading's idx map is built by
+	// iterating secsA with idx[normalizeHeading(s.heading)] = i -- last
+	// write wins. Before heading normalization existed, two on-disk
+	// sections differing only by case (real, pre-existing corpus drift --
+	// the exact pattern #106 itself cites) never collided, since idx keyed
+	// on the exact string. After normalization they collide, and every
+	// fresh update silently, deterministically routes to whichever
+	// duplicate happens to appear LAST in the file -- the first one is
+	// frozen forever, never receiving updates again, with nothing to say
+	// so. A Contains-only check doesn't catch this: nothing is literally
+	// deleted, a bullet just lands under the wrong of two still-present
+	// headings. Assert it lands under the FIRST occurrence instead —
+	// deterministic and matches "earliest is canonical," same reasoning
+	// as every other on-disk-wins default in this file.
+	a := Page{Path: "p.md", Content: "---\ntitle: X\n---\n\n## Key Claims\n\n- claim one\n\n## KEY CLAIMS\n\n- claim two\n"}
+	b := Page{Path: "p.md", Content: "---\ntitle: X\n---\n\n## Key Claims\n\n- claim one\n- fresh claim\n"}
+
+	got := Merge(a, b).Content
+
+	assert.Contains(t, got, "## Key Claims\n\n- claim one\n- fresh claim\n",
+		"the fresh bullet must land in the first-occurrence section, not silently route to the last duplicate")
+	assert.Contains(t, got, "## KEY CLAIMS\n\n- claim two\n",
+		"the second duplicate is untouched by this update, not merged into or overwritten")
+}
+
+func TestRefreshOwned_CommentLinesSurviveUnmangled(t *testing.T) {
+	// Third review round on PR #126: parseFrontmatterBlock dropped the
+	// sibling api package's comment guard (strings.HasPrefix(trimmed, "#")).
+	// Without it, a comment line containing a colon gets cut at the colon
+	// and re-rendered with collapsed whitespace instead of surviving
+	// verbatim.
+	a := "---\n#see also:   https://x/y\ntitle: 'X'\n---\n"
+	b := "---\nsource_hash: bbbb\n---\n"
+
+	got := refreshOwned(a, b)
+	assert.Equal(t, "---\n#see also:   https://x/y\ntitle: 'X'\nsource_hash: bbbb\n---\n", got)
+}
+
+func TestRefreshOwned_IndentedListItemsWithColonsAreNotMisparsedAsKeys(t *testing.T) {
+	// Same round: an indented YAML block-list item that happens to contain a
+	// colon (e.g. a title with a subtitle) is a continuation line, never a
+	// top-level key, regardless of what strings.Cut finds in it. Misparsing
+	// it as a key/value pair and re-rendering strips its indentation,
+	// de-indenting it out of the list it belongs to -- and refreshOwned
+	// re-renders this block on essentially every non-skipped ingest, so this
+	// is the normal path, not an edge case.
+	a := "---\naliases:\n  - 'Chapter 3: The Reckoning'\ntitle: 'X'\n---\n"
+	b := "---\nsource_hash: bbbb\n---\n"
+
+	got := refreshOwned(a, b)
+	assert.Equal(t, "---\naliases:\n  - 'Chapter 3: The Reckoning'\ntitle: 'X'\nsource_hash: bbbb\n---\n", got)
+}