jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
2.9 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-07-10 | jochen | true |
10. Applications live in their own repository; the monorepo is for the mesh
Reconstructed after the fact from the evidence cited below.
Context
The module system makes adding anything to the monorepo trivial — a directory and a manifest. That ease is the problem. Standalone applications, sites and side-projects accumulated beside the mesh's own components, and once there they inherited the monorepo's review cadence, its pipeline detection, and its history.
The mesh's own code and an application that merely runs on the mesh have nothing in common except the manifest format. They change for different reasons, are reviewed by different criteria, and have no reason to share a branch.
Considered options
- Everything in the monorepo. Rejected — it is what existed. The monorepo becomes an inventory of one installation's applications, and every application change queues behind mesh review.
- A second monorepo for applications. Rejected: the same coupling with an extra name. Applications have no more in common with each other than with the mesh.
- One repository per application, registered with the mesh as a build source. Chosen.
Decision
Every standalone application, site or side-project lives in its own repository, with a manifest at the root. It registers with the mesh as a build source and is then built, provisioned, deployed and verified by exactly the same pipeline as anything in the monorepo.
The monorepo holds the mesh: the runtime, the core modules, the delivery machinery, and the shared infrastructure the mesh itself provisions against.
Creating an application directory in the monorepo is a convention violation, and reviewers reject it.
Consequences
- An application's cadence is its own. It is not reviewed as mesh code and does not queue behind mesh work.
- The separation is safe only because the pipeline and provisioning are identical either side of it — which ADR 0007 is what makes true. Without standalone packages this decision would fork the build.
- The monorepo stops being an inventory of the installation, which is a precondition for publishing anything about it.
- Discovery gets harder: there is no single listing of everything the mesh runs, and the registry of build sources becomes the closest thing to one.
- A module source that is not registered is silently skipped by the pipeline. The cost of being outside the monorepo is that being forgotten is possible.
References
- The rule is stated in the governed constitution page authored 2026-07-10, §3, as a convention violation reviewers must reject.
- ADR 0015 decision 4 extends this from new applications to the modules already in the monorepo.
- Knowledge base:
troubleshooting/unregistered-module-source.