archik 0.12.34 → 0.12.36

package/.claude/commands/archik/actor.md

@@ -0,0 +1,89 @@
+---
+description: Add or update an actor in the actor index
+argument-hint: <actor id> [— description]
+---
+
+# /archik:actor — author an entry in `*.archik.actors.yaml`
+
+The user wants you to add (or update) an actor in the project's actor
+index. Actors are *who* initiates use cases — humans (end users,
+operators, customers) or non-human systems (other services, schedulers,
+external APIs). The user-facing description is:
+
+**$ARGUMENTS**
+
+This slash command IS the user's confirmation. Skip "want me to add
+this?" and produce the change now.
+
+## Direct-write — not the sidecar workflow
+
+Actors live in `.archik/actors.archik.actors.yaml` (one file per
+project, conventionally). Authored with `Write` / `Edit` directly,
+then validated via `npx archik validate`.
+
+## Steps
+
+0. **Frame.** Restate the user's intent in one sentence and ask 1–2
+   sharp questions only if any of these are unclear:
+   - **Actor kind** — `human` (end user / operator / customer),
+     `external-system` (third-party service we don't own),
+     `time` (scheduler / cron), or `device` (sensor / hardware)?
+   - **Goals** — one short sentence per goal the actor pursues
+     against this system. Optional but useful.
+
+   Skip questions `$ARGUMENTS` already answers.
+
+1. **Ground in current actors:**
+   ```
+   npx archik q actors
+   ```
+   If the id already exists, this is an UPDATE — read the existing
+   entry's fields and preserve everything the user didn't ask to
+   change. Otherwise it's a NEW addition.
+
+2. **Lock in the schema:**
+   ```
+   npx archik schema actors
+   ```
+   Required: `id`, `kind`, `description`. Optional: `goals`.
+
+3. **Edit the file.** If `.archik/actors.archik.actors.yaml` doesn't
+   exist yet, `Write` a new file with the standard header. If it
+   exists, `Edit` to add/update the one actor you're touching — do
+   NOT rewrite the whole file unless you're consolidating.
+
+   ```yaml
+   version: "1.0"
+   actors:
+     - id: <kebab-id>
+       kind: human          # human | external-system | time | device
+       description: One sentence — who they are and why they touch the system.
+       goals:
+         - "Verb-first short outcome they pursue."
+   ```
+
+4. **Validate:**
+   ```
+   npx archik validate
+   ```
+   Common failures:
+   - Duplicate `id` across actor files
+   - Missing `description` (required, non-empty)
+   - `kind` not in the allowed enum
+
+5. **Confirm inline.** Print the actor's id, kind, and description.
+   Ask: "Looks right? Want me to author a use case (`/archik:usecase`)
+   that has this actor as `primaryActor`?"
+
+   Don't auto-proceed. Inline-review gate.
+
+## Notes
+
+- Actors must exist BEFORE any use case can reference them. The
+  use case validator rejects dangling `primaryActor` / `secondaryActors`
+  references with the actor id named in the error.
+- The `external` node kind in the structural model is for third-party
+  systems that participate in the *runtime* graph. The `external-system`
+  actor kind is for systems that *initiate* use cases. They overlap
+  conceptually but live in different files — actor file for "who acts
+  on us", structural file for "what we integrate with".

package/.claude/commands/archik/alpha.md

@@ -0,0 +1,71 @@
+---
+description: Show alpha state snapshot, or promote one with criteria check
+argument-hint: [show | promote <alpha> <state> | demote <alpha> <state>]
+---
+
+# /archik:alpha — read or move project alphas
+
+Alphas (Essence / SEMAT) are the universal progress dials of the
+project. The user wants either a snapshot of all alphas, or a
+deliberate promotion / demotion with the underlying criteria
+verified mechanically. Argument:
+
+**$ARGUMENTS**
+
+## Branches
+
+### No args / `show`
+
+Run:
+```
+npx archik alpha show
+```
+
+Read the table. For each alpha:
+- `✓` means the claimed state is satisfied by the current artifacts
+- `?` means the state can't be fully verified (manual review needed)
+- `✗ over-claimed` means the artifacts don't meet the criteria —
+  surface this as a blocker
+
+Translate the table into a short paragraph: which alphas are honest,
+which are over-claimed, and what one concrete next action would
+unblock the most progress (usually whichever alpha is closest to
+its next state and just needs one more artifact).
+
+### `promote <alpha> <state>`
+
+Run the promotion (it runs the criteria check first and refuses if
+the state isn't satisfied):
+```
+npx archik alpha promote <alpha> <state>
+```
+
+If it succeeds, narrate which evidence satisfied the criteria. If it
+refuses, name the specific criterion that failed and the concrete
+artifact that would satisfy it (e.g. "to promote `requirements` to
+`addressed`, every active slice needs `realization.seqFile` — slice
+X currently has none. Author `.archik/X.archik.seq.yaml` with
+`realizes: { useCase, slice }` and re-run.").
+
+### `demote <alpha> <state>`
+
+```
+npx archik alpha demote <alpha> <state> --note "<reason>"
+```
+
+Demotion is a deliberate admission that the project no longer meets
+a previously-claimed state. Always prompt for the `--note` reason if
+the user didn't supply one — the audit trail matters.
+
+## Notes
+
+- Alphas tracked: `stakeholders`, `requirements`, `softwareSystem`,
+  `work` (the four Essence alphas most directly evidenced by archik
+  artifacts). State ladders match the Essence kernel — see
+  `npx archik alpha show --json` for the full enum.
+- The alpha file lives at `.archik/alphas.archik.alphas.yaml` —
+  direct-write only via this command (or the underlying CLI). Don't
+  edit it by hand; the criteria check is the discipline.
+- Over-claiming is fixed by EITHER advancing artifacts OR demoting
+  the state. Whichever is easier given the project's actual
+  trajectory. Don't fudge.

package/.claude/commands/archik/trace.md

@@ -0,0 +1,55 @@
+---
+description: Show the use case × slice × test × seq × ECB coverage matrix
+argument-hint: [filters — see notes]
+---
+
+# /archik:trace — surface the Jacobson coverage matrix
+
+The user wants to see how completely the project's use cases are
+traced — for each slice: are tests declared, is a seq diagram
+realising it, are participants ECB-tagged. Optional filter args:
+
+**$ARGUMENTS**
+
+## Steps
+
+1. Run the trace CLI. If `$ARGUMENTS` is empty, full matrix:
+   ```
+   npx archik trace
+   ```
+   If the user passed a filter (`use-case=<id>`, `actor=<id>`,
+   `status=active|proposed|deprecated`, `coverage=full|partial|none`),
+   pass it through as a query flag:
+   ```
+   npx archik trace --<filter>=<value>
+   ```
+
+2. **Read the totals row** at the bottom (`X full, Y partial, Z untraced`)
+   and surface it in your reply as the headline answer:
+   - **All full** → "✓ Every active slice is fully traced. Ready to ship."
+   - **Any partial** → "◐ N partial slices — listed below; each is
+     missing tests, a realisation seq, or full ECB tagging."
+   - **Any untraced** → "○ N untraced slices — these slices declare
+     neither tests nor a seq realisation. Address before milestone close."
+
+3. **For each partial / untraced row**, narrate ONE concrete next
+   action — e.g. "`pubmed-abstract-only` has tests but no seq —
+   author `.archik/<slice>.archik.seq.yaml` with `realizes:
+   { useCase: …, slice: pubmed-abstract-only }`".
+   Don't dump raw rows; the user can read those in the CLI output if
+   they want. Your job is to translate the matrix into actions.
+
+4. **If everything is full**, also run `npx archik alpha show` and
+   call out any alpha that's now eligible for promotion. The trace
+   matrix is a major input to `requirements: addressed` and
+   `softwareSystem: ready`.
+
+## Notes
+
+- The matrix is also visible on screen via the **Use cases** toolbar
+  badge (rolled-up, "am I done?" answer) and the dedicated
+  `/__archik/usecases` page (per-slice breakdown). Mention this if
+  the user wants visual context.
+- The check has CI teeth: `npx archik trace --fail-on partial`
+  exits non-zero on any partial; `--fail-on none` exits non-zero on
+  untraced only. Suggest the right flag for their CI gate if asked.

package/.claude/commands/archik/usecase.md

@@ -0,0 +1,134 @@
+---
+description: Author a use case (actors + flows + slices + tests)
+argument-hint: <use case name or id>
+---
+
+# /archik:usecase — author a `*.archik.uc.yaml`
+
+The user wants you to author a **use case** that captures user-visible
+behaviour as actors + flows + slices, with each active slice backed by
+test paths on disk. The user-facing description is:
+
+**$ARGUMENTS**
+
+This slash command IS the user's confirmation. Skip "want me to draft
+this?" and produce a use case file now.
+
+## Direct-write — not the sidecar workflow
+
+Use case files are authored with `Write` directly (unlike structural
+sidecars which go through `suggest set`). After writing, validate via
+`npx archik validate`. If validation fails, fix and re-write.
+
+## This is the DESIGN (b) handoff of the engineering loop
+
+The skill defines a 5-phase loop: **Discover → Design → Decide → Build
+→ Verify**. This command covers Discover (ground in current actors and
+use cases) and the Design (b) Requirements step. The output is a
+reviewable artifact gated by **inline review** (you show the YAML in
+chat, the user confirms) — *not* the canvas gate (that's only for
+structural sidecars).
+
+## Steps
+
+0. **Frame + clarify.** Restate the user's intent in one sentence and
+   ask 1–3 sharp clarifying questions if any of these are ambiguous in
+   `$ARGUMENTS`:
+   - **Primary actor** — who initiates this use case? (Will need to
+     resolve in the actor index — check step 1 first.)
+   - **Goal** — what does the actor want to accomplish in business
+     terms (one sentence, observable outcome)?
+   - **Pre / postconditions** — what must be true before/after? (Skip
+     if obvious.)
+   - **Slice scope** — happy path only, or also one or two alternates
+     (e.g. payment-declined, validation-failed, retry)? Each slice =
+     one flow subset + one test path.
+
+   Skip questions `$ARGUMENTS` already answers. **Use judgment.**
+
+1. **Ground in the current models.** Check who the actors are and
+   what use cases exist already so you reuse rather than duplicate:
+   ```
+   npx archik q actors
+   npx archik q usecases
+   ```
+   If the primary actor isn't in the actor index, STOP and tell the
+   user — they need `/archik:actor <id>` first (or you offer to run
+   it). Use cases without resolving actors fail validation.
+
+2. **Lock in the schema:**
+   ```
+   npx archik schema uc
+   ```
+   Required fields: `id`, `name`, `primaryActor`, `goal`, `flows.basic`,
+   at least one slice with `id`, `description`, `flows`, `tests`.
+   Optional: `secondaryActors`, `preconditions`, `postconditions`,
+   alternate flows, slice realization (`seqFile`).
+
+3. **Write the file** to `.archik/usecases/<id>.archik.uc.yaml`. Use
+   the `Write` tool — direct-write, no sidecar.
+
+   **Slice test paths must exist on disk** for `status: active` slices.
+   Validator rejects active slices whose test files are missing. If
+   the test isn't written yet, mark the slice `status: proposed` —
+   you'll flip it to `active` once the test lands in the BUILD phase.
+
+   ```yaml
+   version: "1.0"
+   id: <kebab-id>
+   name: <Human-readable name>
+   primaryActor: <actor-id>     # must resolve in actors index
+   goal: One sentence describing the observable outcome.
+   preconditions: [<…optional…>]
+   postconditions: [<…optional…>]
+   flows:
+     basic:
+       steps:
+         - "Actor does X."
+         - "System does Y."
+         - "Actor receives Z."
+     alternates:
+       - id: <kebab-id>
+         branchFrom: basic.<step-number>
+         steps: ["…"]
+   slices:
+     - id: happy
+       description: One-line slice summary.
+       flows: [basic]
+       tests: [<path/to/test/file.spec.ts>]   # must exist OR slice must be `status: proposed`
+   ```
+
+4. **Validate:**
+   ```
+   npx archik validate
+   ```
+   Expect zero errors. If validation fails, the message names the
+   field — fix and re-write. Common failures:
+   - `primaryActor` doesn't resolve in actors index → ensure the
+     actor file has that id
+   - `flows.basic` missing → required by schema
+   - `branchFrom` references unknown step → `basic.4` requires
+     `flows.basic.steps` to have at least 4 entries
+   - Slice tests path doesn't exist → either create the test file
+     stub or mark the slice `status: proposed`
+
+5. **Show inline + confirm.** Print the file's path and a short
+   summary of what it covers (actor / number of flows / slice ids /
+   test paths). Ask: "Looks right? Once you confirm, want me to
+   stage the structural sidecar (`/archik:suggest`) for the nodes
+   this use case implies?"
+
+   Don't auto-proceed. The user's "looks good" IS the inline-review
+   gate.
+
+## Notes
+
+- If the use case implies new structural nodes (a new service, a new
+  external integration), the next step is `/archik:suggest` — that
+  gate is separate.
+- If the slice has non-trivial runtime branching, async fan-out, or
+  cross-context interaction, plan for a `*.archik.seq.yaml` next that
+  carries `realizes: { useCase: <id>, slice: <id> }` and binds
+  participants to the structural nodes.
+- Actor must exist BEFORE the use case file is written. Use cases
+  reference `primaryActor` by id; the validator rejects dangling refs.

package/README.md

@@ -102,8 +102,36 @@ No `x` / `y` / `width` — layout is computed by [ELK](https://eclipse.dev/elk/)
 - **27 node kinds** across compute, data, messaging, networking, hexagonal, AI/ML, identity, observability, cloud, UI, and external.
 - **12 relationships** with distinct visual styling — `http_call`, `invokes`, `reads`, `writes`, `publishes`, `subscribes`, `streams_to`, `routes_to`, `implements`, `depends_on`, `has_a`, `uses`.
 - **Drag-to-connect, multi-select, undo/redo, compact view, themed (dark / light), notes per node, color overrides on edges.**
-- **CI-ready CLI** — `validate`, `render` (headless SVG), `watch`, `check` (drift between YAML and source dirs).
-- **AI skill + slash commands** — `archik init` installs both automatically. Seven `/archik:*` commands (`spawn`, `evolve`, `suggest`, `describe`, `dev`, `accept`, `reject`) drive the diagram entirely through the CLI, so Claude never edits YAML by hand.
+- **CI-ready CLI** — `validate`, `render` (headless SVG), `watch`, `drift` (source-tree gaps), `trace` (coverage matrix with `--fail-on partial|none`).
+- **AI skill + slash commands** — `archik init` installs both automatically. Eleven `/archik:*` commands cover the structural surface (`spawn`, `evolve`, `suggest`, `describe`, `dev`, `accept`, `reject`) plus the requirements layer (`actor`, `usecase`, `trace`, `alpha`).
+
+## Beyond the diagram — use cases, traceability, alphas
+
+The structural diagram is the start. Above it sits a thin requirements
+layer that closes the Jacobson chain — *who acts → what they want →
+how the system behaves at runtime → which structural nodes participate
+→ which tests prove it*. Every link is a YAML cross-reference and the
+validator rejects breaks at every step.
+
+| Artifact                       | File                                | What it captures                                              |
+| ------------------------------ | ----------------------------------- | ------------------------------------------------------------- |
+| **Actors**                     | `*.archik.actors.yaml`              | Who initiates use cases — humans, external systems, schedulers |
+| **Use cases + slices**         | `.archik/usecases/*.archik.uc.yaml` | What each actor wants, with slim slices that name test paths   |
+| **Sequence diagrams**          | `*.archik.seq.yaml`                 | How a slice plays out at runtime (ECB-checked when bound to a slice via `realizes`) |
+| **Alphas (Essence / SEMAT)**   | `*.archik.alphas.yaml`              | Project-wide progress dials with mechanically-verified states  |
+
+`npx archik trace` prints the coverage matrix (use case × slice × test
+× seq × ECB) so "are we done?" stops being an opinion. The dev canvas
+surfaces the same information visually: the **Use cases** toolbar
+button shows live trace status (`✓ all traced` / `◐ N to finish` /
+`○ N untraced`), and `/__archik/usecases` is a dedicated page with
+master/detail rail, slice cards with clickable test paths, and direct
+links to each realising sequence diagram.
+
+The `validate` command enforces the integrity triangle: if a slice
+points at a seq file, the seq must point back; if a seq diagram
+realises a slice, every participant node must list that seq in its
+`seqFiles` array. Orphans get caught at lint time, not in code review.
 
 ## For Claude Code & other LLMs
 
@@ -111,7 +139,9 @@ The whole reason archik uses YAML instead of a binary format: **the file is the
 
 The skill enforces a hard rule: **Claude talks to archik only through the `npx archik` CLI** — never `Read`, `Write`, or `Edit` on a YAML directly. Queries go through `npx archik q`, suggestions through `npx archik suggest set`, lifecycle through `npx archik suggest accept | reject`. You own the file; the CLI is the contract.
 
-### The seven slash commands
+### The slash commands
+
+**Structural diagram (the original surface):**
 
 | Command                     | What it does                                                |
 | --------------------------- | ----------------------------------------------------------- |
@@ -123,6 +153,15 @@ The skill enforces a hard rule: **Claude talks to archik only through the `npx a
 | `/archik:accept`            | Apply the pending suggestion                                |
 | `/archik:reject`            | Discard the pending suggestion                              |
 
+**Requirements + traceability (the Jacobson layer — see below):**
+
+| Command                              | What it does                                                                |
+| ------------------------------------ | --------------------------------------------------------------------------- |
+| `/archik:actor <id>`                 | Add or update an actor in the actor index                                   |
+| `/archik:usecase <name>`             | Author a use case (actors + flows + slices + tests)                         |
+| `/archik:trace`                      | Show the use case × slice × test × seq × ECB coverage matrix                |
+| `/archik:alpha [show \| promote …]`  | Read the project's alpha state, or promote one with a criteria check        |
+
 A typical first-day flow:
 
 ```
@@ -170,6 +209,24 @@ archik render [path]     Render to a self-contained SVG file
                          --theme <name>   "dark" (default) or "light"
 archik watch [path]      Re-render to SVG on every file change (Ctrl+C to stop)
 
+archik trace [path]      Use case × slice × test × seq × ECB coverage matrix
+                         --json              structured rows + summary
+                         --fail-on <level>   exit 1 on partial | none (CI gate)
+                         --use-case <id>     filter to one use case
+archik drift [path]      Surface gaps where a node's sourcePath or a slice's
+                         tests path no longer resolves on disk
+
+archik alpha [sub]       Project-wide alpha state (Essence / SEMAT)
+                         show              snapshot with ✓ / ? / ✗ verification
+                         promote <a> <s>   advance an alpha — runs criteria first
+                         demote <a> <s>    walk back; --note '<reason>' required
+
+archik upgrade           Pull the latest archik via the project's package manager
+                         (auto-detects npm / pnpm / yarn / bun from the lockfile)
+                         then refreshes SKILL.md + slash commands from the new binary
+                         --skip-install    just refresh artifacts; don't reinstall
+                         --user            install to ~/.claude (global skill)
+
 archik suggest [sub]     Manage Claude's pending architecture suggestion
                          show             summarise the pending sidecar (default; --json supported)
                          set <draft>      validate a draft YAML and stage it as the sidecar