paircode 0.10.1__tar.gz → 0.11.3__tar.gz

{paircode-0.10.1 → paircode-0.11.3}/.gitignore

@@ -35,3 +35,6 @@ ENV/
 /tmp/
 scratch/
 dist/
+
+# paircode runtime state (focuses, peer workspaces, etc.)
+.paircode/

paircode-0.11.3/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: paircode
+Version: 0.11.3
+Summary: Adversarial journey framework — orchestrate multiple LLM peers through research, plan, and execute stages with file-trace peer review.
+Project-URL: Homepage, https://github.com/starshipagentic/paircode
+Project-URL: Repository, https://github.com/starshipagentic/paircode
+Project-URL: Issues, https://github.com/starshipagentic/paircode/issues
+Author-email: Travis Somerville <travis.somerville@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,claude,codex,gemini,llm,multi-agent,ollama,orchestration,peer-review
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: cliworker>=0.8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# paircode
+
+**Multi-LLM peer review for your code, with file-traces on disk.** One primary LLM (alpha, usually Claude Code) + any number of peer LLMs (Codex, Gemini, Ollama, …) running research / plan / execute / ask cycles with structured cross-review rounds stored entirely as Markdown on disk.
+
+> Born from 31 iterations of dual-LLM silent-agreement hunting on a real ML project. See `diary/001-step-a-architecture.md` for the origin story and `diary/003-arch-b-pivot-grappling.md` for the current (v0.11) team-lead architecture.
+
+## Install
+
+```bash
+pipx install paircode       # or: pip install --user paircode
+paircode install            # registers /paircode in every detected LLM CLI
+```
+
+`paircode install` deploys `/paircode` into each LLM CLI it finds on your PATH:
+
+| CLI | How it's installed | What you get |
+|---|---|---|
+| Claude Code | file-drop `~/.claude/commands/paircode.md` | `/paircode` slash command |
+| Codex CLI | `codex marketplace add starshipagentic/paircode-codex` | `/paircode` slash command |
+| Gemini CLI | `gemini extensions install github.com/starshipagentic/paircode-gemini --consent` | `/paircode` slash command |
+
+In Gemini you may need `/commands reload` the first time. In Codex the marketplace fetches on first use.
+
+paircode delegates LLM subprocess invocation to [`cliworker`](https://pypi.org/project/cliworker/) — that's where speed flags, MCP strip tricks, skip-cache, and subscription-first fallback live. paircode adds the peer-review orchestration on top (file-traces, stages, rosters, convergence).
+
+## Use it
+
+Inside any LLM CLI that has `/paircode` installed, just type:
+
+```
+/paircode "build a KISS PHQ-9 depression risk engine"
+```
+
+or
+
+```
+/paircode "review my auth middleware approach at src/auth/"
+/paircode "plan the refactor" --peers codex,gemini
+/paircode "get a second opinion on this PR" --peer gemini
+```
+
+The slash command's team-lead prompt (the LLM you're inside) reads your prompt, picks a stage (`research | plan | execute | ask`), fires peers, collects their markdown, iterates through review rounds until convergence, and writes `consensus.md` at the end. Everything lands under `.paircode/` in your current project.
+
+## What ends up on disk
+
+```
+your-project/
+  .paircode/
+    JOURNEY.md                    # fleet log
+    peers.yaml                    # roster: who's on the team
+    peers/
+      peer-a-codex/               # codex's persistent sandbox (code goes here)
+      peer-b-gemini/               # gemini's persistent sandbox
+    focus-01-<slug>/
+      FOCUS.md                    # this focus's prompt + metadata
+      research/
+        alpha-v1.md ... alpha-vN.md
+        peer-a-codex-v1.md ...
+        reviews/round-01-peer-a-codex-critiques-alpha.md
+        alpha-FINAL.md
+        peer-a-codex-FINAL.md
+        consensus.md              # team-lead synthesis (last thing written)
+      plan/         (same shape)
+      execute/      (same shape)
+      ask/          (same shape)
+    focus-02-<slug>/
+      ...
+```
+
+**Code vs. reports.** Files inside `focus-*/` are markdown *reports* (opinions, plans, critiques, summaries of work). Actual code lives elsewhere:
+
+- **Peers** code in their sandboxed workspaces at `.paircode/peers/<peer-id>/` — persistent across focuses.
+- **Alpha** codes directly in the project root (the real repo) — alpha *is* the project.
+
+## Stages
+
+Stage is picked by the team-lead LLM based on the prompt:
+
+| Stage | When | Typical prompt |
+|---|---|---|
+| `research` | Explore new ground | "build X", "find the right Y", "how should we approach Z" |
+| `plan` | Concrete implementation plan from prior research | "plan the refactor based on focus-02" |
+| `execute` | Do the work from an existing plan | "execute the plan at focus-02" |
+| `ask` | Get opinions on existing work | "what does codex think of this PR", "review my approach at <path>" |
+
+The team lead can chain stages in one invocation: `research → plan → execute → done`. No hard round cap — the team lead converges when peers stop surfacing new signal.
+
+## Commands (the helper CLI)
+
+Most users will only ever type `paircode install` and then use `/paircode` inside their LLM CLI. The binary's other commands are helpers the team-lead slash command calls on your behalf:
+
+```
+paircode                         print current .paircode/ state
+paircode install                 register /paircode in every detected LLM CLI
+paircode uninstall               remove /paircode from LLM CLIs (idempotent)
+paircode ensure-scaffold         idempotent .paircode/ init + handshake (silent)
+paircode focus new <slug>        create a new focus dir, print its path
+paircode focus active            print the active focus path
+paircode roster [--alpha <cli>] [--peer <id>] [--peers <id,id>]
+                                 print peer ids, best-effort, never errors
+paircode invoke <peer-id> "<prompt>" --out <path>
+                                 fire one peer, write file-trace to --out
+paircode converge <stage>        copy each participant's latest vN to *-FINAL.md
+```
+
+## Model compatibility
+
+| CLI | `/paircode` slash command | Peer invocation | Parallel peers? | Status |
+|---|---|---|---|---|
+| Claude Code (`claude`) | ✓ file-drop at `~/.claude/commands/paircode.md` | ✓ `claude -p <prompt>` | ✓ via Agent tool + `run_in_background=true` | stable |
+| Codex (`codex`) | ✓ via `codex marketplace add` | ✓ `codex exec <prompt>` | ✗ serial-only (codex constraint) | stable |
+| Gemini (`gemini`) | ✓ via `gemini extensions install` | ✓ `gemini -p <prompt>` | ✗ serial-only (gemini constraint) | stable |
+| Ollama (`ollama`) | — (local models, no slash-cmd host) | ✓ `ollama run <model> <prompt>` | n/a | peer-only |
+| Aider / others | — | best-effort, PRs welcome | — | planned |
+
+Peer roster is auto-detected at first install via `paircode handshake` (silent, called by `ensure-scaffold`). Edit `.paircode/peers.yaml` to customize.
+
+## Why this exists
+
+See [`diary/001-step-a-architecture.md`](diary/001-step-a-architecture.md). Short version: running two LLMs adversarially surfaces silent-agreement bug classes that neither engine alone catches — cross-engine agreement is not the same as correctness when both engines share a blind spot.
+
+See [`diary/003-arch-b-pivot-grappling.md`](diary/003-arch-b-pivot-grappling.md) for why v0.11 moved orchestration out of a Python driver and into the slash-command's team-lead LLM.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

