finishing-a-development-branch

Finishing a Development Branch

Work is not finished because the code looks done. It is finished when a gate you just ran says so — not when a record claims one already did.

The completion gate

Work is not finished because the code looks done, and never because "the tests looked green" or "the teammate said it was done" earlier in the conversation. Which check applies depends on what state the run is in — check in this order.

1. Fleet run: status.gates is recorded

If .teammates/<run-id>/status.json exists and has a non-empty status.gates, this is a fleet run — but a record in status.gates is a report written by the agents being enforced, and status.json is agent-writable, so it is never trusted as evidence. A recorded verdict of PASS proves nothing by itself:

{
  "gates": {
    "<phaseName>": {
      "verdict": "PASS",
      "failed": [],
      "skipped": [],
      "pending": [],
      "recordedAt": 1785952191621
    }
  }
}

Use status.gates only to see which phases the run executed. For each of those phases, re-run the gate now:

node "$CLAUDE_PLUGIN_ROOT/scripts/cli.mjs" gate --run <runId> --plan <planPath> --root <project root> --phase <name>

gate recomputes fileset and ownership from git at the moment it runs — it does not read or trust the old record. If any phase's fresh run does not exit 0, the work is not finished — name the phase and stop.

2. Inline run: a run directory exists but gates are absent or empty

executing-plans runs plans inline, task by task, and never writes a gate manifest or a verdict — that's by design, not an omission. If status.json exists but status.gates is absent or empty, the run is inline, and the absent gates are expected, not a fault to fix here.

There is no fleet history to derive fileset or ownership from, so run the gate solo:

node "$CLAUDE_PLUGIN_ROOT/scripts/cli.mjs" gate --no-fleet --root <project root>

--no-fleet is the only way the enforcement checks are skipped, and it runs the project's full test suite (and any other command checks teammates.gate.json declares) fresh — a remembered result, or a run from earlier in this session, is not evidence. Once it exits 0, proceed.