PyPI - paircode - Versions diffs - 0.11.1__tar.gz → 0.11.5__tar.gz - Mend

paircode 0.11.1tar.gz → 0.11.5tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

{paircode-0.11.1 → paircode-0.11.5}/.gitignore RENAMED Viewed

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

paircode-0.11.5/PKG-INFO ADDED Viewed

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: paircode
+Version: 0.11.5
+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.3
+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
+    sandbox/
+      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/sandbox/<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.5/README.md ADDED Viewed

@@ -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
+    sandbox/
+      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/sandbox/<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.1 → paircode-0.11.5}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 [project]
 name = "paircode"
-version = "0.11.1"
+version = "0.11.5"
 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" }
@@ -39,7 +39,7 @@ dependencies = [
     "click>=8.1",
     "pyyaml>=6.0",
     "rich>=13.0",
-    "cliworker>=0.8.1",
+    "cliworker>=0.8.3",
 ]
 [project.urls]

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/__init__.py RENAMED Viewed

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

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/cli.py RENAMED Viewed

@@ -243,7 +243,7 @@ def converge(stage: str) -> None:
     Runs on the active focus. Mechanical file-copy only; the slash command
     writes `consensus.md` afterward from the FINAL files.
     """
-    from paircode.seal import seal_stage
+    from paircode.converge import seal_stage
     state = find_paircode()
     if state is None or state.active_focus is None:

paircode-0.11.1/src/paircode/seal.py → paircode-0.11.5/src/paircode/converge.py RENAMED Viewed

@@ -1,8 +1,12 @@
-"""Seal a stage — copy the latest version per peer to {peer}-FINAL.md.
+"""Converge a stage — copy the latest version per peer to {peer}-FINAL.md.
-Sealing is the declarative exit signal for a stage. Once alpha-FINAL.md and
-each peer's *-FINAL.md exist, the stage is considered complete and the next
-stage can consume its outputs.
+Convergence is the declarative exit signal for a stage. Once alpha-FINAL.md
+and each peer's *-FINAL.md exist, the stage is considered complete and the
+next stage can consume its outputs.
+Renamed from `seal.py` in v0.11.1 to match the user-facing CLI verb
+(`paircode converge <stage>`). The public function name stayed `seal_stage`
+because it describes a file-copy primitive, not the user-level action.
 """
 from __future__ import annotations

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/installer.py RENAMED Viewed

@@ -22,12 +22,12 @@ Also cleans up legacy files from pre-v0.10 paircode versions on every install.
 from __future__ import annotations
 from dataclasses import dataclass
-from importlib import resources
 from pathlib import Path
 from cliworker import invoke
 from paircode.detect import detect_all, CliInfo
+from paircode.util import read_template as _read_template
 # Satellite repo coordinates — update here when repos move.
@@ -46,15 +46,6 @@ class InstallResult:
     message: str
-def _read_template(relative_path: str) -> str:
-    """Read a file under `paircode/templates/` by relative path.
-    Host templates live at `<host>/commands/...`, host-agnostic scaffold
-    templates at the root (`FOCUS.md`, `JOURNEY.md`, `peers.yaml`).
-    """
-    return resources.files("paircode.templates").joinpath(relative_path).read_text(encoding="utf-8")
 # ---------------------------------------------------------------------------
 # Per-CLI installers
 # ---------------------------------------------------------------------------

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/runner.py RENAMED Viewed

@@ -107,8 +107,14 @@ def run_peer(
         f"<!-- cli: {cli} -->\n"
         f"<!-- model: {model or '(default)'} -->\n"
         f"<!-- duration_s: {cli_result.duration_s:.1f} -->\n"
-        f"<!-- ok: {cli_result.ok} -->\n\n"
+        f"<!-- ok: {cli_result.ok} -->\n"
     )
+    # Surface the cliworker watchdog's reason on failure so downstream tools
+    # can tell startup-idle hangs apart from hard timeouts apart from real errors.
+    timeout_kind = getattr(cli_result, "timeout_kind", None)
+    if timeout_kind:
+        header += f"<!-- timeout_kind: {timeout_kind} -->\n"
+    header += "\n"
     if cli_result.ok:
         body = cli_result.stdout
     else:

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/state.py RENAMED Viewed

@@ -4,9 +4,9 @@ The .paircode/ layout (from diary/001-step-a-architecture.md):
   .paircode/
     JOURNEY.md              ← fleet log, focus transitions
-    peers.yaml              ← roster
-    peers/
-      peer-a-{cli}/         ← per-peer working dir (+profile.md, +code if full-fork)
+    peers.yaml              ← roster (who's on the team)
+    sandbox/
+      peer-a-{cli}/         ← per-peer persistent sandbox (code/scripts/prototypes)
     focus-01-{slug}/
       FOCUS.md
       research/
@@ -18,12 +18,13 @@ from __future__ import annotations
 import datetime as _dt
 import re
 from dataclasses import dataclass
-from importlib import resources
 from pathlib import Path
 from typing import Iterable
 import yaml
+from paircode.util import read_template as _read_template
 PAIRCODE_DIRNAME = ".paircode"
 PEERS_FILE = "peers.yaml"
@@ -35,15 +36,6 @@ def _now_iso() -> str:
     return _dt.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
-def _read_template(relative_path: str) -> str:
-    """Read a file under `paircode/templates/` by relative path.
-    Examples: `_read_template("FOCUS.md")` or
-    `_read_template("claude/commands/paircode.md")`.
-    """
-    return resources.files("paircode.templates").joinpath(relative_path).read_text(encoding="utf-8")
 def _render(template: str, vars: dict[str, str]) -> str:
     out = template
     for k, v in vars.items():
@@ -61,7 +53,7 @@ class PaircodeState:
     root: Path                       # path to .paircode/ dir itself
     journey_path: Path
     peers_path: Path
-    peers_dir: Path
+    sandbox_dir: Path
     focus_dirs: list[Path]           # sorted by name
     @property
@@ -98,7 +90,7 @@ def load_state(root: Path) -> PaircodeState:
         root=root,
         journey_path=root / JOURNEY_FILE,
         peers_path=root / PEERS_FILE,
-        peers_dir=root / "peers",
+        sandbox_dir=root / "sandbox",
         focus_dirs=focus_dirs,
     )
