@magnusekdahl/parallix 1.0.0

package/docs/readme-rewrite-benchmark.md

@@ -0,0 +1,188 @@
+# README rewrite benchmark — how credible developer-tool READMEs open
+
+**Purpose:** Establish what a skeptical engineer expects to see in the first screen of
+a developer-tool README, so the Parallix rewrite (task-1336) borrows proven structure
+without copying the hype patterns that would undercut its credibility.
+
+**Method:** Seven comparable projects were inspected — AI coding agents, agent
+frameworks, and CLI developer tools that compete for the same first-glance attention
+Parallix needs to win. For each: opening headline/tagline pattern, first-paragraph
+structure, what the README leads with (features / problem / example / screenshot /
+install / docs), quickstart depth, how credibility and caveats are handled, what is
+worth borrowing, and what should *not* be copied because it would make Parallix less
+credible.
+
+The benchmark is descriptive of the prevailing patterns these projects use; it is not a
+line-by-line transcription. The decisions column is the actionable output.
+
+---
+
+## 1. Aider (`Aider-AI/aider`)
+
+- **Headline/tagline:** "Aider is AI pair programming in your terminal." A one-line
+  capability statement, no adjectives.
+- **First paragraph:** What it is + the concrete loop it runs ("edit code in your local
+  git repo … works with your existing files"). Names Git as a first-class concept
+  immediately.
+- **Leads with:** Capability statement, then a short feature list, then install. A
+  recorded terminal cast (asciinema) sits near the top.
+- **Quickstart depth:** Very shallow path to value — `pip install aider-install` →
+  `aider --model …` → start editing. Two or three commands to a working session.
+- **Credibility/caveats:** Strong proof signal — leaderboard/benchmark numbers (SWE-style
+  edit benchmarks), explicit "works best with" model guidance, and an honest note that
+  results vary by model. Git auto-commit behavior is stated up front so it is not a
+  surprise.
+- **Borrow:** The one-line capability headline; naming Git as a first-class concept in the
+  first paragraph; a shallow two-to-three-command path to a first result; stating a
+  potentially surprising default behavior up front.
+- **Avoid:** Leading the page with benchmark leaderboards — Parallix has *one* measured
+  figure with heavy caveats (`docs/use-cases.md` UC-1), not a maintained benchmark, so a
+  leaderboard-style flex would over-claim. Keep the measurement, drop the leaderboard
+  framing.
+
+## 2. Goose (`block/goose`)
+
+- **Headline/tagline:** Positions as "an open-source, extensible AI agent that goes beyond
+  code suggestions" — it frames against the *limitation of the adjacent category*
+  (autocomplete/suggestions) rather than listing its own features first.
+- **First paragraph:** What it is + who builds it (Block) + the differentiator (executes
+  tasks, not just suggests). Establishes credibility by association and by contrast.
+- **Leads with:** Problem/positioning contrast, then capabilities, then install. Polished
+  but still text-first above the fold.
+- **Quickstart depth:** Medium — a CLI install plus a desktop option; a few steps to a
+  running agent, with provider/key setup called out.
+- **Credibility/caveats:** Corporate backing is the main trust signal; extension/MCP
+  ecosystem implies durability. Lighter on hard limitation statements.
+- **Borrow:** Positioning *against the adjacent category* ("goes beyond suggestions") is
+  exactly the move Parallix needs — define against "a single coding agent run directly,"
+  not against nothing. Naming who is behind it builds trust.
+- **Avoid:** Leaning on corporate backing as the trust signal (Parallix is a solo,
+  alpha, local-first project — claiming institutional weight would be dishonest). Replace
+  that trust signal with cited code/tests and stated caveats instead.
+
+## 3. OpenCode (`opencode-ai/opencode` / sst)
+
+- **Headline/tagline:** "The AI coding agent built for the terminal." A
+  built-for-*audience* tagline — it names the user (terminal-native developers) inside the
+  tagline itself.
+- **First paragraph:** Short — what it is and the audience, then straight to a visual and
+  install. Provider-agnostic ("works with any model") is stated early as a differentiator.
+- **Leads with:** Tagline → screenshot/TUI image → install. Heavily visual above the fold.
+- **Quickstart depth:** Shallow — a single curl/npm install line and a run command.
+- **Credibility/caveats:** Provider-agnosticism and a clean TUI are the implicit proof;
+  caveats are light.
+- **Borrow:** Naming the audience inside the positioning ("for operators comfortable with
+  Git and CLI"); stating provider-agnosticism (Parallix's multi-family support is a
+  genuine parallel — codex/claude/mistral/qwen).
+- **Avoid:** The screenshot-first above-the-fold — Parallix's mission is explicitly *out
+  of scope* for screenshots/demos (task-1336 Out of Scope), and a CLI workflow harness is
+  better shown by a command-flow block than a TUI image. Lead with text and a fenced
+  command example instead.
+
+## 4. Get Shit Done — `gsd` (agentic CLI task runner)
+
+- **Headline/tagline:** Blunt, outcome-named tagline (the tool name *is* the promise).
+  Plain-spoken, anti-hype voice.
+- **First paragraph:** States the pain ("you keep re-explaining context to your agent")
+  before the solution. Problem-first.
+- **Leads with:** Problem statement → the workflow it imposes (structured tasks/plans) →
+  install.
+- **Quickstart depth:** Shallow-to-medium; an install line and a first command that
+  produces a plan/task artifact.
+- **Credibility/caveats:** Plain voice itself is the credibility signal — it reads like an
+  engineer wrote it for engineers, not a marketing team. Limitations stated casually but
+  honestly.
+- **Borrow:** Problem-first opening (state the pain before the mechanism); the structured
+  workflow framing (tasks/plans as durable artifacts) is the closest analog to Parallix
+  missions/checkpoints; the plain anti-hype engineer voice is the exact tone target.
+- **Avoid:** Over-casual voice that drifts into jokes — Parallix's audience is a
+  *skeptical engineering manager*, so keep the plain voice but stay precise and sober.
+
+## 5. Continue (`continuedev/continue`)
+
+- **Headline/tagline:** "the leading open-source AI code assistant" — a category-leadership
+  claim plus what it is.
+- **First paragraph:** What it is + where it runs (IDE extensions) + extensibility. Names
+  the integration surface immediately.
+- **Leads with:** Capability + ecosystem, screenshots/GIFs of the IDE experience, then
+  install per-IDE.
+- **Quickstart depth:** Medium — install the extension, configure a model, use it; more
+  setup than a pure CLI.
+- **Credibility/caveats:** Open-source + large ecosystem as trust; a "leading" superlative
+  that only works because adoption backs it.
+- **Borrow:** Naming the integration surface early (for Parallix: Git worktrees + your
+  existing CI gate, not an IDE).
+- **Avoid:** The "leading" superlative — Parallix is alpha with one measured window; any
+  leadership/superlative claim fails the falsifiability bar (task-1336 Success Criteria,
+  ADR 039 Part 2). Also avoid IDE-centric framing: Parallix is explicitly *not* an IDE
+  (it is a CLI workflow harness), and the "What Parallix is not" section must say so.
+
+## 6. Codex CLI (`openai/codex`)
+
+- **Headline/tagline:** "a coding agent that runs locally on your computer." Local-first
+  capability statement.
+- **First paragraph:** What it is + local execution + a one-line install. Emphasizes
+  running in your terminal against your repo.
+- **Leads with:** Capability → install → a short usage example. Sandbox/approval behavior
+  is documented near the top because it affects trust.
+- **Quickstart depth:** Shallow — one install command, one run command.
+- **Credibility/caveats:** Documents sandboxing and approval modes early — security posture
+  *is* the caveat handling. Honest about what it will and won't touch.
+- **Borrow:** Local-first stated as a feature, not an apology ("local-first developer
+  workflow"); documenting safety/boundary behavior (for Parallix: review gate, verification
+  gates, what it will not auto-merge) as a trust signal rather than fine print.
+- **Avoid:** Nothing major to avoid; the trap here is matching its polish/scope claims —
+  Parallix should not imply a comparable maturity. State alpha status plainly.
+
+## 7. Cline (`cline/cline`)
+
+- **Headline/tagline:** Capability + autonomy framing ("can use your CLI and editor"),
+  with explicit human-in-the-loop language ("with your permission").
+- **First paragraph:** What it does + the explicit approval model. Autonomy is paired with
+  a control statement in the same breath.
+- **Leads with:** Capability → permission/approval model → screenshots → install.
+- **Quickstart depth:** Shallow (marketplace install).
+- **Credibility/caveats:** The *headline pairing* of "autonomous" with "with your
+  permission" is the credibility move — it pre-empts the "is this a runaway agent?"
+  objection in the first sentence.
+- **Borrow:** Pairing capability with a control statement up front — Parallix should pair
+  "runs multiple agents" with "behind a forced review step and your own verification
+  gates" so the autonomy fear is answered immediately. This directly informs the "What
+  Parallix is not … not a magic autonomous engineer" section.
+- **Avoid:** Marketplace/IDE-install framing (not applicable to a CLI harness).
+
+---
+
+## Cross-cutting findings
+
+1. **Every credible README states what the tool *is* in one line, in the first sentence,
+   with zero internal jargon.** None of the seven opens with its own internal
+   abstractions. → Parallix must not open with "authority stack / state-map / adapter
+   internals."
+2. **The strongest openers are problem-first or contrast-first** (Goose, gsd, Cline) — they
+   define against the adjacent category or name the pain before the mechanism. → Parallix
+   leads with "running several AI coding agents directly against one repo clobbers the
+   working tree" before describing missions/worktrees.
+3. **Shallow quickstart wins.** Two-to-three commands to a first result is the norm. →
+   Parallix's Quick start must be a short, honest path: `npm pack` + global install + a
+   first mission command, no enterprise walkthrough.
+4. **Caveats build trust when stated early and specifically** (Aider benchmarks + "varies
+   by model", Codex sandbox, Cline permission). → Parallix turns its *honesty* into the
+   trust signal: alpha, local-first, npm-pack-only, one measured window that eroded, review
+   coverage caveats — all cited.
+5. **Superlatives and leaderboards only work with adoption/benchmarks behind them**
+   (Continue "leading", Aider leaderboard). Parallix has neither at scale → no
+   superlatives, no "2× forever"; use the single cited figure *with* its caveats.
+
+## Structure decision
+
+The task-1336-specified structure (positioning line → Why Parallix? → What it does → The
+core workflow → Quick start → Example → Use cases → What Parallix is not → Current status →
+Documentation → Development → License) **matches the prevailing credible pattern** and is
+adopted as-is. It is problem-first (Why Parallix? early, per finding 2), keeps the
+quickstart shallow and high (finding 3), and dedicates explicit sections to caveats ("What
+Parallix is not", "Current status") per finding 4. No competitor revealed a clearly
+superior structure that would justify deviating, so **no stop-rule escalation is
+triggered**. The one adaptation from the benchmark: lead the page with a fenced
+command-flow / example block rather than a screenshot (findings re OpenCode/Continue),
+since screenshots are out of scope and a CLI harness is better shown as commands.

package/docs/use-cases.md

@@ -0,0 +1,105 @@
+# Parallix — Primary Use-Case Inventory (evidence-backed)
+
+**Author role:** Skeptical PM doing discovery, not advocacy.
+**Question answered:** Which use cases does Parallix actually support today, and which are strong enough for public positioning?
+**Method:** Every claim is sourced to repository code, tests, or configs — never to a README assertion — and any throughput claim is tied to the visualBoard measured retro figures *with their caveats*. See [CP-1.md](CP-1.md) for the raw evidence base.
+
+> **How to read a confidence level.**
+> **Confirmed** = the capability is executable code *and* exercised by a passing test cited by path.
+> **Partial** = the mechanism exists in code but enforcement, coverage, or measured value is incomplete (caveat stated).
+> **Aspirational** = documented intent only; not delivered today. All aspirational items live in their own section (§3).
+
+---
+
+## 1. Confirmed and Partial use cases
+
+Each use case carries the four required parts: **(P) persona/buyer**, **(B) before→after pain**, **(E) non-README evidence**, **(C) confidence + one-line justification.**
+
+### UC-1 — Run several AI coding agents on one repo at once without them clobbering each other
+
+- **(P)** Solo maintainer or small-team lead driving more than one AI coding agent against a single repository.
+- **(B)** *Before:* two agents in one working tree fight over the index, branch, and uncommitted files, so you serialize them (one agent idle while the other runs) or you hand-manage `git worktree` and branch naming yourself. *After:* each mission is given its own branch (`mission/<slug>`) and its own sibling checkout (`../<repo>-<slug>`) automatically, so N agents make progress independently and each lands by squash-merge.
+- **(E)** Worktree + branch creation is code: `lib/commands/draft.js:133` (mission branch name), `:135` (`ensureMissionBranch`), `:138-139` (`ensureWorktree` at the sibling path); pattern declared in `workflow.config.json` (`adapters.missions.worktreePattern: "../<repo>-<slug>"`, `branchPrefix: "mission/"`). Tested: `test/draft.test.js` — `ensureWorktree creates worktree when target directory is absent`, `ensureMissionBranch creates branch from main when absent`. **Measured value:** the observed mission-output gain depends on the comparison surface. In strict user-value terms, the visualBoard parallel-model periods ranged from `0.44/day` to `0.58/day` over a `0.28/day` human baseline — roughly **+57% to +107%** (`../visualBoard/docs/missions/2026/ai-workflow-retrospective-since-october/EVALUATION_SUMMARY.md:46-52`, `../visualBoard/docs/missions/2026/task-1023/RETROSPECTIVE_P5.md:20-30`). A later productized workflow window recorded **58 completed missions in 15 days** — about **27/week** or `~3.86/day` — which is roughly **+1,280%** versus the same `0.28/day` baseline if you frame the comparison as total completed mission throughput in a setup where the buyer no longer has to build the AI-SDLC machinery first (`../visualBoard/docs/missions/2026/task-1247/research.md:55-75`). The later Q2 normalization keeps the user-value story in the middle of that spread, at `0.54/day` in P4 and `0.48/day` in P6 (`../visualBoard/docs/missions/2026/task-1099/RETROSPECTIVE_Q2_2026.md:18-29`). **Caveats that travel with the range:** the low-end user-value periods carried heavy AI-workflow overhead (34% in the early summary; 85% AI-SDLC mix in P5), C2/external review coverage was only 7% against a 100% rule (`EVALUATION_SUMMARY.md:66`), the comparison METR study found AI *slowed* experienced devs 19% and carries a model-currency caveat (`:70-72`), and the high-end `27/week` figure is a different mission-output metric from user-value/day.
+- **(C)** **Confirmed** for the mechanic (worktree/branch isolation is tested code); the throughput *value* is **measured but caveated** — real and attributable to the parallel model, but highly dependent on whether you measure user-value delivery only or general completed-mission output in a productized workflow.
+
+### UC-2 — Don't lose a run when one AI provider hits its usage cap
+
+- **(P)** Anyone driving agents on metered/rate-limited LLM subscriptions (Claude, Codex/GPT, Mistral, local Qwen).
+- **(B)** *Before:* the agent prints "usage limit reached", the run dies, and you babysit it — manually restarting later or hand-switching to a different model. *After:* the limit message is pattern-detected, that agent family is written to a timed blocklist, and the run retries with the next eligible, unblocked family; only when all are exhausted does it fail loudly.
+- **(E)** Per-family limit regexes: `lib/agents/limit-hit.js:8-36`; selection honoring eligibility + blocklist + env override: `lib/agents/agents.js:382` (`selectAgent`), `:340-348` (`isAgentBlocked` for permanent/timed/`blocked:false`). Tested: `test/agents-limit-hit.test.js` — `startAgent persists a block via updateAgentBlock when limit-hit detector fires`, `startAgent throws when every eligible agent hits the limit`, `startAgent does not loop forever when WORKFLOW_AGENT is pinned and that agent hits limit`.
+- **(C)** **Confirmed** — detection, timed-block persistence, and next-agent retry are each covered by named passing tests.
+
+### UC-3 — Resume a long agent task exactly where it stopped, deterministically
+
+- **(P)** Operator running multi-step missions that outlast a single session or context window, possibly across machines.
+- **(B)** *Before:* a crashed or context-exhausted agent leaves you reconstructing what was already done by re-reading diffs. *After:* every checkpoint runs the gate, commits a checkpoint document, and pushes it with a literal `Next action:` line, so a later session (or a different agent) resumes from a written instruction rather than a guess.
+- **(E)** `lib/commands/checkpoint.js:41-47` (gate runs first), `:56-58` (`checkpoint(<slug>): <cp>` commit + `Next action:` body), `:67` (push). Handoff refuses to proceed without a checkpoint and auto-generates a minimal `CP-1.md` with a valid Goal Check when none exists: `lib/commands/handoff.js:92-102`. Tested: `test/handoff.test.js` (checkpoint discovery + auto-remediation).
+- **(C)** **Confirmed** — the commit/push + `Next action:` contract is code and the handoff path is tested.
+
+### UC-4 — Require a second review pass before merge (different AI preferred, same-family fallback when no other is runnable)
+
+- **(P)** Lead who distrusts single-agent self-approval — exactly the unverified-AI risk METR quantifies.
+- **(B)** *Before:* the agent that wrote the change also declares it done; nobody independent looks. *After:* review is a separate workflow step whose reviewer selection actively excludes the implementer (preferring a different agent family, falling back to the same family only when no other is runnable), and a self-approval is explicitly skipped at the provider and flagged as requiring a different agent or a human.
+- **(E)** Self-approval guard: `lib/review/review-commands.js:902` ("self-approval POST skipped. A different agent or a human must post the formal provider approval"). Reviewer selection *excludes the implementer* to prefer a different family — `lib/review/review-loop.js:427` (`selectAgent('review', { exclude: new Set([implementer]) })`) — but the same step has an **explicit same-family fallback**: when no different-family agent is runnable/unblocked it sets `reviewer = implementer` with source `single-family-fallback` (`lib/review/review-loop.js:484-485`). So review is a *separate step that prefers, but does not guarantee, a different agent*. (Note: `config/agents.json:9-20` lists the **same** four families for `active` and `review` — there is no separate reviewer pool; separation comes only from the runtime implementer-exclusion above.) Review loop with bounded attempts: `lib/review/review-loop.js:281` (`maxAttempts`).
+- **(C)** **Partial.** The *mechanism* (separate step + code-level self-approval block + implementer-exclusion at reviewer selection) exists in `test/review.test.js`, but two honesty constraints hold it below Confirmed: (a) the guarantee is incomplete *by design* — reviewer selection falls back to the *same* family when no other is runnable (`review-loop.js:484-485`), and measured C2 review coverage was only **7%** against the 100% rule (`EVALUATION_SUMMARY.md:66`); (b) that test suite is **timing-flaky** — it is async-poll/timeout-sensitive and non-deterministic across runs (observed both all-pass and 11–15 failures depending on machine load), so it is not a dependable green signal. Position this as "forces a second, preferentially-different review pass," **not** "guarantees a different reviewer or coverage."
+
+### UC-5 — Adopt the mission workflow without rewriting your existing CI
+
+- **(P)** Team with an established `make`/`npm`/script-based verification setup that wants the mission lifecycle without replacing its gate.
+- **(B)** *Before:* workflow tools assume their own gate runner, so adopting them means re-plumbing verification. *After:* the gate is a configured shell command with `{{area}}` substitution and a **no-op default** — declare your existing command in `workflow.config.json` and it runs verbatim; declare nothing and verification is a documented no-op pass rather than an invented gate.
+- **(E)** `lib/core/verification.js:5-11` (no-op notice when unconfigured), `:25-31` (`{{area}}` substitution), `:34` (`runVerificationGate`). This repo configures `npm test` / area `all` (`workflow.config.json` `adapters.verification`). Tested: `test/verification.test.js`.
+- **(C)** **Confirmed** — adapter resolution, substitution, and the no-op default are tested code.
+
+### UC-6 — See which agent family actually pays off, across every repo one runtime drives
+
+- **(P)** Operator/buyer deciding which paid agent subscriptions to keep or cut.
+- **(B)** *Before:* no durable, cross-repo record of how each agent performs, so the keep/cut decision is a hunch. *After:* a single parallix-owned `stats.csv` accumulates per-agent telemetry (`classification, implementer, pr_fix_rounds`, plus an extended 21-column schema) across every repository one runtime drives, keyed so the same mission in different repos stays distinct.
+- **(E)** `lib/commands/stats.js:14` (legacy 5-col schema), `:21-30` (extended schema). Tested: `test/stats.test.js` — `upsertStatsRow writes the workflow stats schema and updates existing missions idempotently`, `task-1314: upsertStatsRow keys on (repo, mission, stage) so same mission in different repos stays distinct`. The kind of agent-comparison this enables is demonstrated in `../visualBoard/docs/missions/2026/task-1023/RETROSPECTIVE_P5.md:198-243` (per-family PRs, reviews/PR, durations).
+- **(C)** **Partial.** Schema and CSV upsert are tested, but the value is bounded: the richest per-agent comparison in the evidence came from Forgejo PR data, not `stats.csv`, and two of four families record honest zeros for token usage (`opencode`/local Qwen and `mistral`/vibe telemetry are zeroed by design, per `README.md:230-231` describing `opencode-telemetry.js`/`mistral-telemetry.js`). So cross-agent *cost/value* comparison is complete only for `codex` and `claude` today.
+
+---
+
+## 2. Ranking — top 3 for immediate public positioning
+
+Ranked by *credibility as a public claim given cited evidence*, each naming the single competing tool/workflow a user would otherwise reach for, and each carrying a claim that is **only true of Parallix** given the evidence.
+
+| Rank | Use case | What the user reaches for instead | The claim only Parallix can make (with evidence) |
+|---|---|---|---|
+| **1** | UC-1 Parallel multi-agent execution | A single Cursor / Claude Code / Aider session run serially, or hand-rolled `git worktree` juggling | It is the *specific* mechanic an internal retro measured as the only one to beat a human baseline, with observed mission-output gains ranging from roughly **+57%** on strict user-value delivery up to about **+1,280%** on later completed-mission throughput in a productized setup (`EVALUATION_SUMMARY.md:46-52`, `RETROSPECTIVE_P5.md:20-30`, `task-1247/research.md:55-75`). No generic AI tool ships that attached measurement. |
+| **2** | UC-2 Usage-limit auto-failover across families | Manually restarting with a different model when you hit a cap | Family-specific limit detection → timed blocklist → retry-next-eligible is a tested control loop (`limit-hit.js:8-36`, `test/agents-limit-hit.test.js`), not a retry button. |
+| **3** | UC-4 Second review gate (prefers a different agent family, with same-family fallback) | Single-agent self-review, or waiting on a human PR reviewer | A self-approval is *code-blocked* and rerouted to a different family or human (`review-commands.js:902`), and reviewer selection actively excludes the implementer family (`review-loop.js:427`). (Marked Partial — there is a documented same-family fallback at `review-loop.js:484-485`, so this is "forces a second *attempt*," not "guarantees a different agent or coverage.") |
+
+**Genericness check (value-bar §3):** strike "Parallix" and substitute any other AI coding tool — rank 1 fails to read identically because the +57% to +107% user-value figures, and the later +1,280% completed-mission figure, are specific repository data; rank 2 fails because per-family limit regexes + timed blocklist is a named tested behavior, not a generic "retry"; rank 3 fails because a code-level self-approval block is specific behavior, not a slogan.
+
+**Feature-list strike check (value-bar §1):** removing every Parallix-internal noun still leaves a user situation in each top-3: (1) "run several AI agents on one repo at once without them overwriting each other"; (2) "when one provider hits its cap mid-task, continue on another automatically"; (3) "a second review pass by a preferentially different AI is forced before the author's own approval counts (though same-family fallback applies when no other agent is available)."
+
+---
+
+## 3. Aspirational / not-yet-supported (do NOT position as live)
+
+- **Public distribution (registry/Homebrew/Docker/signed binaries/CI-release automation).** Explicitly out of the near-term model — supported path is a local `npm pack` + global install only (`README.md:281-285`, cited here as the thing being *tested*, corroborated by `package.json:10-11` `publishConfig.access: "restricted"`). **Aspirational.**
+- **"Sustained 2× throughput at scale."** The observed range is context-dependent, not flat. Strict user-value throughput moved between `0.44/day` (+57%) and `0.58/day` (+107%), while a later productized window reached about `27/week` (`~3.86/day`, roughly +1,280% vs `0.28/day`) on completed-mission throughput (`RETROSPECTIVE_P5.md:20-30`, `RETROSPECTIVE_Q2_2026.md:18-29`, `task-1247/research.md:55-75`). A "consistently 2× faster" claim is **Aspirational** and hides the fact that these are different mission-output measures.
+- **Full structured telemetry for all four agent families.** `mistral`/`vibe` telemetry is blocked in-environment and records honest zeros, tracked as follow-up (`README.md:231`). Cross-agent cost comparison for all families is **Aspirational** until those sources exist.
+
+---
+
+## 4. Red-team (required adversarial self-review)
+
+The two weakest use cases and the single strongest objection a skeptical senior PM would raise against each:
+
+1. **UC-4 (Cross-agent review) is the weakest "confirmed-sounding" claim.**
+   *Objection:* "Even framed as a 'second-agent review gate that prefers a different family,' you still rank it as a differentiator — but the eligibility config lists the *same* families for `active` and `review` (`config/agents.json:9-20`), reviewer selection has a documented same-family fallback (`review-loop.js:484-485`), and your own cited retro puts real C2 coverage at **7%** against a 100% rule (`EVALUATION_SUMMARY.md:66`). The separation is preferential and best-effort, so even the softened claim leans on a control that often doesn't bind."
+   *How the evidence answers it:* It mostly concedes. The *self-approval block* (`review-commands.js:902`) and the *implementer-exclusion at reviewer selection* (`review-loop.js:427`) are real and present, so the mechanism is honestly "supported/forced at the point of approval." But it is not a guarantee: `config/agents.json:9-20` lists the **same** families for `active` and `review` (no dedicated reviewer pool), and there is an explicit **same-family fallback** (`review-loop.js:484-485`) when no other family is runnable. That is exactly why UC-4 is marked **Partial** and kept out of any "guarantee" framing. A PM should ship it as "forces a second review attempt by a *preferentially* different agent," not as a coverage or different-agent guarantee.
+
+2. **UC-6 (Cross-repo agent telemetry) over-reaches on value.**
+   *Objection:* "Your richest agent comparison (`RETROSPECTIVE_P5.md:198-243`) came from Forgejo PR data, not `stats.csv`, and two of four families log zero tokens by design. So 'know which agent pays off' is true only for codex and claude — the CSV alone can't make the buyer's decision you imply."
+   *How the evidence answers it:* It partially answers. The schema and idempotent upsert are tested (`test/stats.test.js`), so the *plumbing* claim holds; but the *decision-grade comparison* claim is bounded to families with structured telemetry. UC-6 is marked **Partial** with that boundary stated, and it is deliberately excluded from the top-3.
+
+---
+
+## 5. Limitations & honesty constraints (carried into any downstream positioning)
+
+- Throughput framing is permitted **only** with the cited observed ranges and their metric labels: `0.44-0.58/day` over a `0.28/day` baseline for user-value throughput, or `58 missions / 15 days` (`~27/week`, `~3.86/day`) for later completed-mission throughput. Do not blur those into one number. All such framing must travel with its caveats (34% overhead in the early summary, 7% C2 coverage, METR −19%/model-currency, P5 erosion under 85% AI-SDLC mix). A bare "2× faster" is a defect.
+- The README is treated as the artifact under test, never as proof — every value claim above is anchored to code/tests/configs/measured retro data.
+- visualBoard's human baseline carries acknowledged confounds (2022 codebase was simpler); rate comparisons are directional (`EVALUATION_SUMMARY.md:9`). The latest metrics-bearing retro is `../visualBoard/docs/missions/2026/task-1099/RETROSPECTIVE_Q2_2026.md`, which reports P4 `0.54/day`, P5 `0.44/day`, and P6 `0.48/day`.
+- History coverage backing this analysis: parallix — 14 `MISSION.md` files + 25 backlog tasks (≥10 ✓); visualBoard — `EVALUATION_SUMMARY.md`, `RETROSPECTIVE.md`, `BENCHMARK.md`, `RETROSPECTIVE_P5.md` among 18 retro files (≥3 ✓).

package/examples/README.md

@@ -0,0 +1,62 @@
+# parallix examples
+
+These examples use the provisional `px` runner from inside a **caller-supplied**
+target repository. They contain no fixed workstation paths, no sibling worktree
+names, no npm global install directory, no local registry URL, and they copy no
+`parallix/` source into the target repo.
+
+In every command below:
+
+- `PARALLIX_DIR` is the directory holding the parallix runtime when running
+  `node "$PARALLIX_DIR/px.js"` directly.
+- `TARGET_REPO` is a repository path **you** supply, then `cd` into before
+  running `px`.
+
+## Read-only environment check
+
+Runs `verify-env` which answers "Can I use this repo?" with an explicit verdict:
+
+```sh
+cd "$TARGET_REPO"
+node "$PARALLIX_DIR/px.js" verify-env
+```
+
+On a healthy repo the output ends with `[PASS] Environment verdict: USABLE`.
+On a blocked repo (e.g. invalid `workflow.config.json`) it exits 1 and prints `[FAIL] Environment verdict: NOT USABLE` followed by remediation steps.
+
+## Record a mission review event (writes only under the target repo)
+
+```sh
+cd "$TARGET_REPO"
+node "$PARALLIX_DIR/px.js" review-event my-slug --type human_note --actor reviewer \
+  --content "example note" --skip-git
+```
+
+## Runnable smoke
+
+`run-verify-env-smoke.sh` creates a throwaway target repo with `mktemp -d`,
+runs `verify-env` against it, and cleans up. It takes the parallix directory as
+an optional first argument (defaults to the directory containing this package's
+`px.js`):
+
+```sh
+./run-verify-env-smoke.sh                 # uses the bundled px.js
+./run-verify-env-smoke.sh /path/to/parallix/workflow
+```
+
+## Enterprise tarball transfer smoke
+
+`run-enterprise-tarball-workflow-smoke.sh` proves the enterprise transfer shape:
+it packs `parallix/` with `npm pack` into a throwaway transfer dir, then
+`npm install -g`s the tarball into an **isolated** global prefix (via
+`npm_config_prefix`, so it never touches the machine's real global install) and
+drives a throwaway target repo through `config`, `status`, `draft`, `handoff`,
+and `review-event` using the resulting `px` command. It asserts exactly one `px`
+is installed and that its `px.js` lives in the global prefix — never inside the
+target repo or mission worktree — then cleans up after itself:
+
+```sh
+./run-enterprise-tarball-workflow-smoke.sh
+```
+
+See `../README.md` for the canonical packaging and install commands.

package/examples/run-enterprise-tarball-workflow-smoke.sh

@@ -0,0 +1,257 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PACKAGE_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+PACKAGE_VERSION="$(node -p "require('$PACKAGE_ROOT/package.json').version")"
+SLUG="${1:-task-enterprise-hello}"
+TRANSFER_DIR="$(mktemp -d "${TMPDIR:-/tmp}/px-enterprise-transfer-XXXXXX")"
+RUNTIME_DIR="$(mktemp -d "${TMPDIR:-/tmp}/px-enterprise-runtime-XXXXXX")"
+TARGET_REPO="$(mktemp -d "${TMPDIR:-/tmp}/px-enterprise-target-XXXXXX")"
+REMOTE_REPO="$(mktemp -d "${TMPDIR:-/tmp}/px-enterprise-origin-XXXXXX")"
+FAKE_AGENT_BIN="$(mktemp -d "${TMPDIR:-/tmp}/px-enterprise-agent-bin-XXXXXX")"
+FAKE_AGENT="$FAKE_AGENT_BIN/codex"
+
+cleanup() {
+  git -C "$TARGET_REPO" worktree remove "../$(basename "$TARGET_REPO")-$SLUG" --force >/dev/null 2>&1 || true
+  rm -rf "$TRANSFER_DIR" "$RUNTIME_DIR" "$TARGET_REPO" "$REMOTE_REPO" "$FAKE_AGENT_BIN"
+}
+trap cleanup EXIT
+
+chmod 700 "$TRANSFER_DIR" "$RUNTIME_DIR" "$TARGET_REPO" "$REMOTE_REPO" "$FAKE_AGENT_BIN"
+
+cat > "$FAKE_AGENT" <<'AGENT'
+#!/usr/bin/env bash
+set -euo pipefail
+
+slug="${PX_ENTERPRISE_SMOKE_SLUG:?PX_ENTERPRISE_SMOKE_SLUG is required}"
+year="${PX_ENTERPRISE_SMOKE_YEAR:?PX_ENTERPRISE_SMOKE_YEAR is required}"
+mission_dir="docs/missions/$year/$slug"
+task_file="$(find backlog/tasks -maxdepth 1 -type f -name "*$slug*.md" | head -n 1)"
+
+mkdir -p "$mission_dir"
+
+if [ -f "$mission_dir/MISSION.md" ]; then
+  cat > "$mission_dir/MISSION.md" <<EOF
+# Mission: Hello World parallix Proof ($slug)
+
+## Goal
+Create one hello-world file through the packaged parallix workflow.
+
+## Why Now
+This proves the enterprise tarball can run against a separate target repository.
+
+## Scope
+- Create hello.txt with one tested line.
+
+## Out of Scope
+- Production deploys.
+
+## Success Criteria
+- [ ] hello.txt contains "hello from px enterprise smoke".
+
+## Risks and Assumptions
+- Fake local agent is used only for package smoke proof.
+
+## Checkpoints
+- CP 1: Create hello.txt and record proof.
+
+## Gates
+- [ ] ./scripts/verify-local.sh docs
+
+## Restricted Areas
+- Do not run production deploy scripts.
+
+## Stop Rules
+- Stop if the package runtime is copied into the target repo.
+EOF
+fi
+
+if [ -n "$task_file" ]; then
+  cat > "$task_file" <<EOF
+---
+id: ${slug^^}
+title: Hello world package proof
+status: refined
+assignee:
+  - codex
+created_date: '2026-06-05 00:00'
+labels:
+  - ai_sdlc
+---
+
+## Description
+
+Create a hello-world file through packaged parallix in this example repo.
+EOF
+fi
+
+cat > hello.txt <<'EOF'
+hello from px enterprise smoke
+EOF
+
+cat > "$mission_dir/CP-1.md" <<'EOF'
+# CP-1: Hello world package proof
+
+## Summary
+
+The packaged parallix `px` runner created this checkpoint in a temporary target
+repository while the parallix runtime stayed outside the target repository.
+
+## Goal Check
+
+| Goal | Status | Evidence |
+|---|---|---|
+| hello.txt created | DONE | hello.txt contains the expected smoke text. |
+
+Next action: handoff the temporary mission for review.
+EOF
+AGENT
+chmod +x "$FAKE_AGENT"
+
+git init --bare "$REMOTE_REPO" >/dev/null
+git -C "$TARGET_REPO" init -b main >/dev/null
+git -C "$TARGET_REPO" config user.email "px-enterprise@example.invalid"
+git -C "$TARGET_REPO" config user.name "Px Enterprise Smoke"
+git -C "$TARGET_REPO" remote add origin "$REMOTE_REPO"
+
+mkdir -p "$TARGET_REPO/backlog/tasks" "$TARGET_REPO/scripts" "$TARGET_REPO/docs/missions"
+cat > "$TARGET_REPO/backlog/tasks/$SLUG - hello-world.md" <<EOF
+---
+id: ${SLUG^^}
+title: Hello world package proof
+status: backlog
+assignee: []
+created_date: '2026-06-05 00:00'
+labels:
+  - ai_sdlc
+---
+
+## Description
+
+Create a hello-world file through packaged parallix in this example repo.
+EOF
+
+cat > "$TARGET_REPO/scripts/verify-local.sh" <<'VERIFY'
+#!/usr/bin/env bash
+set -euo pipefail
+area="${1:-docs}"
+case "$area" in
+  docs|all)
+    find docs -name '*.md' -print >/dev/null
+    ;;
+  *)
+    ;;
+esac
+exit 0
+VERIFY
+chmod +x "$TARGET_REPO/scripts/verify-local.sh"
+
+cat > "$TARGET_REPO/workflow.config.json" <<'CONFIG'
+{
+  "product": {
+    "name": "Enterprise Px Smoke"
+  },
+  "adapters": {
+    "tasks": { "provider": "backlog-md", "storage": "backlog" },
+    "missions": {
+      "baseDir": "docs/missions",
+      "branchPrefix": "mission/",
+      "worktreePattern": "../<repo>-<slug>"
+    },
+    "verification": {
+      "command": "./scripts/verify-local.sh {{area}}",
+      "defaultArea": "docs"
+    },
+    "review": { "provider": "none" },
+    "agents": {}
+  }
+}
+CONFIG
+
+git -C "$TARGET_REPO" add -A
+git -C "$TARGET_REPO" commit -m "example: install backlog hello world ticket" >/dev/null
+git -C "$TARGET_REPO" push -u origin main >/dev/null
+
+PACK_JSON="$(npm pack "$PACKAGE_ROOT" --json --pack-destination "$TRANSFER_DIR")"
+TARBALL="$(node -e "const p=JSON.parse(process.argv[1]); console.log(p[0].filename)" "$PACK_JSON")"
+TARBALL_PATH="$TRANSFER_DIR/$TARBALL"
+SHA256="$(sha256sum "$TARBALL_PATH" | awk '{print $1}')"
+
+# The enterprise runtime is `npm install -g <tarball>`, which puts a single `px`
+# on PATH and replaces any prior install. RUNTIME_DIR is an isolated global
+# prefix so this smoke never touches the machine's real global install.
+npm_config_prefix="$RUNTIME_DIR" npm install -g "$TARBALL_PATH" >/dev/null 2>&1
+export PATH="$FAKE_AGENT_BIN:$RUNTIME_DIR/bin:$PATH"
+
+VERSION_OUTPUT="$(px --version)"
+
+(
+  export PX_ENTERPRISE_SMOKE_SLUG="$SLUG"
+  export PX_ENTERPRISE_SMOKE_YEAR="2026"
+  export WORKFLOW_AGENT="codex"
+  cd "$TARGET_REPO"
+  px config >/dev/null
+  px status "$SLUG" >/dev/null
+  px draft "$SLUG" >/dev/null
+)
+
+MISSION_WORKTREE="$(dirname "$TARGET_REPO")/$(basename "$TARGET_REPO")-$SLUG"
+
+(
+  export PX_ENTERPRISE_SMOKE_SLUG="$SLUG"
+  export PX_ENTERPRISE_SMOKE_YEAR="2026"
+  export WORKFLOW_AGENT="codex"
+  cd "$MISSION_WORKTREE"
+  px handoff "$SLUG" --no-gate >/dev/null
+)
+
+(
+  cd "$MISSION_WORKTREE"
+  px review-event "$SLUG" \
+    --type human_note \
+    --actor px-enterprise-smoke \
+    --content "packaged px enterprise smoke completed" \
+    --timestamp "2026-06-05T120000" \
+    --skip-git >/dev/null
+)
+
+test -f "$MISSION_WORKTREE/hello.txt"
+grep -q "hello from px enterprise smoke" "$MISSION_WORKTREE/hello.txt"
+test -f "$MISSION_WORKTREE/docs/missions/2026/$SLUG/CP-1.md"
+test -f "$MISSION_WORKTREE/docs/missions/2026/$SLUG/review-events/2026-06-05T120000-human_note-1-px-enterprise-smoke.md"
+test ! -d "$TARGET_REPO/parallix"
+test ! -d "$MISSION_WORKTREE/parallix"
+grep -q "parallix $PACKAGE_VERSION" <<<"$VERSION_OUTPUT"
+
+# Exactly one px must be installed in the global prefix, and its px.js must live
+# there -- never inside the target repo or mission worktree. This is the single
+# runtime + runtime/target boundary assertion.
+INSTALL_COUNT="$(find "$RUNTIME_DIR/lib/node_modules" -maxdepth 1 -name parallix -type d | wc -l)"
+test "$INSTALL_COUNT" -eq 1 || { echo "FAIL: expected exactly one px install, found $INSTALL_COUNT" >&2; exit 1; }
+
+PX_JS="$(sed -n 's/^px: //p' <<<"$VERSION_OUTPUT")"
+test -n "$PX_JS"
+grep -q "node_modules/parallix/px.js" <<<"$PX_JS"
+case "$PX_JS" in
+  "$RUNTIME_DIR"/*) : ;;  # expected: under the global prefix
+  "$TARGET_REPO"/*|"$MISSION_WORKTREE"/*)
+    echo "FAIL: px.js resolved inside target/worktree: $PX_JS" >&2
+    exit 1
+    ;;
+  *)
+    echo "FAIL: px.js resolved outside the global prefix: $PX_JS" >&2
+    exit 1
+    ;;
+esac
+
+cat <<EOF
+PASS enterprise tarball workflow smoke
+transfer_dir=$TRANSFER_DIR
+target_repo=$TARGET_REPO
+mission_worktree=$MISSION_WORKTREE
+tarball=$TARBALL_PATH
+px_js=$PX_JS
+sha256=$SHA256
+version=$(head -n 1 <<<"$VERSION_OUTPUT")
+EOF