wicked-garden 12.28.1 → 12.29.1

package/.claude-plugin/components.json

@@ -2,8 +2,8 @@
   "_comment": "Issue #328: Component declarations for wicked-garden plugin. Claude Code plugin.json does not yet support inline component declarations beyond path overrides. This manifest documents all components for tooling, validation, and future schema support. When plugin.json gains a 'components' field, merge this data into plugin.json. The plugin is skills-only: former commands/ became actions of consolidated per-domain skills, and former agents/ became standalone context:fork worker skills (enumerated under fork_skills). Regenerate derived blocks with scripts/ci/sync_components.py.",
   "domains": ["agentic", "crew", "data", "engineering", "jam", "mem", "persona", "platform", "product", "qe", "search", "smaht"],
   "summary": {
-    "skills": 94,
-    "fork_skills": 34,
+    "skills": 99,
+    "fork_skills": 38,
     "hooks": 13,
     "specialists": 7
   },
@@ -21,8 +21,13 @@
     "data": ["data"],
     "data-engineer": ["data-engineer"],
     "deliberate": ["deliberate"],
+    "domain": ["domain"],
+    "domain-coverage": ["domain-coverage"],
+    "domain-extractor": ["domain-extractor"],
+    "domain-modeler": ["domain-modeler"],
     "engineering": ["architecture", "backend", "debugging", "docs", "engineering", "frontend", "integration", "large-scale-migration", "patch", "system-design", "unit-test-quality"],
     "engineering-api-documentarian": ["engineering-api-documentarian"],
+    "engineering-conformance-reviewer": ["engineering-conformance-reviewer"],
     "engineering-migration-engineer": ["engineering-migration-engineer"],
     "engineering-solution-architect": ["engineering-solution-architect"],
     "ground": ["ground"],
@@ -53,7 +58,7 @@
     "workflow": ["workflow"],
     "worktrees": ["worktrees"]
   },
-  "fork_skills": ["wicked-garden-agentic-architect", "wicked-garden-agentic-performance-analyst", "wicked-garden-agentic-safety-reviewer", "wicked-garden-archetype", "wicked-garden-classify", "wicked-garden-crew-implementer", "wicked-garden-crew-researcher", "wicked-garden-crew-reviewer", "wicked-garden-data-engineer", "wicked-garden-engineering-api-documentarian", "wicked-garden-engineering-debugging", "wicked-garden-engineering-migration-engineer", "wicked-garden-engineering-solution-architect", "wicked-garden-ground", "wicked-garden-integration-discovery", "wicked-garden-jam-brainstorm-facilitator", "wicked-garden-jam-council", "wicked-garden-multi-model", "wicked-garden-persona-agent", "wicked-garden-platform-compliance-officer", "wicked-garden-platform-privacy-expert", "wicked-garden-platform-security-engineer", "wicked-garden-product-a11y-expert", "wicked-garden-product-requirements-analyst", "wicked-garden-product-ui-reviewer", "wicked-garden-product-ux-designer", "wicked-garden-product-value-strategist", "wicked-garden-qe-semantic-reviewer", "wicked-garden-runtime-exec", "wicked-garden-smaht", "wicked-garden-swarm", "wicked-garden-wickedizer", "wicked-garden-workflow", "wicked-garden-worktrees"],
+  "fork_skills": ["wicked-garden-agentic-architect", "wicked-garden-agentic-performance-analyst", "wicked-garden-agentic-safety-reviewer", "wicked-garden-archetype", "wicked-garden-classify", "wicked-garden-crew-implementer", "wicked-garden-crew-researcher", "wicked-garden-crew-reviewer", "wicked-garden-data-engineer", "wicked-garden-domain-coverage", "wicked-garden-domain-extractor", "wicked-garden-domain-modeler", "wicked-garden-engineering-api-documentarian", "wicked-garden-engineering-conformance-reviewer", "wicked-garden-engineering-debugging", "wicked-garden-engineering-migration-engineer", "wicked-garden-engineering-solution-architect", "wicked-garden-ground", "wicked-garden-integration-discovery", "wicked-garden-jam-brainstorm-facilitator", "wicked-garden-jam-council", "wicked-garden-multi-model", "wicked-garden-persona-agent", "wicked-garden-platform-compliance-officer", "wicked-garden-platform-privacy-expert", "wicked-garden-platform-security-engineer", "wicked-garden-product-a11y-expert", "wicked-garden-product-requirements-analyst", "wicked-garden-product-ui-reviewer", "wicked-garden-product-ux-designer", "wicked-garden-product-value-strategist", "wicked-garden-qe-semantic-reviewer", "wicked-garden-runtime-exec", "wicked-garden-smaht", "wicked-garden-swarm", "wicked-garden-wickedizer", "wicked-garden-workflow", "wicked-garden-worktrees"],
   "hooks": ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "TaskCompleted", "SubagentStart", "SubagentStop", "PermissionRequest", "Notification", "PreCompact", "Stop", "SessionEnd"],
   "specialists": [
     {

package/.claude-plugin/marketplace.json

@@ -8,8 +8,8 @@
       "name": "wicked-garden",
       "source": "./",
       "description": "Your coding agent already plans and swarms \u2014 Wicked Garden is the curated toolkit for what it can't: proof-not-claims gates, code links grep can't see, deterministic refactor, cross-session memory, real multi-model second opinions. Don't fight the harness; fill its gaps. The gate needs wicked-vault (auto-installed via wicked-testing) and re-derives through garden's built-in engine; testing/brain/bus are opt-in layers.",
-      "version": "12.28.1"
+      "version": "12.29.1"
     }
   ],
