Define the Echo–Keep boundary and semantic decision model

.github/workflows/ci.yml

@@ -40,8 +40,8 @@ jobs:
               run: bash tests/docs/test_retired_component_refs.sh
             - name: repository knowledge model regression
               run: bash tests/docs/test_knowledge_model.sh
-            - name: ADR namespace regression
-              run: bash tests/docs/test_adr_namespace.sh
+            - name: Documentation model regression
+              run: bash tests/docs/test_documentation_model.sh
             - name: generated rule truth regression
               run: bash tests/docs/test_generated_rule_truth.sh
             - name: determinism policy gate regression

ADVANCED_GUIDE.md

@@ -15,7 +15,8 @@ Use [GUIDE.md](GUIDE.md) for operator orientation and the
 - [Strictly Deterministic Math](docs/determinism/SPEC_DETERMINISTIC_MATH.md)
   owns the normative numeric policy;
 - [specifications](docs/spec/), [invariants](docs/invariants/), and
-  [ADRs](docs/adr/) own executable contracts and durable decisions.
+  [topics](docs/topics/) own executable contracts and concept-owned durable
+  decisions under the [Documentation Standards](docs/DOCUMENTATION_STANDARDS.md).
 
 Do not recover the former graph-substrate, stale spec-path, generated-client,
 or fabricated trig-oracle guidance from this page. Git history is the archive,

AGENTS.md

@@ -68,7 +68,9 @@ Repository knowledge has one owner for each kind of truth:
 
 - **Current architectural truth**: `docs/architecture/`, `docs/spec/`,
   `docs/invariants/`, and `docs/topics/`.
-- **Durable architectural decisions**: accepted ADRs in `docs/adr/`.
+- **Documentation policy and decision relationships**:
+  `docs/DOCUMENTATION_STANDARDS.md`.
+- **Historical numbered decisions**: the closed archive in `docs/adr/`.
 - **Live work, priority, dependencies, and status**: GitHub Issues, Projects,
   pull requests, and review threads.
 - **Shipped externally meaningful behavior**: `CHANGELOG.md`.
@@ -77,18 +79,20 @@ Repository knowledge has one owner for each kind of truth:
 Use `README.md`, `GUIDE.md`, and `docs/README.md` as entrances. Do not recreate
 cycles, retrospectives, a checked-in backlog, a checked-in status ledger, or a
 post-hoc design document. Change-local design and test plans may live in the
-issue or pull request. Write an ADR only when a decision changes a durable
-architectural boundary or invariant.
+issue or pull request. Record a durable decision in the named current document
+that owns its concept, and state supersession, refinement, dependency, and
+related-decision edges explicitly. Do not allocate a new numbered ADR.
 
 When recovering context, read the relevant canonical topic/spec/invariant and
