@magnusekdahl/parallix 1.0.5 → 1.1.1

package/README.md

@@ -2,7 +2,7 @@
 
 **Parallix is a local-first Git workflow CLI for running AI coding agents in isolated, reviewable missions instead of letting one long-lived agent session mutate your main checkout.**
 
-It is for engineers who already use Git and terminal-first coding agents such as Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral, and want branch isolation, resumable checkpoints, agent-family failover, and a forced review step without building that harness by hand.
+It is for engineers who already use Git and terminal-first coding agents such as Claude Code, Codex, OpenCode/custom, and Vibe/Mistral, and want branch isolation, resumable checkpoints, agent-family failover, and a forced review step without building that harness by hand.
 
 It wraps your existing AI coding workflow without replacing it: each mission gets its own branch and worktree, long runs checkpoint to markdown, review is a separate phase, and integration still goes through your repo's own verification command. A human still chooses the mission, launches each phase, reads the output, and decides what lands.
 
@@ -12,11 +12,10 @@ It wraps your existing AI coding workflow without replacing it: each mission get
 npm install -g @magnusekdahl/parallix
 px draft "create a hello world program"
 px active
-px review
 px integrate
 ```
 
-That path shows the whole value: isolate the work on its own branch and worktree, let an agent execute it with checkpoints, run a separate review phase, and only then integrate it back.
+That path shows the whole value: isolate the work on its own branch and worktree, let an agent execute it with checkpoints, autorun a separate review phase, and only then integrate it back when you are satisfied with the result.
 
 ## Why Parallix?
 
@@ -33,14 +32,14 @@ Parallix is a mission-based development workflow that addresses each of these di
 
 Each capability below is tied to a use case in [`docs/use-cases.md`](docs/use-cases.md), with the confidence level (Confirmed / Partial) carried through honestly.
 
-- **Run several AI coding agents on one repo without clobbering each other** *(UC-1 — Confirmed mechanic).* Every mission gets its own `mission/<slug>` branch and its own sibling git worktree (`../<repo>-<slug>`) automatically, so N agents make progress independently and each lands by squash-merge.
+- **Run several AI coding agents on one repo without clobbering each other**. Every mission gets its own `mission/<slug>` branch and its own sibling git worktree (`../<repo>-<slug>`) automatically, so N agents make progress independently and each lands by squash-merge.
 - **Fail over automatically when an agent hits its usage limit** *(UC-2 — Confirmed).* Per-family limit messages are pattern-detected; the 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. Agent usage limits stop a single session; they don't have to stop the mission.
-- **Resume a long mission deterministically** *(UC-3 — Confirmed).* Every checkpoint runs the gate, commits a checkpoint document with a literal `Next action:` line, and pushes it — so a later session or a different agent resumes from a written instruction, not a guess.
+- **Resume a long mission deterministically**. Every checkpoint runs the gate, commits a checkpoint document with a literal `Next action:` line, and pushes it — so a later session or a different agent resumes from a written instruction, not a guess.
 - **Force a second, preferentially-different coding agent review before merge** *(UC-4 — Partial).* Review is a separate step whose reviewer selection excludes the implementer to prefer a different agent family, and a self-approval is code-blocked at the provider. It falls back to the same family when no other agent is runnable, so this forces a second review *attempt* — it does not guarantee a different reviewer.
-- **Publish work to a Forgejo reviewer surface without making Forgejo your branch authority** *(Confirmed mechanic).* When the review provider is enabled, Parallix syncs the local baseline to a dedicated `review` remote and opens or updates the PR there; if Forgejo is disabled, the branch/worktree flow still runs locally.
-- **Use a repo-local Graphify knowledge graph for smaller codebase context pulls** *(Confirmed mechanic, optional, unproven payoff).* In repositories where the operator has already installed the Graphify skill, the workflow keeps `graphify-out/` isolated per worktree and refreshes it during review/integration, while the installed agent guidance steers codebase questions toward `graphify query` / `path` / `explain` before full reports or raw grep. That should reduce context bloat, but this repo does not currently claim a measured token-usage reduction.
-- **Keep your existing verification gate instead of agent self-reporting** *(UC-5 — Confirmed).* The gate is a configured shell command with a no-op default: declare your existing `make` / `npm` / script command in `workflow.config.json` and it runs verbatim; declare nothing and verification is a documented no-op pass, not an invented gate.
-- **See which agent family actually pays off across every repo one runtime drives** *(UC-6 — Partial).* A single operator-owned `stats.csv` accumulates per-agent usage telemetry across repositories. Token-cost comparison is complete today only for the families with structured telemetry (codex, claude, opencode/qwen); vibe/mistral record honest zeros by design.
+- **Publish work to a Forgejo reviewer surface without making Forgejo your branch authority**. When the review provider is enabled, Parallix syncs the local baseline to a dedicated `review` remote and opens or updates the PR there; if Forgejo is disabled, the branch/worktree flow still runs locally.
+- **Use a repo-local Graphify knowledge graph for smaller codebase context pulls**. In repositories where the operator has already installed the Graphify skill, the workflow keeps `graphify-out/` isolated per worktree and refreshes it during review/integration, while the installed agent guidance steers codebase questions toward `graphify query` / `path` / `explain` before full reports or raw grep. That reduces token-usage.
+- **Keep your existing verification gate instead of agent self-reporting**. The gate is a configured shell command with a no-op default: declare your existing `make` / `npm` / script command in `workflow.config.json` and it runs verbatim; declare nothing and verification is a documented no-op pass, not an invented gate.
+- **See which agent family actually pays off across every repo one runtime drives** *(UC-6 — Partial).* A single operator-owned `stats.csv` accumulates per-agent usage telemetry across repositories. Token-cost comparison is complete today only for the families with structured telemetry (codex, claude, opencode/local AI/custom); vibe/mistral record honest zeros by design.
 
 ## The core workflow
 
@@ -62,14 +61,12 @@ Install from the public npm registry and run a complete mission:
 
 ```sh
 npm install -g @magnusekdahl/parallix