-  "version": "12.28.1"
+  "version": "12.29.1"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-garden",
-  "version": "12.28.1",
+  "version": "12.29.1",
   "description": "Your coding agent's harness already plans and swarms; Wicked Garden is the curated toolkit for what it can't do alone. Proof, not claims \u2014 gates re-derive 'done' through the internal loom engine (fail-closed, independently attested via wicked-vault), so a self-asserted pass can't lie its way green. Relationships grep can't see \u2014 codegraph + injected bus/dispatch/capability edges power blast-radius & lineage. Plus deterministic multi-file refactor (wicked-patch), cross-session memory (wicked-brain), real multi-model second opinions (jam:council), portable expertise as on-demand skill-refs, and evidence-gated testing (wicked-testing). It reads the shape of your work to apply the right rigor \u2014 steering, not a pipeline \u2014 then gets out of the way. The compiler stamps a self-contained evidence gate into any repo that runs with no wicked-garden installed. Don't fight the harness; fill its gaps. The evidence gate requires wicked-vault (installed automatically via wicked-testing); wicked-testing, wicked-brain, and wicked-bus are opt-in layers \u2014 install what you'll use, the toolkit works without the rest.",
   "wicked_testing_version": "^0.8.0",
   "wicked_vault_version": "^0.4.0",

package/.product/DES-001-technical-design.md

