feat(proof): first-class bounded convergence loops in DAG schema

[tonyketcham]

Summary of changes

Generalizes the --converge-on/--max-iterations CLI singleton in @flatbread/proof into a DAG-native loops array, so a single run can stack multiple convergence tasks (e.g. one for the implementation reviewer, one for the docs reviewer) and so DAG-emitting tooling can declare loop intent reproducibly.

Resumes from cursor agent bc-0ff9d782-…, which discussed cyclic vs acyclic task graphs in proof and concluded:

• The dependency graph should stay acyclic — depends_on is causality + parallelism, not iteration.
• Bounded refinement (research → critique → refine, fix → test → fix-until-oracle) is real and useful, but it belongs in an explicit loop primitive, not a back-edge in the DAG.

This PR lifts that loop primitive into the DAG JSON.

What's new

{
  "title": "implementation + adversarial review",
  "loops": [
    {
      "id": "review-loop",
      "convergeOn": "review",
      "maxIterations": 3,
      "reexecute": { "kind": "ancestors" },
      "stopWhen": "no-blockers"
    }
  ],
  "tasks": [/* … */]
}

• convergeOn and maxIterations are required.
• reexecute is optional. { kind: 'ancestors' } (default) mirrors the legacy CLI behavior. { kind: 'tasks'; tasks: [...] } is an explicit allow-list, validated to lie inside the convergence ancestor cone (off-cone tasks would break filtered topological ordering).
• stopWhen is optional. Today the only value is 'no-blockers'; the schema is open for future predicates without further churn.
• id is optional and defaults to loop-${convergeOn}.
• DAG.budget.maxIterations keeps applying per-loop and the existing BUDGET-EXCEEDED terminal status carries through unchanged.
• The CLI flag and DAG.loops are mutually exclusive — supplying both fails fast at startup rather than picking a silent precedence rule.

Backward compatibility

• DAG JSON without loops parses unchanged.
• --converge-on <id> --max-iterations <N> keeps working end-to-end. Internally it synthesizes a single-element loops array so the runner has one canonical code path.
• extractConvergenceFindings, the findings-dir sidecar contract, the extraContext stitching format, and transitiveAncestors are all unchanged. Existing reviewer prompts keep working.

Out of scope (this PR)

• New stopWhen predicates beyond 'no-blockers' (e.g. 'oracle-pass', score thresholds).
• Nested loops.
• Cross-loop coordination.

The full design rationale is in docs/proposals/proof-bounded-convergence-loops.md (commit 1).

Files changed

• docs/proposals/proof-bounded-convergence-loops.md — proposal & rationale.
• packages/proof/src/dag.ts — DAGConvergenceLoop, LoopReexecute, LoopStopWhen, ResolvedConvergenceLoop types, validation, resolveConvergenceLoops().
• packages/proof/src/converge_loop.ts — new resolveLoopReexecuteIds() helper.
• packages/proof/src/run_dag.ts — runConvergenceLoop accepts a precomputed reExecIds set + loopId; main() iterates dag.loops (or a synthesized loop from the CLI flag).
• packages/proof/src/index.ts — re-exports new types/helpers.
• packages/proof/src/__tests__/loops.test.ts — 18 AVA cases.

Testing

• ✅ pnpm --filter @flatbread/proof typecheck
• ✅ pnpm --filter @flatbread/proof build
• ✅ pnpm exec ava packages/proof/src/__tests__/loops.test.ts — 18/18 passing
• ✅ pnpm test:ava — 73/73 passing across the workspace
• ✅ pnpm test:vitest — 46/46 passing across @flatbread/codegen + @flatbread/utils
• ✅ pnpm lint
• ✅ pnpm build (full monorepo)
• ✅ End-to-end CLI smoke: proof --init-only --dag <loops.json> writes the canvas; proof --dag <loops.json> --converge-on b errors with --converge-on cannot be combined with DAG.loops (DAG "loop-smoke" already declares 1 loop(s)). Remove one.

Notes

The user originally asked for /proof to drive a planning + implementation + self-review loop on this PR with Opus 4.7 (HIGH) and GPT 5.4 (MEDIUM). Three earlier resume attempts on this same agent thread errored out trying to launch the runner, so this PR ships the planning + implementation + tests directly and lets /proof ride the new DAG.loops config in a follow-up rather than blocking the change behind another runner spin-up. The implementation here is exactly the schema /proof would self-review against, so the follow-up is now a one-flag config change instead of "remember to pass --converge-on review --max-iterations 3".

Please don't delete this checklist!

• I added doc comments to any new public exports, and inline comments to any hard-to-understand areas
• My changes generate no new console errors locally
• If applicable, try to include a test that fails without this PR but passes with it

Does this introduce any non-backwards compatible changes?

• Yes
• No

Does this include any user config changes?

• Yes
  • If so, I have updated the relevant areas of documentation
• No