docs: purge historical / pre-implementation artifacts (−55k lines)#54
Merged
Conversation
Cleans out documents that pollute AI context (and developer search) without describing current behavior. The deletions fall in five clusters: ## 1. Pre-1.0 roadmap / parity docs (top-level) - `docs/MVP-ROADMAP.md` — superseded by `ROADMAP_TO_1.0.md` - `docs/CLI_PARITY.md` — pre-1.0 parity tracking; specs in `docs/subcommand-specs/` are now authoritative - `docs/PARITY_APPROACH.md` (Oct 2025 strategy doc) - `docs/PARITY_PROMPT.md` (AI-prompt template for generating gap issues) - `docs/testcontainers-migration.md` (migration tracker for upstream issue #436; doesn't exist locally) - `docs/mergedConfiguration-test-fixtures.md` (regression-prevention doc for `specs/004-mergedconfig-metadata`, which has shipped) `README.md` updated to point at `docs/ROADMAP_TO_1.0.md` instead of the deleted `docs/MVP-ROADMAP.md`. ## 2. 1.4 MB upstream-codebase snapshot - `docs/repomix-output-devcontainers-cli.xml` — repomix-format snapshot of the entire upstream `devcontainers/cli` codebase, useful for one-time AI context but committed by accident. It inflated every `grep`/`rg` over `docs/`, every assistant context window, and every clone size. `.gitignore` now contains `repomix-output*` / `**/repomix-output*` so this can't recur. ## 3. Pre-implementation gap analyses (one per subcommand) Every `docs/subcommand-specs/*/GAP.md` (6 files) was a snapshot of "what we haven't implemented yet" from Oct/Nov 2025. The commands have all shipped; the GAP analyses are pure history. ## 4. Templates-subcommand historical analysis bundle - `docs/subcommand-specs/templates/GAP-ANALYSIS-SUMMARY.md` - `docs/subcommand-specs/templates/IMPLEMENTATION-STATUS.md` (the "~40% compliance" snapshot) - `docs/subcommand-specs/templates/QUICK-REFERENCE.md` - `docs/subcommand-specs/templates/README.md` (90% pointers to the above) ## 5. Maverick workflow artifact - `docs/subcommand-specs/upgrade/MAVERICK_APPROVALS.md` — auto-approval log from a December 2025 maverick run. ## 6. Pre-implementation task breakdowns - `docs/subcommand-specs/*/tasks/` (6 dirs, ~30 files of `01-cli-flags-and-validation.md`-style work-planning artifacts) - `docs/subcommand-specs/completed-specs/*/tasks/` (27 more files for the build / exec / read-configuration commands) ## 7. completed-specs supplementary historical files `docs/subcommand-specs/completed-specs/` has parallel spec directories for `build`, `exec`, `read-configuration`. Same cleanup rule: deleted `GAP.md`, `IMPLEMENTATION_STATUS.md`, `IMPLEMENTATION_CHECKLIST.md`, `SPEC_VS_IMPLEMENTATION.md`, `SUMMARY.md`, `FEATURES_FLAGS.md`, per-command `README.md`. Kept the authoritative `SPEC.md`, `DATA-STRUCTURES.md`, `DIAGRAMS.md` per command. ## Updates - `docs/ROADMAP_TO_1.0.md`: marked the two punchlist items (consolidate parity docs / add SECURITY.md / add CONTRIBUTING.md) as Done with pointers to the work that landed. - `.gitignore`: added `repomix-output*` pattern. ## Net diff **144 files changed, +20 / −55,455 lines.** What remains in `docs/`: - `ARCHITECTURE.md` (referenced from CLAUDE.md) - `ROADMAP_TO_1.0.md` (referenced from CLAUDE.md) - `testing/nextest.md` (current test-runner reference) - 6 active subcommand-specs × ~3 spec files each (`SPEC.md` + `DATA-STRUCTURES.md` + `DIAGRAMS.md`, sometimes `README.md`) - 3 completed-spec commands × 3 spec files each **33 files total**, all current and load-bearing. ## Verification - `cargo build` ✓ - No code touched; this is a docs-only change. Co-Authored-By: Claude Opus 4.7 (1M context) <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.
Cleans out documents that pollute AI context (and developer search) without describing current behavior.
Net diff: 143 files changed, +19 / −55,455 lines.
What's deleted
1. Pre-1.0 roadmap / parity docs (top-level)
docs/MVP-ROADMAP.md— superseded byROADMAP_TO_1.0.mddocs/CLI_PARITY.md,docs/PARITY_APPROACH.md,docs/PARITY_PROMPT.md— Oct 2025 parity strategy docsdocs/testcontainers-migration.md— migration tracker for upstream issue #436; doesn't exist locallydocs/mergedConfiguration-test-fixtures.md— regression-prevention doc forspecs/004-mergedconfig-metadata, which shipped2. 1.4 MB upstream-codebase snapshot
docs/repomix-output-devcontainers-cli.xml— repomix dump of the entiredevcontainers/cliupstream, accidentally committed. Inflated everygrep/rg, every assistant context window, and every clone size..gitignorenow containsrepomix-output*so this can't recur.3. Pre-implementation gap analyses
docs/subcommand-specs/*/GAP.md(6 files) — snapshots from Oct/Nov 2025 of "what's not implemented yet." Commands have shipped.4. Templates supplementary historical bundle
templates/GAP-ANALYSIS-SUMMARY.md,templates/IMPLEMENTATION-STATUS.md("~40% compliance" snapshot),templates/QUICK-REFERENCE.md,templates/README.md(90% pointers to the above three)5. Maverick workflow artifact
docs/subcommand-specs/upgrade/MAVERICK_APPROVALS.md— auto-approval log from a Dec 2025 maverick run6. Pre-implementation task breakdowns
docs/subcommand-specs/*/tasks/directories + the 3 undercompleted-specs/(~12001-cli-flags-and-validation.md-style work-planning files)7.
completed-specs/supplementary historical filesGAP.md,IMPLEMENTATION_STATUS.md,IMPLEMENTATION_CHECKLIST.md,SPEC_VS_IMPLEMENTATION.md,SUMMARY.md,FEATURES_FLAGS.md, per-commandREADME.mdacross build/exec/read-configuration. Kept the authoritativeSPEC.md,DATA-STRUCTURES.md,DIAGRAMS.md.What's kept (the 33 remaining files in
docs/)ARCHITECTURE.md— referenced from CLAUDE.mdROADMAP_TO_1.0.md— referenced from CLAUDE.md; updated to mark completed punchlist items as Donetesting/nextest.md— current test-runner referenceUpdates alongside deletions
README.md— olddocs/MVP-ROADMAP.mdlink now points atdocs/ROADMAP_TO_1.0.mddocs/ROADMAP_TO_1.0.md— two punchlist items marked Done (consolidate parity docs / add SECURITY.md / CONTRIBUTING.md) with pointers to the work that landed.gitignore— addedrepomix-output*patternVerification
cargo build✓ — no code touched🤖 Generated with Claude Code