jschoubben
87f4f29cc6
ADR 0027 — the product is Novox Mesh, shortened to mesh internally. HAL was never chosen: it arrived with the dotfiles repository this grew out of, it is borrowed, and it is borrowed from the canonical untrustworthy machine intelligence, which is an odd flag for infrastructure trusted with credentials. Timing is the substance of the decision, not an aside — the skeleton is not built, so renaming costs a search and replace now and a migration later. Nox is an identity of Novox, and specifically the agent of the MESH rather than of a node. Nodes keep their own identities. Nox addresses them, and a human mostly talks to Nox — which makes it the concrete form of the mission's vision: state an intent, and the mesh works out which node holds the thing. It holds no private channel. The gap this opens is recorded: ADR 0012 binds every agent to a home node, and a mesh-scoped agent has none, so the model needs extending. ADR 0028 — HQ is company-scoped, novox/hq, with the mesh as its first product. Checked rather than assumed: the company organisation already holds live projects that the mesh builds and deploys, so they are tenants rather than peers, and the mesh is the ground they stand on. There is also company work outside the mesh already, which strengthens the case and means the eventual split is closer than "some day" — so each document's scope is fixed now, in a table, making that split mechanical instead of archaeological. The folders are deliberately not restructured yet. The skeleton takes the new vocabulary: mesh-host, mesh-substrate, mesh-control, mesh-surfaces, mesh-catalog. Substrate drops to four services now that identity is a hosted workload rather than a dependency. Research 009 opens the migration, with the reframing that lowers its risk: replace the control plane, do not move the workloads. Their data never moves, so it is re-declared rather than adopted — which keeps adoption out of scope, as the lab design requires. Self-hosting is the last phase, or a failed cutover takes away the means to fix it.
46 lines
2.0 KiB
Markdown
46 lines
2.0 KiB
Markdown
---
|
|
name: hal-amend-design
|
|
description: Use when an HQ design document must change, or when an as-is document is found to be wrong about what the mesh actually does. Triggers on "the design changed", "that's not how it works any more", "update the as-is", "this shipped differently".
|
|
---
|
|
|
|
# hal-amend-design
|
|
|
|
Changes a design document. **Authoritative playbook:**
|
|
[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md).
|
|
|
|
## Which layer is being changed
|
|
|
|
**Establish this first — the two amend for opposite reasons.**
|
|
|
|
| Layer | Amend when | Requires |
|
|
|---|---|---|
|
|
| `01-to-be/` | The intention changed | A decision record. Always. |
|
|
| `00-as-is/` | The mesh changed, or the document was wrong about it | Evidence from the implementation. Never a decision. |
|
|
|
|
An as-is document is corrected against **what the code does**, not against what anyone meant.
|
|
If the implementation and the intention disagree, the as-is document records the implementation
|
|
and says they disagree.
|
|
|
|
## Amending the to-be layer
|
|
|
|
1. Write the decision record. If it reverses an earlier one, that record gets
|
|
`status: superseded` and `superseded-by:` — its text is never edited.
|
|
2. Edit the design; set `updated:` to today.
|
|
3. If this came from an issue, set that issue's `amended-design:`.
|
|
|
|
## Amending the as-is layer
|
|
|
|
1. Establish what is actually true — from the code, a pipeline log, a live query, the
|
|
operational record. Not from a design document.
|
|
2. Edit the document. Set `updated:` only if the **implementation state** changed; a
|
|
correction to text that was always wrong does not change it.
|
|
3. If the correction reveals that something shipped differently from its design, say so in the
|
|
as-is document and leave the to-be document alone. That divergence is a finding, and may
|
|
deserve an issue.
|
|
|
|
## Do not
|
|
|
|
- Do not put a future intention in an as-is document.
|
|
- Do not quietly fix a wrong claim that held up a decision. Record that it was wrong and where
|
|
it was relied on — that is the failure this repository exists to name.
|