novox/hq

Files

T

jschoubben 93a1231e00 Retire the HAL name where it points forward

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.

2026-08-23 21:26:09 +02:00

2.0 KiB

Raw Blame History

name, description

name	description
hq-amend-design	Use when an HQ design document must change, or when an as-is document is found to be wrong about what the mesh actually does. Triggers on "the design changed", "that's not how it works any more", "update the as-is", "this shipped differently".

hq-amend-design

Changes a design document. Authoritative playbook: 00-META/process/02-graduation.md.

Which layer is being changed

Establish this first — the two amend for opposite reasons.

Layer	Amend when	Requires
`01-to-be/`	The intention changed	A decision record. Always.
`00-as-is/`	The mesh changed, or the document was wrong about it	Evidence from the implementation. Never a decision.

An as-is document is corrected against what the code does, not against what anyone meant. If the implementation and the intention disagree, the as-is document records the implementation and says they disagree.

Amending the to-be layer

Write the decision record. If it reverses an earlier one, that record gets status: superseded and superseded-by: — its text is never edited.
Edit the design; set updated: to today.
If this came from an issue, set that issue's amended-design:.

Amending the as-is layer

Establish what is actually true — from the code, a pipeline log, a live query, the operational record. Not from a design document.
Edit the document. Set updated: only if the implementation state changed; a correction to text that was always wrong does not change it.
If the correction reveals that something shipped differently from its design, say so in the as-is document and leave the to-be document alone. That divergence is a finding, and may deserve an issue.

Do not

Do not put a future intention in an as-is document.
Do not quietly fix a wrong claim that held up a decision. Record that it was wrong and where it was relied on — that is the failure this repository exists to name.

2.0 KiB Raw Blame History