archik 0.13.0 → 0.15.0

package/README.md

@@ -41,9 +41,11 @@ Actor → Use case → Slice → Tests on disk → Seq diagram → Nodes → Sou
 - 🤖 **AI-native** — installable Claude Code skill + 12 slash commands, and an MCP server for Cursor, Windsurf, Copilot, Claude Desktop, Zed
 - ✅ **Validator, not convention** — schema, cross-file references, `sourcePath` existence, use-case/actor/seq integrity, ECB rules
 - 🔍 **Traceability** — `archik trace` proves which use case slices are tested and realized; `--fail-on` gates CI
-- 🌿 **Git-aware** — `archik diff origin/main` shows what a branch changes architecturally; `archik affected` maps changed files to nodes, slices, and tests
-- 🤝 **Team-ready** — semantic merge driver for YAML, node ownership, and governance constraints (architecture fitness rules)
-- 🚀 **Fast adoption** — `archik import compose` bootstraps a diagram from docker-compose; `/archik:spawn` mirrors an existing source tree
+- 🌿 **Git-aware** — `archik diff origin/main` shows what a branch changes architecturally; `archik affected` maps changed files to nodes, slices, and tests (`--run` executes them); `archik hooks install` gates every commit
+- 🤝 **Team-ready** — semantic merge driver for YAML, node ownership with CODEOWNERS sync, and governance constraints (architecture fitness rules)
+- 🔬 **Verified at every altitude** — `validate` proves the model is consistent, `drift --edges` proves it matches the code's import graph, `otel check` proves it matches production traffic
+- 🧬 **Self-evolving** — opt-in `archik evolution` loop (observe → reflect → propose → validate → apply → measure) learns from your accepts, rejects, and failures and proposes its own upgrades behind a human approval gate; `archik patterns` ships the same design patterns for your systems
+- 🚀 **Fast adoption** — `archik import compose` / `import mermaid` bootstrap a diagram from what you already have; `/archik:spawn` mirrors an existing source tree
 - 📦 **Zero runtime dependencies** in the published package
 
 ## Installation
@@ -86,13 +88,14 @@ Day-to-day:
 | `/archik:usecase <name>` | A use case with flows, slices, and test paths |
 | `/archik:trace` | "Are we done?" — the coverage matrix |
 
-**Already containerised?** Skip the blank canvas:
+**Already have docker-compose or Mermaid diagrams?** Skip the blank canvas:
 
 ```bash
 npx archik import compose --out .archik/main.archik.yaml
+npx archik import mermaid docs/architecture.mmd --out .archik/main.archik.yaml
 ```
 
-Compose services become nodes (postgres → `database`, redis → `cache`, kafka → `stream`, …), build contexts become `sourcePath`s, and `depends_on` becomes edges.
+Compose services become nodes (postgres → `database`, redis → `cache`, kafka → `stream`, …), build contexts become `sourcePath`s, and `depends_on` becomes edges. The Mermaid importer parses the flowchart subset: shaped nodes map to kinds, subgraphs become module parents, arrows become labelled edges.
 
 ## The YAML
 
@@ -135,23 +138,35 @@ Full schema: `npx archik schema` (also `schema seq | uc | actors`).
 # What am I touching on this branch? Which tests cover it?
 npx archik affected --since main
 
+# …and run exactly those tests (vitest/jest/playwright/mocha auto-detected)
+npx archik affected --since main --run
+
 # What does this branch change architecturally?
 npx archik diff origin/main            # add --out diff.svg for the visual
 
 # Is the diagram still telling the truth?
 npx archik validate && npx archik drift
 
