ADR-008: The standard repo separates three zones - repo-own, source, shipped


Status	Accepted (2026-07-22); zone mechanics revised by ADR-014 - zones 2 and 3 merged into the single `standard/` tree; stacks clause revised by ADR-016 - per-technology overlays became satellite repos
Date	2026-07-21
Author	Łukasz Bodurka
Tags	structure, repo-layout, dogfood

Context

The 2026-07-21 re-review found the repo failing its own first impression: no root AGENTS.md, marketing and working files (landing.html, wheel experiments, blog drafts, a Polish notes file) loose in the root, and source directories (github/, claude/, agents/, gitleaks/) whose names collide with the dot-dir conventions of a normal repo. An agent (or human) entering could not tell what is this repo's own life, what is the source of the standard, and what is the shipped skeleton. For a repo whose whole pitch is "structure that agents can navigate", that is the one failure it cannot afford.

Options considered

A - Flat root, documented only. Keep everything where it is; a root AGENTS.md maps the zones. Cheapest; but the github/-vs-.github/ class of collision stays, and the root keeps reading as a grab-bag.
B - Three explicit zones, source grouped under one directory (recommended). Zone 1: the repo's own life (governance, backlog.md, tools/, apps/landing-page/, docs/working/). Zone 2: the standard's source, eventually grouped under a single directory (working name: standard/) so nothing in it collides with normal repo conventions. Zone 3: dist/, build output only. Cost: a one-time migration PR that rewrites the reflect.mjs map and internal links (tracked as STRUCT-1).
C - Merge source into dist/ (single tree). One copy, no reflect. Rejected: the divergent class (template vs filled example) genuinely needs two forms, and consumers should receive a clean skeleton, not the factory.

Decision

Option B. Effective immediately: the zones are named, the root AGENTS.md is the map, repo-own public artifacts live in docs/ and apps/; working/idea notes live outside the repo (owner rule, 2026-07-22), and dist/ is never edited by hand. The physical regroup of zone 2 under one directory is executed as a dedicated migration (STRUCT-1) once this record is Accepted - it rewrites the reflect map and many links, so it rides alone.

Two clarifications added while Proposed (owner direction, 2026-07-22):

Zone 3 has two shipped surfaces, and technology never leaks into the first: the universal core skeleton (today dist/ - Layer 1, any language) and per-technology overlays (stacks/<technology>/ - today node-ts; a Python or Go stack slots in beside it without touching the core). A Python adopter takes the core plus their stack; nothing Next.js/TS-flavored may live in the core. (The .mjs verify scripts and the .nvmrc pin are the standard's own toolchain, not a stack choice - documented as such.)
The name dist/ stays (owner decision, 2026-07-22): the owner's own framing settles it - this structure IS the repo's output, and dist/ is literally built by reflect; the name universally reads "generated - do not edit by hand", which is exactly the behavior we want (a skeleton/ invites editing). STRUCT-1 therefore moves zone-2 sources only.

Consequences

Positive: an entering agent reads one file and knows where it is; root stops accumulating strays; the standard models its own taxonomy.
Negative: one migration PR of pure churn (paths, links, reflect map); until then the zone-2 name collisions remain, mitigated only by the map.

Confirmation

Root AGENTS.md exists and names the three zones; reflect --check drift 0 after every zone-2 change; no working/marketing file sits directly in the root.

Revisit when

The regroup (STRUCT-1) turns out to break external links or consumer expectations, or a monorepo layout (apps/) proves overweight for what stays a docs-first repo.

ADR-005 (align-engine is a manifest) - the manifest stays the client layout, unaffected by zone-2 grouping.
STRUCT-1 in backlog.md; the 2026-07-21 re-review notes.