Merge pull request #675 from cluesmith/builder/task-NH8C

[Maintain 0007] Pre-v3.0.0 maintenance

Author: waleedkadous

AGENTS.md

@@ -36,23 +36,28 @@ To release a new version, tell the AI: `Let's release v1.6.0`. The AI follows th
 To test changes locally before publishing to npm:
 
 ```bash
-# From packages/codev directory:
-cd packages/codev
+# From the repository root:
 
-# 1. Build and create tarball (Tower stays up during this)
+# 1. Build (Tower stays up during this)
 pnpm build
-pnpm pack
 
-# 2. Install (Tower stays up — running process already loaded old code)
-npm install -g ./cluesmith-codev-*.tgz
+# 2. Pack both tarballs
+pnpm --filter @cluesmith/codev-core pack
+pnpm --filter @cluesmith/codev pack
+
+# 3. Install globally (Tower stays up)
+pnpm local-install
 
 # 3. Restart (only this step needs downtime)
 afx tower stop && afx tower start
 ```
 
+- `pnpm build` builds core first, then codev (including dashboard)
+- `pnpm --filter <package> pack` creates tarballs (run for core and codev separately)
+- `pnpm local-install` installs both tarballs in a single `npm install -g` command — separate installs fail because `@cluesmith/codev-core` isn't on the public npm registry
 - Install while Tower is running — it doesn't affect the running process
 - Do NOT stop Tower before installing — unnecessary downtime
-- Do NOT delete the tarball — keep it for debugging if restart fails
+- Do NOT delete the tarballs — keep them for debugging if restart fails
 - Do NOT build between stop and start
 - Do NOT use `npm link` or `pnpm link` — it breaks global installs
 

codev/maintain/0007.md