@@ -117,19 +109,19 @@ def _peer_id(entry) -> str | None:
 def ensure_peer_dirs(state: PaircodeState, proposed: Iterable) -> list[Path]:
-    """Create .paircode/peers/{peer.id}/ for each entry. Idempotent.
+    """Create .paircode/sandbox/{peer.id}/ for each entry. Idempotent.
     Accepts iterables of ProposedPeer dataclasses OR plain dicts (anything
     with an `id` attribute / key). Silently skips entries without a usable id.
-    Returns the list of peer-dir paths that now exist (created or pre-existing).
+    Returns the list of sandbox-dir paths that now exist (created or pre-existing).
     """
-    state.peers_dir.mkdir(exist_ok=True)
+    state.sandbox_dir.mkdir(exist_ok=True)
     created: list[Path] = []
     for entry in proposed:
         pid = _peer_id(entry)
         if not pid:
             continue
-        peer_dir = state.peers_dir / pid
+        peer_dir = state.sandbox_dir / pid
         peer_dir.mkdir(exist_ok=True)
         created.append(peer_dir)
     return created
@@ -138,7 +130,7 @@ def ensure_peer_dirs(state: PaircodeState, proposed: Iterable) -> list[Path]:
 def init_paircode(project_root: Path | None = None, force: bool = False) -> PaircodeState:
     """Bootstrap .paircode/ in `project_root` (or cwd). Returns the new state.
