archik 0.19.5 → 0.21.0

package/.claude-plugin/marketplace.json

@@ -11,10 +11,10 @@
         "source": "github",
         "repo": "bacharSalleh/archik"
       },
-      "description": "Plain-YAML architecture diagrams + Jacobson use cases / actors / sequence diagrams / alphas, all CLI-mediated and validated. The skill enforces CLI-only access; the slash commands wrap the loop.",
+      "description": "Plain-YAML architecture diagrams of code structure (nesting, dependency flow, drift, structural smells), all CLI-mediated and validated. The skill enforces CLI-only access; the slash commands wrap the loop.",
       "homepage": "https://github.com/bacharSalleh/archik#readme",
       "license": "MIT",
-      "keywords": ["architecture", "diagram", "yaml", "jacobson", "ecb"]
+      "keywords": ["architecture", "diagram", "yaml"]
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "archik",
-  "description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams + Jacobson use cases / actors / sequence diagrams / alphas, all CLI-mediated and validated.",
+  "description": "The shared vocabulary between you and Claude Code, at the engineering level. Plain-YAML architecture diagrams of code structure (nesting, dependency flow, drift, structural smells), all CLI-mediated and validated.",
   "author": {
     "name": "Bashar",
     "email": "welcomebachar@gmail.com"
@@ -12,10 +12,6 @@
     "architecture",
     "diagram",
     "yaml",
-    "jacobson",
-    "use-case",
-    "ecb",
-    "essence",
     "documentation"
   ]
 }

package/README.md

@@ -27,13 +27,13 @@
 
 Your architecture lives in **plain YAML**. You edit it through a **CLI**, a **validator** rejects drift before it merges, and a **live canvas** renders it in the browser. AI agents — Claude Code, or anything that speaks MCP — read the same YAML as the map of your system, so they reason about structure instead of guessing from filenames.
 
-One chain runs from a stakeholder request to a passing test, and every link is checked mechanically:
+archik focuses on code **structure**: which parts exist, how they nest, which way dependencies flow, and whether the code still agrees:
 
 ```
-Actor → Use case → Slice → Tests → Sequence diagram → Nodes → Source
+Nodes → Nesting (parentId, sub-files) → Edges → Source code
 ```
 
-Nothing in that chain can quietly fall out of sync with the code.
+Every link is checked against the code, so the map can't quietly fall out of sync.
 
 ## Install
 
