curate

What this skill does

# /curate — Canonical Miner Skill

> **Role:** miner. Input = trinity slice (transcripts, `.agents/`, `bd`, `git`). Output = skill diffs (proposed), bd updates, rare wiki entries. **Never mutates code.**

> **Status (2026-05-08):** introduced ADDITIVE in Phase 1 (m6v5.D.1 / soc-78s2v). Existing miners (dream, harvest, forge, compile, retro, post-mortem-mining, flywheel, trace, provenance, defrag) stay until Phase 3 shim conversion (m6v5.D.3). Fix-C smoke (`soc-wb2aa`) gates Phase 3.

## Modes (≤8 per Fix-F mode-flag budget)

| Mode | Purpose | Replaces (post-Phase 3) |
|---|---|---|
| `--mode=dream` | Overnight bounded INGEST→REDUCE→MEASURE on `.agents/` | retired dream lane |
| `--mode=harvest` | Cross-rig promotion + post-mortem mining + flywheel rollup | retired harvest lane, `/post-mortem` mining half, `/flywheel` |
| `--mode=forge` | Per-session transcript mining (SessionEnd cadence) | `/forge` |
| `--mode=compile` | Mine→Grow→Defrag→Lint corpus pipeline | `/compile` |
| `--mode=retro` | Single-session learning capture | retired retro lane |
| `--mode=defrag` | Knowledge defragmentation (overnight) | `compile-session-defrag.sh` hook |
| `--mode=watch` | In-session drift / loop detection (15-min cadence) | `research-loop-detector.sh` hook |
| `--mode=provenance` | Decision-trace + artifact-provenance walk | artifact lineage plus `/trace` |

**Mode-budget assertion:** 8 modes. Adding a 9th requires demoting an existing one OR refusing the addition (per Fix-F § continuous CI gate).

**Anti-goals (hard constraints from architecture):**

- NEVER mutates source code.
- NEVER invokes `/rpi` or any code-mutating flow.
- NEVER performs git operations (no commits, branches, push, rebase, checkout).
- NEVER creates symlinks anywhere.

## Quick Start

```bash
/curate --mode=harvest                  # cross-rig promotion sweep
/curate --mode=forge                    # mine the most recent session's transcript
/curate --mode=dream --duration=8h      # overnight bounded run
/curate --mode=compile                  # rebuild .agents/ corpus
/curate --mode=retro                    # capture this session's learning
/curate --mode=defrag                   # knowledge defragmentation
/curate --mode=watch                    # in-session drift check
/curate --mode=provenance --bead=soc-X  # walk decision trace for a bead
```

## Execution

### Step 1: Resolve mode + scope

Parse `--mode`. Each mode has its own scope semantics:

| Mode | Reads | Writes | Cadence (typical loop binding) |
|---|---|---|---|
| dream | `.agents/` corpus | `.agents/overnight/<run-id>/` summary + per-iteration JSON | overnight (1×/24h) |
| harvest | `.agents/` across rigs (`~/.agents/learnings/`) | `~/.agents/learnings/` (promotion), `.agents/harvest/latest.json` | daily (1×/24h) |
| forge | session transcripts (`~/.claude/projects/<session>/*.jsonl`) | `.agents/learnings/`, `.agents/patterns/` | per-session (SessionEnd) or 30m loop |
| compile | `.agents/` corpus | `wiki/INDEX.generated.md`, `.agents/compile/<date>.md` | weekly |
| retro | this session's transcript + recent diffs | `.agents/retro/index.jsonl` (append) | per-session (manual) |
| defrag | `.agents/` corpus | `.agents/defrag/<date>.md` (cleanup report) | overnight (1×/24h) |
| watch | last 100 lines of current session transcript | `.agents/watch/<date>.md` (advisory) | in-session 15m loop |
| provenance | `bd` graph + `git log` + `.agents/` for given anchor | `.agents/provenance/<anchor>.md` | on-demand |

### Step 2: Acquire lock (when applicable)

For `--mode=dream`: acquire `.agents/overnight/run.lock` exclusively. If held, exit with "another curator holds the lock" message; do NOT block.

For `--mode=harvest`: check the dream lock. If held, defer harvest to next loop fire.

For `--mode=forge`: per-session lock at `.agents/forge/session-<id>.lock`. Auto-released at end of run.