-    Also pre-creates a subdir per auto-detected peer under .paircode/peers/.
+    Also pre-creates a subdir per auto-detected peer under .paircode/sandbox/.
     If no peers are detected, the parent dir exists but stays empty.
     """
     if project_root is None:
@@ -150,7 +142,7 @@ def init_paircode(project_root: Path | None = None, force: bool = False) -> Pair
             f"{root} already exists. Use --force to overwrite, or `paircode status` to inspect."
         )
     root.mkdir(parents=True, exist_ok=True)
-    (root / "peers").mkdir(exist_ok=True)
+    (root / "sandbox").mkdir(exist_ok=True)
     journey = _render(
         _read_template("JOURNEY.md"),
@@ -170,8 +162,8 @@ def init_paircode(project_root: Path | None = None, force: bool = False) -> Pair
         ensure_peer_dirs(state, propose_roster())
     except Exception:
-        # Scaffolding peers is best-effort; a detect failure shouldn't
-        # block bootstrap. The peers/ parent dir is already there.
+        # Scaffolding sandboxes is best-effort; a detect failure shouldn't
+        # block bootstrap. The sandbox/ parent dir is already there.
         pass
     return state

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/templates/claude/commands/paircode.md RENAMED Viewed

@@ -18,12 +18,11 @@ Inside every `$FOCUS/{stage}/`:
 `N` in `vN` is the current round number, starting at 1. Only write v1 in the first round; bump to v2, v3, … if you do review rounds.
-**Code vs. reports.** Every file inside `$FOCUS/{stage}/` is a **markdown report** (opinion, critique, plan, or summary of work). Actual code lives elsewhere:
+**Reports vs. code — the three rules.** Files inside `$FOCUS/{stage}/` are always **markdown reports** (opinions, plans, critiques, summaries). Actual code lives elsewhere, and sandboxes are **always available, never required**:
-- **Peers** code in their sandboxed workspace at `.paircode/peers/{peer-id}/` — persistent across focuses, each peer builds there.
-- **Alpha** codes directly in the project root (the user's repo) — alpha IS the project, no sandbox.
-The `$FOCUS/execute/*-v1.md` files describe what was done; the `$FOCUS/execute/` dir is never where code is written.
+1. **Always available.** Peers can use their persistent sandbox at `.paircode/sandbox/{peer-id}/` at **any stage** — not just execute. Verifying a bug in `ask`, grounding research in real data, prototyping a tricky plan section — all fine. Alpha (this Claude session) works directly in the project root (the user's repo). **Code only when it makes your answer materially better** — a 5-line verification script is cheap insurance; a 500-line prototype during an `ask` is over-engineering.
+2. **Separation.** Markdown is the deliverable; the sandbox is the laboratory. Scripts, prototypes, dumps, evidence files live in `.paircode/sandbox/{peer-id}/`. The `$FOCUS/{stage}/*-v1.md` file summarizes what you did + what it proved. The `$FOCUS/` tree is never where code is written.
+3. **Isolation.** Peers never touch files outside their own sandbox. Alpha never touches other peers' sandboxes. The project root is alpha's.
 ## Step 1 — Bootstrap
@@ -44,34 +43,41 @@ PEERS=$(paircode roster --alpha claude <user's --peer/--peers flags if any>)
 `paircode roster` always returns a usable list. Trust it.
-## Step 2 — Pick the stage
+## Step 2 — Pick the flow (not just a stage)
+Read the user's quoted prompt and pick the **whole flow** you're committing to. Store it as `{flow}`. Each flow is an ordered list of stages; you run them in order.
-Read the user's quoted prompt and decide which stage best fits. Store your pick as `{stage}`:
+| Flow | Deliverable | Trigger phrases |
+|---|---|---|
+| `ask` | Opinion on existing work | "what do you think", "review X", "critique", "second opinion" |
+| `research` | Investigation report | "figure out", "explore", "find the right", "how should we" |
+| `research → plan` | Concrete plan | "plan the X", "design the Y", "lay out the approach" |
+| `research → plan → execute` | **Shipped code / action done** | "build", "fix", "implement", "write code for", "ship", "do", and most imperative tasks |
+| `execute` | Just do it (plan already exists) | "execute the plan at focus-NN", "run the migration from focus-05" |
-- **research** — explore new ground, figure something out. ("build a KISS PHQ-9 depression engine", "find the right TTS library", "how should we approach X")
-- **plan** — produce a concrete implementation plan, usually building on prior research. ("plan the refactor based on focus-02's research")
-- **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>")
+**Default when ambiguous: `research → plan → execute`.** It's safer to over-deliver than to stop at research for a prompt that meant "build this." The only prompts that aren't build-shaped are explicit opinion/review requests.
-When unsure, pick `research` — it's the safe cold-investigation default. All four stage subdirs already exist under `$FOCUS` — no mkdir needed.
+Write `{flow}` into `$FOCUS/FOCUS.md` (append a line like `flow: research → plan → execute`) so later steps can see your commitment.
+The stage for **this iteration** is the first stage in `{flow}`. Store that as `{stage}`. All four stage subdirs already exist under `$FOCUS`.
 ## Step 3 — Fire peers in parallel
 For each peer id in `$PEERS`, spawn one subagent using the **Agent tool** with `subagent_type=general-purpose` and `run_in_background=true`. Send them all in a single message so they run truly concurrently.
-Construct a stage-appropriate peer prompt. The general shape for each `{stage}`:
+Construct a stage-appropriate peer prompt. Every prompt reminds the peer its sandbox is available; the deliverable is always the markdown report. General shape for each `{stage}`:
-- **research**: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific **cold take** on the prompt. Clean markdown, no preamble."
-- **plan**: "Read $FOCUS/FOCUS.md and any `../research/*-FINAL.md` if present. Write a **concrete step-by-step plan** for this prompt: goal, scope, numbered steps, risks, success criteria. Be KISS. Clean markdown."
-- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Execute the plan IN YOUR PEER WORKSPACE at `.paircode/peers/{peer-id}/`** — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the *report*; the *code* lives in your peer workspace."
-- **ask**: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your **honest critique** of that artifact — what's wrong, what's right, severity-ranked findings with file:line citations where possible. Clean markdown, no preamble."
+- **research**: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific **cold take** on the prompt. Use your sandbox at `.paircode/sandbox/{peer-id}/` to write quick scripts grounding your claims in real data (not README marketing) if it would sharpen your take. Clean markdown report, no preamble."
+- **plan**: "Read $FOCUS/FOCUS.md and any `../research/*-FINAL.md` if present. Write a **concrete step-by-step plan**: goal, scope, numbered steps, risks, success criteria. Be KISS. Use your sandbox at `.paircode/sandbox/{peer-id}/` to prototype tricky sections and verify feasibility. Clean markdown."
+- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Carry out the plan and produce working artifacts.** For code-shipping plans: work in your peer workspace at `.paircode/sandbox/{peer-id}/`, write code there, run commands there, run tests there. For action plans (run a migration, make an API call, file a ticket): do the action and report results. Do NOT touch files outside your workspace. Your output is a markdown report summarizing what you built/ran, files touched, verification status, what's open."
+- **ask**: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your **honest critique** — severity-ranked findings with file:line citations where possible. If reproducing a claim by running a quick script in your sandbox (`.paircode/sandbox/{peer-id}/`) would make your critique sharper, do it. Your output is still a critique report, not a prototype. Clean markdown, no preamble."
 Each subagent's prompt:
 ```
 You are the {peer-id} peer in a paircode {stage} cycle.
-Your persistent workspace: .paircode/peers/{peer-id}/
+Your persistent workspace: .paircode/sandbox/{peer-id}/
 The focus we're on: $FOCUS
 The prompt from the user: "<the quoted prompt>"
 The stage: {stage}
@@ -93,7 +99,7 @@ Do not try to "fix" the peer's output. We want the raw file-trace on disk.
 While the peer subagents run, you (the team lead) write your own v1 at `$FOCUS/{stage}/alpha-v1.md`. Use the Write tool. Same stage-appropriate rules as above — and your advantage over the peers is you have this session's full context (memory, recent work, the maintainer's voice).
-**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/peers/{peer-id}/`). You, alpha, code directly in the project root — you're working on the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
+**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/sandbox/{peer-id}/`). You, alpha, code directly in the project root — you're working on the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
 ## Step 5 — Wait and read
@@ -136,20 +142,13 @@ Then read every `*-FINAL.md` and write `$FOCUS/{stage}/consensus.md` via the Wri
 Adversarial-but-honest. No pile-on. No rubber-stamping either.
-## Step 8 — Next stage or done?
-After a stage converges, decide whether to transition to another stage or wrap up:
+## Step 8 — Advance the flow (mechanical)
-- **Done** — the user's prompt is now served. Go to Step 9.
-- **Next stage** — move to whichever stage follows naturally from what you just finished. Pick the new `{stage}`, then jump back to **Step 3** (Fire peers). Skip Step 1 — focus is still open. Skip Step 2 — you already picked. The previous stage's `*-FINAL.md` files are input for the next stage's peer prompts.
+Look at the `{flow}` you committed to in Step 2. Set `{stage}` to the **next** stage in that flow and jump back to **Step 3** (Fire peers). Skip Step 1 (focus is still open) and Step 2 (flow already chosen). The previous stage's `*-FINAL.md` files are input for the next stage's peer prompts.
-Typical chains:
-- `ask → done`
-- `research → done` (if research itself was the deliverable)
-- `research → plan → execute → done` (most common full-build chain)
-- `research → plan → done` (when the plan is the deliverable and the maintainer will execute manually)
+**If the last stage just finished, go to Step 9.**
-Back-to-Step-3 recursion is how paircode moves through multiple stages in one invocation. No round cap, no stage cap — team lead's call when to stop.
+This step is mechanical. Do not re-deliberate. Do not ask the user whether to continue. The user's prompt in `$ARGUMENTS` was implicit go-ahead for the whole flow; stopping early is an exception that only happens if **something blocked you** (a peer hard-errored and the blocker is critical, the consensus explicitly said "do not proceed", or the user interrupted). If you do stop early, say so explicitly in the final report with the reason.
 ## Step 9 — Final report
@@ -166,4 +165,6 @@ Keep it under 200 words. Brief, honest, actionable.
 - **Never skip Step 1.** The focus and roster helpers do the work Python is better at.
 - **Never invent peer commands.** Always route through `paircode invoke <id> "..." --out <path>` — that's how cliworker's speed flags, MCP strip, and output tracing work.
 - **Never pass the interactive Claude session as a peer by mistake.** `paircode roster --alpha claude` handles that for you.
+- **Peer sandboxes are always available, never required.** Use them when it materially sharpens your answer, not by default.
+- **The user's prompt is implicit go-ahead for the whole `{flow}`.** Do not pause for permission between stages. If you must stop early, say so explicitly in the final report with the reason.
 - **No AI attribution** in any artifact you write (consensus.md, alpha-*.md). See the maintainer's CLAUDE.md.

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/templates/codex/commands/paircode.md RENAMED Viewed

@@ -21,7 +21,7 @@ Inside every `$FOCUS/{stage}/`:
 **Code vs. reports.** Every file inside `$FOCUS/{stage}/` is a **markdown report** (opinion, critique, plan, or summary of work). Actual code lives elsewhere:
-- **Peers** code in their sandboxed workspace at `.paircode/peers/{peer-id}/` — persistent across focuses.
+- **Peers** code in their sandboxed workspace at `.paircode/sandbox/{peer-id}/` — persistent across focuses.
 - **Alpha** codes directly in the project root (the user's repo) — alpha IS the project, no sandbox.
 The `$FOCUS/execute/*-v1.md` files describe what was done; the `$FOCUS/execute/` dir is never where code is written.
@@ -77,14 +77,14 @@ Construct one per stage — keep it reusable across peers:
 - **research**: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific **cold take** on the prompt. Clean markdown, no preamble."
 - **plan**: "Read $FOCUS/FOCUS.md and any `../research/*-FINAL.md` if present. Write a **concrete step-by-step plan** for this prompt: goal, scope, numbered steps, risks, success criteria. Be KISS. Clean markdown."
-- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Execute the plan IN YOUR PEER WORKSPACE at `.paircode/peers/{peer-id}/`** — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the *report*; the *code* lives in your peer workspace."
+- **execute**: "Read $FOCUS/FOCUS.md and the plan at `$FOCUS/plan/*-FINAL.md`. **Execute the plan IN YOUR PEER WORKSPACE at `.paircode/sandbox/{peer-id}/`** — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the *report*; the *code* lives in your peer workspace."
 - **ask**: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your **honest critique** — severity-ranked findings with file:line citations where possible. Clean markdown, no preamble."
 ## Step 4 — Team lead's own take
 After the serial peer loop completes (or right after you kick it off if your tools allow), write your own v1 at `$FOCUS/{stage}/alpha-v1.md` using the shell tool (e.g. `cat > ... <<'EOF'`). Same stage-appropriate rules as above — your advantage over the peers is session context (memory, recent work, the maintainer's voice).
-**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/peers/{peer-id}/`). You, alpha, code directly in the project root — the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
+**Execute-stage asymmetry:** when `{stage}` is `execute`, peers code inside their sandboxed peer workspaces (`.paircode/sandbox/{peer-id}/`). You, alpha, code directly in the project root — the user's actual repo. Your `alpha-v1.md` is a report summarizing what landed in the real project files; the code itself lives in the repo, not in `$FOCUS/execute/`.
 ## Step 5 — Wait and read

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/templates/gemini/commands/paircode.toml RENAMED Viewed

@@ -21,7 +21,7 @@ N in vN is the current round number, starting at 1. Only write v1 in the first r
 **Code vs. reports.** Every file inside $FOCUS/{stage}/ is a markdown report (opinion, critique, plan, or summary of work). Actual code lives elsewhere:
-- Peers code in their sandboxed workspace at .paircode/peers/{peer-id}/ — persistent across focuses.
+- Peers code in their sandboxed workspace at .paircode/sandbox/{peer-id}/ — persistent across focuses.
 - Alpha codes directly in the project root (the user's repo) — alpha IS the project, no sandbox.
 The $FOCUS/execute/*-v1.md files describe what was done; the $FOCUS/execute/ dir is never where code is written.
@@ -71,14 +71,14 @@ Construct one per stage — keep it reusable across peers:
 - research: "Read $FOCUS/FOCUS.md. Give an honest, skeptical, specific cold take on the prompt. Clean markdown, no preamble."
 - plan: "Read $FOCUS/FOCUS.md and any ../research/*-FINAL.md if present. Write a concrete step-by-step plan for this prompt: goal, scope, numbered steps, risks, success criteria. Be KISS. Clean markdown."
-- execute: "Read $FOCUS/FOCUS.md and the plan at $FOCUS/plan/*-FINAL.md. Execute the plan IN YOUR PEER WORKSPACE at .paircode/peers/{peer-id}/ — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the report; the code lives in your peer workspace."
+- execute: "Read $FOCUS/FOCUS.md and the plan at $FOCUS/plan/*-FINAL.md. Execute the plan IN YOUR PEER WORKSPACE at .paircode/sandbox/{peer-id}/ — that is your persistent sandbox. Write code there, run commands there. Do NOT touch files outside that workspace. Then write a markdown report to your output file summarizing: what you built, files touched (paths relative to your peer workspace), tests/verification status, what's open. The output file holds the report; the code lives in your peer workspace."
 - ask: "Read $FOCUS/FOCUS.md and the artifact it points to. Give your honest critique — severity-ranked findings with file:line citations where possible. Clean markdown, no preamble."
 ## Step 4 — Team lead's own take
 After the serial peer loop completes, write your own v1 to $FOCUS/{stage}/alpha-v1.md via run_shell_command (cat > ... <<'EOF' or equivalent). Same stage-appropriate rules — your advantage over the peers is session context.
-**Execute-stage asymmetry:** when {stage} is execute, peers code inside their sandboxed peer workspaces (.paircode/peers/{peer-id}/). You, alpha, code directly in the project root — the user's actual repo. Your alpha-v1.md is a report summarizing what landed in the real project files; the code itself lives in the repo, not in $FOCUS/execute/.
+**Execute-stage asymmetry:** when {stage} is execute, peers code inside their sandboxed peer workspaces (.paircode/sandbox/{peer-id}/). You, alpha, code directly in the project root — the user's actual repo. Your alpha-v1.md is a report summarizing what landed in the real project files; the code itself lives in the repo, not in $FOCUS/execute/.
 ## Step 5 — Wait and read

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/templates/peers.yaml RENAMED Viewed

@@ -5,7 +5,7 @@
 # project root.
 #
 # Every other LLM that participates is a peer. Each peer gets an entry
-# below AND a folder at .paircode/peers/peer-N-{cli}/.
+# below AND a folder at .paircode/sandbox/peer-N-{cli}/.
 #
 # Fields:
 #   id              — peer-a, peer-b, peer-c, ... (unique, immutable)

paircode-0.11.5/src/paircode/util.py ADDED Viewed

@@ -0,0 +1,18 @@
+"""Small shared helpers for paircode internals."""
+from __future__ import annotations
+from importlib import resources
+def read_template(relative_path: str) -> str:
+    """Read a file under `paircode/templates/` by relative path.
+    Examples:
+        read_template("FOCUS.md")
+        read_template("claude/commands/paircode.md")
+    """
+    return (
+        resources.files("paircode.templates")
+        .joinpath(relative_path)
+        .read_text(encoding="utf-8")
+    )

paircode-0.11.1/tests/test_seal.py → paircode-0.11.5/tests/test_converge.py RENAMED Viewed

@@ -1,9 +1,9 @@
-"""Tests for stage sealing."""
+"""Tests for stage convergence — copying latest vN to *-FINAL.md."""
 from __future__ import annotations
 from pathlib import Path
-from paircode.seal import discover_latest_versions, seal_stage
+from paircode.converge import discover_latest_versions, seal_stage
 def test_discover_latest_versions_picks_highest_per_peer(tmp_path: Path):

{paircode-0.11.1 → paircode-0.11.5}/tests/test_state.py RENAMED Viewed

@@ -22,13 +22,13 @@ def test_init_creates_paircode_structure(tmp_path: Path):
     assert state.root.is_dir()
     assert state.journey_path.exists()
     assert state.peers_path.exists()
-    assert state.peers_dir.is_dir()
+    assert state.sandbox_dir.is_dir()
     assert state.focus_count == 0
     assert state.active_focus is None
 def test_init_scaffolds_peer_dirs_from_detected_clis(tmp_path: Path, monkeypatch):
-    """init_paircode should create .paircode/peers/{id}/ for each detected peer."""
+    """init_paircode should create .paircode/sandbox/{id}/ for each detected peer."""
     fake_proposed = [
         ProposedPeer(id="peer-a-codex", cli="codex", priority="high", notes=""),
         ProposedPeer(id="peer-b-gemini", cli="gemini", priority="low", notes=""),
@@ -36,15 +36,15 @@ def test_init_scaffolds_peer_dirs_from_detected_clis(tmp_path: Path, monkeypatch
     monkeypatch.setattr("paircode.handshake.propose_roster", lambda: fake_proposed)
     state = init_paircode(tmp_path)
-    assert (state.peers_dir / "peer-a-codex").is_dir()
-    assert (state.peers_dir / "peer-b-gemini").is_dir()
+    assert (state.sandbox_dir / "peer-a-codex").is_dir()
+    assert (state.sandbox_dir / "peer-b-gemini").is_dir()
-def test_init_with_no_detected_peers_leaves_peers_dir_empty(tmp_path: Path, monkeypatch):
+def test_init_with_no_detected_peers_leaves_sandbox_dir_empty(tmp_path: Path, monkeypatch):
     monkeypatch.setattr("paircode.handshake.propose_roster", lambda: [])
     state = init_paircode(tmp_path)
-    assert state.peers_dir.is_dir()
-    assert list(state.peers_dir.iterdir()) == []
+    assert state.sandbox_dir.is_dir()
+    assert list(state.sandbox_dir.iterdir()) == []
 def test_ensure_peer_dirs_accepts_dicts_and_is_idempotent(tmp_path: Path, monkeypatch):
@@ -54,7 +54,7 @@ def test_ensure_peer_dirs_accepts_dicts_and_is_idempotent(tmp_path: Path, monkey
     dicts = [{"id": "peer-a-codex", "cli": "codex"}, {"id": "peer-c-ollama"}]
     created = ensure_peer_dirs(state, dicts)
     assert len(created) == 2
-    assert (state.peers_dir / "peer-a-codex").is_dir()
+    assert (state.sandbox_dir / "peer-a-codex").is_dir()
     # Running again is a no-op (idempotent)
     created_again = ensure_peer_dirs(state, dicts)
     assert len(created_again) == 2

paircode-0.11.1/PKG-INFO DELETED Viewed

@@ -1,160 +0,0 @@
-Metadata-Version: 2.4
-Name: paircode
-Version: 0.11.1
-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) + any number of peer LLMs (Codex, Gemini, Ollama, …) running independent research, plans, and code, 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 full design rationale.
-## Install
-```bash
-pipx install paircode       # or: pip install --user paircode
-paircode install            # registers /paircode in every detected LLM CLI
-```
-After install, `/paircode` is available in all three:
-| CLI | File installed |
-|---|---|
-| Claude Code | `~/.claude/commands/paircode.md` |
-| Codex CLI | `~/.codex/prompts/paircode.md` |
-| Gemini CLI | `~/.gemini/commands/paircode.toml` |
-Open any of them and type `/paircode`. In Gemini, you may need `/commands reload` the first time.
-As of v0.8.0, paircode delegates all CLI invocation to [`cliworker`](https://pypi.org/project/cliworker/) — one place to own
-the speed flags, MCP strip tricks, skip-cache, and subscription-first fallback
-logic. paircode adds the peer-review orchestration on top (file-traces, stages,
-gates, journey).
-## Use it — three entry points
-### 1. From Claude Code (or any supported LLM) as a slash command
-Inside a Claude Code session:
-```
-/paircode drive "build a KISS PHQ-9 depression risk engine"
-```
-Claude relays that to the CLI. paircode opens a focus, runs research → plan → execute with peer-reviewed rounds, writes everything to `.paircode/` as Markdown.
-### 2. From the shell directly
-```bash
-paircode init                                   # bootstrap .paircode/ in cwd
-paircode handshake --write                      # detect CLIs + write peer roster
-paircode drive "refactor the auth middleware"   # full loop
-paircode status                                 # see where you are
-```
-### 3. Piece by piece
-```bash
-paircode focus "try GitHub Actions migration"
-paircode stage research --rounds 2              # cold v1 + one review/revise round
-paircode seal research                          # mark research FINAL
-paircode stage plan --rounds 3
-paircode seal plan
-paircode stage execute
-paircode seal execute
-```
-## What ends up on disk
-```
-your-project/
-  .paircode/
-    JOURNEY.md                    # fleet log (auto-updated)
-    peers.yaml                    # who's on the team
-    peers/
-      peer-a-codex/               # peer's profile (and code if full-fork mode)
-    focus-01-<slug>/
-      FOCUS.md                    # this focus's goal, roster override, gate config
-      research/
-        alpha-v1.md ... alpha-vN.md
-        peer-a-codex-v1.md ...
-        reviews/round-01-peer-a-codex-critiques-alpha.md
-        alpha-FINAL.md            # sealed exit artifact
-        peer-a-codex-FINAL.md
-      plan/
-        (same shape)
-      execute/
-        (same shape)
-    focus-02-<slug>/
-      ...
-```
-Every LLM's every thought lands as a Markdown file. That's how heterogeneous LLM tools communicate reliably across vendors, sessions, and days.
-## Three peer modes
-| Mode | What the peer does | When to use |
-|---|---|---|
-| **full-fork** | Writes its own cold codebase + markdown artifacts | Silent-agreement hunting, safety-critical code |
-| **pair-code** | Contributes directly to alpha's codebase via patches + reviews | Feature work, regular dev |
-| **opinion-only** | Reads alpha's work, writes reviews, never touches code | Budget peers, quick sanity checks |
-Configured per peer in `.paircode/peers.yaml`.
-## Model compatibility
-| CLI | Slash command | Subprocess driver | Status |
-|---|---|---|---|
-| Claude Code (`claude`) | ✓ `/paircode` via `~/.claude/commands/paircode.md` | ✓ `claude -p <prompt>` | stable |
-| Codex (`codex`) | ✓ context rule via `~/.codex/rules/paircode.rules` | ✓ `codex exec <prompt>` | stable |
-| Gemini CLI (`gemini`) | ✓ reference file at `~/.gemini/paircode.md` | ✓ `gemini -p <prompt>` | stable |
-| Ollama (`ollama`) | — (local models, no slash-cmd primitive) | ✓ `ollama run <model> <prompt>` | stable |
-| Aider / others | — | best-effort, PRs welcome | planned |
-## Commands
-```
-paircode --help           full command list
-paircode install          register /paircode in all detected LLM CLIs
-paircode uninstall        remove /paircode from LLM CLIs (idempotent)
-paircode handshake        detect CLIs, propose peer roster
-paircode handshake --write save roster to .paircode/peers.yaml
-paircode init             bootstrap .paircode/ in cwd
-paircode status           summarize current state
-paircode focus <name>     open a new focus
-paircode focus            list existing focuses
-paircode stage <name>     run one stage N rounds on active focus
-paircode seal <stage>     seal stage — copy each peer's latest vN to {peer}-FINAL.md
-paircode drive <topic>    full loop: research → plan → execute
-```
-## Why this exists
-See [`diary/001-step-a-architecture.md`](diary/001-step-a-architecture.md) for the full backstory. The short version: running two LLMs adversarially surfaces silent-agreement bug classes that neither engine alone can catch, because cross-engine agreement is not the same as correctness when both share the same blind spot.
-## License
-MIT. See [LICENSE](LICENSE).

paircode-0.11.1/README.md DELETED Viewed

@@ -1,132 +0,0 @@
-# paircode
-**Multi-LLM peer review for your code, with file-traces on disk.** One primary LLM (alpha) + any number of peer LLMs (Codex, Gemini, Ollama, …) running independent research, plans, and code, 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 full design rationale.
-## Install
-```bash
-pipx install paircode       # or: pip install --user paircode
-paircode install            # registers /paircode in every detected LLM CLI
-```
-After install, `/paircode` is available in all three:
-| CLI | File installed |
-|---|---|
-| Claude Code | `~/.claude/commands/paircode.md` |
-| Codex CLI | `~/.codex/prompts/paircode.md` |
-| Gemini CLI | `~/.gemini/commands/paircode.toml` |
-Open any of them and type `/paircode`. In Gemini, you may need `/commands reload` the first time.
-As of v0.8.0, paircode delegates all CLI invocation to [`cliworker`](https://pypi.org/project/cliworker/) — one place to own
-the speed flags, MCP strip tricks, skip-cache, and subscription-first fallback
-logic. paircode adds the peer-review orchestration on top (file-traces, stages,
-gates, journey).
-## Use it — three entry points
-### 1. From Claude Code (or any supported LLM) as a slash command
-Inside a Claude Code session:
-```
-/paircode drive "build a KISS PHQ-9 depression risk engine"
-```
-Claude relays that to the CLI. paircode opens a focus, runs research → plan → execute with peer-reviewed rounds, writes everything to `.paircode/` as Markdown.
-### 2. From the shell directly
-```bash
-paircode init                                   # bootstrap .paircode/ in cwd
-paircode handshake --write                      # detect CLIs + write peer roster
-paircode drive "refactor the auth middleware"   # full loop
-paircode status                                 # see where you are
-```
-### 3. Piece by piece
-```bash
-paircode focus "try GitHub Actions migration"
-paircode stage research --rounds 2              # cold v1 + one review/revise round
-paircode seal research                          # mark research FINAL
-paircode stage plan --rounds 3
-paircode seal plan
-paircode stage execute
-paircode seal execute
-```
-## What ends up on disk
-```
-your-project/
-  .paircode/
-    JOURNEY.md                    # fleet log (auto-updated)
-    peers.yaml                    # who's on the team
-    peers/
-      peer-a-codex/               # peer's profile (and code if full-fork mode)
-    focus-01-<slug>/
-      FOCUS.md                    # this focus's goal, roster override, gate config
-      research/
-        alpha-v1.md ... alpha-vN.md
-        peer-a-codex-v1.md ...
-        reviews/round-01-peer-a-codex-critiques-alpha.md
-        alpha-FINAL.md            # sealed exit artifact
-        peer-a-codex-FINAL.md
-      plan/
-        (same shape)
-      execute/
-        (same shape)
-    focus-02-<slug>/
-      ...
-```
-Every LLM's every thought lands as a Markdown file. That's how heterogeneous LLM tools communicate reliably across vendors, sessions, and days.
-## Three peer modes
-| Mode | What the peer does | When to use |
-|---|---|---|
-| **full-fork** | Writes its own cold codebase + markdown artifacts | Silent-agreement hunting, safety-critical code |
-| **pair-code** | Contributes directly to alpha's codebase via patches + reviews | Feature work, regular dev |
-| **opinion-only** | Reads alpha's work, writes reviews, never touches code | Budget peers, quick sanity checks |
-Configured per peer in `.paircode/peers.yaml`.
-## Model compatibility
-| CLI | Slash command | Subprocess driver | Status |
-|---|---|---|---|
-| Claude Code (`claude`) | ✓ `/paircode` via `~/.claude/commands/paircode.md` | ✓ `claude -p <prompt>` | stable |
-| Codex (`codex`) | ✓ context rule via `~/.codex/rules/paircode.rules` | ✓ `codex exec <prompt>` | stable |
-| Gemini CLI (`gemini`) | ✓ reference file at `~/.gemini/paircode.md` | ✓ `gemini -p <prompt>` | stable |
-| Ollama (`ollama`) | — (local models, no slash-cmd primitive) | ✓ `ollama run <model> <prompt>` | stable |
-| Aider / others | — | best-effort, PRs welcome | planned |
-## Commands
-```
-paircode --help           full command list
-paircode install          register /paircode in all detected LLM CLIs
-paircode uninstall        remove /paircode from LLM CLIs (idempotent)
-paircode handshake        detect CLIs, propose peer roster
-paircode handshake --write save roster to .paircode/peers.yaml
-paircode init             bootstrap .paircode/ in cwd
-paircode status           summarize current state
-paircode focus <name>     open a new focus
-paircode focus            list existing focuses
-paircode stage <name>     run one stage N rounds on active focus
-paircode seal <stage>     seal stage — copy each peer's latest vN to {peer}-FINAL.md
-paircode drive <topic>    full loop: research → plan → execute
-```
-## Why this exists
-See [`diary/001-step-a-architecture.md`](diary/001-step-a-architecture.md) for the full backstory. The short version: running two LLMs adversarially surfaces silent-agreement bug classes that neither engine alone can catch, because cross-engine agreement is not the same as correctness when both share the same blind spot.
-## License
-MIT. See [LICENSE](LICENSE).

paircode-0.11.1/src/paircode/journey.py DELETED Viewed

@@ -1,63 +0,0 @@
-"""Update JOURNEY.md as focuses open/close."""
-from __future__ import annotations
-import datetime as _dt
-import re
-from pathlib import Path
-from paircode.state import PaircodeState
-_HISTORY_HEADER_RE = re.compile(r"^## History\s*$", re.MULTILINE)
-_HISTORY_TABLE_RE = re.compile(
-    r"\| # \| Focus \| Opened \| Closed \| Iterations \| Result \|\n\|[-|\s]+\|\n"
-)
-_ACTIVE_FOCUS_RE = re.compile(
-    r"## Active focus\s*\n\n(.+?)\n\n##", re.DOTALL
-)
-def _now() -> str:
-    return _dt.datetime.now().strftime("%Y-%m-%d %H:%M")
-def note_focus_opened(state: PaircodeState, focus_name: str) -> None:
-    """Update JOURNEY.md: set active focus, append history row."""
-    j = state.journey_path
-    if not j.exists():
-        return
-    text = j.read_text(encoding="utf-8")
-    # Replace the "Active focus" section
-    new_active = f"## Active focus\n\n**{focus_name}** — opened {_now()}\n\n##"
-    text = _ACTIVE_FOCUS_RE.sub(new_active, text, count=1)
-    # Append to history table
-    history_match = _HISTORY_TABLE_RE.search(text)
-    if history_match:
-        # Count existing rows in history table
-        rest = text[history_match.end():]
-        existing_rows = rest.split("\n\n")[0]
-        row_count = len([r for r in existing_rows.split("\n") if r.startswith("|")])
-        new_row = f"| {row_count + 1} | {focus_name} | {_now()} | — | 0 | — |\n"
-        text = text[:history_match.end()] + new_row + text[history_match.end():]
-    j.write_text(text, encoding="utf-8")
-def note_focus_closed(state: PaircodeState, focus_name: str, iterations: int, result: str) -> None:
-    """Update JOURNEY.md: mark the focus row as closed with iteration count + result."""
-    j = state.journey_path
-    if not j.exists():
-        return
-    text = j.read_text(encoding="utf-8")
-    # Find row for this focus and update its Closed/Iterations/Result columns
-    pattern = re.compile(
-        rf"(\| \d+ \| {re.escape(focus_name)} \| [^|]+\| )—( \| )0( \| )—( \|)"
-    )
-    text = pattern.sub(
-        rf"\g<1>{_now()}\g<2>{iterations}\g<3>{result}\g<4>",
-        text,
-        count=1,
-    )
-    j.write_text(text, encoding="utf-8")

{paircode-0.11.1 → paircode-0.11.5}/LICENSE RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/diary/001-step-a-architecture.md RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/diary/002-v0.10-release-pipeline.md RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/diary/003-arch-b-pivot-grappling.md RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/__main__.py RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/detect.py RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/handshake.py RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/templates/FOCUS.md RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/src/paircode/templates/JOURNEY.md RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/tests/__init__.py RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/tests/test_cli_smoke.py RENAMED Viewed

File without changes

{paircode-0.11.1 → paircode-0.11.5}/tests/test_smoke.py RENAMED Viewed

File without changes

paircode 0.11.1__tar.gz → 0.11.5__tar.gz

paircode 0.11.1tar.gz → 0.11.5tar.gz