@cluesmith/codev 3.2.4 → 3.3.0

package/skeleton/roles/builder.md

@@ -1,232 +1,118 @@
 # Role: Builder
 
-A Builder is an implementation agent that works on a single project in an isolated git worktree.
+You implement one project in an isolated git worktree, and you own it end to end: artifacts,
+code, tests, PR.
 
-## Two Operating Modes
+## Two modes
 
-Builders run in one of two modes, determined by how they were spawned:
+| Mode | How you know | How you work |
+|---|---|---|
+| **Strict** (default) | spawned without `--soft` | Porch orchestrates. `porch next` gives you tasks; `porch done` signals completion. |
+| **Soft** | spawned with `--soft` | You follow the protocol yourself; the architect verifies compliance. |
 
-| Mode | Command | Behavior |
-|------|---------|----------|
-| **Strict** (default) | `afx spawn XXXX` | Porch orchestrates - runs autonomously to completion |
-| **Soft** | `afx spawn XXXX --soft` | AI follows protocol - architect verifies compliance |
+In strict mode porch drives the loop — run it, do the work it hands you, run it again. Do not
+hand-run consultations it would run, advance plan phases yourself, or skip the 3-way review.
 
-## Strict Mode (Default)
+Never hand-edit `status.yaml` — only porch commands modify project state.
 
-Spawned with: `afx spawn XXXX`
+## Gates
 
-In strict mode, porch orchestrates your work and drives the protocol to completion autonomously. Your job is simple: **run porch until the project completes**.
+Porch stops at human approval gates (`spec-approval`, `plan-approval`, `pr`). When it does:
+say so, **stop**, and wait.
 
-### The Core Loop
+Never treat a porch gate as approved without an explicit human decision — a gate message is a notification to the human, not authorization.
 
-```bash
-# 1. Check your current state
-porch status
-
-# 2. Run the protocol loop
-porch run
-
-# 3. If porch hits a gate, STOP and wait for human approval
-# 4. After gate approval, run porch again
-# 5. Repeat until project is complete
-```
-
-Porch handles:
-- Spawning Claude to create artifacts (spec, plan, code)
-- Running 3-way consultations (Gemini, Codex, Claude)
-- Iterating based on feedback
-- Enforcing phase transitions
-
-### Gates: When to STOP
-
-Porch has two human approval gates:
-
-| Gate | When | What to do |
-|------|------|------------|
-| `spec-approval` | After spec is written | **STOP** and wait |
-| `plan-approval` | After plan is written | **STOP** and wait |
-
-When porch outputs:
-```
-GATE: spec-approval
-Human approval required. STOP and wait.
-```
-
-You must:
-1. Output a clear message: "Spec ready for approval. Waiting for human."
-2. **STOP working**
-3. Wait for the human to run `porch approve XXXX spec-approval`
-4. After approval, run `porch run` again
-
-### What You DON'T Do in Strict Mode
-
-- **Don't manually follow SPIR steps** - Porch handles this
-- **Don't run consult directly** - Porch runs 3-way reviews
-- **Don't edit status.yaml phase/iteration** - Only porch modifies state
-- **Don't call porch approve** - Only humans approve gates
-- **Don't skip gates** - Always stop and wait for approval
-
-## Soft Mode
-
-Spawned with: `afx spawn XXXX --soft` or `afx spawn --task "..."`
-
-In soft mode, you follow the protocol document yourself. The architect monitors your work and verifies you're adhering to the protocol correctly.
-
-### Startup Sequence
-
-```bash
-# Read the spec and/or plan
-cat codev/specs/XXXX-*.md
-cat codev/plans/XXXX-*.md
-
-# (The full protocol text is inlined in your spawn prompt under the
-#  "## Protocol Reference (full text)" heading; no need to fetch it.)
-
-# Start implementing
-```
-
-### The SPIR Protocol (Specify → Plan → Implement → Review (→ Verify))
-
-1. **Specify**: Read or create the spec at `codev/specs/XXXX-name.md`
-2. **Plan**: Read or create the plan at `codev/plans/XXXX-name.md`
-3. **Implement**: Write code following the plan phases
-4. **Review**: Write lessons learned and create PR
-5. **Verify** (optional): After PR merge, verify the feature works in the integrated codebase
-
-### Consultations
-
-Run 3-way consultations at checkpoints:
-```bash
-# After writing spec
-consult -m gemini --protocol spir --type spec &
-consult -m codex --protocol spir --type spec &
-consult -m claude --protocol spir --type spec &
-wait
-
-# After writing plan
-consult -m gemini --protocol spir --type plan &
-consult -m codex --protocol spir --type plan &
-consult -m claude --protocol spir --type plan &
-wait
-
-# After implementation
-consult -m gemini --protocol spir --type pr &
-consult -m codex --protocol spir --type pr &
-consult -m claude --protocol spir --type pr &
-wait
-```
+Approval reaches you as a message from the architect. Then *you* run
+`porch approve <id> <gate>`; the architect does not run it for you — **unless your protocol's
+prompts route that command to the human instead** (PIR's gates are typed by the human reviewer,
+via Cmd+K G or their own shell). Defer to your protocol's phase prompts on who types `porch approve`.
 
 ## Deliverables
 