paircode-0.11.3/README.md

@@ -0,0 +1,126 @@
+# paircode
+
+**Multi-LLM peer review for your code, with file-traces on disk.** One primary LLM (alpha, usually Claude Code) + any number of peer LLMs (Codex, Gemini, Ollama, …) running research / plan / execute / ask cycles with structured cross-review rounds stored entirely as Markdown on disk.
+
+> Born from 31 iterations of dual-LLM silent-agreement hunting on a real ML project. See `diary/001-step-a-architecture.md` for the origin story and `diary/003-arch-b-pivot-grappling.md` for the current (v0.11) team-lead architecture.
+
+## Install
+
+```bash
+pipx install paircode       # or: pip install --user paircode
+paircode install            # registers /paircode in every detected LLM CLI
+```
+
+`paircode install` deploys `/paircode` into each LLM CLI it finds on your PATH:
+
+| CLI | How it's installed | What you get |
+|---|---|---|
+| Claude Code | file-drop `~/.claude/commands/paircode.md` | `/paircode` slash command |
+| Codex CLI | `codex marketplace add starshipagentic/paircode-codex` | `/paircode` slash command |
+| Gemini CLI | `gemini extensions install github.com/starshipagentic/paircode-gemini --consent` | `/paircode` slash command |
+
+In Gemini you may need `/commands reload` the first time. In Codex the marketplace fetches on first use.
+
+paircode delegates LLM subprocess invocation to [`cliworker`](https://pypi.org/project/cliworker/) — that's where speed flags, MCP strip tricks, skip-cache, and subscription-first fallback live. paircode adds the peer-review orchestration on top (file-traces, stages, rosters, convergence).
+
+## Use it
+
+Inside any LLM CLI that has `/paircode` installed, just type:
+
+```
+/paircode "build a KISS PHQ-9 depression risk engine"
+```
+
+or
+
+```
+/paircode "review my auth middleware approach at src/auth/"
+/paircode "plan the refactor" --peers codex,gemini
+/paircode "get a second opinion on this PR" --peer gemini
+```
+
+The slash command's team-lead prompt (the LLM you're inside) reads your prompt, picks a stage (`research | plan | execute | ask`), fires peers, collects their markdown, iterates through review rounds until convergence, and writes `consensus.md` at the end. Everything lands under `.paircode/` in your current project.
+
+## What ends up on disk
+
+```
+your-project/
+  .paircode/
+    JOURNEY.md                    # fleet log
+    peers.yaml                    # roster: who's on the team
+    peers/
+      peer-a-codex/               # codex's persistent sandbox (code goes here)
+      peer-b-gemini/               # gemini's persistent sandbox
+    focus-01-<slug>/
+      FOCUS.md                    # this focus's prompt + metadata
+      research/
+        alpha-v1.md ... alpha-vN.md
+        peer-a-codex-v1.md ...
+        reviews/round-01-peer-a-codex-critiques-alpha.md
+        alpha-FINAL.md
+        peer-a-codex-FINAL.md
+        consensus.md              # team-lead synthesis (last thing written)
+      plan/         (same shape)
+      execute/      (same shape)
+      ask/          (same shape)
+    focus-02-<slug>/
+      ...
+```
+
+**Code vs. reports.** Files inside `focus-*/` are markdown *reports* (opinions, plans, critiques, summaries of work). Actual code lives elsewhere:
+
+- **Peers** code in their sandboxed workspaces at `.paircode/peers/<peer-id>/` — persistent across focuses.
+- **Alpha** codes directly in the project root (the real repo) — alpha *is* the project.
+
+## Stages
+
+Stage is picked by the team-lead LLM based on the prompt:
+
+| Stage | When | Typical prompt |
+|---|---|---|
+| `research` | Explore new ground | "build X", "find the right Y", "how should we approach Z" |
+| `plan` | Concrete implementation plan from prior research | "plan the refactor based on focus-02" |
+| `execute` | Do the work from an existing plan | "execute the plan at focus-02" |
+| `ask` | Get opinions on existing work | "what does codex think of this PR", "review my approach at <path>" |
+
+The team lead can chain stages in one invocation: `research → plan → execute → done`. No hard round cap — the team lead converges when peers stop surfacing new signal.
+
+## Commands (the helper CLI)
+
+Most users will only ever type `paircode install` and then use `/paircode` inside their LLM CLI. The binary's other commands are helpers the team-lead slash command calls on your behalf:
+
+```
+paircode                         print current .paircode/ state
+paircode install                 register /paircode in every detected LLM CLI
+paircode uninstall               remove /paircode from LLM CLIs (idempotent)
+paircode ensure-scaffold         idempotent .paircode/ init + handshake (silent)
+paircode focus new <slug>        create a new focus dir, print its path
+paircode focus active            print the active focus path
+paircode roster [--alpha <cli>] [--peer <id>] [--peers <id,id>]
+                                 print peer ids, best-effort, never errors
+paircode invoke <peer-id> "<prompt>" --out <path>
+                                 fire one peer, write file-trace to --out
+paircode converge <stage>        copy each participant's latest vN to *-FINAL.md
+```
+
+## Model compatibility
+
+| CLI | `/paircode` slash command | Peer invocation | Parallel peers? | Status |
+|---|---|---|---|---|
+| Claude Code (`claude`) | ✓ file-drop at `~/.claude/commands/paircode.md` | ✓ `claude -p <prompt>` | ✓ via Agent tool + `run_in_background=true` | stable |
+| Codex (`codex`) | ✓ via `codex marketplace add` | ✓ `codex exec <prompt>` | ✗ serial-only (codex constraint) | stable |
+| Gemini (`gemini`) | ✓ via `gemini extensions install` | ✓ `gemini -p <prompt>` | ✗ serial-only (gemini constraint) | stable |
+| Ollama (`ollama`) | — (local models, no slash-cmd host) | ✓ `ollama run <model> <prompt>` | n/a | peer-only |
+| Aider / others | — | best-effort, PRs welcome | — | planned |
+
+Peer roster is auto-detected at first install via `paircode handshake` (silent, called by `ensure-scaffold`). Edit `.paircode/peers.yaml` to customize.
+
+## Why this exists
+
+See [`diary/001-step-a-architecture.md`](diary/001-step-a-architecture.md). Short version: running two LLMs adversarially surfaces silent-agreement bug classes that neither engine alone catches — cross-engine agreement is not the same as correctness when both engines share a blind spot.
+
+See [`diary/003-arch-b-pivot-grappling.md`](diary/003-arch-b-pivot-grappling.md) for why v0.11 moved orchestration out of a Python driver and into the slash-command's team-lead LLM.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

