paircode 0.7.1__py3-none-any.whl

paircode/journey.py

@@ -0,0 +1,63 @@
+"""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/runner.py

@@ -0,0 +1,114 @@
+"""Invoke peer LLM CLIs as subprocesses, capture output to .md files.
+
+This is the "spawn an LLM, write its answer to disk" primitive. Each CLI
+has different flags for non-interactive / prompt-mode; we normalize them
+here so upstream code just says "ask <peer> this prompt, save to <path>".
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+DEFAULT_TIMEOUT_SECONDS = 600  # 10 min per peer call — generous for cold research
+
+
+@dataclass(frozen=True)
+class PeerRunResult:
+    peer_id: str
+    cli: str
+    ok: bool
+    stdout: str
+    stderr: str
+    duration_s: float
+    command: list[str]
+
+
+def _cli_command(cli: str, prompt: str, model: Optional[str]) -> list[str]:
+    """Return the subprocess argv to invoke `cli` non-interactively with `prompt`."""
+    if cli == "claude":
+        # Claude Code: -p is non-interactive (print) mode
+        cmd = ["claude", "-p", prompt]
+        if model:
+            cmd.extend(["--model", model])
+        return cmd
+    if cli == "codex":
+        # Codex CLI: `codex exec` is non-interactive; --dangerously-bypass needed to
+        # write files / skip approvals when running headless.
+        cmd = ["codex", "exec", "--dangerously-bypass-approvals-and-sandbox", prompt]
+        if model:
+            cmd.extend(["--model", model])
+        return cmd
+    if cli == "gemini":
+        cmd = ["gemini", "-p", prompt]
+        if model:
+            cmd.extend(["--model", model])
+        return cmd
+    if cli == "ollama":
+        # Ollama needs a model name
+        return ["ollama", "run", model or "llama3.1", prompt]
+    # Unknown CLI — best-effort: pass prompt as last arg
+    return [cli, prompt]
+
+
+def run_peer(
+    peer_id: str,
+    cli: str,
+    prompt: str,
+    output_path: Path,
+    model: Optional[str] = None,
+    timeout_s: int = DEFAULT_TIMEOUT_SECONDS,
+) -> PeerRunResult:
+    """Run one peer LLM against `prompt`, write its stdout to `output_path`.
+
+    Returns a PeerRunResult capturing success/failure + full stdout + stderr.
+    The output file is written regardless of success (empty or error-captured
+    text) so that every invocation leaves a file-trace on disk.
+    """
+    import time
+
+    cmd = _cli_command(cli, prompt, model)
+    start = time.monotonic()
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout_s,
+            check=False,
+        )
+        duration = time.monotonic() - start
+        ok = proc.returncode == 0
+        stdout, stderr = proc.stdout, proc.stderr
+    except FileNotFoundError:
+        duration = time.monotonic() - start
+        ok = False
+        stdout = ""
+        stderr = f"{cli} binary not found on PATH"
+    except subprocess.TimeoutExpired:
+        duration = time.monotonic() - start
+        ok = False
+        stdout = ""
+        stderr = f"{cli} timed out after {timeout_s}s"
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    header = (
+        f"<!-- peer_id: {peer_id} -->\n"
+        f"<!-- cli: {cli} -->\n"
+        f"<!-- model: {model or '(default)'} -->\n"
+        f"<!-- duration_s: {duration:.1f} -->\n"
+        f"<!-- ok: {ok} -->\n\n"
+    )
+    body = stdout if ok else f"# Peer run FAILED\n\n```\n{stderr}\n```\n\n{stdout}"
+    output_path.write_text(header + body, encoding="utf-8")
+    return PeerRunResult(
+        peer_id=peer_id,
+        cli=cli,
+        ok=ok,
+        stdout=stdout,
+        stderr=stderr,
+        duration_s=duration,
+        command=cmd,
+    )

paircode/seal.py

