living-architecture · diff
git:20261024.181dec5 to git:20261109.20ba352
48 added, 26 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: living-architecture
- description: Reference for the living-architecture layer (LikeC4 structure model + arc42 principles + model-truth import enforcement + cross-check) — its syntax, the checks, and how to maintain it alongside the /la:pr + OpenSpec flow. Building the first model is la:arch-init; carving a boundary is la:arch-cleanup.
+ description: 'Reference for the living-architecture layer (LikeC4 structure model + arc42 principles + model-truth import enforcement + cross-check): its syntax, the checks, the rules a coding agent follows when it changes code under it, and how to maintain it. Building the first model is la:arch-init; carving a boundary is la:arch-cleanup.'
---
**Preflight:** run `la-doctor --plugin <this skill's base directory>` once per session before using any `la-*` or `dr-*` command; if it fails, stop and show the user its output.
# Living architecture
- Four layers, one element id everywhere. Behaviour lives in OpenSpec; everything
+ Four layers, one element id everywhere. Behaviour lives in OpenSpec (in repos that use it); everything
cross-cutting lives here:
| Layer | Question | Artifact | Property |
|---|---|---|---|
| Behaviour | what does it do, now? | `openspec/specs/<id>/spec.md` | living, merged by OpenSpec |
| Structure | how is it arranged, now? | LikeC4 model + views | living; ONE model, diagrams are projected views |
| Rationale | why is it this way, and what must all code here obey? | arc42 file per element that earns prose | living, edited in place |
- | Enforcement | is the code actually like this? | `arch_check` model-truth (the one import law) + LikeC4 model validation, run in the flow gates | executable, blocking |
+ | Enforcement | is the code actually like this? | `arch_check` model-truth (the one import law) + LikeC4 model validation, run before a change is done and in CI | executable, blocking |
- **History is NOT a layer here.** The openspec archive (per-change design +
- deltas, dated, immutable) plus git history IS the decision trail. Never create
+ **History is NOT a layer here.** Git history, plus the OpenSpec archive (per-change
+ design + deltas, dated, immutable) in repos that use it, IS the decision trail. Never create
ADR files or append-only decision logs (they are merge hell). "Why it is like
- this now" belongs in the element's arc42, present tense; "how we got here" is the
- archive.
+ this now" belongs in the element's arc42, present tense; "how we got here" is
+ history.
## Alignment rules
- **arc42 = LikeC4 = module structure align perfectly.** An element's fully qualified id is its LikeC4 id
and names its arc42 file, `architecture/<id>.arc42.md`; a precise element's package is its node's `package` plus
its path below the node.
- **OpenSpec is looser.** A spec either belongs to one element at any depth (listed in that element's
metadata `specs` — the element is then a behaviour *leaf*) or is **cross-cutting** (listed once in `index.yaml`
with the fully qualified elements it touches, at any depth). Never duplicate a spec across elements; `arch_check`
enforces exactly-once.
- **Model depth is a dial, not an obligation.** Model precisely where you are
actively enforcing boundaries; sweep the rest into a few *virtual bucket
nodes* (tagged `#virtual`, claiming several packages, no alignment claim,
governed only at bucket granularity — no nested elements, no child-level arrows).
Deepen a bucket into precise nodes the first time real
work touches it. Never model deeper than you're willing to keep true.
## File layout — the tree is virtual
Each tool keeps its native layout; shared node ids join them. The LikeC4 model
maps nodes to code; `index.yaml` holds only repo-wide settings.
```
repo/
openspec/specs/<spec-id>/spec.md
architecture/
model.c4 # the ONE LikeC4 model: one specification and one model block
views.c4 # one views block; each view scoped to one language root
index.yaml # repo-wide settings (below)
system.arc42.md # root narrative + global principles
<element id>.arc42.md # e.g. python.sql.arc42.md; only where an element earns prose
living-architecture.yaml # repo config: format, and architecture: true once the model exists
```
Every arc42 file sits directly in `architecture/`, never in a subfolder.
These are the only LikeC4 files allowed anywhere under `architecture/` (`.c4` or
`.likec4`). Nothing else may sit at their top level. Any other layout makes
`la-arch-check` exit 2 and `la-arch-diagrams` exit 1, with one message naming
every violation. The repo's format is `format` in `living-architecture.yaml`:
the `la` version that introduced it. Every command refuses any other format,
naming the `la` to upgrade to for a newer one and `la-arch-migrate` for an older
or missing one; `la-arch-migrate` converts the repo (verified, all-or-nothing)
and stamps the current format.
The checker is `la-arch-check` (the one import law + cross-check, run by the
gates); it needs no per-repo code. `la-arch-diagrams` regenerates the embedded
view diagrams.
The model has one top-level **root element per language** `index.yaml` declares,
whose id is the language (`python`, `typescript`); it carries no mapping metadata. A node
is a direct child of a root; it is virtual iff its element kind is declared
`#virtual`. Relations are written inside a root with names relative to it
(`sql -> core` inside `python { }` is `python.sql -> python.core`), so a relation
across roots cannot be written. Element ids are fully qualified in findings and
in `touches:`. Any element — root, node or nested — MAY list the `specs` it owns in one `metadata { }`
block; a node also declares its mapping there:
```
specification {
element node
element bucket {
#virtual
}
tag legacy
tag virtual
}
model {
python = system 'My package' { // the python root (any element kind)
sql = node 'SQL' { // precise node python.sql
metadata {
package 'mypkg.sql' // required
claims ['mypkg.sqlutil'] // optional: further units it owns
specs ['sql-dialects'] // specs owned by THIS node alone
}
// arc42 doc, if any: architecture/python.sql.arc42.md
render = node 'Render' { metadata { specs ['sql-render'] } } // maps to mypkg.sql.render; nested elements may own specs
dialects = node 'Dialects' // maps to mypkg.sql.dialects
}
surfaces = bucket 'Surfaces' { // virtual bucket
metadata {
packages ['mypkg.api', 'mypkg.mcp', 'mypkg.cli']
}
}
surfaces -> sql
}
}
```
TypeScript units are extensionless paths relative to the section's
`source_root` (`package 'src/daemon'`, nested `pty` maps to `src/daemon/pty`); a
unit is a directory with a visible source file or exactly one module file, and a
unit naming both is ambiguous. Test files, declaration files
(`la-config get lang.typescript.declaration_globs`) and installed dependencies are
invisible; type-only imports never count.
Keys and types come from the shared node schema; values are `key 'value'` or
`key ['a', 'b']` — single quotes, no escapes, arrays may span lines, no trailing
comma. Nested elements, at any depth, carry no mapping keys: `<node>.a.b` maps to `<package>.a.b`, and the
import law applies wherever the model nests. Malformed metadata is a setup error (exit 2) naming the element; a
model still using the retired `arc42` key converts with `la-arch-migrate`.
`index.yaml`:
```yaml
python: # one section per language; at least one
root_package: mypkg # required: the unit of the python root
source_root: src # optional: directory containing root_package
typescript:
root_package: src
source_root: web # optional
tsconfig: web/tsconfig.app.json # optional: default the nearest tsconfig
legacy_arrows: {baseline: 8} # exact count of #legacy arrows in the model (ratchet)
cross_cutting_specs:
queries: {touches: [python.core, python.engine, python.sql]}
x-anything: {} # repo-owned keys start with x-; the tools ignore them
```
`views.c4` scopes each view to a root, `view <id> of <root> { ... }`, with include names and predicate
anchors relative to the root at any depth (`include api.handlers`, `api.handlers -> *`); the root itself is never
drawn.
## arc42 element file — required shape
arc42-lite, per element, always present tense, updated in place:
1. **Purpose & context** — 3–10 lines.
2. **Building blocks** — pointer to the node's LikeC4 view. Never a duplicate
drawing, never a prose restatement of the model.
3. **Principles** — numbered rules that ALL code in this element and its descendants, old and new,
MUST obey. Each tagged `[enforced: <check|test id>]` or
`[review]`. Prefer enforced; every `[review]` principle is a standing
candidate for a new fitness function. Keep them normative and minimal: when
work strains a principle, first make the code comply; edit one only when it
genuinely forbids something needed, in the smallest general wording — never
descriptive text or implementation detail (function names, mechanisms).
4. **Rationale** — why the current shape is right. Where it derives from a
specific change, link the archived openspec change id — do not restate
history.
## Enforcement wiring — the one import law
There is no separate import-linter config: the entire import law lives in the
LikeC4 model and is checked by `la-arch-check` (**model-truth**). The
model's relations must exactly match the AST-measured runtime import edges, at
every granularity the model declares:
- a module attributes to its finest mapped element, else its node;
- every edge is licensed by its most-specific covering arrow — a declared
arrow is the only thing that permits an import, and silence is a ban;
- a measured edge with no covering arrow, a declared arrow with no measured
edge, and an undeclared edge between two nested elements are all findings.
Type-only imports are excluded. Grandfathered crossings are dashed
`#legacy` arrows in the model itself (one arrow per real edge, no wildcards);
"layer direction" is just *no upward arrow declared*, and a child boundary is
just *no arrow declared between those nested elements* — so one law subsumes what used
to be separate `layers` / `forbidden` / boundary contracts.
Python edges come from `ast`, TypeScript edges from the TypeScript compiler
under the repo's tsconfig. Either twin checks a mixed repo: each language's facts
come from its own twin (PyPI or npm, found on PATH or run through `uvx`/`npx`), and
model-truth runs once over all of them.
**The enforcement bundle** = `la-arch-check` + LikeC4 model validation
(`npx likec4 validate`; if the installed CLI version lacks it, use the lightest
command that parses the model, e.g. `npx likec4 build`) + `la-typecheck` against
- its committed baseline. It runs, blocking, in:
- - the **pr-review** gate (that stage runs it when `architecture: true`),
- - the **arch-cleanup** move gate,
- - CI — `arch_check` is cheap and deterministic, so wire it there once the setup
- has settled (not at init), pinned to a release, in the form of the repo's
- ecosystem: `uvx --no-build --from living-architecture==<version> la-arch-check`
- (after `astral-sh/setup-uv`, pinned by commit SHA) or
- `npx -y -p living-architecture@<version> la-arch-check` (after
- `actions/setup-node`, pinned by commit SHA).
+ its committed baseline. It is blocking: run it before declaring any change done,
+ and in CI. `arch_check` is cheap and deterministic, so wire it there once the setup
+ has settled (not at init), pinned to a release, in the form of the repo's
+ ecosystem: `uvx --no-build --from living-architecture==<version> la-arch-check`
+ (after `astral-sh/setup-uv`, pinned by commit SHA) or
+ `npx -y -p living-architecture@<version> la-arch-check` (after
+ `actions/setup-node`, pinned by commit SHA).
**Ratchet rules (hard):**
- `#legacy` arrows may only ever be REMOVED, never added. Wanting to add one
means the architecture is changing — change the model and arc42 deliberately
instead, with the user's explicit OK.
- `legacy_arrows.baseline` in `index.yaml` is the exact `#legacy` count;
`arch_check` fails if the model's count differs, and the baseline is lowered
as arrows are retired. Progress is monotonic and machine-checked.
**`la-arch-check` verifies, from the model and `index.yaml`:**
- `architecture/` holds exactly `model.c4` and `views.c4`, each with only its blocks (else exit 2);
- every element's metadata matches the shared schema (else exit 2);
- every precise node's `package` and `claims` (and every bucket's `packages`)
exist on disk; every nested element's unit exists under its node's package
and does not collide with another declared unit; a bucket contains no
elements; every arc42 file sits directly in `architecture/` and is `system.arc42.md`,
`<element id>.arc42.md` of a model element, or listed in `cross_cutting_arc42`;
- every top-level unit of each language's `root_package` is claimed by exactly
one node — no orphan packages;
- every spec group (a directory under `openspec/specs/` or under a non-archived
change's `specs/`) is mapped exactly once: in exactly one element's `specs`
or in `cross_cutting_specs:`; every element named in a `touches:` list exists;
- model-truth holds at every declared granularity, the `#legacy` count equals
`legacy_arrows.baseline`, and each mapped doc's embedded view diagram is
byte-fresh;
- every principle item in an arc42 file carries a status tag —
`[enforced: arch_check:<check-id>]`, `[enforced: test:<path>]`, `[review]`,
or `[target: <issue key>]` (a future-state clause; keys must match the
repo's `issue_key_pattern`); an item may add one `[lang: <language>]` naming
a declared language it alone binds.
## Maintenance
- No model yet (`architecture/index.yaml` absent) → run the **la:arch-init**
skill; it builds the first model from a measured scaffold.
- Otherwise keep the model, `index.yaml`, and arc42 in sync IN THE SAME PR as
any structural change; deepen buckets / add views for new subsystems; tighten
boundaries via the **la:arch-cleanup** skill.
- ## Interaction with /la:pr
+ ## Working under the architecture
- - At pr-plan time, read `architecture/index.yaml` and the model plus the arc42 file and view of every element the change
- touches and of each of its ancestors. The plan must state which principles apply,
- and must not violate the model's import law — or must explicitly include the
- model + arc42 change as part of the same change.
- - At pr-review time, the enforcement bundle is part of the convergence gate.
- - New capability → decide with the user where its spec attaches (one element's metadata `specs`, at any depth, or `cross_cutting_specs` in `index.yaml` with a
- `touches:` list) and record it in the same change.
- - Pure structural refactors (moving code across boundaries) are their own
- changes via **la:arch-cleanup** — never smuggled into feature PRs.
+ These rules bind a coding agent at every step of any change in a repo with an
+ `architecture/` directory at its root: planning, writing tests, implementing,
+ and fixing review findings. `architecture/*.arc42.md`, `architecture/model.c4`
+ and `architecture/views.c4` are normative harnesses, exactly like tests.
+
+ - **Read them first.** Before the work, read `architecture/index.yaml`, the
+ arc42 file of each element the change touches and of each of its ancestors
+ (`architecture/<element id>.arc42.md`, where present), `system.arc42.md`
+ (cross-cutting principles), and the LikeC4 view of every touched element.
+ - **Obey them.** Every plan, test, implementation and fix obeys the element
+ principles and the model's import law, or explicitly includes the model +
+ arc42 update as part of the change. A plan states which principles apply.
+ - **Flag, never deviate.** If anything in an arc42 file seems wrong,
+ contradictory, or makes the task impossible or substantially harder, flag it
+ to the user explicitly and wait for their call. Never silently deviate from,
+ reinterpret, or ignore a principle, and never produce work that quietly
+ conflicts with one.
+ - **Keep them normative and minimal.** When work strains a principle, first make
+ the code comply; propose an edit only when the principle genuinely forbids
+ something needed, in the smallest general wording. Never use descriptive text
+ or implementation detail (function names, mechanisms).
+ - **Never edit without per-change approval.** Never create, modify, or delete a
+ harness without the user's explicit approval of that specific edit: present
+ the exact edit and wait for the OK. An approved plan that mentions the edit
+ does not count.
+ - **Finish green.** Before declaring the change done, run the enforcement bundle
+ and fix until it passes.
+ - **New capability** (OpenSpec repos): decide with the user where its spec
+ attaches (one element's metadata `specs`, at any depth, or
+ `cross_cutting_specs` in `index.yaml` with a `touches:` list) and record it in
+ the same change.
+ - **Pure structural refactors** (moving code across boundaries) are their own
+ changes via **la:arch-cleanup**, never smuggled into feature changes.