Other modes: no lock; concurrent invocation is safe.

### Step 3: Run the mode-specific body

Each mode delegates to a body section in this skill (see § per-mode bodies below for outline; full content moves to `references/<mode>.md` at Phase 2 startup).

### Step 4: Produce artifacts

Output is one of (priority order, per architecture knowledge-flywheel rule):

1. **Skill diffs** — proposed changes to existing skill bodies, written to `.agents/skill-diffs/<date>-<skill>.diff`. Operator approves before applying. NEVER writes to `skills/` directly.
2. **bd updates** — `bd note` or new `bd create` for surfaced issues. Direct, no approval queue.
3. **Knowledge entries** — `.agents/research/`, `.agents/learnings/`, `~/.agents/learnings/` (rare; only when knowledge is generally reusable).

### Step 5: Append to LOG.md

Every mode appends one line to `.agents/LOG.md`:

```
2026-MM-DDTHH:MM:SSZ [curate --mode=<mode>] <run-id> — <short-summary> — outputs: <artifact-paths>
```

### Step 6: Report

1. Mode + scope
2. Output path(s)
3. Surfaced bd issues (if any)
4. Loop continuation hint (next-fire cadence per architecture catalog)

## Per-mode bodies (outline)

### --mode=dream

Overnight INGEST → REDUCE → MEASURE iterations until halt:
- INGEST: scan `.agents/` for new artifacts since last run
- REDUCE: dedupe + score + cluster
- MEASURE: compute knowledge-corpus health metrics
- Halt when: wall-clock budget exhausted, plateau (K sub-epsilon deltas), regression beyond per-metric floor, metadata integrity failure
- Knowledge-only; never code mutation
- Output: `.agents/overnight/<run-id>/summary.{json,md}` + per-iteration archive

Detailed body remains inline until Phase 2 extraction.

### --mode=harvest

Cross-rig promotion sweep (folds the retired harvest skill, cp-dxa):
- Walk `.agents/` across all rigs (paths from `~/.agents/rigs.yaml` or fleet config; default roots `~/gt/`)
- Extract learnings/patterns/research artifacts
- Dedupe by content hash (SHA256 after normalization)
- Promote high-confidence items to `~/.agents/learnings/` global hub
- Roll up flywheel-health metrics as byproduct
- Output: `.agents/harvest/latest.json` + promoted files in global hub

**Naming gotcha:** harvest promotes into `~/.agents/learnings/`, NOT `~/.agents/`.
When a user says "harvest all to `~/.agents`" they mean the promotion hub. If they
really want every raw artifact mirrored verbatim (not just the promotion set), that's
`rsync`, not harvest.

Reference CLI (dry-run gate → execute → post-dedup):

```bash
ao harvest --dry-run --quiet                                              # preview scope → .agents/harvest/latest.json
ao harvest --roots ~/gt/ --promote-to ~/.agents/learnings --min-confidence 0.5
ao dedup --merge ~/.agents/learnings/ 2>/dev/null || true                 # post-harvest cleanup
```

Governance (sweep frequency, size budgets, staleness thresholds, cross-rig synthesis
triggers, dedup policy): [references/harvest-governance.md](references/harvest-governance.md).

Detailed body remains inline until Phase 2 extraction.

### --mode=forge

Per-session transcript mining:
- Locate latest transcript (`~/.claude/projects/<project>/<session>/*.jsonl`)
- Extract knowledge candidates (decisions, patterns, anti-patterns, bug fixes)
- Validate candidates against finding-registry contract
- Queue to `.agents/knowledge/pending/` for curator review
- Output: pending markdown files; bd notes for high-confidence findings

Detailed body remains inline until Phase 2 extraction.

### --mode=compile

Corpus pipeline:
- Mine: extract candidate knowledge from `.agents/`
- Grow: merge into existing taxonomy
- Defrag: collapse redundant entries
- Lint: check for orphans, contradictions, staleness
- Output: `wiki/INDEX.generated.md` (rebuilt), `.agents/compile/<date>.md` (lint report)

Detailed body remains inline until Phase 2 extraction.

### --mode=retro

Single-session learning capture:
- Read last N turns + diff summary
- Identify one durable insight (or none — exit clean)
- Append to `.agents/retro/index.jsonl`
- Optional: surface to bd as note

Detailed body remains inline u