Doc Sync

doc-sync — Keep .docs/ + README.md in sync with landed work

This skill brings a repo's documentation up to date with the work that has landed in git but not yet been written up. It is the doc equivalent of a cargo doc rebuild: the code shipped, now make the narrative match.

When to use

• After a plan closes with a GOAT/gain verdict (promote, keep-opt-in, or honest fail).
• After a batch of issues resolves (especially negative-result issues that move a primitive's status line).
• After a feature is promoted to default-on OR demoted to opt-in.
• Quarterly as a doc-hygiene gate.
• NOT for speculative work — only landed, committed work counts.

BOUNDARY.md — the 4th doc surface (added 2026-08-21)

Every repo ships a root BOUNDARY.md: Owns / Does not own / May depend on (crate-granular allowlist) / Inherited (links) / Drift ledger. It is a doc-sync surface because its drift ledger is a claim about issue state, and claims rot:

• Row ⟺ open issue. A fixable / owner-call row REQUIRES an existing issue file; a by-design row cites a decision record instead. When an issue closes, its row must be removed in the same commit — the noise-reduction rule extended to BOUNDARY.md. A row whose issue is gone is the boundary equivalent of a stale README claim.
• Flag row-without-issue and issue-without-row (a boundary issue that landed with no ledger row is invisible to the guard).
• Don't hand-verify the dep tables — run riir-ai/scripts/ci_boundary_contract.sh. It fails on an undeclared cross-repo dep, a stale allowlist row, an unparseable ledger, and on the 4 split-prep invariants. --list-deps prints the measured graph.
• Numbers in a contract are measurements, so they carry a date. If a row cites "N symbols" or "N packages", re-measure before trusting it in a new decision (riir-ai/BOUNDARY.md D2/D3 are the pattern).
• The contract is per-repo; cross-repo rules live in ONE canonical home (chain admission → riir-chain, dep matrix + split-prep → riir-ai) and every other repo LINKS. Never copy a cross-repo rule into a second file — that is the duplication doc-sync exists to catch.

The workspace repos and their doc shapes (derived, never counted — de-counted 2026-09-04)

The header carried a hand-typed count (18, measured 2026-09-01) while the workspace moved to 16 live repos on 2026-09-04 (three to git/obsolete/) — the same rot class the boundary-guard skill de-counted in its 21st run. It is 18 again since 2026-09-10 (riir-esp32 moved out of riir-chain 2026-09-06; riir-kat spun out of riir-clippy 2026-09-10) — same count, different membership, which is exactly why the count is derived and the census below is a snapshot; the one-liner derives the membership.

The header said "14 as of 2026-08-28" over a table of 12 rows until 2026-09-01 — wrong twice, and six repos had no row at all, so a sync run that walked this table skipped them silently. Don't re-type the count; derive the set the same way the boundary gate does:

cd /Users/katopz/git && for d in */; do
  [ -f "$d/BOUNDARY.md" ] && [ -d "$d/.git" ] && echo "${d%/}"
done

Canonical count + product-vs-workspace split: katgpt-rs/AGENTS.md §"Repo count".

Each repo has a different doc layout. Read the repo's AGENTS.md first — it documents the canonical layout and the numbering discipline.

The sync workflow (per repo)

Step 1 — Find the last documented commit

git --no-pager log --oneline <branch> -- ".docs/**" "README.md" | head -20

The most recent docs: commit is your baseline. Everything after it is undocumented work.

Step 2 — List landed-but-undocumented work

git --no-pager log --oneline <baseline>..<branch>

Filter for:

• feat: / fix: commits that close a plan or issue (grep the message for Plan NNN / Issue NNN).
• docs: commits that close research notes or benchmarks (these may already be half-documented).
• Promotions / demotions (search for promote, demote, default-on, opt-in).

Cross-reference against the repo's .plans/, .issues/, .benchmarks/, .research/ folders — read the highwater files to know the current max number.

Step 3 — Classify each landed item

For each undocumented plan/issue, classify it:

Step 4 — Write the updates

Apply the repo-specific rules:

katgpt-rs (the public engine)

• README.md: feature showcase entries (one ### section per primitive with a GOAT gate table), the opt-in features table, the default-features list, the Documentation Index.
• .docs/01_orientation/overview.md: the full feature-flag table (one row per flag).
• .docs/09_feature_catalog/: opt-in features + negative results.
• .docs/<group>/README.md: the group's fusion map + file list.
• Numbering: never reuse a plan/issue/benchmark/research number. Read the .highwater file, use value + 1, write it back.

riir-ai (the private runtime)

• README.md: crate table + feature showcase.
• .docs/: 12 numbered folders — drop new docs in the right group, add one line to the group README.
• Cross-repo: if a katgpt-rs primitive was consumed, note the fusion in the riir-ai doc AND the katgpt-rs doc (bidirectional cross-refs).

riir-chain (7-folder .docs/ book, reindexed 2026-08-08)

• README.md: build surface, feature flags, consumers, drift notes.
• .docs/: 7 numbered folders mirroring the riir-ai/.docs/ format — 01_orientation (what it is + feature surface + module map + how the ledger works), 02_consensus, 03_economics, 04_daemon (incl. the operator runbook), 05_wallet (trust boundaries, SIWR, node certificates), 06_operations (rolling upgrade across protocol versions, e2e coverage, failure scenarios), 07_formal_verification (pointer — the invariant table stays in AGENTS.md). Drop new docs in the right group folder and add one line to that folder's README.md index table. The top-level .docs/README.md is the entry point.
• Division of labour with riir-ai (set 2026-08-08): riir-chain holds the canonical chain docs; riir-ai/.docs/07_neuro_symbolic_chain/ is a fusion map + feature highlights that links here and keeps only what is riir-ai's own (the Egg/Shell raw-vs-latent boundary, latent precision realms, game-layer sync strategy, CF Workers edge topology). Do not re-centralize chain internals in riir-ai — that duplication is what drifted before. Cross-link bidirectionally.
• Module map discipline: 01_orientation/overview.md claims to list every src/ and crates/riir-chaind/src/ subtree. If a plan adds a module, add the row — a map that silently omits modules reads as "these do not exist".
• AGENTS.md: the FV (Lean 4) invariant table lives here (mirrored in .proofs/README.md), NOT in .docs/. Plan 016 spec self-tests live next to each spec module under .proofs/RiirChainProof/.

riir-neuron-db (11-folder .docs/ book; 10th added 2026-07-30, 11th 11_cli/ added 2026-09-09)

• README.md: build surface — feature gates (default-on / transitive / opt-in / per-feature prose sections for promoted primitives) + Formal Verification summary + License. Prose sections are reserved for promoted default-on features; opt-in features get table rows only.
• .docs/: 11 numbered folders mirroring the riir-ai/.docs/ format. Drop new docs in the right group folder (by capability: shard substrate / freeze-thaw / consolidation / vessel / specialized / zone / examples / FV / local-kv Warm tier / CLI), add one line to that folder's README.md index table. The top-level .docs/README.md is the entry point. The 05_secure_vessel/vessel_primitive.md doc is the restored home of the old 15_vessel.md (corrected: riir-neuron-db is "this crate", NOT katgpt-rs per Plan 006). The 10_local_kv/ folder covers the LocalKvStore + CommitLevel/CommitBatch + WAL compaction + BM25 (the Warm tier substrate backing per-player state recovery in riir-mmorpg-examples Plan 013, added Issue 043). The 11_cli/ folder covers the ndb binary (Plan 327: Warm-tier CRUD, identity login via riir-auth account_key, multi-node WAL-mirror sync).
• AGENTS.md: the FV (Lean 4) invariant table lives here (mirrored in .proofs/README.md), NOT in .docs/. The .docs/09_formal_verification/ folder is the narrative overview; AGENTS.md is the authoritative invariant table.
• Cross-repo: if a primitive was consumed by riir-ai or riir-chain, the fusion is documented bidirectionally.

riir-train (6-folder .docs/ book, reindexed 2026-07-15)

• 6 numbered folders (01_orientation/ … 06_cross_cutting/), unnumbered .md files inside — mirrors the riir-ai/.docs/ format.
• Training-method research vault: adapter training, distillation/RL, data filtering, cross-cutting audits.
• README.md is minimal — role + sibling layout.
• main branch (no develop).

riir-game-sdk (10-folder .docs/ book; 10th added for multiplayer topology)

• README.md: build surface — boundary rule, leaf constraint, spatial canonical, feature gates, Phase 2/3 status table.
• .docs/: 10 numbered folders mirroring the riir-ai/.docs/ / riir-neuron-db/.docs/ format. Drop new docs in the right group folder (by capability: spatial-entity / tick-world / rules-ai / game-builder / zone-living-world / gm-dashboard / examples / lessons / multiplayer-topology), add one line to that folder's README.md index table. The top-level .docs/README.md is the entry point. The 10_multiplayer_topology/ folder covers the two-binary authority/player production model + avatar/game sync facade (the consumer pattern for the documented C1/C2/C4 chain topologies).
• AGENTS.md: authoritative repo-local context (phase status, boundary rule rationale, leaf-constraint argument, the canonical-failure lessons). The 09_lessons/ folder is the narrative mirror of those lessons.
• examples/: showcase examples are part of the doc surface (Issue 517 rule) AND documented in .docs/08_examples/.
• Leaf constraint reminder: this crate has zero sibling path deps. Docs that reference sibling repos use relative links only — never imply a code dependency.

riir-mmorpg-examples (no .docs/ folder — AGENTS.md-centric)

• POC consumer of riir-game-sdk (orchard multiplayer: 1000-NPC swarm + cross-target Bevy binary).
• No .docs/ folder — documentation lives in:
  • AGENTS.md — the authoritative narrative (role, topology, plans/issues/benchmarks index, canonical-failure lessons, honest POC-grade caveats).
  • README.md — build surface (status, build commands, env vars, Plan/Issue index).
  • .plans/ / .issues/ / .benchmarks/ — individual plan/issue/benchmark files.
• The AGENTS.md is large (~1000+ lines) and IS the doc surface — doc-sync for this repo means keeping AGENTS.md sections current with landed plans.

riir-refine (12-folder .docs/ book)

• .docs/: 12 numbered folders mirroring the riir-ai/.docs/ format — corpus / drafter / pruner / verify / ruliology / examples / benchmarks / lessons / self-evolve / domains / ANE substrate knowledge (12_ane/, riir-ai Issue 726 T0 distillation). Drop new docs in the right group folder, add one line to that folder's README.md index table.
• AGENTS.md: the batch-mining progress notes + sweep records live here (the cross-repo clippy-heal record home). A landed heal slice in a sibling repo (katgpt-rs, riir-train, riir-ai) gets its progress note in the SAME commit as the heal — a later doc-sync run defers to the healing session (never write progress notes for someone else's in-flight sweep).
• README.md: Status + Quick Start + Usage + feature gates.

riir-unity — RETIRED 2026-09-04 (git/obsolete/), lineage only

• AGENTS.md: domain boundary (no Rust crates here; UPM package is build output; no engine substrate in C#) + the Unity MCP rules + the issue log. Doc-sync = issue-log sections for resolved issues + module-map freshness (the Packages/com.riir.viewbridge/ population + scene wiring notes).
• The Rust side of any feature lives in riir-viewbridge — cross-repo arcs (e.g. Issue 004) document on BOTH sides at arc close.

riir-viewbridge (.docs/01_orientation/ + an AGENTS.md-centric remainder)

• AGENTS.md: workspace layout (core/derive/abi/xtask) + boundary rules (latent/raw wall, generated-bindings rule, catch_unwind) + the issue log.
• .benchmarks/: GOAT records (e.g. Bench 002 node GOAT). Doc-sync = issue-log resolution entries + benchmark cross-refs.

Every repo not subsectioned above (riir-dapps, riir-dao, riir-auth, riir-deployer, riir-esp32, riir-kat, katgpt-web, mmorpg-remake, mmorpg-editor)

• Follow the census-table row — these are AGENTS.md/BOUNDARY.md-centric: doc-sync = AGENTS.md/BOUNDARY.md status sections + numbering highwater + README freshness (riir-kat has no README; its AGENTS.md is the surface). The repo's own AGENTS.md supersedes this skill.
• katgpt-web checkout may sit on a feature branch (see census row) — sync the branch you find, and say which one in the run log.

Step 5 — Verify

• No broken links: every [...](.plans/NNN_*.md) must point to a file that exists.
• No stale numbers: if a README entry says "ratio 0.01" but the benchmark says "0.27", the README is wrong — update it.
• Numbering discipline: .highwater files must be bumped when new plans/issues land.
• Honesty: a GOAT FAIL stays a GOAT FAIL in the docs. A "stays opt-in" primitive is documented as opt-in with the reason. Never upgrade a verdict in the docs without the benchmark to back it.

Step 6 — Commit

Per the global AGENTS.md rule: always commit at task completion. Use docs: prefix. Stay on the repo's working branch (develop for most, main for riir-train). Do not push.

git add .docs/ README.md .plans/ .issues/ .benchmarks/ .research/
git commit -m "docs: sync .docs + README with recent plans (NNN, NNN, NNN)"

Cross-repo coordination

The 5-repo (now 10-repo) family shares numbering namespaces for plans/issues/benchmarks/research within each repo but NOT across repos. When a katgpt-rs primitive is consumed by riir-ai, the fusion is documented bidirectionally: the katgpt-rs doc notes "consumed by riir-ai/NNN", and the riir-ai doc notes "consumes katgpt-rs/NNN".

Formal verification (Lean 4) has its own cross-repo pattern (Research 351): each repo's .proofs/ instance is self-documenting via its invariant table in AGENTS.md. The doc-sync skill does NOT cross-port Lean files between repos (coordinator rule C4: private proofs stay private).

Shape-change contract (when .docs/ grows a new top-level NNN_* folder)

This is the root-cause guard for skill drift. The recurring failure mode: a plan adds a top-level .docs/NNN_*/ folder to a repo, lands the commit, and nobody updates this skill file — so the next doc-sync run operates on a stale folder-count assumption (canonical drifts: riir-neuron-db 9→10 via Issue 043, riir-game-sdk 9→10 via the multiplayer-topology docs, riir-chain flat→7 via the 2026-08-08 reindex, riir-ai 11→12 via Plan 455's orphaned 02_inference/ folder discovered 2026-08-08). This contract makes the update a grep-able checklist instead of an implicit expectation.

Trigger: any plan/issue/commit that adds a new top-level .docs/NNN_*/ folder to any repo that already has numbered folders — measured 2026-09-14 as 12 of the 20: katgpt-rs, riir-ai, riir-chain, riir-clippy, riir-dapps, riir-deployer, riir-game-sdk, riir-neuron-db, riir-shader, riir-train, riir-viewbridge, mmorpg-remake. Or that gives a .docs/ to one of the five with none (katgpt-web, riir-dao, riir-esp32, riir-kat, riir-mmorpg-examples) or the one whose .docs/ holds no document (riir-auth) — creating the folder is itself a shape change and requires this contract. Derive the split rather than reading it here (ls */.docs); the previous version of this trigger named riir-viewbridge as having none while its .docs/01_orientation/ had shipped in the repo's own scaffold commit — and the version before that kept riir-shader in the "none" list for two days after its 4-folder book landed (2b78bb5), because a census row nobody re-derived beats no row at all for hiding a shape change.

Checklist (run in the SAME pass as the folder-adding commit):

• Verify ground truth. ls <repo>/.docs/ and count the NNN_* folders. Do not trust the skill's current number — it may already be stale.
• Update the table row in ## The workspace repos and their doc shapes above: bump the folder count, extend the range (…NN_<new-folder>/), and add a short provenance note (plan/issue number + one-phrase capability description).
• Update the Step 4 section for that repo: change the header count, add the new folder's name to the capability list, and add a one-sentence description of what the folder covers.
• Grep-verify zero stale counts. After the edit, run grep -nE "<old_count> (numbered|folder)" ~/.agents/skills/doc-sync/SKILL.md for the repo you touched — it MUST return zero hits. (Example: after bumping riir-neuron-db from 9 to 10, grep -nE "9 (numbered|folder)" filtered to the neuron-db rows must be empty.)
• Commit. This file is NOT in a git repo (~/.agents/ is on-disk only), so the update lands by saving — but the repo-side commit that adds the folder should reference this contract in its message (e.g. docs: add .docs/10_local_kv/ (shape-change contract: doc-sync SKILL.md updated)).

Who runs this: the agent executing the plan that adds the folder — NOT a later doc-sync run. doc-sync is the consumer of the skill; the contract is the producer-side obligation. A doc-sync run that discovers a stale count (row says 9, disk says 10) is a SIGNAL that the producer skipped this contract — fix the skill then, but also note the gap.

Anti-patterns

• Do not write a doc entry for a plan that hasn't landed yet. Speculative docs go in .proposals/.
• Do not remove a negative-result entry when closing its issue — the negative result is load-bearing documentation.
• Do not upgrade a GOAT FAIL to a PASS in the docs without the benchmark file to back it.
• Do not impose a .docs/ shape that differs from the repo's existing convention — respect the shape you find. Re-measured 2026-09-14 over the live 20 (the 09-12 measurement read 19 — it had no row for mmorpg-remaster, which joined at Issue 760): 12 numbered folders (katgpt-rs 10, riir-ai 12, riir-chain 7, riir-clippy 12, riir-dapps 1, riir-deployer 2, riir-game-sdk 10, riir-neuron-db 11, riir-shader 4, riir-train 6, riir-viewbridge 1, mmorpg-remake 1), 5 with no .docs/ at all (katgpt-web, riir-dao, riir-esp32, riir-kat, riir-mmorpg-examples), 1 whose .docs/ holds no document (riir-auth — only .highwater, which reads as a shape and is not one), 1 NAMED subfolders (mmorpg-editor), 1 flat numbered FILES (mmorpg-remaster — the shape did NOT leave the workspace with riir-burner; the 09-12 version of this sentence was wrong because that repo had no census row to be counted through). Don't re-type this census: the one-liner in the trigger above derives it, and every hand-written version of it in this file's history has been wrong within days — the previous one said "8 numbered / 8 AGENTS.md-centric" over a table whose membership differed from the workspace in BOTH directions. A shape change is a deliberate, committed decision governed by the Shape-change contract above.
• Do not renumber existing docs — the numbering discipline is monotonic and never reused.
• Do not document trivial mechanical commits (lockfile bumps, clippy fixes) unless they close a tracked issue.

Standing lessons (distilled from the run log — the load-bearing process rules)

• Per-file logs + pickaxe are the reliable baseline tools. git log -- .docs README.md AGENTS.md once reported 5a1330b as game-sdk's newest doc-touching commit while git log -- AGENTS.md + git log -S '<landed-string>' -- <file> proved 1977d83 (two days newer) had touched AGENTS.md. Always re-verify a suspicious baseline per-file before declaring a range clean.
• Narrow producer-side syncs leave holes the baseline heuristic can't see. A narrow sync fixes its own feature and skips everything else, so the strict baseline..HEAD range can be empty while the book still misses older landings. Gate runs GREP the book for recently-landed headline features; don't just trust the range. The inverse gap exists too: code landing to MATCH an already-documented row (mmorpg ?transport=local) is invisible to any baseline heuristic — nothing to fix, but don't declare a gap either.
• Grep extraction regex must include digits. ^[a-z_]+ = over [features] silently dropped avatar_sync_ed25519 and game_sync_p2p — nearly filed phantom "documented-but-dead feature" findings. Use ^[a-z0-9_]+ =.
• The staged-index check must GATE the commit, not precede it. One run saw two sibling-staged files in git diff --cached --name-only output and then sailed past them because the check was ;-chained ahead of git add + git commit — the sibling's WIP landed inside the run-log commit (benign outcome, luck not process). The correct form: run the check as its OWN command and read it, or use git commit -- <paths> (a partial commit builds a temporary index from HEAD + the named paths, leaving anyone else's staged hunks intact — the safe form on shared checkouts). scripts/staged_set_audit.py (katgpt-rs) reports the same signal class pre-commit.
• A doc claim of determinism is a claim about a proof. When a fix refutes the proof (the ndb Bm25 tie-truncation class), grep the book for the CLAIM, not just for coverage of the fix — the fix landed with in-source comments only and the book kept asserting the falsified invariant.
• False positives: grep the repo's OWN .benchmarks/ before declaring coverage. Different repos (and even different series in one repo) reuse bench numbers — the overview's only "Bench 025" hit was a different numbering series.
• Broken links: prose citations survive file removal, markdown links do not. The noise-reduction rule removes record files but no link-fix pass followed, so every closed issue left ](.issues/NNN…) links dangling. Standing tools (committed in katgpt-rs .agents/skills/doc-sync/tools/ — moved out of a repo-root tools/ that no longer exists; the 2026-09-04 landing row below still says tools/ and is history, not a path): python3 .agents/skills/doc-sync/tools/linkcheck_sweep.py (census) + python3 .agents/skills/doc-sync/tools/link_fix.py <repo> (auto R1-repoint / R3-delink), re-sweep to verify, commit pathspec'd .md only. Guards baked into the tools: absent-repo (a link into a workspace repo not checked out on the running box is UNVERIFIABLE, not broken — exists() is box-relative), backtick (link text already code-marked is emitted unwrapped), EOL (the fixer reads/writes with newline="" since 2026-09-22 — CRLF/mixed files round-trip byte-exact; before that the read_text/write_text pair LF-normalized whole files, measured on a CRLF .research/200, and the old 'restore EOL to HEAD convention manually' workaround is retired), and a markdown link split across lines is invisible to one-line fix regexes (NOMATCH → manual two-line edit).
• Never cite "Plan/Research NNN" without naming the repo when the number exists in more than one namespace — and never link a path you haven't verified (ls it first; per-repo numbering namespaces collide constantly).
• Classification against dirty trees uses git show <rev>: content, never the working tree. Sync remotes first; git show -1 <sha> mis-parses (the -1 overrides the sha — pass the sha alone). The reliable per-file baseline is the 4-surface set (AGENTS.md / README.md / .docs/ / the feature file) + a since-count.
• "0 passed" in a baseline run is the reliable gate detector — grep on attribute FORMS lies (whole-file #![cfg] gates sit below doc-comment headers, mod-level cfg(any(feature…)) compiles empty under default).