docs: refresh README + ARCHITECTURE + CLAUDE.md + ROADMAP for Phase 1 reality - #126
Merged
Conversation
… reality Adversarial Phase 1 doc review surfaced 3 critical + 5 important + minor freshness issues. The docs that are supposed to track current state (README, ARCHITECTURE, CLAUDE.md, ROADMAP) had drifted significantly during 30+ PRs of implementation work. Frozen-banner docs (phase-1-foundation, SPEC) are left alone per their own preserved-as-is policy. **README:** - Status section was "early development; scaffolding in place" — actual state is 17K LOC, 8 pak versions parsed, opt-in SHA-1 verification with FDI/PHI region coverage, working `paksmith list` CLI. Replaced with honest current-state summary + ROADMAP pointer. - Build command was `cargo build --workspace` — directly contradicts the workspace's deliberate exclusion of `paksmith-fixture-gen` from `default-members` (which exists specifically to keep routine builds free of the trumank/repak git dep). Changed to `cargo build` + a separate fixture-regeneration line. - Added `paksmith list` example + auto-format-detection note (the whole point of Phase 1 was to ship this command; the README never mentioned it). - Added the GHAS-mirroring clippy invocation (`cargo clippy --workspace --all-targets --all-features -- -D warnings`) alongside the routine commands. **ARCHITECTURE:** - Crate dep graph showed 3 crates; workspace has 4 (`paksmith-fixture-gen` was missing). Added it to the graph with explanation of why it's excluded from default-members. - `paksmith-core` Modules section was a 5-bullet sketch; replaced with Modules-current (actual implementation: container/pak with all the index/, error.rs typed faults, digest.rs Sha1Digest, testing/ with __test_utils-gated infrastructure) + Modules-planned (iostore, asset, export, profile with their phase numbers). - Added paksmith-fixture-gen section. - GUI section now notes "currently a stub; full implementation in Phase 6". - Design Principles expanded with the discipline that Phase 1 actually enforced (checked_* arithmetic, try_reserve_exact bulk allocation, structural caps, wire-stable Display, cross-parser fixtures). **CLAUDE.md:** - Clippy command was `cargo clippy --workspace -- -D warnings` — misses the `__test_utils` surface and integration tests that GHAS includes. This is captured in MEMORY (`ghas_clippy_extra_lints.md`) as a known trap. Aligned with the CI invocation: `--all-targets --all-features`. - "Cargo workspace with three crates" → four crates (added paksmith-fixture-gen with the not-in-default-members rationale). - Module Layout `container/` description said "(pak, iostore)" — only pak exists. Other planned modules correctly carried "(planned)" but iostore did not. Now disambiguated as a `container/iostore/` planned submodule with phase number. - Added `error.rs`, `digest.rs`, `testing/` to the Module Layout (they were missing — only forward-looking modules were listed). - Added `cargo run -p paksmith-fixture-gen` to the Build section. **ROADMAP:** - Tech Stack listed `tokio` — no async runtime in any Cargo.toml. Replaced with the actual deps (`byteorder`, `sha1`, `flate2`) and a note that async is deferred to Phase 5 network fetch. - Architecture line mentioned 3 crates; added paksmith-fixture-gen. Frozen-banner docs (phase-1-foundation.md, SPEC.md) intentionally left alone — their preserved-as-is policy still applies and the divergences flagged by the docs reviewer (1109 stale-API snippet, registry/ planned directory, etc.) are within the frozen-banner's accepted-divergence scope. If those docs are ever revived for editing, the divergences need addressing then. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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 free
to 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.
Summary
Adversarial Phase 1 doc review surfaced 3 critical + 5 important + minor freshness issues. Fixes the docs that are supposed to track current state (README, ARCHITECTURE, CLAUDE.md, ROADMAP) — the 30+ PRs of implementation work had drifted them significantly. Frozen-banner docs (phase-1-foundation, SPEC) intentionally left alone per their preserved-as-is policy.
Critical fixes:
paksmith-fixture-gen)cargo build --workspacedirectly contradicted thedefault-membersexclusion designed to keep routine builds free of thetrumank/repakgit depiostoreas if it existed; onlypakdoes (now disambiguated ascontainer/iostore/planned submodule with phase number)Important fixes:
paksmith list)__test_utilssurface & integration tests that GHAS includes — aligned with CI's--all-targets --all-featuresinvocationtokio— no async runtime exists; replaced with actual deps + note that async is deferred to Phase 5paksmith listexample — addedTest plan
cargo buildsucceeds (no code changes)crates/, CLAUDE.md clippy command matches.github/workflows/ci.yml, README build command works against currentdefault-members🤖 Generated with Claude Code