Preserve development plans and schedule early stabilization

README.md

@@ -231,6 +231,11 @@ CI runs Python 3.11 to 3.14 and the free-threaded 3.14t build. Reports on
 each development slice, with their evidence and measurements, are in
 [docs/history](docs/history/README.md).
 
+Planned work (stabilization of the current product, then the Open/R and BGP
+foundation and the shared route-policy language) is ordered in the roadmap, [docs/plan.md](docs/plan.md). Its
+contracts are in [docs/design](docs/design/README.md); they describe future
+behaviour, not features available today.
+
 ## License
 
 MIT

docs/design/README.md

@@ -0,0 +1,60 @@
+# Design
+
+These pages specify behaviour NetLab-Sim does not have yet: the foundation for
+Open/R and BGP, and the shared route-policy language. The stabilization page
+also states what the review, the NetGraph 0.26 port and the defect fixes of
+the implemented product must guarantee. They are for maintainers who implement
+or review that work.
+
+## Which document decides what
+
+| Question | Where the answer lives |
+|---|---|
+| What the code does now | The code and its tests, then the [README](../../README.md) and the [reference](../reference.md). [History reports](../history/README.md) record what each delivered slice changed and how it was checked, as of their date |
+| What future work must guarantee | The design pages below. Each statement is a requirement for planned code, or an internal guarantee or decision that implemented code still keeps; neither is user documentation |
+| What is planned, in which order, and its state | The [roadmap](../plan.md), the only place with status |
+| Where a requirement came from | The [archive](archive/README.md): frozen design documents kept for extraction and provenance. They are not current rules and do not override anything above |
+
+When a design page and the code disagree, the code describes today and the
+page describes the target; the plan row says which slice closes the gap. When
+the archive and a design page disagree, the design page wins.
+
+## Pages
+
+- [Stabilization](stabilization.md): the review of the implemented product,
+  the NetGraph 0.26 port and the fixes of confirmed defects, including today's
+  resolver defects.
+- [Protocol foundation](protocols.md): the common design decisions, the
+  contracts for F0 and F5, the requirements for F1a, C6, S1a and S1b, and the
+  list of pending contracts with their archived sources.
+- [Routing policy](routing-policy.md): the route-policy language, attachment
+  points, per-node configuration, lifecycle and the acceptance examples E01 to
+  E24.
+
+## Pending contracts
+
+The roadmap records whether a slice's contract is ready
+([status values](../plan.md#status-values)). Reconciling a pending contract
+means: collect every requirement from the archived sections and from all later
+amendments of them, write them as exact rules with the examples and tests that
+check them, and resolve or record each conflict. A pending contract is
+reconciled before its implementation starts, not all at once: work on the next
+slice needs only its own contract and those it depends on.
+
+Rules for these pages:
+
+- One home per requirement. The plan holds order and state; a design page holds
+  the rule; neither repeats the other.
+- A design page names no status and no schedule. Planned names (records,
+  modules, settings) are written as code-formatted names and are not links;
+  links to code point only at files that exist.
+- A behaviour taken from another implementation (FRR, Open/R) names its pinned
+  source. Such a statement is a vendor reference until a reproducer or pinned
+  fixture confirms it.
+- When a slice lands, the behaviour users rely on moves into the README or the
+  reference in the same change. Internal guarantees, their proofs and
+  decisions that still bind later work may stay on the design page; anything
+  that is no longer true or no longer binding is removed.
+
+How the roadmap is kept current is under
+[Maintaining the roadmap](../plan.md#maintaining-the-roadmap).

docs/design/archive/README.md

@@ -0,0 +1,29 @@
+# Design archive
+
+Frozen copies of the design documents written before the plan moved into this
+repository. They are kept byte for byte as they were last revised, so that
+every requirement can be traced to its source. They are not current rules: the
+[design pages](../README.md) and [docs/plan.md](../../plan.md) override them,
+and their status statements (what is implemented, what can start, test counts,
+review outcomes, measurements) describe their own date and older commits.
+
+The project was called NetSim, with the package `netsim`, and from
+2026-10-02 NetGraph-Sim (`ngraph_sim`); it is now NetLab-Sim (`netlab_sim`).
+The documents keep the old names, file paths and links. Links to files
+outside this repository (research notes, local checkouts, other documents
+under their old names) are not repaired and may not resolve; nothing current
+depends on them.
+
+| File | Original name | Content | Revision and date | SHA-256 |
+|---|---|---|---|---|
+| [network-layer-r17.md](network-layer-r17.md) | `hazy-foraging-cloud.md` | Network-layer design of record: Gates A, B and C | Revision 17 (Gate C implemented), with a rename note of 2026-10-02 | `22bf74952aaeb9c975b428b88fcd1bbf4f9f5202b4a4f49cd7d5ec42112aca5e` |
+| [protocols-r8.md](protocols-r8.md) | `netsim-protocols.md` | Open/R and BGP design and plan; slice table §15.9 amended by §16.9; S0 delivery in §17 | Revision 8, 2026-09-27, with S0 updates of 2026-10-02 | `995c2d5b0c1ef986804125cd5737971e01beedce7d7329105e6b8ed1caaf53a9` |
+| [routing-policy-r4.md](routing-policy-r4.md) | `routing-policy.md` | Routing-policy language and hooks | Revision 4, 2026-09-27 | `2319e0a49de9aa29fefafe92bc757a9db15bfb655f1db55aa977c4db1c8b36d3` |
+| [routing-policy-reviews.md](routing-policy-reviews.md) | `routing-policy-reviews.md` | Review passes that produced routing-policy revision 4 | 2026-09-27 | `8e2f9d5759ea133f4fe77ee90e1b049cc01ca8c1884ba78366fbdf72d742283a` |
+
+Within `protocols-r8.md`, later sections override earlier ones (§16 over §15,
+§15 over the body). `routing-policy-r4.md` links to its review record by its
+original file name, which is kept here.
+
+To check the copies, run `shasum -a 256` on the four files in this directory
+and compare with the table.