wicked-garden 12.27.0

package/skills/smaht/propose-skills/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: propose-skills
+description: |
+  Mine recent Claude Code session transcripts to propose skills that would
+  automate repetitive patterns the user actually does. Read-only MVP — outputs a
+  markdown report only. No interactive UI, no scaffolding handoff in v1 (those
+  are v2/v3 follow-ups).
+
+  Use when: "find skills I should build", "what should I automate", "propose
+  skills from my sessions", "mine my history for skill ideas",
+  "session-mined skill builder", "skill discovery from past usage".
+user-invocable: true
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Propose Skills (session-mined, MVP)
+
+Detect recurring patterns in Claude Code session transcripts and emit a markdown
+report of skill candidates. The framework grows from what the user *actually
+does*, not from speculative authoring (#677).
+
+## Quick Reference
+
+```bash
+# Default — current project, last 10 sessions
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/smaht/propose_skills.py"
+
+# Scan a different project (use --project= because the slug starts with '-')
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/smaht/propose_skills.py" \
+  --project=-Users-me-Projects-other --limit 25
+
+# Print structured JSON alongside the markdown report
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" \
+  "${CLAUDE_PLUGIN_ROOT}/scripts/smaht/propose_skills.py" --json
+```
+
+**Output modes**:
+
+- Default — prints the report file path on stdout (one line). Read the file,
+  summarize the top 3 candidates inline, and stop.
+- `--json` — prints a JSON object on stdout with `report_path`, scan stats, and
+  the full `candidates` array. The markdown report is still written to disk.
+
+Do not auto-invoke `/wg-scaffold` — this is a read-only proposer.
+
+## What It Detects (3 cheap detectors, no LLM)
+
+| Kind | Trigger |
+|------|---------|
+| **Repeated tool sequence** | Same ordered N-tuple of tool names appears in >= 3 distinct sessions (N in [2, 5]). Homogeneous sequences like `Bash → Bash → Bash` are filtered. |
+| **Repeated prompt template** | User prompts whose first 5 normalized words match across >= 3 sessions. Generic continuations (`yes`, `continue`) and Claude Code system envelopes (`<local-command-...>`, `<command-name>`) are filtered. |
+| **Repeated bash shape** | Same first 2 tokens of a bash command across >= 3 sessions (e.g. `gh pr ...`). Generic file-inspection commands (`ls`, `cat`, `cd`, ...) are filtered. |
+
+## Pipeline
+
+1. **Locate sessions**: `${CLAUDE_CONFIG_DIR:-~/.claude}/projects/{project-slug}/*.jsonl`.
+   The analyzer honors `CLAUDE_CONFIG_DIR` so users with custom config dirs
+   (e.g. `$HOME/alt-configs/.claude`) get matched correctly. Default slug
+   is derived from the current working directory.
+2. **Parse**: each `.jsonl` line, extracting `tool_use` items from assistant
+   messages and the leading text of user messages. Robust against malformed
+   lines.
+3. **Privacy filter**: skip any session whose user prompt contains the literal
+   token `private` or `secret` (case-insensitive). The check runs on the
+   FULL untruncated prompt — a trigger token past the 200-char detector limit
+   still flags the session.
+4. **Detect**: run the 3 detectors over the parsed sessions. A candidate must
+   meet `MIN_FREQUENCY` (total occurrences) AND `MIN_SESSION_COUNT` (distinct
+   sessions) — those are independent counters, not the same number.
+5. **Dedupe**: drop any tool-sequence candidate that is a contiguous
+   subsequence of a more-frequent (or equal-frequency) longer parent.
+6. **Propose**: for each candidate, build a kebab-case slug, a frontmatter-ready
+   description (≤140 chars), and a `/wg-scaffold skill <name> --domain <d>`
+   suggestion. Domain is inferred from tool / bash keywords.
+7. **Render**: write a markdown report to
+   `tempfile.gettempdir()/wg-propose-skills-{timestamp}.md`. On macOS this
+   resolves to a per-user dir under `/var/folders/...`; on Linux it follows
+   `$TMPDIR` and falls back to `/tmp`. Print the report path (default mode)
+   or a JSON envelope including the full candidates array (`--json` mode).
+8. **Summarize inline**: read the top 3 candidates from the report and quote
+   them in the assistant reply.
+
+## Hard Constraints
+
+- **Read-only.** Never writes outside `tempfile.gettempdir()`. Never modifies
+  session files.
+- **Local-only.** No network, no telemetry, no LLM calls inside the analyzer.
+- **stdlib-only.** Cross-platform Python — `pathlib.Path`,
+  `tempfile.gettempdir()`, no third-party deps.
+- **Privacy-first.** Absolute paths under `$HOME` are scrubbed to `~/...` in the
+  report. Sessions mentioning `private` / `secret` are skipped entirely.
+- **Heuristic, not deterministic.** Treat each candidate as a *prompt for
+  judgment*, not a directive. False positives are expected.
+
+## What v1 Does NOT Do
+
+These are explicit v2 / v3 follow-ups and out of scope for this MVP:
+
+- Interactive accept/reject UI.
+- Direct handoff to `/wg-scaffold` or the `scaffolding` skill.
+- LLM-based pattern extraction or summarization.
+- Cross-project mining (only the current project's sessions are scanned).
+- Propose agents, hooks, or commands — the issue scope is *skills only*.
+
+## Inline Summary Format
+
+After running the script, the assistant should reply with something like:
+
+```
+Report: /var/folders/.../wg-propose-skills-20260427T030000Z.md (4 candidates)
+
+Top 3 candidates:
+1. run-curl-s — `curl -s …` shell pattern, 24 occurrences across 12 sessions
+2. run-pnpm-run — `pnpm run …` shell pattern, 9 occurrences across 6 sessions
+3. run-lsof-ti-4321 — `lsof -ti:4321 …` shell pattern, 5 occurrences across 5 sessions
+
+Run `/wg-scaffold skill <name> --domain <d>` for any candidate that's
+worth building.
+```
+
+Exit codes:
+
+- `0` — graceful run (even when no candidates are found).
+- `1` — failed to write the report file (I/O error after analysis succeeded).
+
+## Related
+
+- `/wg-scaffold skill ...` — manual scaffolding (the v2 handoff target).
+- `hookify:hookify` — different direction (proposes *hooks*, not skills).
+- `claude-code-setup:claude-automation-recommender` — codebase-level analysis,
+  not session-level.
+
+## Provenance
+
+- Issue: [#677](https://github.com/mikeparcewski/wicked-garden/issues/677)
+- Helper script: `scripts/smaht/propose_skills.py`
+- Tests: `tests/smaht/test_propose_skills.py` (3 detectors + dedupe + privacy
+  scrub + end-to-end smoke).
+- Scenario: `scenarios/smaht/propose-skills-shape.md`.

package/skills/smaht/refs/state.md

@@ -0,0 +1,76 @@
+# smaht:state — Session State + Recent Events Rubric
+
+Full rubric sourced from `commands/smaht/state.md`.
+Snapshot and report current session state and recent events.
+
+## Step 1: Load SessionState
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" -c "
+import sys, json
+from pathlib import Path
+sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT}/scripts')
+from _session import SessionState
+state = SessionState.load()
+print(json.dumps(state.to_dict() if hasattr(state, 'to_dict') else state.__dict__, indent=2, default=str))
+"
+```
+
+## Step 2: Display Session State
+
+```markdown
+## Session State
+
+**Turn count**: {turn_count}
+**Active chain**: {active_chain_id or "(none)"}
+**Active crew project**: {active_project or "(none)"}
+**Current phase**: {current_phase or "(none)"}
+**Session goal**: {session_goal or "(not set)"}
+```
+
+Skip this section if `--state` is not the only flag (i.e. when `--events` is also given, show both; when `--state` only, skip events).
+
+## Step 3: Display Recent Events
+
+Pull the last N events from the wicked-bus (default 10, override with `--events N`):
+
+```bash
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" -c "
+import sys, json
+from pathlib import Path
+sys.path.insert(0, '${CLAUDE_PLUGIN_ROOT}/scripts')
+try:
+    from _bus import tail_events
+    events = tail_events(limit=${EVENTS_LIMIT:-10})
+    for e in events:
+        print(f\"  [{e.get('event_type','?')}] {e.get('data',{}).get('summary','')}\")
+except Exception as exc:
+    print(f'bus unavailable: {exc}')
+"
+```
+
+```markdown
+## Recent Events (last {N})
+
+{bulleted list of event_type + summary}
+```
+
+## Step 4: v11 Project Context (when `--project <name>` is given)
+
+The v6-era "active crew project" auto-resolver was deleted in v11. When the
+caller passes `--project <name>`, look up via phase_manager:
+
+```markdown
+## Project (v11 archetype-mode)
+
+**Name**: {name}
+**Archetype**: {v11_archetype}
+**Current phase**: {current_phase}
+**Phase plan**: {phase_plan}
+**Is complete**: {is_complete}
+```
+
+## When Context Is Thin
+
+If the output above doesn't surface what you need, invoke `wicked-garden:ground`
+to pull richer brain + bus context for the current task.

package/skills/swarm/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: wicked-garden-swarm
+context: fork
+description: |
+  Parallel verification-swarm orchestration playbook: fan out N scoped
+  subagents over N units of work (repos / modules / files), then run a
+  SEPARATE verifier wave that re-derives each result from a clean state —
+  self-graded "done" is rejected. Composes the crew agents, the qe
+  semantic-reviewer, /wicked-garden:prove, wicked-vault attestation, and
+  the worktrees + deliberate skills rather than reinventing them. This is
+  multi-AGENT parallel execution+verification; for independent multi-MODEL
+  perspectives use jam:council instead.
+
+  Use when: multi-unit / fan-out work ("review every repo", "resolve the
+  backlog with proof", "apply this across all modules", "audit each
+  service"), high-blast-radius changes that need independent verification,
+  or any run where a claimed "done" must be re-derivable from receipts.
+status: stable
+phase_relevance: ["build", "test", "review"]
+archetype_relevance: ["build", "review", "migrate", "modernize", "incident"]
+---
+
+# Swarm — parallel verification swarm
+
+Orchestrate **N units of work in parallel** (one scoped subagent per unit),
+then **independently verify** every result with a separate wave of agents that
+re-derive "done" from a clean state. The swarm's value is not the parallelism —
+it's that **no agent grades its own work**. A claimed "tests pass" / "done" that
+can't be re-derived from receipts is rejected.
+
+> **Swarm vs council.** `jam:council` gets independent *multi-model* opinions on
+> one decision (different vendors answer the same scaffold). Swarm gets parallel
+> *multi-agent* execution + verification over many units. Use council to decide;
+> use swarm to execute-and-prove. They compose: run a council inside the verify
+> wave for a high-stakes verdict (see `refs/independent-verification.md`).
+
+## Compose, don't reinvent
+
+This skill is orchestration prose. Every primitive it needs already exists in
+the garden — reference these, do not duplicate them:
+
+| Need | Use (existing garden piece) |
+|------|------------------------------|
+| Per-unit implementer subagent | `agents/crew/implementer.md` (already does parallel-when-independent + evidence) |
+| Per-unit recon subagent | `agents/crew/researcher.md` (read-only context gathering) |
+| Independent semantic verdict | `agents/qe/semantic-reviewer.md` (independent-by-construction; refuses to attest its own work) |
+| Fallback reviewer | `agents/crew/reviewer.md` (reviewer-separation + external-review rules baked in) |
+| Re-derive a claim (the receipt) | `/wicked-garden:prove` (run + freeze evidence + gate; fail-closed) |
+| Hard-gate independent sign-off | `/wicked-garden:prove --with-attestations` → `wicked-vault attest` (evaluator ≠ creator, G10) |
+| Blast-radius / scope lens | `wicked-garden:deliberate` (lens 2 + 3) and `/wicked-garden:search:blast-radius` |
+| Per-unit isolation + commit hygiene | `wicked-garden:worktrees` (dangling-commit trust-but-verify) |
+| Phase shape per unit | `wicked-garden:archetype` refs (`build` / `review` / `migrate`) |
+| Multi-model verdict in a wave | `wicked-garden:jam:council` |
+
+## The wave loop
+
+```
+0. recon      → parallel researcher agents → concept catalog + per-unit profiles
+   synthesize → fit-matrix + relevance tiers
+   checkpoint → ONE structured scope question to the user (skip under full latitude)
+1. implement  → N parallel implementer agents (one per unit, self-contained brief)
+                each writes DETAILED artifacts to disk, returns a ~150-word summary
+2. verify     → M parallel verifier agents (SEPARATE from implementers)
+                re-run from clean state, read the ACTUAL diff, render PASS/FAIL/PARTIAL
+3. receipts   → /wicked-garden:prove per claim; hard gates add --with-attestations
+4. ship       → branch per unit, conventional commits, CI-green, independent review,
+                clean merge tree, tag-driven release  (only when asked)
+```
+
+Each numbered step has a ref. Waves hand off **via disk artifacts**, never via
+the orchestrator's context — that is what keeps the parent lean and the run
+auditable.
+
+## Orchestrator hygiene (the parent context stays lean)
+
+- **Detail to disk, summary to context.** Subagents write the full profile /
+  plan / diff / receipt to the scratch dir and return ≤150 words. Never let a
+  subagent dump raw output into your context.
+- **One message, many Task calls** for each wave — that is what makes it
+  parallel. A serial run with no documented `serial_reason` is a protocol miss
+  (same rule `agents/crew/implementer.md` enforces).
+- **Background long/external work** and synthesize on completion rather than
+  blocking the wave.
+- **The verifier is a different agent than the implementer.** If the same agent
+  type did the work, the verdict is a self-grade — `agents/qe/semantic-reviewer.md`
+  and the vault `attest` both refuse `evaluator == creator`.
+
+## The two reusable briefs
+
+The mechanics that make this repeatable are the **briefs** handed to each wave.
+Both live in `refs/fan-out.md` (implementer) and `refs/independent-verification.md`
+(verifier) as copy-paste templates. The shape:
+
+- **Implementer brief** (per unit): read THIS unit's own rules/conventions →
+  impact analysis (blast radius) BEFORE changing → implement with **in-scope
+  tech-debt cleanup only** (no opportunistic refactor sprawl) → functionally
+  test **proportional to blast radius** → write artifacts to disk → return a
+  concise summary.
+- **Verifier brief** (per unit): ignore the implementer's prose → re-run the
+  suite/build from clean → read the ACTUAL diff → check over-claims (e.g. a
+  claimed "pre-existing failure" must actually fail on the BASE commit) →
+  render PASS / FAIL / PARTIAL → write the authoritative receipt.
+
+## Honest marking (no padding)
+
+Mark every finding `GAP` / `PARTIAL` / `ALREADY-COVERED`. Surface
+reverse-transfers and "you're already ahead of this" honestly. **A short true
+list beats a long speculative one.** Record considered-and-rejected items
+explicitly so they read as weighed, not missed. Details in
+`refs/receipts-and-evidence.md`.
+
+## Recon-first, then checkpoint
+
+Before an expensive fan-out, run the recon wave and synthesize a fit-matrix +
+relevance tiers, then **checkpoint scope with the user in a single structured
+question**. Under an explicit goal / full latitude, proceed without asking.
+Full procedure in `refs/recon-synthesis.md`.
+
+## Disk-artifact layout (waves hand off here)
+
+A scratch dir (the worked example this playbook was distilled from used
+`.cross-pollination/`) with a top synthesis/index doc, per-unit
+profile/plan/review/receipt files, and a deferred-items log. Exact tree in
+`refs/recon-synthesis.md` §layout and `refs/receipts-and-evidence.md`.
+
+## Refs
+
+- [refs/recon-synthesis.md](refs/recon-synthesis.md) — recon wave, fit-matrix, relevance tiers, the single checkpoint question, scratch-dir layout
+- [refs/fan-out.md](refs/fan-out.md) — parallel implementer wave + the **implementer brief template**, impact analysis, in-scope cleanup
+- [refs/independent-verification.md](refs/independent-verification.md) — the verifier wave + the **verifier brief template**, isolation, over-claim kills, PASS/FAIL/PARTIAL
+- [refs/receipts-and-evidence.md](refs/receipts-and-evidence.md) — verbatim receipts, prove/vault/wicked-testing composition, honest GAP/PARTIAL/ALREADY-COVERED marking
+- [refs/ship-discipline.md](refs/ship-discipline.md) — branch-per-unit, conventional commits, CI-green gate, independent review + resolve, clean merge tree, tag-driven release

package/skills/swarm/refs/fan-out.md

@@ -0,0 +1,104 @@
+# Fan-out — the parallel implementer wave
+
+Dispatch **N independent subagents in parallel**, one per unit of work
+(repo / module / file / service). One message, multiple `Task` calls — that
+is what makes it a swarm and not a loop.
+
+Use `agents/crew/implementer.md` as the agent. It already encodes the rules
+that matter here: parallel-when-independent dispatch, structured evidence in
+every `TaskUpdate`, and the guardrails (never auto-proceed on deploys / deletes /
+schema migrations). This ref adds the **per-unit brief** that scopes each one.
+
+## When a unit is independent
+
+A unit is safe to fan out in parallel when it:
+- touches disjoint files from the other units,
+- shares no mutable state with them, and
+- has no producer→consumer ordering against them.
+
+If two units edit the same file or one's output feeds another, either serialize
+those two (and record a `serial_reason`) or merge them into one unit. Everything
+else runs concurrently.
+
+## The implementer brief template
+
+Each subagent gets a **tight, self-contained** brief. It must not need the
+orchestrator's context to do its job — everything it needs is in the brief or
+discoverable from the unit itself.
+
+```
+You are the swarm implementer for unit: <unit-name> (<path / repo URL>).
+You run in parallel with sibling implementers on other units. You share no
+state with them. Do not touch anything outside this unit.
+
+SCRATCH DIR: <scratch>/<unit-name>/   (create it; write all detail here)
+
+1. GROUND IN THE UNIT'S OWN RULES FIRST.
+   Read this unit's own conventions before changing anything: its
+   AGENTS.md / CLAUDE.md / CONTRIBUTING, lint+test config, and any
+   wicked-understanding repo playbook (add-feature / fix-bug / write-tests).
+   Follow THIS unit's method, not a generic one.
+
+2. IMPACT ANALYSIS (blast radius) BEFORE you change anything.
+   What does this change touch? What depends on it? Use
+   /wicked-garden:search:blast-radius (or grep the call sites) and the
+   deliberate lens ("map the blast radius: what else shares this root cause").
+   Write blast-radius.md to your scratch dir. The blast radius SETS YOUR
+   TEST BAR (step 4) — a wide radius demands more verification.
+
+3. IMPLEMENT — in scope only.
+   - Make the smallest change that satisfies the goal.
+   - In-scope tech-debt cleanup ONLY: fix debt you are already editing.
+     NO opportunistic refactor sprawl — drift is the #1 cause of inflated
+     cycles (same rule as the build archetype's implement phase).
+   - Fix ROOT causes, not symptoms.
+
+4. FUNCTIONALLY TEST, proportional to blast radius.
+   | blast radius | test bar |
+   |--------------|----------|
+   | low (leaf, reversible) | one targeted test that exercises the change |
+   | medium | unit tests + 1-2 integration |
+   | high (shared code, many callers) | unit + integration + an acceptance check |
+   Run the unit's REAL test command. Capture exact command + output + exit code.
+
+5. WRITE DETAILED ARTIFACTS TO DISK (not to your reply):
+   <scratch>/<unit-name>/blast-radius.md, plan.md, diff.patch (or commit SHA),
+   test-output.txt (verbatim, with exit code), assumptions.md.
+
+6. RETURN A CONCISE SUMMARY (~150 words MAX). Include:
+   - what changed (1-2 sentences) and the scope you held to,
+   - the blast-radius verdict (low/medium/high),
+   - the test command + PASS/FAIL + exit code,
+   - the artifact paths,
+   - the base commit SHA you started from (the verifier needs it),
+   - anything you deferred (so it lands in the deferred log, not silently dropped).
+   Do NOT paste diffs or raw logs into the summary — those are on disk.
+```
+
+## Why the brief is shaped this way
+
+- **Self-contained** → the orchestrator's context stays lean; the subagent can
+  run in an isolated worktree without back-and-forth.
+- **Rules-first** → a unit's own conventions win over a generic house style;
+  this is the difference between a change that merges and one that bounces.
+- **Impact analysis before code** → you cannot pick the right test bar until you
+  know the blast radius. This is the hinge that makes verification proportional.
+- **In-scope cleanup only** → bounded debt repair without scope creep.
+- **Detail to disk, ~150 words back** → the receipts are auditable and the
+  verify wave reads the artifacts, not the implementer's prose.
+
+## Isolation + commit hygiene
+
+When implementers commit (each on its own branch — see `refs/ship-discipline.md`),
+follow `wicked-garden:worktrees`: a subagent's "Commit SHA: abc1234" can be a
+**dangling commit** that `git gc` will collect once its worktree is removed.
+**Trust-but-verify every reported SHA** with the ancestry check before you treat
+the work as landed. This matters double in a swarm because many agents commit
+concurrently.
+
+## Hand-off
+
+When the wave returns, you have N concise summaries in context and N detailed
+artifact sets on disk. Do **not** start verifying inline — dispatch the
+**separate** verify wave (`refs/independent-verification.md`), handing each
+verifier the unit's scratch dir + base commit SHA.

package/skills/swarm/refs/independent-verification.md

@@ -0,0 +1,86 @@
+# Independent verification — the verify wave (the core)
+
+This is the mechanism the whole skill exists for. The verifier is a **separate
+agent from the implementer** that **re-derives** each result from a clean state.
+Self-graded "done" is rejected. This is the vault / `prove` ethos applied to a
+swarm: a claim is only true if it can be recomputed from frozen evidence.
+
+> **Independence is structural, not polite.** Use a *different* agent type than
+> the one that did the work. `agents/qe/semantic-reviewer.md` is independent by
+> construction and **refuses to attest code it authored**; `wicked-vault attest`
+> fails closed when `evaluator == creator` (G10). If you let the implementer
+> verify itself, you have a self-grade — the one thing this skill forbids.
+
+## Pick the verifier agent
+
+| Verdict needed | Agent |
+|----------------|-------|
+| Does the code do what the spec/AC MEANS? | `agents/qe/semantic-reviewer.md` (opus, independent-by-construction) |
+| General correctness when no specialist fits | `agents/crew/reviewer.md` (has reviewer-separation + external-review baked in) |
+| High-stakes verdict needing multiple opinions | `wicked-garden:jam:council` (independent multi-model) inside the wave |
+| The raw "did the suite actually pass" receipt | `/wicked-garden:prove` (run + gate) — see `refs/receipts-and-evidence.md` |
+
+Run M verifiers in parallel — one message, multiple `Task` calls — one per unit.
+
+## The verifier brief template
+
+```
+You are the swarm VERIFIER for unit: <unit-name>. You did NOT implement this.
+Your job is to re-derive the result from a clean state and render a verdict.
+Trust nothing the implementer asserted — re-derive it.
+
+INPUTS: <scratch>/<unit-name>/  (the implementer's artifacts) and
+        BASE COMMIT SHA: <sha>  (the state before the change).
+
+1. RE-RUN FROM CLEAN.
+   Check out / reset to a clean tree. Run the unit's REAL build + test suite
+   yourself. Do not read the implementer's test-output.txt as truth — produce
+   your own. Capture exact command + full output + exit code.
+
+2. READ THE ACTUAL DIFF, not the prose.
+   git diff <base-sha>..HEAD (or the diff.patch). Verify the change is what the
+   summary claimed, scoped where it claimed, with no smuggled-in extra edits.
+
+3. KILL FORCE-FITS AND OVER-CLAIMS.
+   - If the implementer said a failure is "pre-existing", CHECK OUT THE BASE
+     COMMIT and confirm it actually fails there. A "pre-existing failure" that
+     passes on base is a regression the implementer introduced — FAIL.
+   - If a test was weakened, skipped, or its assertion gutted to go green — FAIL.
+   - If the change does less than claimed — PARTIAL, and say exactly what's missing.
+
+4. RENDER THE VERDICT: PASS / FAIL / PARTIAL.
+   - PASS: re-ran clean, diff matches claim, no over-claims, tests genuinely green.
+   - PARTIAL: works but incomplete / claim overstated — list the gap.
+   - FAIL: does not re-derive — name the exact command + output that disproves it.
+
+5. WRITE THE AUTHORITATIVE RECEIPT to <scratch>/<unit-name>/receipt.md:
+   verdict, the exact command(s) you ran, their verbatim output + exit codes,
+   the base SHA and head SHA, and a one-line rationale. This receipt — not the
+   implementer's summary — is the record of truth for this unit.
+
+6. RETURN ~150 words: verdict + the single most load-bearing piece of evidence
+   (the command + exit code that proves it) + receipt path.
+```
+
+## The wave structure
+
+```
+implementers wave  →  (disk artifacts)  →  verifiers wave  →  (receipts)  →  prove gate
+```
+
+- The two waves never run as one agent. The hand-off is **disk artifacts**, so
+  the verifier starts from the implementer's outputs but re-derives the result
+  independently.
+- A unit is only "done" when its `receipt.md` says PASS **and** the claim is
+  re-derived through `/wicked-garden:prove` (next ref). A FAIL or PARTIAL goes
+  back to a fresh implementer slice — the original implementer does not get to
+  argue its way to PASS.
+
+## Why re-derivation beats assertion
+
+A traceability/claim heuristic reports an untagged-but-correct change as
+"missing" and a tagged-but-wrong one as "done" — both wrong (this is exactly
+why `semantic_review.py` is only a pre-filter and `agents/qe/semantic-reviewer.md`
+does the real read). The verifier closes that gap: it judges by re-running and
+reading, not by trusting a label or a summary. The verdict that **names the gap**
+is the value; never inflate to PASS to be helpful.

package/skills/swarm/refs/receipts-and-evidence.md

@@ -0,0 +1,69 @@
+# Receipts & evidence — claims must be re-derivable
+
+A swarm produces **receipts, not assertions**. Every "done" / "tests pass" /
+"build clean" must be re-derivable from frozen evidence: the **exact command**,
+its **real output**, **exit code**, and the **commit SHA** it ran against. If you
+can't re-derive it, it isn't proven — it's a claim, and claims are rejected.
+
+## Compose the garden's evidence machinery — don't hand-roll it
+
+| Mechanism | Use it for |
+|-----------|------------|
+| `/wicked-garden:prove <claim> --by "<cmd>" [--verifier ...]` | The one-line receipt: runs the command, freezes its real exit code as wicked-vault evidence, gates by **re-running** the verifier. Exit 0 only on a re-derived PASS; **fail-closed** (exit 3) when the backend is down — never a vacuous pass. Works on **interim** artifacts too (prove a produce the moment it exists). |
+| `/wicked-garden:prove ... --with-attestations` | Hard gates (review / incident / migrate). Stays REJECT (`UNATTESTED`) until an **independent** evaluator runs `wicked-vault attest <id> --opinion pass`. The doer's own evidence cannot satisfy it — that is the anti-self-grade point. |
+| `wicked-vault attest <id> --opinion pass --evaluator <who>` | The independent sign-off itself. Fails closed on `evaluator == creator` and on weak/ambient identity (record under an explicit `--actor`, default `garden-prove`). |
+| `wicked-testing:*` verdicts (writer → executor → reviewer, isolated) | When the unit needs a full evidence-gated acceptance verdict rather than a single command receipt. The reviewer is isolated from execution — same independence principle as the verify wave. |
+
+This is the **Sentinel rule** made concrete: a done-claim needs a *re-derived
+verdict*, not a self-report. `/wicked-garden:prove` is the verb you reach for by
+reflex before telling the user a unit is done.
+
+## What a receipt looks like (verbatim, never paraphrased)
+
+Each unit's `receipt.md` (written by the **verifier**, not the implementer) holds:
+
+```
+unit:        <unit-name>
+verdict:     PASS | FAIL | PARTIAL
+base_sha:    <sha the change started from>
+head_sha:    <sha after the change>
+command:     <the exact command run, copy-pasteable>
+exit_code:   <real exit code>
+output: |
+  <verbatim stdout/stderr — the real thing, not a summary>
+prove:       <the /wicked-garden:prove JSON verdict: satisfied + re_derived>
+attestation: <artifact id + evaluator, for hard gates; else "n/a">
+rationale:   <one line>
+```
+
+Never write "tests pass" without the command + output + exit code that proves
+it. A receipt a reviewer can't re-run is not a receipt.
+
+## Honest marking — no padding
+
+The swarm's credibility comes from honesty, not volume. Mark every finding:
+
+- **GAP** — genuinely missing; should be added.
+- **PARTIAL** — half-there; name exactly what's missing.
+- **ALREADY-COVERED** — the unit is already ahead of this; say so plainly.
+
+Rules:
+- **Surface reverse-transfers and "you're already ahead" honestly.** If a unit
+  already does the thing better than the proposed change, that's a finding, not
+  an omission — and sometimes the change should flow the *other* way.
+- **A short true list beats a long speculative one.** Don't pad the fit-matrix
+  with maybes to look thorough.
+- **Record considered-and-rejected items explicitly** in `deferred.md` so they
+  read as *weighed, not missed*. "Considered X, rejected because Y" is a
+  stronger signal than silence.
+- **The verdict that names the gap is the value.** Never inflate a PARTIAL to
+  PASS, or a GAP to ALREADY-COVERED, to be agreeable.
+
+## Tie it back to the gate
+
+A unit is shippable only when: its `receipt.md` verdict is PASS **and**
+`/wicked-garden:prove` returns `satisfied: true, re_derived: true` for the
+claim **and** (for hard-gate work) an independent `wicked-vault attest --opinion
+pass` exists from an evaluator that is not the implementer. Anything short of
+that is PARTIAL or FAIL and loops back to a fresh implementer slice — see
+`refs/independent-verification.md`.