wicked-garden 12.27.0

package/skills/archetype/refs/decide.md

@@ -0,0 +1,117 @@
+# decide — pick between options with an ADR
+
+When 2+ paths are viable AND the choice is load-bearing (changing it later
+is expensive). Produces an ADR-shaped artifact that records the chosen
+path and the reasons.
+
+## Phase shape
+
+| Phase   | Goal                                                       |
+|---------|------------------------------------------------------------|
+| brief   | One-paragraph framing: the problem, the stakes, the constraints. |
+| options | 2–4 named alternatives, each with a one-paragraph description. |
+| score   | Qualitative scoring on the dimensions that matter for this decision. |
+| record  | Write the ADR. Pick a path. Note the trade-offs you accepted. |
+
+## Produces
+
+- An **ADR** (Architecture Decision Record) at `docs/decisions/{N}-{slug}.md`
+  or `docs/adr/{N}-{slug}.md`, following whatever ADR convention the repo
+  uses. New repos: use the standard ADR template.
+- A **decision artifact**: which option was picked, and the explicit
+  trade-offs accepted by picking it.
+
+The select gate **re-derives** these via `wicked-loom` (`scripts/qe/vault_gate.py` shells `wicked-loom gate`, which shells `wicked-vault cross-check`): the ADR's bytes are re-hashed and its
+structure verifier re-run, never trusting a cached "ADR written". The
+check is **deterministic document-structure** — it proves the ADR
+contains the required sections, not that the call was wise. 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. `--no-require`
+opts a throwaway/low-rigor decision back to the doctrine-light
+claim-only path. (A judgment tier — `wicked-vault analyze-evidence` —
+exists for "was this the right call" sign-off; it's optional here and
+not part of this discrete gate.)
+
+## HITL
+
+`discrete:select-gate` — the user (or a council) picks. Don't auto-select.
+
+## How to run
+
+### brief
+
+1. Restate the problem in one paragraph. What changes if we pick wrong?
+2. Name the constraints: budget, time, team capability, blast radius,
+   reversibility.
+3. If reversibility is HIGH and blast radius is LOW, **stop and ask**
+   whether this even needs an ADR. Cheap-to-reverse decisions don't
+   benefit from this archetype's overhead.
+4. If a vault is resolvable
+   (`scripts/qe/vault_gate.py resolve` → `available: true`), declare the
+   re-derivable contract so the select gate has a bar to check against:
+   `wicked-vault init` (once per repo) then
+   `wicked-vault declare-contract --scope <scope> --phase decide --spec contract.json`.
+   `required_evidence` pins `adr` (kind `adr-doc`) to a `regex_match`
+   verifier proving the ADR carries every required section — Status,
+   Context, Decision, Consequences — and pins `decision-artifact` to a
+   presence/structure check (`regex_match`, or `commit_exists` once the
+   ADR is committed). Skip silently if no vault.
+
+### options
+
+1. Generate 2–4 distinct options. Don't pad — false alternatives weaken
+   the decision.
+2. For each option:
+   - One-paragraph description.
+   - Cost: time + complexity + ongoing maintenance.
+   - Reversibility: how hard is undoing this in 6 months?
+   - Failure mode: what's the worst plausible outcome?
+
+### score
+
+1. Pick 3–5 dimensions that actually matter for this decision (not a
+   generic checklist). Examples: latency, operational complexity,
+   contract stability, team familiarity, vendor lock-in.
+2. Score each option qualitatively (LOW/MEDIUM/HIGH) on each dimension.
+3. The score is a *thinking aid*, not a winner-picker. The user picks.
+
+### record
+
+1. Use `wicked-garden:jam:council` for a multi-model second opinion when
+   the stakes warrant it.
+2. Write the ADR. Sections: context, options considered, decision,
+   consequences, trade-offs accepted.
+3. Commit the ADR with the implementing change, not separately. The ADR
+   is the explanation for the diff.
+4. Record the ADR as re-derivable evidence (vault present):
+   `wicked-vault record --scope <scope> --phase decide --claim adr
+   --kind adr-doc --source "<path to the ADR>"
+   --criteria "ADR has Status / Context / Decision / Consequences"
+   --verifier 'regex_match:(?ims)^#+\s*(status|context|decision|consequences)\b'
+   --run`, then record `decision-artifact` against the committed ADR
+   (`--verifier commit_exists:<sha>` once committed, else a `regex_match`
+   on the decision line). The `--run` hashes the file's bytes now and the
+   gate re-derives the structure later — a claim you can't re-derive is
+   not evidence. No vault → fall back to `evidence_tracker.py claim`.
+
+## When to stop
+
+Decide is done when the produces-gate is satisfied AND the chosen option
+is named. Check the gate — don't self-assert it:
+`scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase decide` (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 decide`
+(exit 0 = satisfied). This is a re-derived PASS over the declared
+contract — the ADR was re-hashed and its structure verifier re-run. A
+REJECT means the recorded ADR doesn't clear its contract (a missing
+section, an uncommitted artifact) — fix the document, not the claim. An
+`unavailable` verdict means the required vault isn't installed — run
+`/wicked-garden:setup`. Then hand off to `build` (implement the chosen
+path), `migrate` (when the choice is a shape change), or `ship` (when the
+choice is a rollout strategy).
+
+## Anti-patterns
+
+- **Don't run decide for cheap-reversible choices.** A feature flag that
+  defaults to off does not need an ADR. The overhead exceeds the benefit.
+- **Don't pad to 4 options.** Three honest options beats four with one
+  filler.
+- **Don't quantify when you don't have data.** Qualitative scoring is
+  fine; spurious numbers are worse than honest LOW/MEDIUM/HIGH.

package/skills/archetype/refs/explore.md

@@ -0,0 +1,66 @@
+# explore — diverge then converge on open problems
+
+When the problem space is genuinely open and a single answer would be
+premature. Produces an option set or hypothesis, **not a decision** — that's
+the `decide` archetype's job.
+
+## Phase shape
+
+| Phase    | Goal                                                     |
+|----------|----------------------------------------------------------|
+| frame    | Name the problem in one sentence. Surface assumptions.   |
+| diverge  | Generate 4–8 distinct options. Aim for variety, not quality. |
+| converge | Cluster, score qualitatively, and pick a top-3 to take forward. |
+
+## Produces
+
+- **Option set**: 3–8 named alternatives with one-line rationales.
+- **Hypothesis** (when the prompt is research-shaped): testable statement
+  with a falsification condition.
+
+## HITL
+
+`continuous` — the user is a participant. Don't run explore as a closed
+loop; check in after frame, after diverge, before convergence.
+
+## How to run
+
+### frame
+
+1. Restate the problem in one sentence in your own words. Confirm with the user.
+2. List 2–4 assumptions you're making. Get the user to mark them
+   "true / unknown / false".
+3. If a critical assumption is "unknown", branch to `specify` to elicit
+   facts before continuing.
+
+### diverge
+
+1. Generate 4–8 options. **Variety beats quality.** Include at least one
+   "lazy" option (do nothing) and one "expensive" option (the over-built
+   answer).
+2. Use `wicked-garden:jam:quick` or `wicked-garden:jam:brainstorm` for
+   structured ideation when the surface is unfamiliar.
+3. Don't score yet. Just name them.
+
+### converge
+
+1. Cluster the options into 2–3 thematic groups.
+2. Pick the top-3 to take forward. Each one needs:
+   - A one-line description.
+   - A risk note.
+   - A reversibility note.
+3. Hand off to `decide` if the user wants a verdict, or to `specify` /
+   `build` if the path forward is now clear.
+
+## When to stop
+
+Explore is done when the user has a top-3 option set OR a falsifiable
+hypothesis they can take forward. Don't keep diverging.
+
+## Anti-patterns
+
+- **Don't pick a winner inside explore.** That's the decide archetype.
+- **Don't skip frame.** A bad problem statement makes diverge produce
+  noise.
+- **Don't rank prematurely.** Convergence is qualitative clustering,
+  not quantitative scoring.

package/skills/archetype/refs/incident.md

@@ -0,0 +1,149 @@
+# incident — live-fire response to production failure
+
+Mitigate first, RCA second, follow-up third. The cost band is variable —
+a quick rollback may take 5 minutes; a complex multi-service incident
+may consume a day. The phase order is **non-negotiable**: do not
+investigate before mitigating unless investigation IS the mitigation.
+
+## Phase shape
+
+| Phase        | Goal                                                |
+|--------------|-----------------------------------------------------|
+| triage       | Classify severity + scope. Page who needs paging.   |
+| investigate  | Find proximate cause. Just enough to mitigate.      |
+| mitigate     | Stop the bleeding. Rollback / feature flag / scaling / circuit break. |
+| resolve      | Permanent fix. May be the same as mitigate, may not. |
+| followup     | RCA writeup, action items, tests/alerting that would have caught this. |
+
+## Produces
+
+- **Mitigation**: the action that stopped the impact (rollback hash,
+  feature flag toggle, scaling change, etc.).
+- **RCA**: root cause analysis writeup at `docs/postmortems/INC-{N}.md`.
+- **Followup list**: action items with owners. Each gets a github issue
+  or tracked task.
+
+The mitigate gate **re-derives** these via `wicked-loom` (`scripts/qe/vault_gate.py` shells `wicked-loom gate`, which shells `wicked-vault cross-check`): the evidence is re-hashed and its verifier
+re-run, never trusting a cached "mitigated". The honesty move here is the
+mitigation pin — a claimed mitigation that doesn't actually make the
+symptom check pass must REJECT. 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. `--no-require` opts a throwaway/low-rigor run back
+to the doctrine-light claim-only path.
+
+## HITL
+
+`hard:mitigate` — mitigate is a hard gate. Don't move past it without
+confirming the bleeding stopped. Don't skip to followup before resolve.
+
+## How to run
+
+### triage
+
+1. Classify severity: SEV-1 (revenue/data impact), SEV-2 (degraded
+   primary path), SEV-3 (degraded secondary path).
+2. Page the right people. SEV-1 is a phone call, not a slack message.
+3. Open an incident channel + tracking ticket. The ticket is the
+   single source of truth for the timeline.
+4. If a vault is resolvable
+   (`scripts/qe/vault_gate.py resolve` → `available: true`), declare the
+   re-derivable contract so the mitigate gate has a bar to check against:
+   `wicked-vault init` (once per repo) then
+   `wicked-vault declare-contract --scope <scope> --phase incident --spec contract.json`.
+   `required_evidence` pins `mitigation` to a deterministic re-run of the
+   symptom check (`exit_code_eq:0`), and `rca` / `followup-list` to
+   presence/structure `regex_match` (required RCA sections present;
+   followup list non-empty). Skip silently if no vault.
+
+### investigate
+
+1. Look at dashboards FIRST — `wicked-garden:platform:health` /
+   `:traces` / `:incident`. Hypothesize from data, not memory.
+2. Run `wicked-garden:platform:incident` for triage workflows.
+3. **Time-box investigation to 15 minutes during SEV-1.** If you don't
+   have a mitigation hypothesis in 15 min, escalate; don't keep
+   investigating.
+4. Capture the **symptom check** — the command that reproduces the break
+   (it fails now). This becomes the deterministic verifier the mitigate
+   gate re-runs: a real mitigation makes this same command pass.
+
+### mitigate
+
+1. Pick the cheapest reversible action that stops the impact:
+   - Rollback to last-known-good (cheapest).
+   - Feature flag off (cheap if instrumented).
+   - Scale up (when capacity is the issue).
+   - Circuit break a downstream (when a dependency is the issue).
+2. **Confirm the bleeding stopped.** Watch the same dashboards that
+   surfaced the incident. Don't declare mitigated based on logs alone.
+3. Record the mitigation as re-derivable evidence (vault present;
+   **wicked-vault ≥ 0.4.0**):
+   `wicked-vault record --scope <scope> --phase incident --claim mitigation
+   --kind mitigation-check --source "<the symptom-check command>"
+   --criteria "symptom check passes post-mitigation"
+   --verifier exit_code_eq:0 --actor "${WICKED_VAULT_ACTOR:-garden-prove}"
+   --run`. The **`--actor`** is mandatory because `mitigate` is a hard
+   gate: vault ≥ 0.4.0 refuses an `attest` over evidence recorded under a
+   weak/ambient identity, so without an explicit actor the independent
+   attestation fails closed and the gate can never PASS. The `--run`
+   captures the symptom check's real exit code now and the gate re-runs it
+   later — a mitigation you can't re-derive is not evidence. No vault →
+   fall back to `evidence_tracker.py claim`.
+4. Update the incident channel: "MITIGATED via {action} at {time}".
+
+### resolve
+
+1. The permanent fix may be the same as the mitigation (rollback that
+   stays rolled back) or different (rollback unblocks impact, then
+   forward-fix the bug).
+2. Test the fix in staging when possible. Cowboying a fix into prod
+   during an incident is how you get a second incident.
+3. Land the fix; close the incident channel.
+
+### followup
+
+1. Write the RCA within 48h. Use the standard postmortem template.
+2. Use `wicked-garden:incident-to-scenario-synthesizer` to convert the
+   incident into a regression scenario that would catch the same break.
+3. Track action items in github. Don't bury them in a Slack thread.
+4. Record the docs evidence (vault present; **wicked-vault ≥ 0.4.0**):
+   `wicked-vault record --scope <scope> --phase incident --claim rca
+   --kind doc --artifact docs/postmortems/INC-{N}.md
+   --criteria "required RCA sections present"
+   --verifier "regex_match:## Root Cause"
+   --actor "${WICKED_VAULT_ACTOR:-garden-prove}"` and
+   `wicked-vault record --scope <scope> --phase incident
+   --claim followup-list --kind doc --artifact <followup-list>
+   --criteria "followup list non-empty"
+   --verifier "regex_match:- \[" --actor "${WICKED_VAULT_ACTOR:-garden-prove}"`.
+   The **`--actor`** keeps this incident's evidence attestable by an
+   independent reviewer under vault ≥ 0.4.0. No vault →
+   `evidence_tracker.py claim`.
+
+## When to stop
+
+`mitigate` is a **hard gate** — confirm the bleeding stopped before
+moving past it, and don't self-grade the mitigation. Check the gate WITH
+judgment:
+`scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase incident --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 incident --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 incident`. The doer's own evidence cannot satisfy a hard gate.
+(exit 0 = satisfied). This re-runs the symptom check (the mitigation pin)
+and requires an **independent attestation** — an evaluator who is *not*
+the responder confirms the mitigation holds and the RCA is adequate,
+recorded via `wicked-vault:analyze-evidence`. It fails closed on a
+self-grade. A REJECT means the symptom check still fails or the
+attestation is missing/negative — fix the work, not the claim. An
+`unavailable` verdict means the required vault isn't installed — run
+`/wicked-garden:setup`.
+
+Incident is done when the gate is satisfied and the followup list is
+owned and tracked. Hand off to `build` (forward-fix work), `migrate`
+(when the fix is a shape change), or `review` (when the followup includes
+auditing prevention).
+
+## Anti-patterns
+
+- **Don't investigate before you mitigate.** SEV-1 with users impacted
+  is not the time for root-cause analysis.
+- **Don't skip the RCA.** "We know what happened" is what every team
+  says before the same incident recurs.
+- **Don't blame.** Blameless postmortems aren't soft — they produce
+  better followups.

package/skills/archetype/refs/migrate.md

@@ -0,0 +1,170 @@
+# migrate — expand / backfill / cutover / contract
+
+For shape changes that require both forward and rollback proof. Schema
+migrations, data backfills, breaking API rollouts. Uses the standard
+**expand-contract** pattern: add the new shape, make both work, switch
+readers, switch writers, remove the old shape.
+
+## Phase shape
+
+| Phase    | Goal                                                  |
+|----------|-------------------------------------------------------|
+| plan     | Document the shape change. Define rollback contract.  |
+| expand   | Add the new shape. **Do not remove the old shape.**   |
+| backfill | Populate the new shape from the old. Idempotent.      |
+| cutover  | Switch readers/writers. **Hard gate** — staged.       |
+| contract | Remove the old shape. Only after cutover has soaked.  |
+
+## Produces
+
+- **Shape change**: the new schema / API / data layout.
+- **Rollback proof**: an executable rollback path. Tested in staging
+  before cutover.
+
+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 rollback drill is re-run and the
+shape-change post-condition re-checked, never trusting a self-asserted
+"rolled back fine". This is the original evidence-vault use case — for a
+migration the load-bearing honesty move is **no cutover without a
+re-derivable rollback proof**. 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
+migrator confirms the rollback proof and shape change 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 cutover without
+explicit user approval AND a green pre-cutover checklist (rollback
+tested, backfill complete, dual-read working).
+
+## Ground in the repo's method first
+
+Before you plan, check for **wicked-understanding** repo playbooks (the opt-in
+"how to work in THIS repo" layer). A migration lives or dies on repo-specific
+wiring — where readers/writers are switched, how schema/config is loaded, the
+deploy/rollback command. If its skills are present — `add-domain` / `add-feature`
+/ `scaffold`, or the routing block in `AGENTS.md` / `CLAUDE.md` — **load the
+matching playbook** and let it name those exact points instead of rediscovering
+them mid-cutover. Absent? Discover it the usual way — and consider
+`npx skills add mikeparcewski/wicked-understanding --all` so next time it's known.
+
+## How to run
+
+### plan
+
+1. Document the shape change at `docs/migrations/{N}-{slug}.md`. The
+   doc names:
+   - The OLD shape, the NEW shape.
+   - The rollback contract: how to undo, who pulls the trigger, how
+     long the rollback window is.
+   - The expand-contract phase boundaries: when each step happens.
+2. Use `wicked-garden:engineering:migration-engineer` for the canonical
+   playbook.
+3. Declare the re-derivable contract early so the cutover gate has a bar
+   to check against. If a vault is resolvable
+   (`scripts/qe/vault_gate.py resolve` → `available: true`):
+   `wicked-vault init` (once per repo) then
+   `wicked-vault declare-contract --scope <scope> --phase migrate --spec contract.json`.
+   `required_evidence` must pin both claim_ids:
+   - `rollback-proof` → `exit_code_eq:0` on the rollback-drill command —
+     the rollback was actually exercised and succeeded, not asserted.
+   - `shape-change` → a deterministic post-condition: `exit_code_eq:0`
+     on a migration-applied verification, or `jq_pred` over a captured
+     schema-state JSON.
+   Skip silently if no vault.
+4. **If the shape change is reversible HIGH (e.g. a column add), this
+   archetype is overkill.** Drop back to `build`.
+
+### expand
+
+1. Add the new shape alongside the old. **Both must work.**
+2. New writes go to BOTH shapes (dual-write). New reads still come from
+   the old shape.
+3. Land + deploy expand. Don't combine with backfill.
+4. Record the **shape-change** as re-derivable evidence (vault present;
+   **wicked-vault ≥ 0.4.0**):
+   `wicked-vault record --scope <scope> --phase migrate --claim shape-change
+   --kind schema-state --source "<migration-applied verification>"
+   --criteria "<the post-condition>" --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.
+
+### backfill
+
+1. Populate the new shape from the old. The backfill must be
+   **idempotent** — a half-completed backfill that gets restarted
+   should converge to the same end state as a clean run.
+2. Run in batches; rate-limit against the production DB.
+3. Verify completeness: the row count + checksum + spot-check sample
+   match the old shape.
+4. **Exercise the rollback drill and record it as re-derivable evidence —
+   this must exist and re-derive BEFORE cutover** (vault present):
+   `wicked-vault record --scope <scope> --phase migrate --claim rollback-proof
+   --kind rollback-drill --source "<the rollback-drill command>"
+   --criteria "rollback exercised and succeeded" --verifier exit_code_eq:0
+   --actor "${WICKED_VAULT_ACTOR:-garden-prove}" --run`.
+   The **`--actor`** keeps the rollback proof attestable by an independent
+   reviewer under vault ≥ 0.4.0 (the hard cutover gate needs it). The
+   `--run` captures the drill's real exit code now; the gate re-runs
+   it at cutover. A rollback path you can't re-derive is not a rollback
+   path. No vault → fall back to `evidence_tracker.py claim`.
+
+### cutover
+
+1. **Pre-cutover checklist**:
+   - Rollback path executed in staging. (`✓` or block.)
+   - Backfill complete + verified.
+   - Dual-write running cleanly for at least 24h.
+   - Monitoring + alerts updated to surface new shape's anomalies.
+2. **Gate before any switch** — don't self-assert the checklist. Run the
+   produces-gate WITH judgment:
+   `scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase migrate --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 migrate --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 migrate`. The doer's own evidence cannot satisfy a hard gate.
+   (exit 0 = satisfied). This re-derives the rollback drill and the
+   shape-change post-condition over the declared contract, and requires
+   the independent attestation (evaluator ≠ migrator, via
+   `wicked-vault:analyze-evidence`). A REJECT means the rollback proof or
+   shape change 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**: switch readers first, watch for 1h, then switch
+   writers. Don't switch both at once.
+4. The cutover gate is HARD — explicit user "go" before each switch.
+5. If anything looks off post-cutover: **rollback first, debug second.**
+
+### contract
+
+1. Wait for cutover to soak (24–72h, longer for data shape).
+2. Stop the dual-write. Only the new shape is being written.
+3. After another soak, drop the old shape.
+4. Land the contract change with a docs update — the migration is now
+   complete.
+
+## When to stop
+
+Cutover may only proceed when the produces-gate is satisfied — check it,
+don't self-assert it:
+`scripts/qe/prove.py <claim> --by "<command>" --scope <scope> --phase migrate --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 migrate --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 migrate`. The doer's own evidence cannot satisfy a hard gate.
+(exit 0 = satisfied). This is a re-derived PASS over the declared contract
+plus the independent attestation; a missing vault is `gate: "unavailable"`
+/ `satisfied: false`, never a claim-only pass.
+
+Migrate is done when the old shape is removed AND the contract phase
+has soaked. Hand off to `review` for a post-migration audit when the
+change touched compliance or revenue surface.
+
+## Anti-patterns
+
+- **Don't combine expand with backfill.** Each phase is a separate
+  ship. Combining them removes the ability to roll back to a clean
+  intermediate state.
+- **Don't switch readers and writers simultaneously.** Stage them.
+- **Don't contract before soaking.** "We've cutover; let's clean up
+  the old shape" is how you discover at 3am that one consumer never
+  switched.
+- **Don't skip rollback testing.** A rollback path you haven't
+  exercised is not a rollback path.