wicked-garden 12.27.0

package/skills/workflow/refs/archetype-adjustments.md

@@ -0,0 +1,205 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Archetype Adjustments
+
+11 project archetypes with detection keywords and scoring adjustments.
+Archetypes adjust impact scoring and inject relevant signals based on what
+actually matters for the project type.
+
+---
+
+## Archetype Detection
+
+An archetype is detected when **at least 2** of its keywords match the input
+text. Single-keyword matches do not trigger an archetype (prevents false
+positives like "scoring" alone triggering infrastructure-framework).
+
+Confidence = min(matched_count / (total_keywords * 0.3), 1.0)
+
+Multiple archetypes can be detected simultaneously. The highest-confidence
+archetype is the `primary_archetype`.
+
+---
+
+## Adjustment Format
+
+| Field | Meaning |
+|-------|---------|
+| `impact_bonus` | Added to impact score before composite calculation |
+| `inject_signals` | Signals auto-added if not present (with given confidence) |
+| `min_complexity` | Floor for complexity score — prevents underscoring |
+| `description` | Why this archetype matters for scoring |
+
+---
+
+## Archetype Table
+
+### content-heavy
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | `product: 0.3` |
+| min_complexity | 2 |
+| description | Content-heavy: messaging consistency and factual accuracy matter |
+
+**Detection keywords**: content, copy, messaging, blog, cms, landing page,
+marketing, seo, editorial, article, headline, brand, tone, voice, paragraph,
+section copy, fact*, consistency, wording
+
+---
+
+### ui-heavy
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | `ux: 0.3` |
+| min_complexity | 2 |
+| description | UI-heavy: design consistency and user experience require review |
+
+**Detection keywords**: component, design system, css, layout, responsive,
+animation, theme, style, visual, frontend, react, vue, angular, dashboard,
+widget, button, form, modal, sidebar, navigation, menu, look and feel, differentiation
+
+---
+
+### api-backend
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | _(none)_ |
+| min_complexity | 2 |
+| description | API/Backend: integration surface and contract stability matter |
+
+**Detection keywords**: api, rest, graphql, endpoint, service, server, backend,
+database, query, orm, grpc, websocket, microservice, gateway, proxy, contract
+
+---
+
+### infrastructure-framework
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +2 |
+| inject_signals | `architecture: 0.3` |
+| min_complexity | 3 |
+| description | Infrastructure/Framework: core execution path changes have broad impact |
+
+**Detection keywords**: plugin, framework, build system, ci/cd, scaffold, hook,
+middleware, engine, core, execution, routing, dispatch, orchestrat*, phase,
+workflow, configuration, tooling, cli, command, agent, prompt engineering,
+behavior, core path, execution path, foundational
+
+---
+
+### data-pipeline
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | `data: 0.3` |
+| min_complexity | 2 |
+| description | Data pipeline: data quality, lineage, and downstream effects matter |
+
+**Detection keywords**: etl, pipeline, data flow, transform, warehouse, lake,
+batch, stream, ingest, extract, load, lineage, dbt, airflow, spark
+
+---
+
+### mobile-app
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | `ux: 0.3` |
+| min_complexity | 2 |
+| description | Mobile app: platform constraints, UX patterns, and release cycles matter |
+
+**Detection keywords**: ios, android, mobile, react native, flutter, swift,
+kotlin, app store, play store, push notification, offline, gesture
+
+---
+
+### ml-ai
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | `data: 0.3` |
+| min_complexity | 3 |
+| description | ML/AI: model quality, training data, and evaluation rigor matter |
+
+**Detection keywords**: model, training, inference, embedding, vector, llm,
+fine-tune, prompt, rag, evaluation, benchmark, dataset, feature engineering,
+hyperparameter
+
+---
+
+### compliance-regulated
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +2 |
+| inject_signals | `compliance: 0.5, security: 0.3` |
+| min_complexity | 3 |
+| description | Compliance/Regulated: audit trails, policy adherence, and risk documentation matter |
+
+**Detection keywords**: hipaa, soc2, gdpr, pci, audit, compliance, regulation,
+phi, pii, data protection, retention, consent, privacy
+
+---
+
+### monorepo-platform
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +2 |
+| inject_signals | `architecture: 0.3` |
+| min_complexity | 3 |
+| description | Monorepo/Platform: cross-package impact, shared dependencies, and versioning matter |
+
+**Detection keywords**: monorepo, workspace, package, shared, library, dependency,
+nx, turborepo, lerna, cross-package, internal package, versioning
+
+---
+
+### real-time
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +1 |
+| inject_signals | `performance: 0.3` |
+| min_complexity | 2 |
+| description | Real-time: latency, concurrency, and state synchronization matter |
+
+**Detection keywords**: websocket, real-time, realtime, streaming, push,
+event-driven, pubsub, message queue, kafka, rabbitmq, socket, live update
+
+---
+
+### text-as-code
+
+| Field | Value |
+|-------|-------|
+| impact_bonus | +2 |
+| inject_signals | `architecture: 0.3, text-as-code: 0.7` |
+| min_complexity | 3 |
+| description | Text-as-code: commands/agents/skills/hooks are behavioral programs — instruction changes affect crew routing, gate enforcement, and QE coverage |
+
+**Detection keywords**: _(detected via text-as-code signal category rather than its own keyword list — see signal-keywords.md)_
+
+---
+
+## Application Order
+
+1. Detect all matching archetypes from input text
+2. Sort by confidence (highest first)
+3. Apply adjustments from each detected archetype:
+   - `impact_bonus` is applied once per archetype (additive)
+   - `inject_signals` is merged into signal_confidences (max wins)
+   - `min_complexity` takes the maximum floor across all archetypes
+4. After all archetype adjustments, re-run specialist selection with updated signals

