jschoubben
93a1231e00
Skills take the hq- prefix: they are HQ process workflows, not mesh workflows, and HQ is company-scoped now. hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design, hq-handoff, hq-sync-constitution, hq-status. Forward-looking prose becomes Novox Mesh or simply the mesh — the root README, AGENTS.md, the 00-META README, the mission's module example, and one to-be document that addressed 'someone working on HAL'. Three categories deliberately keep HAL, per ADR 0027: The monorepo is still called hal on the forge. repos.md, every code: field and every located-in: field name a repository that exists under that name, and renaming them in prose would make them false. The as-is layer and the research that measured it describe the system that runs, and that system is called HAL. 124 modules, 9 daemons, a dead containerised node — those are observations, not intentions. Records 0001-0026 are immutable. A record says what was decided when it was decided, and no record is edited for a name. Also repoints ADR 0022's link at the renamed skill — a path fix, which the immutability rule permits, not a change of meaning.
54 lines
3.2 KiB
Markdown
54 lines
3.2 KiB
Markdown
# 00-META
|
|
|
|
The **northern star**. What the mesh is, the environment it runs in, and what changes when it
|
|
works — plus the engineering practice that holds across everything Novox builds. Every research effort and design decision is checked against this folder.
|
|
|
|
| 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) | 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. 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.
|
|
|
|
## On the architecture overview in the code repository
|
|
|
|
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 [`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
|
|
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](../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.
|
|
|
|
It also lists **"symlinks, not copies" as a key design principle**, and that is a genuine
|
|
contradiction rather than a stale detail. The mesh's stated intent is that it creates no
|
|
symlinks at all — the rule is not merely "only the installer may link", and a founding document
|
|
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](../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](../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.
|