@cluesmith/codev 3.2.2 → 3.2.4

package/skeleton/.codex/skills/porch/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: porch
+description: Protocol orchestrator CLI — drives SPIR, ASPIR, AIR, and BUGFIX protocols via a state machine. ALWAYS check this skill before running any `porch` command. Use when you need to check project status, approve gates, signal phase completion, or manage protocol state. Also use when a builder asks about gate approvals or phase transitions.
+---
+
+# porch - Protocol Orchestrator
+
+Porch manages the state machine behind development protocols. It tracks phases, gates, consultations, and transitions.
+
+## Commands
+
+```
+porch status [id]              Show current project state and phase
+porch run [id]                 Run the protocol loop (strict mode)
+porch next [id]                Get next tasks as JSON
+porch done [id]                Signal current phase is complete
+porch check [id]               Run checks for current phase
+porch gate [id]                Request human approval at a gate
+porch approve <id> <gate> --a-human-explicitly-approved-this
+porch rollback <id> <phase>    Rewind to an earlier phase
+porch init <protocol> <id> <name>   Initialize a new project
+```
+
+Project ID auto-detects from worktree path when inside a builder worktree.
+
+## Gate approvals
+
+Gates are human-only approval checkpoints. The `--a-human-explicitly-approved-this` flag is **required** — it exists to prevent AI agents from auto-approving.
+
+| Gate | Protocol | When |
+|------|----------|------|
+| `spec-approval` | SPIR | After spec is written |
+| `plan-approval` | SPIR | After plan is written |
+| `pr` | SPIR, AIR | After PR is created |
+
+```bash
+porch approve 42 spec-approval --a-human-explicitly-approved-this
+porch approve 42 plan-approval --a-human-explicitly-approved-this
+porch approve 42 pr --a-human-explicitly-approved-this
+```
+
+**ASPIR and BUGFIX have no spec/plan gates** — they run autonomously through those phases.
+
+## Checking pending gates
+
+```bash
+porch pending                  # List all gates waiting for approval
+```
+
+## Critical rules
+
+- **Builders must NEVER call `porch approve`** — only humans approve gates
+- **Never edit `status.yaml` directly** — porch manages all state
+- Builders signal completion with `porch done`, not `porch approve`
+- `porch run` is for strict mode only — soft mode builders follow the protocol document manually
+- When running `porch approve` from the architect, use a subshell if you need worktree context: `(cd /path/to/worktree && porch approve ...)`
+
+## State storage
+
+Project state lives in `codev/projects/<id>-<name>/status.yaml`, managed automatically by porch. The status file tracks current phase, gate states, consultation results, and timestamps.

