diff --git a/.claude/skills/hal-amend-design/SKILL.md b/.claude/skills/hal-amend-design/SKILL.md index 4db3880..edc08ea 100644 --- a/.claude/skills/hal-amend-design/SKILL.md +++ b/.claude/skills/hal-amend-design/SKILL.md @@ -6,7 +6,7 @@ description: Use when a hal-hq design document must change, or when an as-is doc # hal-amend-design Changes a design document. **Authoritative playbook:** -[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md). +[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md). ## Which layer is being changed diff --git a/.claude/skills/hal-diagnose/SKILL.md b/.claude/skills/hal-diagnose/SKILL.md index 46a7ee1..e7aa44c 100644 --- a/.claude/skills/hal-diagnose/SKILL.md +++ b/.claude/skills/hal-diagnose/SKILL.md @@ -6,7 +6,7 @@ description: Use when investigating an open hal-hq issue — finding which compo # hal-diagnose Investigates an open issue to the point where its owner is known. **Authoritative playbook:** -[`00-GENESIS/process/03-issues.md`](../../../00-GENESIS/process/03-issues.md). +[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md). ## Before forming a hypothesis @@ -28,7 +28,7 @@ result is not "nothing to learn" — it is the reason the next person repeats th what was ruled out and how. Archaeology — which commit, which pull request, which date a behaviour changed — is the most valuable content here. 3. When the owner is known, set `status: located` and fill `located-in:` with repositories or - modules from [`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md). + modules from [`00-META/repos.md`](../../../00-META/repos.md). 4. On resolution: `status: resolved`, fill `fixed-by:`. If the root cause was a design gap, run `hal-graduate` for the amendment and fill `amended-design:`. diff --git a/.claude/skills/hal-graduate/SKILL.md b/.claude/skills/hal-graduate/SKILL.md index 2d09869..1ef5bf1 100644 --- a/.claude/skills/hal-graduate/SKILL.md +++ b/.claude/skills/hal-graduate/SKILL.md @@ -7,17 +7,17 @@ description: Use when a hal-hq research effort concludes and becomes design, or Closes a research effort into a decision and a design, or amends an existing design. **Authoritative playbook:** -[`00-GENESIS/process/02-graduation.md`](../../../00-GENESIS/process/02-graduation.md) — read +[`00-META/process/02-graduation.md`](../../../00-META/process/02-graduation.md) — read it; this skill adds only the scaffolding. ## Steps 1. **Check against GENESIS** — `mission.md`, `context.md`, `effect.md`. If the conclusion conflicts, say which is wrong, in writing, before proceeding. -2. **Write the decision record** in `adr/`, next free number, frontmatter per - [`adr/README.md`](../../../adr/README.md). `reconstructed: false` — this one is being taken, +2. **Write the decision record** in `02-DECISIONS/`, next free number, frontmatter per + [`02-DECISIONS/README.md`](../../../02-DECISIONS/README.md). `reconstructed: false` — this one is being taken, not recovered. Record the rejected options. -3. **Write the design** under `02-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`, +3. **Write the design** under `03-DESIGN/01-to-be/` with `layer: to-be`, `status: designed`, empty `code:`, today's `updated:`, and `decisions:` pointing at the record. 4. **Close the effort** — the research `00-overview.md` gets `status: graduated` and `became:` pointing at both. @@ -31,7 +31,7 @@ Then edit the design and set `updated:`. ## When something ships -Write or update the matching `02-DESIGN/00-as-is/` document so it describes what now runs, +Write or update the matching `03-DESIGN/00-as-is/` document so it describes what now runs, including anything that shipped differently from the intent. Set the to-be document's `status: implemented` and its `code:`. **The to-be document does not move** — both stand. diff --git a/.claude/skills/hal-handoff/SKILL.md b/.claude/skills/hal-handoff/SKILL.md index 3ed0229..6f31b1a 100644 --- a/.claude/skills/hal-handoff/SKILL.md +++ b/.claude/skills/hal-handoff/SKILL.md @@ -6,18 +6,18 @@ description: Use when a hal-hq design is settled and implementation is about to # hal-handoff Hands a settled design to a code repository. **Authoritative playbook:** -[`00-GENESIS/process/04-build-handoff.md`](../../../00-GENESIS/process/04-build-handoff.md). +[`00-META/process/04-build-handoff.md`](../../../00-META/process/04-build-handoff.md). ## Steps 1. **Confirm it is settled.** `status: designed`, and every claim traceable to a record in - `adr/`. An open question in the text is a reason to run `hal-new-research`, not to build + `02-DECISIONS/`. An open question in the text is a reason to run `hal-new-research`, not to build around it. 2. **Name the owner.** Set `code:` from - [`00-GENESIS/repos.md`](../../../00-GENESIS/repos.md). If the repository does not exist yet, + [`00-META/repos.md`](../../../00-META/repos.md). If the repository does not exist yet, add it to `repos.md` in the same change. 3. **Read the as-is counterpart.** What is being replaced must be written down in - `02-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how + `03-DESIGN/00-as-is/` before it is changed. Building against an undocumented as-is is how shipped behaviour gets lost. 4. **Flip the status** to `in-progress`, `updated:` today. 5. Build in the code repository. hal-hq never carries implementation. diff --git a/.claude/skills/hal-new-issue/SKILL.md b/.claude/skills/hal-new-issue/SKILL.md index 62f9803..f17bdbc 100644 --- a/.claude/skills/hal-new-issue/SKILL.md +++ b/.claude/skills/hal-new-issue/SKILL.md @@ -6,7 +6,7 @@ description: Use when something is wrong with the HAL mesh at the level of desig # hal-new-issue Opens a numbered issue. **Authoritative playbook:** -[`00-GENESIS/process/03-issues.md`](../../../00-GENESIS/process/03-issues.md). +[`00-META/process/03-issues.md`](../../../00-META/process/03-issues.md). ## First, decide it belongs here diff --git a/.claude/skills/hal-new-research/SKILL.md b/.claude/skills/hal-new-research/SKILL.md index ddeae00..66081c6 100644 --- a/.claude/skills/hal-new-research/SKILL.md +++ b/.claude/skills/hal-new-research/SKILL.md @@ -6,7 +6,7 @@ description: Use when starting a new research effort in hal-hq — an idea, tech # hal-new-research Scaffolds a new research effort. **Authoritative playbook:** -[`00-GENESIS/process/01-research.md`](../../../00-GENESIS/process/01-research.md) — read it; +[`00-META/process/01-research.md`](../../../00-META/process/01-research.md) — read it; this skill only does the mechanical setup. ## Steps @@ -33,7 +33,7 @@ this skill only does the mechanical setup. - Do not restate the status in prose. It lives in frontmatter, in one place. - Do not fill `became:` while the effort is open — `hal-graduate` sets it at closure. - Do not skip or reuse a sequence number. -- Do not write into `02-DESIGN` from an open effort. +- Do not write into `03-DESIGN` from an open effort. - Do not name the mesh being observed. Evidence is required; identification is forbidden. ## Closing diff --git a/.claude/skills/hal-status/SKILL.md b/.claude/skills/hal-status/SKILL.md index 833fddd..0b1a131 100644 --- a/.claude/skills/hal-status/SKILL.md +++ b/.claude/skills/hal-status/SKILL.md @@ -14,8 +14,8 @@ generated on demand and never written back to disk. | Section | Files | Frontmatter | |---|---|---| | Research | `01-RESEARCH/NNN-*/00-overview.md` | `status` (`active` / `graduated` / `abandoned`), `initiated`, `touches`, `became` | -| Design | `02-DESIGN/**/*.md` (not READMEs) | `layer` (`as-is` / `to-be`), `status` (`designed` / `in-progress` / `implemented` / `abandoned`), `code`, `updated`, `decisions` | -| Decisions | `adr/NNNN-*.md` | `status` (`proposed` / `accepted` / `superseded`), `date`, `deciders`, `reconstructed`, `superseded-by`, `extends` | +| Design | `03-DESIGN/**/*.md` (not READMEs) | `layer` (`as-is` / `to-be`), `status` (`designed` / `in-progress` / `implemented` / `abandoned`), `code`, `updated`, `decisions` | +| Decisions | `02-DECISIONS/NNNN-*.md` | `status` (`proposed` / `accepted` / `superseded`), `date`, `deciders`, `reconstructed`, `superseded-by`, `extends` | | Issues | `04-ISSUES/NNN-*/00-report.md` | `status` (`open` / `diagnosing` / `located` / `resolved` / `wontfix`), `opened`, `located-in`, `fixed-by`, `amended-design` | ## Steps diff --git a/.claude/skills/hal-sync-constitution/SKILL.md b/.claude/skills/hal-sync-constitution/SKILL.md index 4a36268..5002a67 100644 --- a/.claude/skills/hal-sync-constitution/SKILL.md +++ b/.claude/skills/hal-sync-constitution/SKILL.md @@ -1,16 +1,16 @@ --- name: hal-sync-constitution -description: Use after changing a rule in hal-hq's 00-GENESIS/how-we-build.md, to publish the derived constitution page the mesh injects into design sessions. Triggers on "sync the constitution", "publish the rules", "I changed how-we-build", "update the governed page". +description: Use after changing a rule in hal-hq's 00-META/how-we-build.md, to publish the derived constitution page the mesh injects into design sessions. Triggers on "sync the constitution", "publish the rules", "I changed how-we-build", "update the governed page". --- # hal-sync-constitution Publishes the derived constitution from its source. **Authoritative playbook:** -[`00-GENESIS/process/05-constitution-sync.md`](../../../00-GENESIS/process/05-constitution-sync.md). +[`00-META/process/05-constitution-sync.md`](../../../00-META/process/05-constitution-sync.md). ## What this is -[`00-GENESIS/how-we-build.md`](../../../00-GENESIS/how-we-build.md) is the **source**. The +[`00-META/how-we-build.md`](../../../00-META/how-we-build.md) is the **source**. The knowledge base carries a **derived** page that the mesh injects into every eligible design session, and against which a check phase can block work. diff --git a/00-GENESIS/README.md b/00-META/README.md similarity index 87% rename from 00-GENESIS/README.md rename to 00-META/README.md index 518d1f6..5326627 100644 --- a/00-GENESIS/README.md +++ b/00-META/README.md @@ -1,4 +1,4 @@ -# 00-GENESIS +# 00-META The **northern star**. What HAL is, the environment it runs in, and what changes when it works. Every research effort and design decision is checked against this folder. @@ -26,7 +26,7 @@ works. Every research effort and design decision is checked against this folder. The code repository carries an architecture overview predating this folder. It is a useful description of *how* the mesh works, and its content now lives — anonymised and checked against -the implementation — in [`02-DESIGN/00-as-is/`](../02-DESIGN/00-as-is/). GENESIS answers *why*; +the implementation — in [`03-DESIGN/00-as-is/`](../03-DESIGN/00-as-is/). GENESIS answers *why*; that document answered *how*, which is the design layer's job. It had also drifted from the implementation in ways worth recording, since both were found by @@ -34,7 +34,7 @@ comparing it against the code rather than by anyone noticing: - It described the pipeline as having a separate builder process and a build stage that packages. Neither was true after 2026-08-04; the documents stayed stale until 2026-08-06 - ([ADR 0014](../adr/0014-build-publish-and-deploy-are-three-silos.md)). + ([ADR 0014](../02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md)). - It listed the mesh as spanning a fixed number of named machines, which is exactly the content this repository cannot carry. @@ -44,10 +44,10 @@ symlinks at all — the rule is not merely "only the installer may link", and a elevating linking to a principle points the opposite way from where this is going. What exists today is that the installer owns and reconciles every link -([ADR 0011](../adr/0011-the-installer-owns-linking.md)) — an as-is fact, recorded in -[`02-DESIGN/00-as-is/05-runtime-and-installation.md`](../02-DESIGN/00-as-is/05-runtime-and-installation.md). +([ADR 0011](../02-DECISIONS/0011-the-installer-owns-linking.md)) — an as-is fact, recorded in +[`03-DESIGN/00-as-is/05-runtime-and-installation.md`](../03-DESIGN/00-as-is/05-runtime-and-installation.md). Centralising who may link narrowed the incident class; it did not close it. The intent is to -remove the mechanism, recorded as [ADR 0018](../adr/0018-the-mesh-creates-no-symlinks.md). +remove the mechanism, recorded as [ADR 0018](../02-DECISIONS/0018-the-mesh-creates-no-symlinks.md). A founding document contradicting the direction of travel is precisely the failure this folder exists to prevent. diff --git a/00-GENESIS/context.md b/00-META/context.md similarity index 100% rename from 00-GENESIS/context.md rename to 00-META/context.md diff --git a/00-GENESIS/effect.md b/00-META/effect.md similarity index 100% rename from 00-GENESIS/effect.md rename to 00-META/effect.md diff --git a/00-GENESIS/how-we-build.md b/00-META/how-we-build.md similarity index 90% rename from 00-GENESIS/how-we-build.md rename to 00-META/how-we-build.md index c5defbc..4b5b8a2 100644 --- a/00-GENESIS/how-we-build.md +++ b/00-META/how-we-build.md @@ -3,7 +3,7 @@ status: canonical updated: 2026-08-23 derives: knowledge-base constitution page decisions: - - adr/0009-the-mesh-is-governed-by-a-constitution.md + - 02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md --- # How we build @@ -37,13 +37,13 @@ incident behind it is not written down, and the fix is to write it down, not to | Rule | What it means | |---|---| | **Never write to a production database directly** | No insert, update, delete or schema statement executed against production by hand. Schema changes go through numbered migrations; data changes go through application code or the module's own capabilities. Raw statements skip every side effect the proper path has — events, audit, cache invalidation, fan-out. | -| **Every schema change is a migration** | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation *and* an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. [ADR 0006](../adr/0006-schema-changes-are-numbered-migrations.md) | +| **Every schema change is a migration** | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation *and* an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. [ADR 0006](../02-DECISIONS/0006-schema-changes-are-numbered-migrations.md) | | **Never bypass the pipeline** | No manual database edit, no manual restart as a workaround. Fix the cause and deploy. A workaround that works is a workaround that is never removed, and the next person cannot tell the node from its declaration. | -| **Never create a symlink** | A hand-made link caused production data loss through container volume resolution, and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. Today the installer owns and reconciles the links the mesh still uses [ADR 0011](../adr/0011-the-installer-owns-linking.md); the intent is that the mesh creates none at all [ADR 0018](../adr/0018-the-mesh-creates-no-symlinks.md). Neither reading permits you to make one. | +| **Never create a symlink** | A hand-made link caused production data loss through container volume resolution, and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. Today the installer owns and reconciles the links the mesh still uses [ADR 0011](../02-DECISIONS/0011-the-installer-owns-linking.md); the intent is that the mesh creates none at all [ADR 0018](../02-DECISIONS/0018-the-mesh-creates-no-symlinks.md). Neither reading permits you to make one. | | **Never push directly to the main branch** | Branch, push, review, merge. Every merge is a human checkpoint, without exception. | | **One change per pull request, and never merge your own** | Unrelated improvements bundled together cannot be reviewed or reverted separately. Self-merging removes the checkpoint that is the entire point. | | **Never open a pull request unprompted** | A permissions list saying it is allowed is not a request. | -| **A failed step fails the job** | A sequence that continues past a failure does the next thing in the wrong place. Gate each step on the last. [ADR 0008](../adr/0008-a-failed-step-fails-the-job.md), and §5. | +| **A failed step fails the job** | A sequence that continues past a failure does the next thing in the wrong place. Gate each step on the last. [ADR 0008](../02-DECISIONS/0008-a-failed-step-fails-the-job.md), and §5. | ### A failed step must stop the steps after it — how it was earned @@ -69,7 +69,7 @@ reported failure, nothing stopped, and the damage happened somewhere nobody was - **Every runtime variable is declared.** A variable the module reads and the manifest does not declare is invisible to the mesh: it will not be generated, injected, or audited. - **Provisioned credentials arrive through declared requirements**, never hardcoded in code, - compose files or scripts. [ADR 0005](../adr/0005-capabilities-are-provisioned-on-declaration.md) + compose files or scripts. [ADR 0005](../02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md) ### Placement @@ -78,7 +78,7 @@ reported failure, nothing stopped, and the damage happened somewhere nobody was - **Every standalone application gets its own repository**, with a manifest at its root, registered as a build source. Creating an application directory in the monorepo is a convention violation and reviewers reject it. - [ADR 0010](../adr/0010-applications-live-in-their-own-repository.md) + [ADR 0010](../02-DECISIONS/0010-applications-live-in-their-own-repository.md) ### Migrations @@ -92,7 +92,7 @@ reported failure, nothing stopped, and the damage happened somewhere nobody was surface is regenerated from the mesh database; a local edit survives one synchronisation and is then silently overwritten, bringing back whatever it fixed. Use the mesh operation that owns the value. If unsure whether a file is managed, ask the tooling — the answer is not visible -from the file. [ADR 0004](../adr/0004-managed-files-are-generated-never-edited.md) +from the file. [ADR 0004](../02-DECISIONS/0004-managed-files-are-generated-never-edited.md) --- @@ -115,7 +115,7 @@ Anatomy makes attractive names and poor boundaries. Name the thing the domain ca A module is a purpose, not a piece of software. Four modules that together constitute "how a node is reachable" and cannot be assigned, versioned or replaced as one thing are four accidents, not four boundaries. -[ADR 0017](../adr/0017-modules-outside-the-core-are-grouped-by-domain.md) +[ADR 0017](../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md) ### Contexts integrate through the record, never through a shared schema @@ -167,7 +167,7 @@ This document is governed. It does not change by commit message or unilateral de 1. **Propose** — a change stating what rule is changing, why the current wording is inadequate, and what reviewed it. 2. **Review** — sign-off by reviewers who are not the proposer. -3. **Record** — the change is a decision and gets a record in [`adr/`](../adr/), because a +3. **Record** — the change is a decision and gets a record in [`02-DECISIONS/`](../02-DECISIONS/), because a rule the mesh enforces is architecturally significant. 4. **Sync** — playbook [`process/05-constitution-sync.md`](process/05-constitution-sync.md) publishes the derived page. An unsynced rule is a rule the mesh does not enforce, whatever diff --git a/00-GENESIS/mission.md b/00-META/mission.md similarity index 100% rename from 00-GENESIS/mission.md rename to 00-META/mission.md diff --git a/00-GENESIS/process/00-overview.md b/00-META/process/00-overview.md similarity index 90% rename from 00-GENESIS/process/00-overview.md rename to 00-META/process/00-overview.md index e32c4fc..157865b 100644 --- a/00-GENESIS/process/00-overview.md +++ b/00-META/process/00-overview.md @@ -15,11 +15,11 @@ playbooks; agents must not act outside them. ## The knowledge flow ``` -idea ──► 01-RESEARCH ──► decision (adr/) ──► 02-DESIGN/01-to-be ──► built (code repo) +idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo) │ │ │ - │ │ └─► 02-DESIGN/00-as-is once shipped + │ │ └─► 03-DESIGN/00-as-is once shipped │ └────► abandoned (recorded, kept) - └─(small/obvious, decision recorded in DECISIONS.md)────► 02-DESIGN directly + └─(small/obvious, decision recorded in DECISIONS.md)────► 03-DESIGN directly symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment @@ -28,12 +28,12 @@ how-we-build.md ──► constitution sync ──► knowledge base ──► i ## The two design layers -`02-DESIGN` holds two layers that are never mixed: +`03-DESIGN` holds two layers that are never mixed: | Layer | What it is | Changes when | |---|---|---| | `00-as-is/` | The mesh that exists today. Describes shipped behaviour, including behaviour nobody would choose again. | Something ships, or an as-is claim is found to be wrong. | -| `01-to-be/` | The mesh being built toward. Every statement traceable to a record in `adr/`. | A decision is taken or amended. | +| `01-to-be/` | The mesh being built toward. Every statement traceable to a record in `02-DECISIONS/`. | A decision is taken or amended. | A to-be document that ships does not move. Its as-is counterpart is written or updated, the to-be document's frontmatter goes to `implemented`, and both stand — one describing what runs, diff --git a/00-GENESIS/process/01-research.md b/00-META/process/01-research.md similarity index 97% rename from 00-GENESIS/process/01-research.md rename to 00-META/process/01-research.md index bfb33ad..0241f43 100644 --- a/00-GENESIS/process/01-research.md +++ b/00-META/process/01-research.md @@ -39,7 +39,7 @@ carries the whole lesson without naming anything. - Do not put status in prose. It lives in `00-overview.md`'s frontmatter, and the prose must not restate it. - Do not set `became:` while the effort is open — playbook 02 sets it at closure. -- Do not write into `02-DESIGN` from an open effort. +- Do not write into `03-DESIGN` from an open effort. ## Closing diff --git a/00-GENESIS/process/02-graduation.md b/00-META/process/02-graduation.md similarity index 82% rename from 00-GENESIS/process/02-graduation.md rename to 00-META/process/02-graduation.md index 62013e8..a29653a 100644 --- a/00-GENESIS/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -10,10 +10,10 @@ [`mission.md`](../mission.md), [`context.md`](../context.md) and [`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is — say which, in writing, before proceeding. -2. **Record the decision.** Write a record in [`adr/`](../../adr/) taking the next free - number. Format and rules are in [`adr/README.md`](../../adr/README.md). State evidence, +2. **Record the decision.** Write a record in [`02-DECISIONS/`](../../02-DECISIONS/) taking the next free + number. Format and rules are in [`02-DECISIONS/README.md`](../../02-DECISIONS/README.md). State evidence, not assertion, and record the options that were rejected — that is the half worth keeping. -3. **Write the design.** Create the document under `02-DESIGN/01-to-be/` with frontmatter: +3. **Write the design.** Create the document under `03-DESIGN/01-to-be/` with frontmatter: ```yaml --- @@ -21,7 +21,7 @@ status: designed code: [] # owning code repo(s); set at build handoff, empty before updated: YYYY-MM-DD - decisions: [adr/NNNN-....md] + decisions: [02-DECISIONS/NNNN-....md] --- ``` @@ -35,7 +35,7 @@ A design changes only through a decision. 1. Write the decision record. If it reverses an earlier one, the earlier record's `status:` - becomes `superseded-by: adr/NNNN-....md` — **its text is never edited**. + becomes `superseded-by: 02-DECISIONS/NNNN-....md` — **its text is never edited**. 2. Edit the to-be design document and set `updated:` to today. 3. If the amendment came from an issue, set that issue's `amended-design:` to the document path. @@ -45,7 +45,7 @@ A design changes only through a decision. Implementation state is a third axis, independent of both design and decision. -1. Write or update the matching document under `02-DESIGN/00-as-is/` so it describes what now +1. Write or update the matching document under `03-DESIGN/00-as-is/` so it describes what now runs — including anything that shipped differently from the intent. A design that shipped bent is an as-is fact, not a design amendment. 2. Set the to-be document's `status: implemented` and its `code:` to the owning repositories diff --git a/00-GENESIS/process/03-issues.md b/00-META/process/03-issues.md similarity index 100% rename from 00-GENESIS/process/03-issues.md rename to 00-META/process/03-issues.md diff --git a/00-GENESIS/process/04-build-handoff.md b/00-META/process/04-build-handoff.md similarity index 88% rename from 00-GENESIS/process/04-build-handoff.md rename to 00-META/process/04-build-handoff.md index 9bc645c..5c3b84f 100644 --- a/00-GENESIS/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -7,12 +7,12 @@ ## Steps 1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every - claim in it traces to a record in [`adr/`](../../adr/). An open question in the text is a + claim in it traces to a record in [`02-DECISIONS/`](../../02-DECISIONS/). An open question in the text is a reason to run playbook [01](01-research.md), not to start building around it. 2. **Name the owner.** Set `code:` in the design's frontmatter to the repositories from [`repos.md`](../repos.md). If the repository does not exist yet, add it to `repos.md` in the same change. -3. **Check the as-is.** Read the matching `02-DESIGN/00-as-is/` document. What is being +3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being replaced is stated there; if it is not, write it before changing it. Building against an undocumented as-is is how a shipped behaviour gets lost. 4. **Flip the status.** `status: in-progress`, `updated:` today. diff --git a/00-GENESIS/process/05-constitution-sync.md b/00-META/process/05-constitution-sync.md similarity index 100% rename from 00-GENESIS/process/05-constitution-sync.md rename to 00-META/process/05-constitution-sync.md diff --git a/00-GENESIS/repos.md b/00-META/repos.md similarity index 91% rename from 00-GENESIS/repos.md rename to 00-META/repos.md index 8b09b86..c221e87 100644 --- a/00-GENESIS/repos.md +++ b/00-META/repos.md @@ -21,7 +21,7 @@ and a forge address is an operational detail (see [`README`](../README.md)). ## What lives where inside the monorepo Named by role, because the layout is itself part of the as-is design — see -[`02-DESIGN/00-as-is/`](../02-DESIGN/00-as-is/). +[`03-DESIGN/00-as-is/`](../03-DESIGN/00-as-is/). | Area | Holds | |---|---| @@ -34,7 +34,7 @@ Named by role, because the layout is itself part of the as-is design — see ## Why applications do not live in the monorepo A standalone application in the monorepo is a convention violation, and reviewers reject it. -The reasoning is recorded in [`adr/0010`](../adr/0010-applications-live-in-their-own-repository.md): +The reasoning is recorded in [`02-DECISIONS/0010`](../02-DECISIONS/0010-applications-live-in-their-own-repository.md): the mesh installs, provisions for, and ships an application through exactly the same machinery whether or not its source sits beside the mesh's own — so co-location buys nothing and costs the monorepo's review cadence. @@ -45,7 +45,7 @@ Each module is a standalone package that consumes its dependencies from the priv not from a sibling directory. The workspace was removed after it caused build-versus-development divergence — a workspace member importing another resolved to local unbuilt source in the pipeline and to a published version in development. Recorded in -[`adr/0007`](../adr/0007-no-npm-workspace.md). +[`02-DECISIONS/0007`](../02-DECISIONS/0007-no-npm-workspace.md). Consequence, and it is a real one: a cross-package change is two steps — publish, then consume — and a repository-wide `npm install` does not exist. diff --git a/01-RESEARCH/001-module-domain-decomposition/00-overview.md b/01-RESEARCH/001-module-domain-decomposition/00-overview.md index 2ba8f4b..dab3be4 100644 --- a/01-RESEARCH/001-module-domain-decomposition/00-overview.md +++ b/01-RESEARCH/001-module-domain-decomposition/00-overview.md @@ -1,8 +1,8 @@ --- status: active initiated: 2026-08-22 -touches: [02-DESIGN/00-as-is/02-modules-and-manifests.md, 02-DESIGN/00-as-is/10-module-catalogue.md, 02-DESIGN/01-to-be/00-work-breakdown.md] -became: [adr/0015-mesh-brokers-nodes-host-agents-think.md] +touches: [03-DESIGN/00-as-is/02-modules-and-manifests.md, 03-DESIGN/00-as-is/10-module-catalogue.md, 03-DESIGN/01-to-be/00-work-breakdown.md] +became: [02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md] --- # 001 — Module domain decomposition diff --git a/01-RESEARCH/002-local-mesh/00-overview.md b/01-RESEARCH/002-local-mesh/00-overview.md index 1aeeea5..b0d5da5 100644 --- a/01-RESEARCH/002-local-mesh/00-overview.md +++ b/01-RESEARCH/002-local-mesh/00-overview.md @@ -1,8 +1,8 @@ --- status: graduated initiated: 2026-08-22 -touches: [02-DESIGN/00-as-is/04-delivery.md, 02-DESIGN/00-as-is/05-runtime-and-installation.md] -became: [02-DESIGN/01-to-be/01-end-to-end-testing.md, adr/0016-a-lab-node-is-a-virtual-machine.md] +touches: [03-DESIGN/00-as-is/04-delivery.md, 03-DESIGN/00-as-is/05-runtime-and-installation.md] +became: [03-DESIGN/01-to-be/01-end-to-end-testing.md, 02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md] --- # 002 — A mesh that runs locally @@ -15,7 +15,7 @@ became: [02-DESIGN/01-to-be/01-end-to-end-testing.md, adr/0016-a-lab-node-is-a-v ## Summary -Phase 0 of [`02-DESIGN/00-work-breakdown.md`](../../02-DESIGN/01-to-be/00-work-breakdown.md) requires +Phase 0 of [`03-DESIGN/00-work-breakdown.md`](../../03-DESIGN/01-to-be/00-work-breakdown.md) requires a mesh that comes up in containers, runs its own pipeline, and reproduces known faults on demand. Nothing else in the decomposition starts until it exists, because every fault the decomposition addresses was found in production — there was nowhere else to find it. diff --git a/01-RESEARCH/002-local-mesh/analysis.md b/01-RESEARCH/002-local-mesh/analysis.md index ea7a5b8..785df6e 100644 --- a/01-RESEARCH/002-local-mesh/analysis.md +++ b/01-RESEARCH/002-local-mesh/analysis.md @@ -244,7 +244,7 @@ over either way. 3. **How faithful must the local mesh be to be trusted?** It will not run the bootstrap scripts, and it will run one OS where the real mesh is heterogeneous by design - (`00-GENESIS/context.md`). Stating the divergence up front is what stops "it works + (`00-META/context.md`). Stating the divergence up front is what stops "it works locally" from becoming its own class of silent failure. Now sharper, because a development environment people use daily is trusted far more than a rig — and drifting from production costs correspondingly more. @@ -253,9 +253,9 @@ over either way. ## References -- [`adr/0001`](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) — the decision this +- [`02-DECISIONS/0001`](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) — the decision this phase unblocks -- [`02-DESIGN/00-work-breakdown.md`](../../02-DESIGN/01-to-be/00-work-breakdown.md) — Phase 0 tasks +- [`03-DESIGN/00-work-breakdown.md`](../../03-DESIGN/01-to-be/00-work-breakdown.md) — Phase 0 tasks and checkpoint - `troubleshooting/provision-adoption-rotates-live-credential` — fixture B, root cause open - `troubleshooting/deploy-reports-transport-not-effect` — the nine defects that shipped diff --git a/01-RESEARCH/003-service-supervision/00-overview.md b/01-RESEARCH/003-service-supervision/00-overview.md index 395815e..4736fc6 100644 --- a/01-RESEARCH/003-service-supervision/00-overview.md +++ b/01-RESEARCH/003-service-supervision/00-overview.md @@ -1,7 +1,7 @@ --- status: active initiated: 2026-08-22 -touches: [02-DESIGN/00-as-is/05-runtime-and-installation.md] +touches: [03-DESIGN/00-as-is/05-runtime-and-installation.md] became: [] --- diff --git a/01-RESEARCH/003-service-supervision/analysis.md b/01-RESEARCH/003-service-supervision/analysis.md index 25cb8eb..b4dc117 100644 --- a/01-RESEARCH/003-service-supervision/analysis.md +++ b/01-RESEARCH/003-service-supervision/analysis.md @@ -196,7 +196,7 @@ hand. This is worth recording for two reasons. It weakens any argument that systemd-adjacent self-healing is already wired — it is not. And it is another instance of the pattern this whole refactor is about: **a documented mechanism that does not exist, believed because it -was written down.** `00-GENESIS/how-we-build.md` calls this out as a rule; here it is again, +was written down.** `00-META/how-we-build.md` calls this out as a rule; here it is again, found by grep. --- @@ -208,7 +208,7 @@ found by grep. **This no longer gates Phase 0.** When this was written, the local mesh was assumed to be built from application containers, which forced the question — there is no natural way to run an init system inside one. The decision of 2026-08-22 to build development nodes as -**system containers** (see [`02-DESIGN/01-end-to-end-testing.md`](../../02-DESIGN/01-to-be/01-end-to-end-testing.md)) +**system containers** (see [`03-DESIGN/01-end-to-end-testing.md`](../../03-DESIGN/01-to-be/01-end-to-end-testing.md)) removes that pressure entirely: a system container runs a real init, so the existing model works unmodified and the lab needs no answer here to exist. @@ -223,7 +223,7 @@ fate-sharing reason in §3. ## References - [`002-local-mesh`](../002-local-mesh/analysis.md) — the effort this came out of -- [`adr/0001`](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) — agent modality, which +- [`02-DECISIONS/0001`](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) — agent modality, which decides what cannot leave the host - `modules/hal/meshware/daemon/src/cerebellum.ts:815-828` — the self-restart workaround - `modules/hal/meshware/systemd/hal-module@.service` — the per-module Docker lifecycle diff --git a/01-RESEARCH/004-lab-network/00-overview.md b/01-RESEARCH/004-lab-network/00-overview.md index 26d8169..c5cd1d0 100644 --- a/01-RESEARCH/004-lab-network/00-overview.md +++ b/01-RESEARCH/004-lab-network/00-overview.md @@ -1,8 +1,8 @@ --- status: active initiated: 2026-08-22 -touches: [02-DESIGN/00-as-is/01-mesh-and-transport.md, 02-DESIGN/01-to-be/01-end-to-end-testing.md] -became: [adr/0016-a-lab-node-is-a-virtual-machine.md] +touches: [03-DESIGN/00-as-is/01-mesh-and-transport.md, 03-DESIGN/01-to-be/01-end-to-end-testing.md] +became: [02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md] --- # 004 — Reproducing the mesh network in a lab diff --git a/01-RESEARCH/004-lab-network/analysis.md b/01-RESEARCH/004-lab-network/analysis.md index 205b155..5fc3027 100644 --- a/01-RESEARCH/004-lab-network/analysis.md +++ b/01-RESEARCH/004-lab-network/analysis.md @@ -199,5 +199,5 @@ Several manifests declare `scope: public` on firewall rules — `wireguard`, `tr `modules/unifi/module.yml:52-93` does deliberately. So a manifest can appear to restrict a port to the public scope and in fact restrict nothing. -This is the same shape as the rule in `00-GENESIS/how-we-build.md` — *an unenforced rule is +This is the same shape as the rule in `00-META/how-we-build.md` — *an unenforced rule is indistinguishable from a wrong one, and costs more, because people believe it.* diff --git a/01-RESEARCH/README.md b/01-RESEARCH/README.md index 11adf98..0f82c9b 100644 --- a/01-RESEARCH/README.md +++ b/01-RESEARCH/README.md @@ -27,16 +27,16 @@ draft designs. | status | Meaning | |---|---| | `active` | Investigation in progress. | -| `graduated` | Checked against `00-GENESIS`, decided in `adr/`, and specified in `02-DESIGN` — see `became:`. | +| `graduated` | Checked against `00-META`, decided in `02-DECISIONS/`, and specified in `03-DESIGN` — see `became:`. | | `abandoned` | Stopped or superseded. Nothing is deleted. | -An effort graduates by producing a decision record **and** a `02-DESIGN` entry. It is abandoned +An effort graduates by producing a decision record **and** a `03-DESIGN` entry. It is abandoned in place — never deleted. What was rejected, and why, is the more expensive half to rediscover. Starting and closing efforts is playbook territory: -[`00-GENESIS/process/01-research.md`](../00-GENESIS/process/01-research.md) and -[`02-graduation.md`](../00-GENESIS/process/02-graduation.md). +[`00-META/process/01-research.md`](../00-META/process/01-research.md) and +[`02-graduation.md`](../00-META/process/02-graduation.md). ## Rules diff --git a/adr/0001-nodes-communicate-over-a-broker.md b/02-DECISIONS/0001-nodes-communicate-over-a-broker.md similarity index 100% rename from adr/0001-nodes-communicate-over-a-broker.md rename to 02-DECISIONS/0001-nodes-communicate-over-a-broker.md diff --git a/adr/0002-everything-is-a-module.md b/02-DECISIONS/0002-everything-is-a-module.md similarity index 100% rename from adr/0002-everything-is-a-module.md rename to 02-DECISIONS/0002-everything-is-a-module.md diff --git a/adr/0003-the-mesh-database-is-the-source-of-truth.md b/02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md similarity index 100% rename from adr/0003-the-mesh-database-is-the-source-of-truth.md rename to 02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md diff --git a/adr/0004-managed-files-are-generated-never-edited.md b/02-DECISIONS/0004-managed-files-are-generated-never-edited.md similarity index 100% rename from adr/0004-managed-files-are-generated-never-edited.md rename to 02-DECISIONS/0004-managed-files-are-generated-never-edited.md diff --git a/adr/0005-capabilities-are-provisioned-on-declaration.md b/02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md similarity index 100% rename from adr/0005-capabilities-are-provisioned-on-declaration.md rename to 02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md diff --git a/adr/0006-schema-changes-are-numbered-migrations.md b/02-DECISIONS/0006-schema-changes-are-numbered-migrations.md similarity index 100% rename from adr/0006-schema-changes-are-numbered-migrations.md rename to 02-DECISIONS/0006-schema-changes-are-numbered-migrations.md diff --git a/adr/0007-no-npm-workspace.md b/02-DECISIONS/0007-no-npm-workspace.md similarity index 100% rename from adr/0007-no-npm-workspace.md rename to 02-DECISIONS/0007-no-npm-workspace.md diff --git a/adr/0008-a-failed-step-fails-the-job.md b/02-DECISIONS/0008-a-failed-step-fails-the-job.md similarity index 97% rename from adr/0008-a-failed-step-fails-the-job.md rename to 02-DECISIONS/0008-a-failed-step-fails-the-job.md index ef35502..7f5b006 100644 --- a/adr/0008-a-failed-step-fails-the-job.md +++ b/02-DECISIONS/0008-a-failed-step-fails-the-job.md @@ -67,5 +67,5 @@ Concretely, and these are the forms it takes: `troubleshooting/service-started-is-not-ready`, `troubleshooting/green-pipeline-means-transport-not-effect`, `troubleshooting/silent-failures-and-stale-state`. -- The core value it became: [`00-GENESIS/mission.md`](../00-GENESIS/mission.md), "Failure must +- The core value it became: [`00-META/mission.md`](../00-META/mission.md), "Failure must be loud." diff --git a/adr/0009-the-mesh-is-governed-by-a-constitution.md b/02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md similarity index 94% rename from adr/0009-the-mesh-is-governed-by-a-constitution.md rename to 02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md index 29897a6..0088030 100644 --- a/adr/0009-the-mesh-is-governed-by-a-constitution.md +++ b/02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md @@ -47,9 +47,9 @@ Scoped override pages may **tighten** it for a team or product. They may never r - The check phase makes a violation a blocking outcome rather than a review comment. - Two copies of the same rules now exist: this document, and the reasoning in HQ that earned them. The enforced copy wins by default, so the reasoned copy quietly stops being true — - which is why [`00-GENESIS/how-we-build.md`](../00-GENESIS/how-we-build.md) is now the source + which is why [`00-META/how-we-build.md`](../00-META/how-we-build.md) is now the source and the governed page is derived from it, via playbook - [`05-constitution-sync.md`](../00-GENESIS/process/05-constitution-sync.md). + [`05-constitution-sync.md`](../00-META/process/05-constitution-sync.md). - Injection costs context on every eligible turn, and grows with the document. Nothing currently bounds that. - The amendment process requires two reviewers, which a mesh with one human operator satisfies diff --git a/adr/0010-applications-live-in-their-own-repository.md b/02-DECISIONS/0010-applications-live-in-their-own-repository.md similarity index 100% rename from adr/0010-applications-live-in-their-own-repository.md rename to 02-DECISIONS/0010-applications-live-in-their-own-repository.md diff --git a/adr/0011-the-installer-owns-linking.md b/02-DECISIONS/0011-the-installer-owns-linking.md similarity index 100% rename from adr/0011-the-installer-owns-linking.md rename to 02-DECISIONS/0011-the-installer-owns-linking.md diff --git a/adr/0012-agents-are-persistent-employees.md b/02-DECISIONS/0012-agents-are-persistent-employees.md similarity index 100% rename from adr/0012-agents-are-persistent-employees.md rename to 02-DECISIONS/0012-agents-are-persistent-employees.md diff --git a/adr/0013-an-artifact-is-build-output.md b/02-DECISIONS/0013-an-artifact-is-build-output.md similarity index 100% rename from adr/0013-an-artifact-is-build-output.md rename to 02-DECISIONS/0013-an-artifact-is-build-output.md diff --git a/adr/0014-build-publish-and-deploy-are-three-silos.md b/02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md similarity index 100% rename from adr/0014-build-publish-and-deploy-are-three-silos.md rename to 02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md diff --git a/adr/0015-mesh-brokers-nodes-host-agents-think.md b/02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md similarity index 99% rename from adr/0015-mesh-brokers-nodes-host-agents-think.md rename to 02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md index fbd290c..3ad2729 100644 --- a/adr/0015-mesh-brokers-nodes-host-agents-think.md +++ b/02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md @@ -178,7 +178,7 @@ existing pipeline. Nothing here requires a flag day, and nothing here is cheap. - [`01-RESEARCH/001-module-domain-decomposition`](../01-RESEARCH/001-module-domain-decomposition/analysis.md) — current-state evidence, table counts, open questions -- [`00-GENESIS/how-we-build.md`](../00-GENESIS/how-we-build.md) — naming and integration rules +- [`00-META/how-we-build.md`](../00-META/how-we-build.md) — naming and integration rules - `modules/hal/sdk/src/feature-handlers/index.ts` — `FEATURE_HANDLERS`, the fixed handler array that makes a feature a singleton per module - `modules/postgres/tools/index.ts` — the adoption path that rotates a shared credential diff --git a/adr/0016-a-lab-node-is-a-virtual-machine.md b/02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md similarity index 99% rename from adr/0016-a-lab-node-is-a-virtual-machine.md rename to 02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md index 08db4be..9288c29 100644 --- a/adr/0016-a-lab-node-is-a-virtual-machine.md +++ b/02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md @@ -131,7 +131,7 @@ than staging means every certificate experiment on a real node consumes issuance the four host couplings that only obstruct a container-shaped node - [`01-RESEARCH/004-lab-network`](../01-RESEARCH/004-lab-network/analysis.md) — the topology being reproduced and the endpoint constraint -- [`02-DESIGN/01-end-to-end-testing.md`](../02-DESIGN/01-to-be/01-end-to-end-testing.md) — what the lab +- [`03-DESIGN/01-end-to-end-testing.md`](../03-DESIGN/01-to-be/01-end-to-end-testing.md) — what the lab is for - `modules/wireguard/hooks/index.ts:206-240` — the endpoint rule, and the incident comments recording what it cost to get right diff --git a/adr/0017-modules-outside-the-core-are-grouped-by-domain.md b/02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md similarity index 98% rename from adr/0017-modules-outside-the-core-are-grouped-by-domain.md rename to 02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md index 8598e11..ba9578d 100644 --- a/adr/0017-modules-outside-the-core-are-grouped-by-domain.md +++ b/02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md @@ -89,5 +89,5 @@ ADR stays `proposed`. extends, and its rule about naming a context after its aggregate. - [ADR 0010](0010-applications-live-in-their-own-repository.md) — standalone applications are already out of scope here; they are not domains and do not group. -- [`02-DESIGN/00-as-is/10-module-catalogue.md`](../02-DESIGN/00-as-is/10-module-catalogue.md) +- [`03-DESIGN/00-as-is/10-module-catalogue.md`](../03-DESIGN/00-as-is/10-module-catalogue.md) — the catalogue's current shape, which is the evidence for the problem. diff --git a/adr/0018-the-mesh-creates-no-symlinks.md b/02-DECISIONS/0018-the-mesh-creates-no-symlinks.md similarity index 98% rename from adr/0018-the-mesh-creates-no-symlinks.md rename to 02-DECISIONS/0018-the-mesh-creates-no-symlinks.md index 2fc0909..efa9a43 100644 --- a/adr/0018-the-mesh-creates-no-symlinks.md +++ b/02-DECISIONS/0018-the-mesh-creates-no-symlinks.md @@ -97,5 +97,5 @@ Until those are answered this record stays `proposed`, and ADR 0011 remains the - [ADR 0011](0011-the-installer-owns-linking.md) — the incident, and the rule this widens. - [ADR 0004](0004-managed-files-are-generated-never-edited.md) — the machinery that makes a copy safe. -- [`02-DESIGN/00-as-is/05-runtime-and-installation.md`](../02-DESIGN/00-as-is/05-runtime-and-installation.md) +- [`03-DESIGN/00-as-is/05-runtime-and-installation.md`](../03-DESIGN/00-as-is/05-runtime-and-installation.md) — what the installer does today, including reconciliation and adoption. diff --git a/adr/README.md b/02-DECISIONS/README.md similarity index 77% rename from adr/README.md rename to 02-DECISIONS/README.md index 441d744..f8fade6 100644 --- a/adr/README.md +++ b/02-DECISIONS/README.md @@ -1,4 +1,11 @@ -# Architecture Decision Records +# 02-DECISIONS + +Architecture decision records — the "why" trail behind the rules in +[`00-META`](../00-META/) and the specifications in [`03-DESIGN`](../03-DESIGN/). + +**Numbered `02` because a decision precedes the design it authorises.** Research concludes, +the decision is recorded here, and only then is the design written. Following the folder +numbers walks the process in the order it happens. One file per decision, numbered, never deleted. A superseded record has its `status:` changed and gains a pointer to what replaced it — **its text is never edited**. The reasoning that was @@ -14,8 +21,8 @@ status: proposed | accepted | superseded date: YYYY-MM-DD # when the decision was taken, not when it was written down deciders: name reconstructed: true|false # true when the record was written after the fact from evidence -superseded-by: # adr/NNNN-....md, when status is superseded -extends: # adr/NNNN-....md, when this record widens an earlier one +superseded-by: # 02-DECISIONS/NNNN-....md, when status is superseded +extends: # 02-DECISIONS/NNNN-....md, when this record widens an earlier one --- ``` diff --git a/02-DESIGN/00-as-is/00-overview.md b/03-DESIGN/00-as-is/00-overview.md similarity index 81% rename from 02-DESIGN/00-as-is/00-overview.md rename to 03-DESIGN/00-as-is/00-overview.md index 9727a87..c1d6a0d 100644 --- a/02-DESIGN/00-as-is/00-overview.md +++ b/03-DESIGN/00-as-is/00-overview.md @@ -4,9 +4,9 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0001-nodes-communicate-over-a-broker.md - - adr/0002-everything-is-a-module.md - - adr/0003-the-mesh-database-is-the-source-of-truth.md + - 02-DECISIONS/0001-nodes-communicate-over-a-broker.md + - 02-DECISIONS/0002-everything-is-a-module.md + - 02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md --- # The mesh as it stands @@ -28,11 +28,11 @@ onto it and can be regenerated. containerised service is a module. A set of capabilities with no service behind them is a module. A bare marker whose whole content is that a node has it is a module. The mesh's own components are modules on exactly the same terms as everything else it carries -([ADR 0002](../../adr/0002-everything-is-a-module.md)). +([ADR 0002](../../02-DECISIONS/0002-everything-is-a-module.md)). **An agent** is a participant. Some agents are human. What differs is modality — how the agent acts — and not category: both hold identity, both act, both accumulate memory -([ADR 0012](../../adr/0012-agents-are-persistent-employees.md)). +([ADR 0012](../../02-DECISIONS/0012-agents-are-persistent-employees.md)). ## Where truth lives @@ -40,10 +40,10 @@ The repository defines **what exists**: the modules, what each declares, how eac The mesh database defines **what runs where**: which node is assigned which module, at which selection, with which overrides, plus the settings every node reads. No node-to-module mapping -is ever committed ([ADR 0003](../../adr/0003-the-mesh-database-is-the-source-of-truth.md)). +is ever committed ([ADR 0003](../../02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md)). Everything on a node's disk is **derived** from those two, and is regenerated rather than -edited ([ADR 0004](../../adr/0004-managed-files-are-generated-never-edited.md)). A node that +edited ([ADR 0004](../../02-DECISIONS/0004-managed-files-are-generated-never-edited.md)). A node that loses its database keeps running from a local cache, which is deliberate and has the obvious cost: the cache carries no indication of its own age. @@ -51,7 +51,7 @@ cost: the cache carries no indication of its own age. Nothing dials a node. Every node dials the broker outbound, owns an exchange named for itself, and consumes from its own request queue -([ADR 0001](../../adr/0001-nodes-communicate-over-a-broker.md)). Three message shapes carry +([ADR 0001](../../02-DECISIONS/0001-nodes-communicate-over-a-broker.md)). Three message shapes carry everything: requests expecting a reply, commands instructing that a stage of work be done, and events stating that something happened. @@ -65,9 +65,9 @@ goes to where the capability is. A push to the forge is the only trigger. What follows is three silos with deliberately different cardinality: compile once, package and upload once, then install-configure-start- verify **on every assigned node** -([ADR 0014](../../adr/0014-build-publish-and-deploy-are-three-silos.md)). What travels between +([ADR 0014](../../02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md)). What travels between build and node is a self-contained build output, so a deploy is extract-and-run and touches no -network ([ADR 0013](../../adr/0013-an-artifact-is-build-output.md)). +network ([ADR 0013](../../02-DECISIONS/0013-an-artifact-is-build-output.md)). Modules are resolved into dependency levels and a level completes before the next begins, so a module always builds against its dependencies as they were just published. @@ -78,7 +78,7 @@ A module declares what it **provides** and what it **requires**. The mesh satisf requirement: it creates the resource, generates the credential, records the grant, and writes the values where the module will read them. The module never learns which node its database lives on, and nobody ever writes a credential by hand -([ADR 0005](../../adr/0005-capabilities-are-provisioned-on-declaration.md)). +([ADR 0005](../../02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md)). This is the property the mesh's whole shape rests on, and it is why provisioning is treated as a core concern rather than as plumbing. @@ -92,7 +92,7 @@ named for a feature the module does not declare, a stage that reported it had di message rather than that the effect happened, a package that 404ed from every mirror while the job went green. -[ADR 0008](../../adr/0008-a-failed-step-fails-the-job.md) is the response, and it is applied +[ADR 0008](../../02-DECISIONS/0008-a-failed-step-fails-the-job.md) is the response, and it is applied instance by instance rather than enforced by a mechanism. New instances are still being found. That is an as-is fact, not a criticism: it is the single most useful thing to know about this system before changing it. diff --git a/02-DESIGN/00-as-is/01-mesh-and-transport.md b/03-DESIGN/00-as-is/01-mesh-and-transport.md similarity index 97% rename from 02-DESIGN/00-as-is/01-mesh-and-transport.md rename to 03-DESIGN/00-as-is/01-mesh-and-transport.md index 4b3cd4e..7416575 100644 --- a/02-DESIGN/00-as-is/01-mesh-and-transport.md +++ b/03-DESIGN/00-as-is/01-mesh-and-transport.md @@ -4,8 +4,8 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0001-nodes-communicate-over-a-broker.md - - adr/0003-the-mesh-database-is-the-source-of-truth.md + - 02-DECISIONS/0001-nodes-communicate-over-a-broker.md + - 02-DECISIONS/0003-the-mesh-database-is-the-source-of-truth.md --- # The mesh and its transport diff --git a/02-DESIGN/00-as-is/02-modules-and-manifests.md b/03-DESIGN/00-as-is/02-modules-and-manifests.md similarity index 94% rename from 02-DESIGN/00-as-is/02-modules-and-manifests.md rename to 03-DESIGN/00-as-is/02-modules-and-manifests.md index 031d470..4cc8875 100644 --- a/02-DESIGN/00-as-is/02-modules-and-manifests.md +++ b/03-DESIGN/00-as-is/02-modules-and-manifests.md @@ -4,9 +4,9 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0002-everything-is-a-module.md - - adr/0006-schema-changes-are-numbered-migrations.md - - adr/0007-no-npm-workspace.md + - 02-DECISIONS/0002-everything-is-a-module.md + - 02-DECISIONS/0006-schema-changes-are-numbered-migrations.md + - 02-DECISIONS/0007-no-npm-workspace.md --- # Modules, manifests and features @@ -81,7 +81,7 @@ recorded in the knowledge base; both presented as "the change did not apply" wit ## Dependencies between modules Modules depend on each other, above all on the shared library they all build against. There is -**no workspace** ([ADR 0007](../../adr/0007-no-npm-workspace.md)): each module is a standalone +**no workspace** ([ADR 0007](../../02-DECISIONS/0007-no-npm-workspace.md)): each module is a standalone package consuming published dependencies, including the mesh's own. The pipeline resolves modules into dependency **levels** and completes a level before starting @@ -96,7 +96,7 @@ since (see A module that owns state owns its migrations: numbered, written in the module's own language, compiled with it, frozen once they have run anywhere, and idempotent so that re-running is safe -([ADR 0006](../../adr/0006-schema-changes-are-numbered-migrations.md)). +([ADR 0006](../../02-DECISIONS/0006-schema-changes-are-numbered-migrations.md)). Two kinds exist and the distinction matters: migrations against the module's **own** local state, and migrations against a **provisioned** resource, which run on the node that consumes diff --git a/02-DESIGN/00-as-is/03-provisioning.md b/03-DESIGN/00-as-is/03-provisioning.md similarity index 96% rename from 02-DESIGN/00-as-is/03-provisioning.md rename to 03-DESIGN/00-as-is/03-provisioning.md index c6bf402..aa199c8 100644 --- a/02-DESIGN/00-as-is/03-provisioning.md +++ b/03-DESIGN/00-as-is/03-provisioning.md @@ -4,8 +4,8 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0005-capabilities-are-provisioned-on-declaration.md - - adr/0004-managed-files-are-generated-never-edited.md + - 02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md + - 02-DECISIONS/0004-managed-files-are-generated-never-edited.md --- # Provisioning diff --git a/02-DESIGN/00-as-is/04-delivery.md b/03-DESIGN/00-as-is/04-delivery.md similarity index 92% rename from 02-DESIGN/00-as-is/04-delivery.md rename to 03-DESIGN/00-as-is/04-delivery.md index 7b1829e..0f55da7 100644 --- a/02-DESIGN/00-as-is/04-delivery.md +++ b/03-DESIGN/00-as-is/04-delivery.md @@ -4,9 +4,9 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0014-build-publish-and-deploy-are-three-silos.md - - adr/0013-an-artifact-is-build-output.md - - adr/0008-a-failed-step-fails-the-job.md + - 02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md + - 02-DECISIONS/0013-an-artifact-is-build-output.md + - 02-DECISIONS/0008-a-failed-step-fails-the-job.md --- # Delivery — from a push to a running node @@ -31,7 +31,7 @@ merge that created no pipeline, and nothing said so**. ## Three silos Cardinality is the whole point, and the three differ -([ADR 0014](../../adr/0014-build-publish-and-deploy-are-three-silos.md)): +([ADR 0014](../../02-DECISIONS/0014-build-publish-and-deploy-are-three-silos.md)): | Silo | Runs | Where | Does | |---|---|---|---| @@ -50,7 +50,7 @@ later stage runs. ## The artifact The artifact is **build output** — compiled and bundled with its dependency graph inlined — -never a filtered copy of source ([ADR 0013](../../adr/0013-an-artifact-is-build-output.md)). +never a filtered copy of source ([ADR 0013](../../02-DECISIONS/0013-an-artifact-is-build-output.md)). A deploy is extract-and-run and touches no network. The consequence is the whole cost of the decision: **anything not in the build output does not diff --git a/02-DESIGN/00-as-is/05-runtime-and-installation.md b/03-DESIGN/00-as-is/05-runtime-and-installation.md similarity index 92% rename from 02-DESIGN/00-as-is/05-runtime-and-installation.md rename to 03-DESIGN/00-as-is/05-runtime-and-installation.md index 5ad0c8c..3db208d 100644 --- a/02-DESIGN/00-as-is/05-runtime-and-installation.md +++ b/03-DESIGN/00-as-is/05-runtime-and-installation.md @@ -4,8 +4,8 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0002-everything-is-a-module.md - - adr/0011-the-installer-owns-linking.md + - 02-DECISIONS/0002-everything-is-a-module.md + - 02-DECISIONS/0011-the-installer-owns-linking.md --- # The node runtime, and how a node comes into being @@ -38,7 +38,7 @@ suggestive word in the system names the node runtime, and the component whose ma "mesh messaging" is documented elsewhere as the interactive runtime. Anatomy makes attractive names and poor boundaries. -[ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) replaces this with names +[ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) replaces this with names taken from what each part owns. Until then, this is the vocabulary in the code. ## Starting a module @@ -57,14 +57,14 @@ outstanding local migrations, create data directories with the right ownership, service under supervision. **The installer is the only thing that creates a link** ([ADR -0011](../../adr/0011-the-installer-owns-linking.md)). It reconciles rather than assumes: a +0011](../../02-DECISIONS/0011-the-installer-owns-linking.md)). It reconciles rather than assumes: a missing link is created, a stale one repointed, and a real file found where a link belongs is adopted into the node's override area and replaced. Nothing else — not a hook, not a fix, not a person debugging — creates one. That is the as-is. The intent is to remove linking altogether and derive a real file instead, which the reconciliation machinery already makes possible -([ADR 0018](../../adr/0018-the-mesh-creates-no-symlinks.md), proposed). What is described above +([ADR 0018](../../02-DECISIONS/0018-the-mesh-creates-no-symlinks.md), proposed). What is described above is what runs today. ## Supervision diff --git a/02-DESIGN/00-as-is/06-configuration-and-secrets.md b/03-DESIGN/00-as-is/06-configuration-and-secrets.md similarity index 92% rename from 02-DESIGN/00-as-is/06-configuration-and-secrets.md rename to 03-DESIGN/00-as-is/06-configuration-and-secrets.md index f49695e..8372519 100644 --- a/02-DESIGN/00-as-is/06-configuration-and-secrets.md +++ b/03-DESIGN/00-as-is/06-configuration-and-secrets.md @@ -4,8 +4,8 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0004-managed-files-are-generated-never-edited.md - - adr/0005-capabilities-are-provisioned-on-declaration.md + - 02-DECISIONS/0004-managed-files-are-generated-never-edited.md + - 02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md --- # Configuration and secrets @@ -17,7 +17,7 @@ files is **generated**. A managed file is derived from the mesh database. A synchroniser rewrites it when the values behind it change. The write path is the mesh operation that owns the value; the file is an -output ([ADR 0004](../../adr/0004-managed-files-are-generated-never-edited.md)). +output ([ADR 0004](../../02-DECISIONS/0004-managed-files-are-generated-never-edited.md)). An edit to a managed file survives until the next synchronisation and is then overwritten silently, taking whatever it was fixing with it — bringing back the bug the edit had removed, @@ -61,7 +61,7 @@ are both left behind. Configuration is additive in practice, whatever the manife Generated secrets are produced by the mesh, never authored. Provisioned credentials arrive as database overrides written by the provisioner and are marked as such, so they can be distinguished from a deliberate override and cleaned up when the grant is removed -([ADR 0005](../../adr/0005-capabilities-are-provisioned-on-declaration.md)). +([ADR 0005](../../02-DECISIONS/0005-capabilities-are-provisioned-on-declaration.md)). Nothing in the repository contains a credential. The repository has no per-node content at all, which is what makes that guarantee structural rather than a matter of care. diff --git a/02-DESIGN/00-as-is/07-knowledge.md b/03-DESIGN/00-as-is/07-knowledge.md similarity index 97% rename from 02-DESIGN/00-as-is/07-knowledge.md rename to 03-DESIGN/00-as-is/07-knowledge.md index d3ad87e..d721c89 100644 --- a/02-DESIGN/00-as-is/07-knowledge.md +++ b/03-DESIGN/00-as-is/07-knowledge.md @@ -40,7 +40,7 @@ owning approval and promotion at the boundary. Proposals to edit are reviewed ra applied. This is where the mesh's **governed** documents live, including the constitution injected into -design sessions ([ADR 0009](../../adr/0009-the-mesh-is-governed-by-a-constitution.md)). +design sessions ([ADR 0009](../../02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md)). ## Why both diff --git a/02-DESIGN/00-as-is/08-agents-and-work.md b/03-DESIGN/00-as-is/08-agents-and-work.md similarity index 86% rename from 02-DESIGN/00-as-is/08-agents-and-work.md rename to 03-DESIGN/00-as-is/08-agents-and-work.md index 4b4c874..d6d3877 100644 --- a/02-DESIGN/00-as-is/08-agents-and-work.md +++ b/03-DESIGN/00-as-is/08-agents-and-work.md @@ -4,8 +4,8 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0012-agents-are-persistent-employees.md - - adr/0009-the-mesh-is-governed-by-a-constitution.md + - 02-DECISIONS/0012-agents-are-persistent-employees.md + - 02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md --- # Agents and work @@ -17,7 +17,7 @@ model they run under is the employee model, not a worker pool. An agent is a singular named identity with a home node, a workspace on that node, accumulating memory, and an explicit lifecycle -([ADR 0012](../../adr/0012-agents-are-persistent-employees.md)). +([ADR 0012](../../02-DECISIONS/0012-agents-are-persistent-employees.md)). | Property | Meaning | |---|---| @@ -45,7 +45,7 @@ Both hold identity, both act, both accumulate memory. The mesh does not currently record modality completely. Which user, on which node, a human agent acts as is **required by the model and not stored** — an open question carried over from -[ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md). +[ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md). ## Work @@ -70,7 +70,7 @@ template that names the phases. This is where governance meets execution. The constitution is injected into every eligible meeting turn — agents do not fetch it, it arrives — and a check phase verifies the meeting's output against it before the meeting may proceed -([ADR 0009](../../adr/0009-the-mesh-is-governed-by-a-constitution.md)). A named violation +([ADR 0009](../../02-DECISIONS/0009-the-mesh-is-governed-by-a-constitution.md)). A named violation blocks progress. Meeting turns run on the orchestrator's node regardless of where the participating agents are @@ -79,10 +79,10 @@ pinned. That is a known divergence between the model and its execution, not a de ## What this rests on that is not built The work domain shares one large schema with several other domains. That is the concrete -instance of a rule stated in [`how-we-build.md`](../../00-GENESIS/how-we-build.md) — *contexts +instance of a rule stated in [`how-we-build.md`](../../00-META/how-we-build.md) — *contexts integrate through the record, never through a shared schema* — being violated by the mesh's own largest component, and it is the reason work that belongs to one domain keeps having to be implemented in another. -[ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement. +[ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) dissolves that arrangement. Until it does, this is the shape. diff --git a/02-DESIGN/00-as-is/09-interfaces-and-observability.md b/03-DESIGN/00-as-is/09-interfaces-and-observability.md similarity index 96% rename from 02-DESIGN/00-as-is/09-interfaces-and-observability.md rename to 03-DESIGN/00-as-is/09-interfaces-and-observability.md index d31ae0d..f47665d 100644 --- a/02-DESIGN/00-as-is/09-interfaces-and-observability.md +++ b/03-DESIGN/00-as-is/09-interfaces-and-observability.md @@ -4,8 +4,8 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0001-nodes-communicate-over-a-broker.md - - adr/0008-a-failed-step-fails-the-job.md + - 02-DECISIONS/0001-nodes-communicate-over-a-broker.md + - 02-DECISIONS/0008-a-failed-step-fails-the-job.md --- # Interfaces and observability diff --git a/02-DESIGN/00-as-is/10-module-catalogue.md b/03-DESIGN/00-as-is/10-module-catalogue.md similarity index 88% rename from 02-DESIGN/00-as-is/10-module-catalogue.md rename to 03-DESIGN/00-as-is/10-module-catalogue.md index 08acd76..9a07a56 100644 --- a/02-DESIGN/00-as-is/10-module-catalogue.md +++ b/03-DESIGN/00-as-is/10-module-catalogue.md @@ -4,16 +4,16 @@ status: implemented code: [hal] updated: 2026-08-23 decisions: - - adr/0002-everything-is-a-module.md - - adr/0010-applications-live-in-their-own-repository.md - - adr/0017-modules-outside-the-core-are-grouped-by-domain.md + - 02-DECISIONS/0002-everything-is-a-module.md + - 02-DECISIONS/0010-applications-live-in-their-own-repository.md + - 02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md --- # The catalogue, and what its shape says The catalogue holds **124 modules**. Thirty-three belong to the mesh's own domain; the other ninety-one run *on* the mesh rather than being *of* it -([ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md)). +([ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md)). The count is not the finding. The **shape** is. @@ -55,11 +55,11 @@ connectivity is made four times. the unit of one piece of software, because that is the only granularity the module system offers. -This is the same failure [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) +This is the same failure [ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) names for the platform core — *boundaries drawn by deployment accident rather than by domain* — appearing outside it, at four times the scale. The core is being recomposed; the flat level is addressed in principle by -[ADR 0017](../../adr/0017-modules-outside-the-core-are-grouped-by-domain.md), which +[ADR 0017](../../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md), which deliberately does not yet settle the domain list. ## Two properties worth keeping @@ -72,7 +72,7 @@ which is what makes dogfooding structural rather than a discipline, and what mak module out of the repository safe. **Placement is already decided.** A standalone application belongs in its own repository -([ADR 0010](../../adr/0010-applications-live-in-their-own-repository.md)), and reviewers reject +([ADR 0010](../../02-DECISIONS/0010-applications-live-in-their-own-repository.md)), and reviewers reject it in the monorepo. The catalogue's flat level is not a dumping ground by policy; it is one by history. diff --git a/02-DESIGN/00-as-is/README.md b/03-DESIGN/00-as-is/README.md similarity index 98% rename from 02-DESIGN/00-as-is/README.md rename to 03-DESIGN/00-as-is/README.md index b267670..d2537e0 100644 --- a/02-DESIGN/00-as-is/README.md +++ b/03-DESIGN/00-as-is/README.md @@ -1,4 +1,4 @@ -# 02-DESIGN / 00-as-is +# 03-DESIGN / 00-as-is The mesh as it stands. These documents describe what runs, including the parts nobody would choose again — an as-is layer that only records the good decisions is a brochure. diff --git a/02-DESIGN/01-to-be/00-work-breakdown.md b/03-DESIGN/01-to-be/00-work-breakdown.md similarity index 96% rename from 02-DESIGN/01-to-be/00-work-breakdown.md rename to 03-DESIGN/01-to-be/00-work-breakdown.md index 5489a20..e39762e 100644 --- a/02-DESIGN/01-to-be/00-work-breakdown.md +++ b/03-DESIGN/01-to-be/00-work-breakdown.md @@ -3,12 +3,12 @@ layer: to-be status: designed code: [hal] updated: 2026-08-23 -decisions: [adr/0015-mesh-brokers-nodes-host-agents-think.md] +decisions: [02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md] --- # Work breakdown — the decomposition -How [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) gets built, in what order, and where a human must look. +How [ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) gets built, in what order, and where a human must look. Ordering is not preference. Each phase removes a constraint the next one needs gone. @@ -35,7 +35,7 @@ An agent may, without asking: - **merging anything** — every merge is a human checkpoint, without exception - **a decision the ADRs do not already answer** — record the question in the relevant research effort rather than picking and moving on -- **any change to `hq/00-GENESIS`** — it is stable by nature +- **any change to `hq/00-META`** — it is stable by nature ### Definition of done for every task diff --git a/02-DESIGN/01-to-be/01-end-to-end-testing.md b/03-DESIGN/01-to-be/01-end-to-end-testing.md similarity index 98% rename from 02-DESIGN/01-to-be/01-end-to-end-testing.md rename to 03-DESIGN/01-to-be/01-end-to-end-testing.md index e981989..2c4932f 100644 --- a/02-DESIGN/01-to-be/01-end-to-end-testing.md +++ b/03-DESIGN/01-to-be/01-end-to-end-testing.md @@ -3,7 +3,7 @@ layer: to-be status: designed code: [hal] updated: 2026-08-23 -decisions: [adr/0016-a-lab-node-is-a-virtual-machine.md] +decisions: [02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md] --- # End-to-end testing @@ -41,7 +41,7 @@ Work reaches the mesh along one path today: **The gate is a human reading a diff, and the test is production.** That is workable at a change a day and it is the constraint at ten. For autonomous work it is worse than a constraint: an agent's output arrives as a diff that *looks* right, carrying no evidence -that it runs, and the only reviewer is the condition `00-GENESIS/context.md` calls mandatory +that it runs, and the only reviewer is the condition `00-META/context.md` calls mandatory — *human agents are few, often one, and usually asleep.* The missing step goes between the pull request and the merge: @@ -154,7 +154,7 @@ that only the developer path can do is a divergence, and it will drift. the pipeline result is the verdict ``` -This is the same property `00-GENESIS/mission.md` asks for: *the mesh's own components ship +This is the same property `00-META/mission.md` asks for: *the mesh's own components ship through the same machinery as anything else it carries — if they need an exception, the machinery is not finished.* A test that needed its own delivery path would be that exception. diff --git a/02-DESIGN/01-to-be/README.md b/03-DESIGN/01-to-be/README.md similarity index 64% rename from 02-DESIGN/01-to-be/README.md rename to 03-DESIGN/01-to-be/README.md index 2c5ec88..d86e771 100644 --- a/02-DESIGN/01-to-be/README.md +++ b/03-DESIGN/01-to-be/README.md @@ -1,7 +1,7 @@ -# 02-DESIGN / 01-to-be +# 03-DESIGN / 01-to-be The mesh being built toward. Every statement here traces to a record in -[`adr/`](../../adr/); nothing arrives by drafting. +[`02-DECISIONS/`](../../02-DECISIONS/); nothing arrives by drafting. A document here describes an intention. What currently runs is in [`00-as-is/`](../00-as-is/), and the two are never merged — when something ships, the as-is @@ -9,14 +9,14 @@ document is written and this one's status becomes `implemented`. | Document | Covers | Rests on | |---|---|---| -| [`00-work-breakdown.md`](00-work-breakdown.md) | How the decomposition gets built, in what order, and where a human must look | [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) | -| [`01-end-to-end-testing.md`](01-end-to-end-testing.md) | The lab: a real mesh a change can be run against before it reaches nodes | [ADR 0016](../../adr/0016-a-lab-node-is-a-virtual-machine.md) | +| [`00-work-breakdown.md`](00-work-breakdown.md) | How the decomposition gets built, in what order, and where a human must look | [ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) | +| [`01-end-to-end-testing.md`](01-end-to-end-testing.md) | The lab: a real mesh a change can be run against before it reaches nodes | [ADR 0016](../../02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md) | ## Not yet written -- **The eight bounded contexts.** [ADR 0015](../../adr/0015-mesh-brokers-nodes-host-agents-think.md) +- **The eight bounded contexts.** [ADR 0015](../../02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) decides the decomposition; the per-context specifications do not exist yet. The work breakdown says in what order they are needed. -- **Domain grouping outside the core.** [ADR 0017](../../adr/0017-modules-outside-the-core-are-grouped-by-domain.md) +- **Domain grouping outside the core.** [ADR 0017](../../02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md) settles the principle and explicitly does not settle the domain list. That is a research effort, not a design document, until it concludes. diff --git a/02-DESIGN/README.md b/03-DESIGN/README.md similarity index 87% rename from 02-DESIGN/README.md rename to 03-DESIGN/README.md index 87fe118..ca48e61 100644 --- a/02-DESIGN/README.md +++ b/03-DESIGN/README.md @@ -1,4 +1,4 @@ -# 02-DESIGN +# 03-DESIGN The authoritative specification. Implementation is built against what is written here. @@ -7,7 +7,7 @@ The authoritative specification. Implementation is built against what is written | Folder | What it is | |---|---| | [`00-as-is/`](00-as-is/) | **The mesh that exists today.** Shipped behaviour, described as it is — including behaviour nobody would choose again. | -| [`01-to-be/`](01-to-be/) | **The mesh being built toward.** Every statement traceable to a record in [`adr/`](../adr/). | +| [`01-to-be/`](01-to-be/) | **The mesh being built toward.** Every statement traceable to a record in [`02-DECISIONS/`](../02-DECISIONS/). | They are never mixed. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention. @@ -25,9 +25,9 @@ Every design document (not the READMEs) carries: --- layer: as-is | to-be status: designed | in-progress | implemented | abandoned -code: [] # owning code repo(s), from 00-GENESIS/repos.md +code: [] # owning code repo(s), from 00-META/repos.md updated: YYYY-MM-DD # date of the last status change, not of text edits -decisions: [] # adr/ records this document rests on +decisions: [] # 02-DECISIONS/ records this document rests on --- ``` @@ -45,7 +45,7 @@ written to disk. Functional analysis, architectural description, and specification — **prose and diagrams only, no code**. A manifest field may be named; a manifest may not be pasted. A document -enters the to-be layer only after the decision behind it is recorded in [`adr/`](../adr/) +enters the to-be layer only after the decision behind it is recorded in [`02-DECISIONS/`](../02-DECISIONS/) and the research that produced it is closed. Subfolders are encouraged where a layer grows enough to need them. diff --git a/04-ISSUES/001-failed-package-install-reports-success/00-report.md b/04-ISSUES/001-failed-package-install-reports-success/00-report.md index 1074d35..02a0655 100644 --- a/04-ISSUES/001-failed-package-install-reports-success/00-report.md +++ b/04-ISSUES/001-failed-package-install-reports-success/00-report.md @@ -31,14 +31,14 @@ exists to catch — a step that failed, reported success, and left the next step state that was never produced. It is also a direct violation of a decision already taken and recorded: -[ADR 0008](../../adr/0008-a-failed-step-fails-the-job.md) says a step that fails must fail the +[ADR 0008](../../02-DECISIONS/0008-a-failed-step-fails-the-job.md) says a step that fails must fail the job. That record notes the rule is applied instance by instance and enforced by no mechanism. This is an instance where it was never applied. ## Evidence - Observed 2026-08-22 while declaring the virtualisation package required by - [ADR 0016](../../adr/0016-a-lab-node-is-a-virtual-machine.md). + [ADR 0016](../../02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md). - A fix is written and open as a pull request, unmerged since 2026-08-20. ## Open questions diff --git a/04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md b/04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md index 2501915..f2b5d5c 100644 --- a/04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md +++ b/04-ISSUES/003-firewall-scope-is-read-by-no-code/00-report.md @@ -17,7 +17,7 @@ A manifest can therefore appear to restrict a port and restrict nothing. ## Why this matters -This is the failure mode [`how-we-build.md`](../../00-GENESIS/how-we-build.md) names directly: +This is the failure mode [`how-we-build.md`](../../00-META/how-we-build.md) names directly: *an unenforced rule is indistinguishable from a wrong one, and costs more, because people believe it.* Here it is worse than unenforced — the declaration reads as a restriction, so a reviewer checking whether a port is scoped will find that it is, and be wrong. diff --git a/04-ISSUES/004-certificate-issuance-targets-production/00-report.md b/04-ISSUES/004-certificate-issuance-targets-production/00-report.md index 5a0cad3..23f7c51 100644 --- a/04-ISSUES/004-certificate-issuance-targets-production/00-report.md +++ b/04-ISSUES/004-certificate-issuance-targets-production/00-report.md @@ -21,7 +21,7 @@ recoverable by retrying — it removes the ability to issue a certificate anyone The consequence lands hardest on exactly the work most likely to iterate: standing up a new node, changing how names resolve, or testing the lab's certificate authority split -([ADR 0016](../../adr/0016-a-lab-node-is-a-virtual-machine.md)). +([ADR 0016](../../02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md)). ## Evidence diff --git a/04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md b/04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md index e1a997e..1957ffe 100644 --- a/04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md +++ b/04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md @@ -29,13 +29,13 @@ coverage was assumed, not checked. ## Evidence - The workspace was removed by pull request #240 on 2026-06-04 - ([ADR 0007](../../adr/0007-no-npm-workspace.md)). + ([ADR 0007](../../02-DECISIONS/0007-no-npm-workspace.md)). - The harness has not built since that date. - Recorded in the knowledge base as a standing entry, not as a fixed incident. ## Relationship to the lab -[`02-DESIGN/01-to-be/01-end-to-end-testing.md`](../../02-DESIGN/01-to-be/01-end-to-end-testing.md) +[`03-DESIGN/01-to-be/01-end-to-end-testing.md`](../../03-DESIGN/01-to-be/01-end-to-end-testing.md) designs end-to-end testing on a lab mesh, which would replace this harness rather than repair it. That is a reason to decide its fate deliberately, not a reason to leave it broken and unmentioned: until the lab exists, this is the coverage the pipeline is presumed to have. diff --git a/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md b/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md index 3480f9d..3725926 100644 --- a/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md +++ b/04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md @@ -51,7 +51,7 @@ checked it — including in the same commit that wrote the rule. is this a periodic sync of a repository into it, or a search surface that reads the repository directly? - Which store — the flat symptom-indexed memory, the structured archive, or both? They have - different lifecycles ([`02-DESIGN/00-as-is/07-knowledge.md`](../../02-DESIGN/00-as-is/07-knowledge.md)), + different lifecycles ([`03-DESIGN/00-as-is/07-knowledge.md`](../../03-DESIGN/00-as-is/07-knowledge.md)), and this content is governed rather than incidental. - Public repository, private mesh: the sync direction must not become a path for mesh-specific content to arrive **into** these documents. diff --git a/04-ISSUES/README.md b/04-ISSUES/README.md index 604e6b9..aba4de2 100644 --- a/04-ISSUES/README.md +++ b/04-ISSUES/README.md @@ -41,6 +41,6 @@ amended-design: # design doc path, when the root cause was a design gap ## Rules - Anyone may open an issue. No localisation is required to report one. -- The full flow is playbook [`00-GENESIS/process/03-issues.md`](../00-GENESIS/process/03-issues.md). +- The full flow is playbook [`00-META/process/03-issues.md`](../00-META/process/03-issues.md). - Closed issues are never deleted — they are the mesh's symptom-to-component memory. - `wontfix` is legitimate and requires a sentence saying why. diff --git a/AGENTS.md b/AGENTS.md index 25bd84d..a4ab546 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,10 +2,10 @@ This repository is the source of truth for the HAL mesh's mission, research, design and decisions. Implementation lives in the code repositories (see -[`00-GENESIS/repos.md`](00-GENESIS/repos.md)). +[`00-META/repos.md`](00-META/repos.md)). Before changing anything here, read the playbooks in -[`00-GENESIS/process/`](00-GENESIS/process/) — every workflow (research, graduation, design +[`00-META/process/`](00-META/process/) — every workflow (research, graduation, design amendment, issues, build handoff, constitution sync) is documented there, and agents operate through them. Thin skills in `.claude/skills/` wrap these playbooks for invocation (`hal-new-research`, `hal-graduate`, `hal-new-issue`, `hal-diagnose`, `hal-amend-design`, @@ -19,17 +19,17 @@ authoritative and adds only the mechanical scaffolding. docs (`layer`, `status`, `code`, `updated`), issue reports (`status`, `located-in`, `fixed-by`, `amended-design`) and decision records (`status`, `date`, `deciders`). Never create a central status file; cross-cutting views are generated from frontmatter. -- **`adr/` records are immutable.** Supersede with a new record; never edit meaning. Fixing a +- **`02-DECISIONS/` records are immutable.** Supersede with a new record; never edit meaning. Fixing a broken link or path is allowed. - **Design docs are prose and diagrams only** — no code. A manifest field may be named; a manifest may not be pasted. -- **Two layers, never mixed.** [`02-DESIGN/00-as-is/`](02-DESIGN/00-as-is/) describes the mesh - that exists; [`02-DESIGN/01-to-be/`](02-DESIGN/01-to-be/) describes the one being built +- **Two layers, never mixed.** [`03-DESIGN/00-as-is/`](03-DESIGN/00-as-is/) describes the mesh + that exists; [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) describes the one being built toward. Every design doc says which it is in `layer:`. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention. -- **`00-GENESIS/how-we-build.md` is the source of the mesh constitution.** The knowledge-base +- **`00-META/how-we-build.md` is the source of the mesh constitution.** The knowledge-base constitution page is derived from it — see playbook - [`05-constitution-sync.md`](00-GENESIS/process/05-constitution-sync.md). Never edit the + [`05-constitution-sync.md`](00-META/process/05-constitution-sync.md). Never edit the derived page directly. ## This repository is public diff --git a/DECISIONS.md b/DECISIONS.md index f14a11b..03f88ac 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -5,7 +5,7 @@ marked superseded and left in place, because the reasoning that was rejected is half to rediscover. An entry here is a **record**, not the reasoning. Anything architecturally significant carries -its full context, options and consequences in an [ADR](adr/); anything still being worked out +its full context, options and consequences in an [ADR](02-DECISIONS/); anything still being worked out lives in [`01-RESEARCH`](01-RESEARCH/). This file is the index that makes both findable, and the place small decisions live that never warrant a document of their own. @@ -18,10 +18,10 @@ no pointer is one small enough that this line is the whole record. | # | Decision | Decided | Where | |---|---|---|---| -| 1 | The mesh brokers capabilities; nodes host; agents think. Eight bounded contexts replace 33 platform modules. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) | -| 2 | Nodes and agents decouple — a node holds no licence; an agent holds credentials and delivery follows its bindings and modality. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) | -| 3 | noxflow dissolves; `hal/work` inherits tasks and workflows. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) | -| 4 | Third-party modules leave this repository — they run *on* the mesh, not *of* it. | jochen | [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) | +| 1 | The mesh brokers capabilities; nodes host; agents think. Eight bounded contexts replace 33 platform modules. | jochen | [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) | +| 2 | Nodes and agents decouple — a node holds no licence; an agent holds credentials and delivery follows its bindings and modality. | jochen | [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) | +| 3 | noxflow dissolves; `hal/work` inherits tasks and workflows. | jochen | [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) | +| 4 | Third-party modules leave this repository — they run *on* the mesh, not *of* it. | jochen | [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) | | 5 | ~~Documentation lives inside the code repository under `hq/`.~~ | jochen | **Superseded by #27** | ## 2026-08-22 — the lab @@ -31,24 +31,24 @@ no pointer is one small enough that this line is the whole record. | 6 | Phase 0 is a **development environment**, not a fixture rig — it is what the host-borrowing dev tooling becomes. | jochen | [002](01-RESEARCH/002-local-mesh/00-overview.md) | | 7 | The delivery trigger is a **real forge** inside the lab, not a synthetic event — the webhook relay is part of what is under test. | jochen | [002](01-RESEARCH/002-local-mesh/00-overview.md) | | 8 | ~~A lab node is a **system container**, promotable to a virtual machine.~~ | jochen | **Superseded by #10** | -| 9 | Adoption is a legacy path and is out of scope. Bringing nodes into being is the lab runner's job instead. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 10 | A lab node is a **virtual machine** running the real install. Supersedes #8: the scale argument for system containers was invented rather than required, and a virtual machine dissolves the fidelity question instead of answering it. | jochen | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md) | +| 9 | Adoption is a legacy path and is out of scope. Bringing nodes into being is the lab runner's job instead. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 10 | A lab node is a **virtual machine** running the real install. Supersedes #8: the scale argument for system containers was invented rather than required, and a virtual machine dissolves the fidelity question instead of answering it. | jochen | [ADR 0016](02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md) | | 11 | The environment is called **the lab**. | jochen | — | -| 12 | The lab is driven by `incus` — for virtual machines, snapshots and bridges through one interface, and because it also runs system containers if a scale run is ever needed. | jochen | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md) | -| 13 | The simulated public segment uses **TEST-NET-3** (`203.0.113.0/24`). Not cosmetic: an RFC1918 public segment makes the hub test as unreachable and the mesh silently never forms. | — | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md), [004](01-RESEARCH/004-lab-network/analysis.md) | -| 14 | The lab **issues its own certificates**, keeping production's two-authority split rather than collapsing it. | jochen | [ADR 0016](adr/0016-a-lab-node-is-a-virtual-machine.md) | +| 12 | The lab is driven by `incus` — for virtual machines, snapshots and bridges through one interface, and because it also runs system containers if a scale run is ever needed. | jochen | [ADR 0016](02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md) | +| 13 | The simulated public segment uses **TEST-NET-3** (`203.0.113.0/24`). Not cosmetic: an RFC1918 public segment makes the hub test as unreachable and the mesh silently never forms. | — | [ADR 0016](02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md), [004](01-RESEARCH/004-lab-network/analysis.md) | +| 14 | The lab **issues its own certificates**, keeping production's two-authority split rather than collapsing it. | jochen | [ADR 0016](02-DECISIONS/0016-a-lab-node-is-a-virtual-machine.md) | ## 2026-08-22 — what the lab is for | # | Decision | Decided | Where | |---|---|---|---| -| 15 | **The module is what is under test; the mesh is the harness.** The loop is: change a module, run it end to end, get a verdict. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 16 | **Nothing new drives delivery.** A lab mesh has its own coordinator; the pipeline that runs is the real one. A second delivery path would be blind to exactly the faults worth catching. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 17 | A **test runner** is a legitimate component *used by* the coordinator — lab lifecycle and assertion execution. The line is the pipeline: a runner that decides what to build is a fork of the coordinator. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 18 | The runner has **two callers** — the coordinator, and a person developing the mesh — so it needs both a run-to-verdict verb and a leave-it-standing verb. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 19 | **A module carries its own assertions**, stated once, in the verification stage the coordinator already dispatches. Running them where failing is free is what makes writing them worth doing. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 20 | A test declares the mesh it needs; **size ranges from one node upward**, chosen by the question rather than by what the mesh happens to have. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | -| 21 | The real topology is **one test among many**, not the baseline. Anything only testable there is a gap in the vocabulary. | jochen | [design](02-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 15 | **The module is what is under test; the mesh is the harness.** The loop is: change a module, run it end to end, get a verdict. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 16 | **Nothing new drives delivery.** A lab mesh has its own coordinator; the pipeline that runs is the real one. A second delivery path would be blind to exactly the faults worth catching. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 17 | A **test runner** is a legitimate component *used by* the coordinator — lab lifecycle and assertion execution. The line is the pipeline: a runner that decides what to build is a fork of the coordinator. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 18 | The runner has **two callers** — the coordinator, and a person developing the mesh — so it needs both a run-to-verdict verb and a leave-it-standing verb. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 19 | **A module carries its own assertions**, stated once, in the verification stage the coordinator already dispatches. Running them where failing is free is what makes writing them worth doing. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 20 | A test declares the mesh it needs; **size ranges from one node upward**, chosen by the question rather than by what the mesh happens to have. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | +| 21 | The real topology is **one test among many**, not the baseline. Anything only testable there is a gap in the vocabulary. | jochen | [design](03-DESIGN/01-to-be/01-end-to-end-testing.md) | ## 2026-08-22 — working agreements @@ -56,8 +56,8 @@ no pointer is one small enough that this line is the whole record. |---|---|---|---| | 22 | **Never install packages by hand.** A package is declared in the module manifest and arrives the way every other package does. | jochen | — | | 23 | **Never open a pull request unprompted.** A permissions list saying it is allowed is not a request. | jochen | — | -| 24 | **Every merge is a human checkpoint**, without exception. | jochen | [`02-DESIGN/01-to-be/00-work-breakdown.md`](02-DESIGN/01-to-be/00-work-breakdown.md) | -| 25 | Work in an **isolated worktree**, never a shared checkout. | jochen | [`how-we-build`](00-GENESIS/how-we-build.md) §2 | +| 24 | **Every merge is a human checkpoint**, without exception. | jochen | [`03-DESIGN/01-to-be/00-work-breakdown.md`](03-DESIGN/01-to-be/00-work-breakdown.md) | +| 25 | Work in an **isolated worktree**, never a shared checkout. | jochen | [`how-we-build`](00-META/how-we-build.md) §2 | | 26 | Decisions are recorded **here**, thoroughly, as they are taken. | jochen | this file | | 27 | HQ is **its own repository**, `hal-hq`. Supersedes #5: the original objection was to a fourth knowledge *system*, which indexing answers rather than location. Cadence, reviewers, and a scope wider than one repository all argue for separation. | jochen | [`README`](README.md) | | 28 | **This repository is public.** Written for a reader who is not its author and has no access to the mesh it describes. No routable addresses, real domains, hosting providers, node names, absolute paths, or operational detail useful only to an attacker. Supersedes the previous rule that research may name instances. | jochen | [`README`](README.md) | @@ -68,17 +68,19 @@ no pointer is one small enough that this line is the whole record. | # | Decision | Decided | Where | |---|---|---|---| -| 29 | Design splits into two layers that are never mixed — **`00-as-is` describes the mesh that exists, `01-to-be` the one being built toward**. A design that ships does not move; its as-is counterpart is written and both stand. | jochen | [`02-DESIGN/README`](02-DESIGN/README.md) | -| 30 | The as-is layer is written **from the implementation and the operational record**, not from intent, and records shipped behaviour nobody would choose again. An as-is layer that keeps only the good decisions is a brochure. | jochen | [`02-DESIGN/00-as-is/README`](02-DESIGN/00-as-is/README.md) | -| 31 | **HQ is the source of the mesh constitution.** The governed page injected into design sessions is derived from `how-we-build.md` and never edited directly. Same one-source-many-surfaces argument as #27. | jochen | [playbook 05](00-GENESIS/process/05-constitution-sync.md) | -| 32 | Every workflow is a **playbook** in `00-GENESIS/process/`, wrapped by a thin skill that defers to it. Agents operate through the playbooks and not outside them. | jochen | [`process/00-overview`](00-GENESIS/process/00-overview.md) | +| 29 | Design splits into two layers that are never mixed — **`00-as-is` describes the mesh that exists, `01-to-be` the one being built toward**. A design that ships does not move; its as-is counterpart is written and both stand. | jochen | [`03-DESIGN/README`](03-DESIGN/README.md) | +| 30 | The as-is layer is written **from the implementation and the operational record**, not from intent, and records shipped behaviour nobody would choose again. An as-is layer that keeps only the good decisions is a brochure. | jochen | [`03-DESIGN/00-as-is/README`](03-DESIGN/00-as-is/README.md) | +| 31 | **HQ is the source of the mesh constitution.** The governed page injected into design sessions is derived from `how-we-build.md` and never edited directly. Same one-source-many-surfaces argument as #27. | jochen | [playbook 05](00-META/process/05-constitution-sync.md) | +| 32 | Every workflow is a **playbook** in `00-META/process/`, wrapped by a thin skill that defers to it. Agents operate through the playbooks and not outside them. | jochen | [`process/00-overview`](00-META/process/00-overview.md) | | 33 | Issues get a **front door**, `04-ISSUES` — design-level and governance faults only. Operational lessons stay in the knowledge base, which is indexed on symptoms. This repository is not a second copy of it. | jochen | [`04-ISSUES/README`](04-ISSUES/README.md) | -| 34 | Decision records are a **chronological ledger**. Fourteen decisions already taken in implementation were back-filled as records 0001–0014, each marked `reconstructed` and carrying its evidence; the two existing records renumbered to 0015 and 0016. | jochen | [`adr/README`](adr/README.md) | -| 35 | **Status lives in frontmatter.** No central status files; cross-cutting views are generated on demand. This file is a ledger of decisions as taken — an index, and the home of decisions too small to warrant a record — and explicitly not a status board. | jochen | [`process/00-overview`](00-GENESIS/process/00-overview.md) | -| 36 | The ADR index is **generated, not maintained**. The hand-written one had already drifted after a single addition. | jochen | [`adr/README`](adr/README.md) | -| 37 | Modules outside the platform core are grouped **by domain, not by single function**, extending #1. The principle is settled; the domain list deliberately is not. | jochen | [ADR 0017](adr/0017-modules-outside-the-core-are-grouped-by-domain.md) | -| 38 | **The mesh creates no symlinks at all** — not by hand, and not by the installer. Centralising who may link narrowed the incident class without closing it, and a derived file is a copy by nature. The position is settled; the staleness mechanism is not. | jochen | [ADR 0018](adr/0018-the-mesh-creates-no-symlinks.md) | +| 34 | Decision records are a **chronological ledger**. Fourteen decisions already taken in implementation were back-filled as records 0001–0014, each marked `reconstructed` and carrying its evidence; the two existing records renumbered to 0015 and 0016. | jochen | [`02-DECISIONS/README`](02-DECISIONS/README.md) | +| 35 | **Status lives in frontmatter.** No central status files; cross-cutting views are generated on demand. This file is a ledger of decisions as taken — an index, and the home of decisions too small to warrant a record — and explicitly not a status board. | jochen | [`process/00-overview`](00-META/process/00-overview.md) | +| 36 | The ADR index is **generated, not maintained**. The hand-written one had already drifted after a single addition. | jochen | [`02-DECISIONS/README`](02-DECISIONS/README.md) | +| 37 | Modules outside the platform core are grouped **by domain, not by single function**, extending #1. The principle is settled; the domain list deliberately is not. | jochen | [ADR 0017](02-DECISIONS/0017-modules-outside-the-core-are-grouped-by-domain.md) | +| 38 | **The mesh creates no symlinks at all** — not by hand, and not by the installer. Centralising who may link narrowed the incident class without closing it, and a derived file is a copy by nature. The position is settled; the staleness mechanism is not. | jochen | [ADR 0018](02-DECISIONS/0018-the-mesh-creates-no-symlinks.md) | | 39 | Research efforts follow the **`00-overview.md`** convention, with `active` / `graduated` / `abandoned` in frontmatter — the same shape papa-hq uses, so the two repositories read alike. | jochen | [`01-RESEARCH/README`](01-RESEARCH/README.md) | +| 40 | **The numbering is the flow.** Decisions become `02-DECISIONS` and design becomes `03-DESIGN`, so a reader following the folder numbers walks the process in the order it happens — research, decision, design. papa-hq numbers these the other way round because `02-DESIGN` predated the promotion of `adr/`, which then took the next free number rather than its place in the sequence; that repository was too settled to renumber and this one was not. | jochen | [`02-DECISIONS/README`](02-DECISIONS/README.md) | +| 41 | `00-GENESIS` is renamed **`00-META`**, matching papa-hq. | jochen | [`00-META/README`](00-META/README.md) | --- diff --git a/README.md b/README.md index 42606cd..c8815f9 100644 --- a/README.md +++ b/README.md @@ -7,30 +7,34 @@ why. Implementation lives in `modules/`; the reasoning behind it lives here. | Folder | Purpose | |--------|---------| -| [`00-GENESIS`](00-GENESIS/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. The northern star for every decision. | +| [`00-META`](00-META/) | Mission, foundational context, the rules that hold across the mesh, the repository map, and the process playbooks. The northern star for every decision. | | [`01-RESEARCH`](01-RESEARCH/) | Active and historical investigations, before they harden into design. | -| [`02-DESIGN`](02-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](02-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](02-DESIGN/01-to-be/) — the one being built toward. | -| [`adr`](adr/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. | +| [`02-DECISIONS`](02-DECISIONS/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. | +| [`03-DESIGN`](03-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](03-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](03-DESIGN/01-to-be/) — the one being built toward. | | [`04-ISSUES`](04-ISSUES/) | The front door for "something is wrong" at the level of design or governance. | | [`DECISIONS.md`](DECISIONS.md) | The ledger: every decision as it was taken, indexing the records and holding the ones too small to warrant one. | +**The numbering is the flow.** Research produces a decision; the decision authorises a design. +That is why decisions are `02` and design is `03` — a reader following the numbers walks the +process in the order it happens. + ## The flow ``` -idea ──► 01-RESEARCH ──► decision (adr/) ──► 02-DESIGN/01-to-be ──► built (code repo) +idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo) │ │ │ - │ │ └─► 02-DESIGN/00-as-is once shipped + │ │ └─► 03-DESIGN/00-as-is once shipped │ └────► abandoned (recorded, kept) - └─(small/obvious, decision recorded in DECISIONS.md)────► 02-DESIGN directly + └─(small/obvious, decision recorded in DECISIONS.md)────► 03-DESIGN directly symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment -00-GENESIS/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions +00-META/how-we-build.md ──► sync ──► the constitution the mesh injects into design sessions ``` Implementation lives in the code repositories — see -[`00-GENESIS/repos.md`](00-GENESIS/repos.md). Every workflow is a playbook in -[`00-GENESIS/process/`](00-GENESIS/process/); agents operate through them and not outside them. +[`00-META/repos.md`](00-META/repos.md). Every workflow is a playbook in +[`00-META/process/`](00-META/process/); agents operate through them and not outside them. ## Rules @@ -97,7 +101,7 @@ Answered separately, a repository of its own is the better home: changes. Tying documents to a code branch means they merge on the code's schedule. - **The reviewers are different.** A design argument is not reviewed the way an implementation is, and it should not queue behind a build. -- **The scope is wider than one repository.** [ADR 0015](adr/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the +- **The scope is wider than one repository.** [ADR 0015](02-DECISIONS/0015-mesh-brokers-nodes-host-agents-think.md) sends most modules out of the monorepo entirely. Documentation that governs several repositories cannot live inside one of them.