wicked-garden 12.27.0

package/docs/plans/2026-06-10-codegraph-to-brain-phase1b-injected-edges.md

@@ -0,0 +1,44 @@
+# Codegraph → Brain, Phase 1b: Injected Edges + Extractor Registry — Plan
+
+> **For agentic workers:** executed via subagent-driven-development against the wicked-brain repo (branch `feat/codegraph-graph-core`, same as Phase 1a). Builds on Phase 1a's `codegraph-client`/`codegraph-index`.
+
+**Goal:** Materialize wicked-ecosystem **injected edges** (grep-/static-invisible, string-wired relationships) into the codegraph graph so blast-radius/lineage traverse them — with a pluggable registry so brain ships generic extractors and any plugin can drop in proprietary ones (Decision D3). **Zero garden dependency.**
+
+**Repo:** `/Users/michael.parcewski/Projects/wicked-brain` (worktree `.claude/worktrees/codegraph-phase1a`).
+
+---
+
+## Decisions
+
+| # | Decision | Why |
+|---|---|---|
+| B1 | Brain **ships** built-in extractors that read only target-repo files/conventions: **bus** (`_bus_consumers.json` + emit sites), **dispatch** (`subagent_type:` in `commands/**/*.md` → `agents/<d>/<n>.md`), **capability** (agent `tool-capabilities:` frontmatter → `capability:<name>` nodes, **frontmatter-only — no registry import**). | These are wicked-bus / Claude-plugin conventions, not garden internals. No garden code is imported (the garden `capability` extractor's `_capability_registry` import is dropped — registry *filtering* becomes a drop-in concern). |
+| B2 | **Drop-in registry**: brain scans `<sourcePath>/.codegraph-extractors/*.mjs`, dynamic-imports each, runs its `extract({db, sourcePath, nodes})`. Absent dir → no-op. | D3 mechanism. Garden's proprietary archetype extractor (Phase 2) drops in here. Dependency points target→brain only; brain never imports the drop-in's repo. |
+| B3 | Extractors write to the codegraph SQLite **read-write** (better-sqlite3). Each is **idempotent**: `DELETE FROM edges WHERE provenance=?` (its own), re-insert. Self-node markdown/virtual nodes via `ensureFileNode`/`ensureVirtualNode` (codegraph indexes code, not .md — issue garden#916). | Matches the garden Python extractors' contract; injected edges co-locate in the same `nodes`/`edges` tables as the static graph (ADR 0001). |
+| B4 | `graph-index` runs the codegraph build **then** all extractors (built-in + drop-in) in one pass, so a single action yields the complete graph. Re-index drops injected edges (codegraph rebuild) → extractors re-apply every run. | One front door; blast-radius never sees a stale/empty injected layer. |
+
+Edge convention (from Phase-1a contract): edge `(source, target, kind, metadata, provenance)`; injected edges use `kind="references"`, `provenance="injected:<mechanism>"`, semantics in `metadata`. Direction matches static edges so `DEPENDENTS_BY="target"` blast-radius surfaces the dependent (e.g. consumer is a dependent of producer ⇒ edge `source=consumer? ...`). **NB:** the garden bus extractor inserts `edge(source=producer, target=consumer)`; verify against Phase-1a blast-radius direction during implementation and align so blast-radius(producer) surfaces the consumer (see Task B-real).
+
+## File structure (brain `server/`)
+
+| File | Responsibility |
+|---|---|
+| `lib/codegraph-nodes.mjs` | `ensureFileNode(db, relpath, lang?)`, `ensureVirtualNode(db, id, kind, name, filePath?)` — idempotent `INSERT OR IGNORE` populating all NOT NULL node cols. Port of `_graph_nodes.py`. |
+| `lib/codegraph-extractors/bus.mjs` | `extract({db, sourcePath})` — read `scripts/_bus_consumers.json` + grep `wicked|wg.x` event strings in `scripts/**/*.py`; insert producer→consumer edges (`injected:bus`). |
+| `lib/codegraph-extractors/dispatch.mjs` | command→agent edges from `subagent_type:` handles resolving to `agents/<d>/<n>.md` (`injected:dispatch`). |
+| `lib/codegraph-extractors/capability.mjs` | agent→`capability:<name>` edges from `tool-capabilities:` frontmatter (`injected:capability`); creates virtual capability nodes. |
+| `lib/codegraph-extract.mjs` | registry: `BUILTINS=[bus,dispatch,capability]`; `discoverDropins(sourcePath)` scans `<sourcePath>/.codegraph-extractors/*.mjs`; `runExtractors({db, sourcePath})` runs all, returns `{<label>:counts, total_injected_edges, dropins:[...]}`. Fail-open per extractor. |
+| `bin/wicked-brain-server.mjs` | `graph-index` action: after `runIndex`, open db read-write, `runExtractors`, return build + injection stats + staleness. |
+| `test/codegraph-nodes.test.mjs`, `test/codegraph-extract.test.mjs`, per-extractor tests | fixtures with the wiring; assert edges materialized + idempotency + drop-in discovery (present/absent). |
+
+## Tasks (TDD, subagent-driven)
+
+- **B1 nodes**: `codegraph-nodes.mjs` + test (ensure file/virtual node idempotent; all NOT NULL cols set).
+- **B2 bus extractor**: `extractors/bus.mjs` + test (fixture repo with `scripts/_bus_consumers.json` + a producer .py emitting the event + the consumer module node; assert producer→consumer edge with `injected:bus`; idempotent re-run).
+- **B3 dispatch + capability extractors** + tests (fixture command/agent .md with `subagent_type:` and `tool-capabilities:`).
+- **B4 registry**: `codegraph-extract.mjs` + test (runs builtins; discovers a drop-in `.mjs` in `.codegraph-extractors/` and runs it; absent dir → builtins only; one failing extractor doesn't abort the rest).
+- **B5 wire `graph-index`** to run extractors after build + test (action returns injection stats; read actions unaffected).
+- **B-real**: real-repo test — point brain at **wicked-garden**, `graph-index`, then `graph-blast-radius` on a bus producer module; assert a consumer wired only via the event string appears in the blast radius (a link grep cannot find). This is the Phase-1b acceptance + part of the goal's "tested on a real repo".
+
+## Out of scope
+Registry-filtered capability validation (drop-in concern); hooks event→script extractor (additive later); import-node→file resolution (Phase 1a limitation).

package/docs/required-peers.md

@@ -0,0 +1,60 @@
+# Peers — two required, three opt-in
+
+Wicked Garden is a **curated toolkit**, and like any toolkit you can use the
+parts you want. Only one thing is non-negotiable: the **evidence gate**. A gate
+that can't re-derive its own evidence is the single thing the toolkit refuses to
+fake — so its two peers are required. Everything else is an **opt-in layer**:
+install it for the capability it unlocks, skip it and the rest of the kit still
+works.
+
+> **History:** v12 briefly made all five peers required infrastructure. That
+> maximized the honesty guarantee and minimized adoption — you couldn't try the
+> toolkit without standing up five things first. We walked it back: the gate
+> stays required (that's the floor), the other three became opt-in layers.
+
+## Required — the evidence gate (setup blocks without these)
+
+| Peer | What it does | Install |
+|------|--------------|---------|
+| **wicked-vault** | The honest-evidence backend the gate re-derives against: record → re-hash + re-run the verifier → cross-check. Never trusts a cached status. | `npx wicked-vault-install` (npm; pinned `^0.3.0`). Resolved at runtime via `WICKED_VAULT_BIN` → config → `PATH` → `node_modules` → `npx wicked-vault`. |
+| **wicked-loom** | The gate engine garden drives: peer resolution (`loom resolve`), synchronous fail-closed evidence gating (`loom gate`), and the flow runtime (`loom flow run/status/resume`). It is the *sole* re-derivation engine — without it the produces-gate fails closed. | `npx wicked-loom` (npm; pinned `^0.2.0`). Resolved via `WICKED_LOOM_BIN` → config → `PATH` → `node_modules` → `npx wicked-loom`; `WICKED_LOOM_BIN=""` is the kill-switch. |
+
+`/wicked-garden:setup` **blocks** without these two — a toolkit whose headline is
+"done is re-derived, not asserted" cannot ship the gate as optional.
+
+## Opt-in layers (setup recommends; never blocks)
+
+Add what you want. Each unlocks one capability; the rest of the toolkit (the gate,
+the code graph, wicked-patch, the council, the rubric skill-refs) runs without any
+of them.
+
+| Layer | What it unlocks | Skip it and… | Install |
+|-------|-----------------|--------------|---------|
+| **wicked-testing** | Evidence-gated acceptance testing with writer/executor/**independent reviewer** separation — no self-graded "it passed." | the produces-gate still works (via vault+loom); you just don't get the acceptance-testing tool. | `npx wicked-testing install` (npm `^0.3.0`) |
+| **wicked-brain** | The memory layer — cross-session recall, cited search, `smaht:briefing`. Carries decisions/gotchas from session 1 to session 47. | structural search (`blast-radius`/`lineage`/`hotspots`, via codegraph) still works; you lose cross-session memory + semantic search. | `/plugin install wicked-brain` (npm `0.14.0`) |
+| **wicked-bus** | The audit-trail layer — append-only events recording what happened. | nothing breaks — emission is already fire-and-forget / fail-open; events just aren't recorded. | `/plugin install wicked-bus` (npm `2.0.0`) |
+| **wicked-understanding** | The repo-playbooks layer — analyzes the repo at HEAD into task playbooks (`fix-bug`/`add-feature`/`verify`/`write-tests`/`scaffold`) that tell the agent *how to work in this repo*: the file that owns the bug, the wiring step, the test command, the gotcha. Pairs with brain — brain is the *what*, this is the *how* (`repo-analyst --enrich-from-brain` folds in design rationale). | the agent re-derives the method from scratch each task; the rest of the toolkit works. | `npx skills add mikeparcewski/wicked-understanding --all` (skills-standard; multi-CLI, no server, no lock-in) |
+
+The SessionStart bootstrap hook probes for all peers and **warns** (non-blocking)
+when one isn't resolvable — informational for the opt-in layers, a real flag for
+the gate's two.
+
+## The stance: gate required, layers optional, runtime resilient
+
+- **The gate is the floor.** vault + loom are required because the toolkit's
+  central promise — re-derived, fail-closed "done" — is meaningless without them.
+  This is the one place we trade adoption for honesty on purpose.
+- **The layers are a toolkit, not a checklist.** Testing/brain/bus each add a
+  capability; none is a prerequisite for the others. Install the toolkit and reach
+  for the layers you need. Breadth is the point of a toolkit — but breadth you can
+  *adopt incrementally*, not a five-thing prerequisite wall.
+- **Resilient at runtime.** Even the required gate degrades cleanly: a transient
+  outage never crashes a session, and the kill-switches (`WICKED_VAULT_BIN=""`,
+  `WICKED_LOOM_CUTOVER=off`) disable cleanly and **fail closed** — they never let a
+  gate treat missing evidence as a pass. `WICKED_LOOM_CUTOVER=off` is an emergency
+  disable (e.g. a wedged `npx`): gating pauses and fails closed until loom is
+  restored, rather than thrashing.
+
+The line is simple: **fake-able honesty is worse than no honesty**, so the gate is
+required. Everything else earns its place by being useful when you reach for it —
+which is exactly what makes it a toolkit and not a monolith.

package/docs/specs/2026-06-08-wicked-loom-extraction.md

@@ -0,0 +1,225 @@
+# North-Star Spec — `wicked-loom`: extracting the orchestration runtime
+
+- **Date:** 2026-06-08
+- **Status:** Design (approved shape; pending written-spec review → implementation plan)
+- **Author:** brainstormed with Mike Parcewski
+- **Topic:** Reshape wicked-garden from a heavy library into a thin orchestrator by extracting its runtime/wiring into a new standalone peer, `wicked-loom`.
+- **Related:** ETHOS.md, docs/required-peers.md, issues #887 #843 #878 #842
+
+---
+
+## 1. Context & motivation
+
+`wicked-garden` is published at **v12.2.0** on a marketplace with real users. It has grown heavy: **~127k lines** across **71 skills · 93 commands · 55 agents · 131 Python scripts**. A large share of that weight is not domain expertise or archetype intelligence — it is *runtime plumbing*: peer detection/install/resolution, bus wiring, gate execution, and phase-loop mechanics. That plumbing was even formalized once as a `daemon/` (typed bus subscribers + projector + council, #592/#624) and then **deliberately deleted in v11** (commit `d205fc3`, "daemon cleanup") for being too heavy in-tree. The plumbing keeps wanting to exist, and keeps not belonging in garden.
+
+Meanwhile the `wicked-*` ecosystem already decomposes cleanly by concern, each concern a standalone primitive:
+
+| Primitive | Concern |
+|---|---|
+| `wicked-bus` | messaging substrate (how components talk) |
+| `wicked-brain` | memory / knowledge |
+| `wicked-vault` | evidence / verification (re-derive, never trust a claim) |
+| `wicked-testing` | QE execution (plan → run → judge) |
+| `wicked-understanding` | per-repo knowledge + **verifier spec** |
+
+`wicked-garden` uniquely owns three things none of the primitives provide: the **archetype engine** (classify work-shape, steer phases), the **domain catalog** (skills + agents), and the **compiler** (stamp a self-contained gate into any repo). Everything else garden does today is runtime that *should be a primitive too* — and isn't. That missing primitive is `wicked-loom`.
+
+**Thesis:** garden should *drive* a runtime, not *be* one. Extract the runtime into `wicked-loom`; garden becomes "archetype engine + domain catalog + compiler, running on loom."
+
+---
+
+## 2. Decisions (locked)
+
+These were settled during brainstorming and are the spine of this spec.
+
+| # | Decision | Rationale |
+|---|---|---|
+| D1 | **North star = Level 1.** Garden keeps the archetype engine, domain catalog, and compiler. Extract concerns *gate/phase + autonomy substrate* and *peer-wiring/adapters* into one standalone. | L1 is destination *and* first increment — biggest clarity win, smallest blast radius, and it names the missing component precisely. L2 (unbundle the domain catalog) and L3 (gut the archetype engine) are explicitly **out of scope** — L3 would erase garden's identity. |
+| D2 | **One new primitive, not two.** `wicked-loom`, containing a `compose` module and a `conduct` module. | Honors the "a missing component" (singular) framing and YAGNI — do not spec a separate `compose` primitive until a *second* consumer needs it. |
+| D3 | **Hybrid autonomy, synchronous-core-first.** The in-session synchronous runtime is the L1 deliverable. Headless/daemon is **spec'd now, built later**, with the park-at-hard-gate contract baked into the interface from day one. | The deleted daemon shows headless was too heavy as a default; garden's HITL discipline (hard gates require a human) collides with unattended autonomy unless bounded. Baking the contract in now prevents a later repaint. |
+| D4 | **Hybrid wiring.** Bus-as-spine for coordination/audit/knowledge/parks (async); direct synchronous resolution for re-derivation gates. **An event never satisfies a gate.** | Vault re-derivation must be blocking + in-line — a gate cannot return "pass" off a stale event. The bus carries everything that *isn't* a gate verdict. |
+| D5 | **Language-neutral standalone, Python impl, CLI + (deferred) daemon surface, consumed by garden via subprocess.** | Reuses nearly all existing Python code (daemon, `qe/`, resolvers) while making loom a true sibling primitive any stack can shell to — identical to how garden already consumes `npx wicked-vault`. Keeps garden's plugin packaging decoupled from loom's Python env. |
+| D6 | **Name: `wicked-loom`.** | A loom is the frame that wires threads together into cloth — the literal metaphor for "only wiring them together." |
+
+---
+
+## 3. Target architecture
+
+```
+                       ┌───────────────────────────────────────────┐
+ prompt ─────────────► │            wicked-garden (plugin)          │
+                       │  • archetype engine (classify + steer)     │   KEEPS
+                       │  • domain catalog (71 skills / 55 agents)  │
+                       │  • compiler (emit stamped gate into repos) │
+                       │  compiles archetype → FLOW DEFINITION;     │
+                       │  shells to loom for compose / gate / flow  │
+                       └───────────────┬───────────────────────────┘
+                          subprocess (CLI, sync)  +  bus events (async)
+                                       ▼
+                       ┌───────────────────────────────────────────┐
+                       │        wicked-loom  (NEW standalone)       │   TAKES
+                       │  COMPOSE: declare → install → version →    │
+                       │           resolve (the WICKED_*_BIN ladder)│
+                       │  CONDUCT: run any FLOW DEFINITION —        │
+                       │           phase-loop · gate exec · park-   │
+                       │           at-hard-gate · bus-consumer+proj │
+                       └──┬──────────┬──────────┬──────────┬─────────┘
+            direct/sync ──┘          │          │          └── bus/async
+                       ▼             ▼          ▼             ▼
+                  wicked-vault  wicked-testing  wicked-brain  wicked-bus
+                  (re-derive)   (QE exec)       (knowledge)   (spine)
+                              (+ wicked-understanding — verifier spec, optional/fail-soft)
+```
+
+### 3.1 The load-bearing abstraction: loom is archetype-agnostic
+
+Garden does **not** hand loom an archetype name. Garden's archetype engine compiles a catalog entry into a generic, declarative **flow definition**:
+
+```jsonc
+// flow definition — garden produces it, loom executes it
+{
+  "flow_id": "…",
+  "phases": [
+    { "name": "plan",      "gate": null,                       "produces": [...] },
+    { "name": "implement", "gate": null,                       "produces": [...] },
+    { "name": "test",      "gate": "produces:test-report",     "hitl": "discrete:review" },
+    { "name": "review",    "gate": "produces:verdict",         "hitl": "hard:final-verdict" }
+  ],
+  "peers_required": ["vault", "testing"],
+  "verifier_spec_ref": "…optional wicked-understanding verify.json…"
+}
+```
+
+Loom knows nothing about "build" vs "migrate" vs "incident." It runs *any* flow definition: advance phase → if the phase has a gate, execute it (sync vault re-derive) → if the gate is `hard:*`, park and emit `needs-human` → else continue. This is the seam that makes loom a genuine reusable primitive (any agent system can author flow definitions) rather than "garden's engine in a sidecar repo." Garden remains the archetype-to-flow compiler; loom is the generic flow runtime.
+
+### 3.2 Responsibility split
+
+| Concern | Owner | Notes |
+|---|---|---|
+| Archetype catalog, detector, steering hook, playbooks | **garden** | `archetypes_v11.py`, `prompt_submit.py`, `commands/archetype/`, `skills/archetype/refs/`, `archetypes.json` |
+| Domain catalog (skills/agents) | **garden** | unchanged |
+| Compiler (stamped-gate emitter) | **garden** | stays; see §7 synergy |
+| Archetype → flow-definition compilation | **garden** | new thin layer; the handoff contract to loom |
+| Peer install + version-check + resolution (compose) | **loom** | cross-cutting; not archetype-specific |
+| Gate execution (vault re-derive) | **loom** | the honest-evidence engine |
+| Flow/phase mechanics + state + park-at-gate | **loom** | generic flow runtime |
+| Bus consumer + projector (headless) | **loom** | resurrected daemon, deferred-on by default |
+
+---
+
+## 4. `wicked-loom` component spec
+
+One standalone, two modules, three surfaces.
+
+### 4.1 COMPOSE module
+Owns the peer lifecycle. Salvaged from garden's `bootstrap.py` (peer portion), `_integration_resolver.py`, `_capability_resolver.py`, `_capability_registry.py`, and `required-peers` logic.
+
+- **Declare** — a peer manifest (peer name, npm package, pinned `^x.y`, resolution env var, optional/required).
+- **Install** — orchestrate installs across mechanisms. **All four current peers are on npm**, so install runs headless via `npm`/`npx` (`npx wicked-testing install`, `npx wicked-vault-install`, `npm i wicked-brain@0.14`, `npm i wicked-bus@2`). The Claude Code `/plugin install` path is UX sugar, *not* the only route — loom never depends on a live CC session to install.
+- **Version-check** — verify resolved versions satisfy the pins; report drift.
+- **Resolve** — own the runtime resolution ladder (`WICKED_<PEER>_BIN` → config → `PATH` → `node_modules/.bin` → `npx`), including the `WICKED_VAULT_BIN=""` kill-switch.
+
+### 4.2 CONDUCT module
+Runs flow definitions. Salvaged from `qe/vault_gate.py`, `crew/phase_manager.py`, and the deleted `daemon/`.
+
+- **Run a flow** — advance through declared phases; persist phase state.
+- **Execute a gate** — *synchronous, in-line* vault re-derivation: re-hash recorded evidence + re-run the verifier via `cross-check`. Missing vault → `gate: "unavailable"`, **fail-closed**, never a vacuous pass. Hard gates additionally require an independent attestation (`--with-attestations`). If a `verifier_spec_ref` is present, read it to know *what* to re-derive; if absent/stale, fall back to generic detection (fail-soft on the *spec*, never on the *gate*).
+- **Park at hard gate** — on `hard:mitigate / cutover / final-verdict`, stop the flow and emit `loom:flow:needs-human`; do not self-approve. (Contract present from day one even though headless execution is deferred.)
+- **Project** — materialize flow/phase/evidence state from bus events to disk (headless, deferred).
+
+### 4.3 Surfaces
+1. **CLI** (the L1 deliverable; garden shells to it):
+   - `loom compose install [--peer X] [--check]` · `loom resolve <peer>` · `loom doctor`
+   - `loom gate <produces> [--verifier-spec path] [--with-attestations]`
+   - `loom flow run <flow-def.json>` · `loom flow status <flow-id>` · `loom flow resume <flow-id>`
+2. **Bus-consumer / daemon** (deferred per D3): headless mode that reacts to bus events, runs soft-gated flows unattended, parks at hard gates.
+3. **Event contract** (stable, on `wicked-bus`): `loom:flow:started|phase-advanced|gate-passed|gate-failed|needs-human|completed`, `loom:compose:installed|drift-detected`.
+
+---
+
+## 5. Wiring contract & invariants
+
+- **I1 — Gates are synchronous and direct.** `loom gate` re-derives every call. **An event never satisfies a gate.**
+- **I2 — Fail-closed.** Missing vault → `unavailable`, never pass. A claimed-but-false "tests pass" is rejected.
+- **I3 — Fail-soft on the verifier spec only.** Absent/stale `wicked-understanding` verifier spec → generic detection, never a blocked or vacuous gate.
+- **I4 — Bus is the spine for everything that is not a gate verdict:** phase transitions, evidence-recorded notices, brain knowledge writes, audit, and `needs-human` parks.
+- **I5 — Autonomy never overrides a hard gate.** Headless flows park + emit at `hard:*`.
+- **I6 — Loom is archetype-agnostic.** It executes flow definitions; it does not know archetype names.
+
+---
+
+## 6. Extraction inventory (file-level, grounded)
+
+`→ loom` = moves; `STAY` = remains in garden; `PARTIAL` = split.
+
+> **OUTCOME (shipped 2026-06-08 — supersedes the forward-looking `→ loom` dispositions below).** What *actually* moved to loom: **resolve** (peer resolution) and **gate** (`vault_gate.cross_check`) — both fully cut over **and contracted** (in-process deleted; loom is the sole path, fail-closed). **flow** landed as a loom-*authoritative* hard-gate park decision with an in-process fail-closed floor — the `phase_manager` state machine was **not** moved (incompatible execution models: garden advances one phase agent-in-loop; loom runs a whole flow-def). Everything else listed `→ loom` below **STAYS in garden permanently** — re-decided, *not* future loom work: `_integration_resolver` / `_capability_resolver` / `_capability_registry` (agent/domain MCP-tool discovery — a different concern from wicked-peer orchestration), `bootstrap` (session assembly; loom peer-detection already shimmed), `_bus`/`_event_*` (not migrated), `phase_manager` storage (rejected). The loom migration is **complete**; nothing further is owed. Shipped: garden **v12.3.0** (resolve/gate) + **v12.4.0** (flow); loom **v0.2.x**.
+
+| File | Lines | Disposition |
+|---|---:|---|
+| `hooks/scripts/bootstrap.py` | 1711 | **PARTIAL** — peer detect/install/resolve → loom compose; session-bootstrap (state init, archetype priming, brain orientation) STAYS |
+| `scripts/_integration_resolver.py` | 321 | → loom (compose) |
+| `scripts/_capability_resolver.py` | 322 | → loom (compose) |
+| `scripts/_capability_registry.py` | 226 | → loom (compose) |
+| `scripts/qe/vault_gate.py` | 348 | → loom (conduct/gate) |
+| `scripts/crew/phase_manager.py` | 614 | → loom (conduct/state) |
+| `scripts/_bus.py` | 973 | **PARTIAL** — consumer/projector role → loom; thin fire-and-forget emit (`_bus_emit.py`, 43) STAYS so any garden component can emit |
+| `scripts/_event_store.py` / `_event_log_reader.py` / `_event_schema.py` | 397 / 154 / 305 | → loom (conduct/projector) — confirm during expand phase |
+| `scripts/_wicked_testing_probe.py` / `_wicked_testing_tier1.py` | 277 / 88 | → loom (compose/resolution) |
+| `scripts/_brain_port.py` | 65 | → loom (compose/resolution) |
+| `scripts/crew/archetypes_v11.py` | 348 | **STAY** — archetype engine (garden identity) |
+| `hooks/scripts/prompt_submit.py` | 1126 | **STAY** — classification entry (archetype engine) |
+| `scripts/crew/scope_delta.py` | 264 | **STAY** — HITL scope heuristic feeds flow-definition compilation |
+| `scripts/compiler/**` | 2312 | **STAY** — see §7 synergy |
+
+Exact partial boundaries (esp. `bootstrap.py`, `_bus.py`, the `_event_*` trio) are confirmed empirically during the **expand** phase, not asserted here.
+
+---
+
+## 7. Migration plan — strangler (expand → cutover → contract)
+
+Garden is published with users; this is a migration, not a rewrite. Each step is independently verifiable via vault.
+
+1. **Expand.** Stand up the `wicked-loom` repo. *Copy* (don't move) compose + conduct code; ship the CLI; publish to npm with a `^0.1` pin. Garden is byte-for-byte unchanged and keeps working. Loom is usable standalone by other consumers immediately.
+2. **Cutover (strangler).** Garden's `scripts/` shims start shelling to `loom` instead of running in-process, **one surface at a time**: `resolve` → `gate` → `flow`. Each cutover ships behind the existing fail-soft posture (if loom unresolvable, the old in-process path or graceful degradation still applies during transition). Add `wicked-loom` as a **5th peer** in `docs/required-peers.md` (required at install, resilient at runtime — same stance as the other four). Introduce the archetype → flow-definition compiler in garden.
+3. **Contract.** Delete the now-dead in-garden runtime code (the `→ loom` rows above). Re-measure garden's footprint; slim whatever genuinely remains (this absorbs #843).
+
+**Backward compat:** during expand+cutover, no user-visible behavior change. The contract phase is a major version bump for garden (v13) with a migration note: "wicked-loom is now a required peer; `/wicked-garden:setup` installs it."
+
+---
+
+## 8. The four open issues, re-triaged against the north star
+
+| Issue | Disposition |
+|---|---|
+| **#887** consume wicked-understanding | **Absorbed into loom.** Understanding's `verify.json` is the `verifier_spec_ref` that `loom gate` reads to know *what* to re-derive. Optional/fail-soft peer (I3), exactly as the author proposed. Resolve by speccing it into loom, not as a standalone garden change. Open sub-item: confirm the `verify.json` schema loom's gate consumes (tracked in §9). |
+| **#843** slim `commands/*` | **Largely dissolved** by the contract phase — much weight is runtime plumbing that leaves. Re-measure after contract; slim the genuine remainder. |
+| **#878** cwd-leak PreToolUse hook | **Tactical, do now.** Independent of the rethink — worktree-safety bug. Not blocked by loom. |
+| **#842** SessionEnd dogfood (v9.2.15) | **Stale** (we're at v12.2). Verify-or-close; do not carry v9 dogfooding forward. |
+
+---
+
+## 9. Open questions / deferred
+
+- **D-headless:** the daemon/bus-consumer execution mode is spec'd (§4.2/§4.3) but **not built** in L1. The contract (park-at-hard-gate, event names) is fixed now to avoid a repaint.
+- **Compiler↔loom synergy:** `loom gate` and the compiler's stamped gate are the same logic at different lifetimes (live runtime vs. stamped file). L1 leaves the compiler as-is (self-contained, resolves vault directly via npx). A later increment *may* have the compiler emit a thin shim over loom — flagged, not scoped.
+- **compose-as-its-own-primitive:** deferred per D2 (YAGNI). Revisit only if a non-garden consumer needs the composer.
+- **`verify.json` schema:** the structured sidecar wicked-understanding would emit (issue #887, rec #2) needs its shape confirmed against what `loom gate` consumes. Coordinate cross-repo before building.
+- **CLI verb naming:** `compose`/`gate`/`flow` are provisional.
+
+---
+
+## 10. Error handling & testing posture
+
+- **Error handling:** all peer interaction is fail-soft *except gates* (fail-closed, I2). Loom unresolvable → garden degrades gracefully during transition; a gate with no vault returns `unavailable`. The `WICKED_VAULT_BIN=""` kill-switch and the loom resolution ladder are preserved verbatim.
+- **Testing:** loom ships with its own suite (compose resolution ladder, gate fail-closed behavior, flow phase advance + park-at-hard-gate). Garden adds **contract tests** asserting each cutover shim produces identical results to the in-process path it replaces (the strangler's safety net). The emitted-compiler-gate AST test (stdlib-only, imports nothing from the garden) is unaffected.
+
+---
+
+## 11. Success criteria for L1
+
+1. `wicked-loom` exists as a standalone npm-published primitive with a working CLI, usable by a non-garden consumer.
+2. Garden shells to loom for `resolve`, `gate`, and `flow`; the in-process runtime code is deleted.
+3. No regression: every archetype's gate behavior is identical pre/post cutover (proven by contract tests + vault re-derivation, not asserted).
+4. Garden's footprint drops measurably (target: the `→ loom` rows above leave; #843 re-measured).
+5. The honest-evidence invariants (§5) hold unchanged — done is still re-derived, never claimed.
+6. Loom is archetype-agnostic: it runs a hand-authored flow definition with zero garden knowledge.

package/docs/specs/2026-06-10-codegraph-to-brain-migration.md

@@ -0,0 +1,168 @@
+# North-Star Spec — move the code-relationship graph from `wicked-garden` into `wicked-brain`
+
+- **Date:** 2026-06-10
+- **Status:** Design (approved shape; pending written-spec review → implementation plan)
+- **Author:** brainstormed with Mike Parcewski
+- **Topic:** Relocate the codegraph-backed relationship graph (engine integration, injected-edge extractors, and the blast-radius / lineage / architecture query surface) out of `wicked-garden` and into `wicked-brain`, so any project — not just ones running garden — gets enhanced code/graph knowledge.
+- **Related:** docs/adr/0001-code-relationship-graph-engine.md (**this spec amends/inverts it**), docs/required-peers.md, `scripts/_codegraph.py`, `scripts/codegraph/`, the `wicked-brain-lsp` skill.
+
+---
+
+## 1. Context & motivation
+
+There are currently **two half-built code-intelligence stacks** answering overlapping questions in different places:
+
+- **garden's codegraph stack** — `scripts/_codegraph.py` (peer shim) + `scripts/codegraph/inject_*.py` (injected-edge extractors), feeding `search:blast-radius` / `search:lineage` and (eventually) wicked-patch's `--db`. Introduced by ADR 0001 (dated 2026-06-09).
+- **brain's LSP stack** — the `wicked-brain-lsp` skill already advertises "blast radius" and "architecture map" via language servers.
+
+Two blast-radius implementations, two homes, one concept. The smell is structural: **"what breaks if I change X" / "what flows where" / "what's connected to this" are knowledge questions about relationships** — and brain *is* the knowledge layer. Code-relationship comprehension is a thinking pattern, and thinking patterns belong in brain.
+
+ADR 0001 noticed `search:blast-radius` was "wrongly" calling the brain and concluded *pull the graph into garden*. **That was the wrong direction.** The original instinct (blast-radius = brain) was right; the fix is to move the *graph* to brain, not move the *query* to garden. The decisive secondary requirement: the graph is **valuable to everyone**, and requiring all of wicked-garden just to give a repo enhanced code/graph knowledge is unacceptable. The graph must be a standalone brain capability with **zero garden dependency**.
+
+**Thesis:** brain *knows* (the relationship graph + every query over it). Garden *does* (deterministic refactor, gates, archetypes) and is merely a *consumer* of the graph.
+
+---
+
+## 2. Decisions (locked)
+
+Settled during brainstorming; the spine of this spec.
+
+| # | Decision | Rationale |
+|---|---|---|
+| D1 | **Ownership: brain owns the graph + all relationship queries; garden consumes.** The *knowing*-vs-*doing* line: brain knows (blast-radius, lineage, impact, callers, architecture); garden does (wicked-patch refactor, gates, archetypes). | Blast-radius is knowledge; knowledge lives in brain. Unifies the two stacks under one owner. **Amends ADR 0001.** |
+| D2 | **Dependency arrow points garden→brain only, never back.** Brain is fully valuable standalone for code/graph knowledge. | "Don't require all of garden just for brain to have graph knowledge." The graph is universally valuable. |
+| D3 | **Proprietary edges via a pluggable extractor-drop registry (option i).** Brain defines an extractor interface + a discovery dir, *ships* the generic/ecosystem extractors itself, and discovers + runs plugin-dropped extractors if present (ignores if absent). | Most "injected" edges are ecosystem/platform conventions (bus wiring, plugin frontmatter, hooks), not garden internals — brain should know them natively. The genuinely garden-proprietary ones (archetypes) drop in without a reverse dependency. Generalizes to any wicked-* plugin. |
+| D4 | **codegraph = graph of record; LSP = live precision (option A).** codegraph owns the persistent relationship graph, injected edges, and blast-radius / lineage / architecture. LSP keeps def/ref/hover/diagnostics and **stops being a second blast-radius**. No fusion layer. | LSP cannot represent injected edges (it only knows language semantics) and has no persistent whole-repo graph; codegraph is the only layer that can. Two clean lanes, each doing what it's best at. YAGNI on a merge/facade. |
+| D5 | **Freshness: lazy staleness-stamp baseline + optional commit-hook accelerator (A + C). No watcher full-reindex.** | The 40%-CPU runaway diagnosed on 2026-06-10 *was* a reindex loop (watcher → polling → repeated re-index). Lazy + staleness-stamped is structurally incapable of that failure. Commit-hook is an opt-in accelerator (garden's compiler already installs git hooks — precedent). |
+| D6 | **DB stays codegraph-native: `<repo>/.codegraph/codegraph.db` (per-repo, gitignored).** Brain records a pointer + staleness, does not relocate it. | It is codegraph's stable, self-describing contract; consumers (wicked-patch `--db`) expect it; it travels with the repo. |
+
+---
+
+## 3. Target architecture
+
+```
+codegraph CLI (peer, resolved via env→config→PATH→node_modules→npx)
+        │ index
+        ▼
+ <repo>/.codegraph/codegraph.db   ── per-repo, gitignored, codegraph-native ──┐
+        ▲                                                                      │
+        │ inject                                                               │ read
+  ┌─────┴──────────────────────────────────────────────┐                      │
+  │ brain BUILT-IN extractors (ship with brain):        │                      │
+  │   • bus producer→consumer  (emit + _bus_consumers)   │                      │
+  │   • command→agent          (subagent_type:)          │                      │
+  │   • hook event→script      (hooks.json)              │                      │
+  │   • agent→tool             (capability registry)     │                      │
+  │ brain DISCOVERED extractors (drop-in, optional):     │                      │
+  │   • garden: archetype→playbook/gate (archetypes.json)│                      │
+  └──────────────────────────────────────────────────────┘                     │
+                                                                                │
+ LSP servers ──live──▶ def/ref/hover/diagnostics      ◀── SEPARATE LANE         │
+                                                          (not blast-radius)     │
+                                                                                 │
+ brain GRAPH QUERIES  ◀───────────────────────────────────────────────────────┘
+   blast-radius · lineage · impact · callers · architecture
+   every answer carries a staleness stamp (N commits behind HEAD, indexed-at)
+
+ CONSUMERS:
+   • brain skill  `wicked-brain-graph`  (new) — the query surface
+   • garden wicked-patch (rename/add-field/remove) — consumes .codegraph.db as --db
+   • any other plugin
+```
+
+### 3.1 Component responsibilities
+
+| Component | Home | Does | Depends on |
+|---|---|---|---|
+| codegraph engine | external peer (`@colbymchenry/codegraph`, MIT) | static multi-language graph, column-precise, SQLite | Node ≥ 22.5 |
+| engine integration (resolve + run + staleness) | **brain** | resolution ladder, `index`, `impact`/`callers`, staleness stamp | codegraph peer |
+| extractor framework + interface + discovery | **brain** | define interface, discover + run extractors | — |
+| built-in extractors (bus / command→agent / hooks / capability) | **brain** | materialize ecosystem-convention edges | brain graph |
+| `wicked-brain-graph` skill | **brain** | blast-radius / lineage / impact / callers / architecture | brain graph |
+| LSP intelligence (`wicked-brain-lsp`) | **brain** | live def/ref/hover/diagnostics (blast-radius role removed) | language servers |
+| archetype extractor (drop-in) | **garden** | materialize archetype→gate edges into brain's graph | brain extractor interface |
+| wicked-patch (rename/add-field/remove) | **garden** | deterministic refactor; consumes `.codegraph.db` as `--db` | brain graph DB shape |
+
+---
+
+## 4. What moves / what stays
+
+| Today (garden) | Disposition | Note |
+|---|---|---|
+| `scripts/_codegraph.py` (engine shim, staleness) | **→ brain** | **Cross-language re-home, not a file copy** — brain's server is Node; this is Python. Re-implemented in brain's runtime. The resolution-ladder + staleness *semantics* port verbatim. |
+| `scripts/codegraph/inject_edges.py` (bus) | **→ brain built-in extractor** | reads `_bus_consumers.json` + emit sites — a wicked-bus convention, not a garden internal |
+| `scripts/codegraph/inject_dispatch_edges.py` (command→agent) | **→ brain built-in extractor** | `subagent_type:` is a Claude-Code plugin convention |
+| `scripts/codegraph/inject_capability_edges.py` (agent→tool) | **→ brain built-in extractor** | capability registry — ecosystem-wide |
+| `scripts/codegraph/_graph_nodes.py`, `inject_all.py` | **→ brain** | shared helpers + the orchestration entry |
+| archetype→gate extractor (proprietary; future) | **garden ships as drop-in** | discovered by brain at runtime; brain works without it |
+| `scripts/engineering/patch/{codegraph_db,patch}.py` | **stays garden** | repoint `--db` to `<repo>/.codegraph/codegraph.db`; a *doing* action |
+| `commands/search/{blast-radius,lineage,hotspots,index}.md` | **thin aliases → brain skills, or removed** | the query surface is brain's now |
+| `tests/codegraph/test_codegraph.py` | **engine/extractor tests → brain; garden keeps drop-in + patch-consumer tests** | |
+
+---
+
+## 5. Freshness & failure modes
+
+### 5.1 Freshness (D5)
+- **Baseline (lazy + staleness-stamped):** brain stamps how far `.codegraph.db` is behind HEAD (commits-behind + indexed-at — the `staleness()` logic already in `_codegraph.py`). Reindex runs **on explicit demand** or **when a query finds the graph stale past a threshold**. Zero idle CPU.
+- **Accelerator (opt-in, commit-driven):** a git `post-commit` / `pre-push` hook triggers reindex so the graph is commit-fresh. Off by default.
+- **Explicitly NOT** watcher-driven full reindex — that is the failure class diagnosed on 2026-06-10.
+
+### 5.2 Failure modes (fail-closed, never vacuous)
+| Condition | Behavior |
+|---|---|
+| codegraph unresolvable (no peer) | query returns `engine: "unavailable"` — **not** an empty/zero-edge graph that looks like a real answer |
+| graph stale | answer is returned **with** a `stale: true, commits_behind: N` flag; caller decides |
+| drop-in extractor absent | skipped silently — the standalone guarantee (D2) |
+| shim subprocess error/timeout | surfaced as data (`{error: ...}`), never raises (R4) |
+
+---
+
+## 6. Testing & the standalone guarantee
+
+- Engine resolver: resolution ladder (env → config → PATH → node_modules → npx) + the set-but-empty kill-switch.
+- Staleness math: present/absent DB, commits-behind computation, fail-open on git errors.
+- Each built-in extractor: deterministic edge materialization against a fixture repo (producer→consumer, command→agent, hooks, capability).
+- Extractor-drop discovery: present (runs) vs absent (skipped, graph still valid).
+- Query correctness: blast-radius / lineage over a known fixture graph with injected edges grep cannot see.
+- **Standalone guarantee (the load-bearing test):** brain's graph module imports **nothing** from garden — enforced in CI (the inverse of the compiler's existing "emitted gate imports nothing from the garden" AST test). This is what keeps D2's one-way arrow from silently regressing.
+
+---
+
+## 7. Implementation decomposition
+
+Two phases, sequenced — garden phase depends on brain having shipped the graph.
+
+### Phase 1 — `wicked-brain`
+1. Engine integration (resolve + `index` + `impact`/`callers` + staleness), Node-native.
+2. Extractor framework: interface + discovery dir + registry.
+3. Built-in extractors: bus, command→agent, hooks, capability.
+4. Graph query surface + new `wicked-brain-graph` skill (blast-radius / lineage / impact / callers / architecture).
+5. Remove blast-radius/architecture from `wicked-brain-lsp`'s advertised surface (keep live ops).
+6. Freshness: staleness stamp + opt-in commit hook.
+7. Standalone CI test (zero garden imports).
+
+### Phase 2 — `wicked-garden`
+1. Repoint wicked-patch (`codegraph_db.py` / `patch.py`) to brain's `.codegraph.db`.
+2. Ship the archetype extractor as a brain drop-in.
+3. Convert `search:{blast-radius,lineage,hotspots,index}` commands to thin aliases over brain skills, or remove.
+4. Delete the migrated `scripts/_codegraph.py` + `scripts/codegraph/*` from garden.
+5. **Amend ADR 0001** (record the inversion: graph → brain, not garden) — likely a new ADR 0004 superseding the relevant section.
+6. Update CLAUDE.md (storage/search sections) to point at brain for graph queries.
+
+---
+
+## 8. Out of scope (YAGNI)
+
+- A unified LSP+codegraph graph or a query facade over both (D4 rejected B and C).
+- Watcher-driven incremental reindex (D5 rejected B).
+- Relocating the graph DB under brain's project dir (D6 — keep codegraph-native).
+- Any general data-flow lineage layer beyond what codegraph + injected edges provide (deferred; was ADR 0001 roadmap step 5).
+
+---
+
+## 9. Related operational findings (non-blocking)
+
+Surfaced while diagnosing why brain appeared "down" on 2026-06-10 (separate from this migration, tracked separately):
+- **wicked-brain bug:** file-watcher polling fallback (after EMFILE) re-indexes unchanged files in a hot loop → ~40% CPU runaway. This spec's D5 ensures the *codegraph* reindex path cannot reproduce that class of bug, but the watcher bug itself is a brain-repo fix.
+- **wicked-garden bug:** the brain reachability probe (`_brain_api` / `_check_search_staleness`, 2s timeout) collapses slow/down/errored/non-JSON into one "not reachable — start wicked-brain" message, mis-reporting an up-but-slow server. Dogfooding issue to be filed.