docs(authority): one owner per kind of truth, and six documents that said otherwise - #1684
Merged
Merged
Conversation
…said otherwise Helm already has every primitive a knowledge system needs. What it did not have was a statement of which one owns which kind of truth — and six current-state documents were quietly asserting things that had stopped being true. All six were verified against the live repository before being touched. THE ADR memory/decisions/ADR-2026-08-30-helm-knowledge-authority.md records the hierarchy, the projection rule, identity normalization, the three-feature-map split, and the alternatives rejected (a fourth registry, merging the two feature maps, a KNOWN_ISSUES.md, deleting the superseded documents, a prose contradiction detector). The decisions directory's own README names this exact reconciliation as the case it exists for. The load-bearing rule: a projection may summarise an authority; it may never become a second copy with its own update path. WHAT WAS FALSE, AND VERIFIED FALSE memory/system/golfhelm-engineering-os.md — the runtime contract every session loads — claimed a guard-feature-context PreToolUse hook DENIES governed edits without loaded context. There is no such file on disk and no such hook in .claude/settings.json; the only wired PreToolUse hook matches Write|Edit| MultiEdit and refuses canonical writes. It also credited a guard-bash.sh rule deleted 2026-08-27. Corrected to POST-HOC DETECTION, which is what docs/CONTROL_PLANE_ENFORCEMENT.md has recorded the whole time. docs/README.md opened with "Everything in docs/ is hand-written prose. None of it is generated" while two generated files sat in that directory. Its Start Here list routed readers to an issue ledger whose own header reads STATUS: SUPERSEDED, and has since 2026-07-10. memory/ledgers/README.md documented a ledgers/operations/ directory that has never existed — no directory, no file, no writer, no reference. Removed rather than created: incident aftermath already has a per-feature home, and a fifth slot with no distinct lifecycle is a place for entries to go unread. memory/operations/release-queue.yml said it was "empty until then, not a placeholder for hand-written entries" directly above five hand-written repair units. The header now describes how it is actually populated. memory/README.md said collapsing the two feature-doc generations was "work still owed" and that CLAUDE.md routes to the losing one — CLAUDE.md no longer does. Reframed; the actual collapse is the next PR. docs/OBSERVABILITY.md implied every server failure reaches both Sentry and admin_events. Its scope is narrowed to EMISSION and it now points at docs/OBSERVABILITY_AUTHORITY.md for what each surface knows. .claude/rules/shipping.md answered "worktree or canonical?" two different ways in one file while AGENTS.md carried the real rule. AGENTS.md owns workspace policy; this file links. Three prose counts removed under shipping.md §1 — "there are 22", "the other 44", "192 commits stale". An index that breaks that rule about itself is not one to trust about anything else. A GATE THAT COULD NOT SEE A NAMESPACE Writing the ADR turned docs:schema-drift red on `golf_round_lifecycle` — a memory/registry.yml FEATURE ID, not a table. The gate greps memory/** for golf_*/baseball_* tokens, and feature ids share that shape, so the first .md under memory/ to name one in prose failed as a phantom table. Same substring-is-not-a-mechanism error this repo has now made three times. Fixed by excluding DECLARED registry keys only — parsed from the registry, not pattern-matched — so a misspelled table is still caught, and printed on every run so the exemption is never silent. Five tests; injection (forcing the exemption set empty) turns two of them red. docs/HELM_OS.md lands here rather than later because the ADR and the docs index both need to point somewhere, and a dangling forward reference is what docs:path-drift exists to refuse. VERIFIED preflight 0 · 1270 files / 12,106 tests 0 · docs:check 0 · knowledge:check 0 · markdown ratchet 30515, unchanged · control-plane:verify VERIFIED exit 0. Also removes #1683's disposition row, now stale — the closing half of the cost the ADR states: every PR turns the verifier red twice, once on open and once on merge, because the registry must equal the live open-PR set exactly. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbDxyygyXRUEERuGocpZZH
|
ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing |
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
|
This pull request has been ignored for the connected project Preview Branches by Supabase. |
|
Important Review skippedAuto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
The open-half of the cost the ADR states. Row lands after the PR exists because there is no other order in which it can. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NbDxyygyXRUEERuGocpZZH
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR B of the truth-convergence run. PR A (#1683) fixed the reproduced lifecycle
defect; this fixes the already-proven documentation contradictions and records
the decision that keeps them fixed.
The ADR
memory/decisions/ADR-2026-08-30-helm-knowledge-authority.md— the authorityhierarchy, the projection rule, identity normalization, the three-feature-map
split, and the alternatives rejected. The decisions README names this exact
reconciliation as what the directory exists for.
The load-bearing rule: a projection may summarise an authority; it may never
become a second copy with its own update path.
Six false current-state claims, each verified before touching
memory/system/golfhelm-engineering-os.mdguard-feature-contextPreToolUse hook denies governed edits; aguard-bash.shrule blocks deploysdocs/README.mddocs/README.mdStart HereSTATUS: SUPERSEDED, since 2026-07-10memory/ledgers/README.mdledgers/operations/directorymemory/operations/release-queue.yml.claude/rules/shipping.mdThree prose counts removed under
shipping.md§1.A gate that could not see a namespace
Writing the ADR turned
docs:schema-driftred ongolf_round_lifecycle— amemory/registry.ymlfeature id, not a table. The gate grepsmemory/**for
golf_*/baseball_*tokens and feature ids share that shape.Fixed by excluding declared registry keys only — parsed from the registry,
never pattern-matched, so a misspelled table is still caught — and printed on
every run so the exemption is never silent. Five tests; injection turns two red.
Verified
preflight 0 · 1270 files / 12,106 tests 0 ·
docs:check0 ·knowledge:check0· markdown ratchet 30515 unchanged ·
control-plane:verifyVERIFIED exit 0.🤖 Generated with Claude Code
https://claude.ai/code/session_01NbDxyygyXRUEERuGocpZZH