@@ -0,0 +1,52 @@
+"""Seal 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.
+"""
+from __future__ import annotations
+
+import re
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+
+VERSION_RE = re.compile(r"^(?P<peer>[a-z0-9][a-z0-9-]*?)-v(?P<version>\d+)\.md$")
+
+
+@dataclass(frozen=True)
+class SealedFile:
+    peer_id: str
+    source: Path
+    final: Path
+
+
+def discover_latest_versions(stage_dir: Path) -> dict[str, Path]:
+    """Walk a stage dir, group files by peer_id, return peer_id → highest-version file."""
+    latest: dict[str, tuple[int, Path]] = {}
+    for p in stage_dir.iterdir():
+        if not p.is_file() or not p.name.endswith(".md"):
+            continue
+        m = VERSION_RE.match(p.name)
+        if not m:
+            continue
+        peer_id = m.group("peer")
+        version = int(m.group("version"))
+        if peer_id not in latest or version > latest[peer_id][0]:
+            latest[peer_id] = (version, p)
+    return {pid: path for pid, (_, path) in latest.items()}
+
+
+def seal_stage(stage_dir: Path) -> list[SealedFile]:
+    """For each peer in the stage, copy their highest-version file to {peer}-FINAL.md.
+
+    Idempotent: re-running re-seals to the current latest. No-op if no versioned
+    files found.
+    """
+    sealed: list[SealedFile] = []
+    for peer_id, src in discover_latest_versions(stage_dir).items():
+        final_path = stage_dir / f"{peer_id}-FINAL.md"
+        shutil.copy2(src, final_path)
+        sealed.append(SealedFile(peer_id=peer_id, source=src, final=final_path))
+    return sealed

paircode/state.py

@@ -0,0 +1,162 @@
+"""Read/write paircode state in .paircode/ directories.
+
+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)
+    focus-01-{slug}/
+      FOCUS.md
+      research/
+      plan/
+      execute/
+"""
+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
+
+
+PAIRCODE_DIRNAME = ".paircode"
+PEERS_FILE = "peers.yaml"
+JOURNEY_FILE = "JOURNEY.md"
+FOCUS_FILE = "FOCUS.md"
+
+
+def _now_iso() -> str:
+    return _dt.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _read_template(name: str) -> str:
+    return resources.files("paircode.templates").joinpath(name).read_text(encoding="utf-8")
+
+
+def _render(template: str, vars: dict[str, str]) -> str:
+    out = template
+    for k, v in vars.items():
+        out = out.replace("{{" + k + "}}", v)
+    return out
+
+
+def _slugify(text: str, max_len: int = 40) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug[:max_len].rstrip("-") or "unnamed"
+
+
+@dataclass(frozen=True)
+class PaircodeState:
+    root: Path                       # path to .paircode/ dir itself
+    journey_path: Path
+    peers_path: Path
+    peers_dir: Path
+    focus_dirs: list[Path]           # sorted by name
+
+    @property
+    def project_root(self) -> Path:
+        return self.root.parent
+
+    @property
+    def active_focus(self) -> Path | None:
+        """Latest focus by directory-name order (focus-NN prefix sorts naturally)."""
+        return self.focus_dirs[-1] if self.focus_dirs else None
+
+    @property
+    def focus_count(self) -> int:
+        return len(self.focus_dirs)
+
+
+def find_paircode(start: Path | None = None) -> PaircodeState | None:
+    """Walk up from `start` (or cwd) looking for .paircode/. Return None if absent."""
+    if start is None:
+        start = Path.cwd()
+    start = start.resolve()
+    for ancestor in [start, *start.parents]:
+        root = ancestor / PAIRCODE_DIRNAME
+        if root.is_dir():
+            return load_state(root)
+    return None
+
+
+def load_state(root: Path) -> PaircodeState:
+    focus_dirs = sorted(
+        [d for d in root.iterdir() if d.is_dir() and d.name.startswith("focus-")]
+    )
+    return PaircodeState(
+        root=root,
+        journey_path=root / JOURNEY_FILE,
+        peers_path=root / PEERS_FILE,
+        peers_dir=root / "peers",
+        focus_dirs=focus_dirs,
+    )
+
+
+def init_paircode(project_root: Path | None = None, force: bool = False) -> PaircodeState:
+    """Bootstrap .paircode/ in `project_root` (or cwd). Returns the new state."""
+    if project_root is None:
+        project_root = Path.cwd()
+    project_root = project_root.resolve()
+    root = project_root / PAIRCODE_DIRNAME
+    if root.exists() and not force:
+        raise FileExistsError(
+            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)
+
+    journey = _render(
+        _read_template("JOURNEY.md"),
+        {"project_name": project_root.name, "created_at": _now_iso()},
+    )
+    (root / JOURNEY_FILE).write_text(journey, encoding="utf-8")
+
+    (root / PEERS_FILE).write_text(_read_template("peers.yaml"), encoding="utf-8")
+
+    return load_state(root)
+
+
+def open_focus(state: PaircodeState, name: str, prompt: str | None = None) -> Path:
+    """Open a new focus dir `focus-NN-{slug}/`. Returns the focus path."""
+    next_num = state.focus_count + 1
+    slug = _slugify(name)
+    focus_dir = state.root / f"focus-{next_num:02d}-{slug}"
+    if focus_dir.exists():
+        raise FileExistsError(f"{focus_dir} already exists")
+    focus_dir.mkdir()
+    for stage in ("research", "plan", "execute"):
+        (focus_dir / stage).mkdir()
+    (focus_dir / "research" / "reviews").mkdir()
+    (focus_dir / "plan" / "reviews").mkdir()
+
+    focus_md = _render(
+        _read_template("FOCUS.md"),
+        {
+            "focus_name": name,
+            "created_at": _now_iso(),
+            "prompt": prompt or "(none given — edit this file to set the prompt)",
+        },
+    )
+    (focus_dir / FOCUS_FILE).write_text(focus_md, encoding="utf-8")
+    return focus_dir
+
+
+def read_peers(state: PaircodeState) -> list[dict]:
+    """Parse peers.yaml into a list of peer dicts. Returns [] if empty/missing."""
+    if not state.peers_path.exists():
+        return []
+    data = yaml.safe_load(state.peers_path.read_text()) or {}
+    return list(data.get("peers") or [])
+
+
+def write_peers(state: PaircodeState, peers: Iterable[dict]) -> None:
+    state.peers_path.write_text(
+        yaml.safe_dump({"peers": list(peers)}, sort_keys=False, default_flow_style=False),
+        encoding="utf-8",
+    )

