refactor(knowledge)!: remove unused KB policy optimization, relation graph, and invalidation helpers

[drewstone]

Problem

Eight root APIs have no consumer, together with their modules and tests (1,826 source lines and 735 test lines):

• optimizeKnowledgeBasePolicy and improveSelectedKnowledgeCandidate (kb-improvement/optimization.ts, kb-improvement/selected-candidate.ts);
• buildKnowledgeRelationGraph with neighbors, walk, isReachable, and the relation-graph types and schemas (feat(graph): add a labeled relation graph with a query surface #161, built for a Discovery Lab provenance adapter that was never adopted);
• knowledgeCitationAuditFindings (citation-lint.ts);
• planInvalidationPropagation and formatKnowledgeInvalidationProposal;
• calibrateRagAnswerJudge and createRagAnswerQualityHook (rag-eval/calibration.ts).

Change

• Delete those modules, their tests, and the cases in state-scope, graph, and rag-eval tests that exercised them.
• Remove KnowledgeRelationNode, KnowledgeRelationGraph, and their schemas. KnowledgeRelation and KnowledgeRelationSchema stay, because page relations and the index graph use them.
• In the README, replace the invalidation-propagation workflow with the retained behavior (the lint cites-invalidated warning and excludeInvalidated search), and drop the removed rows and sentences. Drop the relation-graph bullet from docs/architecture.md. verify-package.mjs no longer requires optimizeKnowledgeBasePolicy.
• Add to the unpublished 20.0.0 changelog entry (34 exports removed).

Consumer evidence

The same import scan as #240-#242 found no import of any removed name. It covered the Mac checkouts, ~/code on beelink1 and drew-gtr-pro, and fresh clones of every dependent repository. The scanner did flag walk, but the only file was Tax Agent's tangle-peer-floors.test.ts. It names the package only as a string in a peer-floor table, and "walk" appears in its comments. Discovery docs mention planInvalidationPropagation as a one-time migration in its deletion ledger; no current code calls it.

Why this is the right long-term shape

The public surface becomes the APIs products actually call. Each removed helper either had no adopter or was a one-time migration tool.

Cost

24 files, 6 insertions, 2,615 deletions. This rides the unpublished 20.0.0 major. Rollback: revert, or stay on 19.x.

Verification (beelink1, merged with origin/main)

• pnpm install --frozen-lockfile, pnpm lint (only the existing proposals.ts warning), pnpm typecheck, pnpm build, and pnpm run api:surface (642 exports) all pass.
• pnpm test: 61 files, 668 passed, 2 skipped, 0 failed. After the final import cleanup I reran state-scope.test.ts: 4/4 passed.
• node scripts/check-version-bump.mjs passes: 34 export changes are paid for by 19.1.5 -> 20.0.0.
• Every relative markdown link resolves, and git merge-tree --write-tree origin/main HEAD is clean.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[tangletools]

✅ Auto-approved PR — 32a53741

Blanket team auto-approval is intentional. This is not a code review.
No automated review runs on this PR. This approval rests on the rule above alone.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-10-06T07:17:46Z}