package/skeleton/.codex/skills/update-arch-docs/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: update-arch-docs
+description: "Audit, prune, and update the project's governance docs — the COLD reference archives `codev/resources/arch.md` and `codev/resources/lessons-learned.md` AND their always-on HOT companions `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md` (Spec 987, hot/cold two-tier model). Use this skill when running MAINTAIN's arch-doc step, or when asked to update / audit / prune any of those four files. It polices the hot-tier cap (capped facts/lessons + a bounded cold-doc map), enforces displacement (demote to cold when full), keeps each hot file's map accurate, and is opinionated about what NOT to put in each tier (per-spec changelogs, exhaustive enumerations, aspirational state). Two modes: diff-mode (apply a specific change) and audit-mode (propose cuts with reasons). Edits files directly via normal file-edit tooling; no destructive shell commands."
+---
+
+# update-arch-docs
+
+This skill maintains the project's governance docs, each split into **two tiers** (Spec 987):
+
+- **COLD reference archives** — `codev/resources/arch.md` (architecture) and `codev/resources/lessons-learned.md` (durable wisdom). Full, on-demand; grepped/read for depth.
+- **HOT always-on companions** — `codev/resources/arch-critical.md` and `codev/resources/lessons-critical.md`. Tiny, **hard-capped**, **always injected** into every porch prompt and into CLAUDE.md/AGENTS.md. Each holds capped facts/lessons **plus a bounded "consult when…" map** of its cold doc's top-level topics.
+
+It is invoked by the MAINTAIN protocol's documentation step, and ad-hoc whenever someone updates, audits, or prunes any of these files. The skill is opinionated about *what does not belong* in each tier and **polices the hot-tier cap, displacement, and map accuracy**. Use it whenever a doc change touches any of the four files.
+
+## What this skill does NOT do
+
+These are the patterns that have, in practice, caused arch.md and lessons-learned.md to grow without bound. Treat them as bright-line rejections during both audit-mode and diff-mode work.
+
+### In arch.md
+
+- **Per-file enumerations** that go stale the moment they're written. Document the *shape* of a directory and the handful of load-bearing files; do not list every file. `git ls-files` is authoritative; the doc is for orientation.
+- **Per-spec changelog sections** ("Spec 0042 added X, Spec 0073 changed Y"). Architecture is current state, not history. The git log + the spec/review documents own the changelog framing.
+- **Specs/plans tables** that mirror the contents of `codev/specs/` and `codev/plans/`. These are duplicative and rot quickly. Link to the directory; do not paginate it into the doc.
+- **Aspirational state** ("we plan to…", "in the next phase we'll…"). That belongs in the relevant meta-spec or roadmap doc, not in the architecture body. arch.md describes what *is*, not what *might be*.
+- **Date-stamped narrative** ("As of 2026-Q2, the system uses…"). Dates make the doc look fresh while making it harder to maintain. Use git log + commit dates for temporal context.
+- **Duplication of meta-spec content**. If a subsystem has its own meta-spec under `codev/architecture/<domain>.md` or under `codev/specs/`, arch.md should carry a 1-paragraph summary plus a pointer — not a copy.
+- **Retired-component graveyards**. When a component is removed, delete its section. `git log` retains history; an arch.md that describes things that no longer exist is misleading.
+
+### In the HOT files (`arch-critical.md`, `lessons-critical.md`)
+
+These are capped, always-on, and **behavior-changers only**. Bright-line rejections:
+
+- **Anything over the cap.** Each hot file fits in a handful of lines (≈10 single-line facts/lessons + a cold-doc map of ≈12 top-level topics, ≤35 lines). To add an entry, **demote** a weaker one into the cold doc (displacement) — never grow the hot file.
+- **Spec-narrow recipes / reference detail.** Those go in the COLD archive (reference), never the hot file.
+- **A full/auto table of contents** in the cold-doc map. The map lists only **top-level** cold-doc sections, each with a one-line "consult when…" — never every entry.
+- **Multi-paragraph entries.** One line each.
+
+### In the COLD archives (`arch.md`, `lessons-learned.md`)
+
+These are the on-demand **reference**. They may hold spec-narrow recipes and deeper detail — the anti-accretion discipline lives in the hot cap, not here. Still avoid:
+
+- **Multi-paragraph lesson entries**. Split or compress to 1–3 sentences.
+- **Duplicate adjacent entries**. Fold variations of the same lesson into one.
+- **Spec-numbered narrative framing** ("Lesson from #0468:…"). State the general principle; link the review if needed.
+
+### In either file (process)
+
+- **Destructive shell commands**. The skill must not invoke `rm -rf`, `git rm`, or destructive `sed` scripts. All edits go through the normal Edit tool. The MAINTAIN PR diff is the human-confirmation step; that's enough.
+
+## arch.md vs. lessons-learned.md (two-doc framing)
+
+Treat the two files as siblings with different purposes. When in doubt about which file a fact belongs in, route by purpose:
+
+| Purpose | Goes in |
+|---|---|
+| Current system shape — services, transports, key mental models | `arch.md` |
+| Mechanism for a unique subsystem | `arch.md` (subsystem section) — or its own meta-spec if the mechanism is large enough to warrant one, with arch.md keeping a 1-paragraph summary + pointer |
+| Pointers ("see meta-spec X for details") | `arch.md` |
+| A durable engineering pattern that applies across multiple specs | `lessons-learned.md` |
+| A system-shape surprise verified-wrong in production ("looks like X but isn't") | `arch.md` § "Verified-Wrong Assumptions" — *not* lessons-learned.md, because it's a property of the system, not a general pattern |
+
+The "system-shape surprise" routing is the one most often gotten wrong. If a future reader needs to know "the system *looks* like X but actually does Y", that is system shape and lives in arch.md. If they need to know "we learned that doing X is generally a bad idea", that is engineering wisdom and lives in lessons-learned.md.
+
+That arch-vs-lessons routing is the **cold-tier** axis. **Orthogonal to it is the hot/cold axis**: once you know a fact is architecture (or a lesson), decide whether it is *behavior-changing enough* to earn a slot in the capped hot companion, or whether it is reference detail for the cold archive.
+
+## Hot tier: cap, displacement, and map accuracy
+
+The hot files (`arch-critical.md`, `lessons-critical.md`) are the behavior-changers, and their value depends on staying tiny. When MAINTAIN runs — or any update touches them — enforce:
+
+- **Cap.** Each hot file fits in a handful of lines: ≈10 single-line facts/lessons **plus** a cold-doc map of ≈12 top-level topics, ≤35 lines total. If an addition would exceed the cap, **demote** the weakest existing entry into the corresponding cold doc rather than growing the hot file. The cap is load-bearing: it is what keeps the hot tier cheap enough to inject into *every* prompt.
+- **Map accuracy (bounded AND accurate).** Each hot file ends with a "Map of <cold doc> (consult when…)" listing only the cold doc's **top-level** sections, each with a one-line "consult when…". As cold-doc sections are added / renamed / removed, update the map to match — but keep it top-level only; never expand it into a full table of contents (that re-creates the accretion the hot tier exists to avoid).
+- **Behavior-changers only.** A hot entry must be something that should change a decision up front. Reference detail, recipes, and one-offs belong in the cold archive — demote on sight.
+
+## Sizing by purpose, not by line count
+
+There is no line-count budget for either file. The right size for each section is determined by what the section needs to do. If a subsystem genuinely has unique mechanism that takes 80 lines to explain clearly, 80 lines is the right size. If a subsystem can be described in 5 lines and a pointer to a meta-spec, 5 lines is right.
+
+What's *wrong* is bulk that comes from any of the patterns in "What this skill does NOT do" above. Strip those, and the file's size will land where it belongs.
+
+When proposing a section, ask: "Could a future reader skip this section without losing anything load-bearing?" If yes, the section should not exist. The doc's purpose is orientation, not completeness.
+
+## Mode: diff-mode (apply a specific change)
+
+Use diff-mode when the request is specific: "add a section about the new caching layer," "update the Glossary entry for Tower," "remove the reference to the deleted dashboard-server."
+
+In diff-mode:
+
+1. Find the smallest section that needs to change.
+2. Apply the change via the Edit tool.
+3. If the change adds new content, run a quick sanity check against "What this skill does NOT do" before saving — make sure the new content is current state, not aspirational; not duplicative of a meta-spec; not a per-spec changelog entry.
+4. Surface the resulting diff for review.
+
+Diff-mode is fast. It is the right mode for ~80% of post-MAINTAIN documentation work.
+
+## Mode: audit-mode (identify what to cut)
+
+Use audit-mode when the request is general: "the doc feels stale," "MAINTAIN says it's time to prune," "review arch.md against the principles."
+
+In audit-mode:
+
+1. Read the file end-to-end.
+2. For each section in arch.md, run through the per-section pruning checklist (from the MAINTAIN protocol):
+   - Does it describe *current state*? If aspirational, the section moves to a meta-spec; the arch.md keeps a 1-paragraph summary + pointer (or nothing, if the meta-spec stands on its own).
+   - Does it duplicate a meta-spec? If yes, replace with a 1-paragraph summary + pointer.
+   - Is it a per-file enumeration that's gone stale? If yes, prune to the directory shape + a few key files.
+   - Is it a changelog/narrative section ("Spec 0042 added X")? If yes, absorb the architecturally-relevant facts and remove the spec-numbered framing.
+   - Is the component still alive? If retired, delete the section entirely.
+3. For each entry in the COLD `lessons-learned.md`, run the per-entry checklist:
+   - Is it terse (1–3 sentences)? If multi-paragraph, split or compress.
+   - Is the topic section the right one? If filed under "Architecture (continued)" or a spec-numbered section, move it to the right topical home.
+   - Is it a duplicate of an adjacent entry? If yes, fold them.
+   - (Spec-narrow recipes are **kept** here as reference — do not cut them just for being spec-narrow. Anti-accretion now lives in the hot cap, not in the cold archive.)
+
+   Then audit each **HOT** file (`arch-critical.md`, `lessons-critical.md`):
+   - **Cap**: within ≈10 entries + a ≈12-topic map, ≤35 lines? If over, **demote** the weakest entries into the cold doc.
+   - **Map accuracy**: does every map topic name a real top-level cold-doc section, and is any new/renamed section reflected? Fix drift; keep the map top-level only.
+   - **Behavior-changers only**: demote any reference detail that crept in.
+4. **When in doubt, KEEP.** This rule comes from the MAINTAIN protocol and applies in audit-mode too. A confident cut is better than three speculative ones. Bias toward fewer, higher-confidence proposals with clear rationale; do not chase a maximum cut count.
+5. Apply the cuts via the Edit tool — the skill does not produce a "candidate-cuts list and stop." The diff *is* the proposal. The MAINTAIN PR review is the human-confirmation step.
+6. Surface a short reason alongside each cut in the run file (`codev/maintain/NNNN.md`) so PR reviewers can evaluate intent ("removed because: per-spec changelog framing"; "compressed because: duplicates the orchestrator meta-spec").
+
+Audit-mode is slower than diff-mode and produces larger diffs. Reserve it for explicit audit invocations, not for routine doc updates.
+
+## Output contract
+
+The skill commits to the following:
+
+- It edits the four governance files — `codev/resources/arch.md` / `arch-critical.md` and `codev/resources/lessons-learned.md` / `lessons-critical.md` — directly via the Edit tool.
+- It does not invoke destructive shell commands (no `rm -rf`, no `git rm`, no destructive `sed`). File deletions happen only through Edit removing the relevant content; whole-file removal would be a structural change that is out of scope for this skill.
+- In audit-mode, every removal is paired with a one-line reason in the MAINTAIN run file's `## Audit Findings` section. Rationale lives there so reviewers can evaluate intent without re-deriving it from the diff.
+- The skill does not modify other files (specs, plans, reviews, source code). If a fact belongs somewhere else, the skill flags it; it does not move it.
+- The skill does not edit live arch.md or lessons-learned.md content as a side effect of being read or invoked — only when the user/MAINTAIN protocol explicitly asks for an update or audit.