@@ -0,0 +1,309 @@
+---
+name: DES-001-technical-design
+title: wicked-garden — Technical Design
+status: draft
+version: 0.1
+date: 2026-07-21
+author: mike.parcewski@gmail.com
+review-required: true
+---
+
+# DES-001 — Technical Design
+
+## Overview
+
+wicked-garden is delivered as a Claude Code plugin. Its runtime is the Claude Code harness; its surfaces are skills (Markdown files with YAML frontmatter loaded by the harness). Imperative logic — archetype detection, evidence gate, compiler, domain store, session state, event bus integration — lives in Python scripts under `scripts/` and `hooks/scripts/`. No server-side component is required for core function (the Flask daemon is opt-in).
+
+The plugin is **skills-only** as of v12.25. There are no slash commands in the distributed artifact. Three hook types fire at harness lifecycle events. A daemon provides optional long-running operation support.
+
+---
+
+## Plugin Architecture
+
+### Directory Structure
+
+```
+wicked-garden/
+├── .claude-plugin/
+│   ├── plugin.json              # version, peer ranges, metadata
+│   ├── marketplace.json         # listing metadata
+│   ├── archetypes.json          # v11 archetype catalog (source of truth)
+│   ├── components.json          # derived skill surface manifest (generated)
+│   └── specialist.json          # specialist resolver registry
+├── skills/
+│   ├── archetype/               # v11 entry point + 10 ref playbooks
+│   │   └── refs/{archetype}.md  # one playbook per work-shape
+│   ├── {domain}/                # domain router skills (user-invocable)
+│   │   ├── SKILL.md             # frontmatter + slim body
+│   │   └── refs/                # on-demand rubrics and content
+│   └── {domain}-{role}/         # fork worker skills (context:fork)
+│       └── SKILL.md
+├── hooks/
+│   ├── hooks.json               # hook registration
+│   └── scripts/                 # stdlib-only Python scripts
+│       ├── bootstrap.py         # SessionStart
+│       ├── prompt_submit.py     # UserPromptSubmit → archetype detection
+│       └── stop.py              # Stop → teardown
+├── scripts/
+│   ├── crew/
+│   │   ├── archetypes_v11.py    # detector + steering engine
+│   │   ├── phase_manager.py     # slim project state
+│   │   ├── scope_delta.py       # HITL scope-delta heuristic
+│   │   ├── specialist_resolver.py
+│   │   ├── _task_reader.py
+│   │   ├── _task_audit_writer.py
+│   │   └── detectors/           # per-archetype detection helpers
+│   ├── qe/
+│   │   ├── vault_gate.py        # ProducesGate: shells wicked-loom gate
+│   │   ├── prove.py             # evidence recording with actor logic
+│   │   └── evidence_tracker.py  # legacy claim-only tracker (fallback/bookkeeping)
+│   ├── compiler/
+│   │   ├── compile.py           # top-level compiler entry
+│   │   └── phase0/detect.py     # ecosystem/binding detection
+│   ├── _domain_store.py         # local JSON persistence with optional MCP routing
+│   ├── _session.py              # per-session shared state
+│   ├── _bus.py                  # wicked-bus event emission
+│   └── _paths.py                # project-scoped path resolution
+├── daemon/                      # optional Flask server
+└── tests/                       # unit tests (pytest)
+```
+
+### Skill Loading and Progressive Disclosure
+
+All skill SKILL.md files are loaded into the harness context on invocation. Frontmatter is always loaded. The body is loaded when the skill is invoked. Refs are loaded on demand via `Skill()` dispatch from the body.
+
+The slim body contract enforces three body patterns:
+- **Pattern A** (≤ 8 lines): state mutation, advisory output. No dispatch.
+- **Pattern B** (≤ 30 lines): write a session-specific brief, then dispatch to a ref or worker.
+- **Pattern C** (≤ 35 lines): interactive branch to get a user decision, then dispatch.
+
+Refs files are the heavy content layer (200-300 lines). Subagent contexts are short-lived and isolated; loading refs in them via `Skill()` is the intended pattern. Parent-context bloat is the problem being avoided.
+
+---
+
+## Archetype Detection Flow
+
+The archetype detection pipeline runs on every user prompt via the `UserPromptSubmit` hook.
+
+```
+User submits prompt
+  → Claude Code fires UserPromptSubmit event
+  → hooks/scripts/prompt_submit.py
+  → calls scripts/crew/archetypes_v11.py::detect_archetypes(prompt_text)
+  → detector scores prompt against all 10 archetype definitions
+      (each archetype definition is in archetypes.json; per-archetype
+       helpers in scripts/crew/detectors/ refine scores)
+  → returns sorted list of (archetype_name, score) pairs above threshold
+  → hook script emits system-reminder:
+      <wg archetype="migrate" score="0.91" />
+      (or multi-archetype: <wg archetype="build,migrate" score="0.85,0.72" />)
+  → hook returns {"continue": true}
+
+Harness injects system-reminder into context
+  → harness (or agent) invokes wicked-garden-archetype skill
+      with detected work-shape name
+  → skill body dispatches to skills/archetype/refs/{archetype}.md
+  → playbook defines phase shape, produces contract, HITL discipline
+  → agent executes phases; invokes domain skills for expertise
+```
+
+The detector is a scoring function, not a classifier — it returns a set with scores, not a single label. Multi-archetype is normal. The harness executes archetypes in dependency order declared by `next_archetypes` in `archetypes.json`.
+
+Archetype detection is **steering, not blocking**. The system-reminder is advisory; the harness decides whether to invoke the archetype skill. No gate blocks execution based on classification alone.
+
+---
+
+## Evidence Gate Mechanics
+
+The evidence gate is the v12 loom cutover architecture: loom is the sole gate/resolve engine. The in-process vault re-derivation path was removed at v12 loom cutover.
+
+```
+agent/skill calls gate_satisfied() in scripts/qe/vault_gate.py
+  → (require=True, the default: fail-closed stance)
+  → resolves wicked-loom binary:
+      WICKED_LOOM_BIN env → config → PATH → node_modules/.bin → npx
+  → if WICKED_LOOM_CUTOVER=off:
+      return {"gate": "unavailable", "reason": "loom cutover disabled"}
+  → shells: wicked-loom gate [--archetype X] [--with-attestations]
+  → wicked-loom shells: wicked-vault cross-check [--actor WICKED_VAULT_ACTOR]
+  → wicked-vault:
+      re-hashes evidence payload (content hash)
+      re-runs the evidence verifier
+      checks actor identity for attestation requests:
+        - explicit actor → acceptable
+        - env-user → rejected (vault >= 0.4.0 breaking change)
+  → wicked-loom returns structured gate result
+  → gate_satisfied() interprets:
+      green: verifier passed, hash matched, actor acceptable
+      fail-closed: any failure → {"gate": "unavailable"} or {"gate": "fail"}
+      never: vacuous pass when evidence is missing
+```
+
+**Actor identity for hard gates**: the `WICKED_VAULT_ACTOR` env var (default `garden-prove`) is the identity under which evidence is recorded and attested. `scripts/qe/prove.py::_prove_actor()` is the reference for resolving the actor at runtime. Hard-gate playbooks pass `--actor "${WICKED_VAULT_ACTOR:-garden-prove}"` explicitly.
+
+**Legacy path**: `evidence_tracker.py` (claim-only, no re-derivation) remains as a fallback and bookkeeping layer. `gate_satisfied(require=False)` opts back to the claim-only path. This path does not satisfy any hard gate.
+
+**Kill switches**:
+- `WICKED_LOOM_CUTOVER=off` — disables the gate. Gate returns `unavailable`.
+- `WICKED_VAULT_BIN=""` — kills the vault behind loom. Gate fails closed.
+
+---
+
+## Multi-Model Council Flow
+
+The council is a structured independent evaluation, not a simulation of multiple viewpoints by a single model.
+
+```
+Developer/skill invokes wicked-garden-jam council <target>
+  → wicked-garden-jam-council fork worker skill activated
+  → worker enumerates available external LLM CLIs
+      (Claude Code via Antigravity, Codex, local models — configured per session)
+  → for each available participant:
+      Task(subagent_type=..., prompt=council_prompt_for(participant, target))
+      → isolated context: no shared state with invoking session
+      → participant evaluates target and returns structured verdict
+          (findings, concerns, confidence)
+  → council skill collects all verdicts
+  → synthesizes: agreement points, disagreement points, unresolved tensions
+  → returns multi-perspective evaluation to invoking skill or developer
+
+Harness (or invoking archetype) decides how to weight verdicts:
+  → unanimous failure may be treated as a hard gate
+  → mixed results surface as findings for developer resolution
+```
+
+The council is the only mechanism in wicked-garden for genuine independent multi-model evaluation. The `quick` action in the jam skill is a single-model lightweight exploration — not a council.
+
+---
+
+## wicked-patch: Graph-Driven Multi-File Refactor
+
+wicked-patch is the deterministic multi-file transformation engine. It is exposed as the nested `wicked-garden-engineering-patch` skill under the engineering domain.
+
+```
+Developer invokes patch action: /wicked-garden-engineering patch-plan OldName
+  → engineering-patch skill reads codegraph from wicked-brain:
+      .codegraph/codegraph.db (structural graph, tree-sitter)
+      + injected edges (bus producer→consumer, dispatch, capability)
+  → computes full affected file set:
+      direct references (grep-visible)
+      + injected-edge references (not grep-visible)
+  → returns patch plan: files × change-kinds × risk surface
+
+Developer approves (or scopes) the plan
+
+Developer invokes apply: /wicked-garden-engineering apply <patch-file>
+  → for each affected file:
+      selects language generator (Python, TypeScript, Java, Go, SQL,
+       Rust, Kotlin, C#, PHP, Ruby — out of the box)
+      generator applies the transformation (rename, add-field, remove)
+      writes the changed file
+  → result: deterministic, complete, consistent transformation
+```
+
+New language support: `/wicked-garden-engineering new-generator` creates a generator for an additional language. Generators implement a documented interface; adding one requires no change to the patch core.
+
+wicked-patch and wicked-brain share the same codegraph database (`.codegraph/codegraph.db`). The `wicked-garden-search index` action refreshes both layers — brain (semantic) and codegraph (structural).
+
+---
+
+## Compiler Architecture
+
+The compiler emits a self-contained vault-backed gate into any repo — no wicked-garden or wicked-loom runtime required in the target.
+
+```
+Developer invokes: /wicked-garden-prove compile <repo> [--trigger hook,ci]
+  → scripts/compiler/compile.py entry point
+  → Phase 0 detection (scripts/compiler/phase0/detect.py):
+      identifies ecosystem (Node, Python, Rust, ...)
+      locates test/lint/build commands (binding detection)
+      identifies claims documents (files with claims: frontmatter)
+      maps risk surfaces
+  → derives multi-claim contract
+  → writes to <repo>/.wicked/:
+      contract.json   — the derived contract
+      gate.py         — stdlib-only, vault-direct gate script
+      bindings.json   — ecosystem bindings
+      README.md       — usage instructions
+      claims_lint.py  — written when claims: frontmatter doc is detected
+  → if --trigger hook:
+      installs git pre-push hook that runs gate.py
+  → if --trigger ci:
+      writes GitHub Actions workflow that runs gate.py
+```
+
+The emitted `gate.py` is vault-direct: it resolves `wicked-vault` via `npx`, not loom. This is intentional — the compiled gate cannot assume wicked-loom is present in the target repo. The garden's own gate uses loom; the emitted gate does not.
+
+AST enforcement: `tests/compiler/test_compile.py` verifies that the emitted `gate.py` is stdlib-only (no third-party imports, no wicked-garden imports). This test is part of CI.
+
+The on-switch rule: **compile the trigger and the enforcement; never compile the tool**. The vault is a runtime-resolved utility, not a compiled-in dependency. The guarantee is self-contained without shipping wicked-garden.
+
+---
+
+## Storage and State
+
+### DomainStore (`scripts/_domain_store.py`)
+
+Local JSON files with optional integration-discovery routing to MCP tools. Project-scoped paths via `scripts/_paths.py`. Path structure: `~/.something-wicked/wicked-garden/projects/{slug}/{domain}/{subpath}`. Do not hardcode the base path in consumer code.
+
+### SessionState (`scripts/_session.py`)
+
+Per-session ephemeral shared state. Not persisted across process restarts. Used for in-session coordination between skills and hooks.
+
+### Event Store (`scripts/_bus.py`)
+
+wicked-bus integration. Emits events in 4-segment format (`wicked.<domain>.<noun>.<past-tense-verb>`). The bus provides at-least-once delivery, append-only event records, and FTS5 search via the wicked-bus backing store.
+
+### codegraph.db
+
+Structural code graph built and maintained by wicked-brain at `.codegraph/codegraph.db`. Consumed by wicked-patch. The `search:index` action refreshes it.
+
+---
+
+## Hook Architecture
+
+Thirteen registered hook events across all `command` type scripts, dispatched through `hooks/scripts/invoke.py`:
+
+| Hook | Event(s) | Script arg | Purpose |
+|------|---------|------------|---------|
+| Bootstrap | `SessionStart` | `bootstrap` | Environment setup; peer verification (`/wicked-garden-core setup` flow); session initialization |
+| Prompt Submit | `UserPromptSubmit` | `prompt_submit` | Archetype detection; system-reminder injection |
+| Pre-Tool | `PreToolUse` | `pre_tool` | Tool input validation; MEMORY.md write guard; plan-mode intercept |
+| Post-Tool | `PostToolUse`, `PostToolUseFailure` | `post_tool` | Task state sync; file-change tracking; search index invalidation |
+| Task Completed | `TaskCompleted` | `task_completed` | Task audit write |
+| Subagent Lifecycle | `SubagentStart`, `SubagentStop` | `subagent_lifecycle start\|stop` | Subagent session tracking |
+| Permission Request | `PermissionRequest` | `permission_request` | Permission audit |
+| Notification | `Notification` | `notification` | Background notification handling |
+| Pre-Compact | `PreCompact` | `pre_compact` | Context-window checkpoint before compaction |
+| Stop | `Stop` | `stop` | Session teardown; audit write; event flush |
+| Session End | `SessionEnd` | `session_end` | Final session cleanup |
+
+Hook scripts are stdlib-only Python — no third-party imports. Bootstrap and Stop hooks return `{"ok": true}` on success; `{"ok": false, "reason": "..."}` blocks the triggering event. The UserPromptSubmit hook (`prompt_submit.py`) returns `{"continue": true}` to proceed and carries injected context in `hookSpecificOutput`; `{"continue": false}` blocks the prompt. The Stop hook uses `"async": true` to avoid blocking session shutdown.
+
+Hook scripts access `CLAUDE_PLUGIN_ROOT` to construct paths. All shell variables are quoted. Temp paths use `tempfile.gettempdir()`.
+
+---
+
+## Daemon (Optional)
+
+The Flask daemon (`daemon/`) provides:
+- Long-running operation support for indexing and background event processing.
+- A local HTTP API for skills to dispatch work that exceeds hook timeout limits.
+- Not required for any core plugin capability.
+
+Skills check for daemon availability before dispatching to it. If the daemon is absent, skills fall back to synchronous inline execution.
+
+---
+
+## Peer Integration Points
+
+| Peer | Integration Point | How Resolved |
+|------|------------------|-------------|
+| wicked-vault | `scripts/qe/vault_gate.py`, `scripts/qe/prove.py` | `WICKED_VAULT_BIN` env → PATH → `npx wicked-vault` |
+| wicked-loom | `scripts/qe/vault_gate.py` | `WICKED_LOOM_BIN` env → config → PATH → `node_modules/.bin` → `npx` |
+| wicked-testing | `scripts/qe/` (acceptance pipeline) | Installed peer; invoked by acceptance skills |
+| wicked-brain | `scripts/crew/`, search/smaht skills | Brain server on port 4243; auto-starts on skill invocation |
+| wicked-bus | `scripts/_bus.py` | Installed peer; event emit/consume |
+| codegraph | `.codegraph/codegraph.db` | Built by wicked-brain; consumed by patch skill |
+
+All peers degrade gracefully on absence — except the evidence gate, which fails closed when vault or loom is unreachable. A transient peer outage never invents a pass.

