v3.1.4 Jacobean Released

[waleedkadous]

v3.1.4 Jacobean

Released: 2026-05-27

A patch on the Jacobean line, driven mostly by porch-discipline findings from real adopter use. Three substantive ships: a CI fix from the v3.1.3 cleanup fallout, the porch consultation-policy correction that fixes a multi-iteration over-eagerness, and the canonical pr_ready_for_human signal that closes the BUGFIX gap in the Needs Attention surface introduced in v3.1.3.

CI: verify-install probes afx instead of removed af (PR #851, fixes #848)

Fallout from v3.1.3's codev afx wrapper removal. packages/codev/scripts/verify-install.mjs was still probing the af bin in its post-install verification list. CI on main has been red since the v3.1.3 merge.

One-line change: ['codev', 'af', 'porch', 'consult'] → ['codev', 'afx', 'porch', 'consult']. The script itself is the CI verification test — changing the list is the regression guard. CMAP-3 unanimous APPROVE.

Out-of-scope nit raised by all three reviewers: the script still doesn't probe team or generate-image (also in the bin map). Not addressed; separate ticket if it becomes relevant.

Porch: COMMENT and REQUEST_CHANGES treated asymmetrically (PR #871, fixes #870)

The reporter (an external Codev adopter's architect) flagged that porch was treating COMMENT and REQUEST_CHANGES symmetrically — both triggered re-iter — and the dead-code getMaxIterations helper was never wired into the verdict-handling flow. A natural experiment over 21 review iterations on a real in-flight SPIR project showed a per-N iteration cap was the wrong abstraction: real bugs hide in deep iterations (one phase had four consecutive iters each catching a new correctness bug), and a count-based cap would have shipped critical bugs.

The fix lands the architect's superseding policy:

• ADVANCE when no reviewer returned REQUEST_CHANGES this round (all APPROVE-or-COMMENT). allApprove() already counted COMMENT as approve; this PR adds an explicit regression test so future refactors can't silently regress the asymmetry.
• RE-ITER when any reviewer returned REQUEST_CHANGES (no count limit in normal flow). The rebuttal-exists branch now increments state.iteration and clears build_complete so the next porch next emits a fresh build task carrying the previous reviews + rebuttal as context.
• SAFETY CEILING via max_iterations — kept only as runaway-prevention. Default raised from 1 to 8 in both protocol-parsing and getMaxIterations() fallback; per-phase override stays available.

A new force_advanced field on ProjectState records when the safety ceiling fires — {phase, iteration, max_iterations, rebuttal_file, at} — and the next phase's first task gets a "ceiling notice" prefix so the architect/builder sees the context.

Notable nuance: PIR's pr phase keeps max_iterations: 1 explicitly. Under the old code that was meaningless (porch ignored it); under the new code it correctly enforces PIR's documented single-pass advisory CMAP — REQUEST_CHANGES at iter-1 force-advances with audit trail, exactly what PIR's CLAUDE.md contract promises.

5 new tests cover the policy (COMMENT-only advances, REQUEST_CHANGES re-iter, force_advanced fires at ceiling, audit trail correctness). CMAP-3 unanimous APPROVE / HIGH on iter-1 and iter-2.

Dashboard: canonical pr_ready_for_human signal closes BUGFIX gap (PR #874, fixes #872)

The v3.1.3 Needs Attention filter (introduced in PR #845) gated PR inclusion on b.blocked === 'PR review' — the gate label for porch's pr gate, which SPIR / ASPIR / PIR / AIR all carry but BUGFIX does not. BUGFIX's pr phase is terminal with no gate, so the builder transitions cleanly from pr to verified after CMAP without ever blocking. Result: every open BUGFIX PR was silently invisible in Needs Attention since v3.1.3 shipped. Found by reviewing an in-flight BUGFIX PR that the dashboard wasn't surfacing.

The fix moves the "is this PR ready for human review" decision from a protocol-specific derivation to a canonical state-machine signal.

What changed

• New pr_ready_for_human: boolean field on ProjectState, written by porch at the three transition points that fire across all five protocols:
  • handleVerifyApproved (next.ts) — SPIR / ASPIR / PIR review (build_verify, gate=pr): set true at pr-gate-pending
  • done() (index.ts) at pr-gate auto-request — AIR pr (once, gate=pr): set true at gate-requested
  • advanceProtocolPhase() (index.ts) on pr → verified transition — BUGFIX (once, no gate, terminal): set true at phase advance
• Reset to false on rebuttal cycle (REQUEST_CHANGES) and on pr gate approval / rollback
• PR-creating phase detection via gate === 'pr' || consultation.on === 'review'. The narrow consultation.on === 'review' check matters — bare consultation presence would mis-flag RESEARCH's investigate / critique phases as PR-creating
• New OverviewBuilder.prReady field on @cluesmith/codev-types (consumer-facing; TypeScript change worth flagging)
• derivePrReady helper in overview.ts reads the canonical field if present, falls back to the v3.1.3 derived logic for in-flight projects (blocked === 'PR review' || (phase === 'verified' && protocol === 'bugfix')) so the BUGFIX gap closes for both new and pre-existing builders
• NeedsAttentionList.tsx's buildItems now gates on b.prReady. The builder fallback loop checks prReady before the !b.blocked early-out — this is critical because BUGFIX builders have blocked: null, so the old skip-on-not-blocked path would drop them. Fallback to b.startedAt for the waiting-since chip when blockedSince is null.

Process notes

This fix is itself a v3.1.2-style dual-CMAP success. The builder's own CMAP-3 was unanimous APPROVE on iter-1, but the architect-side CMAP-3 caught two real bugs both other reviewers missed individually: (a) isPrCreatingPhase over-matched RESEARCH's non-PR consultation phases (Codex caught it), and (b) the NeedsAttentionList builder fallback dropped BUGFIX builders before the prReady check (Gemini caught it). Both blockers were addressed in iter-2 with unanimous APPROVE / HIGH and zero residual issues.

Lesson reinforced: running the architect-side CMAP independently from the builder-side CMAP catches the things either reviewer alone misses. Saved in the architect's working memory.

Related issue closed as superseded

Issue #873 (the "fast-fix filter-side patch" alternative to this canonical signal) was closed as superseded — the fallback path in derivePrReady covers the same BUGFIX gap as a side-effect of the v3.1.3-compat shim.

Breaking changes

• OverviewBuilder.prReady: boolean is now a required field on @cluesmith/codev-types. Consumers that destructure overview-builder objects may want to either consume the new field or treat it as optional in their own types until they catch up. This mirrors the v3.1.1 pattern for spawnedByArchitect.

Install

npm install -g @cluesmith/codev@3.1.4
afx tower stop && afx tower start

Multi-workspace adopters: no migration needed. The new pr_ready_for_human field is automatically set on porch transitions; existing in-flight projects without the field fall back to derivePrReady's v3.1.3-compat logic (which also closes the BUGFIX gap).

Contributors

• External Codev adopter's architect — reported the porch consultation-policy bug, ran the 21-iter natural experiment that drove the retracted-cap → asymmetric-policy reframe, available for cross-workspace consultation.
• M Waleed Kadous (@waleedkadous) — architect review, integration CMAP discipline (caught both blockers on PR [Bugfix #872] Fix: emit canonical pr_ready_for_human signal across all protocols #874 that the builder's own CMAP missed).
• Builders working under BUGFIX protocol across PRs Fix #848: probe afx (not removed af) in verify-install.mjs #851, [Bugfix #870] Wire up max_iterations as safety ceiling; treat COMMENT and REQUEST_CHANGES asymmetrically #871, and [Bugfix #872] Fix: emit canonical pr_ready_for_human signal across all protocols #874.