paircode/templates/FOCUS.md

@@ -0,0 +1,35 @@
+# FOCUS — {{focus_name}}
+
+**Opened:** {{created_at}}
+**Prompt:** {{prompt}}
+
+## Goal
+
+_Edit this section with the concrete goal of this focus._
+
+## Roster override
+
+_Leave empty to inherit from `.paircode/peers.yaml`. Or list peer ids to include/exclude for this focus._
+
+```yaml
+include: []    # if set, only these peers participate
+exclude: []    # if set, these peers skip this focus
+```
+
+## Human gate
+
+```yaml
+mode: auto                   # auto | manual_between_stages | manual_every_N_rounds | manual_always
+max_rounds_per_stage: 20
+convergence: 3_rounds_no_new_findings
+```
+
+## Stages
+
+- [ ] research
+- [ ] plan
+- [ ] execute
+
+## Notes
+
+_Captain's running notes for this focus._

paircode/templates/JOURNEY.md

@@ -0,0 +1,21 @@
+# JOURNEY — {{project_name}}
+
+> Fleet log for paircode orchestration. Captain steers; LLMs author.
+> Initialized: {{created_at}}
+
+## Active focus
+
+_None yet. Run `paircode focus <name>` to open one._
+
+## History
+
+| # | Focus | Opened | Closed | Iterations | Result |
+|---|---|---|---|---|---|
+
+## Roster
+
+See `peers.yaml` at the root of `.paircode/` for the current peer lineup and per-peer config.
+
+## Notes
+
+Add captain's notes here as the journey progresses.

paircode/templates/claude_slash_command.md

