Repository navigation
Conversation
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
left a comment
There was a problem hiding this comment.
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
# Domainsto# 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.
Why
okfctl index build <bundle>/<neighborhood>andindex checkagainst 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 Basewas stamped onto that neighborhood index.md, overwriting the correct neighborhood title (e.g.# Domains). A sub-scopeindex checkthen reported the correct on-disk index as out of date (false positive), and a sub-scopeindex buildsilently 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 Basedefault 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 Basestay byte-identical.Tests (TDD, RED to GREEN)
internal/okf:TestRenderIndex_PreservesExistingRootHeading(root-cause), plusDefaultsRootHeadingWhenNoIndexOnDiskandPreservesKnowledgeBaseRootHeadingcontrols.cmd:TestIndexBuild_SubDirDoesNotRewriteNeighborhoodHeading(step 3),TestIndexCheck_SubDirNoFalsePositive(step 2),TestIndexBuildThenCheck_RootScopeUnchanged(root control).Verification
Conformance gate (AGENTS.md):
go test ./internal/okf/ ./cmd/ -run Conformance: ok.gofmt -l .clean;go vet ./...clean;go test ./... -raceall packages ok, zero regressions.# Knowledge Base, domains H1 stays# Domains(step 4, unchanged).# Knowledge Base(corruption); new keeps# Domains(step 3 fixed).