archik 0.21.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:
@@ -112,6 +113,18 @@ There are no coordinates — layout is computed by [ELK](https://eclipse.dev/elk
 | 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.
@@ -212,6 +225,8 @@ 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 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 |
@@ -246,6 +261,7 @@ Reach for archik when a project has more than a handful of components, ships wit
 | 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

@@ -36,7 +36,9 @@ done at step 1 — the diagram changed; the code probably hasn't.
    ran approved it — go straight to step 4. One-way doors always get
    their own plan approval here.
 
-   Translate the diagram delta into a numbered file-level
+   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`,

package/commands/bootstrap.md

@@ -67,7 +67,14 @@ brief and start the DESIGN loop.
    > 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.
 

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>

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/spawn.md

@@ -223,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:

package/commands/suggest.md

@@ -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