archik 0.20.0 → 0.21.0

package/README.md

@@ -110,6 +110,11 @@ There are no coordinates — layout is computed by [ELK](https://eclipse.dev/elk
 | --- | --- | --- |
 | Structure | `.archik/main.archik.yaml` | Services, databases, queues, agents, LLMs, edges |
 | Sub-architecture | `.archik/*.archik.yaml` | A node's internals, linked via `archikFile` |
+| Decisions | `.archik/decisions/NNNN-*.md` | Why each accepted change was made — context, decision, alternatives, consequences |
+
+The diagram says *what*; decision records say *why*. Every staged change carries one under `metadata.suggestion.decision` — `suggest set` refuses a draft without it — and accepting the change writes it as a numbered markdown record with the node and edge changes listed as evidence. Records are never edited; a later decision that changes course lists the old numbers in `supersedes`.
+
+Each change is also labelled by how hard it is to undo. A **one-way door** — a new data store, queue, external system, gateway, LLM or top-level module, a removal, or a boundary move — gets its own canvas review before the build plan; if it adds data, an outside system or public traffic, its record must say how it is secured, observed and rolled back. A **two-way door** goes through one combined review of model and plan.
 
 Full schema: `npx archik schema`.
 
@@ -126,7 +131,7 @@ npx archik affected --since main         # changed files → nodes → dependent
 npx archik otel check --graph deps.json  # edges vs a production service-dependency graph
 ```
 
-`validate` proves the model is internally consistent, `drift` that it matches the code, and `otel check` that it matches production traffic. `smells` needs no model: it reports folder loops with the real imports as evidence (only relative imports are resolved, so every loop is real) and points at the cheapest import to cut. Gate every commit locally:
+`validate` proves the model is internally consistent, `drift` that it matches the code, and `otel check` that it matches production traffic. `smells` needs no model: it reports folder loops with the real imports as evidence (only relative imports are resolved, so every loop is real) and points at the cheapest import to cut. On existing code, `archik smells --update-baseline` saves today's findings as known debt, so `--fail-on-warn` fails only on new loops and growing files. Gate every commit locally:
 
 ```bash
 npx archik hooks install       # pre-commit: archik validate
@@ -188,7 +193,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: bacharSalleh/archik@main
         with:
-          smells-fail: true   # optional gate; omit for report-only
+          smells-fail: true   # optional gate; with a committed baseline, fails only on new smells
 ```
 
 Inputs: `path`, `working-directory`, `validate`, `drift`, `smells-fail`, `compare-ref`, `comment`, `github-token`, `version`.
@@ -207,7 +212,7 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik dev` / `start` / `stop` / `status` | Live canvas lifecycle (foreground / detached) |
 | `archik validate [path]` | Schema + cross-file + constraints (exit 1 on error) |
 | `archik complexity [path]` | Flag over-large files, hub nodes, deep nesting (`--fail-on-warn` to gate) |
-| `archik smells [dir]` | Folder import loops + oversized source files, from the code (`--max-file-lines`, `--fail-on-warn`) |
+| `archik smells [dir]` | Folder import loops + oversized source files, from the code (`--max-file-lines`, `--fail-on-warn`, `--update-baseline`) |
 | `archik render --out <svg>` | Headless SVG render (`--focus <id>`, `--hide-structural`) |
 | `archik watch` | Re-render SVG on every change |
 | `archik q <sub>` | Query: `describe` `deps` `dependents` `neighbors` `impact` `list` `edges` `stats` |
@@ -215,7 +220,7 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik affected` | Changed files → nodes, dependents, model files, unmapped (`--since <ref>`, `--files`) |
 | `archik drift` | sourcePath gaps (`--edges` verifies edges vs the import graph) |
 | `archik otel check --graph <f>` | Verify edges against a production service-dependency graph |
-| `archik suggest <sub>` | Suggestion sidecar lifecycle: `show` `set` `accept` `reject` |
+| `archik suggest <sub>` | Suggestion sidecar lifecycle: `show` `set` `accept` `reject` — accept writes the decision record to `.archik/decisions/` |
 | `archik evolution <sub>` | Self-evolution loop: `enable` `reflect` `proposals` `approve` `reject` `report` |
 | `archik patterns <sub>` | Pattern library: `list` `show <id>` `apply <id>` |
 | `archik import compose\|mermaid [file]` | Bootstrap from docker-compose or a Mermaid flowchart |
@@ -224,7 +229,8 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik owners sync\|check` | Keep CODEOWNERS in step with node owners |
 | `archik mcp` | MCP server over stdio for non-Claude-Code agents |
 | `archik schema` | Print the document schema |
-| `archik upgrade` | Upgrade + refresh installed skill/commands |
+| `archik upgrade` | Upgrade + refresh installed skill/commands (`--migrate` also runs `archik migrate` with the new version) |
+| `archik migrate` | Bring the project's archik files up to the installed version — archives first, validates after (`--dry-run`) |
 
 Default file resolution: `.archik/main.archik.yaml`, falling back to the legacy `architecture.archik.yaml` (both present is an error).
 
@@ -238,6 +244,7 @@ Reach for archik when a project has more than a handful of components, ships wit
 | AI-editor integration | **Skill + MCP** | None | None |
 | Structural smells from code | **Yes** | No | No |
 | Drift detection | **Yes** | No | No |
+| Decision records tied to model changes | **Yes** | No | No |
 | Governance constraints | **Yes** | No | No |
 | Validator | **Schema + cross-file + constraints** | Syntax only | Syntax only |
 

package/commands/accept.md

@@ -31,6 +31,11 @@ done at step 1 — the diagram changed; the code probably hasn't.
 
 3. **BUILD — plan (HITL).**
 
+   **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`,
@@ -42,6 +47,10 @@ done at step 1 — the diagram changed; the code probably hasn't.
      consumer handler; `writes` needs a repository method; etc).
    - Any node still `status: proposed` → flag it; code must land
      before flipping to `active`.
+   - If the accepted decision record has `crossCutting`, each
+     promise becomes a plan item: the security control, the signal
+     (log / metric / alert) and the rollback path (flag, revert,
+     migration down-step).
    - Default to **tests-first** when behaviour is clearly bounded.
    - If `superpowers:writing-plans` is available, use it; else
      inline.
@@ -84,6 +93,11 @@ done at step 1 — the diagram changed; the code probably hasn't.
    Catches folder loops and oversized files, with the real imports
    as evidence. A new loop is a gap — cut the cheapest import (or
    queue a `/archik:suggest`) before declaring the milestone done.
+   With a committed baseline (`.archik/smells-baseline.json`) only
+   findings marked **NEW** count; known debt is not this change's job.
+
+   For a one-way door, confirm each `crossCutting` promise from the
+   decision record is in the code before flipping nodes to `active`.
    `superpowers:verification-before-completion` when available.
    If `docs/architecture.svg` is committed, regenerate it:
    ```

package/commands/bootstrap.md

@@ -64,6 +64,8 @@ brief and start the DESIGN loop.
    > forces priorities into the open before any code lands. New
    > nodes start `status: proposed` (the code doesn't exist on disk
    > yet) and flip to `status: active` when the code lands in BUILD.
+   > Only the first milestone is modelled in detail; later areas stay
+   > coarse placeholders until their turn.
    > The commitment lives in the YAML, not in the chat log."
 5. When the brief lands, run the standard DESIGN loop:
    `/archik:suggest` (structural sidecar) → `/archik:accept` →
@@ -91,7 +93,9 @@ diagram, then iterate from honest ground truth.
    duplicate them here.
 4. After the user accepts the spawn sidecar, suggest the natural
    follow-up: "Want to check the code for structural smells?
-   `npx archik smells` finds folder loops and oversized files."
+   `npx archik smells` finds folder loops and oversized files — and
+   `--update-baseline` saves today's findings so CI fails only on new
+   ones."
 
 ### C. `.archik/` exists but the diagram is empty or near-empty
 

package/commands/evolve.md

@@ -107,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
    ```
 

package/commands/migrate.md

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

package/commands/self-evolving.md

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

package/commands/spawn.md

@@ -155,6 +155,13 @@ archik suggest set` stages it.
       name: <Id> Internals
       nodes: [ ... ]
       edges: [ ... ]
+      metadata:
+        suggestion:
+          decision:
+            context: <why this split is needed>
+            decision: <what you chose>
+            alternatives: [<option not chosen>]
+            consequences: <what gets easier and harder>
       YAML
       # mechanical: puts sub-file on disk so the main draft's
       # archikFile: pointer validates. NOT the user's review gate
@@ -191,9 +198,21 @@ archik suggest set` stages it.
         # full proposed end-state, with archikFile pointers
       edges:
         # ...
+      metadata:
+        suggestion:
+          decision:
+            context: <what the source tree shows and why it is split this way>
+            decision: <what you chose>
+            alternatives: [<option not chosen>]
+            consequences: <what gets easier and harder>
       YAML
       ```
 
+      Every draft needs its decision record — `suggest set` refuses
+      one without it. For a spawn, the context is what the source
+      tree shows; the alternatives are other ways to cut it (one
+      flat file, a different grouping).
+
    c. If `suggest set` reports validation errors, re-run with the
       corrected YAML. Never edit the sidecar by hand.
 
@@ -215,6 +234,12 @@ archik suggest set` stages it.
    `<a>` and `<b>`? The cheapest cut is `<file imports "specifier">`."*
    If it finds none, skip this line.
 
+   Existing code almost always has some debt. Also offer the
+   baseline so CI can gate on *new* smells from now on: *"Want me to
+   save today's findings as the baseline (`npx archik smells
+   --update-baseline`, commit `.archik/smells-baseline.json`)? Then
+   `--fail-on-warn` only fails on new loops or growing files."*
+
    Do NOT fix smells here — spawn is descriptive, and the fix is a
    separate ask from the user. This note is a prompt, not an action.
 

package/commands/suggest.md

@@ -26,7 +26,7 @@ the contract with the user.
 
 The skill defines a 5-phase loop: **Discover → Design → Decide → Build
 → Verify**. This command covers Discover (grounding) and Design
-(staging the sidecar with rationale), then hands off to the user's
+(staging the sidecar with its decision record), then hands off to the user's
 review and the explicit Decide gate (`/archik:accept` or
 `/archik:reject`). Don't skip clarification just because a slash
 command was typed — clarification is what makes the draft good. Don't
@@ -113,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.
 
@@ -141,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