package/skills/workflow/refs/evidence.md

@@ -0,0 +1,58 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Evidence Tracking
+
+Crew gate decisions and phase artifacts are tracked as evidence to support
+auditability and quality assurance across the workflow lifecycle.
+
+## Evidence Tiers
+
+| Tier | Name | Description | Example |
+|------|------|-------------|---------|
+| L1 | Assertion | Agent states a conclusion | "No security risks found" |
+| L2 | Reference | Points to specific artifact | "See `tests/auth.test.ts` lines 42-68" |
+| L3 | Artifact | Produces a reviewable output | Test results, review checklist, diff |
+| L4 | Verified | Independent confirmation | Second agent validates L3 artifact |
+
+Gates require minimum evidence tiers based on phase:
+- **Clarify/Design gates**: L1 sufficient (assertions with rationale)
+- **Build gates**: L2 minimum (references to changed files, test coverage)
+- **Test/Review gates**: L3 minimum (test output, review report artifacts)
+
+## Artifact Naming
+
+Evidence artifacts follow the convention:
+
+```
+{phase}-{type}-{timestamp}.{ext}
+```
+
+Examples:
+- `build-test-results-20260301T1420.json`
+- `review-checklist-20260301T1430.md`
+- `design-architecture-decision-20260301T1400.md`
+
+## Collection Methods
+
+### Automatic Evidence
+
+The crew workflow automatically captures:
+- **Task completion records**: TaskUpdate status transitions with timestamps
+- **Gate decisions**: Pass/fail with reasoning from gate agents
+- **Phase artifacts**: Files created or modified during each phase
+- **Specialist dispatches**: Which agents were engaged and their outputs
+
+### Manual Evidence
+
+Agents can explicitly record evidence via:
+- Gate reports in phase status files (`phases/{phase}/status.md`)
+- Inline references in task descriptions linking to files or test output
+- Review checklists produced by reviewer agents
+
+## Accessing Evidence
+
+Use `/wicked-garden:crew:evidence` to view evidence collected for the
+current project or a specific task. Evidence is stored alongside the
+crew project data and persists via DomainStore.

package/skills/workflow/refs/integration.md

