docs: move evidence out of the tree, prune orphan dev docs, give ADRs a lifecycle (#1625)

[DecisionNerd]

Closes #1625.

What changed

Method and hashes stay in the repo; results live on the issue. Every evidence file under docs/development/ is removed from the tree and linked, with its SHA-256, from the issue that produced it (permalinks on 29a7b34ebe44, the base of this PR). Schema files that CI validates against move beside their validators, and the receipts three harness tests read as inputs become test fixtures.

Surface	Before (29a7b34e)	After
docs/ tracked files / lines	2,812 / 422,729	238 / 76,055
docs/development/ files / lines	2,622 / 361,748	48 / 14,991
docs/development/evidence/ files / lines	2,525 / 342,843	removed
docs/development/*.md	76	33
unreferenced docs/development/*.md	41	0 (CI-enforced)
ADRs with revisit_when	0 of 47	47 of 47
guide directories	2	1

docs/development/ shrinks 24x. The issue was measured on an older main (231 evidence files); seven spike dispositions since (#1448, #1506, #1509, #1585, #1600, #1607, #1584) had added ~2,300 more files, which is the growth the new check stops.

1. Evidence out of the tree

• docs/development/evidence/** (2,525 files) and the four docs/development/*-evidence.json files are deleted. A comment on each of the 54 originating issues lists every removed file with its permalink and SHA-256 (table below).
• Schemas: g500-certification.schema.json, fly-filesystem-qualification.schema.json → scripts/ci/schemas/; g500-ladder-qualification.schema.json → benchmarks/schemas/. All six readers updated; their tests pass.
• Test inputs: the epic(storage): reduce lifecycle amplification and improve persistent storage/query efficiency #1194 S20/S22 receipts, the fix(scale): resolve S20–S22 process RSS growth blocking S24 admission #1278 s*.json receipts, the two research(storage): attribute remaining ingestion cost after shaping repair #1282 reports and the perf(storage): diagnose and resolve lifecycle runtime scaling threatening S25/S26 #1279 baseline that test_lifecycle_runtime, test_ingestion_attribution and test_parquet_root_1286 analyse move to benchmarks/tests/fixtures/rungs/; the receipt include_str!'d by the certify runner's snapshot-contract test moves to benchmarks/runners/certify/fixtures/. Those tests pass unchanged.
• test_repository_archives_contain_every_manifest_payload is removed: its subject, ladder archives staged inside the repo, no longer exists by policy. Ladder retention (make -C benchmarks retain-ladder-evidence) now targets an out-of-tree archive whose path and manifest digest go on the citing issue; benchmarks/README.md, perf-g500-ladder.md, the Makefile and the module docstring say so. The .gitignore exception for controller-summary.log is dropped.
• bazel-migration-evidence/{perf-sample,ci-gate-ruleset-19988544}.json are CI inputs, not evidence; they move to tools/bazel/migration-evidence/ (test.yml, both scripts, classifier updated).
• Every link or path mention of a removed file in docs/, two Rust doc comments and benchmarks/README.md now points at the permalink (73 references, 16 files).
• make bench-adjacency-200m / bench-file-backed-128m write their evidence to build/ instead of docs/development/.

2. The 41 unreferenced development docs

Disposition	Files
Deleted (superseded pre-v0.5 plans and status reports; history keeps them)	QUICKSTART_V0.2.md, documentation-update-summary.md, phase-1a-completion-report.md, testing-setup-complete.md, v0.4-revised-plan.md, tck_baseline_analysis_v0.3.md, perf-v038-to-v039-delta.md, perf-baseline-findings-v0.3.9.md (referenced only by the previous), parser-performance-analysis.md, executor-kernel-audit.md (audit table for the long-finished issue 1026)
Folded into one page	26 m4-disposition-*.md → m4-algorithm-dispositions.md, linked from m4-exit-evidence.md
Folded into the topic page	perf-delta-stepping-539.md → execution-resource-policy.md (new #539 section); ir-identity-wire.md → book/architecture/ast-and-planning.md (IR 1.0.0 identity wire contract)
Linked from a topic page	stage-error-contract.md ← ADR 0035 and ast-and-planning.md; parser-api-boundary.md ← ast-and-planning.md; fly-filesystem-qualification.md ← g500-certification.md; ingest-region-diagnostics.md ← benchmarking.md; v0.5.0-release-operator-runbook.md ← release-process.md (historical); codecov-integration.md ← testing.md

3. Bazel migration

Seven bazel-migration-*.md pages collapse into docs/development/bazel-migration.md (sections: orchestration, ledger, baseline, parity, cache gates, cutover, AC evidence map). bazel-migration-ledger-check.py and bazel-cache-perf.py read the new page; the change classifier and its test are updated; all inbound links repointed. #1618 decides whether the page survives.

4. ADR lifecycle

Every one of the 47 ADRs carries status, superseded_by and a new revisit_when trigger in frontmatter. scripts/ci/adr-index.py refuses a record without one and renders it as a Revisit when column in the generated docs/engineering/adrs/README.md log (two new mutation tests). ADR 0046 already carried per-row triggers; its frontmatter trigger summarises them.

Deprecations: none. The six ADRs with zero inbound references (0027 native runtime boundary, 0028 shared mutation transaction, 0029 lowering snapshot, 0030 portable OCI crate, 0041 branch publication, 0042 contextual research claims) each still govern live code (graphforge-portable-oci, LoweringSnapshot, MutationTransaction, research branches and claims in graphforge-api, the native-only binding contract), so none is deprecated. The rule and the Deprecated status are documented in docs/adr/README.md and the engineering log.

5. One guide tree, one publishing surface

docs/guides/{repository-integration,infrastructure-validation}.md move to docs/guide/. The site keeps the old URL via an Astro redirect (/guides/repository-integration/ → /guide/repository-integration/); the CLI and Python READMEs use the new URL; durability-isolation-gate.py reads the new path; the previously unpublished infrastructure-validation guide is now allowlisted and in the sidebar. Book/site: docs/ was already the only hand-maintained source (the site syncs an allowlist at build time). That is now stated in docs/README.md and the contributing page; no copy existed to delete. pnpm docs:build (134 pages) and pnpm docs:check-links (20,115 hrefs, 0 broken) pass locally.

6. CI

scripts/ci/docs-tree-policy.py check runs unconditionally in the Repository Policy job: it fails on any non-prose/non-image file under docs/ outside docs/contracts/, docs/reference/discovery/, docs/releases/records/ and the two generated schema inventories; on any file over 300,000 bytes; and on any docs/development/*.md no other tracked text file names. report prints the census. test-docs-tree-policy.py proves each rule against a known positive and then checks the real tree.

7. Policy text

One paragraph each in AGENTS.md (Evidence), CONTRIBUTING.md, docs/development/contributing.md, plus two conventions in docs/README.md. Issues #1616, #1617, #1620 and #1623 are amended to say "on the issue" instead of "committed under docs/development/"; #1618 only referenced docs/development/bazel*.md (documentation, not evidence) and needed no change.

Evidence ledger (by originating issue)

Each issue carries a comment with every file, its permalink and SHA-256.

Issue	Files	Lines
#290	1	163
#336	1	48
#338	2	94
#345	1	728
#1194	61	37,045
#1196	1	847
#1202	1	860
#1203	1	865
#1204	1	377
#1205	1	1,053
#1207	1	8,831
#1213	2	2,486
#1218	1	109
#1219	1	94
#1221	1	155
#1222	1	82
#1224	4	897
#1228	1	132
#1229	1	6,020
#1230	1	111
#1231	1	264
#1241	1	823
#1247	1	1,147
#1249	1	12,578
#1268	1	1,834
#1272	1	17
#1274	1	1,808
#1278	28	35,331
#1279	4	1,753
#1282	14	31,709
#1286	9	19,456
#1384	20	28,665
#1393	7	429
#1418	5	88
#1441	2	397
#1445	2	278
#1448	616	2,738
#1465	2	1,277
#1472	2	711
#1473	2	96
#1478	38	44,068
#1480	2	56,212
#1481	2	1,206
#1506	175	2,865
#1507	3	3,204
#1508	2	390
#1509	111	1,845
#1562	9	428
#1584	31	594
#1585	739	25,096
#1586	5	187
#1600	344	1,052
#1606	9	1,556
#1607	251	1,044

Verification

python3 scripts/ci/docs-tree-policy.py check            # 236 files, 31 dev docs, 0/0/0
python3 scripts/ci/test-docs-tree-policy.py             # 9 tests OK
python3 scripts/ci/adr-index.py generate && ... check   # 44 active + 3 superseded agree
python3 scripts/ci/test-adr-index.py                    # 23 mutations fail closed
python3 scripts/ci/test-bazel-migration-ledger-check.py; test-bazel-cache-perf.py; test-classify-changes.sh
python3 scripts/ci/test-fly-filesystem-safety-contract.py
uv run --with pytest --with jsonschema python scripts/ci/test-validate-g500-certification.py   # exit 0
uv run --with pytest --with jsonschema python scripts/ci/test-fly-filesystem-qualification.py  # exit 0
cd benchmarks && PYTHONPATH=harness uv run python -m unittest tests.test_lifecycle_runtime tests.test_ingestion_attribution tests.test_parquet_root_1286 tests.test_ladder_retention   # 29 OK
cd benchmarks && cargo test -p graphforge-benchmark-certify --lib region_diagnostics   # 5 passed
pnpm docs:build && pnpm docs:check-links   # 134 pages, 20115 hrefs, 0 broken
ruff check / ruff format --check on changed Python; cargo fmt --all -- --check (root and benchmarks)

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository: CurateLabs/graphforge/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: 03c90c18-38ec-4261-9ba5-25ca1d5d7593

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}