package/.product/RAID.md

@@ -0,0 +1,62 @@
+---
+name: RAID
+title: wicked-garden — Risks, Assumptions, Issues, Dependencies
+status: draft
+version: 0.1
+date: 2026-07-21
+author: mike.parcewski@gmail.com
+review-required: true
+---
+
+# RAID Log
+
+## Risks
+
+| ID | Risk | Likelihood | Impact | Mitigation |
+|----|------|-----------|--------|------------|
+| RISK-001 | Archetype detection accuracy degrades for ambiguous or very short prompts | Medium | Medium | Detector returns confidence score; low-confidence prompts prompt for clarification. Multi-archetype output handles mixed-intent work. |
+| RISK-002 | wicked-loom/wicked-vault peer absent → evidence gate fails closed | High (setup) | Low (expected) | Failing closed is the intended behavior. `/wg-check` validates peers at setup; setup skill guides installation. |
+| RISK-003 | codegraph not built → blast-radius/lineage/wicked-patch unavailable | High (optional) | Medium | codegraph is explicitly opt-in; skills degrade gracefully to text-search when graph is absent. |
+| RISK-004 | Plugin not loaded in `claude -p` non-interactive mode | Medium | High | Documented mitigation: user must add `--plugin-dir` via clis.toml override (garden#994 resolution). Long-term fix: persistent worker sessions (core#13). |
+| RISK-005 | Council seat (Antigravity/Codex) unavailable or returns garbage | Medium | Low | Council aggregation tolerates partial failures; the skill surfaces which seats failed. |
+| RISK-006 | Hook scripts fail on Windows without correct Python fallback | Low | High | All scripts use cross-platform patterns (tempfile.gettempdir, python fallback chain). CI must include Windows runner. |
+| RISK-007 | Slim Body Contract violated → parent context bloat | Low | Medium | `/wg-check --full` enforces the limit. CI validates component manifest on every PR. |
+
+---
+
+## Assumptions
+
+| ID | Assumption |
+|----|-----------|
+| ASS-001 | The host harness (Claude Code, Codex, Cursor, …) handles all planning, parallelism, and LLM calls. wicked-garden does not re-implement harness capabilities. |
+| ASS-002 | Users install the required peers (`wicked-testing`/`wicked-vault`, `wicked-loom`) before using the evidence gate. The setup skill validates this. |
+| ASS-003 | The codegraph (`.codegraph/codegraph.db`) is built and up-to-date when blast-radius/lineage/wicked-patch are used. |
+| ASS-004 | Harness plugins are loaded in interactive mode; non-interactive (`claude -p`) mode requires explicit plugin-dir configuration. |
+| ASS-005 | The `WICKED_VAULT_ACTOR` environment variable is set to a meaningful, stable actor identity for hard-gate evidence recording (not OS `$USER`). |
+| ASS-006 | wicked-bus is optional; garden emits events fail-open when bus is unavailable. |
+
+---
+
+## Issues
+
+| ID | Issue | Status | Resolution |
+|----|-------|--------|-----------|
+| ISS-001 | Plugin not loaded in `claude -p` subprocess (garden#994) | Closed | User-level clis.toml override; add `--plugin-dir ~/.claude/plugins` to claude seat's `headless_invocation`. |
+| ISS-002 | Schema drift risk: domain-model schema vendored in 3 places (brain canonical, wicked-core/tests/, garden skills/domain/vendor/) | Open | Drift guard test pending; garden's vendor copy must match canonical on each release. |
+| ISS-003 | Harness drift test for garden's schema vendor skips rather than fails when canonical path absent | Open | Fix: convert `pytest.skip` to `pytest.fail` so the drift guard is fail-closed. |
+
+---
+
+## Dependencies
+
+| Dependency | Type | Required | Notes |
+|-----------|------|----------|-------|
+| Claude Code (or compatible harness) | Runtime | Yes | Plugin host. Must support `context: fork`, hooks, skills. |
+| wicked-vault ≥ 0.4.0 | Runtime | Yes (for evidence gate) | Evidence backend. `0.4.0` introduced fail-closed `attest` on weak identity. |
+| wicked-loom | Runtime | Yes (for evidence gate) | Gate/resolve engine. Resolved via `WICKED_LOOM_BIN` → config → PATH → `npx`. |
+| wicked-testing | Runtime | Yes (for acceptance) | The acceptance pipeline is the standard gate mechanism. |
+| wicked-brain | Runtime | Optional | Cross-session memory + codegraph. Required for blast-radius, lineage, wicked-patch. |
+| wicked-bus | Runtime | Optional | Event audit trail. Garden emits events fail-open without it. |
+| codegraph (`@colbymchenry/codegraph`) | Runtime | Optional | Static graph builder. Powers blast-radius/lineage/wicked-patch. |
+| Python ≥ 3.9 | Runtime | Yes | Required for all hook scripts and CLI tools. |
+| node.js ≥ 18 | Runtime | Yes | Required for npm peer installs and wicked-vault/loom. |

package/.product/REQ-001-application-overview.md

@@ -0,0 +1,94 @@
+---
+name: REQ-001-application-overview
+title: wicked-garden — Application Overview
+status: draft
+version: 0.1
+date: 2026-07-21
+author: mike.parcewski@gmail.com
+review-required: true
+---
+
+# REQ-001 — Application Overview
+
+## Purpose
+
+wicked-garden is a Claude Code plugin (v12.28.1) that fills the gaps modern coding-agent harnesses cannot close alone. The premise is direct: harnesses — Claude Code, Codex, Cursor, Aider, OpenCode, Zed/ACP, and others — already plan, parallelize, and execute well. wicked-garden does not compete with that; it adds only what a planner-executor genuinely cannot do on its own:
+
+- **Evidence-gated done** — re-derives "done" from recorded evidence via the internal loom engine and wicked-vault; a self-asserted "tests pass" cannot lie its way green.
+- **Relationships grep cannot see** — codegraph + injected event-bus/dispatch/capability edges power blast-radius and lineage analysis.
+- **Deterministic multi-file refactor** — wicked-patch applies graph-driven renames and field additions across an entire codebase without leaving silent half-applied states.
+- **Cross-session memory** — wicked-brain persists decisions, patterns, and gotchas across sessions; knowledge that only lives in chat history does not exist.
+- **Real multi-model second opinions** — the jam:council skill convenes external LLM CLIs (Claude Code, Antigravity, Codex, local models) for independent evaluation; it is not the model talking to itself.
+- **Portable evidence gates** — the compiler (`/wicked-garden-prove compile`) emits a self-contained vault-backed gate into any repo that re-derives claims with no wicked-garden runtime present.
+
+The core invariant: **done is re-derived, not asserted.** A gate does not go green because an agent or human said so. Evidence is re-hashed and its verifier re-run through wicked-loom on every gate check. A missing evidence backend fails closed — it never invents a pass.
+
+Work-shape detection is how wicked-garden applies the right rigor without imposing a fixed pipeline. Each prompt classifies into one or more of **ten work-shape archetypes** (triage, explore, specify, decide, ship, review, incident, build, migrate, modernize). Each archetype owns its own phase shape, produces contract, and HITL discipline. The harness drives; wicked-garden steers by archetype.
+
+The plugin installs via `/plugin install wicked-garden` into any Claude Code session. It is skills-only: user entry points are consolidated per-domain skills. There are no slash commands in the distributed plugin — the `.claude/` dev tools (`/wg-*`) are development-only surfaces not shipped to marketplace users.
+
+---
+
+## Core User Flows
+
+### Flow 1 — Archetype-steered session: from prompt to phased execution
+
+1. Developer submits a prompt in Claude Code (e.g., "add a NOT NULL column to the users table and backfill existing rows").
+2. The `UserPromptSubmit` hook fires `hooks/scripts/prompt_submit.py`, which calls `scripts/crew/archetypes_v11.py::detect_archetypes()`.
+3. The detector scores the prompt against all ten archetype definitions and emits a `<wg archetype="migrate" score="0.91" />` system-reminder (or a multi-archetype set, e.g., `build+migrate`).
+4. The harness invokes the `wicked-garden-archetype` skill with the detected work-shape name. The skill loads `skills/archetype/refs/migrate.md` — the migrate playbook.
+5. The playbook defines the phase shape (plan → expand → backfill → cutover → contract), produces contract (shape change artifact, rollback proof), HITL gate at cutover (hard gate: requires explicit approval), and cost band (high).
+6. The harness executes the phases. At the cutover hard gate, execution pauses and surfaces the gate to the user. Approval unblocks; rejection rolls back.
+7. At phase completion the produces-gate re-derives the claim via wicked-loom. A missing verifier or unresolvable evidence backend fails closed.
+
+**Outcome**: the developer gets appropriately-scaled rigor for a schema migration — not the same lightweight flow as a typo fix, and not an arbitrary fixed pipeline.
+
+---
+
+### Flow 2 — Evidence gate: re-deriving done from recorded evidence
+
+1. A build phase completes. The agent records evidence via `wicked-vault record --actor garden-prove --run <test-suite>`. Evidence is stored in the vault's append-only store with a content hash and the actor identity.
+2. At the produces gate, the agent invokes `scripts/qe/vault_gate.py::gate_satisfied()`. The gate shells `wicked-loom gate`, which in turn shells `wicked-vault cross-check`.
+3. wicked-vault re-hashes the recorded evidence and re-runs the verifier. If the evidence hash matches and the verifier passes, the gate returns green. If evidence is missing, the hash does not match, or loom/vault is unresolvable, the gate **fails closed** — it returns `gate: "unavailable"`, never a vacuous pass.
+4. For hard gates (review, incident, migrate archetypes), the gate additionally requires an independent attestation recorded under a distinct `--actor` identity. Evidence recorded under the ambient OS `$USER` (`created_by_source='env-user'`) cannot satisfy an attestation gate — the evaluator-must-not-equal-creator constraint is enforced structurally, not by convention.
+5. The gate verdict is appended to the session's audit trail. Subsequent sessions resume from the recorded verdict without re-running the gate unless evidence changes.
+
+**Outcome**: "done" is a re-derived claim backed by tamper-evident evidence, not a self-assertion that can lie its way green.
+
+---
+
+### Flow 3 — Compiler: emitting a portable gate into a foreign repo
+
+1. A developer in a repo that does not have wicked-garden installed wants a build gate that re-derives claims on push and in CI.
+2. They (or an agent with wicked-garden) invoke the `wicked-garden-prove` skill's `compile` action: `/wicked-garden-prove compile <repo> --trigger hook,ci`.
+3. The compiler (`scripts/compiler/compile.py`) runs Phase 0 detection: it identifies the ecosystem (Node, Python, Rust, etc.), locates test/lint/build commands, identifies claims documents (files with `claims:` frontmatter), and maps risk surfaces.
+4. It derives a multi-claim contract and writes four files into `<repo>/.wicked/`: `contract.json`, `gate.py`, `README.md`, `bindings.json`. When a claims document is detected, it also writes `claims_lint.py`.
+5. The emitted `gate.py` is stdlib-only, imports nothing from wicked-garden, and resolves `wicked-vault` via `npx` — so it runs in any repo with neither wicked-garden nor wicked-loom present.
+6. With `--trigger hook,ci`, the compiler also installs a git pre-push hook and a GitHub Actions workflow. Every push re-derives the gate claims; a failing gate blocks the push.
+
+**Outcome**: the evidence-gate guarantee outlives the session that created it and requires no wicked-garden runtime in the target repo.
+
+---
+
+### Flow 4 — Multi-model council: independent second opinion
+
+1. An agent or developer wants a structural evaluation of an architecture proposal that is not self-graded — the model should not review its own work.
+2. They invoke the jam:council action: `/wicked-garden-jam council <proposal>`.
+3. The `wicked-garden-jam-council` fork worker skill convenes an evaluation session. It dispatches the proposal to available external LLM CLIs (Claude Code via Antigravity/Codex, and any locally-configured model) using `Task()` dispatch with isolated contexts.
+4. Each model evaluates the proposal independently, returning a structured verdict (findings, concerns, confidence). The council skill synthesizes the responses: agreement, disagreement, and unresolved tensions.
+5. The synthesized output is returned as a multi-perspective evaluation. The harness can treat a unanimous council failure as a hard gate.
+
+**Outcome**: the developer receives an independent evaluation from models that did not produce the work, structurally preventing self-grading.
+
+---
+
+### Flow 5 — wicked-patch: deterministic multi-file refactor
+
+1. A developer needs to rename a domain type across a large codebase — source files, tests, migration files, configuration, and documentation.
+2. They invoke the patch skill: `/wicked-garden-engineering rename OldName NewName`.
+3. The `wicked-garden-engineering-patch` nested skill reads the codegraph from wicked-brain (`.codegraph/codegraph.db`), identifies all nodes referencing `OldName`, and computes the full set of affected files including injected edges (bus producer→consumer, dispatch links) that grep cannot see.
+4. The skill shows the patch plan (files affected, kinds of change, risk surface). The developer approves or scopes the change.
+5. On approval, the patch applies deterministically using the language-specific generator for each file type. Generators exist out of the box for Python, TypeScript, Java, Go, SQL, Rust, Kotlin, C#, PHP, and Ruby. A `new-generator` action lets contributors add additional languages.
+6. The result is a complete, consistent rename across every file that references the symbol — including the relationships grep cannot see.
+
+**Outcome**: multi-file refactor is a graph operation, not a search-and-replace that leaves injected-edge references broken.

package/.product/REQ-002-technology-constraints.md

@@ -0,0 +1,103 @@
+---
+name: REQ-002-technology-constraints
+title: wicked-garden — Technology Constraints
+status: draft
+version: 0.1
+date: 2026-07-21
+author: mike.parcewski@gmail.com
+review-required: true
+---
+
+# REQ-002 — Technology Constraints
+
+## Runtime Environment
+
+**Claude Code plugin API** — wicked-garden is delivered as a Claude Code plugin (`/plugin install wicked-garden`). All user-facing surfaces are Claude Code skills (frontmatter-described SKILL.md files). The plugin exposes no slash commands in its distributed form; the `.claude/` developer tools (`/wg-*`) are development-only.
+
+**Node.js / Python dual runtime** — skills are Markdown files loaded by Claude Code; imperative logic lives in Python scripts under `scripts/` and `hooks/scripts/`. Node.js is required for wicked-bus (the event audit substrate) and for npm-installed peers. Python 3 is required for all hook scripts, the archetype detector, the compiler, the evidence gate, and domain store utilities. Both runtimes must be present in the agent's execution environment.
+
+**Cross-platform requirement** — all skills, hook scripts, and shell commands must work on macOS, Linux (x86_64 and arm64), and Windows (Git Bash and WSL). Native PowerShell is a secondary target. Specific constraints:
+- Hook scripts use `python3 -c "..."` with `2>/dev/null || python -c "..."` fallback.
+- Temp paths use `tempfile.gettempdir()`, not hardcoded `/tmp`.
+- JSON output in hooks uses Python, not shell builtins (`printf`, `echo`), which differ across platforms.
+- Python scripts are invoked via `sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh"` for cross-platform resolution.
+
+---
+
+## Required Peers
+
+Two peers are required for the evidence gate to function. Both are verified by `/wicked-garden-core setup`:
+
+| Peer | npm Package | Required Version | Role |
+|------|-------------|-----------------|------|
+| wicked-vault | `wicked-vault` | `>= 0.4.0` | Evidence backend — records, re-hashes, and verifies evidence attestations |
+| wicked-loom | `wicked-loom` | resolved at runtime | Gate engine — shells `wicked-vault cross-check`; the sole gate/resolve path since v12 loom cutover |
+
+wicked-vault `>= 0.4.0` is a breaking-change floor for hard gates: `attest` now fails closed on a weak/ambient worker identity (`created_by_source='env-user'`). Evidence for hard-gate attestation must be recorded under an explicit `--actor` (default: `WICKED_VAULT_ACTOR` env var, fallback `garden-prove`).
+
+wicked-loom is resolved at runtime in this order: `WICKED_LOOM_BIN` env var → config → PATH → `node_modules/.bin` → `npx`. Setting `WICKED_LOOM_CUTOVER=off` disables the gate (fails closed). Setting `WICKED_VAULT_BIN=""` kill-switches the vault behind loom.
+
+Three additional peers are opt-in:
+
+| Peer | npm Package | Required Version | Role |
+|------|-------------|-----------------|------|
+| wicked-testing | `wicked-testing` | `^0.8.0` | Acceptance testing gate; also installs wicked-vault as a transitive dependency |
+| wicked-brain | `wicked-brain` | `^0.18.0` | Cross-session memory, code graph, semantic search |
+| wicked-bus | `wicked-bus` | `^2.0.0` | Event audit trail, append-only event store, FTS5 search |
+
+wicked-understanding (repo playbooks from HEAD) and codegraph (structural code intelligence) are additional optional integrations.
+
+---
+
+## Storage
+
+**Local JSON files** — default persistence layer via `DomainStore` (`scripts/_domain_store.py`). Paths are project-scoped: `~/.something-wicked/wicked-garden/projects/{slug}/{domain}/{subpath}` where `slug` is derived from `cwd` hash. Consumer code must use `get_local_path()` from `_paths.py` or `_domain_store.py` — never hardcode the base path.
+
+**SQLite (via peers)** — wicked-brain provides FTS5 + BM25 search over the code graph and indexed content. wicked-bus provides an append-only event store with FTS5 search. wicked-vault provides an append-only evidence store. No standalone SQLite module in wicked-garden itself.
+
+**SessionState** (`scripts/_session.py`) — per-session ephemeral shared state. Does not persist across process restarts.
+
+**codegraph.db** — wicked-brain builds and maintains this structural code graph at `.codegraph/codegraph.db`. wicked-patch consumes it for multi-file refactor operations.
+
+---
+
+## Plugin Architecture Constraints
+
+**Skills-only** — the plugin exposes only skills. Former command surfaces and agent surfaces were absorbed into consolidated domain skills (domain router skills) and fork worker skills respectively as of v12.25. A domain router skill is user-invocable (`wicked-garden-{domain}`); a fork worker skill carries `context: fork` and is reached only via `Skill()`/`Task()` dispatch from another skill.
+
+**Slim body contract** — skill body files must stay slim (loaded into parent context permanently). Three patterns apply:
+- Pattern A (Advisory/State): ≤ 8 lines. For state mutation with no dispatch.
+- Pattern B (Write Brief + Dispatch): ≤ 30 lines. For session-specific work.
+- Pattern C (Interactive Branch + Dispatch): ≤ 35 lines. For user-decision-before-dispatch flows.
+
+Refs (the detailed content) live in `skills/{domain}/refs/` files (200-300 lines each) and are loaded on demand.
+
+**Hooks** — 13 registered hook events across all `command` type scripts, dispatched through `hooks/scripts/invoke.py`. Primary lifecycle hooks: `SessionStart` (bootstrap: environment setup, peer verification), `UserPromptSubmit` (archetype detection, system-reminder injection), `Stop` (teardown: session audit write). Tool-intercept hooks: `PreToolUse` (tool input validation; MEMORY.md write guard), `PostToolUse`/`PostToolUseFailure` (task sync; file-change tracking). Additional hooks: `TaskCompleted`, `SubagentStart`/`SubagentStop`, `PermissionRequest`, `Notification`, `PreCompact`, `SessionEnd`. Stop and `SessionEnd` hooks use `"async": true`. Bootstrap and Stop hooks return `{"ok": true}` on success; `{"ok": false, "reason": "..."}` blocks the event. The UserPromptSubmit hook returns `{"continue": true}` to proceed (with `hookSpecificOutput` for injected context) or `{"continue": false}` to block. All hook scripts are stdlib-only Python.
+
+**Daemon** (`daemon/`) — a Flask server for long-running operations (e.g., indexing, background event processing). Not required for core plugin function; opt-in for operations that exceed hook timeout limits.
+
+---
+
+## Dependency and Versioning Constraints
+
+**No mandatory cloud infrastructure** — all storage is local-first. No API keys required for wicked-garden itself (LLM calls go through the harness; external LLM CLIs for the council are the user's responsibility to configure).
+
+**Offline operation** — the plugin must function without network access except for LLM inference calls (which the harness manages). The evidence gate, compiler, archetype detector, wicked-patch, and all skill logic operate offline.
+
+**Plugin install path** — `npm install -g wicked-garden` or `/plugin install wicked-garden` via the Claude Code marketplace. The plugin does not require a global npm install to function; the marketplace path is the primary distribution channel.
+
+**Peer version pins** — pinned in `plugin.json` as version ranges (`^` or `>=`). The wicked-vault floor (`>= 0.4.0`) is a hard constraint for hard gates; running an older vault behind loom silently degrades to `gate: "unavailable"`.
+
+**Event naming** — all wicked-garden events on the bus follow the 4-segment format `wicked.<domain>.<noun>.<past-tense-verb>` per the ecosystem event grammar (WICKED_GARDEN_BUS_EVENTS.md). Divergence from this format is a contribution defect.
+
+---
+
+## Non-Functional Constraints
+
+**Gate semantics: fail-closed** — a gate that cannot re-derive its claim must not pass. `gate: "unavailable"` is the only valid non-green verdict when the backend is unreachable. There is no fallback to self-assertion.
+
+**Audit trail: append-only** — all evidence records and gate verdicts are append-only. No verdict is overwritten or deleted.
+
+**Actor identity for hard gates** — evidence recorded under ambient OS identity (`$USER`) cannot satisfy a hard-gate attestation (vault `>= 0.4.0` enforcement). The `WICKED_VAULT_ACTOR` env var (default: `garden-prove`) must be set correctly for hard-gate paths. `scripts/qe/prove.py::_prove_actor` is the reference.
+
+**Compiler emits stdlib-only gate** — the emitted `gate.py` from the compiler must be stdlib-only (AST-enforced in `tests/compiler/test_compile.py`). It resolves wicked-vault via `npx`, not loom. This constraint ensures the compiled gate runs in any repo with no wicked-garden or wicked-loom present.