From db2ed75a7b37eeada91ee1c29edc0f6d9408bcf2 Mon Sep 17 00:00:00 2001 From: Ralf Anton Beier Date: Wed, 20 May 2026 21:18:02 +0200 Subject: [PATCH] docs: archive 17 stale planning docs to docs/historical/ (REQ-074 Phase 2a) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wave 1 / PR-C of the cross-git investigation follow-ups. Acts on the ARCHIVE verdicts from the docs audit (DOC-DOCS-AUDIT-2026-05-19): roughly a third of the docs/ tree was dead-letter planning material sitting next to active reference docs. Moved to docs/historical/ (17 files, all `git mv` — history preserved): - 15 docs/plans/2026-03-*.md — implementation plans for work that has long since shipped (commit-traceability, cross-repo linking, rowan/salsa, baseline-scoped validation, LSP, formal-verification completion, the v0.1.0 release plan, ...). - docs/audit-report.md — a 2026-03-09 doc-vs-reality snapshot that still claimed fuzz/mutation testing "NOT IMPLEMENTED" while CI runs both. Superseded by docs/research/2026-05-19-docs-audit.md. - docs/design/rivet-cli-gaps-2026-04.md — a gap list with most items now shipped. Kept in docs/plans/: oslc-analysis.md (audit verdict KEEP — explains a deliberate non-shipping decision still in force) and the two vscode-lsp-rendering files (audit verdict INVESTIGATE — need a maintainer triage, not archival). doc_check change: `docs/historical/` joins `docs/plans/` and `docs/design/` as an auto-`is_design_doc` directory. A frozen archive snapshot legitimately references subcommands, artifact counts, and IDs that have since changed; without the exemption the moved files would trip the existence-based doc-check invariants (SubcommandReferences / ArtifactCounts / ArtifactIdValidity). New unit test `historical_dir_is_design_doc_without_marker`. The one real inbound markdown link (what-is-rivet.md → audit-report) is repointed to the new path and annotated as superseded. Verified: `rivet docs check` PASS (57 files, 0 violations); `cargo clippy -p rivet-core -- -D warnings` exit 0; the new unit test passes. Refs: FEAT-135, REQ-073, REQ-074 Co-Authored-By: Claude Opus 4.7 --- .../2026-03-09-spar-wasm-browser-rendering.md | 0 .../2026-03-10-commit-traceability-design.md | 0 .../2026-03-10-commit-traceability-plan.md | 0 .../2026-03-10-cross-repo-linking-design.md | 0 .../2026-03-10-cross-repo-linking-plan.md | 0 ...6-03-10-unidirectional-externals-design.md | 0 ...026-03-10-unidirectional-externals-plan.md | 0 ...3-14-phase3-parallel-workstreams-design.md | 0 .../2026-03-15-release-v0.1.0-plan.md | 0 .../2026-03-16-coverage-gap-analysis.md | 0 ...26-03-16-formal-verification-completion.md | 0 .../2026-03-16-rowan-salsa-completion.md | 0 .../2026-03-16-stpa-sec-analysis.md | 0 ...03-21-baseline-scoped-validation-design.md | 0 ...026-03-21-lsp-salsa-architecture-design.md | 0 docs/{ => historical}/audit-report.md | 0 .../rivet-cli-gaps-2026-04.md | 0 docs/what-is-rivet.md | 5 +-- rivet-core/src/doc_check.rs | 32 +++++++++++++++++-- 19 files changed, 32 insertions(+), 5 deletions(-) rename docs/{plans => historical}/2026-03-09-spar-wasm-browser-rendering.md (100%) rename docs/{plans => historical}/2026-03-10-commit-traceability-design.md (100%) rename docs/{plans => historical}/2026-03-10-commit-traceability-plan.md (100%) rename docs/{plans => historical}/2026-03-10-cross-repo-linking-design.md (100%) rename docs/{plans => historical}/2026-03-10-cross-repo-linking-plan.md (100%) rename docs/{plans => historical}/2026-03-10-unidirectional-externals-design.md (100%) rename docs/{plans => historical}/2026-03-10-unidirectional-externals-plan.md (100%) rename docs/{plans => historical}/2026-03-14-phase3-parallel-workstreams-design.md (100%) rename docs/{plans => historical}/2026-03-15-release-v0.1.0-plan.md (100%) rename docs/{plans => historical}/2026-03-16-coverage-gap-analysis.md (100%) rename docs/{plans => historical}/2026-03-16-formal-verification-completion.md (100%) rename docs/{plans => historical}/2026-03-16-rowan-salsa-completion.md (100%) rename docs/{plans => historical}/2026-03-16-stpa-sec-analysis.md (100%) rename docs/{plans => historical}/2026-03-21-baseline-scoped-validation-design.md (100%) rename docs/{plans => historical}/2026-03-21-lsp-salsa-architecture-design.md (100%) rename docs/{ => historical}/audit-report.md (100%) rename docs/{design => historical}/rivet-cli-gaps-2026-04.md (100%) diff --git a/docs/plans/2026-03-09-spar-wasm-browser-rendering.md b/docs/historical/2026-03-09-spar-wasm-browser-rendering.md similarity index 100% rename from docs/plans/2026-03-09-spar-wasm-browser-rendering.md rename to docs/historical/2026-03-09-spar-wasm-browser-rendering.md diff --git a/docs/plans/2026-03-10-commit-traceability-design.md b/docs/historical/2026-03-10-commit-traceability-design.md similarity index 100% rename from docs/plans/2026-03-10-commit-traceability-design.md rename to docs/historical/2026-03-10-commit-traceability-design.md diff --git a/docs/plans/2026-03-10-commit-traceability-plan.md b/docs/historical/2026-03-10-commit-traceability-plan.md similarity index 100% rename from docs/plans/2026-03-10-commit-traceability-plan.md rename to docs/historical/2026-03-10-commit-traceability-plan.md diff --git a/docs/plans/2026-03-10-cross-repo-linking-design.md b/docs/historical/2026-03-10-cross-repo-linking-design.md similarity index 100% rename from docs/plans/2026-03-10-cross-repo-linking-design.md rename to docs/historical/2026-03-10-cross-repo-linking-design.md diff --git a/docs/plans/2026-03-10-cross-repo-linking-plan.md b/docs/historical/2026-03-10-cross-repo-linking-plan.md similarity index 100% rename from docs/plans/2026-03-10-cross-repo-linking-plan.md rename to docs/historical/2026-03-10-cross-repo-linking-plan.md diff --git a/docs/plans/2026-03-10-unidirectional-externals-design.md b/docs/historical/2026-03-10-unidirectional-externals-design.md similarity index 100% rename from docs/plans/2026-03-10-unidirectional-externals-design.md rename to docs/historical/2026-03-10-unidirectional-externals-design.md diff --git a/docs/plans/2026-03-10-unidirectional-externals-plan.md b/docs/historical/2026-03-10-unidirectional-externals-plan.md similarity index 100% rename from docs/plans/2026-03-10-unidirectional-externals-plan.md rename to docs/historical/2026-03-10-unidirectional-externals-plan.md diff --git a/docs/plans/2026-03-14-phase3-parallel-workstreams-design.md b/docs/historical/2026-03-14-phase3-parallel-workstreams-design.md similarity index 100% rename from docs/plans/2026-03-14-phase3-parallel-workstreams-design.md rename to docs/historical/2026-03-14-phase3-parallel-workstreams-design.md diff --git a/docs/plans/2026-03-15-release-v0.1.0-plan.md b/docs/historical/2026-03-15-release-v0.1.0-plan.md similarity index 100% rename from docs/plans/2026-03-15-release-v0.1.0-plan.md rename to docs/historical/2026-03-15-release-v0.1.0-plan.md diff --git a/docs/plans/2026-03-16-coverage-gap-analysis.md b/docs/historical/2026-03-16-coverage-gap-analysis.md similarity index 100% rename from docs/plans/2026-03-16-coverage-gap-analysis.md rename to docs/historical/2026-03-16-coverage-gap-analysis.md diff --git a/docs/plans/2026-03-16-formal-verification-completion.md b/docs/historical/2026-03-16-formal-verification-completion.md similarity index 100% rename from docs/plans/2026-03-16-formal-verification-completion.md rename to docs/historical/2026-03-16-formal-verification-completion.md diff --git a/docs/plans/2026-03-16-rowan-salsa-completion.md b/docs/historical/2026-03-16-rowan-salsa-completion.md similarity index 100% rename from docs/plans/2026-03-16-rowan-salsa-completion.md rename to docs/historical/2026-03-16-rowan-salsa-completion.md diff --git a/docs/plans/2026-03-16-stpa-sec-analysis.md b/docs/historical/2026-03-16-stpa-sec-analysis.md similarity index 100% rename from docs/plans/2026-03-16-stpa-sec-analysis.md rename to docs/historical/2026-03-16-stpa-sec-analysis.md diff --git a/docs/plans/2026-03-21-baseline-scoped-validation-design.md b/docs/historical/2026-03-21-baseline-scoped-validation-design.md similarity index 100% rename from docs/plans/2026-03-21-baseline-scoped-validation-design.md rename to docs/historical/2026-03-21-baseline-scoped-validation-design.md diff --git a/docs/plans/2026-03-21-lsp-salsa-architecture-design.md b/docs/historical/2026-03-21-lsp-salsa-architecture-design.md similarity index 100% rename from docs/plans/2026-03-21-lsp-salsa-architecture-design.md rename to docs/historical/2026-03-21-lsp-salsa-architecture-design.md diff --git a/docs/audit-report.md b/docs/historical/audit-report.md similarity index 100% rename from docs/audit-report.md rename to docs/historical/audit-report.md diff --git a/docs/design/rivet-cli-gaps-2026-04.md b/docs/historical/rivet-cli-gaps-2026-04.md similarity index 100% rename from docs/design/rivet-cli-gaps-2026-04.md rename to docs/historical/rivet-cli-gaps-2026-04.md diff --git a/docs/what-is-rivet.md b/docs/what-is-rivet.md index 44ae95e6..ced52270 100644 --- a/docs/what-is-rivet.md +++ b/docs/what-is-rivet.md @@ -382,8 +382,9 @@ server-side-validated before it lands. - **Polarion / ReqIF fidelity audit.** [docs/design/polarion-reqif-fidelity.md](design/polarion-reqif-fidelity.md). - **Roadmap.** [docs/roadmap.md](roadmap.md). -- **Audit report.** [docs/audit-report.md](audit-report.md) — state - of doc-vs-reality after PR #171's audit. +- **Audit report.** [docs/historical/audit-report.md](historical/audit-report.md) + — archived doc-vs-reality snapshot (2026-03-09). Superseded by + [docs/research/2026-05-19-docs-audit.md](research/2026-05-19-docs-audit.md). --- diff --git a/rivet-core/src/doc_check.rs b/rivet-core/src/doc_check.rs index 5cd3cb76..b0ef5fa5 100644 --- a/rivet-core/src/doc_check.rs +++ b/rivet-core/src/doc_check.rs @@ -134,10 +134,15 @@ pub struct DocFile { impl DocFile { pub fn new(rel_path: PathBuf, content: String) -> Self { + // `plans/` and `design/` are forward-looking; `historical/` is + // frozen archive (REQ-073/074). All three legitimately reference + // subcommands / artifact counts / IDs that have since changed, + // so they opt out of the existence-based invariants. let is_design_doc = content.contains("rivet-docs-check: design-doc-aspirational-ok") - || rel_path - .components() - .any(|c| c.as_os_str() == "plans" || c.as_os_str() == "design"); + || rel_path.components().any(|c| { + let s = c.as_os_str(); + s == "plans" || s == "design" || s == "historical" + }); Self { rel_path, content, @@ -1586,6 +1591,27 @@ mod tests { assert_eq!(v[0].file, PathBuf::from("README.md")); } + /// REQ-073/074: a file under `docs/historical/` is a frozen archive + /// snapshot and opts out of the existence-based invariants — same as + /// `plans/` and `design/` — without needing the explicit marker. + /// + /// rivet: verifies REQ-074 + #[test] + fn historical_dir_is_design_doc_without_marker() { + assert!( + doc("docs/historical/old-plan.md", "Run `rivet discover`.").is_design_doc, + "docs/historical/ must be exempt from existence invariants" + ); + assert!( + doc("docs/plans/p.md", "x").is_design_doc, + "docs/plans/ exemption must still hold" + ); + assert!( + !doc("docs/getting-started.md", "x").is_design_doc, + "a normal reference doc must NOT be auto-exempt" + ); + } + #[test] fn subcommand_references_skip_design_doc() { let content = "\n\