novox/hq

Files

T

jschoubben 1c808898a5 Allow progressive insight, and apply two to the bus record

A record can assert a fact that goes stale while the decision it supports
stays right. Superseding for that buries a sound record under a second one
and makes every reader work out which is live. So a correction of fact is
now made in place, marked and dated, with the old wording quoted — bounded
by three conditions and checked by records.py, which fires on an unmarked,
undated or back-dated note. Judgements still supersede.

Applied to 0115: no conformance suite exists to recapture, and the full
genesis bed cannot run until the links exist. Designs 25 and 28 follow.

2026-09-26 18:39:38 +02:00

5.5 KiB

Raw Blame History

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). Implementation lives in the code repositories (see 00-META/repos.md).

Before changing anything here, read the playbooks in 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) or a symptom (playbook 03 — issues), becomes a decision (02-DECISIONS, via playbook 02), lands in a to-be design naming that decision, is handed to a code repository (playbook 04, on a feature branch per playbook 07) — 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 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`
How do I do X in this repo?	`00-META/process/` — the playbook index is in `00-overview.md`
What was decided, and why?	`02-DECISIONS/README.md` (reading order), then the record
What is being built / already runs?	`03-DESIGN/01-to-be/` / `03-DESIGN/00-as-is/` — each doc's frontmatter says its status, decisions and owning code
What is broken or was?	`04-ISSUES/` — frontmatter carries status/owner/fix
Which repo owns what code?	`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 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. 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). 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/ describes the mesh that exists; 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. 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.

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.

5.5 KiB Raw Blame History