Docs truth: reconcile stale current guidance and agent instructions

[geromet]

Purpose

Canonical current documentation / agent-instruction drift tracker for PZTools. Keep one tracker rather than opening one issue per file.

Audit baseline: exact master@f015a0b5593331186cc410831e8e05f80d80824e on 2026-09-05. The bounded audit enumerated every tracked current Markdown/agent-guidance file:

• README.md
• DESCRIPTION.md
• CLAUDE.md
• Core/CLAUDE.md
• Data/CLAUDE.md
• UI/CLAUDE.md

Historical/provenance material is not present in this six-file surface, so all six were treated as current guidance.

Verified findings

DOC-001 — HIGH — root CLAUDE.md falsely says there are no automated tests

Current text says No automated tests. The repository actually tracks Data.Tests/ and hosted .github/workflows/ci.yml + .github/workflows/data-tests.yml; current fleet proof routinely runs the Data suite (59/59 on the #78 stable rollup).

Why it matters: an agent following current guidance can skip the strongest deterministic verification surface or invent manual-only proof.

Remediation: describe the real build/test commands and hosted workflow split. Keep commands grounded in the current solution/workflow rather than hard-coding transient run counts.

DOC-002 — HIGH — root CLAUDE.md branch/PR rule conflicts with canonical fleet stable topology

Current text says each independent change should start from the default branch and open a PR back to default. The canonical #68 LOCK explicitly supports bounded NON-DEFAULT fleet/stable/* integration, including children whose base is the claimed stable branch and one Gerome-facing stable→default rollup. Current #78 is the live example.

Why it matters: this is contradictory executable agent authority and can cause duplicate default-targeting PRs, bypass coherent stable integration, or misclassify a stable-targeting child as invalid.

Remediation: keep the safe generic default-branch rule for ordinary independent work, but explicitly defer fleet/concurrent work to #68 and permit its claimed non-default stable topology. Preserve the absolute no-direct-default-write/no-force-push protections.

DOC-003 — MEDIUM — README.md and DESCRIPTION.md duplicate a stale Build 42.14 Unstable compatibility claim

Both files currently say Updated for Build 42(.14.0) Unstable. Canonical compatibility issue #65 already establishes that Project Zomboid 42.20 is Stable and requires evidence before changing the advertised compatibility range.

Owner: #65 remains canonical for the actual Build-42.20 compatibility proof. This tracker does not duplicate that technical work.

Remediation: once #65's evidence establishes the exact supported range, update both public copies together so they cannot diverge. Until then, do not replace 42.14 with an unproved 42.20 claim merely to make the prose look current.

Reviewed with no verified drift

• Core/CLAUDE.md — CURRENT / NO VERIFIED DRIFT for the described filtering/folder/item-index seams on this baseline.
• Data/CLAUDE.md — CURRENT / NO VERIFIED DRIFT for the documented parse/model/serialization/reference seams on this baseline; future Build-42 semantic changes remain owned by Validate compatibility against Project Zomboid Build 42.20 Stable #65/Improve Lua serialization — edge cases #36/Add new Bags/Items that are now defaulted as Room #37/Add semantic validation diagnostics for unresolved/unsafe distribution data #67 where evidence demonstrates them.
• UI/CLAUDE.md — CURRENT / NO VERIFIED DRIFT for the present code-behind/helper/binding structure. Incrementally migrate high-churn UI state to MVVM #55 is future incremental MVVM work and does not make current no MVVM wording false today.

Scope / non-scope

• Documentation and agent-instruction truth only; no runtime/product behavior.
• Do not absorb Validate compatibility against Project Zomboid Build 42.20 Stable #65's real-data compatibility proof, Add support for importing all/specific mods #51 project/reference-layer implementation, or Incrementally migrate high-churn UI state to MVVM #55 MVVM product architecture work.
• Preserve current executable facts; do not turn issue/fleet status into undated permanent prose.
• If implementation advances before remediation, recheck the exact current default before editing claims.

Deterministic verification

1. Re-enumerate tracked *.md/agent-guidance files from current default and confirm the inventory is still complete.
2. Cross-check root build/test guidance against PZTools.sln, Data.Tests, and .github/workflows/*.
3. Cross-check branch/PR wording against current P0: Agent work coordination lock #68 before changing agent authority.
4. For compatibility wording, require Validate compatibility against Project Zomboid Build 42.20 Stable #65's recorded real-data evidence and update README.md + DESCRIPTION.md as one synchronized pair.
5. Re-read all six current files after remediation and classify them CURRENT / NO VERIFIED DRIFT, FINDING, HISTORICAL / SNAPSHOT, or RESEARCH / GUIDANCE SNAPSHOT before closing this tracker.

Done when

• DOC-001 and DOC-002 no longer misdirect agents;
• DOC-003 is either truthfully evidence-backed through Validate compatibility against Project Zomboid Build 42.20 Stable #65 or explicitly scoped without overclaiming support;
• all tracked current Markdown/agent-guidance is re-enumerated and rechecked against live authority;
• no unique current-guidance drift remains hidden outside this canonical tracker.