+# Do the EDGES match the code? (TS/JS import-graph verification)
+npx archik drift --edges               # shadow + phantom edge detection
+
 # Are we done?
 npx archik trace
 ```
 
 `affected` walks the chain backwards: changed files → nodes (via `sourcePath`) → use case slices (via tests and sequence-diagram participants) → tests to run — and flags changed files no node or test claims.
 
+`drift --edges` scans the imports under every node's `sourcePath` and reports **shadow edges** (code imports across nodes with no declared edge) and **phantom edges** (structural edges with no import in either direction). Gate every commit locally with:
+
+```bash
+npx archik hooks install               # pre-commit: archik validate
+```
+
 ## AI integration
 
 **Claude Code** (deepest integration): `archik init` installs a skill that enforces one hard 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 — 20 tools covering schema, queries, trace, validate, drift, affected, and the suggestion lifecycle:
+**Everything else** (MCP): `archik mcp` runs a stdio [Model Context Protocol](https://modelcontextprotocol.io) server exposing the same contract — 20 tools covering schema, queries, trace, validate, drift, affected, and the suggestion lifecycle, plus **resources** (`archik://schema`, `archik://stats`, `archik://trace`, `archik://validate`, `archik://drift`) and **prompts** (`propose-change`, `review-architecture`) that encode the same working loop the Claude Code skill teaches:
 
 ```jsonc
 // .cursor/mcp.json, claude_desktop_config.json, etc.
@@ -172,7 +187,7 @@ npx archik merge-driver --install    # once per clone; .gitattributes line is co
 
 Both branches added nodes → keep both. One side changed a field → take it. Same field changed differently, or modify-vs-delete → a real conflict, reported precisely.
 
-**Ownership.** `owner: team-billing` on a node answers "who do I talk to": `archik q describe payments-db`, `archik q list --owner team-billing`.
+**Ownership.** `owner: team-billing` on a node answers "who do I talk to": `archik q describe payments-db`, `archik q list --owner team-billing`. And `archik owners sync` writes one CODEOWNERS rule per owned node into a managed block (hand-authored rules untouched), with `archik owners check` as the CI gate so review routing can't drift from the model.
 
 **Governance constraints.** Architecture fitness rules, enforced by `archik validate` on every run:
 
@@ -191,6 +206,42 @@ constraints:
 
 Intentional exceptions are grandfathered by id in an `except` list — visible in review, never silent.
 
+## Verified against production
+
+Map nodes to your tracing backend's service names (`metadata.otelService`, node id as the fallback), export the service-dependency graph, and let archik compare:
+
+```bash
+curl -s "http://jaeger:16686/api/dependencies?endTs=$(date +%s)000&lookback=86400000" > deps.json
+npx archik otel check --graph deps.json
+```
+
+Undeclared production calls — traffic the diagram doesn't admit to — fail the check; declared wire edges that saw no traffic are reported informationally. That completes the truth chain: `validate` proves the model is consistent, `drift --edges` proves it matches the code, `otel check` proves it matches production.
+
+## Self-evolution
+
+Archik can learn from how you use it. Everything is opt-in, local-only, and human-gated:
+
+```bash
+archik evolution enable      # start observing (events stay on your machine)
+# ... normal work: suggestions accepted/rejected, validate/drift runs ...
+archik evolution reflect     # recurring friction → pending proposals with evidence
+archik evolution proposals   # read them
+archik evolution approve <id># apply: a learned.md note, or a sidecar diff you still review
+archik evolution report      # did it help? last 7 days vs the 7 before
+```
+
+Approved lessons land in `.archik/evolution/learned.md` — the Claude skill reads it at session start (and MCP agents via `archik://learned`), so the AI gets smarter across sessions without anyone editing prompts. Rejecting a proposal is recorded too; the loop learns from "no".
+
+Building a self-evolving system of your own? The same patterns ship as a library:
+
+```bash
+archik patterns list                  # evolution-loop, sidecar-approval-gate,
+archik patterns show evolution-loop   # learned-overlay, truth-chain, feedback-pipeline
+archik patterns apply evolution-loop  # stage the blueprint into YOUR diagram (gated)
+```
+
+Deep dives in [docs/advanced-topics](./docs/advanced-topics/README.md). In Claude Code: `/archik:self-evolving <your idea>`.
+
 ## CI
 
 Plain commands:
