archik 0.19.5 → 0.21.0

package/commands/migrate.md

@@ -1,84 +1,84 @@
 ---
-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**.
+`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:
 
-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.
+- **#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.
 
-## 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.
+   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. **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
    ```
+   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`
+   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:
@@ -54,12 +55,12 @@ 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 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

package/commands/spawn.md

@@ -87,30 +87,12 @@ archik suggest set` stages it.
    - **Frontends**: `apps/web`, `apps/mobile`, `client/`,
      `packages/ui` apps that ship a UI → `frontend`.
 
-5. **Choose the kind and ECB stereotype for each node.** Default
+5. **Choose the kind for each node.** Default
    kind: `service`. Use the taxonomy from the skill — `function`
    for serverless, `worker` for background consumers, `agent` for
    LLM-driven agents, etc. When unsure, pick the closest fit and
    add a `notes:` entry explaining the inference.
 
-   For every node that faces a user or external system, also infer
-   its ECB `stereotype`:
-   - `stereotype: boundary` — accepts requests from actors / external
-     systems: API handlers, gateways, adapters, webhook endpoints,
-     BFF layers. Rule of thumb: the first thing an actor touches.
-   - `stereotype: control` — orchestrates use-case logic: services
-     that coordinate domain objects, use-case handlers, workflow
-     engines. Rule of thumb: knows *what* to do but delegates *how*.
-   - `stereotype: entity` — stores or represents domain data:
-     repositories, domain models, DB-backed modules, caches.
-     Rule of thumb: knows the data and its invariants.
-
-   If a node's role is purely infrastructure (`database`, `queue`,
-   `external`, `cloud`, etc.) or genuinely ambiguous, omit
-   `stereotype` — don't guess. The field is optional and the
-   validator only enforces ECB transition rules on seq diagrams
-   that carry a `realizes` block.
-
 6. **Attach `sourcePath` to every code-bearing node.** This is
    non-negotiable in a normal/suggested file — the validator rejects
    any `service`, `function`, `worker`, `module`, `page`, `component`,
@@ -173,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
@@ -209,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.
 
@@ -223,27 +224,24 @@ archik suggest set` stages it.
      `/archik:evolve` after accepting if you want a cleaner
      bounded-context version."
 
-   **Offer the Jacobson-chain follow-up at the end of this step**
-   (not after accept — you won't be there). Check what's missing
-   before framing the offer:
+   **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:
    ```
-   npx archik q actors
-   npx archik q usecases
+   npx archik smells
    ```
-   Then close with one of these follow-up lines, whichever fits:
-   - No actors, diagram has boundary nodes / user-facing components:
-     *"Once you accept, ask me to author a `*.archik.actors.yaml`
-     — that's the starting point for use-case coverage."*
-   - Actors exist but no use cases:
-     *"Once you accept, ask me to stub `*.archik.uc.yaml` files for
-     the key flows."*
-   - Both exist already:
-     *"Run `/archik:evolve` after accepting for ECB and coverage
-     gap suggestions."*
-
-   Do NOT author actors or use cases here — that requires the
-   structural diagram to be accepted first and is a separate ask
-   from the user. This note is a prompt, not an action.
+   If it finds folder loops or oversized files, close with:
+   *"Once you accept, want me to look at the folder loop between
+   `<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.
 
 ## Notes
 

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
@@ -37,10 +37,6 @@ start Build phase here; that's gated on accept.
 0. **Frame + clarify (entering DESIGN).** Before any CLI call, restate
    the user's intent in one sentence and list 1–3 sharp clarifying
    questions if any of these are ambiguous in `$ARGUMENTS`:
-   - **Actor + use case** — which actor initiates this? Does an
-     existing use case cover it, or is this a new user-visible
-     behaviour? (Check `npx archik q actors` and `q usecases` in
-     step 2 before asking if the answer isn't obvious from the brief.)
    - **Boundary** — which existing context owns this, or is it a new
      one? (data ownership = bounded context)
    - **Sync vs async** — request/response (`http_call`) or
@@ -57,15 +53,6 @@ start Build phase here; that's gated on accept.
    don't ask questions for the sake of asking.** When in doubt, ask
    the user "you decide?" so they can defer back if they want.
 
-   **Before the structural sidecar, check if the feature needs
-   requirements artifacts first:**
-   - New human-facing flow or actor? Create/update
-     `*.archik.actors.yaml` (direct-write) before staging the sidecar.
-   - New user-visible behaviour? Author a `*.archik.uc.yaml` under
-     `.archik/usecases/` (direct-write) with the flow and at least one
-     slice before staging the sidecar. The structural model references
-     what the use case requires.
-
 1. **Make sure the canvas is running** so the user can review:
    ```
    npx archik status
@@ -85,23 +72,6 @@ start Build phase here; that's gated on accept.
    If `$ARGUMENTS` mentions a specific node by name, also run
    `npx archik q describe <id>` for it.
 
-   If the change is **non-trivial** (new actor, new user-visible
-   behaviour, boundary impact, more than one node affected) also
-   ground in the requirements model:
-   ```
-   npx archik q actors
-   npx archik q usecases
-   ```
-   If any use case looks related, run
-   `npx archik q describe-usecase <id>` to see its slices and
-   check whether the proposed change extends, modifies, or
-   introduces a UC — that determines whether you need to update
-   a `*.archik.uc.yaml` before staging the structural sidecar.
-
-   If step 0 already determined the change is trivially small
-   (one node, one edge, no boundary or UC impact), skip the
-   actor/UC queries and go straight to step 3.
-
 3. **Lock in the schema.** Run this before drafting any YAML —
    the prose in this file describes the workflow, not the field
    shapes. The CLI is the schema:
@@ -135,18 +105,6 @@ start Build phase here; that's gated on accept.
    not just its kind or name. Empty / missing descriptions are
    rejected by the validator.
 
-   **For nodes that participate in a use case flow**, add a
-   `stereotype` field to classify their role in the ECB model:
-   - `stereotype: boundary` — accepts requests from actors / external
-     systems (adapters, gateways, API handlers)
-   - `stereotype: control` — orchestrates the use case logic (services,
-     use-case handlers, orchestrators)
-   - `stereotype: entity` — stores or represents domain data (repos,
-     domain models, DB-backed modules)
-
-   The validator enforces ECB transition rules on seq diagrams that
-   carry a `realizes` block — tag the nodes now so the rules can fire.
-
    ```bash
    npx archik suggest set --note "$ARGUMENTS" - <<'YAML'
    version: "1.0"
@@ -155,23 +113,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.
 
@@ -183,6 +169,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