47. The project registry is the folder authority¶
- Status: Accepted
- Date: 2026-10-12
- Deciders: kristof (owner), Claude (orchestrator)
- Amends: ADR-0031 (the alias map becomes the write-time registry once it has entries), ADR-0035 (a populated registry no longer lets a source name a folder)
- Relates: ADR-0015 (
sourcestays provenance), ADR-0024 (which brain; this ADR is which folder inside it)
Context¶
A brain's top-level folders came from whatever the session's cwd was: owner-repo from a git
origin, else the folder name. The Antenna brain grew 41 top-level folders for about 15 real
projects: vault/ and Contexts/ (Relay runs Claude Code in the vault), infra/, k6-tests/ and
lemahieu-shopware/ (non-git parents or repos without an origin), six o2o-Bicycle-leasing-*
folders for one client, and weareantenna-* strays the MCP path wrote without the alias map
(fixed in #324). The alias map existed but was always one step behind: an unknown source created a
folder on its first capture, and a curator could only relayout afterwards.
Decision¶
Once .commonwealth/projects.json has at least one project, it is the only thing that names a
folder. In curate, which every capture path goes through:
- A declared name (
$COMMONWEALTH_PROJECTfrom a host, a manifestproject, an extractor'sproject) resolves against a project's id,customerand newnameslist, on letters and digits only, case-insensitive. - Otherwise the
sourceresolves againstsources, case-insensitive, withowner/*matching a whole org. An exact entry beats a wildcard. - No match: the note is staged without a project. It never auto-promotes,
promote --allandpromote --pr --allskip it, andpromote <id> --project <id>files it (the id must exist in the registry).pendinglabels it with its source. - Allowlist: a git-identity source whose owner appears in no project's sources is refused with
the
outside-registryreceipt. Folder-name and missing sources are not refused; they go to 3.
An empty or missing registry keeps the previous behavior, so single-project brains are unaffected.
Consequences¶
- One project per client is expressible in one entry (
"sources": ["o2o-bicycle-leasing/*"]). - Notes from a person's freelance or personal repos never reach a team brain whose registry doesn't list their org, even if a routing rule sends them there.
- Unassigned notes sit in the per-user
staging/queue, which is local and gitignored, so nothing without a project is published. promote --prnow files underproject ?? source, like local promote (it usedsourceonly).
Alternatives¶
- An
_unsorted/folder in canon: searchable at once, but it becomes a shared junk drawer. - Keep folder-name fallback as identity: it is what produced
vault/andinfra/.