Base layer: the mesh as it is, under the mesh as it should be
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
This commit is contained in:
+29
-11
@@ -3,26 +3,44 @@
|
||||
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.
|
||||
|
||||
| File | Purpose |
|
||||
| File / folder | Purpose |
|
||||
|------|---------|
|
||||
| [`mission.md`](mission.md) | Vision, mission, and the values that decide arguments |
|
||||
| [`context.md`](context.md) | The environment — conditions, not aspirations |
|
||||
| [`effect.md`](effect.md) | What is different when the work is done |
|
||||
| [`how-we-build.md`](how-we-build.md) | Rules that hold across the mesh, each one earned |
|
||||
| [`how-we-build.md`](how-we-build.md) | The rules that hold across the mesh, each one earned. **The source of the mesh constitution** — the governed page the mesh injects into design sessions is derived from it. |
|
||||
| [`repos.md`](repos.md) | Where implementation lives, and what each repository owns |
|
||||
| [`process/`](process/) | The playbooks — how work moves through this repository, for engineers and agents alike |
|
||||
|
||||
## Rules
|
||||
|
||||
- Markdown only.
|
||||
- **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration.
|
||||
- **Stable by nature.** Changes here reflect a genuine shift in intent, not iteration. The one
|
||||
exception is `how-we-build.md`, which changes whenever a rule is earned — and only through
|
||||
its amendment process.
|
||||
- Research and design must be traceable back to what is written here.
|
||||
- **Instance-agnostic.** These documents describe the mesh as a concept. No machine names, no
|
||||
counts, no topology.
|
||||
|
||||
## Note on `VISION.md`
|
||||
## On the architecture overview in the code repository
|
||||
|
||||
The repository root carries `VISION.md`, an architecture overview predating this folder.
|
||||
It is a useful description of *how* the mesh works and should be folded into
|
||||
[`02-DESIGN`](../02-DESIGN/), not here — GENESIS answers *why*.
|
||||
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*;
|
||||
that document answered *how*, which is the design layer's job.
|
||||
|
||||
It has also drifted: it lists "Symlinks, not copies" as a key design principle, while the
|
||||
operating rules forbid creating symlinks at all after one caused production data loss.
|
||||
A founding document contradicting a hard rule is precisely the failure this folder exists
|
||||
to prevent.
|
||||
It had also drifted from the implementation in ways worth recording, since both were found by
|
||||
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)).
|
||||
- It listed the mesh as spanning a fixed number of named machines, which is exactly the
|
||||
content this repository cannot carry.
|
||||
|
||||
One earlier note in this file has been withdrawn as **wrong**, and is recorded here rather than
|
||||
deleted. It claimed the overview's "symlinks, not copies" principle contradicted the mesh's
|
||||
hard rule against symlinks. It does not. The rule forbids *creating* a symlink by hand; the
|
||||
installer creates and reconciles every link the mesh needs, deliberately
|
||||
([ADR 0011](../adr/0011-the-installer-owns-linking.md)). The rule is about who may link, not
|
||||
about whether the mesh links — a misreading common enough that the ADR now says so explicitly.
|
||||
|
||||
Reference in New Issue
Block a user