package/skeleton/protocols/pir/prompts/implement.md

@@ -121,7 +121,7 @@ When the gate goes pending, output a short prose summary in the pane to orient t
 >
 > **Things to look at**: tricky spots, platform-specific behavior, anything you want the reviewer to focus on.
 >
-> **How to test locally**: VSCode → right-click builder → **Run Dev Server**, or `afx dev pir-{{project_id}}`. View diff via VSCode → **View Diff** (auto-detects the repo's default branch).
+> **How to test locally**: VSCode → right-click builder → **Run Dev**, or `afx dev pir-{{project_id}}`. View diff via VSCode → **View Diff** (auto-detects the repo's default branch).
 >
 > Ready for review — type feedback here, or approve with `porch approve {{project_id}} dev-approval --a-human-explicitly-approved-this` (Cmd+K G in VSCode).
 

package/skeleton/protocols/pir/prompts/review.md

@@ -75,7 +75,7 @@ Tricky spots the PR reviewer should focus on. Honest — if a section was hard t
 For reviewers pulling the branch:
 
 - **View diff**: VSCode sidebar → right-click builder pir-{{project_id}} → **Review Diff** (auto-detects the repo's default branch)
-- **Run dev server**: VSCode sidebar → **Run Dev Server**, or `afx dev pir-{{project_id}}`
+- **Run dev**: VSCode sidebar → **Run Dev**, or `afx dev pir-{{project_id}}`
 - **What to verify**: <bullet list mapped to the plan's Test Plan>
 
 ## Flaky Tests (if any)

package/skeleton/protocols/pir/protocol.md

@@ -83,10 +83,10 @@ The builder:
 
 **The reviewer's killer move**: run the worktree locally.
 
-- VSCode: right-click the builder in the Codev sidebar → **Run Dev Server** (spawns `afx dev <builder-id>` via Tower)
+- VSCode: right-click the builder in the Codev sidebar → **Run Dev** (spawns `afx dev <builder-id>` via Tower)
 - CLI: `afx dev <builder-id>`
 
-The dev server uses **the same ports and URLs as main** intentionally (OAuth callbacks, CORS, cookie scoping all depend on consistent origins). Only one dev env runs at a time; stop main's `pnpm dev` before starting the worktree's, or use VSCode's **Stop Dev Server** to swap.
+The dev process uses **the same ports and URLs as main** intentionally (OAuth callbacks, CORS, cookie scoping all depend on consistent origins). Only one dev env runs at a time; stop main's `pnpm dev` before starting the worktree's, or use VSCode's **Stop Dev** to swap.
 
 Reviewer tests the change on real devices / browsers / simulators. When satisfied, approves via Cmd+K G or:
 
@@ -134,7 +134,7 @@ This means typed input in the builder pane reaches the live Claude session immed
 
 ## Configuration
 
-PIR uses the same `.codev/config.json` configuration as other protocols. The `worktree` block (from Issue 689) enables the at-gate dev-server review flow:
+PIR uses the same `.codev/config.json` configuration as other protocols. The `worktree` block (from Issue 689) enables the at-gate dev review flow:
 
 ```json
 {

package/skeleton/resources/commands/agent-farm.md

@@ -237,6 +237,65 @@ Status values:
 
 ---
 
+### afx whoami
+
+Report this terminal's agent identity — workspace, type, and name — from
+Tower/global.db's perspective.
+
+```bash
+afx whoami
+afx whoami --json
+```
+
+**Description:**
+
+Resolves who the current terminal's agent is. Identity precedence:
+
+1. **Builder worktree** — when CWD is inside `.builders/<id>/`, the canonical
+   builder id is verified against `global.db` (the same resolution `afx send`
+   uses). An unverifiable worktree identity is an error, never a fallthrough
+   to the next signal.
+2. **`CODEV_ARCHITECT_NAME`** — the env var Tower injects into architect
+   terminals.
+3. **Unknown** — exits non-zero with an explanation. There is no implicit
+   fallback to `main` (issue #1094: unverified identities misroute messages).
+
+Works without Tower running (reads `global.db` read-only).
+
+**Example output (architect terminal):**
+
+```
+workspace: codev
+type: architect
+name: main
+```
+
+**Example output (builder worktree):**
+
+```
+workspace: codev
+type: builder
+name: builder-spir-984
+architect: main
+```
+
+The `architect:` line is the builder's spawning architect; it is omitted when
+not recorded (legacy rows).
+
+**JSON output:**
+
+```bash
+afx whoami --json
+# {"workspace":"codev","type":"builder","name":"builder-spir-984","architect":"main"}
+```
+
+On failure, `--json` prints `{"error":"..."}` to stdout (the human-readable
+explanation still goes to stderr) and exits 1.
+
+**Exit codes:** `0` identity resolved; `1` identity unknown or unverifiable.
+
+---
+
 ### afx cleanup
 
 Clean up a builder worktree and branch.
@@ -549,6 +608,36 @@ Customize commands via `.codev/config.json` at the project root:
 }
 ```
 
+### Porch Gate Artifact Auto-Open
+
+When Porch requests a specification, plan, or review gate, it automatically
+opens the phase artifact in Tower. This is enabled when the setting is unset or
+`true`. Set `porch.autoOpenArtifacts` to `false` to prevent that automatic
+`afx open` action:
+
+```json
+{
+  "porch": {
+    "autoOpenArtifacts": false
+  }
+}
+```
+
+This setting controls only Porch's automatic gate artifact opens. A manual
+`afx open <path>` still creates a Tower file tab and follows the dashboard's
+normal focus behavior.
+
+You can set the preference globally in `~/.codev/config.json`, for the team in
+the project's committed `.codev/config.json`, or per engineer and project in
+the gitignored `.codev/config.local.json`. Project settings override global
+settings, and project-local settings override both.
+
+When the main workspace has `.codev/config.local.json`, Agent Farm copies it
+into each builder during spawn and `afx setup`. The builder receives a managed
+regular-file snapshot rather than a write-through symlink, so builder edits
+cannot change the main workspace's personal config. Running `afx setup` again
+refreshes the snapshot from the main workspace.
+
 Or override via CLI flags:
 
 ```bash

package/skeleton/resources/commands/codev.md

@@ -102,6 +102,11 @@ Verifies that all required dependencies are installed and properly configured:
 - Gemini (Antigravity CLI, `agy`)
 - Codex (`@openai/codex`)
 
+**Migration Backups (report-only):**
+- Leftover copies of pre-migration state — whole-directory `~/.agent-farm.bak-*` / `~/agent-farm-db-backup-*` copies and the `*.pre-merge-<timestamp>` renames left by `afx db consolidate` — listed with age and size on disk.
+- Nothing reaps these automatically, so doctor surfaces each one together with the exact `rm -rf` command and leaves the decision to you. It never deletes anything.
+- Backups younger than 7 days are listed but not counted as warnings; the section is omitted entirely when there are none.
+
 **Exit Codes:**
 - `0` - All OK or warnings only
 - `1` - Required dependencies missing

package/skeleton/resources/commands/consult.md

@@ -170,6 +170,32 @@ Configure auth:
 - Gemini (`agy`): **OAuth / subscription** — run `agy` once and sign in (no API key). If `agy`
   is missing or unauthenticated, the gemini lane skips non-blockingly (the run proceeds without it).
 
+#### agy auth-state cache (unauthenticated tab burst)
+
+An unauthenticated `agy` opens an OAuth browser tab *before* it prints the URL
+Codev detects, so the lane cannot suppress the tab after spawning — only by not
+spawning. Since a CMAP round is several independent `consult` processes, this used
+to strand one tab per consult (#1077).
+
+Codev keeps a shared auth verdict in `~/.cache/codev/agy-auth.json` (0600,
+honours `XDG_CACHE_HOME`). The first call probes; the rest read the verdict and
+short-circuit, so **an unauthenticated agy is spawned at most once per TTL
+window** instead of once per consult. A file lock keeps parallel consults from
+probing simultaneously. `codev doctor`'s agy check shares the same cache.
+
+Verdicts expire on their own — sign in with `agy` in another terminal and the lane
+recovers within the unauth TTL, no cache clearing required. The cache only ever
+suppresses a lane on positive "signed out" evidence; anything ambiguous falls
+through to a normal spawn.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CODEV_AGY_AUTH_CACHE_TTL_UNAUTH_MS` | `300000` (5 min) | How long a "signed out" verdict is trusted — the sign-in recovery window. |
+| `CODEV_AGY_AUTH_CACHE_TTL_AUTH_MS` | `1800000` (30 min) | How long a "signed in" verdict is trusted. |
+| `CODEV_AGY_AUTH_CACHE_WAIT_MS` | `6000` | How long a consult waits for another process's in-flight probe before proceeding anyway. |
+| `CODEV_AGY_AUTH_CACHE_DIR` | `~/.cache/codev` | Cache location (mainly for tests). |
+| `CODEV_AGY_AUTH_CACHE_DISABLE` | unset | `1` restores the always-spawn behaviour. |
+
 ### Claude auth: subscription vs. metered API
 
 `consult -m claude` runs on the Claude Agent SDK. When `CLAUDE_CODE_OAUTH_TOKEN`

package/skeleton/roles/architect.md

@@ -170,6 +170,17 @@ gh pr view <N> --json files | jq '.files[].path'   # See which subsystems
 - **Medium**: SPIR features, new commands, refactors touching 3+ files
 - **High**: Protocol changes, porch state machine, Tower architecture, security model
 
+#### Presenting the decision to the human (PRFT)
+
+When you bring a fix to the human for a decision — a merge word, a `pr` gate, a dev-approval — present it **unprompted** in PRFT form, whatever the risk tier:
+
+- **Problem** — the user-visible symptom, in a sentence or two.
+- **Root Cause** — the verified mechanism. Verify it yourself; a builder's summary is evidence, not ground truth.
+- **Fix** — what changed and why it's safe.
+- **Testing** — the evidence: suites run, live verification, CI state.
+
+Keep each part tight and lead with it — don't bury the decision under process narration. The human should be able to say yes or no from your message alone, without opening the diff.
+
 #### Step 3: Execute Review
 
 **Low risk** — no external models needed: