paircode 0.13.1__tar.gz → 0.14.0__tar.gz

{paircode-0.13.1 → paircode-0.14.0}/.gitignore

@@ -38,3 +38,7 @@ dist/
 
 # paircode runtime state (focuses, peer workspaces, etc.)
 .paircode/
+.peerlab/
+
+# local agent state (Claude Code settings + lock files)
+.claude/

{paircode-0.13.1 → paircode-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.13.1
+Version: 0.14.0
 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
@@ -21,7 +21,7 @@ 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: cliworker>=0.8.5
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rich>=13.0
 Description-Content-Type: text/markdown

paircode-0.14.0/diary/004-gemini-silent-flash-downgrade.md

@@ -0,0 +1,44 @@
+# Diary 004 — The silent free-flash downgrade: an unpinned peer rubber-stamped a consensus
+
+**Stardate:** 2026-06-17
+**Verified state:** `main`, 81 tests passing. Changes this entry: `handshake.py` (add `ProposedPeer.model`, correct the stale gemini note), `templates/peers.yaml` (model-field warning), `tests/test_handshake.py` (new).
+**TL;DR:** paircode *already* supports per-peer model pinning end-to-end. The bug was that pinning is optional and invisible, and a misconfigured CLI fails **silently** — so a `peer-b-gemini` ran `gemini-2.0-flash-001` for an entire plan consensus while masquerading as a real fork peer.
+
+---
+
+## What triggered this
+
+During an awali working session, `/paircode` was used to review an implementation plan. The Gemini peer "converged" enthusiastically with alpha — suspiciously agreeable. The maintainer's instinct: *"I don't think it's running Gemini Pro... I needed the best model possible instead of small models that just agree with you."*
+
+He was right. Investigation found the peer was running **`gemini-2.0-flash-001`** — the free-tier default — not a Pro model. Its "agreement" was flash-tier noise that polluted the consensus. The only load-bearing peer that session was Codex.
+
+## Why it happened — four silent failures stacked
+
+1. **gemini-cli auth was `oauth-personal`.** That ignores any API key entirely and uses the free Google login → flash. The paid key in the env was never consulted.
+2. **The account was free tier.** `gemini-2.5-pro` returned `limit: 0` — free tier grants *zero* Pro requests, not "rate-limited," literally none. (Fixed by the maintainer adding $25 credit → tier-1 paid.)
+3. **No model was pinned.** paircode passes no `-m` unless a peer has a `model:` field; the awali roster had none, so the CLI default (flash) won.
+4. **Nothing surfaced any of it.** The file-trace header read `<!-- model: (default) -->` — technically honest, operationally a lie. A weak model rubber-stamping consensus is the worst silent failure for an adversarial-review tool.
+
+## Key discoveries (the plumbing was already right)
+
+- **paircode supports per-peer model pinning, fully wired:** `peers.yaml model:` → `cli.py:309 peer.get("model")` → `runner.run_peer(model=...)` → `cliworker.get_spec("gemini", model=...)` → `gemini -m <model>`. Proven by `cliworker/tests/test_registry.py:64-67`. No code was missing — only discoverability and a sane default.
+- **cliworker already strips the stale key.** `registry.py` gemini spec: `env_strip=["GOOGLE_API_KEY", "GEMINI_API_KEY"]`. So even with a dead `AIza` key baked into the running Claude Code session, cliworker removes it before invoking gemini, which then falls through to `~/.gemini/.env`. **No shell restart or `~/.zshenv` edit is needed** — an earlier "you must restart" hypothesis was wrong and is retracted here.
+- **gemini-cli env loader has two traps** (`chunk-*.js` `loadEnvironment`/`findEnvFile`): (a) dotenv **never overrides** an existing `process.env` var; (b) discovery returns the **first** `.env` walking up — a Laravel repo root `.env` wins unless `advanced.ignoreLocalEnv: true`. Both matter for getting the key to land.
+- **There is no Gemini 3.5 Pro.** Pro and Flash version independently: Flash reached 3.5 (`gemini-3.5-flash`); the newest *Pro* is `gemini-3.1-pro-preview`. Cost magnitude (paid, /1M tok in/out, ≤200k): 3.1 Pro Preview $2/$12 · 2.5 Pro $1.25/$10 · 3.5 Flash $1.50/$9 (Flash output now near-Pro!) · 2.5 Flash $0.30/$2.50. A paircode peer call ≈ 1–5¢ regardless — cost is not the constraint, quality is.
+
+## The fix (this repo)
+
+The systemic root cause lived in `handshake.py`: `ProposedPeer` had no `model` field, so every auto-generated roster was born unpinned, and `_PEER_RANK` hardcoded the now-false belief *"gemini = Free tier, not for full forks."*
+
+- `ProposedPeer` gains `model: str = ""`. Because `asdict()` includes defaulted fields, **every generated roster now emits `model: ''`** — the lever is visible instead of hidden. Empty stays safely falsy downstream (`cli.py` passes no `-m`).
+- The stale gemini note is corrected to: *"Pin model: to a Pro tier — unpinned + a free/oauth login silently runs weak flash."* No model version is hardcoded (they rot fast — see "no 3.5 Pro").
+- `templates/peers.yaml` documents the `model` field with the silent-downgrade warning.
+- `tests/test_handshake.py` guards the new surface (model key present + pin round-trips).
+
+External (not this repo, recorded for trace): the maintainer's gemini-cli was reconfigured — `settings.json` auth → `gemini-api-key`, `advanced.ignoreLocalEnv: true`, `~/.gemini/.env` holding the paid key. The awali `.paircode/peers.yaml` should add `model: gemini-3.1-pro-preview` to its gemini peer — that is the per-peer, paircode-native pin and supersedes any global settings.json model.
+
+## Open paper cuts
+
+- **Resolved model is still not surfaced.** The header shows `(default)` when unpinned; paircode can't report the model the CLI actually chose because cliworker doesn't return it. A future improvement: have cliworker echo the resolved model back in `CLIResult` so the file-trace records what *ran*, not what was *requested*. That would have caught this in seconds.
+- **No preflight auth/tier check.** paircode can't tell a Pro peer from a free-flash one before spending a fork on it. A `paircode doctor`-style probe (cheap 1-token call asking tier) could warn "peer-b-gemini resolves to flash — pin a model?" at roster time.
+- **`propose_roster()` still emits `model: ''` for all CLIs.** It does not suggest a concrete Pro default per CLI (deliberately, to avoid version rot). If model-name stability ever improves, a per-CLI recommended default could be added behind `_PEER_RANK`.

{paircode-0.13.1 → paircode-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paircode"
-version = "0.13.1"
+version = "0.14.0"
 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.3",
+    "cliworker>=0.8.5",
 ]
 
 [project.urls]

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/__init__.py

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

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/cli.py

@@ -28,6 +28,7 @@ from paircode.handshake import propose_roster, proposed_as_yaml_dicts
 from paircode.installer import install_all, uninstall_all
 from paircode.runner import run_peer
 from paircode.state import (
+    ensure_gitignore,
     ensure_peer_dirs,
     find_paircode,
     init_paircode,
@@ -108,6 +109,9 @@ def ensure_scaffold() -> None:
     if state is None:
         state = init_paircode()
         did_init = True
+    else:
+        # Retroactively protect projects whose .paircode/ predates this guard.
+        ensure_gitignore(state.project_root)
 
     peers = read_peers(state)
     proposed_count = 0

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/detect.py

@@ -33,6 +33,11 @@ KNOWN_CLIS: dict[str, tuple[str, Path, str]] = {
         Path.home() / ".gemini",
         "Install Gemini CLI: `npm i -g @google/gemini-cli`",
     ),
+    "pi": (
+        "pi",
+        Path.home() / ".pi",
+        "Install Pi coding agent: `npm i -g @earendil-works/pi-coding-agent`",
+    ),
 }
 
 

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/handshake.py

@@ -16,6 +16,11 @@ class ProposedPeer:
     cli: str
     priority: str
     notes: str = ""
+    # Empty = let the CLI pick its own default model. Pin a specific model string
+    # (e.g. a Pro tier) to avoid the silent free-tier trap: an unpinned peer on a
+    # free/oauth login can quietly run a weak flash model and rubber-stamp consensus.
+    # Emitted into every generated roster so the field is discoverable, not hidden.
+    model: str = ""
 
 
 # Default ranking of peers when auto-proposing a roster.
@@ -25,7 +30,7 @@ _PEER_RANK: list[tuple[str, str, str]] = [
     # (cli, priority, notes)
     ("codex", "high", "Second opinion, good for silent-agreement hunts"),
     ("ollama", "medium", "Local unlimited; good if a capable model is pulled"),
-    ("gemini", "low", "Free tier — use for quick opinions, not full forks"),
+    ("gemini", "low", "Pin model: to a Pro tier — unpinned + a free/oauth login silently runs weak flash"),
 ]
 
 

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/installer.py

@@ -2,6 +2,7 @@
 
 Strategy per CLI:
   - Claude Code: file-drop ~/.claude/commands/paircode.md
+  - Pi:          file-drop ~/.pi/agent/prompts/paircode.md ($@ args, bash-parallel peers)
                  Claude's native plugin-install requires publishing a marketplace;
                  overkill for one command. File-drop is first-class + documented.
   - Codex CLI:   native register via `codex marketplace add starshipagentic/paircode-codex`
@@ -80,6 +81,31 @@ def install_claude(info: CliInfo) -> InstallResult:
     )
 
 
