wicked-garden 12.27.0

package/skills/archetype/refs/modernize.md

@@ -0,0 +1,187 @@
+# modernize — discover / extract / blueprint / transform / parity / cutover
+
+For porting a **legacy codebase to a new stack** (a language/framework/runtime
+jump, a rehost/replatform, a rewrite from the working code as the spec). This is
+NOT `migrate` — `migrate` is in-place expand-contract shape change on a *running*
+system. `modernize` reverse-engineers an estate, blueprints a target, transforms
+with leverage, and proves parity before cutting over.
+
+This archetype is a **general modernization steering shape**. It is self-contained
+and **composes the general `code-modernization` skills** for the heavy lifting —
+it does not own a parallel lifecycle, and it routes the same rigor/gate discipline
+garden already preaches into those skills.
+
+## Phase shape
+
+| Phase     | Goal                                                              |
+|-----------|-------------------------------------------------------------------|
+| discover  | Map the estate; resolve the legacy **stack class** via the registry. |
+| extract   | Pull out the testable business rules (what it does, not how).     |
+| blueprint | Decide the target-state architecture. Decision matrix, not prose. |
+| transform | Codemod / regenerate with leverage. Deterministic before AI.      |
+| parity    | Prove old ≡ new on identical inputs. Differential equivalence.    |
+| cutover   | Switch to the new stack. **Hard gate** — staged, parity-proved.   |
+
+## Produces
+
+- **Modernization blueprint**: the target-state architecture (target stack,
+  package/module structure, API surface, data model) + the recorded technique
+  choice per transform wave.
+- **Parity proof**: an executable, re-derivable equivalence check — old vs new
+  on identical seeded inputs assert identical outputs (the trust, not review).
+
+The cutover gate **re-derives** these via `wicked-loom` (`scripts/qe/vault_gate.py`
+shells `wicked-loom gate`, which shells `wicked-vault cross-check`): the parity
+harness is re-run and the blueprint post-condition re-checked, never trusting a
+self-asserted "ported fine". wicked-loom (the gate engine) and wicked-vault (the
+evidence backend) are **required** peers (installed by `/wicked-garden:setup`); if
+loom is unresolvable — or the vault behind it absent — the gate **fails closed**
+(`gate: "unavailable"`, `satisfied: false`) rather than self-asserting a PASS.
+Because `cutover` is a HARD gate, the gate also demands an **independent
+attestation**: an evaluator who is **not** the modernizer confirms the parity proof
+and blueprint are adequate (recorded via `wicked-vault:analyze-evidence`), and the
+gate fails closed on a self-grade.
+
+## HITL
+
+`hard:cutover-gate` — cutover is a hard gate. Don't cut over to the new stack
+without explicit user approval AND a green pre-cutover checklist (parity proved on
+real seeded data, rollback path to the legacy system tested, traffic plan staged).
+
+## Ground in the repo's method first
+
+Before you discover, check for **wicked-understanding** repo playbooks (the opt-in
+"how to work in THIS repo" layer). A modernization lives or dies on repo-specific
+wiring — the build/run command, where the seam between old and new lives, the
+deploy/rollback command. If its skills are present, **load the matching playbook**
+and let it name those points instead of rediscovering them mid-cutover. Absent?
+Discover it the usual way — and consider
+`npx skills add mikeparcewski/wicked-understanding --all`.
+
+## How to run
+
+### discover
+
+1. Survey the legacy estate: entry points, modules, data stores, external
+   contracts. Use `code-modernization:modernize-assess` for the structural read
+   and `code-modernization:modernize-brief` to frame scope + risk.
+2. **Resolve the stack class — DO NOT fabricate a playbook.** Read the dispatch
+   truth in `.claude-plugin/stack-registry.json` via the reader:
+   ```bash
+   sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+     "${CLAUDE_PLUGIN_ROOT}/scripts/crew/stack_registry.py" \
+     resolve --stack <stack-id>
+   ```
+   - `status: wired` (exit 0) → the printed `dispatch` names the `blueprint`,
+     `transform`, and `validate` skills/gate to use in the phases below.
+   - unknown / `planned` / `none` (exit 3) → the reader returns a **capability-gap
+     task** and emits `wicked.modernize.stack_gap`. **STOP.** Create that task
+     (`TaskCreate`) and surface the gap to the user — never invent a transform for a
+     stack the system can't actually handle. This is the fail-closed ETHOS as
+     dispatch data: an honest "we don't handle this yet" beats a fabricated port.
+   - When the legacy stack genuinely is not in the registry but IS general
+     (any language → modern target), use the `generic-cross-stack` entry, which is
+     wired to the general `code-modernization` skills.
+
+### extract
+
+1. Mine the domain logic — calculations, validations, policies — into testable
+   Given/When/Then specs with `code-modernization:modernize-extract-rules`.
+   Separate *what the business requires* from *how the old code happened to do it*.
+2. These extracted rules become the parity oracle: the new stack must satisfy the
+   same rules. Pin each rule so the parity phase has a bar to check.
+
+### blueprint
+
+1. Decide the **target-state architecture** with `code-modernization:modernize-reimagine`
+   (the registry `blueprint` field names this for the resolved stack). Capture it
+   as a **decision matrix, not a narrative**: target stack + version (pin, don't
+   "latest"), module/package structure, API surface, data model, the engines/tools.
+2. Write the blueprint to `docs/modernization/{slug}-blueprint.md` and declare the
+   re-derivable contract early so the cutover gate has a bar. If a vault is
+   resolvable (`scripts/qe/vault_gate.py resolve` → `available: true`):
+   `wicked-vault init` then
+   `wicked-vault declare-contract --scope <scope> --phase modernize --spec contract.json`.
+   `required_evidence` must pin `parity-proof` to a deterministic verifier
+   (`exit_code_eq:0` on the differential harness). Skip silently if no vault.
+
+### transform
+
+1. Transform **with leverage, not an agent-grind** — follow
+   `wicked-garden:engineering:large-scale-migration` (MAP → TRANSFORM → GATE) and
+   its ranked techniques menu: **prefer the lowest-numbered technique that fully
+   covers the task** (deterministic recipe/codemod before AI-assisted waves), and
+   **record the chosen technique** per wave. Drive the bulk through a deterministic
+   codemod/codegen; touch only the self-flagged residue by hand.
+2. Run the resolved `transform` skills (`code-modernization:modernize-map` then
+   `code-modernization:modernize-transform`) over the estate.
+3. **Don't grandfather.** No exemptions, no "left raw with a TODO" — an exemption
+   preserves the exact legacy case the modernization exists to remove.
+
+### parity
+
+1. Prove **old ≡ new** on identical seeded inputs (differential equivalence) — the
+   parity proof is the trust, not a diff review. Seed broadly; an empty fixture
+   passes trivially and lies.
+2. Harden the result with `code-modernization:modernize-harden` (security/CVEs,
+   error handling) before it carries traffic.
+3. Record the parity proof as re-derivable evidence (vault present; **wicked-vault
+   ≥ 0.4.0**):
+   `wicked-vault record --scope <scope> --phase modernize --claim parity-proof
+   --kind differential --source "<the differential harness command>"
+   --criteria "old(input) == new(input) on seeded data" --verifier exit_code_eq:0
+   --actor "${WICKED_VAULT_ACTOR:-garden-prove}" --run`. The **`--actor`** is
+   mandatory because `cutover` is a hard gate: vault ≥ 0.4.0 refuses an `attest`
+   over weak/ambient-identity evidence, so without an explicit actor the
+   independent attestation fails closed and cutover can never be gated PASS. The
+   `--run` captures the real exit code now and the gate re-runs it later — a claim
+   you can't re-derive is not evidence. No vault → fall back to
+   `evidence_tracker.py claim`.
+
+### cutover
+
+1. **Pre-cutover checklist**:
+   - Parity proved on real seeded data. (`✓` or block.)
+   - Rollback path to the legacy system tested.
+   - Traffic plan staged (canary first, not big-bang).
+   - Monitoring + alerts cover the new stack.
+2. **Gate before any switch** — don't self-assert the checklist. Run the
+   produces-gate WITH judgment:
+   `scripts/qe/prove.py parity-proof --by "<command>" --scope <scope> --phase modernize --with-attestations`
+   (frictionless, single claim — re-derive, don't assert) — or the full multi-claim
+   contract via
+   `scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase modernize --with-attestations`.
+   `--with-attestations` keeps this gate `UNATTESTED`/`REJECT` until an INDEPENDENT
+   evaluator (not the doer) runs `wicked-vault attest <artifact-id> --opinion pass`
+   — find it via `wicked-vault list --scope <scope> --phase modernize`. The doer's
+   own evidence cannot satisfy a hard gate. (exit 0 = satisfied.) A REJECT means the
+   parity proof doesn't clear its contract — fix the work, not the claim. An
+   `unavailable` verdict means the required vault isn't installed — run
+   `/wicked-garden:setup`. **No cutover on a fail-closed verdict.**
+3. **Cutover staged**: canary the new stack, watch, ramp. Hand the rollout tail to
+   the `ship` archetype if blast radius warrants.
+4. The cutover gate is HARD — explicit user "go" before each ramp step.
+5. If anything looks off post-cutover: **roll back to the legacy system first,
+   debug second.**
+
+## When to stop
+
+Cutover may only proceed when the produces-gate is satisfied — check it, don't
+self-assert it (see the cutover step). Modernize is done when traffic is on the new
+stack, parity has soaked, and the blueprint matches what shipped. Hand off to
+`review` for a post-modernization audit when the change touched compliance or
+revenue surface.
+
+## Anti-patterns
+
+- **Don't fabricate a playbook for an unhandled stack.** If the registry says
+  `planned`/`none`/unknown, emit the gap task and stop. A fabricated port is the
+  exact failure the fail-closed ETHOS exists to prevent.
+- **Don't hand-edit the bulk.** Modernization is MAP → TRANSFORM → GATE, not "fan
+  out N agents to rewrite each file." Deterministic transform first; AI only for the
+  residue, eval-gated.
+- **Don't trust build-green as parity.** Build/test green ≠ behavior preserved —
+  *especially* for any LLM/agent surface. Prove `old ≡ new` on real inputs.
+- **Don't big-bang the cutover.** Canary, ramp, soak — same discipline as `migrate`.
+- **Don't skip rollback testing.** A path back to the legacy system you haven't
+  exercised is not a rollback path.

package/skills/archetype/refs/review.md

@@ -0,0 +1,145 @@
+# review — independent assessment with hard verdict
+
+When an artifact (code, design, spec, incident response) needs an
+external quality check. Produces a verdict: APPROVE / CONDITIONAL /
+REJECT, with a remediation list when not APPROVE.
+
+## Phase shape
+
+| Phase                  | Goal                                       |
+|------------------------|--------------------------------------------|
+| scope                  | Name what's being reviewed and what isn't. |
+| assess                 | Apply the relevant rubric / quality bar.   |
+| findings               | List what's wrong, what's missing, what's good (in that order). |
+| remediate-or-accept    | Pick: fix the findings, accept them with a CONDITIONAL, or reject. |
+
+## Produces
+
+- **Verdict**: `APPROVE` / `CONDITIONAL` / `REJECT`.
+- **Remediation list**: each item has an id, severity, and a concrete
+  action. Empty when APPROVE.
+
+The final-verdict gate **re-derives** these via `wicked-loom` (`scripts/qe/vault_gate.py` shells `wicked-loom gate`, which shells `wicked-vault cross-check`): the verdict JSON is re-validated and the
+remediation-list structure re-checked, never trusting a self-asserted
+"done". wicked-loom (the gate engine) and wicked-vault (the evidence backend) are **required** peers (installed by `/wicked-garden:setup`); if loom is unresolvable — or the vault behind it absent — the gate **fails closed** (`gate: "unavailable"`, `satisfied: false`) rather than passing
+on a claim alone. Because final-verdict is a **hard** gate, the contract
+also demands an **independent attestation** — the verdict must be signed
+off by an evaluator that is NOT the worker who did the reviewed work
+(anti-self-grade, G10). `--no-require` opts a throwaway/low-rigor run
+back to the doctrine-light claim-only path.
+
+## HITL
+
+`hard:final-verdict` — the verdict is a hard gate. Auto-approve is
+banned (banned-reviewer enforcement applies — `auto-approve-*`,
+`fast-pass`, `just-finish-auto` are rejected at the gate).
+
+## How to run
+
+### scope
+
+1. Name what's in scope: this PR, this commit, this design doc.
+2. Name what's out of scope: don't drift into adjacent code that wasn't
+   changed.
+3. Pick the rubric: code review uses R1–R6; design review uses
+   testability + boundary clarity; spec review uses SMART+T.
+4. If a vault is resolvable (`scripts/qe/vault_gate.py resolve` →
+   `available: true`), declare the re-derivable contract for this phase
+   so the final-verdict gate has a bar to check against:
+   `wicked-vault init` (once per repo) then
+   `wicked-vault declare-contract --scope <scope> --phase review --spec contract.json`.
+   `required_evidence` should pin `verdict` to `exit_code_eq:0` on a
+   verdict-schema validation (`scripts/qe/verdict_schema.py`) and
+   `remediation-list` to a presence/structure `regex_match`. Because
+   this is a **hard** gate, the contract also requires a passing
+   independent `opinion_attestation` (the judgment tier). Skip silently
+   if no vault.
+
+### assess
+
+1. Apply the rubric. Take notes; don't write the findings yet.
+2. Use the right specialist subagent — `pr-review-toolkit:code-reviewer`,
+   `wicked-garden:crew:reviewer`, `wicked-garden:qe:semantic-reviewer`,
+   `wicked-garden:engineering:solution-architect`, etc. Match the artifact
+   to the specialist.
+3. For high-stakes reviews, run a council via
+   `wicked-garden:jam:council` — independent multi-model verdicts
+   catch what a single reviewer misses.
+
+### findings
+
+1. Write the findings list. Each finding:
+   - `id`: F-1, F-2, ...
+   - `severity`: blocker / major / minor / nit
+   - `claim`: what's wrong, in one sentence.
+   - `fix`: a concrete action.
+2. Order: blockers first, then major, then minor. Nits last (or
+   collapsed into a "nit-pile" comment).
+
+### remediate-or-accept
+
+1. Decide the verdict:
+   - **APPROVE**: no blockers, no majors, the code is shippable as-is.
+   - **CONDITIONAL**: blockers/majors that have a clear fix path. Each
+     condition gets a row in the conditions manifest so the next
+     archetype (build / migrate / etc.) can pin it to the resolution
+     artifact.
+   - **REJECT**: fundamental issues. Don't bandaid; send back to the
+     author.
+2. Write the verdict JSON. Validate with `scripts/qe/verdict_schema.py`
+   — confirms shape (verdict enum, reviewer not banned, score in
+   range, invariants per verdict type).
+3. Sanitize free-text fields with `scripts/qe/content_sanitizer.py`
+   to strip prompt-injection patterns from reasons / findings /
+   condition descriptions before persisting.
+4. Append to the audit log with `scripts/qe/verdict_audit.py append`
+   so the verdict is replayable.
+   Then record both produces as re-derivable evidence (vault present;
+   **wicked-vault ≥ 0.4.0**):
+   `wicked-vault record --scope <scope> --phase review --claim verdict
+   --kind verdict --source "<verdict.json>" --criteria "<the bar>"
+   --verifier exit_code_eq:0 --actor "${WICKED_VAULT_ACTOR:-garden-prove}"
+   --run` where the run is `scripts/qe/verdict_schema.py <verdict.json>`,
+   and a second `record` for `--claim remediation-list ... --verifier
+   regex_match:<pattern> --actor "${WICKED_VAULT_ACTOR:-garden-prove}"`.
+   The **`--actor`** is mandatory for a hard gate: vault ≥ 0.4.0 refuses an
+   `attest` over evidence recorded under a weak/ambient identity
+   (`created_by_source='env-user'`), so without an explicit actor the
+   independent sign-off below fails closed and the gate can never reach
+   PASS. The `--run` captures the validator's real exit code now and the
+   gate re-runs it later — a claim you can't re-derive is not evidence. No
+   vault → fall back to `evidence_tracker.py claim`.
+   Then have an **independent** evaluator sign off via the
+   `wicked-vault:analyze-evidence` skill, which records an
+   `opinion_attestation` over the frozen criteria. The evaluator must
+   NOT be the agent that did the reviewed work — the gate fails closed
+   on a self-grade. This is the "never let work self-grade its own done"
+   guarantee.
+5. On CONDITIONAL: initialise the conditions manifest with
+   `scripts/qe/conditions_manifest.py init --from-verdict <path>`.
+   The downstream archetype calls `mark` as it satisfies each one.
+6. Don't soften — REJECT means REJECT.
+
+## When to stop
+
+Review is done when the produces-gate is satisfied. Check the gate —
+don't self-assert it:
+`scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase review --with-attestations` (frictionless, single claim — re-derive, don't assert) — or the full multi-claim contract via `scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase review --with-attestations` **`--with-attestations`** keeps this gate `UNATTESTED`/`REJECT` until an INDEPENDENT evaluator (not the doer) runs `wicked-vault attest <artifact-id> --opinion pass` — find it via `wicked-vault list --scope <scope> --phase review`. The doer's own evidence cannot satisfy a hard gate.
+(exit 0 = satisfied). This is a re-derived PASS over the declared
+contract. `--with-attestations` makes the gate require a passing
+independent `opinion_attestation` recorded via the
+`wicked-vault:analyze-evidence` skill, where the evaluator ≠ the agent
+that did the reviewed work — it fails closed on a self-grade. A REJECT
+means the recorded evidence does not clear its contract — fix the work,
+not the claim. An `unavailable` verdict means the required vault isn't
+installed — run `/wicked-garden:setup`. Then hand off to `build` (when
+fixes are needed before ship) or `ship` (when APPROVE).
+
+## Anti-patterns
+
+- **Don't sandbag with nits.** If the only findings are nits, APPROVE.
+  Don't gate on cosmetic preferences.
+- **Don't write a fix during review.** The reviewer's job is the
+  verdict; the fix is the author's.
+- **Don't auto-approve for speed.** Banned-reviewer enforcement exists
+  for a reason. Time pressure is not a CONDITIONAL.

package/skills/archetype/refs/ship.md

@@ -0,0 +1,117 @@
+# ship — progressive rollout with widening blast radius
+
+For changes that are already built and tested but need controlled exposure
+to production. Each phase widens blast radius; gates are explicit ramps.
+
+## Phase shape
+
+| Phase  | Goal                                                       |
+|--------|------------------------------------------------------------|
+| canary | Expose to a small slice (1–5% traffic, internal only, single region). |
+| ramp   | Widen progressively (10% → 25% → 50%) with monitoring at each step. |
+| full   | 100% exposure. Production traffic on the new path.         |
+| soak   | Keep the new path running unchanged for 24–72h. Watch the long tail. |
+
+## Produces
+
+- **Rollout verdict**: APPROVE / ROLLBACK / HOLD at each gate.
+- **SLO snapshot**: error rate, latency, saturation at each phase
+  boundary, compared to the pre-rollout baseline.
+
+The ramp gate **re-derives** these via `wicked-loom` (`scripts/qe/vault_gate.py` shells `wicked-loom gate`, which shells `wicked-vault cross-check`): the SLO snapshot's verifier is re-run and
+the rollout-verdict command's exit code re-checked, never trusting a
+cached "looked clean". Because live observation verifiers
+(`http_status_eq`, `pr_check_status`) aren't implemented yet, **capture
+the SLO metrics to a snapshot file** and verify with `jq_pred` over that
+captured JSON — deterministic and re-derivable, not a one-shot live
+probe. wicked-loom (the gate engine) and wicked-vault (the evidence backend) are **required** peers (installed by `/wicked-garden:setup`); if loom is unresolvable — or the vault behind it absent — the gate **fails closed** (`gate: "unavailable"`, `satisfied: false`) rather than
+self-asserting an APPROVE. `--no-require` opts a throwaway/low-rigor
+rollout back to the doctrine-light claim-only path.
+
+## HITL
+
+`discrete:ramp-gates` — each phase boundary is a discrete gate. Auto-pass
+is allowed when SLO criteria are clean and prior phases passed; auto-fail
+(rollback) is allowed when SLO criteria breach. **Manual override is
+always available.** Don't bypass the gate; widen the criteria.
+
+## How to run
+
+### canary
+
+1. Define the slice: which traffic, what %, what region.
+2. Define the SLO criteria: error rate threshold, latency p95/p99
+   threshold, saturation threshold. Pull baseline from the last 7d.
+3. If a vault is resolvable
+   (`scripts/qe/vault_gate.py resolve` → `available: true`), declare the
+   re-derivable contract for this rollout so every ramp gate has a bar to
+   check against: `wicked-vault init` (once per repo) then
+   `wicked-vault declare-contract --scope <scope> --phase ship --spec
+   contract.json`. `required_evidence` pins `slo-snapshot` (kind
+   `metrics-snapshot`) to a `jq_pred` verifier over a captured metrics
+   JSON file (e.g. `.error_rate <= 0.01 and .p95_ms < 250`) and
+   `rollout-verdict` to `exit_code_eq:0` on the canary/ramp check command.
+   Skip silently if no vault.
+4. Deploy. Watch for at least 1 hour OR 1000 requests, whichever is
+   longer.
+5. Compare to baseline. If clean: pass to ramp. If degraded:
+   **rollback immediately**. Don't tune in production.
+
+### ramp
+
+1. Step the ramp at 10% → 25% → 50%. Don't skip steps.
+2. At each step, the SLO criteria from canary still apply. New metrics
+   may surface as load scales (saturation, queue depth, lock contention).
+3. Each step gets at least 30 minutes of soak before stepping up.
+4. At each step, **capture fresh SLO metrics to a snapshot file** (don't
+   probe live), then record both produces as re-derivable evidence
+   (vault present):
+   `wicked-vault record --scope <scope> --phase ship --claim slo-snapshot
+   --kind metrics-snapshot --artifact <metrics.json> --criteria "<the
+   SLO bar>" --verifier 'jq_pred:.error_rate <= 0.01 and .p95_ms < 250'`
+   and `wicked-vault record --scope <scope> --phase ship --claim
+   rollout-verdict --kind check --source "<the canary/ramp check
+   command>" --criteria "verdict is APPROVE" --verifier exit_code_eq:0
+   --run`. The `jq_pred` re-runs against the captured snapshot and
+   `--run` re-checks the verdict command's real exit code — a claim you
+   can't re-derive is not evidence. Each ramp step supersedes the prior
+   snapshot, so the cross-check runs against fresh captured evidence at
+   every step. No vault → fall back to `evidence_tracker.py claim`.
+5. The `ship` archetype owns the canonical rollout playbook.
+
+### full
+
+1. Step from 50% → 100%. The same SLO criteria apply.
+2. Tag the release. Publish a one-line "shipped X" note for visibility.
+
+### soak
+
+1. Watch for 24–72h depending on the change's criticality.
+2. The long tail surfaces issues canary missed: data drift, slow leaks,
+   off-hours load patterns, third-party rate limits.
+3. Soak ends when there's no anomaly outside the baseline noise band.
+
+## When to stop
+
+Each ramp step advances only when the produces-gate is satisfied — check
+it, don't self-assert it:
+`scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase ship` (frictionless, single claim — re-derive, don't assert) — or the full multi-claim contract via `scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase ship`
+(exit 0 = satisfied). This is a re-derived APPROVE over the declared
+contract, re-run at **every** ramp step against the fresh captured
+snapshot. A REJECT means the recorded SLO snapshot doesn't clear its
+budget — **rollback**, don't widen. An `unavailable` verdict means the
+required vault isn't installed — run `/wicked-garden:setup`.
+
+Ship is done when soak is clean. Hand off to `review` for a post-rollout
+audit when the change was high-blast-radius, or close out otherwise.
+
+## Anti-patterns
+
+- **Don't skip ramp.** 0% → 100% is not a rollout; it's a deploy.
+- **Don't auto-pass under degraded SLOs.** "It's only slightly worse"
+  has rolled out exactly the kind of regression rollouts are meant to
+  catch.
+- **Don't ship and walk.** Soak is part of ship. A rollout that ends at
+  full is incomplete.
+- **Don't treat ramp as a build phase.** No code changes during ramp.
+  Tuning happens in a follow-up build → ship cycle.

package/skills/archetype/refs/specify.md

@@ -0,0 +1,108 @@
+# specify — turn an ask into testable acceptance criteria
+
+When the implementation path is clear-ish but the success criteria are
+fuzzy. Produces SMART acceptance criteria — Specific, Measurable,
+Achievable, Relevant, Time-bound — that downstream `build` can verify.
+
+## Phase shape
+
+| Phase    | Goal                                                       |
+|----------|------------------------------------------------------------|
+| elicit   | Surface the user's intent through targeted questions.      |
+| structure | Convert intent into REQ-/AC- numbered acceptance criteria.|
+| validate | Confirm with the user that the ACs match their intent.    |
+
+## Produces
+
+- **SMART acceptance criteria** in the form `AC-N: when X, then Y`.
+- One-line invariants: "A response time over 500ms is a regression".
+- Optional: a `requirements.md` artifact in the project dir.
+
+The validate gate **re-derives** this via `wicked-loom` (`scripts/qe/vault_gate.py` shells `wicked-loom gate`, which shells `wicked-vault cross-check`): the recorded `smart-acceptance-criteria`
+artifact is re-hashed and its structural verifier re-run, never trusting
+a self-asserted "the ACs are testable". wicked-loom (the gate engine) and wicked-vault (the evidence backend) are **required** peers (installed by `/wicked-garden:setup`); if loom is unresolvable — or the vault behind it absent — the gate **fails closed** (`gate: "unavailable"`, `satisfied: false`) rather
+than claiming a PASS. `--no-require` opts a throwaway/low-rigor run back
+to the doctrine-light claim-only path. This is a discrete (light) gate —
+the deterministic check proves *shape* (each AC is measurable); if the
+AC *quality* needs an independent sign-off, the judgment tier
+(`wicked-vault analyze-evidence` / `--with-attestations`) is available.
+
+## HITL
+
+`discrete:validate-gate` — the validate phase is a hard checkpoint. Don't
+proceed past validate without explicit user agreement on the AC set.
+
+## How to run
+
+### elicit
+
+1. Use `/wicked-garden:product:elicit` if requirements analysis is needed,
+   or jump in directly when the surface is small.
+2. Ask 3–5 questions. Each should be answerable in one line and target a
+   specific dimension: scope, success metric, failure mode, edge case,
+   non-goal.
+3. **Don't ask open-ended "tell me more about X".** Force the user to pick
+   between concrete options.
+
+### structure
+
+1. If a vault is resolvable
+   (`scripts/qe/vault_gate.py resolve` → `available: true`), declare the
+   re-derivable contract for this phase so the validate gate has a bar to
+   check against: `wicked-vault init` (once per repo) then
+   `wicked-vault declare-contract --scope <scope> --phase specify --spec contract.json`
+   — `required_evidence` should pin `smart-acceptance-criteria`
+   (kind `spec-doc`) to a `regex_match` verifier proving the criteria are
+   testable/measurable (e.g. each AC carries a measurable assertion or a
+   Given/When/Then shape). Skip silently if no vault.
+2. Convert each elicited fact into one acceptance criterion: `AC-N: when
+   <trigger>, then <observable>`.
+3. Add invariants for things that should NOT change: `INV-N: <thing> must
+   stay under <threshold>`.
+4. Keep ACs minimal — 3–7 is the sweet spot. More than 10 means you're
+   treating ACs as design.
+5. Record the AC artifact as re-derivable evidence (vault present;
+   **wicked-vault ≥ 0.4.0**):
+   `wicked-vault record --scope <scope> --phase specify
+   --claim smart-acceptance-criteria --kind spec-doc
+   --artifact <path/to/requirements.md>
+   --criteria "<the testability bar>"
+   --verifier regex_match:'(?im)^(AC|INV)-\d+:'
+   --actor "${WICKED_VAULT_ACTOR:-garden-prove}" --run`. The **`--actor`**
+   records under an explicit identity so that if AC quality needs an
+   independent sign-off (the optional `--with-attestations` judgment tier
+   above), vault ≥ 0.4.0 will let that attestation through instead of
+   refusing it as a weak/ambient identity. The verifier re-runs against
+   the artifact later — a claim you can't re-derive is not evidence. No
+   vault → fall back to the claim-only path.
+
+### validate
+
+1. Show the user the AC list.
+2. Ask: "is anything missing? is anything wrong? is anything overspecified?"
+3. **Hard gate**: do not exit specify until the user explicitly approves the
+   AC set. "Looks good" is enough; silence is not.
+4. If they want changes, loop back to elicit or structure as appropriate.
+
+## When to stop
+
+Specify is done when the user has signed off on the AC list AND the
+produces-gate is satisfied. Check the gate — don't self-assert it:
+`scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase specify` (frictionless, single claim — re-derive, don't assert) — or the full multi-claim contract via `scripts/qe/vault_gate.py gate <project_dir> --scope <scope> --phase specify`
+(exit 0 = satisfied). This is a re-derived PASS over the declared
+contract: the AC artifact is re-hashed and its structural verifier
+re-run. A REJECT means the recorded ACs don't clear the testability bar —
+fix the criteria, not the claim. An `unavailable` verdict means the
+required vault isn't installed — run `/wicked-garden:setup`. Then hand off
+to `build` (when the next step is implementation), `decide` (when you've
+uncovered competing options), or `explore` (when the act of writing ACs
+revealed the problem isn't well understood).
+
+## Anti-patterns
+
+- **Don't write design inside ACs.** "AC-1: implementation uses Redis"
+  is a design choice, not an acceptance criterion. Use `decide` for that.
+- **Don't merge multiple criteria into one.** Split them so each is
+  individually testable.
+- **Don't auto-pass the validate gate.** The whole point is the user
+  agrees this is what they wanted.

package/skills/archetype/refs/triage.md

@@ -0,0 +1,62 @@
+# triage — classify and route
+
+The entry archetype. Every prompt that doesn't already carry an archetype tag
+starts here. Triage is not a workflow on its own — it's a routing decision.
+
+## Phase shape
+
+| Phase    | Goal                                          |
+|----------|-----------------------------------------------|
+| classify | Pick the right archetype (or set of archetypes) and hand off. |
+
+## Produces
+
+- A routing decision: which archetype(s) this prompt belongs in.
+
+## HITL
+
+`none` — fully automated. The detector runs, the directive emits, the
+agent picks up the playbook from there.
+
+## How to run
+
+1. **Read the prompt.** What is the user actually asking for?
+2. **Run the detector.** Call `scripts/crew/archetypes_v11.py detect` with
+   the prompt and any known signals.
+3. **Inspect the matches.**
+   - Single high-confidence match (≥ 0.7): hand off to that archetype's
+     playbook.
+   - Multiple medium matches (0.5–0.7): pick the one with the strongest
+     evidence; if you can't, ask the user which shape they want.
+   - Only triage matched: ask a clarifying question naming what's
+     missing — usually the work isn't ambiguous, the prompt is.
+
+## When to stop in triage
+
+Triage exits as soon as you've named the next archetype. Do **not**
+do work inside triage — every minute spent here is a minute the
+real work isn't moving.
+
+## Examples
+
+| Prompt                                            | Routes to            |
+|---------------------------------------------------|----------------------|
+| "implement caching for the dashboard"             | build                |
+| "drop legacy_id column"                           | build + migrate      |
+| "checkout is down — 5xx spiking"                  | incident             |
+| "redis or memcached for sessions?"                | decide               |
+| "review the new auth middleware"                  | review               |
+| "what should we do about rate limiting?"          | explore              |
+| "write acceptance criteria for the export"        | specify              |
+| "kick off canary for the pricing change"          | ship                 |
+| "fix typo in README"                              | (suppressed — simple-edit, no archetype) |
+
+## Anti-patterns
+
+- **Don't classify into a tier.** "standard rigor" is not an archetype.
+  Triage picks a *shape*, not a depth dial.
+- **Don't stack triage onto an active archetype.** If the user is already
+  inside `build`, a follow-up "and also run the migration" doesn't restart
+  triage — it adds `migrate` as a co-archetype.
+- **Don't write code in triage.** If your hands are at the keyboard,
+  you've already left triage.