docs: refresh the _llm state corpus and README status against the tree - #120
Merged
Merged
Conversation
_llm/current_state.toml carried an unfilled template placeholder path and hadn't been touched since 2026-05-25 (3 commits total): it still said updated="2026-05-01" while dictyon's shared-types crate was renamed to mitos (#86), v0.2.0's changelog was cut (#58), and 100+ PRs landed. The same broken placeholder was also copy-pasted into architecture.toml, decisions.toml, and glossary.toml's source_docs arrays. The real canonical doc exists in the kanon planning tree (the same target hamma's own README auto-metadata block already links), so every occurrence now points there instead of the dead template token. README.md's Status paragraph named a closed audit issue as the "current audit backlog" and didn't mention either issue actually open when it was written; a third open issue wasn't caught either. Issue numbers in prose go stale the moment the tracker changes, so the paragraph now points at the tracker itself instead of naming specific issues.
Uh oh!
There was an error while loading. Please reload this page.
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 freeto 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.
Finding
Two live docs-drift defects.
_llm/current_state.tomlhadn't been touched since 2026-05-25 (3 commits total,git log --follow) and still carried an unfilled<canonical-state-doc>/STATE.mdtemplate placeholder in
source_docs. The same broken placeholder was copy-pastedinto
_llm/architecture.toml,_llm/decisions.toml, and_llm/glossary.toml(4 sites total,
grep -rn canonical-state-doc).README.md's Status paragraph named issue #20 ("Phase 3 audit: missingPeersChangedPatch...") as the "current audit backlog" topic set. #20 closed
2026-05-25T19:46:08Z. Of the issues open when the underlying finding was written,
neither #65 nor #67 was named, and a third (#61, open since 2026-07-21) wasn't
caught either — issue numbers embedded in prose go stale the moment the tracker
moves, independent of whether anyone remembers to update the doc.
Evidence
git log -1 --format='%ci %h' -- _llm/current_state.toml→2026-05-25 ... 3b5b82bwhile the file said
updated = "2026-05-01".crates/hamma-corerenamed tocrates/mitos(fix(lint): burn down the kanon-lint debt baseline and delete it #86, landed2026-08-08 per
git log --diff-filter=A -- crates/mitos/Cargo.toml),crates/dictyon/src/wire.rssplit intowire/mod.rs, PR chore: release main #58 cut the v0.2.0changelog (2026-07-28), and 100+ PRs merged after that (
git log --oneline 3b5b82b..origin/main | wc -l).grep -rn "canonical-state-doc" .→ 4 hits, all_llm/*.toml.block already resolves it —
Planning state: projects/hamma/STATE.md— andgh api repos/forkwright/kanon/contents/projects/hamma/STATE.mdconfirms thefile exists.
_llm/*.tomlnow point at the same target via the full URLhamma's own
CLAUDE.mdalready uses for this cross-repo link(
https://github.com/forkwright/kanon/blob/main/projects/hamma/STATE.md).gh issue list --repo forkwright/hamma --state closed→ Phase 3 audit: missing PeersChangedPatch + Node fields, no zstd, transport duplication, no tracing, no map-stream integration test #20 closed2026-05-25T19:46:08Z.
gh issue list --repo forkwright/hamma --state open→fix(deps): pin Koinon to a released tag instead of tracking main #61 (2026-07-21), Implement HTTP/2 over Noise instead of treating Noise records as control RPC boundaries #65 (2026-07-21), Build authoritative ACL policy state before advertising or activating the data plane #67 (2026-07-21), Reconcile producer guidance with the Phase A interoperability gates #118 (2026-08-26, opened
today) — none is Phase 3 audit: missing PeersChangedPatch + Node fields, no zstd, transport duplication, no tracing, no map-stream integration test #20's topic set.
Why this matters
_llm/*.tomlis the corpus other agents and tools read instead of re-derivingrepo state from scratch; a doc that's been silently wrong for three months
defeats that purpose worse than no doc at all, since it reads as authoritative.
A broken placeholder that's been copy-pasted across four files is the same
defect four times, not four defects. README's Status section is the first thing
a human or agent reads; naming a closed issue as "the current backlog" points
readers at the wrong problem set entirely.
Desired correction
Refresh
_llm/current_state.toml'ssummary,current_phase,updated, andrecent[]/open_threads[]against present-day repo state; point every<canonical-state-doc>placeholder at the real STATE.md; stop naming specificissue numbers in README's Status prose and point at the tracker instead.
Done when:
grep -rn "canonical-state-doc\|map deltas, zstd framing"returnsnothing, and
_llm/current_state.toml'supdatedfield andopen_threads[]reflect the tree at merge time. Both hold in this PR — see the diff.
Note (out of scope, flagged for the right owner)
forkwright/kanon'sprojects/hamma/STATE.md— the doc_llm/*.tomlnowpoints at — is itself stale in a worse way than what this PR fixes: its
frontmatter claims
last_updated: 2026-08-15but its body still saysVersion: v0.1.0 (unreleased), referencescrates/hamma-core(renamed 2026-08-08, beforethe claimed update date), and says "No dictyon code touched since 2026-04-13"
against 100+ merged PRs. That's a
forkwright/kanonplanning-doc defect, not aforkwright/hammaone — this PR doesn't touch it, since kanon is a sharedplanning tree outside this lane's scope.