wicked-garden 12.27.0

package/skills/workflow/refs/signal-keywords.md

@@ -0,0 +1,176 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Signal Keywords
+
+All 16 signal categories with keyword lists and specialist routing.
+Keywords ending with `*` match as stems (e.g., `auth*` matches authentication,
+authorization). Detection threshold: confidence >= 0.1 (matched / total).
+
+---
+
+## Signal-to-Keyword Reference
+
+### security — triggers: platform, qe
+
+`auth*`, `encrypt*`, `pii`, `credential*`, `token*`, `password`, `oauth`, `jwt`,
+`secret*`, `vault`, `certific*`, `login`, `session`, `csrf`, `xss`, `inject*`,
+`security`, `permiss*`, `rbac`
+
+---
+
+### performance — triggers: engineering, qe
+
+`scal*`, `load`, `optimi*`, `latency`, `throughput`, `cache`, `caching`,
+`performance`, `slow`, `fast`, `bottleneck`, `memory`, `cpu`, `concurren*`,
+`benchmark*`
+
+---
+
+### product — triggers: product
+
+`requirement`, `feature`, `story`, `customer`, `stakeholder`, `acceptance`,
+`roadmap`, `backlog`, `priority`, `user story`
+
+---
+
+### compliance — triggers: platform
+
+`soc2`, `hipaa`, `gdpr`, `pci`, `audit`, `policy`, `regulation`, `privacy`,
+`data-protection`, `compliance`, `regulatory`
+
+---
+
+### ambiguity — triggers: jam
+
+`maybe`, `either`, `could`, `should we`, `not sure`, `alternative`, `options`,
+`tradeoff`, `versus`, `vs`, `compare`, `brainstorm`
+
+---
+
+### complexity — triggers: delivery, engineering
+
+`multiple`, `system`, `integration`, `migrate`, `migration`, `refactor`,
+`distributed`, `microservice`, `legacy`, `cross-team`, `downstream`,
+`cascading`, `cross-cutting`, `foundational`, `core module`, `affects all`
+
+---
+
+### data — triggers: data
+
+`data`, `analytics`, `metrics`, `report*`, `dashboard`, `visuali*`, `query`,
+`database`, `sql`, `csv`, `etl`, `pipeline`, `ml`, `model`, `training`,
+`dataset`, `warehouse`, `schema`, `ontology`
+
+---
+
+### infrastructure — triggers: platform
+
+`deploy`, `deployment`, `ci/cd`, `pipeline`, `docker`, `kubernetes`, `k8s`,
+`cloud`, `aws`, `gcp`, `azure`, `terraform`, `helm`, `hook binding`,
+`event handler`, `event listener`, `middleware config`, `build system`,
+`makefile`, `configuration-as-code`
+
+---
+
+### architecture — triggers: agentic, engineering
+
+`architecture`, `design pattern`, `component`, `api contract`, `schema`,
+`system design`, `adr`, `decision record`, `monolith`, `microservice`,
+`event-driven`, `cqrs`, `hexagonal`, `algorithm`, `orchestrat*`, `dispatcher`,
+`resolver`, `parser`, `engine`, `scoring`, `routing logic`, `decision logic`,
+`phase selection`, `signal detection`
+
+---
+
+### ux — triggers: product
+
+`user`, `experience`, `ux`, `ui`, `flow`, `usability`, `accessibility`,
+`a11y`, `wcag`, `persona`, `journey`, `wireframe`, `prototype`,
+`design system`, `interaction`
+
+---
+
+### strategy — triggers: product
+
+`roi`, `business value`, `investment`, `competitive`, `market`, `strategic`,
+`value proposition`, `differentiation`, `business case`
+
+---
+
+### content — triggers: jam, product
+
+`readme`, `documentation`, `docs`, `rewrite`, `messaging`, `copy`, `content`,
+`landing page`, `blog post`, `user guide`, `editorial`, `tone`, `voice`,
+`narrative`, `announcement`, `release note*`
+
+---
+
+### text-as-code — triggers: qe, engineering
+
+`command`, `skill`, `agent`, `prompt`, `instruction`, `SKILL.md`, `frontmatter`,
+`slash command`, `hook script`, `persona`, `specialist`, `phase gate`,
+`crew routing`, `signal detection`, `phase selection`, `plugin instruction*`,
+`behavior-defining`
+
+---
+
+### reversibility — triggers: platform, delivery
+
+`migrat*`, `schema`, `breaking change`, `deprecat*`, `backward incompatible`,
+`drop table`, `drop column`, `remove api`, `rename api`, `data transform*`,
+`restructur*`, `irreversible`, `feature flag`, `toggle`, `rollback`, `canary`,
+`blue-green`
+
+---
+
+### novelty — triggers: jam, engineering
+
+`first time`, `new pattern`, `prototype`, `proof of concept`, `poc`,
+`greenfield`, `from scratch`, `never done`, `unfamiliar`, `research`,
+`spike`, `experiment*`, `evaluat*`
+
+---
+
+### quality — triggers: qe
+
+`quality`, `testing`, `coverage`, `reliability`, `qe`, `test strategy`,
+`acceptance criteria`, `testability`, `tdd`, `regression`, `lint`,
+`static analysis`, `slo`, `error rate`, `error budget`, `canary`, `rollback`,
+`performance regression`, `quality gate`, `shift-left`
+
+---
+
+### imagery — triggers: design (not in default specialist set)
+
+`image`, `visual`, `illustration`, `graphic`, `photo`, `screenshot`, `mockup`,
+`render`, `generate image`, `create image`, `edit image`, `modify image`,
+`inpaint`, `logo`, `icon`, `banner`, `hero image`, `thumbnail`, `dall-e`,
+`imagen`, `stable diffusion`, `flux`, `asset`, `creative`, `artwork`
+
+---
+
+## Detection Algorithm
+
+1. Lowercase the input text
+2. For each signal category: count matching keywords (stem match for `*`, whole-word for plain)
+3. confidence = matched / total_in_category
+4. Signal detected when confidence >= 0.1 (default threshold, configurable)
+5. Detected signals → specialist routing (see specialist-routing-rules.md)
+
+## Ambiguity Detection (separate from signal keywords)
+
+Fires `jam` specialist regardless of signal confidence when input matches:
+- Multiple question marks in input (`?.*?`)
+- Phrases: `should we`, `should i`, `could be`, `might be`, `may be`
+- Words: `not sure`, `options`, `alternative`, `tradeoff`, `versus`, `vs.`,
+  `compare`, `comparison`
+
+## Semantic Signal Entries
+
+**Deprecated in v6**: the v5 `signal_library.py` semantic-matching entry point was
+removed in the v6 rebuild (see issue #428) along with the rule-engine stack. The
+facilitator rubric reads project context directly via factor scoring rather than
+looking up cached signal entries. This document is retained as a historical reference
+for the keyword categories; no runtime consumer reads it in v6.

package/skills/workflow/refs/specialist-routing-rules.md

@@ -0,0 +1,159 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Specialist Routing Rules
+
+Signal-to-specialist mapping, complexity thresholds, fallback agents,
+and routing tier definitions.
+
+---
+
+## Signal-to-Specialist Mapping
+
+| Signal | Specialists Triggered |
+|--------|----------------------|
+| security | platform, qe |
+| performance | engineering, qe |
+| product | product |
+| compliance | platform |
+| ambiguity | jam |
+| complexity | engineering |
+| data | data |
+| infrastructure | platform |
+| architecture | agentic, engineering |
+| ux | product |
+| strategy | product |
+| content | jam, product |
+| text-as-code | qe, engineering |
+| reversibility | platform |
+| novelty | jam, engineering |
+| quality | qe |
+| imagery | _(no specialist in default set)_ |
+
+Note: Each signal maps to a SET of specialists — all specialists in the set are
+considered for engagement when that signal is detected above threshold.
+
+---
+
+## Specialist Routing Tiers
+
+Each specialist is assigned a routing tier based on signal strength and complexity:
+
+| Tier | Meaning | Threshold |
+|------|---------|-----------|
+| REQUIRED | Must engage — signal is high confidence and critical | confidence >= 0.4 OR complexity >= 5 |
+| RECOMMENDED | Should engage — signal detected at moderate confidence | confidence >= 0.1 |
+| OPTIONAL | May engage — low signal confidence, discretionary | below RECOMMENDED |
+
+Specialists below the OPTIONAL threshold are not recommended.
+
+---
+
+## Complexity-Based Engagement Rules
+
+These rules apply AFTER signal-based routing:
+
+| Complexity | Rule |
+|------------|------|
+| 0-2 | Built-in agents only (facilitator, reviewer, implementer, researcher) |
+| 3-4 | Core specialists based on detected signals |
+| 5-7 | All relevant specialists |
+
+---
+
+## Ambiguity Rule
+
+When input is detected as ambiguous (see signal-keywords.md detection patterns),
+`jam` specialist is always added to the recommended list regardless of confidence
+threshold. Ambiguity = jam.
+
+---
+
+## Fallback Agents
+
+When a specialist is not available (not installed), use this fallback:
+
+| Specialist | Fallback Agent |
+|------------|----------------|
+| jam | facilitator |
+| qe | reviewer |
+| product | facilitator |
+| engineering | implementer |
+| platform | implementer |
+
+| data | researcher |
+| agentic | reviewer |
+| design | facilitator |
+
+Valid built-in fallback agents: `facilitator`, `reviewer`, `implementer`, `researcher`
+
+Maximum fallback chain depth: 1 (no chained fallbacks)
+
+---
+
+## Routing Lanes
+
+After specialist selection, projects are assigned a routing lane based on
+the normalized risk score:
+
+| Lane | Weighted Risk Index | Meaning |
+|------|---------------------|---------|
+| AUTO | < 0.15 | Execute immediately — very low risk |
+| FAST | 0.15–0.30 | Minimal gates — trivial, well-understood |
+| STANDARD | 0.30–0.55 | Full crew gates — non-trivial but understood |
+| ELEVATED | 0.55–1.00 | Human review required — complex/regulated/high-risk |
+| LOOP | (hard rule) | Incident/iterative with learning checkpoints |
+
+### Hard Rules (override weighted index)
+
+Hard rules are evaluated FIRST. First matching rule wins:
+
+| Rule | Condition | Lane |
+|------|-----------|------|
+| 1 — Incident | impact >= 0.7 AND team_coordination >= 0.8 | LOOP |
+| 2 — Regulatory | compliance_exposure >= 0.85 | ELEVATED |
+| 3 — Risky irreversible | reversibility >= 0.8 AND (impact >= 0.7 OR novelty >= 0.8) | ELEVATED |
+| 4 — Safe auto | novelty <= 0.25 AND impact <= 0.3 AND reversibility <= 0.2 | AUTO |
+| 5 — Low-risk fast | impact <= 0.2 AND novelty <= 0.2 AND reversibility <= 0.2 | FAST |
+
+If no hard rule matches, use the Weighted Risk Index thresholds above.
+
+---
+
+## Normalized Dimension Weights
+
+Used to compute the Weighted Risk Index (WRI). All dimensions sum to ≤1.0.
+
+| Dimension | Weight |
+|-----------|--------|
+| impact | 0.24 |
+| reversibility | 0.24 |
+| novelty | 0.18 |
+| coupling | 0.10 |
+| data_risk | 0.06 |
+| compliance_exposure | 0.05 |
+| ux_surface | 0.03 |
+| team_coordination | 0.03 |
+
+WRI = Σ(dimension_value × weight) / Σ(weights)
+
+---
+
+## Specialist Discovery
+
+Specialists are discovered at runtime from `specialist.json` files in each plugin.
+Short names (e.g., `engineering`, `platform`) are matched against the
+Signal-to-Specialist mapping above.
+
+When specialists are unavailable, crew falls back to built-in agents per the
+Fallback Agents table above.
+
+---
+
+## Cross-Reference
+
+- Signal keywords per category: [signal-keywords.md](signal-keywords.md)
+- Archetype scoring adjustments: [archetype-adjustments.md](archetype-adjustments.md)
+- Risk dimension scoring: [risk-dimension-signals.md](risk-dimension-signals.md)
+- Composite score formula: [scoring-rubric.md](scoring-rubric.md)

package/skills/worktrees/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: wicked-garden-worktrees
+context: fork
+description: |
+  Git worktree hygiene — when to create, how to clean up, and what fails silently.
+  Captures three classes of bug that recur with worktree-based agent isolation:
+  subagent dangling commits, orphan branches with unique work, and time-sensitive
+  dangling-commit garbage collection. Includes detection commands, the salvage
+  decision flow, and the trust-but-verify rule for subagent commit reports.
+
+  Use when: a subagent reports a commit SHA, after a worktree-based agent finishes,
+  cleaning up `.claude/worktrees/`, salvaging old crew worktrees, "is this branch
+  in main?", verifying agent-claimed commits actually landed, planning multi-agent
+  parallel work in worktrees.
+status: stable
+phase_relevance: ["build"]
+archetype_relevance: ["*"]
+---
+
+# Worktrees
+
+Git worktrees let multiple branches be checked out simultaneously and let
+agent runtimes (Claude Code's `Agent({isolation: 'worktree'})`, crew runners,
+etc.) make changes in isolation without disturbing the main checkout. Useful —
+and a quiet source of three repeating bugs.
+
+## Three failure modes (memorize these)
+
+### 1. Subagent dangling commits
+
+Subagent dispatched into an isolated worktree commits inside that worktree. Branch ref lives only in the worktree; when the worktree is removed, the commit is **dangling** — reachable only via `git fsck --no-reflogs --lost-found` until `git gc` collects it (14-day default via `gc.pruneExpire`). The subagent's "Commit SHA: abc1234" report becomes a lie. Code may also be sitting in the main worktree as unstaged changes.
+
+**Trust-but-verify rule** — every time a subagent reports a commit, run the ancestry check from `refs/recipes.md` §1.
+
+### 2. Orphan branches with unique work, no worktree on disk
+
+Worktree dir is gone (auto-cleaned, deleted weeks ago); branch (local or `origin/crew/<name>`) still points at commits NOT in main; `git worktree list` says nothing about it. Bulk-deleting branches because "no worktree = no work" silently loses everything between fork-point and tip.
+
+Detection commands in `refs/recipes.md` §2. Each branch needs an explicit salvage decision (see Salvage flow below).
+
+### 3. Dangling commits, no branch ref at all
+
+Commit object exists but no branch points at it. **Time sensitive** — once `git gc` runs (default grace 14 days), the object is unreachable forever. List + preserve commands in `refs/recipes.md` §3.
+
+**Decision must be prompt** — there is no third state. Either preserve or accept the loss.
+
+## Authoritative signal for "is this work safe to delete"
+
+Branch + remote ref state, **not** on-disk worktree presence. Worktree-dir absence is the LEAST reliable indicator of merge state. Safe-delete recipe in `refs/recipes.md` §4.
+
+## Salvage flow (when you find unique work)
+
+For each candidate branch:
+
+1. **Locate** — `.claude/worktrees/agent-*` and project-specific dirs (e.g. `~/.command_iq/worktrees/crew-*`). Run `git worktree list`.
+2. **Identify** — branch name + HEAD SHA.
+3. **Classify** using ancestry-based checks (NOT tree-identity diffs — main may have advanced past a fully-merged branch). Verdict table and signals in `refs/recipes.md` §5.
+4. **Act** per verdict:
+   - **ALREADY_MERGED** → delete using the safety recipe.
+   - **SALVAGEABLE** → do not delete; extract plan first; delete only after extraction lands on main.
+   - **DEAD** → delete branch + log the deletion (subject + date).
+
+Manual file-by-file extraction often beats `git cherry-pick` on noisy branches — see `refs/recipes.md` §7.
+
+## When the subagent reports a commit but the work is partly unstaged
+
+Dangling commit SHA + unstaged changes in main worktree shows up when the subagent edited shared files (main worktree sees as unstaged) before its own commit (lands in worktree branch). Both halves need attention. Re-landing recipe in `refs/recipes.md` §6.
+
+## Trust-but-verify checklist for subagent reports
+
+Whenever a subagent's summary says "commit SHA: XYZ":
+
+1. `git merge-base --is-ancestor XYZ origin/main` — must return true (exit 0). Use `origin/main` (not `HEAD`); the latter false-positives if you're on a feature branch. `git fetch origin main` first if origin is stale.
+2. `git status -s` — should be empty if the commit is real and complete
+3. `git show XYZ --stat | head` — confirm the change set matches what the subagent described
+4. If any of those fail, the subagent's work needs re-landing or follow-up
+
+Skipping this check has cost time before. The closing comment on a
+GitHub issue citing a dangling SHA is misleading future archaeology.
+
+## Cross-references
+
+- The CLAUDE.md "Worktree hygiene" section in projects that use worktree
+  isolation should reference this skill instead of redefining the rules.
+- This skill complements `wicked-garden:engineering:review` — that
+  reviews code changes; this reviews whether the changes actually
+  landed where they should.

package/skills/worktrees/refs/recipes.md

@@ -0,0 +1,96 @@
+---
+phase_relevance: ["build"]
+archetype_relevance: ["*"]
+---
+# Worktree Recipes
+
+Detection, salvage, and verification commands for the three worktree failure modes.
+
+## 1. Verify a subagent commit landed in main
+
+Use `origin/main` (not `HEAD`) so a checked-out feature branch doesn't false-positive. Run `git fetch origin main` first if origin is stale.
+
+```bash
+git merge-base --is-ancestor <sha> origin/main && echo "in main" || echo "DANGLING"
+```
+
+If DANGLING: re-commit working-tree changes yourself, or `git cherry-pick <sha>` to bring the dangling commit forward.
+
+## 2. Find orphan branches with unique work (no worktree on disk)
+
+```bash
+# Local branches with unique commits not in main
+git for-each-ref refs/heads/ --format='%(refname:short)' \
+  | xargs -I{} sh -c 'unique=$(git rev-list --count origin/main..{} 2>/dev/null); [ "${unique:-0}" -gt 0 ] && echo "{}: $unique unique"'
+
+# Remote crew/* branches with unique commits not in main
+git for-each-ref refs/remotes/origin/crew/ --format='%(refname:short)' \
+  | xargs -I{} sh -c 'unique=$(git rev-list --count origin/main..{} 2>/dev/null); [ "${unique:-0}" -gt 0 ] && echo "{}: $unique unique"'
+```
+
+Each such branch needs an explicit salvage decision — do NOT bulk-delete on the assumption that "no worktree = no work".
+
+## 3. Find and preserve dangling commits before gc
+
+`git gc` runs after default 14-day grace (`gc.pruneExpire`); after that, dangling commit objects are unreachable forever.
+
+```bash
+# List dangling commits
+git fsck --no-reflogs --lost-found 2>&1 | grep "dangling commit"
+
+# Inspect one (shows tree + parent + message)
+git show <sha> --stat | head -20
+
+# Preserve one before gc takes it
+git branch salvage-<topic> <sha>
+git push origin salvage-<topic>
+```
+
+## 4. Safe delete of worktree + branch
+
+Only delete after step 1 returns empty.
+
+```bash
+# 1. Verify content is in main (MUST be empty before proceeding)
+git log origin/main..<branch-name> --oneline
+
+# 2. Then delete (only if step 1 was empty)
+git worktree unlock <path> 2>/dev/null   # in case it's locked
+git worktree remove --force <path>
+git branch -D <branch-name>
+```
+
+## 5. Salvage classification (per candidate branch)
+
+Use ancestry-based checks, NOT tree-identity diffs. Main may have advanced past a fully-merged branch; tree-identity will lie about it.
+
+| Verdict | Signal | Action |
+|---------|--------|--------|
+| **ALREADY_MERGED** | `git log origin/main..<branch>` empty AND `git cherry -v` shows zero `+` rows | Safe to delete using §4 |
+| **SALVAGEABLE** | `git cherry -v origin/main <branch>` shows `+` rows | Do not delete; produce extract plan; delete only after extraction lands on main |
+| **DEAD** | Abandoned with no useful changes | Delete branch + log the deletion (subject + date) |
+
+`git cherry -v` is more reliable than subject-grepping — it shows patch equivalence even when squash + cherry-pick changed the commit message text.
+
+`git rev-list --count origin/main..<branch>` returns the count of unique-by-ancestry commits — supporting context, not a verdict on its own.
+
+## 6. Re-land work after a dangling commit + unstaged changes
+
+This combination shows up when a subagent edited shared files (which the main worktree sees as unstaged) before making its commit (which lands in the worktree's branch). Both halves need attention:
+
+```bash
+# Check if the working tree has uncommitted changes from the subagent
+git status -s
+
+# If yes, and they look like the fix the subagent claimed:
+git diff --stat                                    # confirm scope is right
+# Run project-specific verification — typecheck / build / unit tests as appropriate
+# (e.g. `npx tsc --noEmit`, `cargo check`, `pytest`, `go test ./...`, etc.)
+git add <files> && git commit -m "..."
+```
+
+You're effectively re-landing the subagent's work as your own commit because the subagent's worktree commit is unreachable.
+
+## 7. Manual extraction beats cherry-pick on noisy branches
+
+When a candidate branch has 70k+ LOC of regenerated noise (lockfiles, brain-index json, snapshot files) plus a few hundred LOC of real work, `git cherry-pick` drags everything. Manual file-by-file extraction keeps only the substantive change set.