Skip to content

fix(index): preserve existing root index H1 on build/check - #213

Draft
cwest wants to merge 1 commit into
mainfrom
topic/fix-index-subdir-title
Draft

cwest wants to merge 1 commit into
mainfrom
topic/fix-index-subdir-title

Conversation

@cwest

@cwest cwest commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Why

okfctl index build <bundle>/<neighborhood> and index check against a SUB-DIRECTORY (not the bundle root) loaded the sub-directory as its own bundle root (empty relative root), so the generic root H1 # Knowledge Base was stamped onto that neighborhood index.md, overwriting the correct neighborhood title (e.g. # Domains). A sub-scope index check then reported the correct on-disk index as out of date (false positive), and a sub-scope index build silently corrupted it.

Fix

The OKF section 8 section-heading text is a human-facing title the producer owns, not a literal the tool may mandate (the spec does not require the bundle-root index be titled anything specific). Preserve an on-disk root index's existing H1 verbatim (rootHeading), falling back to the # Knowledge Base default only when no root index exists yet. This makes building/checking a neighborhood sub-directory keep its own title instead of corrupting it, while a first build and a real corpus whose root is already # Knowledge Base stay byte-identical.

Tests (TDD, RED to GREEN)

  • internal/okf: TestRenderIndex_PreservesExistingRootHeading (root-cause), plus DefaultsRootHeadingWhenNoIndexOnDisk and PreservesKnowledgeBaseRootHeading controls.
  • cmd: TestIndexBuild_SubDirDoesNotRewriteNeighborhoodHeading (step 3), TestIndexCheck_SubDirNoFalsePositive (step 2), TestIndexBuildThenCheck_RootScopeUnchanged (root control).

Verification

Conformance gate (AGENTS.md):

  • Layer 1 - go test ./internal/okf/ ./cmd/ -run Conformance: ok.
  • Layer 2 - gofmt -l . clean; go vet ./... clean; go test ./... -race all packages ok, zero regressions.
  • Layer 3 - REAL CORPUS (bundles/knowledge, 303 nodes), differential old-binary (main at 5bb1fac) vs fixed:
    • Root-scope build: old and new byte-identical; root H1 stays # Knowledge Base, domains H1 stays # Domains (step 4, unchanged).
    • Sub-dir build domains: old produced # Knowledge Base (corruption); new keeps # Domains (step 3 fixed).
    • Sub-dir check domains after a correct root build: old exit 1 (false positive); new exit 0 (step 2 fixed).
    • Controls: validate identical (same 4 pre-existing findings), lint --strict identical (41 to 41) - the fix changes no finding counts.

index build/check against a sub-directory (not the bundle root) loaded
it as the root ("") and stamped the generic `# Knowledge Base` H1 onto
that directory's index.md, overwriting a correct neighborhood title such
as `# Domains`. A sub-scope index check then reported the correct
on-disk index as out of date (false positive).

The §8 section heading text is a human-facing title the producer owns,
not a literal the tool may mandate. Preserve an on-disk root index's
existing H1 verbatim (rootHeading); fall back to the `# Knowledge Base`
default only when no root index exists yet. This makes building or
checking a neighborhood sub-directory keep its own title instead of
silently corrupting it, while a first build and a real corpus whose root
is already `# Knowledge Base` stay byte-identical.

Regression tests cover the sub-directory build (no `# Domains` ->
`# Knowledge Base` rewrite) and the sub-directory check (no false
positive), plus controls for the fresh-bundle default and unchanged
bundle-root behavior.

@cwest cwest left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fix is correct and complete on the merits. Root cause is pinned: building or checking a neighborhood sub-directory loaded it as the bundle root (""), so the render stamped the generic # Knowledge Base H1 over the directory's own title. Preserving an on-disk root index's existing H1 (falling back to the default only when none exists) closes the corruption at the render layer and keeps a fresh bundle and the real corpus byte-identical.

Verified against the head commit in a throwaway clone:

  • RED proven: with the source reverted to main and the new tests kept, all three bug tests fail for the right reasons — sub-dir build rewrites # Domains to # Knowledge Base, sub-dir check false-positives, and the render overwrites the on-disk H1. GREEN with the fix.
  • Full go test ./... -race: every package ok, no regressions.
  • gofmt -l . clean, go vet ./... clean, CGO_ENABLED=0 go build ./... ok.
  • The six new tests cover both reproduction steps plus the fresh-bundle default and the unchanged bundle-root controls.

The h1Re H1 match is anchored to a single leading # so second-level headings are not mistaken for the title, and it reads the same Reserved["index.md"] entry the root frontmatter already uses — consistent with the surrounding code.

One thing holds this back from being mergeable, and it is not in this diff: the required build-test check is red because govulncheck now reports GO-2026-6859 in net/http@go1.26.10 (fixed in go1.26.11). That advisory also fails on an unmodified main — it is a repo-wide toolchain matter (bump the CI go-version and go.mod to 1.26.11), not a defect in this change. No code changes needed here.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant