v3.1.6 Jacobean

v3.1.6 Jacobean

Released: 2026-05-31

A Jacobean-line patch focused on the VS Code extension. The biggest story is a Backlog UX overhaul — mine-only-by-default, in-place title-count, a command-palette Quick Pick, sidebar reorder, and area/* label grouping that also extends to the Builders tree. The Builders tree gets its own clarity pass (phase prefix on every row, gate-specific icons in place of the universal bell, plus Open Spec / Open Review row actions). One real bug fix is notable: the SCM colors on builder file rows that v3.1.4 thought it had fixed but actually hadn't.

Backlog UX overhaul (#808, #809, #811, #818, #885, #895, #911, #918, #932)

Eight coordinated changes turn the Backlog tree from a flat scroll into a triage surface.

Mine-only by default with a one-click "show all" toggle (#809, PR #910). The Backlog tree opens filtered to issues assigned to the current GitHub user — fresh installs land on "what's on my plate" instead of the firehose. A title-bar eye icon toggles show-all and back, with the choice persisting across VSCode reloads. When gh isn't authenticated (no currentUser to filter on), the view falls back to show-all so you never end up with an empty backlog you can't explain.

Title-count reflects what's visible (#911, PR #914). The Backlog view's title bar reads Backlog (3 of 47) when mine-only is active and only some of the backlog is visible, or Backlog (47) when everything is shown — the count updates in lockstep with the eye-icon toggle. The mine-only toggle from #809 shipped without this; the title-count stayed at the unfiltered total over a filtered tree, which produced "where are the other 44?" confusion. This release fixes that in lockstep.

Codev: Search Backlog... Quick Pick (#918, PR #938). A new command-palette entry opens VSCode's native Quick Pick overlay (the same UI behind Cmd+P / Cmd+Shift+P) populated with every open backlog issue. Fuzzy-match by id, title, area, or assignee; select a row to open the issue the same way clicking it in the sidebar would. Search always runs over the full backlog regardless of the mine-only toggle — search is a discovery affordance, not a filter. No default keybinding; bind via keybindings.json if you want one.

area/* grouping in the Backlog AND Builders trees (#811 PR #886, #818 PR #890; UPPERCASE headers via #885 PR #893 + #895 PR #897). Both views now group their rows under their area/* labels (active builders use their underlying issue's label), sorted alphabetically with Uncategorized last. Group headers render in UPPERCASE — VSCODE (4), TOWER (3) — matching VSCode's panel-header convention (EXPLORER, SEARCH, SOURCE CONTROL); the underlying label values stay lowercase. One mental model now applies across both views — same axis, same ordering. Repos that haven't adopted area/* labels collapse to a flat list with no visual change.

Sidebar default order: Backlog above Pull Requests (#932, PR #940). Fresh installs now see Builders → Backlog → Pull Requests → Recently Closed → Team → Status. The top-to-bottom story pairs Builders with Backlog as the two surfaces checked together during active triage, and groups Pull Requests with Recently Closed at the bottom as the downstream/completion-side surfaces. Users who have already dragged views into their own order keep their custom order — VSCode persists user-reordered views per-workspace.

Reference Issue paste includes the title (#808, PR #899). The "Reference Issue in Architect" inline action on a backlog row now pastes #42 "<title>" into the architect terminal (was just #42). The architect gets meaningful context immediately without having to fetch and parse the issue first.

Builders tree clarity (#793, #810)

[<phase>] prefix on every builder row (#810, PR #941). Every builder row in the Builders tree leads with a [<phase>] prefix right after the issue number — so #909 [implement] architect: treat area/*... instead of having the phase buried at the end of the row where long titles would clip it off-screen. Phase stays visible across all three row states (active, blocked, idle), and the prefix's position survives column truncation.

Distinct icons per gate on blocked builders (#810, PR #941). Blocked builders now show distinct icons per gate type — spec, plan, dev, PR, and verify review each get a unique glyph — replacing the universal bell that conflated all gate types into one signal. Color stays uniform warning-yellow across gates so "needs your attention" remains the consistent meta-signal; only the shape varies by gate type. The data flow needed a small extension to thread the canonical gate name (b.blockedGate) to the VSCode side; that's a backward-compatible addition.

Open Spec / Open Review row actions (#793, PR #908). The Builders right-click context menu now includes Open Spec and Open Review alongside the existing Open Plan — and Open Plan is no longer PIR-only (now also visible on SPIR/ASPIR rows). Each entry hides on protocols that don't produce that artifact (e.g. AIR has no spec, so no Open Spec; PIR's Open Review appears only once the review file has actually been written), so you don't end up clicking into a "file not found."

Needs Attention surface keys on the universal pr gate (SPIR #927, PR #928)

The dashboard's Needs Attention surface previously derived "PR ready for human review" from a tangle of fragile signals: a bugfix && phase === 'verified' fallback in derivePrReady, a sticky pr_ready_for_human field on ProjectState, and a defensive builder-emit branch in NeedsAttentionList.buildItems that surfaced builder rows when no PR could be found. All three workarounds existed for one root cause — an external adopter's gateless 4-phase BUGFIX variant — and they collectively kept merged PRs visible, hid ready PRs in some shapes, and swapped builder rows in for PRs that couldn't be located.

v3.1.6 reframes the entire surface around the universal pr gate that every PR-producing protocol already has (BUGFIX got one in #887; AIR / SPIR / ASPIR / PIR already had theirs). The pr gate going pending — set by porch after the PR phase / CMAP completes — is the uniform "ready for human, after CMAP" signal across all five protocols. The dashboard now surfaces PR rows from open PRs whose builder's pr gate is pending; the builder-emit fallback is gone; merged PRs drop naturally because the open-only filter does the work without needing a recentlyMergedIssueIds suppression projection (also retired here, end-to-end).

Net delete: −45 LOC of packages/ source. The most robust kind of fix.

Side effect that flows into VSCode

The shared GATE_LABELS map gains verify-approval (the post-merge SPIR/ASPIR verify gate). That entry propagates through detectBlocked / detectBlockedGate / detectBlockedSince, so a verify-blocked builder now surfaces correctly in the VSCode tree, gate toast, and status-bar counter — and gets its own dedicated verified icon in the Builders tree per the #810 work above. Pre-v3.1.6, verify-approval was simply absent from VSCode's shared blocked-state vocabulary.

Prerequisite: BUGFIX got a pr gate (Bugfix #887, PR #888)

Required for #928 to work uniformly: BUGFIX's pre-#887 shape had a terminal pr phase with no gate, so its PRs never set the canonical signal at the right moment. After #888, BUGFIX behaves identically to AIR / SPIR / ASPIR / PIR at PR-ready time — Needs Attention surfaces them correctly without protocol-specific shims.

SCM colors on changed-file rows — actually this time (#799, PR #942)

A builder's expanded file list now reliably shows Added in green, Modified in yellow, Deleted in red — previously every row's filename either rendered grey, or briefly flashed the correct color and then turned grey.

A first attempt at this fix shipped in v3.1.4 based on the wrong theory: that VSCode's built-in Git FileDecorationProvider gates on URI scheme, so switching the row's resourceUri to a custom codev-builder-diff: scheme would keep Git out of the way. It doesn't. The actual mechanism is that Git's decorator matches resources by repository path, scheme-agnostically — so the row's path (still pointing into the gitignored .builders/<id>/ worktree) kept getting decorated as "ignored" by Git's grey-tinting branch. And all extension FileDecorationProviders share a fixed weight: 10, so an extension can't outrank Git in the color merge — the symptom "correct color flashes, then grey" was the resolution of that equal-weight merge on a ~500ms debounce.

The v3.1.6 fix uses a synthetic path in the resourceUri that resolves into no open repository, so Git's getRepository returns undefined and the row's color stands uncontested. The decorator, cache, and registration logic are unchanged.

Two engineering lessons captured during the investigation: VSCode's built-in Git decorator matches by repository path (not URI scheme), and extensions cannot outrank the built-in decorator's color via the public FileDecorationProvider API. Both lessons landed in codev/resources/lessons-learned.md for future contributors. The fix was verified at the dev-approval gate against the live Extension Development Host with the built-in Git extension enabled — not just at the URI-shape unit-test layer the prior attempt relied on.

Polish

Review-comment polish (#857, PR #900). The inline review-comment input shows a Codev-specific prompt instead of VSCode's generic placeholder, and submitted comments are attributed to your git identity (via git config user.name) instead of the hardcoded @architect.

Cleaner Marketplace command titles (#838, PR #866). Three command entries that surfaced poorly on the extension's public listing have been disambiguated: the palette command reads Codev: Open Builder Terminal... (the trailing ellipsis is VSCode's convention for "prompts for input" — ...

v3.1.4 Jacobean

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 #874 that the builder's own CMAP missed).
• Builders working under BUGFIX protocol across PRs #851, #871, and #874.

v3.1.3 Jacobean

v3.1.3 Jacobean

Released: 2026-05-24

Two structural ships and one cleanup, all in service of letting the panel-of-architects pattern run unattended for days at a time.

Workspace recover — survive machine reboots (PR #833, @amrmelsayed)

The missing piece in Tower's "leave it running" story. After a machine reboot or crash, in-flight builders go silent — worktrees and branches survive but the shellper processes don't. afx workspace recover enumerates porch projects, identifies builders whose shellper died, and respawns them.

afx workspace recover                  # dry-run preview (default)
afx workspace recover --apply          # actually respawn (with confirmation)
afx workspace recover --apply --yes    # unattended
afx workspace recover --max-age 30     # widen the recency window

• Builder conversation resume for SPIR / ASPIR / AIR / PIR / bugfix — the revived claude process picks up the prior session via --resume <uuid>, discovered from the on-disk jsonl store
• Main architect conversation resume after reboot, via the same jsonl-discovery mechanism (single-architect workspaces; multi-architect resume deferred to #832)
• Sequential respawn with bounded concurrency; idempotent — safe to re-run

Multi-architect: a panel, not a soloist

On large projects the work isn't one strand — it's several. UI to fix. Test infra to improve. Backend to refactor. Putting all of it in front of one architect agent makes a mess of the context — conventions, debugging strategies, and schema invariants all colliding. The agent gets worse at all three jobs as the day goes on.

Multi-architect treats the workspace as a panel. There's still a main "chief" architect with the broadest view, but you spin up sub-architects per subsystem:

afx workspace add-architect --name ui-refresh
afx workspace add-architect --name test-infra
afx workspace add-architect --name backend-cleanup

Each has its own context, its own thread, its own in-flight builders. When a builder finishes, it routes back to the architect that spawned it — not a single global inbox.

What you get in 3.1.3:

• afx workspace add-architect / remove-architect lifecycle
• Sibling architects survive afx workspace stop/start and afx tower stop/start
• Identity preservation across shellper auto-restart
• Cross-workspace isolation — sibling architects in workspace A no longer leak into workspace B
• Dashboard tabs + VS Code Architects tree with right-click Remove
• Per-builder attribution: builder cards show · <architect> when N>1
• Sibling-to-sibling messaging — afx send architect:ob-refine "..." from main or another sibling
• Per-builder thread files at codev/state/<builder-id>_thread.md for collective situational awareness

CLI cleanup: codev afx is no longer a thing (PR #847)

• codev afx <subcommand>, codev agent-farm <subcommand> removed (exit non-zero with a helpful stderr suggesting the right form)
• Standalone af bin removed — was deprecated since v3.0.1; afx is the canonical entrypoint
• Standalone afx bin path is unchanged
• Removes a cross-cutting process.argv[1] invocation-style fragility that surfaced in PR #833 integration review

VS Code extension (Amr Elsayed)

Multiple rounds across PRs #771, #779, #785:

• Per-builder file inspection — changed files inline; click for two-way diff
• Codev: View Diff — whole worktree delta in the Multi Diff Editor
• Accordion mode — expanding one builder auto-collapses the others
• Live-status dot for active builders, count badge on the activity-bar icon
• Idle-builder detection — chat-bubble after 5 min of silent waiting
• Backlog hides issues that already have a builder
• Image paste (Cmd+Alt+V)
• Architects tree with right-click Remove and live auto-refresh
• Dev URL rows in the sidebar (worktree.devUrls)
• Per-engineer .codev/config.local.json overrides

Also recent

• Multi-PR builders (Spec 653): worktree, branch, PR decoupled — one builder, multiple PRs; draft PRs mid-flight for early review
• Runnable worktrees: afx dev <builder-id> / afx dev main, swap-detection across slots
• PIR protocol: plan/implement/review with two pre-PR human gates — for design-sensitive or pre-PR-testable changes (mobile, UI, cross-platform)
• RESEARCH protocol: 3-way parallel investigation + synthesis + critique → codev/research/<topic>.md
• Linear hybrid forge: Linear issues + GitHub PRs
• Per-stage consults: each phase picks its own reviewer models
• Inter-agent messaging documented end-to-end — all four addressing forms with spoofing-check semantics

Breaking changes

• codev afx <…>, codev agent-farm <…>, codev af <…> no longer dispatch — they exit non-zero with a stderr pointing at the standalone afx bin. Workaround is a one-character edit (drop the codev prefix). External scripts that hardcoded codev afx will need to be updated.
• Standalone af bin removed (deprecated since v3.0.1). Use afx directly.

Install

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

Multi-workspace adopters: nothing new to do — the cross-workspace isolation migration landed in 3.1.2.

Contributors

• Amr Elsayed (@amrmelsayed) — afx workspace recover (PR #833) including 7 iterations of CMAP discipline that caught real bugs at every round; ongoing VS Code extension stewardship.
• M Waleed Kadous (@waleedkadous) — architect review, integration CMAP, the call to remove the codev afx wrapper surface rather than patch the spawn child.
• Builder working under AIR protocol on the CLI cleanup (PR #847).

v3.1.2 Jacobean

v3.1.2 Jacobean

Released: 2026-05-23

Critical patch on the Jacobean line. Fixes the cross-workspace sibling-architect leak introduced by v3.1.1's #786 lifecycle work — a release-blocker that surfaced within minutes of v3.1.1 going live (the architect's own machine experienced it during post-release verify of a new workspace).

Sibling architects no longer leak across workspaces (#826)

In v3.1.1, opening a workspace OTHER than the one that registered sibling architects caused those siblings to be re-spawned as fresh PTYs in the new workspace. Concrete symptom: shannon had ob-refine registered; opening manazil for the first time showed main + ob-refine + bug-backlog in manazil's terminal list, with new PIDs and real running claude processes none of which belonged to manazil.

Root cause

state.db.architect had no workspace_path column. The table was global per Tower-daemon (anchored to Tower's startup CWD). v3.1.1's #786 added a launchInstance reconcile loop that iterated this global table and re-spawned every architect it found — without any workspace-scoping check, because the data model didn't carry the scope. Pre-v3.1.1, the table was harmless because nothing iterated it; v3.1.1's new iterate-and-respawn loop turned the global table into an active cross-workspace leak.

The fix: schema-level workspace scoping

Migration v11 (in state.db):

• Add workspace_path TEXT NOT NULL column
• Composite primary key (workspace_path, id)
• Backfill workspace_path from global.db.terminal_sessions via ATTACH DATABASE, using architect.terminal_id as the disambiguation key (deterministic — the stable session UUID), with role_id LIMIT 1 as the fallback only when terminal_id has no matching session row
• Drop orphans (architects with no current terminal_session row)
• New index idx_architect_workspace on architect(workspace_path)

All state.ts accessors now require workspace context: getArchitects(workspacePath), setArchitect(workspacePath, …), setArchitectByName(workspacePath, name, …), removeArchitect(workspacePath, name), loadState(workspacePath). launchInstance and other callers thread workspacePath through.

All accessors canonicalize the passed workspacePath via realpathSync at the boundary — so symlinked workspace paths resolve to the same canonical key and the same architect row, regardless of which form the caller used.

Why per-site patching was rejected

The first three iterations of #827 tried to patch individual delete sites (deleteWorkspaceTerminalSessions, PtySession exit handlers, getTerminalsForWorkspace stale-cleanup) with isIntentionallyStopping guards to prevent the leaked rows from being preserved-then-deleted. Each iteration's CMAP caught the next delete site. After four sites and no clear stopping point, the architect-side review escalated to "the architecture is wrong, not the call sites" and the PR rewrote to Option A (schema-level scoping). The result is dramatically simpler — workspace isolation now falls out of the data model rather than depending on a maze of intent-flag guards.

Spec 786 stop+start MUST is preserved

The intentional-stop preservation mechanism from #786 stays — sibling architect rows still survive afx workspace stop + afx workspace start. With Option A, that preservation is now narrowly scoped to ONE concern (skip the architect-row delete on graceful stop), not "protect every site that could leak architects."

Migration ordering hotfix (#834, iter-7)

A late-cycle finding: an initial version of the migration placed CREATE INDEX idx_architect_workspace ON architect(workspace_path) in LOCAL_SCHEMA, which runs on every db.exec(LOCAL_SCHEMA) BEFORE migrations. On existing v10 databases, the architect table has no workspace_path column yet, so the index creation threw and the entire ensureLocalDatabase initialization aborted — breaking every upgrade install. Caught by the architect's local-install verification before publishing. Fixed by moving the CREATE INDEX out of LOCAL_SCHEMA and into the migration block itself (placed outside the alreadyMigrated guard so both fresh-install and upgrade-install paths land it). PR #834 ships alongside PR #827 in this release.

Process notes

This bug fix went through 7 iterations of CMAP-driven review across two PRs (#827 + #834). Each iteration's independent architect-side CMAP caught a finding the builder's own CMAP missed: the original race in the cross-workspace fix, then a stop+start regression, then exit-handler delete leakage, then getTerminalsForWorkspace stale-cleanup, then migration disambiguation non-determinism, then path-canonicalization mismatch, then the migration-ordering bug that broke upgrade installs. The two-CMAP discipline (builder runs one, architect runs an independent one) caught real bugs at every iteration — single-CMAP review on this PR would have shipped a regression.

Lesson saved in the architect's working memory: when builder's CMAP and architect's CMAP converge differently, the architect's CMAP isn't sloppiness — it's signal. Run both, trust the conjunction.

Breaking changes

None at the user-visible API level. The migration is automatic on first state.db read after upgrade.

For TypeScript consumers of @cluesmith/codev-core or internal state accessors: getArchitects, setArchitect, setArchitectByName, removeArchitect, loadState now require a workspacePath parameter. This is internal API; CLI / dashboard / VSCode extension consumers are unaffected.

Install

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

If you were running v3.1.1 with multiple workspaces, this release silently fixes the leak on Tower restart (migration v11 runs automatically). Confirm by opening a previously-unused workspace and verifying its architect list shows only the workspace's own architects.

Contributors

• M Waleed Kadous (@waleedkadous) — reported the leak within minutes of v3.1.1 install (own machine), drove the 7-iteration CMAP discipline that caught every issue including the migration-ordering release blocker.
• External Codev consumers — implicit pressure on multi-workspace correctness; the bug would have surfaced on every two-workspace adopter eventually.
• Builder working under BUGFIX protocol across PRs #827 and #834.

v3.1.1 Jacobean

v3.1.1 Jacobean

Released: 2026-05-23

First minor on the new Jacobean line. Bundles four substantial threads of work that landed since v3.0.7: a critical multi-architect routing fix that the v3.0.5 / v3.0.6 verify phases never caught, two large VS Code extension rounds from Amr, the multi-architect lifecycle/persistence/UX feature pass (Spec 786), and the multi-architect coordination follow-up (Spec 823 — dashboard attribution, inter-agent messaging docs, builder thread files, VS Code Architects tree refresh).

Note on numbering: this release skips v3.0.8 (locally built, never published — superseded by accumulated work) and v3.1.0 (briefly published as orphan dep-only packages under a since-rejected "Jugendstil" name; @cluesmith/codev never reached 3.1.0 and dist-tags.latest stayed at 3.0.7, so users see a clean 3.0.7 → 3.1.1 upgrade path).

Multi-architect routing — actually works now (#774 → PR #775)

The headline value prop of sibling architects ("a builder spawned by ob-refine, when it sends to architect, reaches ob-refine") was non-functional from v3.0.5 → v3.0.7. The primitive shipped in v3.0.5, the dashboard tabs in v3.0.6, but every builder→architect message routed to main regardless of which sibling spawned the builder. Reported by external adopter Shannon within hours of v3.0.7's install.

Root cause: detectCurrentBuilderId() opened the worktree's empty .agent-farm/state.db via the singleton getDb(), missed the canonical builder ID lookup, and fell back to the worktree directory name (e.g. bugfix-1599) instead of the canonical builder-bugfix-1599. Downstream lookupBuilderSpawningArchitect returned undefined for that short ID, the affinity branch was skipped, and routing defaulted to main.

The fix opens the workspace's state.db directly (readonly), mirroring the existing per-workspace-handle pattern in state.ts:lookupBuilderSpawningArchitect. End-to-end verified against shannon's real two-architect workspace before tagging: ob-refine-spawned builder's message landed on ob-refine's terminal 7e3dc4fe..., not main's 48784891....

Lesson saved: the v3.0.5 verify phase never ran the one sentence the spec promised. Going forward, release verification for any "X command does Y" claim must include literally running X and observing Y, on a real workspace, not just unit tests on the primitive. See feedback_e2e_headline_path in the architect's working memory.

Multi-architect lifecycle, persistence, and UX (#786 → PR #822)

A seven-phase feature pass that finishes the multi-architect coherence story started in v3.0.5/v3.0.6.

remove-architect is now a first-class lifecycle operation

afx workspace remove-architect <name>

Refuses to remove main. Refuses unknown names. With in-flight builders, removes anyway and routes their subsequent afx send architect calls to main via the existing fallback (OQ-A: remove-anyway design — minimal new state, matches crash-recovery semantics).

Dashboard parity: sibling architect tabs in the multi-architect tab strip now carry a close button (×) that invokes the same backend lifecycle, with a confirmation modal that surfaces any in-flight builders the sibling spawned (informational; doesn't block removal). main's tab has no close button.

VS Code parity: the workspace sidebar now has an expandable Architects tree node (per OQ-D); right-clicking a sibling shows Remove Architect in the context menu (viewItem == workspace-architect-sibling). main (workspace-architect-main) gets no remove option.

Sibling architects survive graceful stop/start

afx workspace stop followed by afx workspace start now preserves sibling architect rows. Previously the graceful-stop path deleted every row via clearState() (CLI side) and deleteWorkspaceTerminalSessions (server side), so siblings were lost on every stop. Now:

• Server side: an intentionallyStopping flag suppresses the exit-handler cascade that would otherwise delete the persisted state.db.architect row when the PTY is killed.
• CLI side: stop.ts calls a new clearRuntime() variant that skips DELETE FROM architect (preserving the registration) while still clearing builders/utils/annotations.
• Restart side: launchInstance reconciles persisted siblings, re-spawning their terminals with CODEV_ARCHITECT_NAME re-injected so affinity routing keeps working.

Race condition fix (post-PR Codex CMAP catch)

The initial implementation cleared intentionallyStopping in finally before the async PTY exit handlers had fired — leaving a timing window in which the handlers still saw the flag as cleared and deleted the row anyway. Caught at architect integration CMAP. Fixed by collecting once('exit', resolve) promises and awaiting all of them (with a 5s safety timeout) before clearing the flag. Same fix applied to handleWorkspaceStopAll. Behavioral test exercises the timing window; unit tests alone never caught it.

Identity preservation across shellper auto-restart

When shellper auto-restarts a sibling's claude process (max-restart loop), the new process now spawns with CODEV_ARCHITECT_NAME=<sibling-name> in env — previously restartOptions.env was built from process.env only, so a restarted sibling silently lost its affinity identity, and builders spawned afterward routed to main. The reconciliation path at tower-terminals.ts:559-567 and the workspace-status path at :773-776 both inject the name from dbSession.role_id.

Surface parity

afx status now enumerates ALL architects (post-#786):

[info] Architects:
[info]   main (pid=20807 terminal=a16f1b60-8250-...)
[info]   ob-refine (pid=66756 terminal=0ce8f578-9bf6-...)

The v1 "collapse all architects into a single Architect entry" logic at tower-terminals.ts:928-940 is removed. The Tower /status endpoint and dashboard both see the per-architect collection. validateArchitectName now rejects main as a reserved name (previously rejected only by collision with the running main architect).

Architect-to-architect messaging documented (already worked in code)

main can send to ob-refine via afx send architect:ob-refine "..." — sender-is-architect bypasses the spoofing check, so this has worked since v3.0.5. It just wasn't documented anywhere.

Mobile solo-architect tab label restored to "Architect" (#764)

Previously the mobile TabBar showed main instead of Architect on solo-architect workspaces. The N=1 label is now 'Architect'; N>1 uses the architect name. Folded into #786's useTabs.ts:buildArchitectTabs work.

Multi-architect coordination — attribution, messaging, threads, refresh (#823 → PR #824)

A four-deliverable follow-up to #786 that completes the coordination story.

Dashboard builder attribution (N>1)

When state.architects.length > 1, each builder card now shows a · <architect> separator-style attribution next to the builder ID:

● builder-spir-42
  #0042 · ob-refine
  feature: add support for X

N=1 workspaces stay DOM-identical to before. The OverviewBuilder.spawnedByArchitect field is now a required shape on @cluesmith/codev-types (TypeScript-facing change worth flagging for consumers).

Inter-agent messaging documented end-to-end

CLAUDE.md and AGENTS.md (kept synchronized) gain a new "Inter-agent messaging" section documenting all four addressing forms — afx send <builder-id>, afx send architect, afx send architect:<name>, afx send <workspace>:architect — with the spoofing-check constraint that's load-bearing for builders. Discovery patterns for sibling architects (afx status) and active builders (ls .builders/*/codev/state/*.md, post-merge ls codev/state/) are also surfaced. No code change — the primitives already existed; this release closes the documentation gap.

Per-builder thread file convention

Each builder now maintains a free-text markdown thread at codev/state/<builder-id>_thread.md. The builder writes natural-language notes — phase transitions, decisions, blockers — for collective situational awareness across the cohort. No structured schema, no porch hooks, no required format. Just a markdown file. Each builder's role prompt now contains the maintenance instruction; the file is committed at PR time so the thread joins the historical review record. The first dogfood thread (codev/state/spir-823_thread.md) is committed in this release.

VS Code Architects tree auto-refreshes on architect add

Previously the VS Code Architects tree refreshed on remove (the command self-triggered the refresh) but stayed stale on CLI-side afx workspace add-architect until the user clicked Refresh. The asymmetry was caused by Tower having no SSE event for architect lifecycle changes. This release adds:

• Tower side: an architects-updated SSE event emitted on every addArchitect / removeArchitect / launchInstance reconcile call, with { workspace: <path> } payload — same shape as the existing worktree-config-updated event.
• VS Code side: WorkspaceProvider subscribes via the existing onSSEEvent channel, fires changeEmitter.fire() unconditionally on receipt (matching the existing worktree-config-updated pattern; workspace-filtering is unnecessary since each VS Code window is rooted at one workspace).

Dashboard parity falls out of existing polling.

VS Code extension — two substantial Amr rounds (PR #771 + PR #779 + PR #785)

Big workflow improvements across two batches. Highlights:

Per-builder file inspection

• Per-builder changed files inline. A builder row in the Builders view is now expandable to the list of files it changed vs the default branch; clicking a file opens its two-way diff (read-only merge-base base ↔ worktree file). Rows use VS Code's native Source Control look — file-type icon plus a colored A/M/D/R/C/T status badge tinted via the theme's `...

v3.0.7 Ionic

v3.0.7 Ionic

Released: 2026-05-18

A patch on the Ionic line that fixes two regressions shipped in earlier 3.0.x releases — the multi-architect dashboard pane collapsing to ~1/4 height (introduced in 3.0.6), and the Gitea/Forgejo forge crashing Tower overview (since 3.0.3).

Multi-architect dashboard pane fills the SplitPane (#766 → PR #767)

PR #762 in v3.0.6 introduced .architect-pane / .architect-pane-body wrappers in the multi-architect (N>1) left-pane render path, but never added matching CSS. The wrappers collapsed to intrinsic height, shrinking the architect terminal to roughly 1/4 of the SplitPane left side.

The fix uses position: absolute; inset: 0 on .architect-pane so it fills the relatively-positioned parent regardless of the parent's height computation. Solo-architect workspaces (N=1) use a different render path that was never broken.

A Playwright regression test now pins the invariant: in an N=2 workspace, .architect-pane height must match .split-left within 2px, and .architect-pane-body must reach the bottom of the SplitPane left side. The test was written to fail against the v3.0.6 state and pass against the v3.0.7 fix.

Gotcha worth knowing: by default Playwright tests hit localhost:4100, which serves the globally-installed dashboard, not the worktree's built bundle. Setting TOWER_TEST_PORT=<unused-port> spawns a fresh Tower from the worktree — that's what you need for actual change verification. The architect-pane-layout test enforces this implicitly; future dashboard tests should follow the same pattern.

Gitea/Forgejo forge crashes and field-name normalization (#749 + #750 → PR #768)

External adopter Chris Dodge (@pseudoseed) reported two coupled regressions running Codev against a Forgejo instance:

#749 — labels.map is not a function 500 on Tower overview

Forgejo/Gitea returns labels: "" or null for unlabeled issues, where GitHub always returns []. parseLabelDefaults() in lib/github.ts called .map() unconditionally and crashed.

Fix: coerce non-array inputs to [] before mapping (Array.isArray(labels) ? labels.map(...) : []), widen the parameter type to reflect the cross-forge runtime shape, add 4 regression tests covering empty-string / null / undefined / array paths.

#750 — #undefined and NaNd in Tower overview for Gitea

Once the 500 was patched, Tower overview displayed #undefined for every issue number and NaNd for every age — the Gitea preset scripts piped raw tea --output json straight through, but tea's field names don't match the GitHub-compatible shape Tower expects.

Fix: each of the four affected forge scripts (issue-list.sh, pr-list.sh, recently-closed.sh, recently-merged.sh under scripts/forge/gitea/) now requests an explicit --fields list and normalizes via jq:

tea returns	Tower expects
index (string)	number (int)
created	createdAt
author (flat string)	author.login
labels (CSV or "")	labels[].name
assignees (CSV or "")	assignees[].login
description	body

recently-closed.sh maps updated → closedAt; recently-merged.sh filters select(.merged == true) and maps updated → mergedAt. jq was already a runtime dep of the Gitea preset (pr-exists.sh, user-identity.sh).

Verified end-to-end on the reporter's Forgejo instance. Acknowledged test debt: no committed fixture-based test for the jq filters; CMAP-Codex flagged this as a REQUEST_CHANGES, accepted as cost-benefit (4 unit tests cover the upstream TypeScript path, reporter verified runtime, fixture tests would add ~30 min for limited value).

Breaking changes

None.

Install

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

If you're running v3.0.6 with multiple architects, this release fixes the broken dashboard layout. If you're running Codev against a Forgejo / Gitea instance, this release fixes the Tower overview crash and the #undefined / NaNd rendering.

Contributors

• Chris Dodge (@pseudoseed) — reported #749 and #750 with verbatim suggested fix shapes; verified end-to-end against Forgejo.
• External Codev consumer (Shannon multi-architect testing) — surfaced the architect-pane layout regression.
• M Waleed Kadous (@waleedkadous) — architect review, release coordination.
• Builders working under BUGFIX protocol.

v3.0.6 Ionic

v3.0.6 Ionic

Released: 2026-05-18

A patch on the Ionic line that finishes the multi-architect work started in v3.0.5 (now usable from a browser) and lands Amr's PIR protocol plus a substantial VSCode-extension workflow round.

Multi-architect dashboard tabs (#761 → PR #762)

v3.0.5 shipped the multi-architect routing primitive but deferred the UI surface — the result was that humans could register sibling architects via afx workspace add-architect but had no clickable way to access them from the dashboard. That was correctly called out as half-shipped. This release fixes it.

What's new

• /api/state exposes the full architects collection alongside the existing scalar architect pointer (backward compatible). Each entry carries { name, terminalId, port, pid, persistent }.
• Dashboard renders one tab per architect when N > 1. A small tab strip appears inside the left pane on desktop; on mobile the architect tabs join the main TabBar.
• First architect tab uses bare id: 'architect' (stable across the N=1 ↔ N>1 transition); subsequent siblings use id: 'architect:<name>'.
• Active architect tab persists per workspace in localStorage (keyed by URL pathname to avoid cross-workspace collision).
• Deep links: ?tab=architect:<name> selects the named tab; unknown names fall back to the first architect; the bare ?tab=architect continues to work.
• Persistent WebSocket model preserved. Switching architect tabs does not unmount terminals — the existing activatedTerminals lazy-mount + keep-alive pattern from Bugfix #205 is extended to architect tabs, so there's no reconnect-flicker on click.
• Left-pane architect selection is independent of global activeTabId. Clicking an architect tab on the left doesn't blank the right pane. (Caught at plan-phase Codex review; implementation routes around the issue with a separate activeArchitectName state.)

Single-architect workspaces

Desktop solo-architect workspaces are DOM-snapshot-identical to pre-#762 — same bare terminal in the left pane, no tab strip. A known minor cosmetic regression affects mobile + solo-architect users only: the bottom TabBar tab labeled Architect is now labeled main. Tracked as #764 for a 1-line follow-up.

Why this matters

The sibling-architect pattern (driving multiple architect agents in one workspace) is now first-class through the browser. Customers using Codev for large multi-thread initiatives can switch between architect terminals with a click; messages from each architect's builders route to that architect via the v3.0.5 affinity primitive.

PIR protocol (#691 → PR #763)

Amr landed a new protocol: PIR — Plan → Implement → Review. Sits between BUGFIX/AIR (lightweight) and SPIR (full ceremony). The issue body is the implicit spec — there is no spec phase.

Three human gates:

• plan-approval — architect approves the plan before any code is written.
• dev-approval — architect reviews the running worktree (not a PR diff) before the PR is created. Use this for mobile/UI/cross-platform changes where the running code needs visual sign-off.
• pr — post-PR merge-synchronization gate (matches SPIR pattern).

PIR is the right choice when the issue is clear enough to skip spec ceremony but the work still needs design review before coding starts, or live verification before a PR exists.

VSCode extension workflow improvements (#737 → PR #763)

Amr expanded the VSCode extension significantly:

• Workspace dev server runner (codev.runWorkspaceDev) — counterpart to the existing Run Dev Server for builder worktrees, now for the main workspace itself.
• Open worktree in new VSCode window (codev.openWorktreeWindow) — sidebar context-menu action.
• View Issue (codev.viewIssue) — opens the GitHub issue for a builder directly from the sidebar.
• View Artifact (codev.viewArtifact) — opens the spec / plan / review for a project.
• Gate notification toasts — VSCode shows toast notifications when a builder hits a gate (plan-approval, pr-ready, etc.), with click-through to the relevant artifact.
• Plan-review comment integration — review comments on the plan can be authored directly in VSCode and pushed back to the builder.
• Backlog tree view rebuilt; Needs Attention view removed (subsumed into the new gate-toast notifications + Backlog view).
• Review-diff command consolidated into existing diff workflows.

This is a substantial refresh of the IDE side of Codev. See packages/vscode/CHANGELOG.md for the full list.

Other

• Team CLI: team activity now uses GitHub's search.issueCount for true per-member counts (previously paged results misreported).
• DB migration: reintroduced v10 local DB migration for the pir builder type (needed for the new protocol).
• Project paperwork: spec/plan/review for #761, plus iter rebuttals, committed for the historical record.

Breaking changes

None. Single-architect workspaces unchanged on desktop. PIR is additive — existing protocols are untouched.

Install

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

Contributors

• External Codev consumer (Shannon) — reported the multi-architect-routing-without-UI gap that motivated #761; previously reported the sibling-architect pattern and the 5 tier-1 issues shipped in v3.0.5.
• Amr Elsayed (@amrmelsayed) — PIR protocol design and implementation, VSCode workflow round, team activity fix.
• M Waleed Kadous (@waleedkadous) — architect role, driving spec/plan iterations.
• Builders working under SPIR and PIR protocols.

v3.0.5 Ionic

v3.0.5 Ionic

Released: 2026-05-18

A patch on the Ionic line driven almost entirely by an external Codev consumer's production use of the sibling-architect pattern. Two substantial new features (multi-architect message routing, baked architectural decisions) and three workflow bugfixes — all caught and reported via the team channel.

Version note: 3.0.4 was published to the VS Code marketplace only (codev-vscode side). This release moves the entire lockstep — @cluesmith/codev, @cluesmith/codev-core, @cluesmith/codev-types, and codev-vscode — to 3.0.5 together. Solo-architect users see no behavior change from 3.0.3.

Multi-architect message routing (#755 → PR #757)

Codev workspaces have always assumed a single architect terminal. The sibling-architect pattern — where one human operator drives two or more architect agents in the same workspace, each owning a disjoint slice of work — has emerged in production usage on a large customer project. With one architect, afx send architect from any builder lands in the shared singleton; humans then manually decide "is this mine?" and copy-paste the message to the right architect. This release makes that routing automatic.

What's new

• Multiple architect terminals per workspace. Tower's in-memory WorkspaceTerminals.architect and the local architect SQLite table (and terminal_sessions.role_id) now key on a stable name rather than a singleton row. The schema migration (v9 local, v13 global) is forward-only per the project convention; existing single-architect workspaces are rekeyed transparently.
• Naming policy. First architect started in a workspace defaults to main; subsequent siblings auto-number architect-2, architect-3, …. Either can be overridden with an explicit name via the new afx workspace add-architect [--name <name>] subcommand. Allowed charset: [a-z][a-z0-9-]*, max 64 chars; collisions rejected.
• Spawn-time capture. Every afx spawn now writes spawned_by_architect: <name> onto the builder's persisted row, detected automatically from the architect terminal's CODEV_ARCHITECT_NAME env var (injected by Tower at terminal-start). Spawns outside any architect terminal default to main.
• Affinity-aware routing. When a builder runs afx send architect "...", the resolver now looks up that builder's spawned_by_architect and delivers the message only to that architect's terminal — sibling architects do not receive it. Non-builder senders (cron-routed messages, manual sends from the workspace root) continue to resolve to main (or the first registered architect if main is absent).

Backward compatibility

Zero behavior change for solo-architect workspaces:

• /api/state.architect stays scalar (populated with main or first registered).
• The dashboard and VS Code extension see one architect tab, identical to today.
• Builders persisted before this release (no spawned_by_architect field) route to main if present, else fail with a clear error listing the registered architects.

Why a new subcommand instead of afx architect --name

The existing afx architect runs a local Claude session with stdio: 'inherit' and explicitly disclaims Tower — it works in any directory, even outside a workspace. Adding --name semantics would break that no-Tower contract for current users. The new Tower-aware subcommand lives under the workspace noun (next to start, stop, rename), which keeps the existing command intact.

Security

• A builder spoofing architect:<some-other-name> (a name that is not its own spawned_by_architect) is rejected with a clear, test-asserted error.
• Architect-gone (the spawning architect's terminal was killed) falls back to main if present; otherwise fails with a distinct error.

What's deferred

afx status --architect <filter>, surfacing all architects in /api/state, the THREAD.md template + lifecycle, cross-thread visibility, and thread-aware consult are tracked as follow-up issues. Issue #758 tracks the deferred end-to-end Tower-process integration test (the routing matrix is covered by 18 unit tests + direct SQLite + route-handler tests; the e2e is documented technical debt).

Baked architectural decisions for SPIR/AIR/ASPIR (#746 → PR #756)

Architects often have strong priors on a major decision (language, framework, deployment shape, key dependencies) before filing an issue. Until now those priors had nowhere structured to live — buried in prose, easy to miss, easy for CMAP reviewers to override in good faith. The result: spec drafted against an assumed default, iter-2 CMAP reviews that wrong assumption, architect intervenes at iter-3 to override — and iter-2's feedback becomes obsolete.

How to use it

Include a ## Baked Decisions section (any heading level, case-insensitive) in the GitHub issue body before spawning a SPIR/AIR/ASPIR builder. Example:

## Baked Decisions

- Language: Python (match shanutil)
- Framework: FastAPI
- Deployment: deferred to a follow-up spec

The builder treats those decisions as fixed inputs to the spec. CMAP reviewers (Codex, Gemini, Claude) are told to honor them — they may COMMENT with concerns about a baked decision, but REQUEST_CHANGES is reserved for the case where the spec fails to honor a stated decision. The architect retains authority to rescind or amend a baked decision at any time via afx send.

Design properties

• Optional by default. Empty or missing section = full exploration, identical to today's behavior.
• No code surface. Pure prompt + documentation change — the LLM finds the section in the issue body and honors it because the prompt tells it to. No regex parser, no template-context plumbing. Handles variant section names and inline-in-prose baked decisions more robustly than a parser would.
• Architect-override carveout woven through every prompt. Builder prompts say "do not autonomously override" (not "forbidden to question") — so the architect can always rescind a baked decision and the prompt language doesn't fight them.
• Contradiction handling. If two baked decisions contradict each other, the builder pauses and flags via afx send rather than picking one. Reviewers REQUEST_CHANGES and ask the architect to clarify.

Test coverage

An 808-line test file covers grep assertions for the required instruction language across all 12 affected prompts (SPIR/ASPIR builder-prompt + drafting prompt + spec-review + plan-review, AIR builder-prompt + implement + impl-review + pr-review), pure-addition diff against 12 recorded baselines (so any inadvertent edit elsewhere in the prompts fails the test), and codev/ ↔ codev-skeleton/ byte-identical parity.

Bugfixes (#742, #744, #745)

Three workflow bugs reported by a Codev consumer using the bugfix protocol heavily:

Codex misapplied SPIR criteria to BUGFIX PRs (#742)

The bugfix protocol's consult-types/pr-review.md and impl-review.md templates were byte-identical to the SPIR versions, causing Codex to REQUEST_CHANGES on legitimate BUGFIX PRs for missing codev/specs/plans/reviews artifacts, for [Spec NNNN] commit format (BUGFIX uses Fix #N:), and for status.yaml.build_complete: false (porch-managed, not builder-fixable). Each PR cost 2–3 iter cycles of the builder writing protocol-defending rebuttals.

The fix rewrites both bugfix templates around what BUGFIX actually produces (GitHub Issue + fix + regression test) and adds an explicit Out of Scope section naming each of the three SPIR-only criteria to forbid. A regression test pins divergence from the SPIR templates so accidental re-syncing fails CI.

SPIR/ASPIR builder-prompt allowed per-phase PRs (#744)

The SPIR/ASPIR builder-prompt.md did not explicitly state the one-PR-per-spec convention; builders interpreted the plan's "each phase commits independently" as "each phase opens its own PR." A new PR Strategy section now makes this explicit, with an architect-override carveout for cases where the architect requests a PR earlier (e.g., for spec review, mid-implementation feedback, or slicing a large spec into shippable PRs).

The carveout phrasing — "do not autonomously open a PR per implementation phase" rather than absolute prohibition — is the pattern we now reuse for any builder-constraining prompt rule. Memorized for future prompt edits.

afx spawn dirty-worktree check was too strict on untracked files (#745)

git status --porcelain flags untracked files (?? status) alongside modified-tracked ones. Repos with chronic untracked artifacts (e.g., bin/ from pnpm local-install, .claude/scheduled_tasks.lock, build outputs) forced --force on every spawn, defeating the safety check entirely.

The check now uses git status --porcelain --untracked-files=no — it still catches the case where an architect git add-ed a new spec but forgot to commit (the index entry shows as tracked), while ignoring chronic untracked artifacts. Documented tradeoff: a file that's created but never staged won't trigger the check; if the architect wants that protection, git add before spawn restores it.

Other improvements

• @openai/codex-sdk bumped 0.101.0 → 0.130.0 to clear an XProtect cert-revocation issue on macOS (#752, Amr).

Breaking changes

None. Solo-architect workspaces are unchanged. The new ## Baked Decisions section is opt-in (absence = no-op).

Install

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

Contributors

• External Codev consumer (Shannon) — reported the SPIR-vs-BUGFIX template mismatch, the SPIR one-PR ambiguity, the chronic-untracked spawn issue, the architect's-baked-decisions need, and the sibling-architect/multi-architect-routing pattern. Five tier-1 reports filed via team channel; this release ships every one.
• Amr Elsayed (@amrmelsayed) — codex SDK XProtect cert revocation fix.
• **M Waleed Kadous...

v3.0.3 Ionic

v3.0.3 Ionic

Released: 2026-05-12

A patch update on the Ionic line that turns .builders/<id>/ worktrees into runnable, reviewable environments — from both the CLI and the VS Code sidebar — and aligns the workspace on a single lockstep version. Almost all of this release is the work of Amr Elsayed (@amrmelsayed).

Runnable worktrees (#689 + #690, PR #731)

Builder worktrees were already isolated git checkouts. They are now first-class environments you can install, run, and review.

New worktree block in .codev/config.json

Opt-in, zero behavior change for repos that don't add it:

{
  "worktree": {
    "symlinks": [
      "apps/web/.env",
      "apps/server/.env"
    ],
    "postSpawn": [
      "pnpm install",
      "cd apps/server && uv sync"
    ],
    "devCommand": "pnpm dev:local"
  }
}

• symlinks — files/globs symlinked from the main worktree into the builder's worktree on spawn. Designed for .env files and other host-only secrets you don't want copied into a sibling checkout.
• postSpawn — commands run inside the builder's worktree right after creation. Output streams live to the spawn terminal via the new runStreaming helper, so pnpm install / uv sync progress is visible instead of buffered.
• devCommand — the command afx dev <builder-id> and Run Dev Server invoke.

New CLI commands

• afx dev <builder-id> — spawn the worktree's dev server as a Tower-managed PTY. Serial swap by design: only one builder's dev is running at a time, so OAuth callbacks, CORS allowlists, cookie scoping, and webhook URLs keep working without reconfiguration.
• afx setup <builder-id> — re-apply worktree.symlinks and re-run worktree.postSpawn against an existing worktree. Handy after lockfile changes, evolving config, or recovering from an aborted spawn.

Dev terminals are ephemeral by design — they die with Tower and are not persisted to SQLite. The 'dev' TerminalType was added to @cluesmith/codev-core/tower-client and gated at tower-routes.ts. Killing a dev PTY signals the entire process group (SIGTERM → SIGKILL after 5s), so a monorepo pnpm dev with N children gets cascade-killed by one syscall.

VS Code sidebar context menu

Right-click any builder row in Builders or Needs Attention:

Codev: Open Builder Terminal
─────────────────────────────────
Codev: Open Worktree Folder        ← OS file manager
─────────────────────────────────
Codev: View Diff                   ← unified main↔HEAD multi-file diff
─────────────────────────────────
Codev: Run Worktree Setup          ← shells out to `afx setup`
Codev: Run Dev Server              ← spawns the dev PTY
Codev: Stop Dev Server

View Diff uses vscode.changes for a single tab with a file-list pane, instead of opening N diff editors. The brand icon is now theme-aware (light/dark SVG pair) so it doesn't render as a black square on dark themes.

Plus command-palette tightening: hidden palette entries that need a builder-id argument, and a BuilderTreeItem subclass so context-menu commands resolve the right builder regardless of which row was right-clicked.

Recipes

CLAUDE.md and AGENTS.md gain a Runnable Worktrees section with copy-paste recipes for pnpm monorepo, npm, yarn, bun, cargo, poetry/uv, and go mod stacks.

Lockstep version bumps (#692, PR #732)

pnpm bump-version replaces the per-package pnpm version flow. Anchors on root package.json (Vue/Babel pattern), updates root + every publishable workspace package in one shot, and preserves byte-level JSON formatting (the regex-only rewrite avoids the JSON.stringify churn that would have rewritten compact arrays in packages/vscode/package.json).

Command	Effect
pnpm bump-version	Patch bump from the current root version
pnpm bump-version patch / minor / major	Semantic bumps
pnpm bump-version 3.1.0-rc.1	Explicit version (auto-skips packages/vscode because the VS Code Marketplace rejects pre-release suffixes)

This release is the one-time alignment that pulls @cluesmith/codev-core and @cluesmith/codev-types up from their stale 0.0.x values to match @cluesmith/codev. From now on, every workspace package ships at the same version — closing the class of bug where the main package shipped pointing at outdated internal deps.

prepublishOnly: pnpm build is now wired on packages/core and packages/types so dist/ can't be stale at publish time. The release protocol's Step 4 was rewritten around the new flow; the backport path keeps the per-package pnpm version semantics.

VS Code reliability and sidebar UX (PR #729)

Three themes in one bundle — Amr's PR #682 review follow-up, sidebar UX, and the #718/#728 bugfixes.

PR #682 follow-up

• Dropped the SSE rate limiter. Every consumer self-throttles where it matters (the overview-data loading guard, tree views' batched EventEmitters), so the 1s coalescer was solving a problem that wasn't there while creating a real one — a builder-spawned event arriving inside a coalesced overview-changed window was silently dropped. Removed entirely.
• openBuilder close-race fix. When a stale terminal is replaced under the same mapKey, the stale onDidCloseTerminal event can fire after registration; the new entry was being deleted from under itself. Identity-check the current map entry before deleting.
• Workspace path normalization in BuilderSpawnHandler so trailing-slash variants don't drop events. Plus new unit coverage for parsing/dedup/path-norm/mode-dispatch (builder-spawn-handler.test.ts, sse-client.test.ts) and a contract test pinning BuilderTerminalLinkProvider to a pure regex implementation.

Sidebar UX

• Clickable rows. Builders and Needs Attention rows now open the builder's terminal on click. Resolution goes through TerminalManager.openBuilderByRoleOrId — one shared path for link-provider, sidebar, and palette.
• Tail-match builder IDs. Fixes the "No active terminal for 153" toast: sidebar IDs were '153', Tower's runtime IDs were 'builder-spir-153'. resolveAgentName and stripLeadingZeros moved into a new @cluesmith/codev-core/agent-names subpath shared by agent-farm and vscode.
• Focus parameter threaded through the terminal-open path. Click paths opt in; auto-spawn paths don't steal focus mid-typing. Also primes new pseudoterminals with an empty write to work around microsoft/vscode#108298 (writes emitted before open() are dropped, leaving the pane blank until first input).
• Codev SVG terminal icons. Architect, builder, and shell tabs now show the Codev mark instead of >_.
• New Workspace sidebar view above Needs Attention: Open Architect and Open Web Interface entries, sharing codev.openArchitectTerminal with the palette and Cmd-K A keybinding.

Bugfixes #718, #728, #688

• #718 — VS Code extension wasn't showing builder terminals from Tower. Tower's wsTerminals rehydration is now centralised so /api/overview self-heals like /api/state. The extension also activates the workspace before announcing 'connected', and the sidebar gains refresh + reconnect buttons.
• #728 — Cold-start failures can leave VS Code stuck Offline. New codev.reconnect command + status-bar click; connect() has a re-entry guard; cold-start self-heal added.
• #688 — Review nits on local-install.sh addressed.

Breaking changes

None. The new worktree config block is opt-in; the version-bump scripting is internal; sidebar UX and bugfixes are purely additive.

Migration

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

To opt into runnable worktrees, add a worktree block to .codev/config.json and codev update. See the new Runnable Worktrees section in CLAUDE.md for stack-specific recipes.

Install

npm install -g @cluesmith/codev@3.0.3

Contributors

• Amr Elsayed (@amrmelsayed) — runnable worktrees, VS Code review tooling, lockstep version bumps, sidebar UX, PR #682 follow-up
• M Waleed Kadous (@waleedkadous) — release coordination
• MachineWisdomAI — bugfixes #718 / #728 / #688 follow-up under parallel agent
• Builders working under SPIR, ASPIR, AIR, and BUGFIX protocols

v3.0.2 Ionic

v3.0.2 Ionic

Released: 2026-05-07

A patch update on the Ionic line. Three notable additions — a Linear forge provider with hybrid GitHub fallback, an opt-in Bridge Mode for Tower, and a documentation governance pass that converts the architecture-documenter agent into a discoverable skill — plus a handful of bug fixes.

New (opt-in)

Hybrid forges: Linear issue tracking with GitHub PR fallback (#716, #719)

The forge layer now supports partial provider implementations. Linear-for-issues + GitHub-for-PRs is the canonical hybrid: a Linear provider supplies six issue concepts (auth-status, user-identity, issue-view, issue-list, issue-comment, recently-closed) while PR concepts fall through to GitHub.

The architectural improvement that unlocks this: buildPresetFromScripts now omits missing concepts instead of writing null, so unimplemented concepts cascade to the default provider. This benefits any partial-provider scenario, not just Linear.

Also in this work:

• Issue identifiers are widened to string | number throughout the agent-farm CLI, type system, and DB layer (so ENG-123 works alongside 42)
• db_builders.issue_number migrated from INTEGER → TEXT
• Forge config non-concept keys (e.g., linear-team) are exported to provider scripts as CODEV_LINEAR_TEAM

Configure in .codev/config.json:

{
  "forge": {
    "provider": "linear",
    "linear-team": "ENG"
  }
}

Set LINEAR_API_KEY in your environment.

Bridge Mode for Tower (#721)

Tower now has an opt-in path for binding to non-localhost addresses, intended for container-bridging scenarios where Tower runs inside a sandboxed Docker environment and the host browser/CLI needs to reach it.

Two environment variables, both required to expose Tower beyond localhost:

• BRIDGE_MODE=1 — explicit opt-in flag. Without it, Tower binds to 127.0.0.1 regardless of other settings.
• BRIDGE_TOWER_HOST — bind address when bridge mode is enabled (e.g. 0.0.0.0). Only consulted when BRIDGE_MODE=1. Accepts 127.0.0.1, 0.0.0.0, localhost, valid IPv4 literals, and bracketed IPv6 literals.

When bridge mode is enabled, Tower logs a startup warning. Tower has no built-in authentication — if you enable bridge mode, your firewall is the security boundary.

For remote access without container bridging, cloud.codevos.ai remains the recommended path.

Documentation governance (#723)

The architecture-documenter agent has been retired and replaced by an update-arch-docs skill, propagated to all projects via codev update. The MAINTAIN protocol now carries a "Lives where" routing matrix and an audit-then-update split (Step 3a / Step 3b) with concrete pruning checklists for arch.md and lessons-learned.md. The SPIR review phase now name-drops the skill and includes lessons-learned.md alongside arch.md.

Templates also picked up the discipline:

• templates/arch.md is a richer multi-section starter (TL;DR, Repository Layout & Stack, Per-Subsystem Mechanism, Apps Roster, Packages Roster, Verified-Wrong Assumptions, Updating This Document) with skip-if-N/A framing for small projects
• templates/lessons-learned.md gains a preface with "what NOT to add" guidance and a sanity-check checklist

The shipped templates resolve at runtime from the installed npm package; existing projects continue using their own arch.md and can opt into the richer template by manual copy.

Bug fixes

• #717 — afx attach can't find builders (PR #720): findShellperSocket now queries SQLite by workspace root, with fallback to Tower's terminal_sessions
• #712 — Stale af CLI references in resource docs after the af → afx rename (PR #713)
• #711 — porch lacked --version flag and pending command (PR #714)
• #710 — E2E tests depended on removed porch run orchestrator (PR #715)
• #725 — Bridge mode test misclassified as unit test in CI (PR #726): renamed to bridge-mode.e2e.test.ts

Breaking changes

None.

Migration

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

The new update-arch-docs skill lands automatically via codev update on existing projects. The user-global ~/.claude/agents/architecture-documenter.md agent file (if present) should be removed, since the skill replaces it.

Install

npm install -g @cluesmith/codev@3.0.2

Contributors

• M Waleed Kadous (@waleedkadous)
• @timeleft-- (Younes) — Linear forge provider, hybrid forge architectural insight
• @otherview — Bridge Mode for container deployments
• MachineWisdomAI — bugfix #725 and ongoing builder work
• Builders working under SPIR, ASPIR, AIR, and BUGFIX protocols