archik 0.14.0 → 0.15.1

package/README.md

@@ -44,6 +44,7 @@ Actor → Use case → Slice → Tests on disk → Seq diagram → Nodes → Sou
 - 🌿 **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
 
@@ -216,6 +217,31 @@ 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:
@@ -267,6 +293,8 @@ Every command supports `--help`; agent-facing commands support `--json`.
 | `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 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 hooks install` | Pre-commit hook running `archik validate` (`--with-drift` optional) |

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.**