@@ -0,0 +1,130 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Utility Plugin Integration
+
+How wicked-crew integrates with utility plugins (graceful degradation).
+
+## Task Management (Claude Native)
+
+Crew uses Claude's native task tools for all task lifecycle operations. **Use the full richness of task fields, including `metadata`, per the event envelope contract in `scripts/_event_schema.py`.** PreToolUse validates every TaskCreate/TaskUpdate against that contract.
+
+### Creating Tasks
+
+```
+TaskCreate(
+  subject="{Phase}: {project-name} - {task description}",
+  description="WHY this task exists, what problem it solves, acceptance criteria",
+  activeForm="Working on {task}",
+  metadata={
+    "event_type": "task",          # or coding-task, gate-finding, phase-transition, procedure-trigger, subtask
+    "chain_id": "{project}.{phase}",  # dotted causality: {project}.root, {project}.{phase}, {project}.{phase}.{gate}
+    "source_agent": "{agent-name}",
+    "phase": "{phase}",             # required for coding-task, gate-finding, phase-transition
+    "priority": "P1",               # P0 (critical) through P3 (minor)
+    "assigned_to": "agent-name"     # who owns this
+  }
+)
+```
+
+### Updating Tasks (use full fields)
+
+```
+# Set dependencies between tasks
+TaskUpdate(taskId="{id}", addBlockedBy=["{blocker-id}"])
+TaskUpdate(taskId="{id}", addBlocks=["{dependent-id}"])
+
+# Update with reasoning, not just status
+TaskUpdate(
+  taskId="{id}",
+  status="completed",
+  description="Original desc + \n\n## Outcome\nChose X because Y. Trade-off: Z."
+)
+```
+
+### Enrichment Guidelines
+
+- **description**: Include the WHY, not just the WHAT. Add outcomes when completing.
+- **addBlockedBy/addBlocks**: Set dependencies — task views render blocked state until the dependency closes.
+- **metadata.priority**: Set explicitly instead of relying on keyword inference.
+- **description updates on completion**: Document what was decided, learned, or changed.
+
+### Querying
+
+```
+TaskList()  # filter by subject: (?i)^{phase}[\s:-].*{project-name}
+TaskGet(taskId="{id}")
+```
+
+**Validation & persistence**: PreToolUse runs `pretool_taskcreate.py` on every TaskCreate/TaskUpdate, validating the `metadata` dict against `scripts/_event_schema.py` (event_type, chain_id shape, source_agent, required per-type fields). Tasks persist natively under `${CLAUDE_CONFIG_DIR}/tasks/{session_id}/`.
+
+## wicked-brain:memory
+
+**When available**: Cross-session learning
+
+```
+# Store decision
+Skill(skill="wicked-brain:memory", args="store \"{decision}\" --type decision --tags \"{project}\"")
+
+# Recall past context
+Skill(skill="wicked-brain:memory", args="recall \"{project pattern}\"")
+
+# Store episodic memory
+Skill(skill="wicked-brain:memory", args="store \"Encountered {issue}, resolved by {solution}\" --type episodic --tags \"{project}\"")
+```
+
+**Fallback**: Project files stored locally via DomainStore under the wicked-crew domain
+
+### Memory Types for Projects
+
+| Type | Use Case |
+|------|----------|
+| decision | Architecture choices, tradeoffs |
+| episodic | Bugs fixed, lessons learned |
+| procedural | Patterns that worked |
+| preference | User workflow preferences |
+
+## Detection Pattern
+
+Crew uses Claude's native task tools (TaskCreate, TaskUpdate, TaskList, TaskGet) directly — no plugin detection needed for task management. The PreToolUse hook enforces the metadata envelope defined in `scripts/_event_schema.py`.
+
+For optional memory storage (wicked-brain:memory), use graceful degradation:
+
+```python
+# Check if a utility plugin skill is available
+# by attempting to use it; if unavailable, skip gracefully
+```
+
+```
+# In markdown commands, use conditional phrasing:
+# "If wicked-brain:memory is available:" → Skill(skill="wicked-brain:memory", args="store ...")
+# Otherwise, skip the step (no fallback needed)
+```
+
+## Configuration
+
+Users can customize utility plugin usage in the wicked-crew local storage `config.yaml`:
+
+```yaml
+utilities:
+  mem:
+    enabled: true
+    auto_store_decisions: true  # Store architectural decisions
+
+  cache:
+    enabled: true
+    ttl_hours: 1
+```
+
+## Integration Events
+
+Crew emits events when engaging utilities:
+
+```
+crew:utility:engaged:success
+  └── context: {utility: "mem", action: "store-decision"}
+
+crew:utility:unavailable:warning
+  └── context: {utility: "mem", fallback: "file-based"}
+```

