Wave Harvest

---
name: wave-harvest
description: "The honest closing half of a super loop — after a detached bulk wave (`/super-loop`) has run, HARVEST it: witness what each headless worker actually shipped (not what its log claims), re-queue the leaves that were claimed-done-but-not-shipped, stop workers that are spinning without net gain, and surface any lane a worker stranded dirty. A launch is not a ship, so a bulk loop is only durable if something reconciles its output against git ground truth. Read-mostly — it audits and. Use when this named workflow matches the task."
allowed-tools: Read, Bash, Write
metadata:
  opencode: claude-only   # the witness-over-self-report and no-narration-close discipline is load-bearing and not portable per-skill
---

# /wave-harvest — reconcile a detached wave against git ground truth

> **The closing half of `/super-loop`.** A wave launches N detached workers; this
> skill answers the only question that matters afterward — *what actually shipped?*
> — from git and the issue tracker, never from a worker's log tail. It re-queues the
> claimed-but-unshipped, stops the spinners, and leaves the tree clean. Without a
> harvest pass a bulk loop drifts: workers narrate "done", the backlog looks drained,
> and nothing is witnessed. This is the pass that keeps an unattended fleet honest.

## The rule this skill enforces

**A launch is not a ship, and a self-report is not a fact.** Every "done" a worker
emitted is a claim. The harvest verdict for each leaf comes from git ancestry
(`dos commit-audit`, `dos verify`) and the issue's real state (closed by a `Fixes #N`
commit on the trunk) — the same witness `/dos-dispatch-loop` Step 3 uses, applied to
detached workers this session can't see.

## Step 0 — Enumerate what the wave launched

The launchers leave durable markers; read them, don't guess:

```bash
fak dispatch status --json                           # live vs cap, throughput, CLOSURE HONESTY, orphan cross-check
fak dispatch closure-audit --workspace . --json      # closure rate vs claimed closed audit
```

- `.goal-runs/*.pid` / `*.out.log` — one per detached worker.
- `.dispatch-runs/inflight-*` — one per in-repo wave worker (`fak dispatch wave`);
  each names the lane it took.

Build the work-list: for each marker, the `{pid, lane, leaf/issue}` it was launched
on. `fak dispatch status`'s **closure-honesty** block is the headline — a low
`closure_rate` with a high `CLAIMED_CLOSED` count is exactly the drift this pass exists
to catch.

## Step 1 — Witness each claimed leaf (git, not the log)

For each leaf a worker claims it resolved, get the verdict from ground truth:

```bash
dos commit-audit --json                              # HEAD (or a worker's tip): claim vs diff
dos verify --workspace . <plan> <phase> --json       # a plan/phase actually shipped? (source: registry|grep|none)
gh issue view <N> --json state,stateReason,timelineItems   # closed by an ancestry Fixes #N, or still open?
```

Classify each leaf into one of four buckets:

- **VERIFIED** — a witnessed commit on the trunk, issue closed by ancestry. Done; drop
  it from the residual.
- **QUIET_INCOMPLETE** — the worker CLAIMED done but the oracle says NOT_SHIPPED
  (`dos verify` source=none, or `dos commit-audit` CLAIM_UNWITNESSED, or the issue is
  still open with no resolving commit). **Do NOT believe the claim** — re-queue the leaf
  (Step 3). This is the FQ-336 touch-counts-as-ship false-drain.
- **STRANDED** — a real commit exists but its lane's tree is still dirty
  (`git status --porcelain -- <lane paths>` non-empty) and the worker is gone. Durable
  work left uncommitted; surface it and commit it by explicit path (or leave it if the
  path belongs to a still-live sibling lease — check `dos arbitrate`).
- **HONEST_OPEN** — never claimed, never shipped. Fine; it stays in the queue.

## Step 2 — Stop the spinners (net-gain, not motion)

A detached worker that is still live but producing no witnessed net gain is burning an
account. Judge by witnessed work, not log volume — the `fak dispatch status` cross-check
flags orphan processes and dead-but-live workers:

- A worker whose leaf is VERIFIED and whose lane is clean has finished — if it is still
  live and spinning (re-picking, narrating), stop it: `Stop-Process -Id <pid>` (the PID
  is in its `.pid` file).
- A worker repeatedly claiming SHIPPED while every claim reconciles QUIET_INCOMPLETE is
  the docs/351 not-ratcheting failure (motion without measured progress). Stop it and
  hand the leaf back to Step 3 — do not let it keep burning the cap.
- Leave a worker that is genuinely mid-flight (advancing commits, clean lane) alone.

## Step 3 — Re-queue the incomplete (the cross-run KEEP)

The QUIET_INCOMPLETE leaves are the ones a naive "the wave ran, backlog drained" would
silently lose. Put them back so the next `/super-loop` wave picks them up — flagged, so
they route to a verifier pass or `/dos-replan`, not blindly re-dispatched:

- If the leaf is a GitHub issue, it is still open (an ancestry close never fired), so it
  re-enters the `ready-leaves` / `p0-p1` surface automatically — just confirm it is not
  falsely marked `in-progress`/assigned by a dead worker, and clear that marker if so.
- Record the re-queue in the harvest note (Step 4) with the witness that demoted it
  (the `dos verify source=none` / `dos commit-audit CLAIM_UNWITNESSED` line), so the next
  wave has the evidence, not just a re-pick.
- **Never** re-dispatch a leaf held by a re-dispatch-invariant reason (draft-class,
  operator-gated, dependency-unmet) — surface it for the operator instead.

## Step 4 — Record the harvest (optional note) and leave the tree clean

If the operator wants a record, write a dated note under `docs/_audits/` (process
residue, kept out of the root index scan):

```text
docs/_audits/wave-harvest-YYYY-MM-DD.md
```

Shape: workers launched (count, accounts/pools), the VERIFIED/QUIET_INCOMPLETE/STRANDED/
HONEST_OPEN tally, the re-queued leaves + their demoting witness, and the PIDs stopped.
Commit only that path, on the trunk, by explicit path (`fak commit --path ... (fak claude)`),
never `git add -A`.

## What this skill does NOT do

- **It does not close issues.** Ancestry (`Fixes #N` on the trunk) closes an issue; a
  `gh issue close` off a harvest is the self-report this whole discipline refuses.
- **It does not launch new work.** That is `/super-loop`. Harvest reconciles; it re-queues
  by leaving open leaves open, not by spawning.
- **It does not re-implement fleet monitoring.** It reads `dispatch_status.py` and the
  markers; it does not build a new status surface.

## Anti-patterns

- ❌ Trusting a worker's `out.log` "done" over `dos verify` / `dos commit-audit`. The log
  is the claim; git is the witness.
- ❌ Reporting the backlog drained from launch/close counts. Read `closure_rate` and the
  per-leaf witness — a `CLAIMED_CLOSED` is not a `TRUE_RESOLVED`.
- ❌ Killing a mid-flight worker that is actually advancing. Stop spinners (no net gain),
  not progress.
- ❌ Dropping QUIET_INCOMPLETE leaves silently. Re-queue them with the demoting witness —
  a silent drop is the false-drain the harvest exists to prevent.
- ❌ Committing a STRANDED lane that belongs to a still-live sibling lease — check
  `dos arbitrate` first; commit only lanes whose worker is gone.