@@ -0,0 +1,23 @@
+---
+description: Run paircode — adversarial journey framework for LLM peer review. Bootstraps .paircode/ if missing, otherwise advances the active focus.
+---
+
+You have access to the `paircode` CLI. It's a Python tool that orchestrates multi-LLM peer review (research → plan → execute) with file-traces on disk.
+
+Behavior:
+
+1. **Parse `$ARGUMENTS`.** Everything after `/paircode` is passed as CLI args. If empty, run `paircode` with no args (it prints status or bootstraps).
+2. **Run the CLI.** Invoke `paircode $ARGUMENTS` via Bash. Capture stdout and stderr.
+3. **Relay output to the user.** Show what paircode printed. If it asked a question (e.g., "accept proposed roster? y/n"), the user answers in the next turn and you pass their answer back via `paircode` again.
+4. **If `paircode` spawns its own LLM subprocesses** (for research/plan/execute stages), it handles that internally — you don't need to manage the loop. Just relay status updates back to the captain.
+5. **If the user's intent was a topic-level drive** (e.g., `/paircode "build a widget thing"`), invoke `paircode drive "<topic>"`.
+
+Common subcommands you'll see:
+- `paircode install` — register /paircode in Claude/Codex/Gemini (user already ran it if this command exists)
+- `paircode status` — summarize .paircode/ state in cwd
+- `paircode handshake` — detect installed LLM CLIs, propose peer roster
+- `paircode focus <name>` — open a new focus inside .paircode/
+- `paircode stage {research|plan|execute}` — run one peer-review round at that stage
+- `paircode drive "<topic>"` — high-level: open focus, run research → plan → execute sequentially
+
+Always show the captain what happened. Brief, honest, actionable.

paircode/templates/codex_rules.md

@@ -0,0 +1,13 @@
+# paircode — available via CLI
+
+When working in this project, you have access to the `paircode` command-line tool. It orchestrates multi-LLM peer review across research → plan → execute stages with file-traces stored in `.paircode/`.
+
+Invoke it via shell when relevant:
+
+- `paircode status` — show current `.paircode/` state
+- `paircode drive "<topic>"` — high-level workflow driver
+- `paircode stage research` / `plan` / `execute` — run one peer-review round
+
+The captain (user) may ask you to act as a peer reviewer to claude's work. Read files under `.paircode/focus-NN-*/` to see what's been produced; write your review files into the same focus dir.
+
+File-traces on disk are the communication medium between LLMs. Always read relevant `.paircode/*.md` files before reviewing, and always write your output to `.paircode/` when participating.

paircode/templates/peers.yaml

@@ -0,0 +1,20 @@
+# paircode peer roster — edit freely.
+#
+# alpha is the project itself — the primary developer (usually you + your
+# main LLM). No entry needed for alpha; its "code" is whatever lives at
+# 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}/.
+#
+# 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)
+#   mode            — full-fork | pair-code | opinion-only
+#   priority        — high | medium | low (used when budget is tight)
+#   daily_budget    — advisory only for now; paircode logs when a peer sits out
+#
+# Example roster (auto-generated by `paircode handshake`):
+
+peers: []

paircode-0.7.1.data/data/paircode/templates/FOCUS.md

@@ -0,0 +1,35 @@
+# FOCUS — {{focus_name}}
+
+**Opened:** {{created_at}}
+**Prompt:** {{prompt}}
+
+## Goal
+
+_Edit this section with the concrete goal of this focus._
+
+## Roster override
+
+_Leave empty to inherit from `.paircode/peers.yaml`. Or list peer ids to include/exclude for this focus._
+
+```yaml
+include: []    # if set, only these peers participate
+exclude: []    # if set, these peers skip this focus
+```
+
+## Human gate
+
+```yaml
+mode: auto                   # auto | manual_between_stages | manual_every_N_rounds | manual_always
+max_rounds_per_stage: 20
+convergence: 3_rounds_no_new_findings
+```
+
+## Stages
+
+- [ ] research
+- [ ] plan
+- [ ] execute
+
+## Notes
+
+_Captain's running notes for this focus._

