docs(drift): report — mkit

[christopherwxyz]

<!-- docs-drift-state
{"last_run_utc": "2026-07-27T14:21:51Z"}
-->

Docs drift report — mkit — July 27, 2026 14:21 UTC

Full sweep of README.md, CONTRIBUTING.md, all docs/*.md, and all 26 docs/specs/SPEC-*.md files (plus docs/specs/README.md), checked against a fresh read of docs/STYLE-GUIDE.md and against the current main checkout (1520aed4) for dead links/paths/symbols. docs/adr/ still does not exist in this checkout, so there is nothing to sweep there.

Style-guide violations

• CONTRIBUTING.md:123, CONTRIBUTING.md:140, docs/RELEASE.md:207,676,679,711,772, docs/PARITY.md:237,249 — literal — character in prose where the style guide requires the — entity ("the most common variant inserted by AI-assisted writing"). Recurring since the prior report; still not fully cleaned up.
• CONTRIBUTING.md:120 ("assert_cmd + predicates + assert_fs"), CONTRIBUTING.md:122 ("a manual Output + assert! pair"), docs/specs/SPEC-EXTERNAL-SIGNER.md:166 ("algorithm + key form"), docs/specs/SPEC-PACK-SHARDS.md:17 ("transport wiring + producer pipeline"), docs/specs/SPEC-GIT-IMPORT.md:200 ("retained bytes + attestation"), docs/specs/SPEC-PACKFILE.md:8 (H1 heading "mkit packfile format (v1 + v2)") — "+" used instead of "and"/"plus" in prose and a heading; none of these are keyboard-shortcut references, the only carved-out exception.
• CONTRIBUTING.md:80 ("native macOS Keychain/Windows Credential Manager/Linux Secret Service backends") and docs/specs/SPEC-KEYSTORE.md:619 ("macOS Keychain, Windows DPAPI/Credential Manager, Linux Secret Service") — OS list not alphabetical; rule requires "Linux, macOS, and Windows" order.
• Abbreviations not expanded in parentheses on first use per page (none of these are on the STYLE-GUIDE.md allow-list: HTML, HTTP, HTTPS, URL, SSH, JSON, CBOR, TLS, mTLS, CI, CLI, API, RPC, OS, npm, JPEG, PNG, CSV):
  • DSSE: README.md:13 (never expanded anywhere else in the file either).
  • CAS and MMR: docs/specs/SPEC-CONCURRENCY.md:17,40 (both used repeatedly through the page, never expanded).
  • MMR: docs/specs/README.md:17, docs/specs/SPEC-GC.md:83.
  • BMT: docs/specs/SPEC-PACK-SHARDS.md:59.
  • DSSE and PAE: docs/specs/SPEC-EXTERNAL-SIGNER.md:28-29 — the style guide's own worked example for this exact rule is "Distinguished Encoding Rules (DER)"-style expansion, which this page also skips for DER's sibling PAE.
  • DER: docs/specs/SPEC-SIGNING.md:332 — its only mention on the page, unexpanded.
  • TPM: docs/specs/SPEC-RPC.md:131 — appears 4 times on the page, never expanded.
• docs/INSTALL.md:149 — "it proves the archive was signed by this repo's release.yml workflow" — passive "was...by" construction the style guide calls out by name.
• docs/specs/SPEC-MERKLE-OBJECTS.md:39 (recurring through the file), docs/specs/SPEC-OBJECTS.md:30,265, docs/specs/SPEC-PACK-SHARDS.md:252 — space padding around "/" (rule: "working-tree/index state", not "working-tree / index state").

Dead references

• docs/INSTALL.md:190-221 — all three WASM/npm code samples (import init, { hash, parse_envelope } from "@officialunofficial/mkit-wasm", await init(), hash(...)) call functions that don't exist. The actual mkit-wasm crate exports blake3_hex, commit_verify, attest_build, attest_verify, etc. (verified in rust/crates/mkit-wasm/src/{crypto,objects,attest,chunking}.rs) — there is no hash or parse_envelope export anywhere. The package's own README (rust/crates/mkit-wasm/README.md:21-22) also states the bundler build "auto-initializes on import — there is no default init export and nothing to await," directly contradicting the import init / await init() pattern shown in all three samples.
• docs/INSTALL.md:234 — claims contrib signer crates "inherit workspace settings via workspace = "../../../rust" in their own Cargo.toml." contrib/signers/mkit-sign-file/Cargo.toml has no such line; it uses version.workspace = true etc., inheriting from contrib/signers/Cargo.toml (its own sibling workspace), not from rust/. The quoted syntax doesn't exist anywhere in the repo.
• docs/FUZZ.md:19-31 — the "What is fuzzed" table omits two real, active fuzz targets present in rust/fuzz/fuzz_targets/: merkle_packlist.rs and merkle_proof.rs.
• docs/FUZZ.md:103-104 — states the fuzz crate is "pinned to the commonware 2026.5.x train." rust/fuzz/Cargo.toml:57 actually pins commonware-invariants = "=2026.7.0".
• CONTRIBUTING.md:200-203 — the Buf workspace diagram shows the root proto module mapping only to mkit.transport.v1. The actual tree also contains proto/mkit/common/v1/refs.proto (mkit.common.v1) and proto/grpc/health/v1/health.proto (grpc.health.v1), both omitted from the diagram.
• docs/INSTALL.md:26 — recommends mkit-core = "0.3" as the crates.io dependency pin. The actual workspace version (rust/Cargo.toml) is 0.4.1.
• docs/ARCHITECTURE.md:15-34 — the workspace-layout crate table omits real rust/Cargo.toml workspace members mkit-transport-connect and mkit-repo-client (both under rust/crates/), plus the dev-only mkit-test-util member.
• docs/SSH-SECURITY.md:20,33-34,177-178 — describes OP_HELLO (citing "SPEC-TRANSPORT §7.4") as mkit's live first-frame handshake safety net against a wrong binary or a future-proto client/server mismatch. docs/specs/SPEC-TRANSPORT.md §7 ("Retry / idempotency") only goes to §7.1 — no §7.4 exists, and OP_HELLO doesn't appear in that document at all. docs/specs/SPEC-RPC.md:195 and the module doc in rust/crates/mkit-core/src/protocol.rs:11 both describe the hand-rolled OP_HELLO byte format as retired in favor of the protobuf ssh.proto schema. SSH-SECURITY.md describes a mechanism and section that no longer exist as documented.
• docs/SSH-SECURITY.md:129-130 — states the mkit keygen seed "doubles as an id_ed25519 for OpenSSH 8.0+; see docs/specs/SPEC-SIGNING.md §8." docs/specs/SPEC-SIGNING.md §8 itself now contains an explicit correction retracting that exact claim: "an earlier version of this section claimed 'OpenSSH 8.0+ accepts the same raw Ed25519 seed as its id_ed25519 private key.' This is not accurate ... Reusing an mkit seed as an SSH identity requires an explicit conversion step." SSH-SECURITY.md still asserts the retracted claim and cites the very section that disavows it.
• docs/RELEASE.md:520 — lists chacha20poly1305 = 0.10.1 in the dependency table. The actual pin (rust/crates/mkit-keystore/Cargo.toml:45) is 0.11.0.
• docs/RELEASE.md:528,535-536 — lists secrecy as a backend-yubikey-gated dependency of mkit-keystore and claims thiserror is one of its "exact-pinned" deps. Neither secrecy nor thiserror appears in rust/crates/mkit-keystore/Cargo.toml at all, and none of the named "exact-pinned" deps (ed25519-dalek, getrandom, k256, p256, sha2) actually use = version pins there — only the dev-only tempfile = "=3.27.0" does.
• docs/RELEASE.md:592-598 — the reproducibility steps run git clone ... && cd mkit then cargo build --manifest-path rust/Cargo.toml, claiming "rustup picks up rust-toolchain.toml on first cargo invocation." The toolchain file lives at rust/rust-toolchain.toml, not the repo root; rustup's upward directory walk from the repo-root CWD would not find it before reaching rust/Cargo.toml's manifest directory.
• docs/specs/SPEC-HISTORY-PROOF.md:47,61,212,215,400,423,448, docs/specs/SPEC-PACK-SHARDS.md:148, docs/specs/SPEC-SPARSE-CHECKOUT.md:52, docs/specs/SPEC-TRANSPORT-ENC.md:70 — all cite commonware-storage/commonware-coding/commonware_stream as pinned to 2026.5.0 (including docs.rs/.../2026.5.0/... links). rust/Cargo.toml:56-63 now pins every commonware-* crate to =2026.7.0. This is the same drift flagged in the prior report; it still hasn't propagated to these spec docs.
• docs/specs/SPEC-TRANSPORT-ENC.md:26,232,236,240 — references mkit_transport_enc::serve_tcp_with_policy and a bare serve_tcp. Neither exists; the real functions in rust/crates/mkit-transport-enc/src/tcp.rs are serve_tcp_with_policy_and_bounds, serve_tcp_with_addr_and_policy, and serve_tcp_with_addr.
• docs/specs/SPEC-REFS.md:227 — says the file transport wraps an invalid ref-prefix as RefError::InvalidRefName. RefError::InvalidRefName is a real variant in rust/crates/mkit-core/src/refs.rs, but the file transport's actual prefix-validation error (rust/crates/mkit-transport-file/src/lib.rs:481) is TransportError::InvalidRef — a different type and variant than the one attributed to "the file backend."