archik 0.19.4 → 0.20.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,9 @@ 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` |
 
-Full schema: `npx archik schema` (also `schema seq | uc | actors`).
+Full schema: `npx archik schema`.
 
 ## Keeping the model honest
 
@@ -123,14 +119,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. Gate every commit locally:
 
 ```bash
 npx archik hooks install       # pre-commit: archik validate
@@ -142,7 +138,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 +172,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 +188,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; omit for report-only
 ```
 
-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 +207,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`) |
+| `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 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 +223,23 @@ 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 schema` | Print the document schema |
 | `archik upgrade` | Upgrade + refresh installed skill/commands |
 
 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 |
 | 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,9 @@ 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
+   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,13 +40,6 @@ 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`.
    - Default to **tests-first** when behaviour is clearly bounded.
@@ -106,15 +77,13 @@ 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.
    `superpowers:verification-before-completion` when available.
    If `docs/architecture.svg` is committed, regenerate it:
    ```
@@ -128,12 +97,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,15 @@ 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.
+   > 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 +90,8 @@ 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."
 
 ### C. `.archik/` exists but the diagram is empty or near-empty
 
@@ -113,19 +109,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 +134,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
@@ -144,7 +115,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 +131,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 +144,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."*
 

package/commands/migrate.md

@@ -1,84 +1,60 @@
 ---
-description: Finish a migration — back-fill the artifacts the migrator flagged
+description: Finish a migration — check the result and fix what the migrator flagged
 ---
 
-# /archik:migrate — back-fill what the deterministic migration couldn't
+# /archik:migrate — check what the deterministic migration did
 
 `archik upgrade --migrate` already ran the **deterministic** migration:
-it archived the old project, moved files into the current layout,
-validated, and advanced `.archik/.version`. It then flagged the parts
-that need **judgment** — usually: *the project has an architecture but no
-use cases / sequence diagrams.* Your job is to back-fill those, grounded
-in **both** the current model and the **archived original**.
+it archived the old project, ran each pending step, validated, and
+advanced `.archik/.version`. The current steps are:
 
-The deterministic steps are done. Do NOT redo them. You author the
-missing artifacts; `archik validate` is your gate.
+- **#1** — move a legacy root `architecture.archik.yaml` into
+  `.archik/main.archik.yaml`.
+- **#3** — strip retired node fields (`stereotype`, `seqFiles`) from the
+  model files.
 
-## CLI-only for architecture; direct-write for the Jacobson files
+(#2, the old use-case back-fill, is retired and never runs.)
 
-Interact with the architecture diagram only through `npx archik`. Actors,
-use cases, and sequence diagrams are **direct-write** files (no sidecar) —
-author them with `Write`, then `npx archik validate`. Never edit
-`.archik/main.archik.yaml` by hand. **Never delete `.archik.archive/`** —
-it is the developer's only copy of the pre-migration project.
+The deterministic steps are done. Do NOT redo them. Your job is to check
+the result against the **archived original** and fix anything the
+migrator printed as needing judgment. `archik validate` is your gate.
+
+## CLI-only for architecture
+
+Interact with the architecture diagram only through `npx archik`. Never
+edit `.archik/main.archik.yaml` by hand — changes go through
+`suggest set` → `accept`. **Never delete `.archik.archive/`** — it is the
+developer's only copy of the pre-migration project.
 
 ## Steps
 
-1. **See exactly what's missing.** The migrator's `needsJudgment` hint is
-   printed once and not re-derivable, so check the project directly:
-   ```bash
-   npx archik q usecases     # empty → use cases need back-filling
-   npx archik q actors       # empty → actors needed first (use cases reference them)
-   npx archik q sequences    # which flows already have a seq diagram
-   ```
+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.
 
-2. **Read the archived original — this is the migration's whole point.**
-   Find the newest archive and read the old project's intent (descriptions,
-   any notes, the old structure) so the back-fill reflects what the
-   developer actually built, not a generic guess:
+2. **Find the archived original.**
    ```bash
    ls -t .archik.archive/        # newest timestamp dir is the pre-migration copy
    ```
    Read the files under that dir with the `Read` tool (the archive is a
    plain backup, not a live archik doc — reading it directly is correct).
