/clear-out-wip

Reduce backed-up work to the smallest truthful residual set. "Clear out" means every observed path ends in one witnessed disposition: ship, keep active, park, remove generated junk, or file and dispatch. A smaller git status is an outcome, not the objective; never get there by hiding, resetting, stashing, or absorbing another worker's changes.

This is the operator workflow over existing primitives. Use /commit-clean for each ship unit, /stale-work-loop for stale or ownerless candidates, and /fleet-wave only for already-filed, collision-priced follow-on units. Do not recreate those workflows here.

Non-negotiable fences

• Work on main; do not create a branch, hand-rolled worktree, stash, reset, clean unignored files, or bulk-stage the checkout.
• Treat the shared checkout as peer-dirty. A path's presence in git status does not make it yours. Mutate or commit only paths whose ownership is evidenced by the operator, current task, a lane/lease record, or a coherent diff you can attribute independently.
• If MERGE_HEAD exists and the merge is not yours, do not finish or abort it. Leave your edits unstaged and wait. Strictly avoid raw unverified git merges, --autostash, or force-pushes. Integrate upstream advances only through structured convergence (fak sync apply or fak sync reconcile).
• Dual-repo boundary awareness: when clearing WIP spanning shared interfaces (pkg/*), platform modules, or cross-repo dependencies with fak-private, inventory and coordinate both checkouts. Verify multi-module alignment (go work sync) and ensure zero private leak needles (python tools/scrub_public_copy.py --audit-staged) before declaring enabling or ship-now slices ready to land.
• Never add a .gitignore rule merely to make an unknown path disappear. Ignore only a reproducible generated class with a named producer; verify no tracked or durable source path matches. Prefer allocating output through fak tree-doctor --scratch-dir/--scratch-path.
• Never ship broken default builds, secrets, generated binaries, private run fuel, misleading claims, or half of a cross-file symbol dependency. A build tag may protect genuine in-progress source, but is not a way to launder abandoned code into trunk.
• Do not close a parent issue merely because an independently useful enabling slice shipped. Describe and witness exactly the slice that landed; keep or file the remaining done-condition.

0. Open the lifecycle receipt

Before any mutation, run:

fak wip lifecycle begin --kind clear-out --root .

Keep the returned operation_id. This persists the fak-wip-inventory/1 before snapshot outside the working tree. If capture fails, report the typed WIP_LIFECYCLE_CAPTURE_FAILED condition but continue any safety-critical recovery; never reinterpret capture failure as a zero WIP count.

1. Freeze a read-only census

Run the inventory before editing anything. Save bulky machine output under an allocated scratch path, not a new repository-root filename.

git status --short --branch
git rev-parse --abbrev-ref HEAD
git rev-parse -q --verify MERGE_HEAD
fak sweep --json
fak tree-doctor --json

If clearing WIP that crosses shared boundaries into companion repository fak-private, run the dual-repo census:

# In fak-private checkout:
git status --short --branch
git rev-parse -q --verify MERGE_HEAD
git fetch origin
# Multi-module workspace graph verification:
go work sync

If either checkout has an active MERGE_HEAD, halt and wait for merge quiescence before proceeding. Never abort or finish a peer's merge.

Also inspect lane/lease and WIP records when available:

fak wip list --json
fak worktree worker list --json

If a verb differs in the installed build, inspect fak <verb> -h and use its current read-only form. Do not replace a missing read-only verb with an ad hoc mutation.

Build a path ledger with these columns:

Unit	Paths	Evidence of owner	Intent	Dependency seam	Test/proof	Age/origin	Disposition

Group paths by one coherent outcome, not merely by directory. Keep unknown ownership as UNKNOWN; do not infer it from timestamps, author names in nearby commits, or apparent quality. Record the before count and grouped unit count so the final reduction is measurable.

2. Retire hygiene debt first, but only proven hygiene

Classify maintenance residue before feature work because it obscures the real queue:

1. Generated junk: known outputs, temp binaries, logs, caches, or allocated scratch. Preview ignored cleanup with fak tree-doctor --sweep-scratch --dry-run; apply only after every listed path is known disposable. Use fak sweep --clean-junk only for paths that the sweep itself freshly classifies as junk.
2. Durable generated output: promote a successful reusable artifact up the tooling ladder instead of discarding it. In this repo that means a Go leaf/verb plus witness, not a new Python helper.
3. Ignore gap: identify the producer, choose the narrowest pattern, prove it does not match tracked/durable files (git ls-files plus a pattern-specific check), edit .gitignore, rerun the producer or equivalent witness, and commit the maintenance change as its own coherent unit.
4. Unknown or possibly human-authored file: retain it unchanged and route it to ownership adjudication. It is not hygiene.

Never use broad unignored cleanup, broad wildcard ignores, or removal as a triage shortcut.

3. Score units for the next action

Apply this deterministic order; do not prioritize by easiest diff alone:

1. Safety and trunk health: secret exposure, build breakage, merge residue, generated binary collisions, or an active lease conflict.
2. Ready-to-ship user value: a coherent outcome with an appropriate green witness.
3. Enabling value: an independently useful seam that unblocks other work even if the parent feature remains disabled.
4. Decay risk: old, ownerless, duplicated, or conflict-prone work.
5. Cosmetic cleanup: formatting or organization with no independent outcome.

Within a tier, prefer highest user/unblock value, then strongest witness, then smallest collision surface. Use the FAK value frame for every proposed ship unit: For / Problem / Today / Better because / Witness. Reject a slice that cannot explain its own value without promising the unfinished parent.

Assign exactly one next action:

• SHIP_NOW - coherent, owned, truthful, and witnessable now.
• FINISH_SMALL_GAP - one bounded repair/test makes the coherent unit shippable in this session.
• SHIP_ENABLER - useful and safe independently, while the larger feature remains openly incomplete.
• KEEP_ACTIVE - current owner/lease and near-term continuation are evidenced.
• STALE_ADJUDICATE - ownerless/old/ambiguous; use /stale-work-loop, whose discovery phase does not edit the candidate.
• PARK - valuable bytes must be preserved but are not active or safely shippable; use the repo's witnessed parking/WIP mechanism, never a stash or mystery archive.
• DELETE_JUNK - only the generated-junk proof above permits this.
• FILE_FOLLOWUP - concrete residual work with a done-condition and explicit path tree.

4. Decide whether incomplete work can ship

A parent feature need not be fully enabled for a slice to land. The slice may ship as SHIP_ENABLER only when all rows pass:

Gate	Required evidence
Independent value	A caller, operator, or next implementation can use the slice without pretending the parent is done.
Coherent boundary	Named paths form one leaf and contain both sides of any changed contract.
Safe default	Default build/runtime behavior stays green and fail-closed; disabled means honestly unreachable, not silently broken.
Durable witness	Focused test or captured artifact proves the slice's actual claim.
Honest surface	Help, docs, claims, issue state, and flags do not advertise unfinished behavior.
Residual tracked	The remaining parent done-condition is already an open issue or is filed before the run ends.

Examples that can qualify: a tested parser used by an existing path, a fail-closed interface plus fake, a disabled-but-selfchecking demo spine, a migration reader landed before its writer, or a narrow .gitignore producer fix. Orphan structs, speculative frameworks, tests for unreachable behavior, and a flag wired to a stub do not qualify.

If only a small gap prevents qualification, finish that gap before committing. Otherwise keep, park, or issue it; do not lower the gates to reduce the dirty count.

5. Ship serially and re-census after every unit

For each SHIP_NOW or SHIP_ENABLER unit:

1. Confirm ownership and inspect the complete diff for the explicit paths.
2. Run the narrow witness, then fak validate --mine <path> ... for the committed tip plus only that unit. On this Windows host, use the repository's WSL test path where tests are required.
3. Follow /commit-clean: preview the subject, ensure local HEAD is converged with upstream without raw merges or --autostash (fak sync apply or fak sync reconcile supporting ROUTE_DISJOINT_INTEGRATE, ROUTE_SUPERSET_MERGE, or ROUTE_HOLD_DIRTY_COLLISION with fak wip park). Commit exactly the paths under the lock, verify the committed path set, and push through the safe sync path (fak sync push).
   • When clearing WIP spanning shared boundaries (pkg/*) with fak-private, verify boundary leak hygiene (python tools/scrub_public_copy.py --audit-staged), run go work sync, and coordinate safe pushes across both repositories (fak sync push in fak, fak-sync push in fak-private). One coherent unit, one commit, one leaf.
4. Cite the changed module@rev and witness. State parent remains open for an enabling slice.
5. Rerun fak sweep --json; peers may have changed the tree while the unit landed. Never apply a stale census to the next commit.

Do not batch unrelated maintenance and feature work just because both are ready. Do not repeatedly patch the same issue across several commits; finish its coherent acceptance boundary first.

6. Distribute and start contract-ready residual work

Local dirty paths are not worker fuel. First convert residuals into dedicated issues with:

• one outcome and done-condition;
• explicit owned path tree;
• current candidate/evidence digest;
• acceptance witness;
• dependency and collision notes; and
• retain/update/remove authority where stale work is involved.

Use /stale-work-loop for candidate adjudication. A one-unit or same-path queue is serial work, not a fleet wave. For multiple disjoint issues, use /issue-orchestrator (fak issue-orchestrator --plan-waves) and split overlaps into later waves before generating or starting sessions.

Execution intent

Classify the invocation before launch:

• Plan-only: "inspect", "triage", "what can ship?", or "plan a clear-out" produces the census, dispositions, issue contracts, and priced wave; it starts no session.
• Live clear-out: "clear out", "work through", "distribute", "start sessions", "run the backlog", or an unattended/deadline request authorizes the native dry-run -> live launch path for contract-ready residual issues. Local SHIP_NOW units still land serially first.
• Explicit no-fan-out: "locally", "do not launch", or an equivalent constraint keeps all work serial even if several issues are ready.

When intent is unclear, complete the safe local spine and render the dry-run receipt. Never claim that work was distributed merely because issues or a plan were created.

Generate the guarded wave

Use the installed native dispatcher as the single workflow generator and launcher. Do not handwrite child prompts, spawn raw Codex processes, wrap the whole wave in one parent guard, or mix in the legacy launcher.

fak dispatch wave --help
fak fleet-accounts wave --count <N> --work-kind codex --product codex --json
fak fleet-accounts status --provider codex --json
fak dispatch wave --count <N> --backend codex --work-kind codex --max-workers <C> `
  --goal high-priority --workspace . --json

Choose N from the number of contract-ready issues, not the number of dirty paths. Choose C no higher than the collision-safe concurrency and independently observed host/account headroom. Read the dry-run receipt and require all of the following before launch:

• selected issue IDs and bounded issue-derived worker fuel;
• pairwise-safe lane/path leases, with overlaps moved to later waves;
• distinct admitted account/session slots and a truthful shortfall;
• guarded worker commands using the Codex backend;
• implement -> test -> witness -> commit -> push ownership; and
• typed refusal/downsize reasons for every candidate not started.

A refusal is a recovery input, not permission to retry blindly. Apply the receipt's recovery action, re-price once state changes, and preserve the refusal in the run report.

Start sessions once

For live-clear-out intent and a clean dry run, launch the exact plan once:

fak dispatch wave --count <N> --backend codex --work-kind codex --max-workers <C> `
  --goal high-priority --workspace . --live --json

Record the wave ID plus each issue, lane, account/session slot, PID, and run/log path. --count is the total requested session slots over refill time; --max-workers is the concurrent process ceiling. Do not rerun the launcher to top up. Let the native refill controller use newly available capacity; use fak dispatch auto only when the installed /fleet-wave contract directs it.

Monitor and harvest

Monitor from outside worker-owned trees and judge progress by independently readable state:

fak dispatch status --runs-dir <RUNS_DIR> --json
fak dispatch progress --target <N> --json
fak dispatch closure-audit --workspace . --json

Follow /fleet-wave for liveness and account recovery and /wave-harvest for reconciliation. SHIPPED requires git/read-back, focused green acceptance evidence, issue state, and DOS/commit witnesses; a process exit, worker log, or final message is insufficient. Release leases and account slots after reconciliation, then run another census. Start a later collision wave only from the new state and only while live-clear-out intent remains in force.

6.5. Close the lifecycle receipt

After the last mutation and verification, run:

fak wip lifecycle end --root . --id <operation_id>

The resulting fak-wip-lifecycle/1 receipt links ordered before/after inventory artifacts under one operation identity. Include its receipt_path in the final report.

7. Exit with a residual proof

Repeat the read-only census and reconcile every original unit plus any newly observed path. Report:

• before/after dirty path and grouped-unit counts;
• shipped commits with module@rev and focused witness;
• generated junk removed and the producer/classification that proved disposal;
• active or parked units with owner and recovery command/location;
• filed residual issue numbers and any launched/harvested wave;
• unknown/peer-owned paths explicitly untouched; and
• the next checkable action.

The run is complete only when every observed unit has a disposition and every named follow-up is an open issue. A still-dirty tree can be a successful clear-out when the residue is owned and typed; a clean-looking tree with hidden, stashed, removed, or untracked obligations is a failure.