package/skills/workflow/refs/risk-dimension-signals.md

@@ -0,0 +1,260 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Risk Dimension Signals
+
+Seven independent risk dimensions computed from text analysis. Each dimension
+is scored 0-3 and drives different workflow decisions.
+
+---
+
+## Dimension Overview
+
+| Dimension | Range | Drives |
+|-----------|-------|--------|
+| impact | 0-3 | Gate strictness (fast-pass vs full gate) |
+| reversibility | 0-3 | Rollback planning, gate type selection |
+| novelty | 0-3 | Specialist engagement, design phase inclusion |
+| test_complexity | 0-3 | Test strategy scope, integration test setup needs |
+| documentation | 0-3 | API docs, user guides, ADR requirements |
+| coordination_cost | 0-3 | Cross-domain deps, specialist handoffs, review requirements |
+| operational | 0-3 | Deployment, migration, rollback operational needs |
+
+---
+
+## Dimension: impact
+
+Combines file role analysis with integration surface detection. Capped at 3.
+
+### File Role Scoring (5-tier taxonomy)
+
+| Tier | File Pattern | Weight |
+|------|-------------|--------|
+| 1 (behavior-defining) | commands/, handlers/, controllers/, routes/, middleware/, interceptors/ | 3.0 |
+| 1 | hooks/, triggers/, listeners/, subscribers/ | 3.0 |
+| 1 | .github/workflows/, gitlab-ci, Jenkinsfile | 3.0 |
+| 1 | .tf, .hcl, Dockerfile, docker-compose | 3.0 |
+| 1 | hooks.json, routes.json, pipeline.json | 3.0 |
+| 1 | Makefile | 3.0 |
+| 1 | agents/ | 3.0 |
+| 1 | hooks/scripts/ | 3.0 |
+| 2 (source code) | src/, lib/, app/, pkg/, internal/, core/ | 1.5 |
+| 2 | scripts/ | 1.5 |
+| 2 | skills/*.md, SKILL.md | 1.5 |
+| 3 (generic code) | .py, .ts, .js, .go, .rs, .java, .rb, .tsx, .jsx, .c, .cpp | 1.0 |
+| 4 (test code) | tests/, spec/, __tests__, e2e/, cypress/, playwright/ | 1.0 |
+| 5 (low-impact) | README | 0.5 |
+| 5 | CHANGELOG | 0.5 |
+| 5 | docs/, examples/, samples/ | 0.5 |
+| 5 | .md files | 0.5 |
+| 5 | .json, .yaml files | 0.5 |
+| 5 | LICENSE | 0.0 |
+
+**Scoring**: Start with highest-weight file match. If 3+ distinct file matches, add +1 breadth bonus. Cap at 3.
+
+### Integration Surface Detection
+
+If ANY of these keywords appear in the text, add +2: `integrate, connect, api, endpoint, service, system`
+
+Match all (first match of each keyword counts, not per-occurrence).
+
+---
+
+## Dimension: reversibility
+
+0 = trivially reversible, 3 = very hard to undo. Additive scoring.
+
+### Irreversibility Signals (push score UP)
+
+| Keyword | Weight | Label |
+|---------|--------|-------|
+| migrat* | +3 | data migration |
+| schema change | +3 | schema change |
+| schema migrat* | +3 | schema migration |
+| drop table | +3 | destructive DDL |
+| drop column | +3 | destructive DDL |
+| data transform* | +2 | data transformation |
+| breaking change | +3 | breaking change |
+| deprecat* | +2 | deprecation |
+| remove api | +3 | API removal |
+| rename api | +2 | API rename |
+| backward incompatible | +3 | backward incompatible |
+| delete | +1 | deletion |
+| remove | +1 | removal |
+| rename | +1 | rename |
+| restructur* | +2 | restructuring |
+| third party | +1 | third-party dependency |
+| external api | +2 | external API |
+| vendor | +1 | vendor dependency |
+
+### Reversibility Mitigators (push score DOWN, negative weights)
+
+| Keyword | Weight | Label |
+|---------|--------|-------|
+| feature flag | -2 | feature-flagged |
+| feature toggle | -2 | feature-flagged |
+| toggle | -1 | toggle available |
+| rollback | -1 | rollback mentioned |
+| revert | -1 | revert mentioned |
+| canary | -1 | canary deployment |
+| blue-green | -1 | blue-green deployment |
+| experiment | -1 | experimental |
+
+**Final score**: Sum all matched weights, then clamp to [0, 3].
+
+---
+
+## Dimension: novelty
+
+0 = routine/familiar, 3 = highly novel/uncertain. Sources are additive.
+
+### Explicit Novelty Keywords (break after first match)
+
+| Keyword | Weight | Label |
+|---------|--------|-------|
+| first time | +2 | first-time work |
+| new pattern | +2 | new pattern |
+| prototype | +2 | prototype |
+| proof of concept | +2 | proof of concept |
+| poc | +2 | proof of concept |
+| greenfield | +2 | greenfield |
+| from scratch | +2 | built from scratch |
+| never done | +2 | never done before |
+| unfamiliar | +1 | unfamiliar territory |
+| research | +1 | research needed |
+| spike | +1 | exploration spike |
+| experiment* | +1 | experimental |
+| evaluat* | +1 | evaluation |
+
+### Cross-Domain Bonus (applies after keyword check)
+
+| Condition | Weight |
+|-----------|--------|
+| 3+ detected signal categories | +2 |
+| 2 detected signal categories | +1 |
+
+### Ambiguity Bonus
+
+| Condition | Weight |
+|-----------|--------|
+| Input is ambiguous | +1 |
+
+**Final score**: Sum all components, clamp to [0, 3].
+
+---
+
+## Dimension: test_complexity
+
+Detects test strategy scope and integration test setup needs. All matches additive.
+
+| Keyword | Weight |
+|---------|--------|
+| end-to-end test* | +2 |
+| e2e test* | +2 |
+| integration test* | +2 |
+| test fixture* | +1 |
+| test strateg* | +2 |
+| playwright | +2 |
+| cypress | +2 |
+| mock service* | +1 |
+| contract test* | +2 |
+| test coverag* | +1 |
+| acceptance test* | +2 |
+| performance test* | +2 |
+| load test* | +2 |
+| ci pipeline | +1 |
+| test suite* | +1 |
+| unit test* | +1 |
+| test setup | +1 |
+| test infrastr* | +2 |
+
+**Final score**: Sum all, clamp to [0, 3].
+
+---
+
+## Dimension: documentation
+
+Detects API docs, user guides, ADR requirements. All matches additive.
+
+| Keyword | Weight |
+|---------|--------|
+| openapi | +2 |
+| swagger | +2 |
+| api doc* | +2 |
+| adr | +2 |
+| architecture decision | +2 |
+| decision record | +2 |
+| user guide* | +2 |
+| migration guide* | +2 |
+| changelog | +1 |
+| readme | +1 |
+| runbook | +2 |
+| playbook | +2 |
+| docstring* | +1 |
+| api reference* | +2 |
+| technical doc* | +2 |
+| annotate | +1 |
+| document the | +1 |
+| publish doc* | +2 |
+
+**Final score**: Sum all, clamp to [0, 3].
+
+---
+
+## Dimension: coordination_cost
+
+Detects cross-domain dependencies, specialist handoffs, review requirements.
+
+| Keyword | Weight |
+|---------|--------|
+| coordinate with | +2 |
+| cross-team | +2 |
+| cross team | +2 |
+| specialist review | +2 |
+| cross-domain | +2 |
+| handoff | +1 |
+| hand-off | +1 |
+| multiple team* | +2 |
+| security review | +2 |
+| legal review | +2 |
+| compliance review | +2 |
+| sign-off | +1 |
+| approval required | +2 |
+| stakeholder review | +2 |
+| cross-functional | +2 |
+| review board | +2 |
+| change request | +1 |
+| change control | +2 |
+
+**Final score**: Sum all, clamp to [0, 3].
+
+---
+
+## Dimension: operational
+
+Detects deployment, migration, rollback operational needs.
+
+| Keyword | Weight |
+|---------|--------|
+| deploy* | +1 |
+| zero-downtime | +3 |
+| blue-green | +2 |
+| canary deploy* | +2 |
+| rollback plan | +3 |
+| database migration | +3 |
+| schema migration | +3 |
+| migration script* | +2 |
+| deployment window | +2 |
+| ops monitor* | +2 |
+| health check* | +1 |
+| on-call | +2 |
+| runbook | +2 |
+| incident response | +3 |
+| production deploy* | +2 |
+| feature flag* | +1 |
+| infra change* | +2 |
+| config change* | +1 |
+| environment variable* | +1 |
+
+**Final score**: Sum all, clamp to [0, 3].

package/skills/workflow/refs/scoring-rubric.md

@@ -0,0 +1,49 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Scoring Rubric (HISTORICAL — v5)
+
+**Status**: Deprecated. This file describes the v5 weighted-sum complexity-scoring
+algorithm that lived in `scripts/crew/smart_decisioning.py`. The script was deleted
+in the v6 rebuild (Gate 4 Phase 2, #428).
+
+**v6 replacement**: the `wicked-garden:propose-process` facilitator rubric
+replaces this scoring model with a 9-factor judgment read (reversibility,
+blast_radius, compliance_scope, user_facing_impact, novelty, scope_effort,
+state_complexity, operational_risk, coordination_cost) plus a judgment-driven 0-7
+complexity estimate. See:
+
+- `skills/propose-process/SKILL.md`
+- `skills/propose-process/refs/output-schema.md`
+
+This file is kept as a historical reference for anyone reading v5 commit archeology
+or comparing v5 vs v6 behaviour. Do NOT use the composite-score formula below as a
+current contract — it does not reflect v6 behaviour.
+
+---
+
+## v5 Composite Complexity Score (historical)
+
+The v5 composite score combined 8 weighted components (impact, risk_premium, scope,
+coordination, test_complexity, novelty, file_impact, archetype_bonus) clamped to
+[0, 7]. The algorithm relied on `SIGNAL_KEYWORDS` regex matching + archetype
+detection + keyword-to-specialist mapping.
+
+For the full historical algorithm, refer to the v5.2.0 tag:
+
+```bash
+git show v5.2.0:scripts/crew/smart_decisioning.py
+```
+
+## v6 replacement summary
+
+| v5 concept | v6 equivalent |
+|---|---|
+| `SIGNAL_KEYWORDS` (18 categories) | 9 factors in facilitator rubric Step 3 |
+| Complexity 0-7 via weighted sum | Judgment-driven 0-7 in rubric Step 8 |
+| `routing_lane` (auto/fast/standard) | `rigor_tier` (minimal/standard/full) in Step 7 |
+| `SPECIALIST_FALLBACKS` static map | Direct frontmatter read in rubric Step 4 |
+| 12 archetype classes | Implicit in Step 1 "summarize surface area" |
+
+See `scripts/ci/gate4-cutover-matrix.md` for the full coverage matrix.