docs(drift): report — mkit

[christopherwxyz]

Docs drift report — mkit — August 17, 2026 14:25 UTC

Style-guide violations

• README.md:220 — Every object is identified by the BLAKE3 hash of its canonical serialization. — Referencing hashes and identifiers — a full BLAKE3 hash naming an object must be called digest or object ID, not hash; docs/ARCHITECTURE.md correctly says digest for the same concept.
• README.md:272 — Attestations carry the commit hash as the in-toto subject — Referencing hashes and identifiers — same rule; should read commit digest or the commit object ID.
• CONTRIBUTING.md:80 — macOS Keychain/Windows Credential Manager/Linux Secret Service backends — Referencing operating systems and platforms — platform-tied list ordered macOS/Windows/Linux instead of the required alphabetical Linux, macOS, and Windows.
• CONTRIBUTING.md:123 — Not a replacement for Repo — reach for Repo first — Use the mdash entity — literal em dash character in prose instead of the mdash HTML entity; the same bullet and file use the entity correctly elsewhere.
• CONTRIBUTING.md:140 — of mkit-attest alone — see that workflow header comment — Use the mdash entity — same literal-em-dash issue.
• docs/INSTALL.md:79 — verifying the tag is an annotated GPG-signed tag — Abbreviations — GPG is unexpanded and not on the allow list (HTML, HTTP, HTTPS, URL, SSH, JSON, CBOR, TLS, mTLS, CI, CLI, API, RPC, OS, npm, JPEG, PNG, CSV).
• docs/INSTALL.md:149 — it proves the archive was signed by this repo release.yml workflow — Use active voice — passive was-by construction; rewrite as this repo release.yml workflow signed the archive.
• docs/INSTALL.md:265 — mkit-sign-tpm — TPM 2.0 persistent handle (Linux/Windows) — Abbreviations — TPM is never expanded on this page; the style guide own worked example is literally Trusted Platform Module (TPM).
• docs/PARITY.md:237 / :249 — prefix-nested remote names (cli: rename/remove of a prefix remote silently drags or deletes a nested sibling remote's refs and bridge state #660/fix(cli): preserve a nested sibling remote's refs and bridge state across prefix rename/remove (#660) #789) — / dragging it along — — Use the mdash entity — two literal em dashes; every other em dash in the file correctly uses the entity.
• docs/PARITY.md:243 — remote remove was already per-ref-filtered the same way in git — Use active voice — passive construction; reads better as git already per-ref-filters remote remove the same way.
• docs/THREAT-MODEL.md:21 — content addressing plus signed commits and DSSE envelopes detect tampering — Abbreviations — DSSE is this page only use of the term and is never expanded to Dead Simple Signing Envelope (DSSE); not allow-listed.
• docs/RELEASE.md:54 / :57 — keyless OIDC, Rekor logged / a standards-based SLSA build provenance — Abbreviations — OIDC and SLSA are used from first mention onward but never expanded on this page.
• docs/RELEASE.md:119 — Linux Secret Service+systemd-creds+YubiKey, macOS Keychain+YubiKey — Symbols as words — plus sign used for and/plus in prose, not a keyboard-shortcut context.
• docs/RELEASE.md:207,679,711,772 — four instances, for example in an isolated environment — — Use the mdash entity — literal em dashes instead of the entity.
• docs/RELEASE.md:261-263 — crates.io publish table lists mkit-transport-file/http/memory/s3/ssh/enc plus mkit-core, mkit-rpc, mkit-attest, mkit-keystore, mkit-git-bridge, mkit-cli — the table omits mkit-transport-connect, a real workspace crate with no publish=false that also publishes; the documented crate list has drifted from the workspace.
• docs/RELEASE.md:353 — Hashes of every archive plus SBOM plus notices — Abbreviations — SBOM (Software Bill of Materials) is used repeatedly (also 355, 391, 555-567) but never expanded on first use.
• docs/RELEASE.md:459 — Users on Ventura+ may see a Gatekeeper warning — Symbols as words / version-range callout — plus sign stands in for or later in prose; the guide own convention is to spell out and later / or later.
• docs/CLI.md:49 (and throughout, for example 924, 1630) — create a new repository in .mkit/. — File names/directories as bold — the style guide own example is The repository state lives in .mkit/ (bold); CLI.md instead renders .mkit/ as inline code dozens of times.
• docs/CLI.md:317 — commit-history MMR written on every branch advance — Abbreviations — MMR (Merkle Mountain Range) used repeatedly but never expanded on this page.
• docs/CLI.md:573 — produce a signed DSSE attestation — Abbreviations — DSSE never expanded on this page.
• docs/CLI.md:589 — JCS-canonical JSON object — Abbreviations — JCS (JSON Canonicalization Scheme) never expanded on this page.
• docs/CLI.md:617 — verifies the DSSE PAE — Abbreviations — PAE (Pre-Authentication Encoding) never expanded on this page.
• docs/CLI.md:687 — CAS-guarded: refuses to clobber — Abbreviations — compare-and-swap is spelled out once at line 544 but never paired with (CAS); later uses (CAS-protected, CAS-safe) rely on an abbreviation that was never formally introduced.
• docs/specs/SPEC-RPC.md:23 — the CAS enum (RefExpectation) — Abbreviations — CAS never expanded on this page.
• docs/specs/SPEC-RPC.md:119 — ECDSA over SHA-256. DSSE-compatible. — Abbreviations — DSSE never expanded on this page.
• docs/specs/SPEC-RPC.md:121 — Ed25519 wrapped in a WebAuthn assertion (CTAP signers) — Abbreviations — CTAP recurs (131, 152) but is never expanded on this page.
• docs/specs/SPEC-CONCURRENCY.md:17 — the file-transport own CAS lock defined in SPEC-TRANSPORT — Abbreviations — CAS never expanded on this page.
• docs/specs/SPEC-CONCURRENCY.md:40 — ref-write + history-MMR-append critical section — Abbreviations — MMR never expanded; same gap independently in SPEC-GC.md:83 and SPEC-WORKTREE.md:130.
• docs/specs/SPEC-SIGNING.md:326 — raw 32 bytes (Ed25519 SEED — NOT expanded secret key) — Use the mdash entity — literal em dash instead of the entity.
• docs/specs/SPEC-SIGNING.md:390 — DSSE attestation signing via the repo-key signer — Abbreviations — DSSE never expanded on this page, even though the adjacent PAE abbreviation on the same line is correctly expanded.
• docs/specs/SPEC-PACKFILE.md:344 — 70 bytes total, preceded by a literal em dash — Use the mdash entity — literal em dash instead of the entity.
• docs/specs/SPEC-PACKFILE.md:256 — An earlier entry in the same pack whose computed hash is H — Referencing hashes and identifiers — H is a full object digest/object ID; should read digest or object ID, not hash.
• docs/specs/SPEC-OBJECTS.md:60 — any field addition silently shifts every hash — Referencing hashes and identifiers — refers to the full object digest; should read digest/object ID.
• docs/specs/SPEC-OBJECTS.md:269 — the ref points at the tag object hash — Referencing hashes and identifiers — same rule.
• docs/specs/SPEC-OBJECTS.md:306 — its hash is BLAKE3(serialized tag bytes) — Referencing hashes and identifiers — same rule.
• docs/specs/SPEC-TRANSPORT.md:46,47,49 — update_ref(name, condition, hash) / Read a ref current hash / write_ref(name, hash) — Referencing hashes and identifiers — the same verbs table calls the identical BLAKE3 value digest for the pack verbs a few rows up but reverts to hash for the ref verbs, an internal inconsistency.
• docs/specs/SPEC-ATTESTATIONS.md:46 — JCS, DSSE PAE, BLAKE3 hashing — Abbreviations — DSSE used here and again at line 64 before it is spelled out at line 72.
• docs/specs/SPEC-ATTESTATIONS.md:36 — the SLSA verifier — Abbreviations — SLSA appears seven times on this page and is never expanded.
• docs/specs/SPEC-RELEASE-THRESHOLD.md:18 — DSSE envelope shape — Abbreviations — DSSE never expanded; same sentence also uses unexpanded JCS.
• docs/specs/SPEC-RELEASE-THRESHOLD.md:37 — DKG-generated — Abbreviations — DKG used unexpanded here; only informally spelled out (distributed-key-generation protocol) three subsections later, not the required Full Name (ABBR) form at first use.
• docs/specs/SPEC-TRANSPORT-ENC.md:48 — TOFU-style first-use cache — Abbreviations — TOFU (Trust On First Use) never expanded on this page.
• docs/specs/SPEC-TRANSPORT-ENC.md:71 — own handshake or AEAD — Abbreviations — AEAD (Authenticated Encryption with Associated Data) never expanded on this page.
• docs/specs/SPEC-PACK-SHARDS.md:59 — Commonware BMT root — Abbreviations — BMT (Binary Merkle Tree) never expanded on this page (reused at line 307).
• docs/specs/SPEC-EXTERNAL-SIGNER.md:29 — a specific blob, the PAE — Abbreviations — PAE used throughout but never expanded on first use.
• docs/specs/SPEC-EXTERNAL-SIGNER.md:166 — verify the requested algorithm + key form — Symbols as words — plus sign used for and in ordinary prose.
• docs/specs/SPEC-EXTERNAL-SIGNER.md:296 — over CTAP-HID — Abbreviations — CTAP used throughout but never expanded to Client to Authenticator Protocol (CTAP).
• docs/specs/SPEC-EXTERNAL-SIGNER.md:338 — TPM 2.0 P-256 signer — Abbreviations — TPM never expanded on this page.
• docs/specs/SPEC-GIT-IMPORT.md:200 — provenance lives only in the retained bytes + attestation from section 5 — Symbols as words — plus sign used for plus/and in prose.
• docs/specs/SPEC-SPARSE-CHECKOUT.md:331 — Encoder + decoder live in — Symbols as words — sentence-initial plus sign instead of spelling out and.
• docs/specs/SPEC-KEYSTORE.md:41 — Windows TPM/CNG provider keys — Abbreviations — TPM and CNG never expanded on this page (also 85, 92, 150, 169, 188, 828, 860, 864, 1269).
• docs/specs/SPEC-KEYSTORE.md:42 — PKCS#11/HSM support — Abbreviations — HSM (Hardware Security Module) never expanded.
• docs/specs/SPEC-KEYSTORE.md:64 — Credential Manager via DPAPI — Abbreviations — DPAPI (Data Protection API) used throughout (section 6.4, section 16) but never expanded.
• docs/specs/SPEC-KEYSTORE.md:601 — atomic tmp + fsync + rename + parent fsync writes — Symbols as words — this is a requirements bullet, not code or a keyboard shortcut, so plus should be spelled out.
• docs/specs/SPEC-KEYSTORE.md:615 — Encrypt the 32-byte secret with an AEAD — Abbreviations — AEAD never expanded; the doc informally glosses it at line 696 without the required (AAD) parenthetical form.
• docs/specs/SPEC-KEYSTORE.md:620-621 — macOS Keychain, Windows DPAPI/Credential Manager, Linux Secret Service, or systemd-creds — Referencing operating systems and platforms — backends listed macOS/Windows/Linux instead of alphabetical Linux/macOS/Windows.

Dead references

• docs/specs/SPEC-TRANSPORT-ENC.md:232,236 — references mkit_transport_enc::serve_tcp_with_policy, which no longer exists; rust/crates/mkit-transport-enc/src/tcp.rs only has serve_tcp_with_policy_and_bounds, a stale name left over from an apparent API rename.
• docs/specs/SPEC-TRANSPORT-ENC.md:240 — references a bare serve_tcp function, which no longer exists; the AllowAny back-compat entry point in this crate is serve_tcp_with_addr.
• docs/specs/SPEC-ATTESTATIONS.md:13 — references docs/NOTARY.md as a historical design note, which does not exist anywhere in the repo or its git history.
• docs/specs/SPEC-SPARSE-CHECKOUT.md:52 — cites commonware-storage version 2026.5.0, which no longer exists; rust/Cargo.toml now pins =2026.7.0.
• docs/specs/SPEC-HISTORY-PROOF.md:47,61,213-215,422-428 — repeatedly cites commonware-storage version 2026.5.0, including a docs.rs URL embedding that version, which no longer exists; rust/Cargo.toml now pins =2026.7.0.

[christopherwxyz]

test: quotes "like this" and apostrophe's and entity — and amp & end

---

Generated by Claude Code