-ADR, then inspect the current GitHub issue or pull request, `git log -n 5`, and
-`git status`.
+architecture document, follow any explicit links into the historical ADR
+archive, then inspect the current GitHub issue or pull request, `git log -n 5`,
+and `git status`.
 
 ## Work Loop
 
 ```text
 scope claim
--> decide whether an ADR is required
+-> identify the canonical documentation owner
 -> name the test plan and executable witness
 -> RED
 -> GREEN
@@ -139,7 +143,7 @@ changes, compare the branch's actual behavior and artifacts with the current
 documentation. Revisit the relevant entrances and canonical owners:
 `README.md`, `GUIDE.md`, `docs/README.md`, `docs/architecture/`, `docs/spec/`,
 `docs/invariants/`, `docs/topics/`, and the evidence anchors of any applicable
-accepted ADRs.
+historical ADRs.
 
 Search specifically for stale current-state claims such as “not implemented,”
 “fixture-only,” old ownership or authority boundaries, obsolete version or

ARCHITECTURE.md

@@ -20,7 +20,8 @@ owns the boundary you are changing:
   [Runtime Constellation](docs/topics/RuntimeConstellation.md), and
   [WARP Optics](docs/topics/WarpOptics.md) — living cross-module doctrine;
 - [specifications](docs/spec/), [invariants](docs/invariants/), and
-  [ADRs](docs/adr/) — executable contracts and durable decisions.
+  [topics](docs/topics/) — executable contracts and concept-owned durable
+  decisions under the [Documentation Standards](docs/DOCUMENTATION_STANDARDS.md).
 
 The current north star is:
 

CONTRIBUTING.md

@@ -48,8 +48,9 @@ prioritize:
 - Keep `main` pristine. Create feature branches like `echo/<feature>` or `timeline/<experiment>`.
 - Before starting work, ensure `git status` is clean. If not, resolve or coordinate with the human operator.
 - Keep change-local design, test plans, review state, and follow-up work in the
-  GitHub issue or pull request. Record only durable architectural decisions as
-  ADRs in `docs/adr/`.
+  GitHub issue or pull request. Record durable architectural decisions in the
+  semantically named current document that owns the concept, following
+  `docs/DOCUMENTATION_STANDARDS.md`.
 
 ## Testing Expectations
 
@@ -73,8 +74,9 @@ prioritize:
 ## Documentation & Telemetry
 
 - Update relevant docs in `docs/` whenever behavior or architecture changes.
-- Record durable architectural decisions in ADRs (`docs/adr/`). Keep
-  change-local rationale in the issue or pull request.
+- Record durable architectural decisions with their owning concept under
+  `docs/DOCUMENTATION_STANDARDS.md`. Keep change-local rationale in the issue or
+  pull request; treat `docs/adr/` as a closed historical archive.
 
 ## Submitting Changes
 

GUIDE.md

@@ -62,7 +62,9 @@ If you need a comprehensive spec, use the [docs/README.md](./docs/README.md) map
 If you need current architectural truth, use the
 [architecture](./docs/architecture/), [specification](./docs/spec/),
 [invariant](./docs/invariants/), and [topic](./docs/topics/) maps. Durable
-decisions live in [ADRs](./docs/adr/); live work and status live in GitHub.
+decisions live with their owning concept under the
+[Documentation Standards](./docs/DOCUMENTATION_STANDARDS.md); the numbered
+[ADR directory](./docs/adr/) is historical. Live work and status live in GitHub.
 
 If you are just starting, use the [README.md](./README.md) and the orientation tracks above.
 

README.md

@@ -601,9 +601,10 @@ the external Hello Echo application. Compiler-produced application packages use
 the generic `run-edict-operation` witness command.
 
 Live work, priorities, and status are maintained in GitHub Issues, Projects,
-pull requests, and review threads. Architectural decisions live in
-[`docs/adr/`](docs/adr/), while current doctrine lives in
-[`docs/topics/`](docs/topics/).
+pull requests, and review threads. Durable decisions live in the semantically
+named current document that owns their concept, under the
+[`Documentation Standards`](docs/DOCUMENTATION_STANDARDS.md). The numbered
+[`docs/adr/`](docs/adr/) directory is a closed historical archive.
 
 ## Benchmarks And Gates
 

docs/DOCUMENTATION_STANDARDS.md

@@ -0,0 +1,205 @@
+<!-- SPDX-License-Identifier: Apache-2.0 OR LicenseRef-MIND-UCAL-1.0 -->
+<!-- © James Ross Ω FLYING•ROBOTS <https://github.com/flyingrobots> -->
+
+# Documentation Standards
+
+**Status:** Current project policy for new and substantially changed
+documentation.
+**Supersedes:** [ADR 0012: Repository Knowledge Model After Method](adr/0012-repository-knowledge-model.md)
+
+Echo documentation is part of the engineering contract. Its job is to make
+the current system, its governing decisions, and the evidence for those claims
+findable without reconstructing a private chronology.
+
+This policy adapts the structure of Colorful Language's
+[documentation standard](https://github.com/flyingrobots/colorful-language/blob/09dc60a9f23834f8511bcb3067cb1ac4393fae8a/docs/DOCUMENTATION_STANDARDS.md)
+to Echo's existing knowledge model. Echo keeps its established split among
+architecture, specifications, invariants, topics, and executable witnesses. It
+does not adopt Colorful's roadmap, goalpost, or topic test-plan machinery.
+
+## Core rules
+
+1. Give every durable claim one canonical owner.
+2. Give every page one primary reader job.
+3. Name pages after concepts, contracts, or reader tasks, not sequence slots.
+4. State relationships explicitly; directory order and filename order carry no
+   architectural meaning.
+5. Keep current truth, planned work, historical reasoning, and executable
+   evidence distinguishable.
+6. Link strong claims to code, tests, specifications, invariants, or retained
+   historical decisions.
+
+## Corpus map
+
+| Location                                                   | Job                                                                 |
+| ---------------------------------------------------------- | ------------------------------------------------------------------- |
+| `README.md`, `GUIDE.md`                                    | Project entrances and supported routes into deeper documentation.   |
+| `docs/README.md`                                           | Documentation spine and routing index.                              |
+| `docs/topics/`                                             | Living explanations of durable Echo concepts and boundaries.        |
+| `docs/architecture/`                                       | Current cross-subsystem architecture and accepted boundary designs. |
+| `docs/spec/`                                               | Normative protocols, encodings, and conformance contracts.          |
+| `docs/invariants/`                                         | Compact laws that implementations must preserve.                    |
+| `docs/determinism/`                                        | Determinism policy, hazards, and evidence contracts.                |
+| `docs/adr/`                                                | Closed archive of numbered historical decision records.             |
+| GitHub Issues, Projects, pull requests, and review threads | Live work, plans, priority, blockers, and status.                   |
+| `CHANGELOG.md`                                             | Externally meaningful behavior that shipped.                        |
+| Git history                                                | Removed material and the exact evolution of checked-in documents.   |
+
+Do not create a second current reference merely because another directory or
+document type is convenient. Link to the canonical owner and add only the
+reader-specific context the new page needs.
+
+## Page jobs
+
+A page should primarily help its reader do one of these jobs:
+
+- learn a concept or boundary;
+- perform a supported task;
+- look up an exact contract;
+- understand a decision and its tradeoffs;
+- troubleshoot an observable failure;
+- change the implementation and verify the result.
+
+A page may link across jobs, but it should not become a tutorial, reference,
+roadmap, architecture guide, and historical diary at once.
+
+### Topics
+
+A topic describes the current conceptual model. It states the boundary,
+invariants, ownership, and evidence anchors needed to understand that concept.
+Update it in the same change that changes the boundary.
+
+Topics do not own live implementation queues. A limitation may be stated as a
+current fact; the work to change it belongs in GitHub.
+
+### Architecture
+
+An architecture page explains current cross-subsystem structure or an accepted
+boundary design. When an accepted design is not implemented, the page must say
+so prominently and link to the GitHub owner for implementation state. It must
+not describe planned behavior as existing runtime behavior.
+
+### Specifications and invariants
+
+Specifications define conformance. Invariants state compact laws. They are not
+explanatory essays or implementation plans. Examples that form part of a
+contract should be executable or backed by exact fixtures when practical.
+
+## Durable decisions
+
+A durable decision changes a long-lived boundary, identity, format, invariant,
+authority split, compatibility promise, or recovery law. Record the decision
+where a future reader will look for the concept:
+
+- update the owning topic for a conceptual boundary;
+- update the owning architecture page for a cross-subsystem boundary;
+- update the owning specification or invariant for a normative contract;
+- add a semantically named `rationale.md` beside a larger concept when the
+  tradeoffs would otherwise overwhelm its current reference.
+
+Do not allocate a number merely to prove that a decision happened. The numbered
+ADR sequence in `docs/adr/` is a closed historical archive. Existing ADRs remain
+valuable evidence and may be linked, refined, or superseded, but new durable
+decisions use semantic names in their owning current-documentation area.
+
+### Relationship contract
+
+When a decision relates materially to another decision, include the applicable
+relationship near the top of the owning document:
+
+- **Supersedes:** the named older decision no longer governs the stated scope.
+- **Superseded by:** the named newer decision now governs the stated scope.
+- **Refines:** this decision adds precision without replacing the older one.
+- **Depends on:** this decision requires another decision or contract to hold.
+- **Related:** the documents illuminate the same boundary but neither governs
+  the other.
+
+Use descriptive links, not bare identifiers. A supersession must be recorded in
+both directions so readers entering through either document can follow it.
+Absence of a relationship line means no such relationship is claimed; it does
+not mean “whatever has the larger number wins.”
+
+## Current truth, plans, and history
+
+Living references describe current implementation truth or clearly labeled
+accepted contracts. GitHub owns change-local plans and status. Git history owns
+the exact old text.
+
+Do not check in backlogs, cycle packets, retrospectives, review transcripts,
+status ledgers, or roadmap checklists. A short checked-in redirect may remain
+when an old stable path must route readers to its current owner.
+
+Historical reasoning must not masquerade as current behavior. Mark retained
+historical documents clearly and link to the current owner that supersedes or
+refines them.
+
+## Evidence and citations
+
+Strong claims should point to the smallest durable witness that establishes
+them:
+
+- source or public API for ownership and shape;
+- tests, fixtures, or golden vectors for behavior;
+- a specification or invariant for normative law;
+- an accepted architecture page for an unimplemented boundary contract;
+- a historical decision for retained reasoning.
+
+Source links support an explanation; they do not replace one. Prefer
+repository-relative links for checked-in sources. Use stable external
+permalinks when the exact outside revision matters.
+
+Never claim that a command, test, visual inspection, review, or runtime path was
+verified when it was not run or observed.
+
+## Examples and safety
+
+Examples must use supported behavior and enough context to interpret them.
+Separate copyable commands from expected output. Do not put shell prompts in a
+copyable command block.
+
+Put warnings before destructive, privileged, costly, or irreversible commands.
+State the scope and consequence, and provide a safer check or recovery route
+when one exists.
+
+## Writing and structure
+
+- Lead with the result, decision, warning, or essential condition.
+- Prefer exact Echo terms and define unfamiliar ones at first use.
+- Use active voice when it clarifies ownership.
+- Use prose for causality and tradeoffs, lists for parallel facts, and tables
+  for genuinely two-dimensional comparisons.
+- Use descriptive link text rather than “here” or a bare path.
+- Treat length and style metrics as editorial signals, not universal merge
+  gates.
+
+## Maintenance loop
+
+For a meaningful change:
+
+1. Identify the canonical owner of the affected claim.
+2. Name the smallest executable witness when behavior changes.
+3. Update design rationale only when the tradeoff needs durable explanation.
+4. Implement and validate the change.
+5. Update the current owner after the behavior or accepted contract changes.
+6. Add explicit decision relationships when governance changed.
+7. Update `docs/README.md` when a durable route was added or moved.
+8. Keep live follow-up work in GitHub.
+
+## Review checklist
+
+Before calling a documentation change done, verify that:
+
+- the page has one primary reader job;
+- the durable claim has one canonical owner;
+- current behavior and accepted-but-unimplemented design are distinguishable;
+- plans and status remain in GitHub;
+- durable decision relationships are explicit and bidirectional when they
+  supersede;
+- strong claims have appropriate evidence anchors;
+- new durable pages are linked from `docs/README.md`;
+- internal links resolve;
+- Markdown and whitespace checks pass.
+
+The objective is not uniform paperwork. The objective is a corpus in which a
+reader can find what governs a concept, why it governs, what it replaced, and
+what proves it without decoding a global number line.

docs/README.md

@@ -8,6 +8,7 @@ causal history. Git history is the archive; GitHub owns live work and status.
 
 ## Start Here
 
+- [Documentation standards](DOCUMENTATION_STANDARDS.md)
 - [Architecture outline](architecture/outline.md)
 - [Application contract hosting](architecture/application-contract-hosting.md)
 - [Local contract host quickstart](quickstart-local-contract-host.md)
@@ -20,6 +21,7 @@ causal history. Git history is the archive; GitHub owns live work and status.
 - [There Is No Graph](architecture/there-is-no-graph.md)
 - [Continuum transport](architecture/continuum-transport.md)
 - [Echo optics adapter notes](architecture/echo-optics-adapter-notes.md)
+- [Echo × Keep physical content boundary](architecture/echo-keep-physical-content-boundary.md)
 
 ## Case Studies
 
@@ -40,10 +42,15 @@ causal history. Git history is the archive; GitHub owns live work and status.
 - [Runtime constellation](topics/RuntimeConstellation.md)
 - [Security posture and threat models](topics/security/README.md)
 
-## Durable Decisions
+## Decision History
 
-- [ADR map](adr/README.md)
-- [Repository knowledge model](adr/0012-repository-knowledge-model.md)
+Current decisions are reached through the semantic architecture, topic, and
+contract sections above and below. This section routes to the retained numbered
+archive; it is not an allocation queue or a substitute for explicit
+relationships.
+
+- [Legacy numbered decision archive](adr/README.md)
+- [Superseded repository knowledge model](adr/0012-repository-knowledge-model.md)
 - [Echo/Continuum authority boundary](adr/0013-echo-continuum-authority-boundary.md)
 - [Generated rule authorship and footprints](adr/0014-generated-rule-authorship-and-footprints.md)
 - [Registry, provider, and host boundary](adr/0015-registry-provider-host-boundary.md)
@@ -79,7 +86,11 @@ causal history. Git history is the archive; GitHub owns live work and status.
 ## Knowledge Ownership
 
 Current architecture belongs in architecture documents, specifications,
-invariants, and living topics. Accepted durable decisions belong in ADRs.
-Externally meaningful shipped behavior belongs in `CHANGELOG.md`. Live design,
-priority, dependencies, review state, and follow-up work belong in GitHub
-Issues, Projects, pull requests, and review threads.
+invariants, and living topics. Durable decisions update the named document that
+owns their concept and state relationships explicitly. Numbered ADRs are a
+closed historical archive, not the current decision queue. Externally
+meaningful shipped behavior belongs in `CHANGELOG.md`. Live design, priority,
+dependencies, review state, and follow-up work belong in GitHub Issues,
+Projects, pull requests, and review threads. The
+[documentation standards](DOCUMENTATION_STANDARDS.md) define the complete
+contract.