@@ -70,8 +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:usecase <name>` | A use case with flows, slices, and test paths |
-| `/archik:trace` | The coverage matrix — "are we done?" |
+| `/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,12 +109,14 @@ There are no coordinates — layout is computed by [ELK](https://eclipse.dev/elk
 | Layer | File | Captures |
 | --- | --- | --- |
 | Structure | `.archik/main.archik.yaml` | Services, databases, queues, agents, LLMs, edges |
-| Actors | `*.archik.actors.yaml` | Who initiates use cases |
-| Requirements | `.archik/usecases/*.archik.uc.yaml` | Flows and slices that name **test paths** |
-| Behaviour | `*.archik.seq.yaml` | UML-subset sequence diagrams |
-| Progress | `*.archik.alphas.yaml` | Essence/SEMAT alphas, machine-verified |
+| 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 |
 
-Full schema: `npx archik schema` (also `schema seq | uc | actors`).
+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`.
 
 ## Keeping the model honest
 
@@ -123,14 +124,14 @@ A set of commands prove the diagram still matches reality, at every altitude:
 
 ```bash
 npx archik validate            # schema + cross-file integrity + governance constraints
-npx archik drift               # nodes/tests vs the source tree
+npx archik drift               # nodes vs the source tree
 npx archik drift --edges       # edges vs the TS/JS import graph (shadow + phantom edges)
-npx archik affected --since main --run   # changed files → nodes → slices → run their tests
-npx archik trace --fail-on partial       # coverage matrix; gate CI on incomplete traceability
+npx archik smells              # folder import loops + oversized files, read from the code
+npx archik affected --since main         # changed files → nodes → dependents
 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. 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
@@ -142,7 +143,7 @@ Large models stay readable: `archik complexity` flags over-large files, hub node
 
 **Claude Code.** `archik init` installs a skill that enforces one rule — *Claude talks to archik only through the CLI*, never by editing YAML directly. Reads go through `archik q`, writes through `archik suggest set`, and you approve every structural change on the canvas.
 
-**Everything else (MCP).** `archik mcp` runs a stdio [Model Context Protocol](https://modelcontextprotocol.io) server exposing the same contract — tools for schema, queries, trace, validate, drift, and the suggestion lifecycle, plus resources (`archik://schema`, `archik://stats`, `archik://trace`) and prompts that encode the same loop:
+**Everything else (MCP).** `archik mcp` runs a stdio [Model Context Protocol](https://modelcontextprotocol.io) server exposing the same contract — tools for schema, queries, validate, drift, smells, and the suggestion lifecycle, plus resources (`archik://schema`, `archik://stats`, `archik://smells`) and prompts that encode the same loop:
 
 ```jsonc
 // .cursor/mcp.json, claude_desktop_config.json, etc.
@@ -176,7 +177,7 @@ Intentional exceptions are grandfathered by id in an `except` list — visible i
 
 ## CI
 
-Run the commands directly, or use the GitHub Action, which validates, checks drift and traceability, and posts a sticky PR comment with the architecture diff against the base branch:
+Run the commands directly, or use the GitHub Action, which validates, checks drift, reports smells, and posts a sticky PR comment with the architecture diff against the base branch:
 
 ```yaml
 # .github/workflows/archik.yml
@@ -192,10 +193,10 @@ jobs:
       - uses: actions/checkout@v4
       - uses: bacharSalleh/archik@main
         with:
-          trace-fail-on: partial   # 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`, `trace-fail-on`, `compare-ref`, `comment`, `github-token`, `version`.
+Inputs: `path`, `working-directory`, `validate`, `drift`, `smells-fail`, `compare-ref`, `comment`, `github-token`, `version`.
 
 ## Self-evolution
 
@@ -211,16 +212,15 @@ 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 render --out <svg>` | Headless SVG render (`--seq <path>`, `--focus <id>`, `--hide-structural`) |
+| `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` `usecases` `describe-usecase` `actors` `sequences` |
+| `archik q <sub>` | Query: `describe` `deps` `dependents` `neighbors` `impact` `list` `edges` `stats` |
 | `archik diff <a> [b]` | Diff two files **or git refs**; one arg = that ref vs working tree |
-| `archik affected` | Changed files → nodes, slices, tests (`--since <ref>`, `--files`, `--run`) |
-| `archik trace` | Coverage matrix (`--fail-on partial\|none` for CI) |
-| `archik drift` | sourcePath / test-path gaps (`--edges` verifies edges vs the import graph) |
+| `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 alpha <sub>` | Essence alphas: `show`, `promote`, `demote` |
+| `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 |
@@ -228,23 +228,25 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik hooks install` | Pre-commit hook running `archik validate` (`--with-drift` optional) |
 | `archik owners sync\|check` | Keep CODEOWNERS in step with node owners |
 | `archik mcp` | MCP server over stdio for non-Claude-Code agents |
-| `archik schema [seq\|uc\|actors]` | Print the document schemas |
-| `archik upgrade` | Upgrade + refresh installed skill/commands |
+| `archik schema` | Print the document schema |
+| `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).
 
 ## When to use it
 
-Reach for archik when a project has more than a handful of components, ships with an AI agent you want reasoning about structure, needs "are we done?" to be mechanically answerable, or wants CI to fail on architectural drift. Skip it for one-file scripts, slide-deck diagrams (use Mermaid), or projects with no build or CI.
+Reach for archik when a project has more than a handful of components, ships with an AI agent you want reasoning about structure, wants folder loops caught with real import evidence, or wants CI to fail on architectural drift. Skip it for one-file scripts, slide-deck diagrams (use Mermaid), or projects with no build or CI.
 
 |  | archik | Mermaid / PlantUML | Structurizr |
 | --- | --- | --- | --- |
 | Source format | Plain YAML | Custom DSL | Structurizr DSL |
 | AI-editor integration | **Skill + MCP** | None | None |
-| Use cases / test traceability | **Mechanical** | No | No |
+| 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 |
-| Validator | **Schema + cross-file + ECB** | Syntax only | Syntax only |
+| Validator | **Schema + cross-file + constraints** | Syntax only | Syntax only |
 
 ## Contributing
 

package/commands/accept.md

@@ -29,31 +29,14 @@ done at step 1 — the diagram changed; the code probably hasn't.
    non-code-bearing kind, description-only edit, pure metadata),
    skip steps 3–6 and jump straight to step 7.
 
-3. **BUILD — behavioral model first, then plan (HITL).**
+3. **BUILD — plan (HITL).**
 
-   **Before writing the plan**, check whether any new or modified
-   slice has behavior that warrants a seq diagram. A slice needs
-   one when it involves branching, async fan-out, cross-context
-   interaction, or three or more nodes in a single user-visible
-   action. Run:
-   ```
-   npx archik q usecases
-   ```
-   For each active slice without a `realization.seqFile` that meets
-   the above criteria:
-   - Author the `.archik.seq.yaml` now (direct-write), including a
-     `realizes: { useCase, slice }` block.
-   - Run `npx archik validate` — catches ECB violations, broken
-     `nodeId` refs, and duplicate step ids.
-   - Show the seq YAML inline and wait for confirmation before
-     writing the plan.
-
-   A slice without a seq diagram has no traceable spec — the build
-   plan for it is guesswork. Author the seq first; trace it in the
-   plan. If the slice is genuinely simple (single node, no
-   branching), skip the seq and note why.
-
-   **Then** 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.
+
+   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`,
@@ -62,15 +45,12 @@ done at step 1 — the diagram changed; the code probably hasn't.
    - Each new edge that requires code → the corresponding code
      change (a new `http_call` needs a client; `subscribes` needs a
      consumer handler; `writes` needs a repository method; etc).
-   - Each seq diagram that realizes a slice → trace it: every
-     message in the seq must map to a concrete function call in this
-     plan. This is the traceability requirement — the seq is the
-     spec, the plan is the contract, the code is the proof.
-   - Each slice's `tests` paths → include scaffolding those test
-     files in the plan; they must exist on disk before the slice
-     can be marked active.
    - 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.
@@ -106,15 +86,18 @@ done at step 1 — the diagram changed; the code probably hasn't.
    ```
    npx archik drift
    ```
-   Catches both missing `sourcePath` directories and missing slice
-   test files on disk.
-   If the project has use cases, run the coverage matrix:
+   Catches missing `sourcePath` directories on disk.
    ```
-   npx archik trace
+   npx archik smells
    ```
-   No active slice should be untraced at ship time. Partial is a
-   warning; untraced is a gap — add the missing test path or
-   realization seq before declaring the milestone done.
+   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:
    ```
@@ -128,12 +111,3 @@ done at step 1 — the diagram changed; the code probably hasn't.
    - *"Want me to schedule a drift check in two weeks?"*
    - *"This left `payments-worker` as `status: proposed` — flip it
      to `active` once deployed."*
-   - If this milestone completed a significant chunk of work, check
-     whether any alpha state can be promoted:
-     ```
-     npx archik alpha show
-     ```
-     If a state is verified and the next rung's criteria are met,
-     offer to promote: *"Requirements is at `acceptable` and all
-     active slices now have tests — want me to promote it to
-     `addressed`?"*

package/commands/bootstrap.md

@@ -38,8 +38,8 @@ brief and start the DESIGN loop.
 
 1. Confirm with the user once before writing anything:
    > "I see this is a fresh project. I'll scaffold archik, then ask
-   > for a one-paragraph brief so I can model the actors and your
-   > first use case. Sound right?"
+   > for a one-paragraph brief so I can model the first piece you
+   > should ship. Sound right?"
 2. On confirmation, run:
    ```sh
    npx archik@latest init
@@ -48,9 +48,8 @@ brief and start the DESIGN loop.
    and skip step 4. Otherwise:
 4. **Ask for the brief**, in this exact shape (so the user knows
    what fields you actually need). The closing line is the load-
-   bearing one — it commits the conversation to actors-first +
-   pick-exactly-one + ship-it-with-tests, which is the framing
-   that makes the rest of the loop work:
+   bearing one — it commits the conversation to pick-exactly-one,
+   which is the framing that makes the rest of the loop work:
    > "Send me a project brief in this shape (skip any line that
    > doesn't apply):
    >
@@ -60,18 +59,17 @@ brief and start the DESIGN loop.
    > **Constraints:** budget, deadline, team size, hard-no's.
    > **Out of scope:** things you explicitly DON'T want.
    >
-   > **Then end with:** *'Start by modelling the actors and the
-   > first use case I should ship.'* — that single line is what
-   > forces priorities into the open before any code lands. The
-   > use case names its test paths from message one; slices start
-   > `status: proposed` (because the tests don't exist on disk
-   > yet) and flip to `status: active` automatically when the
-   > tests land in BUILD. The commitment lives in the YAML, not
-   > in the chat log."
+   > **Then end with:** *'Start by modelling the smallest structure
+   > for the first thing I should ship.'* — that single line is what
+   > 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:
-   `/archik:actor` (if needed) → `/archik:usecase` → `/archik:suggest`
-   (structural sidecar) → behavioural seq files. Stop at each
-   inline-review gate; don't barrel through.
+   `/archik:suggest` (structural sidecar) → `/archik:accept` →
+   BUILD. Stop at each inline-review gate; don't barrel through.
 
 ### B. No `.archik/` yet, but source code exists (existing project)
 
@@ -94,8 +92,10 @@ diagram, then iterate from honest ground truth.
    `.claude/commands/archik/spawn.md` for the steps. Don't
    duplicate them here.
 4. After the user accepts the spawn sidecar, suggest the natural
-   follow-up: "Want to author the first use case for what you're
-   actively working on right now? `/archik:usecase <name>`."
+   follow-up: "Want to check the code for structural smells?
+   `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
 
@@ -113,19 +113,20 @@ Skip the `init` step in both — the file already exists.
 The project is already running the loop. Don't re-bootstrap. Surface
 the current state and let the user pick the next move:
 
-1. Run two queries to ground the user in where they are:
+1. Run three checks to ground the user in where they are:
    ```sh
    npx archik q stats
-   npx archik trace
+   npx archik drift
+   npx archik smells
    ```
-2. Translate the trace totals into one sentence: "X full slices,
-   Y partial, Z untraced." Name the worst-case slice if any.
+2. Sum it up in one sentence: "X nodes, Y drift findings, Z
+   smells." Name the worst finding if any.
 3. Suggest the next action based on state:
-   - **All traced** → "Ready to ship. Want to add a feature?
-     `/archik:suggest <feature>`. Or start a new use case?
-     `/archik:usecase <name>`."
-   - **Partial / untraced** → "The biggest gap is `<slice-id>`
-     — it's missing `<thing>`. Want me to fix it?"
+   - **Clean** → "Ready to ship. Want to add a feature?
+     `/archik:suggest <feature>`."
+   - **Drift or smells** → "The biggest gap is `<finding>` — the
+     evidence is `<file imports "specifier">` (or the drift line).
+     Want me to fix it?"
 
 ## Notes
 
@@ -137,7 +138,7 @@ the current state and let the user pick the next move:
 - Don't skip `init` if it's needed. The slash commands rely on
   `npx archik` being callable from the project root, and `init`
   also makes sure the skill + slash commands are installed.
-- **Do not** start writing actors / use cases / sidecars before
+- **Do not** start writing sidecars or code before
   the user replies to your "sound right?" check. Bootstrap is the
   one place where confirming-before-acting is more important than
   speed — the user is still calibrating what archik will do.

package/commands/evolve.md

@@ -45,26 +45,15 @@ any file under `.archik/`.
    — there's nothing meaningful to evolve. Suggest `/archik:spawn`
    first.
 
-   Also check the Jacobson-chain artifacts so you can surface
-   ECB and coverage smells alongside structural ones:
+   Also read the code-level smells, so your proposal rests on real
+   imports and not only on the diagram:
    ```
-   npx archik q actors
-   npx archik q usecases
-   npx archik trace --json
+   npx archik smells --json
    ```
-   (These are non-fatal if no UC/actor files exist — note that
-   and skip the UC smells below; focus on structural smells only.)
-
-   **Identify nodes at risk of seq breakage.** As you read the
-   node list, mentally note which nodes you're likely to remove,
-   split, or merge. For each such node, run:
-   ```
-   npx archik q sequences --node <id>
-   ```
-   This returns the seq files whose participants reference that
-   node ID. Collect these — you'll need the list in step 6 to
-   warn the user. If the list is empty for all affected nodes,
-   no seq diagrams are at risk.
+   It reports folder loops (sibling folders that import each other,
+   with each `file imports "specifier"` as evidence and the cheapest
+   import to cut) and oversized files. It needs no model, so it
+   works even when the diagram is thin.
 
 3. **Identify smells and missing structure.** Don't propose change
    for change's sake — every modification should fix one of:
@@ -85,30 +74,12 @@ any file under `.archik/`.
      introduce a `port` (the abstract contract) and an `adapter`
      (the concrete impl), with `implements` between them.
    - **Cyclic dependencies** between modules — should be inverted
-     (events) or broken (extract shared kernel).
+     (events) or broken (extract shared kernel). Use the folder loops
+     from `archik smells` as evidence: quote the imports, and start
+     with the "cheapest to cut" edge.
    - **Anaemic queues.** Two services connected by `http_call`
      for what's clearly an async fire-and-forget → introduce a
      `queue` or `topic` and rewire to `publishes` / `subscribes`.
-   - **Missing ECB stereotypes.** Only applies when actor/UC files
-     exist (`npx archik q usecases` returns results). Nodes that
-     appear in active UC slices (visible in `archik trace` output),
-     or that have user-facing relationships (`http_call` from a
-     gateway, `writes`/`reads` to a domain DB) but no `stereotype`
-     field → classify each as `boundary`, `control`, or `entity`.
-     This is a prerequisite for ECB validation on seq diagrams.
-     Evolve may **add** a stereotype to nodes spawn left blank, but
-     only when this smell is triggered. Never invent stereotypes on
-     a pure structural diagram with no UC files.
-   - **UC coverage gaps.** Only applies when UC files exist and
-     `archik trace --json` returns rows. Active slices that are
-     `partial` (tests exist but no seq realization) usually signal
-     a missing seq diagram or a missing port/adapter in the
-     structural model. Active slices that are `none` (no tests, no
-     realization) signal untested behaviour — propose a test
-     scaffold or a seq diagram, and flag any architectural gap that
-     makes the slice hard to realize (e.g. missing adapter for an
-     external call). If trace output is empty or all slices are
-     `full`, skip this smell.
 
    Aim for 3–8 changes — enough to be meaningful, few enough that
    the user can reason about each. If you'd need more, propose
@@ -136,6 +107,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
    ```
 
@@ -144,7 +122,7 @@ any file under `.archik/`.
      ids, never rename. Renames break diff and require the user to
      manually re-link references in code.
    - Don't drop `description`, `responsibilities`, `notes`,
-     `sourcePath`, or `stereotype` fields the user authored. Carry
+     `owner`, or `sourcePath` fields the user authored. Carry
      them over verbatim.
    - Every new code-bearing node (`service`, `function`, `worker`,
      `module`, `page`, `component`, `store`, `hook`, `model`, `dto`,
@@ -160,9 +138,6 @@ any file under `.archik/`.
      until the code lands.
    - Every node MUST have a non-empty `description` explaining
      what it does. Don't introduce a node without one.
-   - When adding a `stereotype` to address the ECB smell, use only
-     `boundary`, `control`, or `entity`. Don't add `stereotype` to
-     purely infra nodes (`database`, `queue`, `external`, `cloud`).
    - Every change should be motivated by step 3, not by aesthetics.
 
    If `suggest set` reports validation errors, re-run with the
@@ -176,13 +151,7 @@ any file under `.archik/`.
       grouped by motivation (e.g. *"1. Extract a `payments`
       bounded context from `orders`. Why: payment logic was leaking
       into order placement…"*). Keep each item to 2–3 sentences.
-   c. **Seq diagram impact warning** — if any seq file discovered
-      in step 2 references a node that this proposal removes or
-      renames, list them explicitly:
-      *"⚠️ These seq diagrams reference nodes this refactor
-      changes — they will need updating after accept: `<list>`."*
-      If no seq files are affected, skip this bullet.
-   d. An explicit invitation: *"Tell me what you'd like to keep,
+   c. An explicit invitation: *"Tell me what you'd like to keep,
       drop, or rework before you accept. I can re-stage with
       changes — `/archik:accept` is whenever you're ready."*