+def install_pi(info: CliInfo) -> InstallResult:
+    """Write ~/.pi/agent/prompts/paircode.md — file-drop (native for Pi coding agent).
+
+    Pi discovers prompt templates in ~/.pi/agent/prompts/ as /name slash commands.
+    The pi variant of the template uses `$@` for arguments (Pi's convention) and
+    fires peers as parallel background bash jobs (Pi has no stock Agent tool).
+    """
+    if not info.installed:
+        return InstallResult(
+            cli_name="pi", action="skipped", path=None,
+            message=f"pi CLI not on PATH. {info.install_hint}",
+        )
+    prompts_dir = info.config_dir / "agent" / "prompts"
+    prompts_dir.mkdir(parents=True, exist_ok=True)
+    target = prompts_dir / "paircode.md"
+    target.write_text(
+        _read_template("pi/prompts/paircode.md"),
+        encoding="utf-8",
+    )
+    return InstallResult(
+        cli_name="pi", action="installed", path=target,
+        message=f"Wrote /paircode prompt template to {prompts_dir}.",
+    )
+
+
 def _codex_already_installed() -> bool:
     """Idempotency check: is the paircode marketplace already registered?"""
     config = Path.home() / ".codex" / "config.toml"
@@ -181,6 +207,7 @@ def install_all() -> list[InstallResult]:
         "claude": install_claude,
         "codex": install_codex,
         "gemini": install_gemini,
