archik 0.20.0 → 0.22.0

package/README.md

@@ -70,6 +70,7 @@ Day to day:
 | You type | You get |
 | --- | --- |
 | `/archik:suggest <feature>` | A staged diagram change, shown as a green/red diff on the canvas — accept or reject |
+| `/archik:realize` | Make the code match the model the architect changed (works `archik gap` until empty) |
 | `/archik:evolve [area]` | A proposed cleaner refactor, backed by drift and smells |
 
 Already have docker-compose or Mermaid? Bootstrap from it instead of a blank canvas:
@@ -110,6 +111,23 @@ There are no coordinates — layout is computed by [ELK](https://eclipse.dev/elk
 | --- | --- | --- |
 | Structure | `.archik/main.archik.yaml` | Services, databases, queues, agents, LLMs, edges |
 | Sub-architecture | `.archik/*.archik.yaml` | A node's internals, linked via `archikFile` |
+| Decisions | `.archik/decisions/NNNN-*.md` | Why each accepted change was made — context, decision, alternatives, consequences |
+
+**Steer by moving boxes.** The architect changes the architecture directly on the canvas — drag a node into another module (or out to the top level), draw or delete an edge, set a layer — and saves it with a short "why" (the decision record). A moved component becomes a *pending move*. `archik gap` (and the **Code gap** panel on the canvas) then lists exactly what the code must change: move or create code, remove or add imports, fix style breaks, finish nodes whose code landed. "Copy task for your agent" hands it to Claude Code as `/archik:realize`; the agent works the list until the code matches the model.
+
+**Architecture style.** The architect picks the structure the code must follow — `layered`, `hexagonal`, `clean`, `modular-monolith` or `feature-slices` — with `style:` in the root file and a `layer:` on top-level nodes. archik enforces it on every change (validate, suggest set, canvas save reject a dependency that breaks it), draws the board in the style's lanes, and tells agents where each node sits and what it may depend on (`archik style`, `archik q describe`).
+
+```yaml
+style:
+  kind: hexagonal        # adapters → ports / core; the core never depends on an adapter
+nodes:
+  - { id: rest-api, kind: module, name: REST API, layer: adapters, ... }
+  - { id: core, kind: module, name: Ordering core, layer: core, ... }
+```
+
+The diagram says *what*; decision records say *why*. Every staged change carries one under `metadata.suggestion.decision` — `suggest set` refuses a draft without it — and accepting the change writes it as a numbered markdown record with the node and edge changes listed as evidence. Records are never edited; a later decision that changes course lists the old numbers in `supersedes`.
+
+Each change is also labelled by how hard it is to undo. A **one-way door** — a new data store, queue, external system, gateway, LLM or top-level module, a removal, or a boundary move — gets its own canvas review before the build plan; if it adds data, an outside system or public traffic, its record must say how it is secured, observed and rolled back. A **two-way door** goes through one combined review of model and plan.
 
 Full schema: `npx archik schema`.
 
@@ -126,7 +144,7 @@ npx archik affected --since main         # changed files → nodes → dependent
 npx archik otel check --graph deps.json  # edges vs a production service-dependency graph
 ```
 
-`validate` proves the model is internally consistent, `drift` that it matches the code, and `otel check` that it matches production traffic. `smells` needs no model: it reports folder loops with the real imports as evidence (only relative imports are resolved, so every loop is real) and points at the cheapest import to cut. Gate every commit locally:
+`validate` proves the model is internally consistent, `drift` that it matches the code, and `otel check` that it matches production traffic. `smells` needs no model: it reports folder loops with the real imports as evidence (only relative imports are resolved, so every loop is real) and points at the cheapest import to cut. On existing code, `archik smells --update-baseline` saves today's findings as known debt, so `--fail-on-warn` fails only on new loops and growing files. Gate every commit locally:
 
 ```bash
 npx archik hooks install       # pre-commit: archik validate
@@ -188,7 +206,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: bacharSalleh/archik@main
         with:
-          smells-fail: true   # optional gate; omit for report-only
+          smells-fail: true   # optional gate; with a committed baseline, fails only on new smells
 ```
 
 Inputs: `path`, `working-directory`, `validate`, `drift`, `smells-fail`, `compare-ref`, `comment`, `github-token`, `version`.
@@ -207,7 +225,9 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik dev` / `start` / `stop` / `status` | Live canvas lifecycle (foreground / detached) |
 | `archik validate [path]` | Schema + cross-file + constraints (exit 1 on error) |
 | `archik complexity [path]` | Flag over-large files, hub nodes, deep nesting (`--fail-on-warn` to gate) |
-| `archik smells [dir]` | Folder import loops + oversized source files, from the code (`--max-file-lines`, `--fail-on-warn`) |
+| `archik gap` | What the code must change to match the model — move / create code, imports, style breaks, finish (`--json`, `--all`, `--fail-on-gap`) |
+| `archik style [list]` | The architecture style: rule, layers / modules, where nodes sit, violations; `list` shows every style |
+| `archik smells [dir]` | Folder import loops + oversized source files, from the code (`--max-file-lines`, `--fail-on-warn`, `--update-baseline`) |
 | `archik render --out <svg>` | Headless SVG render (`--focus <id>`, `--hide-structural`) |
 | `archik watch` | Re-render SVG on every change |
 | `archik q <sub>` | Query: `describe` `deps` `dependents` `neighbors` `impact` `list` `edges` `stats` |
@@ -215,7 +235,7 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik affected` | Changed files → nodes, dependents, model files, unmapped (`--since <ref>`, `--files`) |
 | `archik drift` | sourcePath gaps (`--edges` verifies edges vs the import graph) |
 | `archik otel check --graph <f>` | Verify edges against a production service-dependency graph |
-| `archik suggest <sub>` | Suggestion sidecar lifecycle: `show` `set` `accept` `reject` |
+| `archik suggest <sub>` | Suggestion sidecar lifecycle: `show` `set` `accept` `reject` — accept writes the decision record to `.archik/decisions/` |
 | `archik evolution <sub>` | Self-evolution loop: `enable` `reflect` `proposals` `approve` `reject` `report` |
 | `archik patterns <sub>` | Pattern library: `list` `show <id>` `apply <id>` |
 | `archik import compose\|mermaid [file]` | Bootstrap from docker-compose or a Mermaid flowchart |
@@ -224,7 +244,8 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik owners sync\|check` | Keep CODEOWNERS in step with node owners |
 | `archik mcp` | MCP server over stdio for non-Claude-Code agents |
 | `archik schema` | Print the document schema |
-| `archik upgrade` | Upgrade + refresh installed skill/commands |
+| `archik upgrade` | Upgrade + refresh installed skill/commands (`--migrate` also runs `archik migrate` with the new version) |
+| `archik migrate` | Bring the project's archik files up to the installed version — archives first, validates after (`--dry-run`) |
 
 Default file resolution: `.archik/main.archik.yaml`, falling back to the legacy `architecture.archik.yaml` (both present is an error).
 
@@ -238,7 +259,9 @@ Reach for archik when a project has more than a handful of components, ships wit
 | AI-editor integration | **Skill + MCP** | None | None |
 | Structural smells from code | **Yes** | No | No |
 | Drift detection | **Yes** | No | No |
+| Decision records tied to model changes | **Yes** | No | No |
 | Governance constraints | **Yes** | No | No |
+| Enforced architecture style (layered, hexagonal, clean, modular) | **Yes** | No | No |
 | Validator | **Schema + cross-file + constraints** | Syntax only | Syntax only |
 
 ## Contributing

package/commands/accept.md

@@ -31,7 +31,14 @@ done at step 1 — the diagram changed; the code probably hasn't.
 
 3. **BUILD — plan (HITL).**
 
-   Translate the diagram delta into a numbered file-level
+   **Two-way door shortcut:** if `/archik:suggest` already showed the
+   build plan with this sidecar (two-way door), the accept you just
+   ran approved it — go straight to step 4. One-way doors always get
+   their own plan approval here.
+
+   Start from `npx archik gap --json` — it lists the code work the
+   accepted model now asks for (moves, new code, imports, style
+   breaks). Then translate the diagram delta into a numbered file-level
    plan and present it for approval **before** touching code:
    - Each new code-bearing node (`service`, `function`, `worker`,
      `module`, `page`, `component`, `store`, `hook`, `model`, `dto`,
@@ -42,6 +49,10 @@ done at step 1 — the diagram changed; the code probably hasn't.
      consumer handler; `writes` needs a repository method; etc).
    - Any node still `status: proposed` → flag it; code must land
      before flipping to `active`.
+   - If the accepted decision record has `crossCutting`, each
+     promise becomes a plan item: the security control, the signal
+     (log / metric / alert) and the rollback path (flag, revert,
+     migration down-step).
    - Default to **tests-first** when behaviour is clearly bounded.
    - If `superpowers:writing-plans` is available, use it; else
      inline.
@@ -84,6 +95,11 @@ done at step 1 — the diagram changed; the code probably hasn't.
    Catches folder loops and oversized files, with the real imports
    as evidence. A new loop is a gap — cut the cheapest import (or
    queue a `/archik:suggest`) before declaring the milestone done.
+   With a committed baseline (`.archik/smells-baseline.json`) only
+   findings marked **NEW** count; known debt is not this change's job.
+
+   For a one-way door, confirm each `crossCutting` promise from the
+   decision record is in the code before flipping nodes to `active`.
    `superpowers:verification-before-completion` when available.
    If `docs/architecture.svg` is committed, regenerate it:
    ```

package/commands/bootstrap.md

@@ -64,8 +64,17 @@ brief and start the DESIGN loop.
    > forces priorities into the open before any code lands. New
    > nodes start `status: proposed` (the code doesn't exist on disk
    > yet) and flip to `status: active` when the code lands in BUILD.
+   > Only the first milestone is modelled in detail; later areas stay
+   > coarse placeholders until their turn.
    > The commitment lives in the YAML, not in the chat log."
-5. When the brief lands, run the standard DESIGN loop:
+5. When the brief lands, agree the **architecture style** first:
+   show `npx archik style list`, recommend one that fits the brief
+   (small service → layered; rich domain with many integrations →
+   hexagonal or clean; several teams in one deployable → modular
+   monolith; many independent features → feature slices), and ask
+   the user to pick. The first sidecar sets `style:` and puts each
+   top-level node in its layer or module.
+6. Then run the standard DESIGN loop:
    `/archik:suggest` (structural sidecar) → `/archik:accept` →
    BUILD. Stop at each inline-review gate; don't barrel through.
 
@@ -91,7 +100,9 @@ diagram, then iterate from honest ground truth.
    duplicate them here.
 4. After the user accepts the spawn sidecar, suggest the natural
    follow-up: "Want to check the code for structural smells?
-   `npx archik smells` finds folder loops and oversized files."
+   `npx archik smells` finds folder loops and oversized files — and
+   `--update-baseline` saves today's findings so CI fails only on new
+   ones."
 
 ### C. `.archik/` exists but the diagram is empty or near-empty
 

package/commands/evolve.md

@@ -30,10 +30,16 @@ any file under `.archik/`.
 
 2. **Ground yourself in the current shape** via the query CLI:
    ```
+   npx archik style
    npx archik q stats
    npx archik q list
    npx archik q edges
    ```
+   If no style is declared, one of the best improvements you can
+   offer is to adopt one (`npx archik style list`): pick the style the
+   code is closest to, set it in the draft with layers on the
+   top-level nodes, and let the violations it reports become the
+   refactor plan.
    If `$ARGUMENTS` names a specific area, also:
    ```
    npx archik q describe <id>
@@ -107,6 +113,13 @@ any file under `.archik/`.
      # full proposed end-state — every node, not just the delta
    edges:
      # ...
+   metadata:
+     suggestion:
+       decision:
+         context: <the smell and its evidence, e.g. the folder loop imports>
+         decision: <the refactor you chose>
+         alternatives: [<other fixes you weighed, incl. leaving it>]
+         consequences: <what gets easier and what it costs>
    YAML
    ```
 

package/commands/migrate.md

@@ -4,7 +4,8 @@ description: Finish a migration — check the result and fix what the migrator f
 
 # /archik:migrate — check what the deterministic migration did
 
-`archik upgrade --migrate` already ran the **deterministic** migration:
+`archik migrate` (or `archik upgrade --migrate`, which runs it through
+the newly installed version) already ran the **deterministic** migration:
 it archived the old project, ran each pending step, validated, and
 advanced `.archik/.version`. The current steps are:
 
@@ -12,6 +13,9 @@ advanced `.archik/.version`. The current steps are:
   `.archik/main.archik.yaml`.
 - **#3** — strip retired node fields (`stereotype`, `seqFiles`) from the
   model files.
+- **#4** — move retired use-case, sequence, actor, alpha and trace files
+  to `.archik/retired/`, strip retired fields from pending suggestions,
+  and flag code, CI and scripts that still use removed features.
 
 (#2, the old use-case back-fill, is retired and never runs.)
 
@@ -30,6 +34,23 @@ developer's only copy of the pre-migration project.
 
 1. **Read the migrator's output.** Any `ⓘ` line it printed is a task for
    you. If it printed none, the steps below are a quick check only.
+   The usual ones from 0.19 and older:
+   - **moved N retired files to `.archik/retired/`** — tell the user
+     they are kept only as history. Ask before deleting them. If a use
+     case explains *why* a structure exists, offer to capture that as a
+     decision record with the next `/archik:suggest` touching that area.
+   - **pending suggestion … has no decision record** — read it with
+     `npx archik suggest show`, then either re-stage it with a decision
+     record (`/archik:suggest`) or ask the user to reject it.
+   - **code imports `archik/trace`** — the recorder is gone. Remove the
+     `trace(...)` calls and the import from those test files; keep the
+     tests' real assertions. Run the tests afterwards.
+   - **workflow uses `trace-fail-on`** — replace it with
+     `smells-fail: true` (or drop it). On existing code, offer
+     `npx archik smells --update-baseline` first so CI fails only on
+     new smells.
+   - **package.json scripts call a removed command** — remove the
+     script or replace it (`archik smells`, `archik drift`).
 
 2. **Find the archived original.**
    ```bash
@@ -47,6 +68,9 @@ developer's only copy of the pre-migration project.
    npx archik drift
    npx archik smells
    ```
+   If `validate` reports `unrecognized key … removed in archik 0.20`,
+   the migration did not run with the new version — run
+   `npx archik migrate` and check again.
 
 4. **Fix gaps through the normal workflow.** If drift or the archive
    shows structure the model misses (a node, an edge, a `parentId`

package/commands/realize.md

@@ -0,0 +1,92 @@
+---
+description: Make the code match the architecture the architect changed
+---
+
+# /archik:realize — make the code match the model
+
+The architect steers the architecture on the canvas: moves a box into
+another module, draws or deletes an edge, sets a layer or a style. The
+model changes first; the code has not caught up. Your job is to close
+that gap — and only that gap.
+
+`$ARGUMENTS` (optional) narrows the work to one node or area.
+
+## CLI-only for architecture
+
+Read the model only through `npx archik`. Change it only through
+`npx archik suggest set` (the lifecycle flips below). Never edit
+`.archik/*.yaml` by hand.
+
+## Steps
+
+1. **Get the work list.**
+   ```bash
+   npx archik gap --json
+   ```
+   Each task has a `type` and a `text`:
+   - `move-code` — move the node's code from `from` to `to`, then fix
+     every import that pointed at the old path.
+   - `create-code` — create the code for a planned node at `path`.
+   - `style-break` — an import breaks the architecture style. Fix it
+     the way the message says (usually: add an interface / port in the
+     inner layer and depend on that).
+   - `remove-import` — the architect deleted that edge. Remove the
+     import (move the logic, or call through an allowed node).
+   - `add-dependency` — the model says A uses B; wire the import.
+   - `finish` — the node's code now exists; flip it to `active`.
+
+   If the list is empty, say so and stop.
+
+2. **Read why.** For each node in the list, read the newest decision
+   record that mentions it in `.archik/decisions/` (plain markdown —
+   read it directly). Keep to the intent: a move into `billing` means
+   the code now belongs to billing, not just a new folder name.
+
+3. **Check the rules before you edit.**
+   ```bash
+   npx archik style
+   npx archik q describe <id>     # the "style:" line: layer / module, may depend on
+   ```
+
+4. **Plan, then wait for "approve".** A numbered, file-level plan:
+   which folders move, which imports change, which files are created.
+   Keep it to the gap. No drive-by refactors.
+
+5. **Do it in small commits.** Move with `git mv` so history follows
+   the code. After each step run the project's tests and typecheck.
+
+6. **Flip finished nodes to active.** When `gap` lists `finish`
+   tasks, stage one sidecar that removes `status: proposed` from those
+   nodes, with a short decision record (context: the code landed;
+   decision: mark it active; alternative: keep it proposed until
+   deploy; consequence: drift now checks it):
+   ```bash
+   npx archik suggest set --note "<nodes> are built" - <<'YAML'
+   ... full document, those nodes without status: proposed ...
+   metadata:
+     suggestion:
+       decision: { context: ..., decision: ..., alternatives: [...], consequences: ... }
+   YAML
+   ```
+
+7. **Verify — the gap must be empty.**
+   ```bash
+   npx archik gap          # ✓ the code matches the model
+   npx archik validate
+   npx archik drift
+   npx archik smells       # no NEW folder loops
+   ```
+   Plus the project's tests, lint and build.
+
+## If the model is wrong
+
+If moving the code shows the architect's change cannot work (a cycle,
+a missing port, a hidden caller), STOP. Explain what you found with the
+file evidence, and propose the fix with `/archik:suggest` — don't bend
+the code around the model, and don't change the model silently.
+
+## Done when
+
+`npx archik gap` prints "the code matches the model", tests pass, and
+the finished nodes are `active`. End with one line on what changed and
+the next step.

package/commands/self-evolving.md

@@ -55,7 +55,8 @@ Never `Read`/`Write`/`Edit` files under `.archik/`.
      (stages the blueprint as `status: proposed` nodes), then refine
      ids/names with a follow-up `suggest set`.
    - Tailored: author the full end-state and stage via
-     `npx archik suggest set --note '…' - <<'YAML' … YAML`.
+     `npx archik suggest set --note '…' - <<'YAML' … YAML`, with a
+     decision record under `metadata.suggestion.decision` (required).
 
 6. **Wire the tests.** Name one test per loop step: "corrections are
    recorded", "insights become proposals", "approved change applies".

package/commands/spawn.md

@@ -155,6 +155,13 @@ archik suggest set` stages it.
       name: <Id> Internals
       nodes: [ ... ]
       edges: [ ... ]
+      metadata:
+        suggestion:
+          decision:
+            context: <why this split is needed>
+            decision: <what you chose>
+            alternatives: [<option not chosen>]
+            consequences: <what gets easier and harder>
       YAML
       # mechanical: puts sub-file on disk so the main draft's
       # archikFile: pointer validates. NOT the user's review gate
@@ -191,9 +198,21 @@ archik suggest set` stages it.
         # full proposed end-state, with archikFile pointers
       edges:
         # ...
+      metadata:
+        suggestion:
+          decision:
+            context: <what the source tree shows and why it is split this way>
+            decision: <what you chose>
+            alternatives: [<option not chosen>]
+            consequences: <what gets easier and harder>
       YAML
       ```
 
+      Every draft needs its decision record — `suggest set` refuses
+      one without it. For a spawn, the context is what the source
+      tree shows; the alternatives are other ways to cut it (one
+      flat file, a different grouping).
+
    c. If `suggest set` reports validation errors, re-run with the
       corrected YAML. Never edit the sidecar by hand.
 
@@ -204,6 +223,13 @@ archik suggest set` stages it.
    - "Looks wrong? Run `/archik:reject` and we'll iterate. Or run
      `/archik:evolve` after accepting if you want a cleaner
      bounded-context version."
+   - Offer an **architecture style** next: name the style the code is
+     closest to (`npx archik style list` — e.g. `controllers/`,
+     `services/`, `repositories/` folders → layered; `ports/` +
+     `adapters/` → hexagonal; one folder per feature → feature
+     slices) and offer to stage it with layers on the top-level
+     nodes. Spawn itself stays descriptive — don't add the style in
+     the spawn draft.
 
    **Offer a smells check at the end of this step** (not after
    accept — you won't be there). Run it now so the offer is concrete:
@@ -215,6 +241,12 @@ archik suggest set` stages it.
    `<a>` and `<b>`? The cheapest cut is `<file imports "specifier">`."*
    If it finds none, skip this line.
 
+   Existing code almost always has some debt. Also offer the
+   baseline so CI can gate on *new* smells from now on: *"Want me to
+   save today's findings as the baseline (`npx archik smells
+   --update-baseline`, commit `.archik/smells-baseline.json`)? Then
+   `--fail-on-warn` only fails on new loops or growing files."*
+
    Do NOT fix smells here — spawn is descriptive, and the fix is a
    separate ask from the user. This note is a prompt, not an action.
 

package/commands/suggest.md

@@ -26,7 +26,7 @@ the contract with the user.
 
 The skill defines a 5-phase loop: **Discover → Design → Decide → Build
 → Verify**. This command covers Discover (grounding) and Design
-(staging the sidecar with rationale), then hands off to the user's
+(staging the sidecar with its decision record), then hands off to the user's
 review and the explicit Decide gate (`/archik:accept` or
 `/archik:reject`). Don't skip clarification just because a slash
 command was typed — clarification is what makes the draft good. Don't
@@ -66,11 +66,21 @@ start Build phase here; that's gated on accept.
 2. **Ground yourself in the current models** using the query CLI
    (do not `cat` the YAML):
    ```
+   npx archik style
    npx archik q stats
    npx archik q list
    ```
    If `$ARGUMENTS` mentions a specific node by name, also run
-   `npx archik q describe <id>` for it.
+   `npx archik q describe <id>` for it (its `style:` line says which
+   layer or module it sits in and what it may depend on).
+
+   If the model declares a style, the draft must follow it: give each
+   new top-level node its `layer` (layered, hexagonal, clean) or put
+   it in the right module (modular monolith, feature slices), and keep
+   every new edge inside the style's rule. `suggest set` rejects a
+   draft that breaks it. If the feature truly needs a forbidden
+   dependency, stop and ask the user — the fix is usually a port /
+   interface, not an exception.
 
 3. **Lock in the schema.** Run this before drafting any YAML —
    the prose in this file describes the workflow, not the field
@@ -113,23 +123,51 @@ start Build phase here; that's gated on accept.
      # full proposed end-state — every node, not just the delta
    edges:
      # full proposed end-state — every edge, not just the delta
+   metadata:
+     suggestion:
+       decision:
+         context: <the problem and the forces — facts, not the solution>
+         decision: <what you chose, 1–2 sentences>
+         alternatives:
+           - <a real option you weighed and did not choose>
+         consequences: <what gets easier AND what gets harder>
+         # crossCutting:          # REQUIRED when the change adds data, an
+         #   security: ...        #   outside system or public traffic
+         #   observability: ...
+         #   rollback: ...
+         # supersedes: ["0003"]   # only when this reverses an earlier record
    YAML
    ```
 
+   The decision record is required — `suggest set` refuses a draft
+   without it, and accept writes it to
+   `.archik/decisions/NNNN-<slug>.md`. Before writing it, read the
+   past records for the area (`ls .archik/decisions/`, they are plain
+   markdown). If your change reverses one, list it in `supersedes`.
+
+   `suggest set` prints whether the change is a **one-way door** (hard
+   to undo: a new data store, queue/stream, external system,
+   gateway/auth/cdn, cloud or LLM node, a new edge to an external
+   system, a new top-level module, a removal, a boundary move) or a
+   **two-way door**. If it adds data, an outside system or public
+   traffic it refuses the draft until `crossCutting` says how it is
+   **secured** (who can reach it, secrets, data exposure),
+   **observed** (the signal that shows it working or failing) and
+   **rolled back** (how to undo it safely). Write real answers, not
+   placeholders — the plan must later land what you promise here.
+
    If the command exits non-zero, re-run with the corrected YAML.
    Never write a draft file under `.archik/` and never edit the
    sidecar directly.
 
-5. **Narrate the design rationale** in 2–4 short bullets before
-   handing off to review. The user needs to see *why* this shape, not
-   just *what* it is. Cover:
-   - Which **bounded context(s)** the change touches and why those
-     boundaries.
-   - The **separation of concerns** — what each new node owns and why
-     it's its own node (not folded into an existing one).
-   - **Async vs sync** choice and the reason (cross-context coupling
-     should default to async).
-   - Any **alternative you rejected** and the trade-off.
+5. **Summarise the decision record** in 2–4 short bullets before
+   handing off to review — the same content the record holds, so the
+   user can judge the *why* next to the diagram (the canvas also shows
+   it under **Why** on the review banner). Make sure it covers:
+   - Which **boundaries** the change touches and why those boundaries.
+   - What each new node owns and why it is its own node.
+   - **Async vs sync** choice and the reason.
+   - The **alternatives** you rejected and what the choice costs.
 
    Keep it tight — bullets, not paragraphs. The diagram does the rest.
 
@@ -141,6 +179,14 @@ start Build phase here; that's gated on accept.
      **reject** and tell me what didn't fit (boundary? relationship?
      scope? naming? composition? lifecycle?) so I can revise."
 
+   Match the gate to the door:
+   - **One-way door** — say so ("This is hard to undo: <reasons>")
+     and hand off the sidecar alone. The build plan comes after
+     accept, as its own approval gate.
+   - **Two-way door** — include the numbered build plan in this same
+     hand-off, and say that `/archik:accept` approves both the model
+     change and the plan.
+
    Do NOT pre-emptively start implementing. Wait for `/archik:accept`.
 
 ## Notes