jochen
2221be11a6
mesh/merge-gate the mesh is checking this head against every machine
mesh/delivery delivered
Turning the merge check on for every repository showed it asked the wrong questions: a repository chose whether it was checked, the gate mapped a change onto modules its own way, the shared-code rule rebuilt 103 modules for a root script, and nothing kept a commit off the trunk from becoming a module's version. Records the operator's decisions, narrows ADR 0237 decision 4, revises to-be 45 §9 and Phase 5 and to-be 30, closes issue 280's left-open, and gives this repository its own merge-check.sh.
90 lines
5.8 KiB
Markdown
90 lines
5.8 KiB
Markdown
# Agent instructions — Novox HQ
|
|
|
|
This repository is the source of truth for Novox's mission, research, design and decisions —
|
|
today almost entirely those of **Novox Mesh**, its first product ([ADR 0019](02-DECISIONS/0019-how-this-repository-works.md)). Implementation lives in the code repositories (see
|
|
[`00-META/repos.md`](00-META/repos.md)).
|
|
|
|
Before changing anything here, read the playbooks in
|
|
[`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
|
|
(`hq-new-research`, `hq-graduate`, `hq-new-issue`, `hq-diagnose`, `hq-amend-design`,
|
|
`hq-handoff`, `hq-sync-constitution`, `hq-status`); each defers to its playbook as
|
|
authoritative and adds only the mechanical scaffolding.
|
|
|
|
## The development cycle
|
|
|
|
Work enters as an **idea** (playbook [01 — research](00-META/process/01-research.md)) or a
|
|
**symptom** (playbook [03 — issues](00-META/process/03-issues.md)), becomes a **decision**
|
|
([02-DECISIONS](02-DECISIONS/), via playbook [02](00-META/process/02-graduation.md)), lands in a
|
|
**to-be design** naming that decision, is handed to a code repository (playbook
|
|
[04](00-META/process/04-build-handoff.md), on a feature branch per playbook
|
|
[07](00-META/process/07-feature-branches.md)) — and on shipping the as-is is updated and the
|
|
design flips to `implemented`. **No design without a decision; no development without a design
|
|
that names its owner.** Enforced by [`00-META/checks/cycle.py`](00-META/checks/cycle.py)
|
|
alongside `records.py` and `index.py` — run all three before any merge here.
|
|
|
|
## Where to look (before assuming anything)
|
|
|
|
| Question | Read |
|
|
|---|---|
|
|
| What does this word mean? | [`00-META/glossary.md`](00-META/glossary.md) |
|
|
| How do I do X in this repo? | [`00-META/process/`](00-META/process/) — the playbook index is in `00-overview.md` |
|
|
| What was decided, and why? | [`02-DECISIONS/README.md`](02-DECISIONS/README.md) (reading order), then the record |
|
|
| What is being built / already runs? | [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) / [`03-DESIGN/00-as-is/`](03-DESIGN/00-as-is/) — each doc's frontmatter says its status, decisions and owning code |
|
|
| What is broken or was? | [`04-ISSUES/`](04-ISSUES/) — frontmatter carries status/owner/fix |
|
|
| Which repo owns what code? | [`00-META/repos.md`](00-META/repos.md) |
|
|
| Cross-cutting status view? | the `hq-status` skill (generated, never stored) |
|
|
|
|
Statuses live **only** in frontmatter; follow the pointers there (`decisions:`, `code:`,
|
|
`became:`, `fixed-by:`) instead of reconstructing history from memory.
|
|
|
|
## Words
|
|
|
|
One name per thing. [`00-META/glossary.md`](00-META/glossary.md) is the authority on
|
|
vocabulary — *controller* (not "control plane"), *foundation* (not "substrate"), *node* and
|
|
*control-node*, *seat* / *bench* / *claim*, *package* vs *artifact*. Use those words.
|
|
|
|
## Ground rules
|
|
|
|
- **Markdown only** — but for the checks in `00-META/checks/` and `merge-check.sh` at the root, which
|
|
runs them on every pull request as its `mesh/repo-check` ([ADR 0238](02-DECISIONS/0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)).
|
|
No new top-level folders without explicit confirmation.
|
|
- **Status lives in YAML frontmatter** — on research overviews (`status`, `became`), design
|
|
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.
|
|
- **`02-DECISIONS/` records hold their meaning.** Supersede with a new record rather than rewriting
|
|
what was decided, the options weighed, or a consequence another record relies on. Fixing a broken
|
|
link or path is allowed, and so is a **progressive insight** — a correction of *fact* that leaves
|
|
the decision standing, made in place, marked and dated in the record's own words
|
|
([`02-DECISIONS/README.md`](02-DECISIONS/README.md)). A fact going stale is not the decision going
|
|
wrong, and superseding a sound record for one buries it.
|
|
- **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.** [`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-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-META/process/05-constitution-sync.md). Never edit the
|
|
derived page directly.
|
|
|
|
## This repository is public
|
|
|
|
Nothing here may contain routable addresses, real domain names, hosting providers, node
|
|
names, absolute paths, usernames, credentials, or operational detail useful only to an
|
|
attacker. Use documentation ranges (RFC 5737, RFC 1918) and role names — `anchor`,
|
|
`home-server`, `workstation`, `laptop`, `the build node`, `the broker node`.
|
|
|
|
The test: would this paragraph still teach a stranger running an entirely different mesh?
|
|
If yes, it belongs. If it only makes sense to someone who knows this installation, it is
|
|
either a note in the wrong place or a disclosure. The full rule is in
|
|
[`README.md`](README.md).
|
|
|
|
## A rule states how it is checked
|
|
|
|
If a document states a rule about the mesh, it says how that rule is verified. An unenforced
|
|
rule is indistinguishable from a wrong one, and costs more, because people believe it.
|