+   Note any old use case, sequence, or stereotype files there: their
+   content is no longer modelled. Do not recreate them.
 
-3. **Ground the use cases in the current model.** Combine the archive's
-   intent with the live structure:
-   ```bash
-   npx archik q stats
-   npx archik q list
-   npx archik q edges
-   ```
-
-4. **Author actors first** (if `q actors` was empty). Use cases reference
-   actors by id, and validate rejects a use case whose `primaryActor`
-   isn't in the actor index. Direct-write `.archik/actors.archik.actors.yaml`
-   (schema: `npx archik schema actors`), then `npx archik validate`.
-
-5. **Author one use case per real flow.** Direct-write
-   `.archik/usecases/<id>.archik.uc.yaml` (schema: `npx archik schema uc`).
-   Mark each slice `status: proposed` and give it `tests:` paths only if
-   those files exist on disk — otherwise omit `tests` (active slices
-   require on-disk tests). Validate after each:
-   `npx archik validate .archik/main.archik.yaml`.
-
-6. **Author a sequence diagram per primary slice.** Direct-write
-   `.archik/<usecase>.<slice>.archik.seq.yaml` (schema: `npx archik schema seq`).
-   Every participant `nodeId` must be a real node; add a `realizes` block
-   AND point the slice's `realization.seqFile` back at the file
-   (bidirectional). Add the seq to each participating node's `seqFiles`
-   via the normal `suggest set` → `accept` workflow.
-
-7. **Verify and report.** Then propose the natural next step (write the
-   tests the slices name, flip them to `active`), don't end on "done":
+3. **Check the live model.**
    ```bash
    npx archik validate .archik/main.archik.yaml
-   npx archik trace
+   npx archik q stats
    npx archik drift
+   npx archik smells
    ```
 
+4. **Fix gaps through the normal workflow.** If drift or the archive
+   shows structure the model misses (a node, an edge, a `parentId`
+   container), stage it with `/archik:suggest`. Don't bulk-restructure.
+
 ## Done when
 
-`archik validate` is clean and `archik q usecases` lists the back-filled
-use cases, each primary slice realising a sequence diagram. The archive
-stays untouched as the developer's rollback.
+`archik validate` is clean, every `ⓘ` line from the migrator is
+handled, and you proposed the natural next step (fix drift, cut a folder
+loop that `smells` found). The archive stays untouched as the
+developer's rollback.

package/commands/self-evolving.md

@@ -35,8 +35,9 @@ Never `Read`/`Write`/`Edit` files under `.archik/`.
    No feedback signal = no evolution loop; help them find one first.
 
 3. **Ground in the current diagram** (`npx archik q stats`, `q list`).
-   If the project is empty, model the *base system* first — actors,
-   then one use case to ship, per the normal archik opening move.
+   If the project is empty, model the *base system* first — the
+   smallest structure for one thing to ship, per the normal archik
+   opening move.
 
 4. **Map the idea onto the loop.** For each stage, name the concrete
    component in THEIR system:
@@ -56,10 +57,9 @@ Never `Read`/`Write`/`Edit` files under `.archik/`.
    - Tailored: author the full end-state and stage via
      `npx archik suggest set --note '…' - <<'YAML' … YAML`.
 
-6. **Wire the requirements.** Author a use case for the loop itself
-   (`/archik:usecase` conventions): slices like "corrections are
-   recorded", "insights become proposals", "approved change applies",
-   each naming test paths.
+6. **Wire the tests.** Name one test per loop step: "corrections are
+   recorded", "insights become proposals", "approved change applies".
+   Add them to the build plan after accept.
 
 7. **Hand over.** Show the canvas URL, summarize which patterns you
    used and why, and point at `npx archik evolution enable` if they