paircode-0.7.1.data/data/paircode/templates/JOURNEY.md

@@ -0,0 +1,21 @@
+# JOURNEY — {{project_name}}
+
+> Fleet log for paircode orchestration. Captain steers; LLMs author.
+> Initialized: {{created_at}}
+
+## Active focus
+
+_None yet. Run `paircode focus <name>` to open one._
+
+## History
+
+| # | Focus | Opened | Closed | Iterations | Result |
+|---|---|---|---|---|---|
+
+## Roster
+
+See `peers.yaml` at the root of `.paircode/` for the current peer lineup and per-peer config.
+
+## Notes
+
+Add captain's notes here as the journey progresses.

paircode-0.7.1.data/data/paircode/templates/claude_slash_command.md

@@ -0,0 +1,23 @@
+---
+description: Run paircode — adversarial journey framework for LLM peer review. Bootstraps .paircode/ if missing, otherwise advances the active focus.
+---
+
+You have access to the `paircode` CLI. It's a Python tool that orchestrates multi-LLM peer review (research → plan → execute) with file-traces on disk.
+
+Behavior:
+
+1. **Parse `$ARGUMENTS`.** Everything after `/paircode` is passed as CLI args. If empty, run `paircode` with no args (it prints status or bootstraps).
+2. **Run the CLI.** Invoke `paircode $ARGUMENTS` via Bash. Capture stdout and stderr.
+3. **Relay output to the user.** Show what paircode printed. If it asked a question (e.g., "accept proposed roster? y/n"), the user answers in the next turn and you pass their answer back via `paircode` again.
+4. **If `paircode` spawns its own LLM subprocesses** (for research/plan/execute stages), it handles that internally — you don't need to manage the loop. Just relay status updates back to the captain.
+5. **If the user's intent was a topic-level drive** (e.g., `/paircode "build a widget thing"`), invoke `paircode drive "<topic>"`.
+
+Common subcommands you'll see:
+- `paircode install` — register /paircode in Claude/Codex/Gemini (user already ran it if this command exists)
+- `paircode status` — summarize .paircode/ state in cwd
+- `paircode handshake` — detect installed LLM CLIs, propose peer roster
+- `paircode focus <name>` — open a new focus inside .paircode/
+- `paircode stage {research|plan|execute}` — run one peer-review round at that stage
+- `paircode drive "<topic>"` — high-level: open focus, run research → plan → execute sequentially
+
+Always show the captain what happened. Brief, honest, actionable.

paircode-0.7.1.data/data/paircode/templates/codex_rules.md

@@ -0,0 +1,13 @@
+# paircode — available via CLI
+
+When working in this project, you have access to the `paircode` command-line tool. It orchestrates multi-LLM peer review across research → plan → execute stages with file-traces stored in `.paircode/`.
+
+Invoke it via shell when relevant:
+
+- `paircode status` — show current `.paircode/` state
+- `paircode drive "<topic>"` — high-level workflow driver
+- `paircode stage research` / `plan` / `execute` — run one peer-review round
+
+The captain (user) may ask you to act as a peer reviewer to claude's work. Read files under `.paircode/focus-NN-*/` to see what's been produced; write your review files into the same focus dir.
+
+File-traces on disk are the communication medium between LLMs. Always read relevant `.paircode/*.md` files before reviewing, and always write your output to `.paircode/` when participating.

paircode-0.7.1.data/data/paircode/templates/peers.yaml

@@ -0,0 +1,20 @@
+# paircode peer roster — edit freely.
+#
+# alpha is the project itself — the primary developer (usually you + your
+# main LLM). No entry needed for alpha; its "code" is whatever lives at
+# 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}/.
+#
+# 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)
+#   mode            — full-fork | pair-code | opinion-only
+#   priority        — high | medium | low (used when budget is tight)
+#   daily_budget    — advisory only for now; paircode logs when a peer sits out
+#
+# Example roster (auto-generated by `paircode handshake`):
+
+peers: []