paircode 0.12.1__tar.gz → 0.12.4__tar.gz

{paircode-0.12.1 → paircode-0.12.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paircode
-Version: 0.12.1
+Version: 0.12.4
 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

{paircode-0.12.1 → paircode-0.12.4}/pyproject.toml

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

{paircode-0.12.1 → paircode-0.12.4}/src/paircode/__init__.py

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

{paircode-0.12.1 → paircode-0.12.4}/src/paircode/peerlab.py

@@ -41,6 +41,30 @@ SEED_EXCLUDES: tuple[str, ...] = (
 
 GITIGNORE_BLOCK_HEADER = "# peerlab — per-peer independent parallel labs"
 
+# Defaults dropped into each new peer lab's own .gitignore so peer commits
+# don't accidentally include Python bytecode, editor junk, OS cruft.
+# If the lab inherited a .gitignore from the project root (rsync seed), we
+# APPEND this block — user's rules win, these are a safety net.
+LAB_GITIGNORE_BLOCK = """\
+# peerlab defaults — python + editor junk (keep peer commits clean)
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+.coverage.*
+htmlcov/
+.DS_Store
+.idea/
+.vscode/
+*.swp
+"""
+LAB_GITIGNORE_MARKER = "peerlab defaults"
+
 
 @dataclass(frozen=True)
 class EnsureResult:
@@ -108,6 +132,25 @@ def _rsync_project(src: Path, dst: Path, excludes: Iterable[str] = SEED_EXCLUDES
     shutil.copytree(src, dst, ignore=_ignore)
 
 
+def ensure_lab_gitignore(lab: Path) -> bool:
+    """Ensure the peer lab has Python/editor junk gitignored. Idempotent.
+
+    If the lab already has a `.gitignore` (inherited via rsync from the
+    project root), our block is appended so user rules win. If none exists
+    (greenfield), our block IS the .gitignore.
+
+    Returns True if the block was added this call, False if it was already
+    there (marker detection).
+    """
+    gitignore = lab / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    if LAB_GITIGNORE_MARKER in existing:
+        return False
+    new_text = (existing.rstrip() + "\n\n" if existing.strip() else "") + LAB_GITIGNORE_BLOCK
+    gitignore.write_text(new_text, encoding="utf-8")
+    return True
+
+
 def _git_init(lab: Path) -> None:
     """`git init` inside `lab/`. No-op if already inited."""
     if (lab / ".git").exists():
@@ -121,17 +164,24 @@ def _git_init(lab: Path) -> None:
         subprocess.run(["git", "init", "--quiet", str(lab)], check=True)
 
 
-def _git_initial_commit(lab: Path, message: str = "initial seed from project root") -> bool:
+def _git_initial_commit(
+    lab: Path, peer_id: str, message: str = "initial seed from project root"
+) -> bool:
     """Stage everything + commit. Returns True if a commit was made.
 
-    Sets local-only user.name/email (doesn't touch global git config) so the
-    commit is authored even on machines without a global identity.
+    Authors the commit as the peer itself (`{peer_id} <{peer_id}@peerlab.local>`)
+    via lab-local git config. Every subsequent peer commit inside this lab
+    inherits that local identity — so `git log` in a peer's lab attributes
+    all work to that peer, clean replay.
     """
     if not any(lab.iterdir()):
         return False
-    # Local git config — scoped to this repo
-    subprocess.run(["git", "-C", str(lab), "config", "user.name", "paircode-peerlab"], check=False)
-    subprocess.run(["git", "-C", str(lab), "config", "user.email", "peerlab@paircode.local"], check=False)
+    # Local git config — scoped to this lab, doesn't touch global identity.
+    subprocess.run(["git", "-C", str(lab), "config", "user.name", peer_id], check=False)
+    subprocess.run(
+        ["git", "-C", str(lab), "config", "user.email", f"{peer_id}@peerlab.local"],
+        check=False,
+    )
     subprocess.run(["git", "-C", str(lab), "add", "-A"], check=False)
     # Commit only if there's something staged
     diff_check = subprocess.run(
@@ -183,8 +233,12 @@ def ensure_peer_labs(state: PaircodeState) -> list[EnsureResult]:
         lab.mkdir(exist_ok=True)
         # Seed from project root (might be empty for greenfield — rsync handles fine)
         _rsync_project(project_root, lab)
+        # Drop peerlab-default .gitignore so peer commits don't pull in
+        # __pycache__, .pytest_cache, editor junk etc. Appends if the lab
+        # already inherited a .gitignore from the project root.
+        ensure_lab_gitignore(lab)
         _git_init(lab)
-        _git_initial_commit(lab, message="initial seed from project root")
+        _git_initial_commit(lab, pid, message="initial seed from project root")
         results.append(EnsureResult(peer_id=pid, lab_path=lab, status="created"))
     return results
 

paircode-0.12.4/src/paircode/templates/claude/commands/peerlab.md

@@ -0,0 +1,113 @@
+---
+description: peerlab — each peer owns a parallel lab with its own git. Peers write real code, then cross-review each other's labs, then team lead synthesizes.
+---
+
+You are the team lead for a `/peerlab` run. Each peer has its own persistent lab at `.peerlab/<peer-id>/` with its own `.git/`. Peers **own** their labs. The flow is:
+
+1. **Work round** — every peer builds in its own lab.
+2. **Cross-review round** — every peer reads the OTHER peers' labs and writes an honest critique (`CRITIQUES.md`) in its own lab. Peer-reviews-peer is the adversarial content; do NOT skip this.
+3. **Team-lead synthesis** — alpha reads both the code diffs AND each peer's critiques, delivers the final take.
+
+Separate concept from `/paircode` — no focus dirs, no stages, no consensus.md. Real code evolution + peer critiques on disk, synthesis in the chat.
+
+`$ARGUMENTS` is the user's raw prompt. Pass it through verbatim.
+
+## Step 1 — Bootstrap (silent via Bash)
+
+```bash
+paircode peerlab ensure           # scaffolds + seeds + git-inits each lab (idempotent)
+PEERS=$(paircode roster --alpha claude)
+```
+
+`paircode peerlab ensure` is safe to run every time. First time: copies the project root into each peer's lab (minus standard excludes) and `git init`s it. Subsequent times: no-op.
+
+## Step 2 — Work round (fire every peer in parallel)
+
+For each peer-id in `$PEERS`, spawn one subagent via the Agent tool (`subagent_type=general-purpose`, `run_in_background=true`) — all in a single message so they run concurrently.
+
+Each subagent's prompt:
+
+```
+Monitor peer {peer-id} on the work round. Run this shell command and wait:
+
+  paircode peerlab invoke {peer-id} "<the user's prompt verbatim>"
+
+That fires the peer with cwd = .peerlab/{peer-id}/ (its own lab). The peer
+commits its work in its own .git before finishing.
+
+After it returns, gather:
+  1. The peer's stdout (narrative).
+  2. git -C .peerlab/{peer-id} log --oneline -5
+  3. git -C .peerlab/{peer-id} diff HEAD~1 HEAD --stat
+
+Report back under 400 words: peer-id, ok=yes/no, duration, 1-line summary,
+and the git stat.
+```
+
+Wait for every peer to finish the work round before starting Step 3.
+
+## Step 3 — Cross-review round (peers read each other's labs)
+
+This is the adversarial heart of `/peerlab`. Every peer now reads every OTHER peer's lab and writes an honest critique. Do not skip this — it's what makes `/peerlab` different from "parallel output".
+
+If only ONE peer finished Step 2 successfully, skip Step 3 (nobody to cross-review) and note it in the final synthesis. Otherwise:
+
+For each peer-id in the set of peers that succeeded in Step 2, spawn one subagent (Agent tool, `run_in_background=true`) — all in one message. Each subagent's prompt:
+
+```
+Monitor peer {peer-id} on the cross-review round. Run this shell command
+and wait:
+
+  paircode peerlab invoke {peer-id} "You already committed your own work
+  in your lab — your cwd. Now cross-review every OTHER peer's lab.
+  Siblings live at ../<other-peer-id>/ relative to your cwd. List them
+  with `ls ..` and exclude your own id ({peer-id}).
+
+  For each other peer:
+    git -C ../<other-peer-id> log --oneline
+    git -C ../<other-peer-id> diff HEAD~1 HEAD
+    # read the changed files directly if the diff isn't enough
+
+  Write CRITIQUES.md in YOUR cwd (your own lab) with one section per
+  peer you reviewed. Severity-ranked findings with file:line citations
+  pointing at the OTHER peer's files. Be specific. Don't pile on,
+  don't rubber-stamp. Cite real lines, not vibes.
+
+  Then commit your critique:
+    git add CRITIQUES.md
+    git commit -m 'cross-review'"
+
+After it returns, verify:
+  - .peerlab/{peer-id}/CRITIQUES.md exists and has non-trivial content
+  - git -C .peerlab/{peer-id} log -1 --oneline mentions 'cross-review'
+
+Report back under 300 words: peer-id, ok=yes/no, duration, and a 1-line
+summary of whose code this peer found most/least convincing.
+```
+
+Wait for every peer to finish cross-review before Step 4.
+
+## Step 4 — Synthesize (one message to user, ≤300 words)
+
+For each peer, read BOTH:
+- The work diff: `git -C .peerlab/<peer-id> log -p HEAD~2..HEAD` (covers work commit + critique commit — 2 commits if both rounds ran, 1 if Step 3 was skipped).
+- The critique: `.peerlab/<peer-id>/CRITIQUES.md` — what THIS peer thought of the OTHERS.
+
+Then produce a tight team-lead synthesis that leans on the peers' own voices, not just yours:
+
+- **Per-peer implementation summary**: 1–2 lines each — files touched, LOC delta, the shape of the approach.
+- **What peers said about each other**: extract the sharpest findings from each `CRITIQUES.md`. If codex called out a bug in gemini's lab with a file:line, quote it. If gemini pointed at an edge case codex missed, quote it. These are the adversarial moments — don't bury them.
+- **Cross-cutting themes**: where did peers agree about what's wrong? Where did they disagree? Disagreement is signal.
+- **Honest head-to-head**: which lab made the cleanest move, informed by the peer critiques? Don't play favorites, don't hedge.
+- **What to pull into alpha**: if a peer's approach is objectively better, name files + approach. Don't do the pull yourself — recommend.
+
+No focus dirs. No consensus.md. Just the synthesis as your chat reply.
+
+## Guardrails
+
+- **Alpha (this session) does NOT edit `.peerlab/<peer-id>/`.** Peers own their labs. You only read.
+- **Alpha does NOT implement the user's prompt in the project root.** That's a `/paircode` job or a direct Claude Code ask. `/peerlab` is strictly "peers go build + cross-review; I read the diffs and critiques."
+- **Fire every peer** unless the user's prompt explicitly names `--peer`/`--peers`. Watchdog protects against hangs.
+- **Do not skip Step 3.** The cross-review round is the point. If only one peer made it through Step 2, note why in the synthesis and skip Step 3 explicitly.
+- **If a peer fails** (hung, errored, no commits), note it in the synthesis and continue. One flaky peer doesn't sink the run.
+- **No AI attribution** in anything you write — see the maintainer's CLAUDE.md.

{paircode-0.12.1 → paircode-0.12.4}/tests/test_peerlab.py

@@ -11,8 +11,10 @@ from click.testing import CliRunner
 from paircode.cli import main
 from paircode.handshake import ProposedPeer
 from paircode.peerlab import (
+    LAB_GITIGNORE_MARKER,
     PEERLAB_DIRNAME,
     ensure_gitignore,
+    ensure_lab_gitignore,
     ensure_peer_labs,
     peer_lab_path,
 )
@@ -176,6 +178,81 @@ def test_paircode_peerlab_help_is_reachable():
 # Seed excludes honored
 # ---------------------------------------------------------------------------
 
+def test_lab_gitignore_has_pycache_on_fresh_lab(tmp_path, monkeypatch):
+    """Fresh lab's .gitignore excludes __pycache__ and bytecode so peer
+    commits don't pull in build junk. Regression for v0.12.0 bug where
+    `git add -A` in peer labs committed .pyc files."""
+    _init_and_scaffold(tmp_path, monkeypatch)
+    state = find_paircode()
+    ensure_peer_labs(state)
+    lab = peer_lab_path(state, "peer-a-codex")
+    gitignore = lab / ".gitignore"
+    assert gitignore.exists()
+    content = gitignore.read_text()
+    assert "__pycache__/" in content
+    assert "*.py[cod]" in content
+    assert LAB_GITIGNORE_MARKER in content
+
+
+def test_ensure_lab_gitignore_appends_to_existing(tmp_path):
+    """If user's project already has a .gitignore (rsync brought it over),
+    the peerlab block is APPENDED — user rules preserved."""
+    lab = tmp_path
+    (lab / ".gitignore").write_text("# user project rules\nsecrets.env\n")
+    assert ensure_lab_gitignore(lab) is True
+    content = (lab / ".gitignore").read_text()
+    assert "secrets.env" in content  # user rule preserved
+    assert LAB_GITIGNORE_MARKER in content  # our block added
+
+
+def test_ensure_lab_gitignore_is_idempotent(tmp_path):
+    """Second call no-ops if marker already there."""
+    lab = tmp_path
+    assert ensure_lab_gitignore(lab) is True
+    before = (lab / ".gitignore").read_text()
+    assert ensure_lab_gitignore(lab) is False
+    assert (lab / ".gitignore").read_text() == before
+
+
+def test_initial_commit_authored_as_peer_id(tmp_path, monkeypatch):
+    """Initial seed commit must be authored as the peer_id so replay
+    (git log) attributes work to each peer. Fixes v0.12.0 where commits
+    were authored as generic 'paircode-peerlab'."""
+    _init_and_scaffold(tmp_path, monkeypatch)
+    state = find_paircode()
+    ensure_peer_labs(state)
+    for pid in ("peer-a-codex", "peer-b-gemini"):
+        lab = peer_lab_path(state, pid)
+        r = subprocess.run(
+            ["git", "-C", str(lab), "log", "-1", "--format=%an <%ae>"],
+            capture_output=True, text=True, check=False,
+        )
+        assert pid in r.stdout, f"commit author should contain {pid}; got {r.stdout}"
+        assert f"{pid}@peerlab.local" in r.stdout
+
+
+def test_different_peers_produce_different_initial_commits(tmp_path, monkeypatch):
+    """Distinct peer_ids as commit authors mean the seed commit SHAs differ
+    across labs — proves independence beyond 'same content, same author,
+    accidental SHA collision'."""
+    _init_and_scaffold(tmp_path, monkeypatch)
+    state = find_paircode()
+    ensure_peer_labs(state)
+    codex_lab = peer_lab_path(state, "peer-a-codex")
+    gemini_lab = peer_lab_path(state, "peer-b-gemini")
+
+    def head_sha(lab):
+        r = subprocess.run(
+            ["git", "-C", str(lab), "rev-parse", "HEAD"],
+            capture_output=True, text=True, check=False,
+        )
+        return r.stdout.strip()
+
+    assert head_sha(codex_lab) != head_sha(gemini_lab), (
+        "initial seed commits should differ across labs since authors differ"
+    )
+
+
 def test_seed_excludes_dot_paircode_and_dot_git(tmp_path, monkeypatch):
     """Seeded labs must not contain `.paircode/` (recursion) or the outer
     repo's `.git/` (each lab gets its own fresh git instead)."""

paircode-0.12.1/src/paircode/templates/claude/commands/peerlab.md

@@ -1,71 +0,0 @@
----
-description: peerlab — each peer does real work in its own parallel lab with its own git; team lead reads the diffs and synthesizes.
----
-
-You are the team lead for a `/peerlab` run. Each peer has its own persistent lab at `.peerlab/<peer-id>/` with its own `.git/`. Peers **own** their labs — they write code, run tests, commit as they go. Your job: fire every peer on the user's prompt, read what they actually did (the diffs), and synthesize.
-
-This is a separate concept from `/paircode` — no focus dirs, no stages, no markdown consensus files. The deliverable is real code evolution per lab + your synthesis at the end.
-
-`$ARGUMENTS` is the user's raw prompt. Pass it through verbatim.
-
-## Step 1 — Bootstrap (silent via Bash)
-
-```bash
-paircode peerlab ensure           # scaffolds + seeds + git-inits each lab (idempotent)
-PEERS=$(paircode roster --alpha claude)
-```
-
-`paircode peerlab ensure` is safe to run every time. First time: copies the project root into each peer's lab (minus standard excludes) and `git init`s it. Subsequent times: no-op.
-
-## Step 2 — Fire every peer in parallel
-
-For each peer-id in `$PEERS`, spawn one subagent via the Agent tool (`subagent_type=general-purpose`, `run_in_background=true`) — all in a single message so they run concurrently.
-
-Each subagent's prompt:
-
-```
-You are monitoring the {peer-id} peer. Run this shell command and wait:
-
-  paircode peerlab invoke {peer-id} "<the user's prompt verbatim>"
-
-That fires the peer with its cwd set to .peerlab/{peer-id}/ (its own lab).
-The peer is expected to commit its work in its own .git before finishing.
-
-After it returns, gather:
-  1. The peer's stdout (its narrative of what it did).
-  2. `git -C .peerlab/{peer-id} log --oneline -5` — recent commits.
-  3. `git -C .peerlab/{peer-id} diff HEAD~1 HEAD --stat` — what changed.
-
-Report back to team lead in under 400 words: peer-id, ok=yes/no, duration,
-1-line summary of what the peer claims it did, plus the git stat output.
-```
-
-## Step 3 — Read the actual code each peer wrote
-
-When every peer has reported, for each peer-id:
-
-```bash
-git -C .peerlab/<peer-id> log --oneline -5
-git -C .peerlab/<peer-id> diff HEAD~1 HEAD
-```
-
-Read the actual diffs (use the Read tool on the changed files inside each lab, or just the full `git diff` output). This is the real content — NOT the peer's narrative in stdout. Trust the code over the claims.
-
-## Step 4 — Synthesize (one message to user, ≤300 words)
-
-Produce a tight team-lead synthesis:
-
-- **Per-peer summary**: 1–2 lines each — files touched, LOC delta, the shape of the approach.
-- **Cross-cutting themes**: did multiple peers hit the same issue/solution? That's signal.
-- **Honest head-to-head**: which lab made the cleanest move? Which went off-track? Don't play favorites but don't hedge.
-- **What to pull into alpha**: if any peer's approach is objectively better than what alpha would do, name the files + the approach. Don't do the pull yourself — just recommend.
-
-No focus dirs. No consensus.md. No markdown artifacts on disk. Just the synthesis as your reply to the user.
-
-## Guardrails
-
-- **Alpha (this session) does NOT edit `.peerlab/<peer-id>/`.** Peers own their labs. You only read.
-- **Alpha does NOT implement the user's prompt in the project root.** That's a `/paircode` job or a direct Claude Code ask. `/peerlab` is strictly "peers go build it, I read the diffs."
-- **Fire every peer** unless the user's prompt explicitly names `--peer`/`--peers`. Watchdog protects against hangs.
-- **If a peer fails** (hung, errored, no commits), note it in the synthesis and continue. One flaky peer doesn't sink the run.
-- **No AI attribution** in anything you write — see the maintainer's CLAUDE.md.