@@ -236,14 +287,19 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `archik watch` | Re-render SVG on every change |
 | `archik q <sub>` | Query: `describe` `deps` `dependents` `impact` `list` `edges` `stats` `usecases` `describe-usecase` `actors` `sequences` |
 | `archik diff <a> [b]` | Diff two files **or git refs**; one arg = that ref vs working tree |
-| `archik affected` | Changed files → nodes, slices, tests to run (`--since <ref>`, `--files`) |
+| `archik affected` | Changed files → nodes, slices, tests to run (`--since <ref>`, `--files`, `--run` to execute them) |
 | `archik trace` | Coverage matrix (`--fail-on partial\|none` for CI) |
-| `archik drift` | sourcePath / test-path gaps vs the source tree |
+| `archik drift` | sourcePath / test-path gaps vs the source tree (`--edges` verifies edges vs the TS/JS 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` (machine-checked), `demote` |
-| `archik import compose [file]` | Bootstrap a document from docker-compose |
+| `archik evolution <sub>` | Self-evolution loop: `enable` `status` `reflect` `proposals` `propose` `approve` `reject` `report` |
+| `archik patterns <sub>` | Self-evolution pattern library: `list` `show <id>` `apply <id>` |
+| `archik import compose\|mermaid [file]` | Bootstrap a document from docker-compose or a Mermaid flowchart |
 | `archik merge-driver --install` | Semantic git merge for `*.archik.yaml` |
-| `archik mcp` | MCP server over stdio for non-Claude-Code agents |
+| `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 (tools + resources + prompts) for non-Claude-Code agents |
 | `archik schema [seq\|uc\|actors]` | Print the document schemas |
 | `archik upgrade` | Upgrade + refresh installed skill/commands |
 

package/commands/self-evolving.md

@@ -0,0 +1,67 @@
+---
+description: Design a self-evolving architecture for an idea, using the pattern library
+argument-hint: <the system idea, e.g. "a code-review bot that learns">
+---
+
+# /archik:self-evolving — from vague idea to self-evolving architecture
+
+The user wants a system that **improves itself over time**, and they
+gave you the idea in `$ARGUMENTS`. Your job: guide them from that idea
+to a concrete architecture with an evolution loop — designs, use
+cases, and a staged diagram they can accept or reject.
+
+If `$ARGUMENTS` is empty, ask for the idea in one sentence first.
+
+## CLI-only — do not touch archik files directly
+
+All diagram reads go through `npx archik q`, all diagram writes
+through `npx archik suggest set` or `npx archik patterns apply`.
+Never `Read`/`Write`/`Edit` files under `.archik/`.
+
+## Steps
+
+1. **Load the pattern library** — this is your design vocabulary:
+   ```
+   npx archik patterns list
+   npx archik patterns show evolution-loop
+   ```
+   Read the other patterns (`sidecar-approval-gate`, `learned-overlay`,
+   `truth-chain`, `feedback-pipeline`) as they become relevant.
+
+2. **Interview briefly** (3 questions max, one at a time):
+   - Who corrects the system today? (those corrections = the feedback signal)
+   - What change should the system be able to make to itself?
+   - Who must approve a self-change before it lands?
+   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.
+
+4. **Map the idea onto the loop.** For each stage, name the concrete
+   component in THEIR system:
+   | Stage | Their component |
+   | --- | --- |
+   | observe | what gets logged, where |
+   | reflect | which rules find patterns |
+   | propose | where proposals live, who reads them |
+   | validate | what check keeps a bad self-change out |
+   | apply | the approval gate (use sidecar-approval-gate) |
+   | measure | the one metric that proves improvement |
+
+5. **Stage the architecture.** Two routes, both gated:
+   - Generic start: `npx archik patterns apply evolution-loop`
+     (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`.
+
+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.
+
+7. **Hand over.** Show the canvas URL, summarize which patterns you
+   used and why, and point at `npx archik evolution enable` if they
+   want archik's own loop watching this project too. **Wait for the
+   user to accept/reject — never accept the sidecar yourself.**