paircode-0.11.3/diary/002-v0.10-release-pipeline.md

@@ -0,0 +1,126 @@
+# Diary 002 — v0.10 release pipeline + cliworker split + satellite repos
+
+**Stardate:** 2026-04-18
+**From:** v0.9.1 (file-drop install for all 3 CLIs)
+**To:** v0.10.1 (native register via satellite repos, driven by `cliworker.invoke()`)
+
+---
+
+## Context — what v0.10 cracked open
+
+Between v0.1 and v0.9 paircode's installer evolved through four bad implementations (broken codex rules file, per-CLI no-ops, file-drop, correct file-drop) before landing on the right answer in v0.10: use each vendor's own registration command, not file-drop.
+
+Research (2026-04-18) confirmed both Codex and Gemini now have user-level slash-command registration:
+- Codex 0.121.0 → `codex marketplace add <owner/repo>` (git-clones a marketplace repo)
+- Gemini 0.35.3 → `gemini extensions install <url> --consent` (git-clones an extension repo)
+
+Neither is deprecated (Codex has both `marketplace` and a now-deprecated `prompts/` file-drop). Industry pattern for tools installing their own slash commands → **native register when available**. So paircode joins that pattern.
+
+## The three-repo architecture
+
+```
+~/dev/paircode              Python package (main repo, pypi)
+├── src/paircode/templates/
+│   ├── claude_slash_command.md      source of truth
+│   ├── codex_slash_command.md       ↓
+│   └── gemini_slash_command.toml    ↓
+└── scripts/release.py               auto-syncs to satellites
+
+~/dev/paircode-codex        Codex marketplace satellite (GitHub only)
+├── .agents/plugins/marketplace.json
+├── plugins/paircode/
+│   ├── .codex-plugin/plugin.json
+│   └── commands/paircode.md         copied from paircode's template
+└── README + LICENSE
+
+~/dev/paircode-gemini       Gemini extension satellite (GitHub only)
+├── gemini-extension.json
+├── commands/paircode.toml           copied from paircode's template
+└── README + LICENSE
+```
+
+**Zero Python in the satellites.** The Python `paircode` CLI lives once, on pypi. Satellites hold only the slash-command manifest each vendor expects. `/paircode` triggers a markdown/TOML prompt telling the host CLI to shell out to the `paircode` binary — which the user already installed via `pipx install paircode`.
+
+## Install flow after v0.10
+
+```bash
+pipx install paircode          # Python binary, once
+paircode install               # registers /paircode in every detected LLM CLI
+```
+
+`paircode install` does per CLI:
+- **claude** — file-drop `~/.claude/commands/paircode.md` (unchanged, it's the native pattern)
+- **codex**  — `cliworker.invoke("codex", "marketplace", "add", "starshipagentic/paircode-codex")`
+- **gemini** — `cliworker.invoke("gemini", "extensions", "install", "https://github.com/starshipagentic/paircode-gemini", "--consent")`
+
+All three idempotent:
+- claude overwrites file (harmless)
+- codex greps `~/.codex/config.toml` for `[marketplaces.paircode]` before invoking
+- gemini greps `gemini extensions list` for `paircode` before invoking
+
+All three graceful on failure:
+- If the `invoke()` call returns ok=False, installer prints the exact command for copy-paste + captured stderr
+- Never silently succeeds with a non-working state
+
+## Why `cliworker.invoke()` exists
+
+cliworker already had `run(prompt, *clis, ...)` for LLM invocation. Admin commands like `codex marketplace add` aren't LLM invocations — no prompt, no API-key stripping, no CLAUDE_FAST, no fallback chain. But they DO want cliworker's subprocess plumbing: timeout, FileNotFoundError handling, `CLIResult` dataclass, skip-cache opt-in.
+
+v0.8 of cliworker added `invoke(cli, *args, ...)` — same subprocess guts, no LLM semantics. Default `stdin=DEVNULL` so any unexpected interactive prompt fails fast instead of hanging (critical: Gemini's `extensions install` has a fallback "install via git clone?" prompt if the GitHub release is missing).
+
+Paircode uses it. Navcom can use it later. Any tool that wants "run a CLI, get a CLIResult back" gets it for free.
+
+## The release pipeline
+
+`scripts/release.py` is the only command needed to cut a paircode release:
+
+```bash
+cd ~/dev/paircode
+./scripts/release.py 0.11.0      # explicit version
+./scripts/release.py patch       # auto-bump patch segment
+./scripts/release.py minor
+./scripts/release.py --dry-run 0.11.0    # preview, write nothing
+```
+
+What it does in order:
+1. Preflight — working trees clean, tests pass, required tools present (git, starforge, gh)
+2. Bump paircode version in `pyproject.toml` + `src/paircode/__init__.py`
+3. Commit + tag + push paircode to GitHub
+4. `starforge beam --pypi` → publishes to pypi (with user's auto-approved yes pipe)
+5. For each satellite:
+   - Copy latest template from paircode's `src/paircode/templates/`
+   - Bump version in the satellite's manifest
+   - Commit + tag + push
+   - `starforge beam` (no --pypi, just GitHub)
+   - `gh release create` — **critical** for Gemini, which falls back to an interactive prompt when the release is missing
+6. Print summary with every URL
+
+One command = pypi, main GitHub repo, both satellite GitHub repos, both satellite GitHub releases, all version-locked.
+
+## Open paper cuts (not shipping blockers)
+
+- **`__version__` string drift** — starforge auto-bumps `pyproject.toml` version on publish (e.g., 0.10.0 → 0.10.1) but leaves `__init__.py` alone. Every release needs a manual follow-up commit to sync. The release.py script could detect starforge's bump and sync automatically; not implemented yet.
+- **Codex has no uninstall CLI** — paircode's `uninstall` for codex edits `~/.codex/config.toml` directly (strips the `[marketplaces.paircode]` section). Fragile. If OpenAI adds `codex marketplace remove <name>`, migrate to that.
+- **Gemini keychain warning** — on macOS Homebrew install, gemini prints `Keychain initialization encountered an error: Cannot find module '../build/Release/keytar.node'` before every command. It falls back to FileKeychain so everything still works. Not a paircode bug; noisy stderr captured in some idempotency checks. Could be suppressed.
+
+## Key files — where to look when something changes
+
+| Change this template | Edit this file | Satellites auto-sync on next release |
+|---|---|---|
+| Claude slash command | `src/paircode/templates/claude_slash_command.md` | (only Claude; no satellite) |
+| Codex slash command | `src/paircode/templates/codex_slash_command.md` | `paircode-codex/plugins/paircode/commands/paircode.md` |
+| Gemini slash command | `src/paircode/templates/gemini_slash_command.toml` | `paircode-gemini/commands/paircode.toml` |
+| Runner (subprocess → LLM) | `src/paircode/runner.py` (delegates to `cliworker.run`/`run_fast`) | — |
+| Installer behavior | `src/paircode/installer.py` (delegates to `cliworker.invoke`) | — |
+| Release steps | `scripts/release.py` | — |
+
+## Verified live (2026-04-18)
+
+- `cliworker` 0.8.1 on pypi with `invoke()`
+- `paircode` 0.10.1 on pypi, depends on `cliworker>=0.8.1`
+- `starshipagentic/paircode-codex` at tag v0.10.0, GitHub release live
+- `starshipagentic/paircode-gemini` at tag v0.10.0, GitHub release live
+- End-to-end `paircode uninstall && paircode install` on dev machine: all three CLIs cleanly register/deregister, `/paircode` appears in each tool's slash menu
+- 52 pytest green in paircode, 88 pytest green in cliworker
+
+*End of diary 002. Next milestone targets: real-data validation, cross-project orchestration.*

paircode-0.11.3/diary/003-arch-b-pivot-grappling.md

@@ -0,0 +1,133 @@
+# Diary 003 — Arch-B pivot: cold-use failure exposed Python-driven orchestrator as a regression
+
+**Stardate:** 2026-04-20
+**From:** v0.10.1 — Python-driven orchestrator (drive.py with ThreadPoolExecutor spawning fresh `claude -p` / `gemini -p` / `codex exec` subprocesses in parallel)
+**Toward:** Arch B — interactive Claude session IS the team lead; Python shrinks to filesystem scaffolding + template rendering
+
+**This diary is a preservation record, not a migration log.** No code has changed on `main` beyond this file. A companion branch `path-python-controls-stages` pins the current Python-driven state so we can return if Arch B underdelivers.
+
+---
+
+## What triggered this pivot
+
+The maintainer ran `/paircode` cold in Claude Code after weeks away, trying to get a second opinion on an unrelated engineering question. He typed:
+
+```
+/paircode use gemini for reserach only to 'i mean go look at their actual releases...'
+```
+
+Four concrete failures in one invocation:
+
+1. **Slash command pass-through failed.** `~/.claude/commands/paircode.md` instructs the LLM to pass args literally to the CLI. `paircode use gemini for research only to '...'` → `Error: No such command 'use'`. The slash command's own literal-pass-through instruction is the failing case.
+2. **Fallback picked the wrong flag.** The previous session fell back to `paircode drive "<topic>" --alpha-cli gemini --research-only`. Wrong: `--alpha-cli` swaps the driver — it replaces Claude with Gemini as alpha. The maintainer wanted Claude (this session) to keep driving and Gemini to be added as a peer. Inverted alpha/peer.
+3. **No primitive for "just get an opinion".** The architecture has `research → plan → execute`. "What does Gemini think of X" isn't any of those — it's review-of-existing. No native primitive. The previous session hacked it with `--research-only`, which is semantically wrong.
+4. **Flag soup.** `--alpha-cli`, `--alpha-model`, `--timeout`, `--research-rounds`, `--plan-rounds`, `--execute-rounds`, `--research-only`. User has to pre-classify their task into flag combinations before typing the quoted prompt.
+
+The redesign brief written mid-session (see conversation transcript 2026-04-20) names these as Gap 1–4.
+
+## What the maintainer wants
+
+Single verb CLI:
+
+```
+paircode "<whatever you want>"                      # ~95% of invocations
+paircode "<whatever>" --peer gemini                 # filter roster to one peer
+paircode "<whatever>" --peers gemini,codex          # subset
+```
+
+The LLM reads the quoted prompt and picks the right stages itself. Stages (research / plan / execute / ask-or-review) become invisible templates the LLMs consult, not CLI verbs the user types.
+
+Plus the philosophy, stated verbatim in the session: *"my philosophy is auto fucking install bro!"* — setup work like `init`, `handshake` happens silently inside the main verb. Saved as a feedback memory under `/Users/t/.claude/projects/-Users-t-dev-paircode/memory/feedback_auto_install.md`.
+
+## The architectural fork — Arch A vs Arch B
+
+The real discovery of this session is that today's `drive.py` architecture is **the opposite of what worked in the maintainer's original mlmodel repo.** Comparing the two:
+
+|  | Arch A — current paircode | Arch B — mlmodel pattern |
+|---|---|---|
+| Alpha identity | Fresh `claude -p` subprocess spawned by Python | Interactive Claude session where `/paircode` was typed |
+| Alpha's context | None (headless, no memory, no session) | Full (session + user memory + project state) |
+| Orchestrator | Python `ThreadPoolExecutor` in drive.py | The interactive Claude session itself, via its Bash + Agent tools |
+| Claude peers | Fresh `claude -p` subprocess | In-process Agent tool subagents (background) |
+| Codex/Gemini peers | `cliworker.run()` → shell subprocess | Bash subprocess |
+| Runs after user closes Claude? | Yes (headless loop) | No (dies with session) |
+| Python code surface | Large — drive.py, gates.py, ThreadPoolExecutor | Small — scaffold + template render |
+
+**Evidence for Arch B being what the maintainer originally built:**
+
+- `/Users/t/clients/syra/mlmodel/.claude/commands/peerkickoff.md` — team lead is the interactive Claude, spawns two Agent-tool subagents in parallel with `run_in_background=true`, then synthesizes.
+- `/Users/t/clients/syra/mlmodel/.claude/commands/audit-me.md` — interactive Claude spawns one subagent that shells out to codex CLI for peer review.
+- `/Users/t/clients/syra/mlmodel/.claude/commands/audit-codex.md` — interactive Claude does PART 1 (review) itself with full context, then spawns a subagent to fire codex for self-heal.
+- **Zero Python orchestrator binary in mlmodel.** Slash command markdown + Bash + Agent tool handles everything.
+
+The maintainer confirmed this was his "worked fucking great" baseline. Today's paircode drive.py is a regression introduced during vibe-coding that built a Python thread pool which spawns the very `claude -p` subprocess that strips alpha of its session context.
+
+## Decisions made in this session
+
+**CLI surface (user-facing):**
+- `paircode "<prompt>"` — the one verb.
+- `paircode` bare — prints current state (eats what `status` used to do).
+- `paircode install` / `paircode uninstall` — stay. One-time setup that writes to `~/.claude`, `~/.codex`, `~/.gemini`. Maintainer explicitly said this is fine because users self-selected into it by installing paircode.
+- **Dies as user verbs:** `init`, `handshake`, `status`, `focus`, `stage`, `seal`, `drive`.
+
+**Auto-silent preconditions inside the main verb:**
+- If `.paircode/` missing → `init_paircode()` runs silently.
+- If `peers.yaml` empty / stale → handshake runs silently.
+- Focus creation is procedural (`open_focus()` in state.py), always-new-per-invocation by default, escape hatch `--continue` to reuse the most recent unsealed focus when the previous team lead flaked.
+
+**Semantic decisions vs mechanical decisions:**
+- LLMs decide: is this a new topic? is this round converged? which focus to continue? who gets which stage?
+- Python decides: where files go on disk, how directories are scaffolded, template rendering, roster persistence.
+
+**Sealing + consensus (the maintainer's design):**
+- Team lead (interactive Claude) runs multiple rounds from the one `/paircode` invocation.
+- When the team lead has heard enough, it tells each peer to write their `{peer}-FINAL.md`.
+- Team lead then writes its own `alpha-FINAL.md`.
+- Team lead reads all FINALs and writes a **new artifact: `consensus.md`** — the very last thing before closing out the focus.
+- **Current prompts in drive.py do NOT describe any of this.** The maintainer had believed sealing logic was already in the prompts; verification showed it is not. This is a real prompt authoring task, not a memory of existing work.
+
+**Capability syntax rejected:**
+- Brief proposed `--peer gemini:opine` / `--peer codex:work` for inline capability override.
+- Maintainer explicitly dislikes this. Capability stays in `.paircode/peers.yaml` only; edit the file if you want to change it. No per-invocation override flag.
+
+## Open tensions we are grappling with
+
+1. **Headless execution.** Arch A can run for an hour unattended after the user closes Claude. Arch B dies with the session. mlmodel worked fine without headless, but this is a genuine capability loss. Does it matter for the paircode use cases? Unresolved. Preservation branch exists partly because of this.
+2. **Claude-reviewing-Claude support.** mlmodel used Agent tool subagents for claude-on-claude peer review. paircode's current thesis is cross-vendor adversarial (different engines surface different blind spots). Do we keep Claude-on-Claude as an option or cut it for simplicity? Leaning toward cut, not decided.
+3. **Consensus.md prompt authoring.** The final-round team-lead prompt needs to instruct: seal each peer, write your own FINAL, read all FINALs, write `consensus.md`, report. Not drafted yet.
+4. **Codex + Gemini as team lead.** Slash commands are installed via satellites for all three CLIs. If `/paircode` is invoked inside Codex or Gemini (not Claude), can those hosts run the Arch B orchestration? Codex has subagent primitives; Gemini's are different. Cross-host parity for Arch B is an open question. Without parity, paircode is effectively Claude-first with Codex/Gemini as peers only.
+5. **`cliworker` dependency.** If the slash command does all subprocess work via its host CLI's Bash tool, `cliworker.run()` leaves the runtime path. cliworker still matters for `paircode install` (marketplace add, extensions install via `invoke()`). The LLM-call speed-flag logic currently in cliworker.run becomes dead code from paircode's perspective.
+6. **Testability.** Today's drive.py has unit tests (`tests/test_drive.py`). Arch B moves orchestration into slash command markdown, which is untestable by pytest. Smoke tests would have to shell out through a real LLM CLI — slow, flaky, costly. Mitigation: keep the procedural Python helpers (`init_paircode`, `open_focus`, template render, seal_stage) testable in isolation, and accept that the orchestration loop itself becomes an integration-test concern.
+
+## Why we're preserving now
+
+Arch B is a bet. It matches the maintainer's philosophy, it matches the pattern that worked in mlmodel, it dissolves Gap 1–4 cleanly. But it trades away:
+
+- Headless execution
+- A testable orchestration loop
+- Cross-host parity guarantees (Codex/Gemini may not support the team-lead pattern as cleanly)
+
+If any of those turn out to matter more than they look like they do today, we come back to this branch. The Python-driven orchestrator at v0.10.1 is a working, shipped system with 52 green tests. Killing it without preservation would be a mistake.
+
+## Preservation details
+
+- Branch `path-python-controls-stages` cut from `main` immediately after this diary commits.
+- `main` continues toward the Arch B rewrite.
+- The `drive` command, `run_stage`, `run_stage_cold`, `run_review_round`, `run_alpha_revision`, and the ThreadPoolExecutor orchestration in `drive.py` are expected to be deleted from `main` during the rewrite. They remain intact on the preservation branch.
+- `state.py` (procedural scaffolding) stays on `main` unchanged — Arch B still uses it.
+- `runner.py` / `cliworker` integration: fate undecided. See tension #5.
+
+## Key files as of this diary
+
+| Concern | File | Fate in Arch B |
+|---|---|---|
+| `/paircode` slash command (Claude) | `src/paircode/templates/claude_slash_command.md` | **Rewritten** — becomes the orchestrator |
+| `/paircode` slash command (Codex) | `src/paircode/templates/codex_slash_command.md` | Rewritten; parity with Claude version tbd |
+| `/paircode` slash command (Gemini) | `src/paircode/templates/gemini_slash_command.toml` | Rewritten; parity tbd |
+| Python CLI | `src/paircode/cli.py` | Reduced to `paircode "<prompt>"`, `install`, `uninstall`, bare-state |
+| Drive loop | `src/paircode/drive.py` | **Deleted** on main, preserved on branch |
+| State scaffolding | `src/paircode/state.py` | Kept |
+| Runner | `src/paircode/runner.py` | Undecided |
+| Seal | `src/paircode/seal.py` | Kept as a helper the slash command can call silently |
+
+*End of diary 003. Next session: draft the rewritten slash command template + the trimmed Python CLI.*

{paircode-0.10.1 → paircode-0.11.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.10.1"
+version = "0.11.3"
 description = "Adversarial journey framework — orchestrate multiple LLM peers through research, plan, and execute stages with file-trace peer review."
 readme = "README.md"
 license = { text = "MIT" }

{paircode-0.10.1 → paircode-0.11.3}/src/paircode/__init__.py

@@ -2,4 +2,4 @@
 
 See README.md and diary/001-step-a-architecture.md for the full design.
 """
-__version__ = "0.10.0"
+__version__ = "0.11.2"