@@ -0,0 +1,107 @@
+# Maintenance Run 0007
+
+**Date**: 2026-04-17
+**Base Commit**: 47cb2c86 (Maintenance Run 0006 merge)
+**Current HEAD**: eaefd35b
+**Scope**: Pre-release maintenance for v3.0.0
+**Commits since last run**: 1751 (261 merges)
+
+## Changes Since Last Run
+
+Major features merged since run 0006 (partial list):
+
+- **VS Code extension** (Spec 0602): New `packages/vscode/` thin client over Tower API — Pseudoterminal↔WebSocket terminals, sidebar TreeViews, auto-Tower startup, SecretStorage auth
+- **codev-core package** (Spec 0602): Shared runtime extracted from codev — `TowerClient`, `auth`, `workspace`, `EscapeBuffer` — published as `@cluesmith/codev-core`
+- **TICK protocol removed** (Spec 653): Replaced by multi-PR workflow in SPIR/ASPIR; verify phase added; worktree reused across multiple PRs
+- **Hermes consult backend** (Spec 671): Optional 4th consultation model; kept off by default
+- **afx rename** (Spec 647): `af` → `afx` across CLI, bin shims, and docs
+- **Configuration overhaul** (Spec 618): Systematic config reorganization
+- **Terminal scroll consolidation** (Spec 627): `ScrollController` state machine replaces three competing mechanisms
+- **Team standalone CLI** (Spec 599): `team` extracted from `afx team`
+- **pnpm monorepo migration** (PR #669): Yarn/npm workspaces → pnpm 10
+- **MAINTAIN protocol simplification** (current branch base): Reduced from 4 phases to 2
+
+## What Was Done
+
+### Dead Code / Dependencies Removed
+
+| Item | Location | Why |
+|------|----------|-----|
+| `http-proxy` | `packages/codev/package.json` | Zero imports in `src/`; leftover from pre-Tower dashboard proxy. Flagged in run 0006 but not removed then. |
+| `@types/http-proxy` | `packages/codev/package.json` | Types for the now-unused `http-proxy` package. |
+
+Other ts-prune/depcheck findings were investigated but retained:
+
+- `@vitest/coverage-v8` — dynamically loaded by vitest config at `vitest.config.ts:30` (`provider: 'v8'`), depcheck can't detect this.
+- `@xterm/xterm` — was flagged as transitively resolved; per Gemini's 3-way review, pinned explicitly in `devDependencies` (`^5.5.0`) since the test file imports it directly. Relying on a transitive dashboard dep was fragile.
+- `state.ts` util/annotation/architect exports — used in test files; part of public state API surface.
+- `forge.ts`, `github.ts`, `templates.ts`, `scaffold.ts`, `skeleton.ts`, `team.ts` unused exports — all used by their sibling test files. Conservative: keep public API stable.
+- `cli.ts:378 run()` — exported for bin shims (`afx.js`, `consult.js`).
+- `terminal/index.ts` re-exports — barrel file for external consumers; not dead.
+
+### Documentation Updated
+
+**`codev/resources/arch.md`**:
+- Refreshed `afx` commands tree: added `spawn-worktree`, `spawn-roles`, `attach`, `architect`, `shell`, `tower`, `tower-cloud`, `cron`, `team`, `team-update`, `db`; removed non-existent `util.ts`.
+- Refreshed `bin/` tree: added `af.js` (deprecation shim) and `generate-image.js`.
+- Refreshed `codev/protocols/` tree: added `aspir`, `air`, `bugfix`, `release`, `spike`, and `protocol-schema.json` (were missing).
+- Corrected `spir/` subtree: removed nonexistent `manifest.yaml`; added actual files (`protocol.json`, `builder-prompt.md`, `prompts/`, `consult-types/`).
+- Refreshed `codev-skeleton/protocols/` subtree: added `aspir`, `air`, `bugfix`, `spike` (was stale — only listed `spir`, `experiment`, `maintain`).
+- Updated version footer: `v2.0.0-rc.54` → `v3.0.0-rc.9`; date bumped to 2026-04-17.
+
+**`codev/resources/lessons-learned.md`**:
+- Added 3 lessons from Spec 653 (builder handling / TICK removal) at the end of the **Critical (Prevent Major Failures)** section: start from structural insight, full-repo grep for protocol removal, single verify-pass consultation cadence.
+- Updated footer date.
+
+**`AGENTS.md`**:
+- Synced with `CLAUDE.md` — local-install instructions updated to pnpm 10 monorepo flow (`pnpm local-install` targets both `codev-core` and `codev` tarballs in one `npm install -g` call). Prior AGENTS.md copy still referenced the pre-monorepo `cd packages/codev && pnpm pack` flow.
+- `diff CLAUDE.md AGENTS.md` is now clean.
+
+### Documentation Changes Log
+
+| Document | Section | Action | Reason |
+|----------|---------|--------|--------|
+| arch.md | afx commands tree | UPDATED | Tree was missing 10 commands added since run 0006; listed obsolete `util.ts` |
+| arch.md | bin scripts tree | UPDATED | Missing `af.js` deprecation shim and `generate-image.js` |
+| arch.md | codev protocols tree | UPDATED | Missing `aspir`, `air`, `bugfix`, `release`, `spike` |
+| arch.md | version footer | UPDATED | Was stamped at v2.0.0-rc.54; now v3.0.0-rc.9 pre-release |
+| lessons-learned.md | Critical | APPENDED | 3 entries from Spec 653 review |
+| lessons-learned.md | footer | UPDATED | Run date 2026-04-17 |
+| AGENTS.md | Local Build Testing | REWRITTEN | OBSOLETE — pre-pnpm-monorepo; drifted from CLAUDE.md during PR #669 |
+
+## Verification
+
+- `pnpm install` → clean
+- `pnpm build` → passes (codev-core, codev, dashboard all built)
+- `pnpm --filter @cluesmith/codev test` → **122 test files, 2462 passed, 13 skipped**
+
+## Deferred
+
+- **`@vitest/coverage-v8` depcheck false positive** — could add explicit import to silence depcheck, but the `provider: 'v8'` string is the idiomatic vitest pattern. Not worth special-casing.
+- **`@xterm/xterm` missing-dep warning** — would need to add as explicit dev dep in `packages/codev` or refactor the test to import through dashboard. Not runtime-critical.
+- **arch.md full rewrite** — `arch.md` is 1,776 lines; ~90% still accurate. A full rewrite is out of scope for a pre-release MAINTAIN pass.
+- **`ts-prune` noise from barrel files** — `terminal/index.ts` re-exports would need per-file annotation (`// ts-prune-ignore-next`) or a config file to silence. Low value.
+
+## Consultation Log
+
+3-way review run before opening PR (prompt at `/tmp/maintain-0007-consult-prompt.md`):
+
+| Reviewer | Verdict | Key findings |
+|----------|---------|--------------|
+| **Gemini** | REQUEST_CHANGES | Missed `protocol-schema.json` in tree; `codev-skeleton/protocols/` subtree still stale; lessons placed under wrong section heading (ran report said Critical, actually appended to end of file); push back on deferring `@xterm/xterm` — one-line fix, just add the devDep. |
+| **Codex** | APPROVE_WITH_COMMENTS | `spir/` subtree listed nonexistent `manifest.yaml`; `codev-skeleton/protocols/` still stale (same as Gemini); noted CLI examples elsewhere in arch.md (`afx util`, `afx tunnel`, `afx ports`) are stale but out of scope. |
+| **Claude** | APPROVE_WITH_COMMENTS | All three trees and dep removal verified against filesystem. Noted pre-existing duplicate step numbering (`# 3`) in local-install section of CLAUDE.md/AGENTS.md (not introduced here). |
+
+### Actions taken in response
+
+- Added `protocol-schema.json` to `codev/protocols/` tree (Gemini)
+- Fixed `spir/` subtree to match actual files (Codex)
+- Refreshed `codev-skeleton/protocols/` subtree (Gemini + Codex)
+- Moved Spec 653 lessons into the **Critical** section (Gemini)
+- Added `@xterm/xterm` to `packages/codev` devDependencies (Gemini)
+- Not addressed: the stale CLI examples elsewhere in arch.md — Codex flagged these as out-of-scope, and fixing them well would require a broader CLI audit. Deferred to a future MAINTAIN pass.
+- Not addressed: duplicate `# 3` step numbering in CLAUDE.md/AGENTS.md. Pre-existing on `main`; belongs in a separate doc tweak.
+
+## Summary
+
+First run on the simplified (2-phase) MAINTAIN protocol. The dependency cleanup caught up on the one un-acted item from run 0006's findings (`http-proxy`). Documentation sync was the bulk of the work: arch.md's directory trees had drifted significantly over 1,751 commits (VS Code extension, codev-core split, pnpm migration, afx rename, TICK removal). Everything builds and all unit tests pass against the refreshed tree.

codev/resources/arch.md

@@ -1046,16 +1046,26 @@ codev/                                  # Project root (pnpm monorepo)
 │   │   │   ├── state.ts                # SQLite state management
 │   │   │   ├── types.ts                # Type definitions
 │   │   │   ├── commands/               # afx CLI commands
-│   │   │   │   ├── start.ts            # Start architect dashboard
+│   │   │   │   ├── start.ts            # Start Tower workspace
 │   │   │   │   ├── stop.ts             # Stop all processes
 │   │   │   │   ├── spawn.ts            # Spawn builder
+│   │   │   │   ├── spawn-worktree.ts   # Create git worktree for spawn
+│   │   │   │   ├── spawn-roles.ts      # Role prompt injection for spawn
 │   │   │   │   ├── status.ts           # Show status
 │   │   │   │   ├── cleanup.ts          # Clean up builder
-│   │   │   │   ├── util.ts             # Utility shell
 │   │   │   │   ├── open.ts             # File annotation viewer
 │   │   │   │   ├── send.ts             # Send message to builder
-│   │   │   │   ├── rename.ts           # Rename builder/util
-│   │   │   │   └── bench.ts            # Consultation benchmarking (afx bench)
+│   │   │   │   ├── rename.ts           # Rename builder
+│   │   │   │   ├── bench.ts            # Consultation benchmarking (afx bench)
+│   │   │   │   ├── attach.ts           # Attach directly to shellper session
+│   │   │   │   ├── architect.ts        # Architect session management
+│   │   │   │   ├── shell.ts            # Shell session management
+│   │   │   │   ├── tower.ts            # Tower daemon control (start/stop)
+│   │   │   │   ├── tower-cloud.ts      # Cloud tunnel management
+│   │   │   │   ├── cron.ts             # Scheduled task management
+│   │   │   │   ├── team.ts             # Team operations (deprecated; use `team` CLI)
+│   │   │   │   ├── team-update.ts      # Team activity aggregation
+│   │   │   │   └── db.ts               # SQLite database commands
 │   │   │   ├── servers/                # Web servers (Spec 0105 decomposition)
 │   │   │   │   ├── tower-server.ts     # Orchestrator: HTTP/WS server creation, subsystem init, shutdown
 │   │   │   │   ├── tower-routes.ts     # HTTP route handlers (~30 routes)
@@ -1078,9 +1088,11 @@ codev/                                  # Project root (pnpm monorepo)
 │   ├── bin/                            # CLI entry points
 │   │   ├── codev.js                    # codev command
 │   │   ├── afx.js                      # afx command (af.js deprecated, redirects)
+│   │   ├── af.js                       # Deprecated; redirects to afx
 │   │   ├── consult.js                  # consult command
 │   │   ├── team.js                     # team command
-│   │   └── porch.js                    # porch command
+│   │   ├── porch.js                    # porch command
+│   │   └── generate-image.js           # generate-image command
 │   ├── dashboard-dist/                 # Dashboard build output (copied from packages/dashboard/dist)
 │   ├── skeleton/                       # Embedded codev-skeleton (built)
 │   ├── templates/                      # HTML templates
@@ -1100,10 +1112,19 @@ codev/                                  # Project root (pnpm monorepo)
 │   ├── protocols/                      # Working copies for development
 │   │   ├── spir/                       # Multi-phase with consultation
 │   │   │   ├── protocol.md
+│   │   │   ├── protocol.json
+│   │   │   ├── builder-prompt.md
 │   │   │   ├── templates/
-│   │   │   └── manifest.yaml
+│   │   │   ├── prompts/
+│   │   │   └── consult-types/
+│   │   ├── aspir/                      # Autonomous SPIR (no human gates)
+│   │   ├── air/                        # Autonomous Implement & Review
+│   │   ├── bugfix/                     # GitHub Issue-driven fixes
 │   │   ├── experiment/                 # Disciplined experimentation
-│   │   └── maintain/                   # Codebase maintenance
+│   │   ├── release/                    # Version release procedure
+│   │   ├── spike/                      # Time-boxed research
+│   │   ├── maintain/                   # Codebase maintenance
+│   │   └── protocol-schema.json        # JSON schema for protocol.json files
 │   ├── specs/                          # Our feature specifications
 │   ├── plans/                          # Our implementation plans
 │   ├── reviews/                        # Our lessons learned
@@ -1118,7 +1139,11 @@ codev/                                  # Project root (pnpm monorepo)
 │   ├── templates/                      # Document templates (CLAUDE.md, arch.md, etc.)
 │   ├── protocols/                      # Protocol definitions
 │   │   ├── spir/
+│   │   ├── aspir/
+│   │   ├── air/
+│   │   ├── bugfix/
 │   │   ├── experiment/
+│   │   ├── spike/
 │   │   └── maintain/
 │   ├── specs/                          # Empty (placeholder)
 │   ├── plans/                          # Empty (placeholder)
@@ -1771,6 +1796,6 @@ See [MAINTAIN protocol](../protocols/maintain/protocol.md) for codebase hygiene
 
 ---
 
-**Last Updated**: 2026-02-18
-**Version**: v2.0.0-rc.54 (Pre-release)
-**Changes**: Refinement round 4/4 -- final fresh-eyes pass. See CHANGELOG.md for version history.
+**Last Updated**: 2026-04-17
+**Version**: v3.0.0-rc.9 (Pre-release)
+**Changes**: Pre-v3.0.0 MAINTAIN run (0007): directory tree refresh, protocol list update, removed unused http-proxy dependency. See CHANGELOG.md for version history.

codev/resources/lessons-learned.md

@@ -38,6 +38,9 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated
 - [From 0324] `detached: true` and `child.unref()` are necessary but not sufficient for process independence -- any pipe-based stdio (e.g., `stdio: ['ignore', 'pipe', 'pipe']`) creates a lifecycle dependency between parent and child processes. When the parent exits, the broken pipe triggers unhandled EPIPE errors in the child. Use file FDs or `'ignore'` for truly independent daemon children.
 - [From bugfix-274] Startup ordering matters when multiple subsystems share resources (Shellper sockets). Initialization order creates implicit synchronization -- calling `initInstances()` before `reconcileTerminalSessions()` allowed dashboard polls to race with reconciliation. Document ordering constraints in comments.
 - [From bugfix-274] Defense in depth for race conditions: the startup reorder closes the primary race path, but the `_reconciling` guard provides a safety net for code paths that bypass the primary fix (e.g., direct `/project/.../api/state` requests bypassing `getInstances()`).
+- [From 653] Start from the structural insight, not the feature list. The first three spec drafts built elaborate gate-ceremony machinery (checkpoint PRs, feedback commands, verify notes) that was all eliminated once the core insight — break the 1:1 builder↔PR assumption — was identified. When a spec feels bloated, look for the one structural change that makes the ceremony unnecessary.
+- [From 653] Protocol removal requires full-repo grep, not targeted searches. Removing a protocol touches ~50 files across source, docs, templates, skills, tests, and CLI help text. Scoped searches miss skeleton templates, test fixtures, and user-facing help strings. Run `rg` across the entire repo and verify zero hits before committing.
+- [From 653] Single verify pass + rebuttal is the right consultation cadence. Multi-iteration consult loops (running `consult` manually after each fix) violate `max_iterations=1` and add little marginal value over one rigorous verify pass followed by rebuttals.
 
 ## Security
 
@@ -364,5 +367,5 @@ Generalizable wisdom extracted from review documents, ordered by impact. Updated
 
 ---
 
-*Last updated: 2026-03-18 (Spec 627 — terminal scroll management consolidation)*
+*Last updated: 2026-04-17 (Maintenance run 0007 — v3.0.0 pre-release)*
 *Source: codev/reviews/*

packages/codev/package.json

@@ -41,12 +41,10 @@
     "@anthropic-ai/claude-agent-sdk": "^0.2.41",
     "@google/genai": "^1.0.0",
     "@openai/codex-sdk": "^0.101.0",
-    "@types/http-proxy": "^1.17.17",
     "better-sqlite3": "^12.5.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "glob": "^11.0.0",
-    "http-proxy": "^1.18.1",
     "js-yaml": "^4.1.0",
     "node-pty": "^1.1.0",
     "open": "^10.1.0",
@@ -57,6 +55,7 @@
     "@cluesmith/codev-dashboard": "workspace:*",
     "@cluesmith/codev-types": "workspace:*",
     "@playwright/test": "^1.58.0",
+    "@xterm/xterm": "^5.5.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.1",