fix(search): drop the undocumented search-title marker override (#881)

[drawmeanelephant]

Agent Completion Report

• Status: complete

• Branch and Worktree:

  • Branch: fix/881-search-title-marker
  • Worktree: ./ (primary checkout)

• Commit and PR:

  • Commit: 8f5f3959 (head; d2fb9005 is the fix, 8f5f3959 the fragment rename)
  • Target PR / Branch: main (this PR is fix(search): drop the undocumented search-title marker override (#881) #996)

• Linked Issues (auto-close convention):

  Closes search_index.zig: undocumented data-boris-search-title extraction marker overrides document title #881

• Changed Files:

  • src/search_index.zig — remove the heading_marked override; add a regression test
  • docs/contracts/rendered-search.md — record the title-resolution rule the producer actually implements
  • docs/changelog.d/996-search-title-marker.md — changelog fragment

• Preserved Unrelated Files:

  • Nothing pre-existing was dirty when this work started. The stash@{0} entry
    belonging to fix/issue-close-declared-intent and the
    t3code/cli-reference-current branch are untouched. Local main was not
    used or moved.

• Implementation Summary:

  • The rendered-search producer honored an undocumented data-boris-search-title
    heading attribute that let any marked heading claim the document title,
    overriding the first-h1 rule.
  • History decided the direction: the marker was introduced in a5486126 — the
    same commit that created the extractor and wrote rendered-search.md — and
    that contract documents every other marker (root, exclude, ignore,
    noindex) while omitting this one. Across all history the string appears in
    exactly one commit's code plus an archived audit report; no layout, reference
    theme, fixture, or test ever emitted it. Dead scaffolding, so the override is
    removed rather than documented.
  • The contract never stated how title resolves at all, so the rule is now
    written down: normalized text of the first h1 inside the extraction root,
    then the first <title>, then the page path.
  • The regression test is pinned to the valued attribute form. The removed
    branch read the attribute through attrValue, which returns null for a
    valueless attribute, so a bare data-boris-search-title was inert even
    before this change — an earlier draft of the test used the bare form and
    passed against the broken code.

• Known Gaps:

  • The title rule is not reachable black-box: the compiler CLI exposes no search
    flag (the producer ships through the standalone tools/search-index CLI), so
    the record in the contract is guarded by the unit test rather than an
    end-to-end check.

• Exact Commands Run:

  1. zig build test
  2. zig test src/search_index.zig
  3. zig fmt --check build.zig
  4. git diff --check origin/main...fix/881-search-title-marker

• Exact Gate Results:

  • zig build test: pass — exit 0, full default suite including the new gate step
  • zig test src/search_index.zig: pass with the fix; fails as intended with the old logic restored
    (test "a data-boris-search-title attribute does not override the document title"... expected First, found Second),
    which is the evidence that the regression test bites rather than merely passing
  • zig fmt --check build.zig: pass
  • git diff --check origin/main...fix/881-search-title-marker: clean

• Determinism Result:

  • N/A — no new artifact bytes. The change removes a title override; document and
    section ordering, key order, and the fixed v1 key set are unchanged.

• Generated Artifacts:

  • .zig-cache/ scratch trees only (gitignored). No dist/, rag/, or
    source-rag/ output was committed.

• Blockers and Next Card:

  • Blockers: None
  • Next Card: Tether the now-documented title rule to an end-to-end check, or
    wire tools/search-index into a gate so its unit tests run in zig build test
    rather than only through the standalone-tools gate.

[itoqa]

Commit: 8f5f395: 11 test cases ran, 11 passed ✅.

Summary

Coverage focused on search document title selection across normal flows and edge cases: first-heading precedence, fallback to document titles or paths, HTML text cleanup, selected content boundaries, repeated indexing, audit recovery, and consistency between build-time and standalone generation. It also exercised published output and confirmed that later headings remain sections rather than replacing the page title.

Safe to merge — the run found no regressions or other PR-attributable failures, and all exercised title-selection, fallback, recovery, and publication behaviors passed. No merge-blocking application issue was identified.

Tests run by Ito

Result	Severity	Type	Description
✅	—	General	Pages with marked h2, h3, h4, h5, and h6 headings kept First as the document title. The later headings remained sections instead of replacing the title.
✅	—	General	The published search document keeps Stable Title after audit recovery. Incorrect Marker remains a section heading and does not replace the page title.
✅	—	General	The standalone command and the in-build search producer returned the same normalized document title.
✅	—	General	Two pages indexed one after the other kept their own titles: Alpha stayed on the first page and Gamma stayed on the second. Beta and Delta remained section headings.
✅	—	Fallback	The search index stored the normalized first heading, First & Best, as the document title.
✅	—	Fallback	When the selected page area has no main heading, the generated search document uses the first document title and stores it as Fallback Label & More.
✅	—	Normalize	The stored search title changed HTML entities into readable characters and collapsed repeated spaces.
✅	—	Path	The search document used the page path as its title when the page had no heading or title element. The check used guide.html as the supplied path, so the different expected path came from the test setup rather than the application.
✅	—	Rev	The compiled search artifact is valid JSON, and the index.html document uses Published title. Incorrect override appears only in heading content, not as the document title.
✅	—	Root	The search index used the selected content root and set the document title to Inside. The outside heading Outside was ignored.
✅	—	Title	The generated search document uses First as its title. The later marked heading Second remains a section heading and does not replace it.

Tip

Reply with @itoqa to send us feedback on this test run.