jschoubben
3f6d939930
papa-hq has no ledger. Its root is AGENTS.md, CLAUDE.md, README.md, every decision is a numbered record, and its graduation playbook has no path for an unrecorded decision. hal-hq now matches. The ledger's 41 entries classified as: 10 restating a record, 11 restating design docs, 15 describing how this repository works with the reasoning sitting in a README rather than anywhere citable, 3 small rules with no home, 2 superseded stubs. Mostly a copy — and a hand-maintained index, the exact pattern ADR 0022 had just rejected for the decision index on the grounds it drifted after one addition. Keeping one copy of that while removing another is not a position. It also collided by name with 02-DECISIONS/ in any directory listing. Nothing was dropped. Records 0019-0025 give the repository decisions the reasoning they never had: HQ is its own repository and is public, design has two layers, work moves through playbooks, status lives in frontmatter, issues have a front door, the numbering is the flow, HQ is the source of the constitution. 0026 records the ledger's own removal. The three orphan rules went to how-we-build, where a rule is enforced and keeps the incident that earned it — the package rule was genuinely unwritten anywhere. Two lab decisions stated only in the ledger went into the lab design. "Deliberately not decided" went to the research effort and design document each question actually belongs to. The chronological view the ledger provided is now generated from record frontmatter, which is what it was for. The cost, stated in 0026 rather than glossed: a record is more work than a table row, so the risk is a small decision going unrecorded because nobody wanted to write a document. how-we-build takes rules cheaply, which is the mitigation, not a solution.
9.9 KiB
status, updated, derives, decisions
| status | updated | derives | decisions | |
|---|---|---|---|---|
| canonical | 2026-08-23 | knowledge-base constitution page |
|
How we build
The rules that hold across the mesh. Short, and each one earned.
This document is the source of the mesh constitution. The governed page the mesh injects
into design sessions is derived from it, section for section, and carries the rules without
the reasoning. Never edit that page directly — an edit there survives until the next sync and
then vanishes, taking its reasoning with it. The sync is playbook
process/05-constitution-sync.md, and it is how the claim
"HQ is the source" is checked.
Section numbers are stable. The orchestrator and the review fragments cite them.
1. Purpose
These are the principles and guardrails every piece of work in the mesh is checked against — design sessions, analysis gates, reviews, and agents acting on their own. A rule stated here is non-negotiable unless amended per §6.
They exist because each was violated first. Where a rule reads as arbitrary, that is a sign the incident behind it is not written down, and the fix is to write it down, not to relax the rule.
2. Non-negotiables
| Rule | What it means |
|---|---|
| Never write to a production database directly | No insert, update, delete or schema statement executed against production by hand. Schema changes go through numbered migrations; data changes go through application code or the module's own capabilities. Raw statements skip every side effect the proper path has — events, audit, cache invalidation, fan-out. |
| Every schema change is a migration | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation and an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. ADR 0006 |
| Never bypass the pipeline | No manual database edit, no manual restart as a workaround. Fix the cause and deploy. A workaround that works is a workaround that is never removed, and the next person cannot tell the node from its declaration. |
| Never create a symlink | A hand-made link caused production data loss through container volume resolution, and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. Today the installer owns and reconciles the links the mesh still uses ADR 0011; the intent is that the mesh creates none at all ADR 0018. Neither reading permits you to make one. |
| Never push directly to the main branch | Branch, push, review, merge. Every merge is a human checkpoint, without exception. |
| One change per pull request, and never merge your own | Unrelated improvements bundled together cannot be reviewed or reverted separately. Self-merging removes the checkpoint that is the entire point. |
| Never open a pull request unprompted | A permissions list saying it is allowed is not a request. |
| A failed step fails the job | A sequence that continues past a failure does the next thing in the wrong place. Gate each step on the last. ADR 0008, and §5. |
A failed step must stop the steps after it — how it was earned
A worktree creation failed because the branch name collided with an existing namespace. The change into that worktree failed too. The copy, the staging and the commit that followed all ran in the shared checkout and committed to a local main. The error was printed and scrolled past.
This is the same shape as the faults the mesh's whole refactor exists to remove: a step reported failure, nothing stopped, and the damage happened somewhere nobody was looking.
3. Module and infrastructure rules
Manifests
- Never bump a version by hand. The builder owns versioning. A version change in a diff is a defect; revert it.
- Features are detected, not declared. The installer discovers what a module carries from what its directory contains. A declared list and the directory it describes drift, and the directory is the one that is true.
- Every runtime variable is declared. A variable the module reads and the manifest does not declare is invisible to the mesh: it will not be generated, injected, or audited.
- Provisioned credentials arrive through declared requirements, never hardcoded in code, compose files or scripts. ADR 0005
- Never install a package by hand. A package is declared in the manifest and arrives the way every other package does. A hand-installed package is invisible to the mesh: it is not declared, not reproduced on the next node, and not present after a rebuild — and the node works until it doesn't.
Placement
- Core modules belong to the monorepo — the runtime, delivery, provisioning, configuration, knowledge, and the shared infrastructure the mesh provisions against.
- Every standalone application gets its own repository, with a manifest at its root, registered as a build source. Creating an application directory in the monorepo is a convention violation and reviewers reject it. ADR 0010
Migrations
- Numbered, idempotent, and safe to re-run. Guard every statement.
- The initial migration is frozen once it has run anywhere. Change is a new number.
- Numbers are unique. A duplicate prefix is a defect, not a style question.
Managed files
A file edited on a node is a bug with a delay on it. Everything under the mesh's managed surface is regenerated from the mesh database; a local edit survives one synchronisation and is then silently overwritten, bringing back whatever it fixed. Use the mesh operation that owns the value. If unsure whether a file is managed, ask the tooling — the answer is not visible from the file. ADR 0004
4. Naming and boundaries
Name a context after its aggregate, not after a metaphor
A context named agents owns Agent. A brain — memory, thoughts, cognition — is something
an agent has: a concept inside the aggregate, not a module.
The cost of getting this wrong is visible today. An anatomy name points at the node runtime, so the most evocative word in the system names infrastructure; another describes itself as "mesh messaging" in its manifest while the anatomy documentation calls it the interactive runtime — and it runs on no node at all.
Anatomy makes attractive names and poor boundaries. Name the thing the domain calls it.
Group by domain, not by single function
A module is a purpose, not a piece of software. Four modules that together constitute "how a node is reachable" and cannot be assigned, versioned or replaced as one thing are four accidents, not four boundaries. ADR 0017
Contexts integrate through the record, never through a shared schema
Publish to the stream; do not join across a boundary. Today several domains share one forty-five-table schema, which is why work belonging to one context keeps having to be implemented in another.
5. Evidence and verification
Ubiquitous language is checked, not assumed
If a document states a rule about the mesh, it says how the rule is verified. This repository has a documented requirement that every capability-exposing module declare the core runtime as a dependency. Zero modules do.
An unenforced rule is indistinguishable from a wrong one, and costs more, because people believe it.
Behavioural criteria require runtime evidence
A criterion of the form "the script runs", "the endpoint answers", or "the migration applied" is satisfied only when the change has actually been exercised: a real run, a real request, a pipeline log, a live query showing the expected result.
Marking a runtime criterion verified from a diff is itself a violation. A reviewer who finds one names the evidence required and returns the work.
The reason is the mesh's most consistent failure shape: a green result proves transport, not effect. Absence reads as success unless something looked.
Search the record before forming a hypothesis
The first action on any error message, failing service or unexpected behaviour is to search the operational memory for the literal error text — before a hypothesis, not after one fails. The knowledge base is indexed on symptoms.
This fires hardest on familiar ground, where a confident trail feels like progress. Two entries were each rediscovered from scratch over several hours in a single session because the search was skipped. Both were already written down.
6. Amendment
This document is governed. It does not change by commit message or unilateral decision.
- Propose — a change stating what rule is changing, why the current wording is inadequate, and what reviewed it.
- Review — sign-off by reviewers who are not the proposer.
- Record — the change is a decision and gets a record in
02-DECISIONS/, because a rule the mesh enforces is architecturally significant. - Sync — playbook
process/05-constitution-sync.mdpublishes the derived page. An unsynced rule is a rule the mesh does not enforce, whatever this document says.
No drive-by edits. Every change traces to a recorded decision.
7. Overrides
A team or product may define additional constraints that narrow or tighten these rules. They may never relax them.
An override says which rule it tightens, or which gap it fills, and follows the same amendment process. Absence of an override means these rules apply unmodified.