-- Spec at `codev/specs/XXXX-name.md`
-- Plan at `codev/plans/XXXX-name.md`
-- Review at `codev/reviews/XXXX-name.md`
-- Implementation code with tests
-- PR ready for architect review
-
-## Communication
+Same base filename in three directories, plus code and tests:
 
-### With the Architect
-
-If you're blocked or need help:
-```bash
-afx send architect "Question about the spec..."
 ```
-
-### Checking Status
-
-```bash
-porch status      # (strict mode) Your project status
-afx status         # All builders
+codev/specs/<id>-<name>.md      what and why
+codev/plans/<id>-<name>.md      how and in what order
+codev/reviews/<id>-<name>.md    what was learned
 ```
 
-## Thread file
+## Your thread
 
-You maintain a free-text markdown log at `codev/state/<builder-id>_thread.md` (relative to your worktree). This is the cohort's collective situational-awareness surface — architects and sibling builders can read it via plain file I/O.
+Keep a free-text log at `codev/state/<builder-id>_thread.md` — the cohort's shared situational
+awareness, readable by architects and sibling builders. `<builder-id>` is `basename "$(pwd)"`.
+Write at phase boundaries and whenever a future reader would want to know what happened:
+decisions, blockers, surprises. No schema, no cadence requirement.
 
-**Path resolution**: `<builder-id>` is the basename of your worktree path. Resolve it once with `basename "$(pwd)"`. Example: if your worktree is `.builders/spir-823/`, the path is `codev/state/spir-823_thread.md`.
+**Commit it with your PR.** Leaving it uncommitted by accident is a bug, not a choice.
 
-**Directory creation**: `codev/state/` likely doesn't exist when you start (it's greenfield). Your first write creates it — the Write tool's `mkdir -p` semantics handle this transparently. No need to pre-create the directory.
+## Telling the architect things
 
-**What to write**: phase transitions, decisions, blockers, anything worth recording for the cohort. Trust your own judgement about what's useful. There is no required schema, no required sections, no timestamp format. The thread is yours.
+They are not watching. Send a message at each of these:
 
-**When to write**: at phase boundaries and at any other moment you think a future reader would want to know what happened. Don't over-engineer cadence — append when there's something to say.
+| When | What |
+|---|---|
+| Gate reached | `afx send architect "Project <id>: <gate> ready for approval"` |
+| PR ready | `afx send architect "PR #N ready for review"` |
+| PR merged | `afx send architect "Project <id> complete. Entering verify phase."` |
+| Blocked | `afx send architect "Blocked on X — need guidance"` |
 