+        "pi": install_pi,
     }
     results: list[InstallResult] = []
     for name, info in detected.items():
@@ -227,6 +254,7 @@ def uninstall_all() -> list[InstallResult]:
     claude_paths = [
         claude_home / "commands" / "paircode.md",
         claude_home / "commands" / "peerlab.md",
+        Path.home() / ".pi" / "agent" / "prompts" / "paircode.md",
         claude_home / "agents" / "paircode-peer.md",
     ]
     removed = []

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/state.py

@@ -31,6 +31,8 @@ PEERS_FILE = "peers.yaml"
 JOURNEY_FILE = "JOURNEY.md"
 FOCUS_FILE = "FOCUS.md"
 
+GITIGNORE_BLOCK_HEADER = "# paircode — adversarial multi-LLM peer review state"
+
 
 def _now_iso() -> str:
     return _dt.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
@@ -127,6 +129,24 @@ def ensure_peer_dirs(state: PaircodeState, proposed: Iterable) -> list[Path]:
     return created
 
 
+def ensure_gitignore(project_root: Path) -> bool:
+    """Append `.paircode/` to outer `.gitignore` if not already present.
+
+    Mirrors `peerlab.ensure_gitignore`. Idempotent; returns True when a line
+    is added, False when `.paircode/` (or `.paircode`) is already listed.
+    """
+    gitignore = project_root / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    for line in existing.splitlines():
+        s = line.strip()
+        if s in (".paircode/", ".paircode"):
+            return False
+    tail = existing.rstrip()
+    new_text = (tail + "\n\n" if tail else "") + GITIGNORE_BLOCK_HEADER + "\n.paircode/\n"
+    gitignore.write_text(new_text, encoding="utf-8")
+    return True
+
+
 def init_paircode(project_root: Path | None = None, force: bool = False) -> PaircodeState:
     """Bootstrap .paircode/ in `project_root` (or cwd). Returns the new state.
 
@@ -143,6 +163,7 @@ def init_paircode(project_root: Path | None = None, force: bool = False) -> Pair
         )
     root.mkdir(parents=True, exist_ok=True)
     (root / "sandbox").mkdir(exist_ok=True)
+    ensure_gitignore(project_root)
 
     journey = _render(
         _read_template("JOURNEY.md"),

{paircode-0.13.1 → paircode-0.14.0}/src/paircode/templates/peers.yaml

@@ -10,7 +10,11 @@
 # Fields:
 #   id              — peer-a, peer-b, peer-c, ... (unique, immutable)
 #   cli             — the command-line binary used to invoke this peer (claude/codex/gemini/ollama/aider/...)
-#   model           — specific model string (optional; CLI default if omitted)
+#   model           — specific model string. Optional but RECOMMENDED. If omitted,
+#                     the CLI picks its own default — which on a free/misconfigured
+#                     login can silently be a weak flash-tier model that just agrees
+#                     with you. Pin a Pro tier for real fork weight (e.g. gemini: a
+#                     *-pro* model; claude: sonnet/opus). Empty = CLI default.
 #   priority        — high | medium | low (used when budget is tight)
 #   daily_budget    — advisory only for now; paircode logs when a peer sits out
 #

paircode-0.14.0/src/paircode/templates/pi/prompts/paircode.md

@@ -0,0 +1,95 @@
+---
+description: "paircode — adversarial multi-LLM peer review. Fire peers in parallel, synthesize, write consensus to .paircode/. Usage: /paircode \"<prompt>\" [--peer id | --peers id,id]"
+---
+
+You are the **team lead** for a paircode peer-review cycle, running inside a pi session
+(alpha = you, whatever model this pi session runs). Your job: get the user a genuinely
+adversarial second opinion by firing every peer LLM in parallel, reading what they wrote,
+and synthesizing an honest consensus. All thoughts land on disk as Markdown under `.paircode/`.
+
+**$@** is the full user input after `/paircode`: a quoted prompt, optionally `--peer <id>`
+or `--peers <id,id>` filter flags.
+
+## File naming (inside every $FOCUS/{stage}/)
+- `alpha-vN.md` — your successive takes · `{peer-id}-vN.md` — each peer's takes
+- `reviews/round-N-{peer-id}-critiques-alpha.md` — peer critiques of alpha
+- `*-FINAL.md` (via `paircode converge {stage}`) · `consensus.md` — your synthesis (last write)
+
+**Reports vs code:** files in `$FOCUS/{stage}/` are always markdown reports. Code lives in
+sandboxes: peers in `.paircode/sandbox/{peer-id}/`, alpha (you) directly in the project root.
+Sandboxes are always available, never required — code only when it materially sharpens an answer.
+
+## Step 1 — Bootstrap (silent, via bash)
+```bash
+paircode ensure-scaffold
+FOCUS=$(paircode focus new "<slug-from-prompt>" --prompt "<the quoted prompt verbatim>")
+PEERS=$(paircode roster --alpha pi <user's --peer/--peers flags if any>)
+```
+Trust the roster. $FOCUS has research/ plan/ execute/ ask/ subdirs ready (each with reviews/).
+**Bootstrap discipline:** run `paircode focus new` EXACTLY ONCE and capture its stdout into $FOCUS. If you lose the value, do NOT re-run it — recover with `FOCUS=$(ls -td .paircode/focus-* | head -1)`. Strip `--peer`/`--peers` flags OUT of the text before passing the quoted prompt to `--prompt` (flags go to `paircode roster`, never into FOCUS.md).
+
+## Step 2 — Pick the flow (commit to the WHOLE flow)
+| Flow | Trigger |
+|---|---|
+| `ask` | "what do you think", "review/critique X", "second opinion" |
+| `research` | "figure out", "explore", "how should we" |
+| `research → plan` | "plan/design/lay out X" |
+| `research → plan → execute` | "build/fix/implement/ship/do" — most imperatives. **Default when ambiguous.** |
+| `execute` | "execute the plan at focus-NN" |
+
+Append `flow: <flow>` to `$FOCUS/FOCUS.md`. {stage} = first stage of {flow}.
+
+## Step 3 — Fire peers in PARALLEL (background bash, one job per peer)
+Construct a stage-appropriate peer prompt (see shapes below), then launch ALL peers at once:
+```bash
+for P in $PEERS; do
+  nohup paircode invoke "$P" "<stage-appropriate prompt>" --out "$FOCUS/{stage}/$P-v1.md" \
+    > "$FOCUS/{stage}/$P-invoke.log" 2>&1 &
+done
+wait   # blocks until every peer returns
+```
+Stage prompt shapes:
+- **research**: honest, skeptical, specific cold take on the prompt; sandbox scripts welcome to ground claims in real data; clean markdown, no preamble.
+- **plan**: concrete numbered plan (goal, scope, steps, risks, success criteria), KISS; read `../research/*-FINAL.md` if present.
+- **execute**: carry out `$FOCUS/plan/*-FINAL.md`; code/tests in your sandbox `.paircode/sandbox/{peer-id}/` only; report = what you built/ran, files, verification, open items.
+- **ask**: severity-ranked critique with file:line citations of the artifact FOCUS.md points to.
+
+## Step 4 — Alpha's own take (while peers run, before `wait` if you can)
+Write `$FOCUS/{stage}/alpha-v1.md` yourself — same stage rules. Your edge: this session's full
+context. Execute-stage asymmetry: peers code in sandboxes; you code directly in the project root
+(alpha-vN.md is the report; code lives in the repo).
+
+## Step 5 — Read everything
+After `wait`: read every `{peer-id}-v1.md` + your alpha file. Where did peers agree, clash,
+surface what you missed? Spot-check 1-2 cited claims against the actual repo.
+
+## Step 6 — Round convergence
+Quick one-shot prompt answered well in round 1 → converge. **Otherwise default to another
+round**: peers critique alpha (`reviews/round-N-{peer-id}-critiques-alpha.md` via the same
+parallel-invoke pattern), you write `alpha-v(N+1).md`, loop to Step 5. Stop when a round adds
+no new friction. No hard cap; use judgment.
+
+## Step 7 — Converge stage + consensus
+```bash
+paircode converge {stage}
+```
+Read every `*-FINAL.md`, then WRITE `$FOCUS/{stage}/consensus.md`:
+`# Consensus — {focus} — {stage}` with sections: **Where peers agreed / Where peers clashed /
+Team-lead verdict (2-3 honest paragraphs) / Next action (one concrete thing)**.
+Adversarial-but-honest. No pile-on, no rubber-stamping.
+
+## Step 8 — Advance the flow (mechanical — do NOT ask permission)
+{stage} = next stage in {flow}; jump to Step 3 (skip Steps 1-2). Previous stage's `*-FINAL.md`
+feed the next stage's prompts. The user's prompt was implicit go-ahead for the WHOLE flow;
+stop early only on a hard blocker, and say so in the final report. Last stage done → Step 9.
+
+## Step 9 — Final report (under 200 words)
+Focus path · stages+rounds run (e.g. `research (2) → plan (1) → execute (1)`) · peers that
+participated/failed · one-sentence headline from the last consensus.md.
+
+## Guardrails
+- Never skip Step 1; never invent peer commands — always `paircode invoke <id> "..." --out <path>`.
+- Fire EVERY rostered peer unless the user passed `--peer`/`--peers`.
+- Peers never touch files outside their sandbox; you never touch theirs.
+- If a peer invoke hard-fails, note it and continue with the rest — one dead peer never blocks the cycle.
+- No AI attribution in any artifact you write.

paircode-0.14.0/tests/test_handshake.py

@@ -0,0 +1,28 @@
+"""Handshake roster shape — guards the silent free-tier downgrade fix.
+
+Diary 004: an unpinned gemini peer on a free/oauth login silently ran a weak
+flash model and rubber-stamped a consensus. The fix makes the `model` field
+present in every generated roster so pinning is discoverable, and keeps an
+empty pin safely falsy downstream (cli.py treats "" as "CLI default").
+"""
+from __future__ import annotations
+
+from paircode.handshake import ProposedPeer, proposed_as_yaml_dicts
+
+
+def test_generated_roster_exposes_model_key_for_pinning():
+    """Every proposed peer must surface a `model` key, even when unpinned,
+    so users see the lever instead of falling into the silent-flash trap."""
+    peers = [ProposedPeer(id="peer-a-gemini", cli="gemini", priority="low", notes="x")]
+    dicts = proposed_as_yaml_dicts(peers)
+    assert "model" in dicts[0]
+    assert dicts[0]["model"] == ""  # empty = CLI default; falsy, so no -m flag is passed
+
+
+def test_model_pin_round_trips_into_roster_dict():
+    """A pinned model survives into the yaml dict that gets written to peers.yaml."""
+    p = ProposedPeer(
+        id="peer-a-gemini", cli="gemini", priority="high",
+        notes="", model="gemini-3.1-pro-preview",
+    )
+    assert proposed_as_yaml_dicts([p])[0]["model"] == "gemini-3.1-pro-preview"