/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:

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:

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):

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.