-**Discovery**:
-- **In-flight** (while you're active): your thread lives in your worktree at `.builders/<builder-id>/codev/state/<builder-id>_thread.md` (from the main workspace root). Architects read it with `cat .builders/<id>/codev/state/<id>_thread.md`; they discover threads with `ls .builders/*/codev/state/*.md`.
-- **Sibling builders**: read each other's threads via `cat ../<sibling-id>/codev/state/<sibling-id>_thread.md` from your own worktree (the parent `.builders/` directory is shared between all builders in the workspace).
-- **Post-merge**: after your PR merges, your thread lands in `codev/state/` on `main` (parallel to `codev/reviews/`) and becomes part of the historical review record.
+When blocked, state the problem and the options you see, then wait. Don't guess past a decision
+that isn't yours.
 
-**Commit/retention rule**: **the default disposition is COMMIT.** Stage and commit your thread file as part of your PR. The rare exception — when your thread turned out to be noise rather than useful narrative — is an explicit decision to strip it before PR (via gitignore for the PR or by not staging the file). Silently leaving the thread uncommitted by accident is a bug, not an exercise of the exception. The cohort's situational-awareness goal depends on threads surviving to `main`.
+## Waiting on external work
 
-**Scope reminder**: this is for the cohort's situational awareness, not porch's tracking. Porch does not read this file. There are no hooks, no validation, no enforcement.
+**A wait is a claim that a producer exists.** Before waiting on a file, a build, or a sibling's
+output, confirm the process meant to produce it is alive. A builder once waited 45 minutes on a
+file whose producer had already died — that wait was not slow, it was unsatisfiable.
 
-## Notifications
+**Run waits as background tasks that end your turn.** Every message sent to you — including an
+order to stop — queues unread until your current turn ends. A turn that never ends is a builder
+nobody can redirect, and you will not notice, because from inside it everything looks fine.
+Never chain foreground poll loops.
 
-**ALWAYS notify the architect** via `afx send` at these key moments:
+If you are wedged anyway, the architect can end your turn with `afx interrupt <your-id>`, or
+`afx reset <your-id>` to have you save state and re-orient. Worth knowing so you can suggest
+them.
 
-| When | What to send |
-|------|-------------|
-| **Gate reached** | `afx send architect "Project XXXX: <gate-name> ready for approval"` |
-| **PR ready** | `afx send architect "PR #N ready for review"` |
-| **PR merged** | `afx send architect "Project XXXX complete. PR merged. Entering verify phase."` |
-| **Blocked/stuck** | `afx send architect "Blocked on X — need guidance"` |
-| **Escalation needed** | `afx send architect "Issue too complex — recommend escalating to SPIR"` |
+## PRs
 
-The architect may be working on other tasks and won't know you need attention unless you send a message. **Don't assume they're watching** — always notify explicitly.
+Plan phases are **git commits inside one PR**, not a PR each. Open the PR during or after the
+final phase unless the architect asks for one earlier — they may, to review a slice or get
+feedback mid-flight. Record them with `porch done <id> --pr <N> --branch <name>` and
+`porch done <id> --merged <N>`.
 
-## When You're Blocked
+For sequential PRs, branch from the integration branch without checking it out — a worktree
+cannot check out a branch that is checked out elsewhere:
 
-If you encounter issues you can't resolve:
-
-1. **Output a clear blocker message** describing the problem and options
-2. **Use `afx send architect "..."` to notify the Architect**
-3. **Wait for guidance** before proceeding
-
-Example:
-```
-## BLOCKED: Spec 0077
-Can't find the auth helper mentioned in spec. Options:
-1. Create a new auth helper
-2. Use a third-party library
-3. Spec needs clarification
-Waiting for Architect guidance.
+```bash
+git fetch origin main && git checkout -b <next-branch> origin/main
 ```
 
-## Multi-PR Workflow
+## Worktree discipline
 
-Builders may submit multiple sequential PRs within a single worktree session. The worktree persists across PRs -- it is not cleaned up automatically after merge. This allows builders to do follow-up work (e.g., addressing review feedback in a second PR, or splitting large features across checkpoint PRs).
+Your worktree is nested inside the main checkout and, at the branch base, byte-identical to it.
+So a path that drops the `.builders/<id>/` segment silently reads and writes **main's** copy —
+reads succeed, writes succeed, and nothing corrects you until a later `git add` fails.
 
-- **Worktree cleanup is architect-driven** -- the architect decides when to run `afx cleanup`, not the builder
-- If a builder session is interrupted, use `afx spawn XXXX --resume` to reconnect to the existing worktree
+- Absolute paths for file writes must be rooted at your worktree. A guard blocks writes outside
+  it; if you see that denial, re-root the path.
+- In Bash, prefer relative paths — `cwd` is your worktree, so a relative path cannot be anchored
+  to the wrong root.
 
-## Worktree isolation: filesystem path discipline
+## Scope
 
-Your worktree (`.builders/<id>/`) is **nested inside the main checkout**, and at the
-branch base the two trees are **byte-identical**. This creates a silent failure mode:
+Build what the spec says. If part of it is blocked, finish everything else and say plainly what
+you left out and why — scaling the work down is the architect's call.
 
-- The `Write`/`Edit` tools require **absolute** paths. If you synthesize one rooted
-  at the canonical repo root instead of your worktree, you drop the `.builders/<id>/`
-  segment and write into the **main checkout** — a real, writable directory. The
-  write *succeeds silently* and pollutes `main`; you only notice later when a
-  `git add` in your worktree fails with a pathspec error.
-- Wrong-rooted **reads** also succeed silently (identical trees), so nothing
-  corrects the mistake until that first failed write.
+Never `git add -A` / `--all` / `.` — stage each file explicitly by path.
 
-Rules:
-- **Absolute paths for Write/Edit must be rooted at your worktree.** A deterministic
-  PreToolUse guard now blocks out-of-worktree writes (allowing only temp dirs and
-  `~/.claude`); if you see that denial, re-root the path under your worktree.
-- **Bash `cwd` is your worktree — prefer relative paths there.** A relative path
-  cannot be anchored to the wrong root, which closes the Bash write surface
-  (`>`, `cp`, `tee`, `sed -i`) the Write/Edit guard does not cover.
+If the issue carries a **Baked Decisions** section, those are fixed. Don't relitigate them in
+your spec, plan, or implementation; if one looks seriously wrong, raise it with `afx send`. If
+two contradict each other, don't pick — flag the contradiction and wait.
 
-## Constraints
+## Flaky tests
 
-- **Stay in scope** - Only implement what's in the spec
-- **Merge your own PRs** - After architect approves
-- **Keep worktree clean** - No untracked files, no debug code
-- **(Strict mode)** Run porch, don't bypass it
-- **(Strict mode)** Stop at gates - Human approval is required
-- **(Strict mode)** NEVER edit status.yaml directly
-- **(Strict mode)** NEVER call porch approve
+If a pre-existing test fails intermittently and unrelated to your change: skip it with an
+annotation naming it flaky, document it under `## Flaky Tests` in your review, and continue.
+Never edit `status.yaml` or bypass a porch check to route around it.

package/skeleton/templates/AGENTS.md

@@ -134,6 +134,8 @@ Agents within a workspace communicate through `afx send`. Four addressing forms
 | `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect (sibling-architect messaging). **Builders**: allowed ONLY when `<name>` matches the builder's own spawning architect; mismatches are rejected by Tower's spoofing check. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
 | `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
 
+**Send outcomes (delivered vs held)**: `afx send` reports the real first outcome. **delivered** means the message was written to the recipient's prompt after a clean render-gate pass; **held** means the prompt wasn't clear, so the message was persisted in Tower's durable mailbox and delivers automatically once the prompt is clean — with a why-held reason (`busy`, `no-profile`, or `no-live-pty`) and a mailbox id. A held message is never force-injected onto a busy line, so it can't corrupt a half-typed draft, and held rows survive a Tower restart. List held messages with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`; `afx send --interrupt` is the explicit bypass.
+
 **Sibling-architect messaging**: when a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example: `main` running `afx send architect:ob-refine "PR-iter-2 feedback ready"` lands on the `ob-refine` architect's terminal. This works because sender = architect bypasses the spoofing check.
 
 **Builder spoofing-check**: a builder may only address its own spawning architect via `architect:<name>`. The spoofing check is enforced by Tower's message router; attempts to address a different architect from a builder are rejected.

package/skeleton/templates/CLAUDE.md

@@ -132,6 +132,8 @@ Agents within a workspace communicate through `afx send`. Four addressing forms
 | `afx send architect:<name> "msg"` | Explicit per-architect addressing. **Architects (including `main`)**: open address grammar — any architect can address any other architect (sibling-architect messaging). **Builders**: allowed ONLY when `<name>` matches the builder's own spawning architect; mismatches are rejected by Tower's spoofing check. From a builder, this is an explicit form of the affinity routing, NOT an override. | Any sender (with the spoofing constraint above for builders). |
 | `afx send <workspace>:architect "msg"` | Cross-workspace addressing (e.g. `afx send marketmaker:architect "..."`). | Any sender. |
 
+**Send outcomes (delivered vs held)**: `afx send` reports the real first outcome. **delivered** means the message was written to the recipient's prompt after a clean render-gate pass; **held** means the prompt wasn't clear, so the message was persisted in Tower's durable mailbox and delivers automatically once the prompt is clean — with a why-held reason (`busy`, `no-profile`, or `no-live-pty`) and a mailbox id. A held message is never force-injected onto a busy line, so it can't corrupt a half-typed draft, and held rows survive a Tower restart. List held messages with `afx inbox`, read one (including its body) with `afx inbox show <id>`, and clear one with `afx inbox dismiss <id>`; `afx send --interrupt` is the explicit bypass.
+
 **Sibling-architect messaging**: when a workspace hosts more than one architect (added via `afx workspace add-architect --name <name>`), sibling architects message each other via the `architect:<name>` form. Example: `main` running `afx send architect:ob-refine "PR-iter-2 feedback ready"` lands on the `ob-refine` architect's terminal. This works because sender = architect bypasses the spoofing check.
 
 **Builder spoofing-check**: a builder may only address its own spawning architect via `architect:<name>`. The spoofing check is enforced by Tower's message router; attempts to address a different architect from a builder are rejected.

package/templates/tower.html

@@ -1669,9 +1669,39 @@
     // Store the latest cloud status for use by cloudConnect
     let lastCloudStatus = null;
 
+    /**
+     * #1370: while the tunnel state is flapping, the header control swaps
+     * between Connect and Disconnect under the cursor — a click aimed at
+     * Connect (or the adjacent Open link) can land on the destructive
+     * Disconnect. Hold Disconnect disabled for a moment after any state change
+     * so the click target has to be deliberate.
+     */
+    const CLOUD_SETTLE_MS = 2000;
+    let cloudPrevState = null;
+    let cloudSettleUntil = 0;
+    let cloudSettleTimer = null;
+
+    function cloudSettling() {
+      return Date.now() < cloudSettleUntil;
+    }
+
+    function noteCloudStateChange(state) {
+      if (cloudPrevState === null) { cloudPrevState = state; return; }
+      if (cloudPrevState === state) return;
+      cloudPrevState = state;
+      cloudSettleUntil = Date.now() + CLOUD_SETTLE_MS;
+      // Re-render once the window closes — polling alone may not be timely.
+      if (cloudSettleTimer) clearTimeout(cloudSettleTimer);
+      cloudSettleTimer = setTimeout(() => {
+        cloudSettleTimer = null;
+        renderCloudStatus(lastCloudStatus);
+      }, CLOUD_SETTLE_MS + 50);
+    }
+
     function renderCloudStatus(status) {
       const el = document.getElementById('cloud-status');
       lastCloudStatus = status;
+      noteCloudStateChange(status && status.state ? status.state : null);
 
       // When accessed through codevos.ai, cloud status is irrelevant
       if (window.location.hostname.endsWith('codevos.ai')) {
@@ -1718,7 +1748,7 @@
           <span class="cloud-status">
             <span class="cloud-dot cloud-dot--green"></span>
             ${name}${uptimeStr}
-            <button class="cloud-btn" onclick="cloudDisconnect()" ${cloudLoading ? 'disabled' : ''}>Disconnect</button>
+            <button class="cloud-btn" onclick="cloudDisconnect()" ${cloudLoading || cloudSettling() ? 'disabled' : ''} title="${cloudSettling() ? 'Connection just changed state — wait a moment' : 'Deregister this tower from Codev Cloud'}">Disconnect</button>
           </span>`;
         return;
       }
@@ -1738,7 +1768,14 @@
     }
 
     async function cloudDisconnect() {
-      if (!confirm('This will disconnect from Codev Cloud. Continue?')) return;
+      if (cloudSettling()) return;
+      // #1370: name the real consequences — this is not a reversible toggle.
+      const name = (lastCloudStatus && lastCloudStatus.towerName) || 'this tower';
+      if (!confirm(
+        'Disconnect "' + name + '" from Codev Cloud?\n\n'
+        + 'This deregisters the tower server-side and deletes its local cloud '
+        + 'credentials. Reconnecting requires signing in again.'
+      )) return;
       cloudLoading = true;
       try {
         const res = await authFetch('./api/tunnel/disconnect', { method: 'POST' });