-px --version
 px draft "hello world"
 px active
-px review
 px integrate
 ```
 
-`px draft` creates the mission branch, sibling worktree, mission file, and task record. Then `cd` into the mission worktree and run `px active`, `px review`, and `px integrate` there with no slug; the CLI infers the mission from the current branch/worktree.
+`px draft` creates the mission branch, sibling worktree, mission file, and task record. Then `cd` into the mission worktree and run `px active` and `px integrate` there with no slug; the CLI infers the mission from the current branch/worktree.
 
 Other draft entry points are available when you need them:
 
@@ -145,7 +142,6 @@ px active task-042
 # A second, preferentially-different agent reviews <main>..HEAD.
 # If Forgejo review is enabled, the PR is published to the dedicated
 # review surface; a self-approval by the implementing agent is blocked.
-px review task-042
 
 # Land it: runs configured integration gates, squash-merges to
 # the primary branch, updates board state, removes the branch
@@ -165,7 +161,7 @@ The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md
 
 ## What Parallix is not
 
-- **Not a model and not an AI coding agent.** It does not generate code itself. It coordinates the agents and models you already use (Claude Code, Codex, OpenCode/Qwen, and Vibe/Mistral).
+- **Not a model and not an AI coding agent.** It does not generate code itself. It coordinates the agents and models you already use (Claude Code, Codex, OpenCode/custom, and Vibe/Mistral).
 - **Not an IDE or an editor plugin.** It is a CLI workflow harness around Git and your existing toolchain — there is no UI, no autocomplete, no inline suggestions.
 - **Not a magic autonomous engineer.** This is a human-in-the-loop workflow. Nothing merges itself, and the safe operating model is that a human decides what to queue, when to run `px active`, how to respond to review findings, and whether `px integrate` should happen at all.
 - **Not a guaranteed throughput multiplier.** The observed gain varies with context. In the data we have, it ranges from roughly **+57%** on strict user-value output to about **+1,280%** on total completed-mission throughput in a later productized setup. Those are both real observations, but they are different mission-output measures and should be labeled that way.
@@ -177,8 +173,8 @@ The full evidence-backed inventory is in [`docs/use-cases.md`](docs/use-cases.md
 - **Distribution:** Published to the public npm registry as `@magnusekdahl/parallix`. Local tarball install (`npm pack`) is also supported. No Homebrew, no Docker image, no standalone binary, and no CI/release automation today.
 - **Review surface:** Forgejo is supported as the hosted PR viewer/publication surface, but the workflow remains local-first and can run without Forgejo when that provider is disabled.
 - **Versioning:** `CHANGELOG.md` is the versioning authority; PATCH bumps are the release discipline.
-- **Telemetry:** structured token/usage telemetry exists for the codex and claude families; the local-Qwen and mistral paths record honest zeros by design rather than fabricated numbers.
-- **Graphify:** the knowledge-graph path is supported for codex, claude, and qwen/opencode after one-time operator setup. It is optional, not a workflow prerequisite. The credible claim today is better-scoped context retrieval, not a proven token-savings benchmark.
+- **Telemetry:** structured token/usage telemetry exists for the codex and claude families; the local-custom and mistral paths record honest zeros by design rather than fabricated numbers.
+- **Graphify:** the knowledge-graph path is supported for codex, claude, and custom/opencode after one-time operator setup. It is optional, not a workflow prerequisite. The credible claim today is better-scoped context retrieval, not a proven token-savings benchmark.
 - **Review coverage** is best-effort, not guaranteed — see UC-4's caveats in [`docs/use-cases.md`](docs/use-cases.md).
 
 This is a tool for a local-first developer workflow on one machine, driven by an operator who reads the caveats.
@@ -188,7 +184,7 @@ This is a tool for a local-first developer workflow on one machine, driven by an
 - [`docs/use-cases.md`](docs/use-cases.md) — evidence-backed use-case inventory with confidence levels and red-team analysis (primary source of truth for what Parallix actually does today).
 - [`docs/authority-reference.md`](docs/authority-reference.md) — the internal operator reference: workflow modes, the authority model, agent selection, the layered validation model, checkpoint model, state mapping, command aliases, stats, persistent operator data, and the full public-distribution story.
 - [`docs/forgejo-setup.md`](docs/forgejo-setup.md) — how the Forgejo review surface, tokens, and `review` remote are bootstrapped.
-- [`docs/operator-setup.md`](docs/operator-setup.md) — one-time Graphify skill installation for codex, claude, and qwen/opencode.
+- [`docs/operator-setup.md`](docs/operator-setup.md) — one-time Graphify skill installation for codex, claude, and custom/opencode.
 - [`docs/readme-rewrite-benchmark.md`](docs/readme-rewrite-benchmark.md) — how comparable developer-tool READMEs are structured, and the decisions behind this one.
 - [`AGENTS.md`](AGENTS.md) — hard rules, restricted actions, and verification entrypoints.
 - `docs/adr/` — architecture decision records, including ADR 0044 (distribution model).

package/config/agents.json

@@ -3,11 +3,11 @@
   "_weights_comment": "Weights are relative integers (not percentages). Agent is selected by weighted random draw from eligible-and-supported set. Omit weights to use equal probability.",
   "steps": {
     "draft": {
-      "eligible": ["codex", "qwen", "mistral"],
+      "eligible": ["codex", "custom", "mistral"],
       "selection": "random"
     },
     "active": {
-      "eligible": ["codex", "claude",  "qwen", "mistral"],
+      "eligible": ["codex", "claude",  "custom", "mistral"],
       "selection": "random"
     },
     "conflict-resolution": {
@@ -15,7 +15,7 @@
       "selection": "random"
     },
     "review": {
-      "eligible": ["codex", "claude", "qwen", "mistral"],
+      "eligible": ["codex", "claude", "custom", "mistral"],
       "selection": "random"
     }
   },

package/config/workflow.config.schema.json

@@ -87,8 +87,20 @@
           "properties": {
             "models": {
               "type": "object",
-              "description": "Optional per-agent-family LLM model override, keyed by agent family name (e.g. codex, claude, gemini, glm, mistral, qwen). Each value is the model identifier passed to that agent's CLI. A family that is not listed sends no model parameter, so the agent uses its own default. There is no 'default' key.",
+              "description": "Optional per-agent-family LLM model override, keyed by agent family name (e.g. codex, claude, gemini, glm, mistral, custom). Each value is the model identifier passed to that agent's CLI. A family that is not listed sends no model parameter, so the agent uses its own default. There is no 'default' key.",
               "additionalProperties": { "type": "string" }
+            },
+            "subagents": {
+              "type": "object",
+              "description": "Operational limits for subagent spawning within an agent.",
+              "additionalProperties": false,
+              "properties": {
+                "maxParallel": {
+                  "type": ["integer", "null"],
+                  "minimum": 0,
+                  "description": "Maximum number of parallel subagent forks. When unset, null, or zero, no limit is applied."
+                }
+              }
             }
           }
         }

package/docs/adr/0047-per-mission-change-size-budget.md

@@ -0,0 +1,161 @@
+# ADR 0047: Estimate Mission Size in Net Engineering Lines, Not Agent-Usage %
+
+**Status:** Accepted
+**Date:** 2026-06-27
+**Task:** task-1355 (research; depends on the task-1267 hypothesis)
+
+## Context
+
+[task-1267](../../backlog/tasks/task-1267%20-%20Hypothesis-reduce-mission-size-to-increase-quality-controls.md)
+hypothesized that smaller missions correlate with fewer defects and proposed a
+flat **<1000-row ceiling**. task-1355 researched this against this repository's own
+archived missions. The full reproducible dataset and method are in
+[`missions/task-1355/data/dataset.md`](../../missions/task-1355/data/dataset.md);
+the analysis is in [`missions/task-1355/findings.md`](../../missions/task-1355/findings.md).
+Every quantitative claim in that research was re-verified against `git log` while
+authoring this ADR (line counts, review rounds, correlations, terciles all
+reproduce exactly), so the decisions below rest on measured data.
+
+### Today missions are estimated in the wrong unit
+
+Per [ADR 0032](0032-mission-refinement-state-and-usage-budget-signals.md) and
+[ADR 0036](0036-mission-sizing-and-dependency-wave-heuristics.md), a mission's
+draft-time size signal is **"Estimated agent % usage limit"** (e.g. "25–50%"). That
+unit is agent-specific, non-portable across models, untethered from the artifact a
+reviewer actually reads, and impossible to verify after the fact — there is no
+ground truth to compare a "%-usage" estimate against, so it can never be calibrated.
+
+### Not all lines are equal
+
+Parallix missions are line-heavy by construction. Each mission emits `MISSION.md`,
+per-checkpoint `CP-*.md`, `review-state.json`, and `review-events/*` files. These are
+**administrative bookkeeping**, not delivery. The risk a reviewer must reason about
+lives in the **engineering change** the mission ships — code and tests — not in its
+workflow paperwork or prose.
+
+Conflating them produces an actively misleading metric. Counting *total* commit lines
+correlates with review rounds at **+0.65**, much stronger than the engineering change
+alone (**+0.39**) — but this is **reverse causation, not signal**: every review round
+writes more `review-events/*` files into the same squash commit, so a mission that was
+hard to review mechanically grows its own line count. Any size signal must therefore
+exclude administrative and documentation lines, or it measures the workflow rather than
+the work.
+
+## Decision
+
+**Change the basis on which missions estimate their size, from agent-usage % to a
+predicted count of Net Engineering Lines (NEL), expressed as one of three buckets.
+Then capture the actual NEL at handoff so the draft estimate can, for the first time,
+be checked for reliability.** This ADR records the design and the data-gathering plan;
+it does **not** yet impose any gate or breach action — see "Why no enforcement yet".
+
+### 1. The metric — Net Engineering Lines (NEL)
+
+**NEL = insertions + deletions in code and test files**, computed `-w`
+(whitespace-insensitive), **excluding**:
+
+- workflow/process bookkeeping — `missions/**`, `backlog/**`, `review-*`, `*CP-*`;
+- documentation — `**/*.md`, `docs/**`;
+- generated / vendored — `package-lock.json`, `coverage/**`, and other lockfiles/build output.
+
+"Net Engineering Lines" is chosen as the name precisely to make the exclusions
+self-evident: *engineering* (code and tests, not prose), *net* (the diff, not the
+whole tree). It is the only one of task-1355's four candidate metrics that has both a
+usable correlation with review rework and **zero new tooling** — it is computable from
+`git diff --numstat` today:
+
+| Candidate | Correlation w/ review rounds (Pearson/Spearman) | Tooling | Verdict |
+|---|---|---|---|
+| **Net Engineering Lines** | **+0.39 / +0.37** | none | **Chosen** |
+| Files touched | +0.15 / +0.21 | none | weak signal |
+| Hunks (`@@`) | +0.06 / +0.27 | none | weakest |
+| Cyclomatic complexity delta | not measurable in-repo | high (AST) | deferred (see Future Work) |
+
+### 2. The draft estimate — a NEL bucket, replacing "% usage"
+
+At draft, the `MISSION.md` size signal becomes a **predicted NEL bucket**, replacing
+"Estimated agent % usage limit". The buckets are the empirical risk terciles found in
+this repo's archived missions (see §4):
+
+| Bucket | Predicted NEL | Observed rework rate in this repo (review round ≥ 3) |
+|---|---|---|
+| **Small** | 0–80 | 11% |
+| **Medium** | 81–235 | 22% |
+| **Large** | 235+ | 73% |
+
+### 3. The actual — capture NEL at handoff
+
+At handoff the **actual** NEL is computed from the merge diff (exact, cheap,
+tamper-evident) and recorded alongside the draft bucket. This produces, per mission, a
+`(predicted bucket, actual NEL, actual bucket, review rounds)` record — the
+prediction-vs-actual series the workflow has never had.
+
+### 4. Why these buckets — the data
+
+Binning the 29 archived missions into terciles by NEL, against the share needing
+rework (`review round ≥ 3`):
+
+| Bucket | NEL range | mean review rounds | % needing rework |
+|---|---|--:|--:|
+| small | 0–79 | 1.89 | **11%** |
+| medium | 92–235 | 2.00 | **22%** |
+| large | 270–1106 | 3.91 | **73%** |
+
+Missions above ~270 NEL needed rework **73%** of the time vs **11%** below ~80 — a
+~6.6× higher rate, concentrated at the small→large boundary. The bucket edges (80, 235)
+sit at these tercile boundaries. Note this places the risk inflection far below
+task-1267's proposed 1000-row ceiling, so a 1000-line wall would have missed the entire
+elevated-risk band.
+
+### Why no enforcement yet — calibrate before you gate
+
+task-1355 found the workflow has **no calibration data**: it never recorded a predicted
+size, so there has never been a way to know whether an up-front estimate is trustworthy.
+The findings show good reasons to doubt it — task-1360 shipped 1106 NEL but approved in
+**1 round** (a mechanical ESLint cleanup), while task-1332 shipped only 105 NEL but took
+**5 rounds** (small but hard) — i.e. whether a mission is large or *hard* depends on
+facts discovered during implementation.
+
+Gating on an uncalibrated estimate would therefore fire on noise. So this ADR
+deliberately stops at **changing the unit and gathering the data**. A threshold and a
+breach action (escalate review depth, force decomposition, block, etc.) are **deferred
+to a follow-up decision** that will be made only once the draft NEL bucket is shown to
+be a reliable estimator of the actual bucket. The whole point of capturing
+`(predicted, actual)` pairs now is to make that future decision evidence-based instead
+of guessed.
+
+## Consequences
+
+### Positive
+- Size is estimated in a **portable, verifiable** unit (lines of engineering change)
+  instead of an agent-specific, uncheckable "% usage".
+- The signal measures **delivery risk**, not workflow paperwork; the +0.65 total-line
+  confound is designed out by construction.
+- For the first time the workflow accumulates **prediction-vs-actual** data, so the
+  reliability of up-front sizing becomes an observable fact rather than an assumption.
+- Zero new tooling — NEL is computable from `git diff --numstat` today.
+- No disruption: nothing is blocked or escalated yet, so a wrong bucket costs nothing.
+
+### Negative / Limitations
+- The bucket edges (80 / 235) are provisional — n=29, single repo — and should be
+  re-tuned as the corpus grows.
+- NEL excludes documentation, so it **under-counts docs-heavy deliverables** (e.g.
+  research/ADR missions). This is an accepted trade-off for now: such missions carry
+  little executable-defect risk. Revisit if doc-only missions prove risky.
+- NEL is gameable at the margin (padding logic with dead code); since nothing is gated
+  on it yet, this is not yet a concern.
+
+### Future Work
+- Once enough `(predicted, actual)` pairs exist, **assess whether the draft NEL bucket
+  is a reliable estimator** of the actual bucket — this is the trigger for a follow-up
+  ADR on enforcement (threshold + breach action).
+- Add a **cyclomatic-complexity-delta** metric once AST tooling lands; evaluate it
+  against NEL on a larger sample.
+
+## Links
+- [task-1267 hypothesis](../../backlog/tasks/task-1267%20-%20Hypothesis-reduce-mission-size-to-increase-quality-controls.md)
+- [Research findings (task-1355)](../../missions/task-1355/findings.md)
+- [Reproducible dataset](../../missions/task-1355/data/dataset.md)
+- [ADR 0032](0032-mission-refinement-state-and-usage-budget-signals.md) — amended: this ADR replaces the "% usage limit" draft signal with a NEL bucket.
+- [ADR 0036](0036-mission-sizing-and-dependency-wave-heuristics.md) — amended: "Too Large" sizing is restated in NEL rather than agent-usage %.
+- Implementation: [task-1379](../../backlog/tasks/task-1379%20-%20Replace-agent-usage-size-signal-with-Net-Engineering-Lines-NEL-bucket-capture-actual-at-handoff.md) (replace the % usage signal with a NEL bucket; capture actual NEL at handoff).

package/docs/adr/index.md

@@ -15,6 +15,7 @@ ADR 0023 remains in WrGroceries and is cross-referenced here instead of copied.
 - `docs/adr/0044-workflow-distribution-model.md` — parallix productization path with `px` naming, runtime/target-state boundary, and a 5-alternative decision matrix; Accepted (2026-06-22, task-1331) on the near-term local npm tarball / global `px` install stance
 - `docs/adr/0045-parallax-branch-model.md` — Two integration modes (trunk-based and feature-branch), Forgejo as PR viewer only, `review` remote wiring, and branch naming conventions
 - `docs/adr/0046-npm-publish-process-and-security.md` — Adopt public npm registry publication for `@magnusekdahl/parallix` alongside the local tarball path; zero-dependency security posture, manual publish process, and rollback considerations
+- `docs/adr/0047-per-mission-change-size-budget.md` — Change the mission size-estimation basis from agent-usage % to **Net Engineering Lines (NEL)** — code+test diff, excluding docs and workflow/admin bookkeeping (the +0.65 reverse-causation confound). Draft estimate becomes a NEL bucket (0–80 / 81–235 / 235+, the empirical risk terciles); capture actual NEL at handoff to calibrate the estimate. No enforcement until the draft bucket is shown reliable.
 
 ## Cross-reference
 - `docs/adr/0023-ai-sdlc-configuration.md` remains in WrGroceries at `/home/magnus/code/visualBoard-task-1302/docs/adr/0023-ai-sdlc-configuration.md`.

package/docs/agents.md

@@ -7,13 +7,13 @@
 | codex   | `codex` |
 | claude  | `claude` |
 | mistral | `vibe` |
-| qwen    | `opencode` |
+| custom    | `opencode` |
 
 All four listed launchers are supported on this workstation. Step eligibility for all workflow steps (`draft`, `active`, `conflict-resolution`, `review`) is controlled by `parallix/config/agents.json`. If a launcher is missing from `PATH`, the harness fails loudly with the exact blocker before launching.
 
-## Tool Calling Workaround (qwen/opencode)
+## Tool Calling Workaround (custom/opencode)
 
-Opencode (qwen agent family) may encounter issues with concurrent tool calls or tool call timeouts during long-running workflow sessions. When working with opencode:
+Opencode (custom agent family) may encounter issues with concurrent tool calls or tool call timeouts during long-running workflow sessions. When working with opencode:
 
 - **Prefer sequential tool calls** over parallel calls for dependent operations — if tool B needs output from tool A, call them separately.
 - **Use `workdir` parameter instead of `cd` chains** — avoid `cd <dir> && command` patterns; always use `workdir` for directory changes.
@@ -27,7 +27,7 @@ Opencode (qwen agent family) may encounter issues with concurrent tool calls or
 | codex   | `codex exec --sandbox danger-full-access --cd <worktree> <prompt>` with a worktree-local `HOME` under `.workflow/codex-home`; resume uses `codex exec resume <session-id-or---last> <prompt>`; the launcher also seeds `.workflow/codex-home/.codex/config.toml` with the repo-standard trusted posture and copies `.codex/auth.json` so headless review commands can start and keep localhost Forgejo access |
 | claude  | `claude --dangerously-skip-permissions --output-format stream-json --verbose --include-partial-messages -p <prompt>` (cwd=worktree) — uses `--output-format stream-json --verbose --include-partial-messages` to stream real-time JSONL events (tool calls, assistant text chunks) to the operator's terminal via the spawn-tee mechanism. `--include-partial-messages` is required: without it, the assistant event contains the full response at once and no intermediate progress is emitted. Session-id extraction parses the `result` event from stream-json output, falling back to the `claude --resume <id>` regex on plain text. |
 | mistral | `vibe --prompt <prompt> --trust --output text` (cwd=worktree) — **Note: NOT resume-capable in current Vibe version**; session management uses internal state in `~/.vibe/logs/session/` but does not emit a parseable resume hint to stdout/stderr. |
-| qwen    | `opencode run --pure --dangerously-skip-permissions <prompt>` (cwd=worktree); resume uses `-s <session>` when a session id is known or `--continue` when only the family marker is known |
+| custom    | `opencode run --pure --dangerously-skip-permissions <prompt>` (cwd=worktree); resume uses `-s <session>` when a session id is known or `--continue` when only the family marker is known |
 
 ## Launch output watchdog
 
@@ -74,10 +74,10 @@ Eligibility is controlled by `parallix/config/agents.json`. The default config c
 ```json
 {
   "steps": {
-    "draft": { "eligible": ["codex", "qwen", "mistral"], "selection": "random" },
-    "active": { "eligible": ["codex", "claude", "qwen", "mistral"], "selection": "random" },
+    "draft": { "eligible": ["codex", "custom", "mistral"], "selection": "random" },
+    "active": { "eligible": ["codex", "claude", "custom", "mistral"], "selection": "random" },
     "conflict-resolution": { "eligible": ["claude", "codex", "mistral"], "selection": "random" },
-    "review": { "eligible": ["codex", "claude", "qwen", "mistral"], "selection": "random" }
+    "review": { "eligible": ["codex", "claude", "custom", "mistral"], "selection": "random" }
   }
 }
 ```
@@ -141,7 +141,7 @@ The workflow detects limit-hit messages in agent stdout/stderr and automatically
 
 ### Detection
 
-`parallix/lib/limit-hit.js` ships a regex catalog per agent family (`claude`, `codex`, `qwen`, `mistral`) covering the common shapes:
+`parallix/lib/limit-hit.js` ships a regex catalog per agent family (`claude`, `codex`, `custom`, `mistral`) covering the common shapes:
 - explicit phrases like `Claude usage limit reached`, `weekly limit`, `Quota exceeded`, `RESOURCE_EXHAUSTED`
 - HTTP signals (`429 Too Many Requests`, `rate_limit_exceeded`, `Retry-After: ...`)
 

package/docs/authority-reference.md

@@ -45,7 +45,7 @@ Mission flow: `backlog → draft → ready → active → review → approved
 
 ## 3. Agent Selection
 
-Four families: `codex`, `claude`, `mistral`, `qwen`. Step eligibility is in `config/agents.json`. Launchers are resolved from `PATH` by bare executable name.
+Four families: `codex`, `claude`, `mistral`, `custom`. Step eligibility is in `config/agents.json`. Launchers are resolved from `PATH` by bare executable name.
 
 `WORKFLOW_AGENT=<name>` overrides random selection only when that agent is eligible and unblocked. The effective blocklist is operator-owned at `<PARALLIX_HOME>/agents.local.json`; on first use parallix non-destructively migrates the legacy runtime-config, repo-root, and main-worktree files in that precedence order. Per-agent values: `true` (permanent block), `{ "until": "YYYY-MM-DD HH" }` (timed), `{ "blocked": false }` (unblock).
 
@@ -256,7 +256,7 @@ Behavior:
 Telemetry capture contract (task-1285):
 - Stage rows are keyed by `(mission, stage)`; `draft.js`, `active.js`, and the review loop each record their phase via `recordStageStats`/`recordActiveStats`/`recordReviewStats`.
 - Structured sources: Codex (`codex-telemetry.js`, rollout JSONL) and Claude (`claude-telemetry.js`, stdout SSE) populate real token/usage fields.
-- `opencode` (local Qwen) exposes no structured usage source, so `opencode-telemetry.js` records honest zeros with provider/model falling back to the agent family — never fabricated numbers.
+- `opencode` (local custom) exposes no structured usage source, so `opencode-telemetry.js` records honest zeros with provider/model falling back to the agent family — never fabricated numbers.
 - `vibe`/`mistral` telemetry is **blocked** in this environment; `mistral-telemetry.js` records honest zeros and the verification is tracked as follow-up task-1288.
 
 ---

package/docs/doc-standards.md

@@ -0,0 +1,89 @@
+# Documentation Standard
+
+Rules for writing and editing README.md and subdirectory READMEs in this repository. Derived from `docs/readme-rewrite-benchmark.md` (task-1336) and applied to the current product state.
+
+---
+
+## 1. Headline / Tagline
+
+- The first line after the H1 must be a **one-line capability statement** that tells a skeptical engineer what the tool does.
+- Zero internal jargon. Do not use terms like `authority stack`, `state-map`, `adapter internals`, `worktree pattern`, or any abstraction that only makes sense to someone who has read the code.
+- Name the audience or the execution context if it matters (e.g., "local-first", "CLI", "for Git operators").
+- **Bad:** "Parallix is an authority-driven mission orchestration engine."
+- **Good:** "Parallix is a local-first Git workflow CLI for running AI coding agents in isolated, reviewable missions."
+
+## 2. Opening Paragraph
+
+- After the headline, the first paragraph should be **problem-first or contrast-first**: name the pain or define against the adjacent category before describing the mechanism.
+- Keep it to 2-4 sentences. Do not lead with features, screenshots, or install commands.
+- If the tool has a potentially surprising default behavior, state it early (like Aider stating Git auto-commit behavior, like Cline stating the permission model).
+
+## 3. Quickstart Depth
+
+- Provide a **shallow path to value**: 2-3 commands to a first working result.
+- Do not bury the quickstart behind enterprise walkthroughs, multi-provider setups, or configuration steps.
+- The quickstart section must be visually separated (fenced code block) and immediately scannable.
+
+## 4. Caveats and Honesty
+
+- Caveats are **trust signals** when stated early and specifically. Alpha status, local-first constraints, limited telemetry, and best-effort guarantees belong in their own visible section ("Current status" or "Limitations").
+- Stating limitations upfront builds more credibility than hiding them in fine print.
+- Every quantitative claim must travel with its caveats and source references.
+
+## 5. Superlative Prohibition
+
+- No superlatives ("leading", "best", "fastest", "2x faster") without **adoption data or measured benchmarks** to back them.
+- If a claim cannot be falsified with a specific number and source, do not use it.
+- This is a hard rule for alpha-stage projects with limited measured data.
+
+## 6. "What It Is Not" Section
+
+- Every README must include a section titled **"What \<tool\> is not"** (or equivalent).
+- Pre-empt the top 3 objections a skeptical user would have (e.g., "not a model", "not an IDE", "not a magic autonomous engineer").
+- This section should appear after use cases and before current status.
+
+## 7. Structural Ordering
+
+The canonical order for this repository's README.md is:
+
+1. H1 title + one-line capability headline (bold)
+2. Audience + positioning paragraph
+3. **The first concrete thing you can do** (brief intro to quickstart)
+4. Quick start (fenced code block, 2-3 commands)
+5. Why \<tool\>? (problem-first)
+6. What it does (capabilities with evidence refs)
+7. The core workflow (diagram or description)
+8. Example (realistic human-in-the-loop pass)
+9. Use cases (summary with link to full inventory)
+10. What \<tool\> is not
+11. Current status (alpha caveats, distribution, review surface, versioning, telemetry)
+12. Documentation (links to supporting docs)
+13. Development (test command)
+14. License
+
+Subdirectory READMEs follow a simplified variant: H1 with capability statement, brief description, and relevant sections.
+
+## 8. Tone and Voice
+
+- **Plain, anti-hype, engineer-to-engineer.** Write like an engineer wrote it for engineers, not a marketing team.
+- Precise and sober. Casual is fine but do not drift into jokes or bluntness that undermines credibility with a skeptical engineering manager.
+- Use active voice. Prefer concrete verbs over abstract nouns.
+- When describing capabilities, tie them to evidence: use-case IDs, file paths, test names, or config references.
+
+## 9. Link Hygiene
+
+- All relative links in README.md must resolve to existing files.
+- Before editing any README, verify: `docs/use-cases.md`, `docs/authority-reference.md`, `docs/forgejo-setup.md`, `docs/operator-setup.md`, `docs/readme-rewrite-benchmark.md`, `AGENTS.md`, `CHANGELOG.md`, `LICENSE`, `docs/adr/`.
+- Broken links are defects, not acceptable trade-offs.
+
+## 10. Subdirectory READMEs
+
+- `lib/README.md`, `examples/README.md`, and any future subdirectory READMEs must begin with a one-line capability statement (no internal jargon).
+- Use consistent heading hierarchy: H1 for the directory name, H2 for sections, H3 for subsections.
+- Keep them concise — they are navigation aids, not deep documentation.
+
+---
+
+## Enforcement Hook
+
+These rules are enforced by the hook in `AGENTS.md` under the "Documentation" section. Agents editing any `.md` file in the repo root or `docs/` directory MUST consult this standard before committing changes.

package/docs/forgejo-setup.md

@@ -10,18 +10,42 @@ Standalone workflow installs need three review-surface pieces before `active`, `
 
 1. Export the workflow into the repo.
 2. If you need a local Forgejo instance, run `parallix/tools/setup-forgejo-docker.sh` and start it with Docker Compose.
-3. Run `px setup`.
-4. Choose whether to keep the standard Backlog.md-style layout:
+3. Create the Forgejo accounts the workflow will use (see [Create the agent accounts](#create-the-agent-accounts-fresh-instance)). On a fresh instance these do not exist yet, and `px setup` only mints *tokens* for accounts that already exist — it does not create the accounts themselves.
+4. Run `px setup`.
+5. Choose whether to keep the standard Backlog.md-style layout:
    - task storage in `backlog/`
    - missions in `missions/`
    - `mission/*` branches on `main`
    - worktrees in `../<repo>-<slug>`
    - verification via `npm test`
-5. If you keep Forgejo bootstrap enabled, enter the Forgejo password for the login that can create the review repo.
-6. Enter passwords for the agent users you want available on this machine, or leave them blank to skip token creation for that user.
+6. If you keep Forgejo bootstrap enabled, enter the Forgejo password for the login that can create the review repo.
+7. Enter passwords for the agent users you want available on this machine, or leave them blank to skip token creation for that user.
 
 `setup` writes `workflow.config.json`, writes token files into `.forgejo-local/tokens/`, grants the listed agent users write access to the configured review repo, creates or updates the git `review` remote, and runs `verify-env` so the install is validated before you start missions.
 
+## Create the agent accounts (fresh instance)
+
+`px setup` / `px setup-review` create **tokens** and grant repo access, but they do **not** create Forgejo user accounts — both the basic-auth token path and the owner-token bootstrap path call `POST /users/<user>/tokens` and `PUT /repos/<repo>/collaborators/<user>`, which require the account to already exist. On a fresh Forgejo you must create the accounts first, or token creation fails with HTTP 404 / 401 for users that don't exist.
+
+Create one account per identity the workflow uses:
+
+- the **owner** that holds the review repo (default `human`),
+- one account per agent family that runs `active`/`review` steps. The canonical list comes from `suggestedForgejoUsers()` — currently `codex`, `claude`, `custom`, `mistral`. (`custom` is the opencode-backed local-model family; it is a first-class identity just like the hosted agents.)
+
+For the bundled Docker instance, create them with the Forgejo admin CLI inside the container (replace `<container>` with your Forgejo container name, e.g. `workflow-forgejo`):
+
+```bash
+for u in human codex claude custom mistral; do
+  docker exec -u 1000 <container> forgejo admin user create \
+    --username "$u" --email "$u@localhost" \
+    --password "CHANGE-ME-$u" --must-change-password=false
+done
+```
+
+Then run `px setup` and enter each account's password so the token files are minted into `.forgejo-local/tokens/`.
+
+> **Adding or renaming an agent family later** (e.g. the `qwen` → `custom` rename): the new family name is a new Forgejo identity. Create its account with `forgejo admin user create`, grant it write on the review repo, then re-run `px setup-review` to mint its token. Without this, `integrate`/`review` fail with `no token file found for <family>` even though every other agent works.
+
 ## Notes
 
 - The configured review repo is created only if it does not already exist.

package/docs/migration/task-classification.md

@@ -15,7 +15,7 @@
 | `TASK-1275` | move | workflow/parallix subject from title and mission context |
 | `TASK-1277` | stay | model-capacity tuning note for GPT family selection; not the parallix workflow tool itself |
 | `TASK-1281` | move | workflow/parallix subject from title and mission context |
-| `TASK-1287` | stay | qwen-9B benchmark note; a model-evaluation task, not a parallix workflow change |
+| `TASK-1287` | stay | custom-9B benchmark note; a model-evaluation task, not a parallix workflow change |
 | `TASK-1288` | move | workflow/parallix subject from title and mission context |
 | `TASK-1290` | move | workflow/parallix subject from title and mission context |
 | `TASK-1294` | move | workflow/parallix subject from title and mission context |

package/docs/operator-setup.md

@@ -25,7 +25,7 @@ Run the installer once per agent family. It copies a platform-specific skill (an
 |--------|---------|-----------------|
 | claude | `graphify install --platform claude` | `~/.claude/skills/graphify/` + `CLAUDE.md` directive |
 | codex | `graphify install --platform codex` | `~/.agents/skills/graphify/` |
-| qwen/opencode | `graphify install --platform opencode` | `~/.config/opencode/skills/graphify/` |
+| custom/opencode | `graphify install --platform opencode` | `~/.config/opencode/skills/graphify/` |
 
 Each command produces a `SKILL.md` file in the target directory. After running all three, verify:
 

package/docs/readme-rewrite-benchmark.md

@@ -73,7 +73,7 @@ line-by-line transcription. The decisions column is the actionable output.
   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).
+  genuine parallel — codex/claude/mistral/custom).
 - **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