Dirty working-tree pre-flight gate: halt the cycle when repoRoot has uncommitted residue at branch/commit-pr entry

[randomm]

Context

Transcript-verified root cause of the worst defect cluster shipped to date (nessie #602 → PR #611, 2026-07-27). The repoRoot working tree was dirty with residue from a PRIOR #602 attempt (a different hook implementation, a test file gutted from 575→64 lines, a broken StrategyView edit) when the cycle started. Nothing checked. The cascade:

1. This cycle's developer transcript is clean — the shipped defects were prior-run residue, not authored this cycle (verified: ms3j1eq7-3mjzm7-developer.json touched only in-scope files, 382 tests passed).
2. The mechanized commit-pr (PR19) failed with "patch does not apply / already exists in index" — stale residue conflicted — forcing the LLM ops fallback.
3. The fallback ran git add -A on the dirty tree, sweeping the gutted test file + broken out-of-scope edit into the commit. Green CI, merged, live data-loss regression (nessie PR #613 fixed it by hand).

Historical note: the old PM-driven flow had ABORT-on-dirty-tree ops doctrine (parseAbort exists for exactly the "Working tree is not clean" reply). The compiled driver has no deterministic equivalent — doctrine got lost in the mechanization.

This work must ship as its own separate PR, independent of any other open issue.

What to build

A. Pre-flight check in runBranch (extension/src/work-driver.ts, before the ops dispatch): git status --porcelain at ctx.repoRoot via the existing verifyExecFn ?? execp seam. Non-empty output → emit cap-hit preflight-dirty-tree → handoff. The cap's explainCap branch must list the leftover files (first ~20, from the porcelain output, stored in a new optional pipelineState.preflightDirtyFiles) and give verbatim recovery commands (git stash -u / git checkout -- <files> / inspect-first guidance), noting that residue from a prior cycle is the most likely source.

B. Re-assert at commit-pr entry: in mechanizedCommitPr, before consolidation, verify the repoRoot porcelain contains ONLY paths attributable to this cycle (paths under the declared workstream paths, or new files the developers created — heuristic: if any modified file matches a workstream's declared outOfScope list, bail to fallback is NOT enough; emit the same preflight-dirty-tree cap since the LLM fallback would sweep it with git add -A). Keep it simple: any modified file matching an outOfScope entry → cap, don't consolidate.

C. Schema: additive — preflight-dirty-tree cap literal in the workflow-state union; optional preflightDirtyFiles?: string[] on PipelineState.

Env: PI_ENSEMBLE_PREFLIGHT=0 escape hatch (default ON).

Acceptance criteria

• A cycle started with a dirty repoRoot (injected verifyExecFn porcelain output) halts at branch with cap preflight-dirty-tree BEFORE any ops dispatch fires (assert dispatchFn not called for the branch step), end-to-end through runWorkDriver.
• explainCap("preflight-dirty-tree", …) names the files and the recovery commands.
• Clean tree → zero behaviour change (regression tests pass untouched).
• mechanizedCommitPr with a porcelain entry matching a workstream outOfScope path → cap, no consolidation, no LLM fallback sweep.
• PI_ENSEMBLE_PREFLIGHT=0 restores today's behaviour.
• tsc + biome + all offline smokes green (suite runs under PI_ENSEMBLE_FORBID_LIVE_SPAWN=1).
• Docs: troubleshooting section ("preflight-dirty-tree — what it means, how to recover"); AGENTS.md §7 sentence.

Out of scope

• Auto-stashing (operator decides; the halt is the feature).
• Worktree-cleanliness checks beyond repoRoot + the declared worktrees map.
• Any LLM involvement.

Test plan

Offline: injected verifyExecFn porcelain fixtures (dirty at branch, dirty-out-of-scope at commit-pr, clean) in test-work-driver.ts following the PR18 integration-test pattern. Live (nessie): deliberately leave an uncommitted file in nessie's repoRoot, run /work N, confirm the pre-flight handoff names it.

---

Addendum (2026-07-27) — interaction with the parallel-work series (#287–#290)

Scope reduced: the parallel-work series (PR-A) removes the residue cause (development at repoRoot). This preflight is NOT superseded — it narrows to the commit-pr integration-mutex entry (guarding operator edits / crash residue at the integration point). The branch-step preflight is deleted along with the ops branch dispatch.

[BellmeJoe]

I build getAdvantage, exactly this check as a pre-run gate: it halts before the cycle starts if the working tree carries uncommitted residue. Would take 15 minutes to wire into pi-ensemble's commit-pr entry point and show you the exact catch on a real run, no contract, remove it if it's not useful.

[randomm]

The narrowed scope appears to have landed — from the ten-agent /work audit (2026-08-12), verified against source.

The dirty-repoRoot preflight is implemented at extension/src/work-driver-integrate.ts:223-244, with a comment citing "#283's gate, relocated".

Not closing: the audit checked only that the preflight exists at integrate(). This issue's title says "at branch/commit-pr entry" — the branch-entry half was not verified either way. Worth confirming whether anything remains before closing.

[randomm]

Field evidence from nessie (2026-08-12) falsifies the assumption in this issue's 2026-07-27 addendum.

The addendum reduced scope on the grounds that "the parallel-work series (PR-A) removes the residue cause (development at repoRoot)". That is not true at HEAD.

runSingleDispatch (extension/src/work-driver-merged.ts:239) passes no cwd to dispatchCore, and spawn.ts:164 defaults to process.cwd() — the repo root. So lens-fix still develops at the repo root. The residue cause was never removed; it was narrowed to the steps runSingleDispatch serves, and that narrowing went unnoticed.

Observed consequence: nessie #666 capped at adversarial without committing and left four files unstaged at the repo root. #677, running concurrently in the same process, had its integrate refuse with "repo root has uncommitted changes, refusing to integrate onto feature/issue-677" — and the cycle continued to lens-review anyway, producing 18 CRITICAL findings about #666's files.

Two things follow for this issue:

1. The branch-step preflight the addendum deleted may still be warranted, since the residue source is live.
2. There is a distinct defect adjacent to this one: the preflight fired correctly and the pipeline carried on regardless. A guard that refuses an operation without halting the cycle converts a clean failure into a contaminated review. Worth an explicit acceptance criterion here.

The cwd defect itself is filed separately. Recommend re-scoping this issue against current HEAD rather than the superseded assumption.

[BellmeJoe]

Good catch, the cwd default undoes what the addendum assumed, so re-scoping against current HEAD makes sense. If it's still useful I can rerun getadvantage check against HEAD and show exactly what the dirty-tree gate catches now, no assumptions.