Architecture decisions: *.archify-decision files, decisions: keys in diagrams

- parse, merge and validate decisions (ids, status, elements, diagrams,
  supersedes); strip decisions keys from diagrams and check the ids
- model:validate counts decisions; model:list lists them with status and
  the diagrams that reference them; examples carry decisions
- formats.md and SKILL.md describe the format and when an agent writes one
This commit is contained in:
root-at-skic committed 2026-10-19 23:13:00 +03:00
1 parent 90a0c0d109
commit b169034b4f
15 files changed
+276 -11

No files matched your search

+39
View File
@@ -100,3 +100,42 @@ For each diagram file under the root (and a single file outside a model):
5. Hand the result to `archify validate <kind> <json> --json` (or `render`).
`task model:resolve -- --file=… --out=x.json` writes step 4's result.
## `name.archify-decision`
One architecture decision of the model, anywhere under the root (`decisions/` by convention):
```yaml
schema_version: 1
decision:
id: queue-between-api-and-worker # unique in the model; words, or a quoted number
title: A queue between the API and the worker
status: accepted # proposed | accepted | superseded | rejected
date: 2026-09-16
elements: [api, queue, worker] # registry ids
diagrams: [0200-containers/online-shop.archify]
supersedes: [] # ids of older decisions this one replaces
context: >
Why a decision was needed.
decision: >
What was decided.
consequences: >
What becomes easier, harder, or must change.
```
Checks (`model:validate`): id present and not a bare number, status known, every element in a registry, every diagram present, every superseded id present. A decision that another one supersedes is shown as superseded whatever its own status says.
Diagrams point back with a `decisions` list on the diagram itself, on a node (component, node, participant, state) and on an edge (connection, edge, flow, transition, message):
```yaml
decisions: [postgres-as-source-of-truth]
components:
- ref: queue
pos: [460, 360]
size: [130, 60]
decisions: [queue-between-api-and-worker]
connections:
- { from: api, to: queue, label: enqueue, decisions: [queue-between-api-and-worker] }
```
The resolver strips the key before Archify sees the diagram and reports an unknown id at its line. Outside a model the key is an error, like `ref`. The extension shows decisions on the `main.archify` page, in a Decisions panel under each diagram, on element cards, and opens a decision file as its own page.