@magnusekdahl/parallix 1.1.0 → 1.2.0

package/config/integration-pipelines.json

@@ -0,0 +1,9 @@
+{
+  "gates": {
+    "lib": {
+      "command": "./scripts/verify-local.sh static-analysis",
+      "order": 1,
+      "run_last": false
+    }
+  }
+}

package/config/workflow.config.schema.json

@@ -89,6 +89,18 @@
               "type": "object",
               "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/0032-mission-refinement-state-and-usage-budget-signals.md

@@ -55,22 +55,23 @@ Also adopt one explicit place for selection metadata:
 
 `## Refinement Signals` must contain:
 
-- `Estimated agent % usage limit`: one of `0-25%`, `25-50%`, `50-75%`, `75-100%`, `100%+`
+- `Predicted NEL bucket`: one of `Small (0–80)`, `Medium (81–235)`, `Large (235+)` per ADR 0047
 - `Confidence`: `High`, `Medium`, or `Low`
 - `Selection note`: `activate as-is`, `split first`, or `defer`, with one short reason
 - `Main drivers`: the 2-4 factors driving the estimate
 
-Interpretation rule for `% usage limit`:
+Interpretation rule for NEL bucket:
 
-- it is an approximate share of a meaningful AI-assisted execution budget under the current repo workflow
+- it is an approximate measure of engineering change volume (insertions + deletions, whitespace-ignored) for the mission's merge diff against the primary branch
 - it may reflect scope breadth, trust-tier sensitivity, validation burden, review/handoff overhead, context churn, and cross-surface coupling
 - it is a selection aid, not a delivery promise or pseudo-scientific schedule estimate
+- NEL is computed by the reusable `nels` module (`lib/core/nels.js`) which excludes workflow/bookkeeping files per ADR 0047
 
 Default activation guidance:
 
-- `0-25%` or `25-50%`: normally safe to activate as-is when confidence is not low
-- `50-75%`: split first unless the mission is unusually high leverage and already sharply bounded
-- `75-100%` or `100%+`: defer or split before activation under normal conditions
+- `Small (0–80)`: normally safe to activate as-is when confidence is not low
+- `Medium (81–235)`: split first unless the mission is unusually high leverage and already sharply bounded
+- `Large (235+)`: defer or split before activation under normal conditions
 - if confidence is `Low`, keep refining instead of treating the estimate as reliable enough for pickup
 
 Current rollout blocker:
@@ -84,14 +85,14 @@ Current rollout blocker:
 
 - The workflow now distinguishes "not ready yet" from "ready, but not yet started."
 - Mission comparison becomes more deliberate because shovel-ready candidates can be compared without immediately activating them.
-- The `% usage limit` signal is lightweight enough to aid selection without creating a second planning system.
+- The NEL bucket signal is lightweight enough to aid selection without creating a second planning system.
 - `MISSION.md` remains the detailed execution contract while Backlog stays the current-state surface.
 
 ### Negative
 
 - The lifecycle gains one more state conceptually, so operators must learn one more transition.
 - Some older workflow docs and historical artifacts will continue to mention the earlier five-state model.
-- `% usage limit` still depends on judgment and may drift if agents stop recording the main drivers behind the estimate.
+- NEL bucket estimates still depend on judgment and may drift if agents stop recording the main drivers behind the estimate.
 
 ## Alternatives Considered
 
@@ -132,4 +133,5 @@ Negative:
 ## Links
 
 - [ADR 0026](0026-ai-task-state-and-agent-recovery-surface.md)
+- [ADR 0047: Per-Mission Change Size Budget](0047-per-mission-change-size-budget.md) — NEL bucket definitions and exclusion globs
 - [Mission](../missions/2026/task-024-mission-complexity-estimation/MISSION.md)

package/docs/adr/0036-mission-sizing-and-dependency-wave-heuristics.md

@@ -18,21 +18,21 @@ Introduce three sizing tracks and a dependency-wave planning heuristic.
 
 ### 1. Sizing Tracks
 
-| Track | Scope | Process | Agent Budget |
-|-------|-------|---------|--------------|
-| **Quick Flow** | < 3 files, < 2h estimated, or docs-only. | Minimal `MISSION.md` (Goal, Why Now, Refinement Signals, Gates). Skip detailed checkpoints if straightforward. | < 10% of agent limit |
-| **Full Method** | > 3 files, complex logic, or > 2h. | Standard `MISSION.md` with all sections. Detailed checkpoints. Mandatory external review (C2 review remains required for sensitive scopes per AGENTS.md). | 10-50% of agent limit |
-| **Multi-Wave** | Very large, high risk, or complex dependencies. | Split into multiple `Full Method` missions (waves). | Total > 50% (requiring split) |
+| Track | Scope | Process | NEL Budget |
+|-------|-------|---------|------------|
+| **Quick Flow** | < 3 files, < 2h estimated, or docs-only. | Minimal `MISSION.md` (Goal, Why Now, Refinement Signals, Gates). Skip detailed checkpoints if straightforward. | 0–80 NEL (Small) |
+| **Full Method** | > 3 files, complex logic, or > 2h. | Standard `MISSION.md` with all sections. Detailed checkpoints. Mandatory external review (C2 review remains required for sensitive scopes per AGENTS.md). | 81–235 NEL (Medium) |
+| **Multi-Wave** | Very large, high risk, or complex dependencies. | Split into multiple `Full Method` missions (waves). | 235+ NEL (Large) |
 
-### 2. "Too Large" Thresholds by Agent
+### 2. "Too Large" Thresholds
 
-A mission is "Too Large" if its `Estimated agent % usage limit` exceeds the following thresholds per session/work-unit:
+A mission is "Too Large" for single-wave execution when its predicted NEL bucket exceeds the following thresholds:
 
-- **Claude**: > 50% of daily limit.
-- **Codex**: > 25% of weekly limit.
-- **Gemini**: > 50% of the reasonable session/context budget (approx. 50k-100k tokens for execution).
+- **Small (0–80 NEL)**: suitable for Quick Flow; no decomposition needed.
+- **Medium (81–235 NEL)**: suitable for Full Method; consider splitting if dependencies are complex.
+- **Large (235+ NEL)**: MUST be split into dependency waves before activation.
 
-Missions exceeding these thresholds MUST be split into dependency waves before activation.
+These thresholds are derived from empirical terciles in task-1355 data (n=29 missions) as documented in ADR 0047. Missions exceeding these thresholds MUST be split into dependency waves before activation.
 
 ### 3. Dependency-Wave Heuristic
 
@@ -70,10 +70,12 @@ Agents MUST assign themselves to a task in `Backlog.md` before beginning work in
 - Improved visibility of parallel work via mandatory assignment.
 
 ### Negative
+
 - Requires upfront estimation effort during the `draft` phase.
-- Agents must learn to judge their own usage limits accurately.
+- Agents must estimate NEL buckets, which requires understanding the exclusion rules from ADR 0047.
 
 ## Links
 - [ADR 0032](0032-mission-refinement-state-and-usage-budget-signals.md)
+- [ADR 0047: Per-Mission Change Size Budget](0047-per-mission-change-size-budget.md) — NEL bucket definitions and exclusion globs
 - [MISSION_FLOW.md](../../MISSION_FLOW.md)
 - [AGENTS.md](../../AGENTS.md)

package/docs/adr/0041-integration-pipeline-gates.md

@@ -145,7 +145,7 @@ Option B (Forgejo Actions) would require runner credentials for docker push and
 
 ## Deliverables
 
-1. **Repo-side config:** `config/integration-pipelines.json` with entries for `server`, `auth-server`, `web-client`, `web-e2e`; `web-e2e` carries `run_last: true`
+1. **Repo-side config:** `config/integration-pipelines.json` with entries for `server`, `auth-server`, `web-client`, `web-e2e`; `web-e2e` carries `run_last: true`. Task-1362 added a `lib` entry mapping to `./scripts/verify-local.sh static-analysis` as a required gate for `lib/` changes.
 2. **Change detection:** Compute the set of top-level dirs touched by `mission/<slug>` vs the primary branch
 3. **Dispatch in `scripts/verify-local.sh`:** New `gate_integrate()` function and `integrate` area in the case statement
 4. **`node workflow integrate` preflight:** Calls the new `integrate` area as part of `printIntegrationPreflight`

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/use-cases.md

@@ -57,6 +57,34 @@ Each use case carries the four required parts: **(P) persona/buyer**, **(B) befo
 - **(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 custom 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.
 
+### UC-7 — Review an agent's whole mission as one branch diff, in your own tool or a PR web view
+
+- **(P)** Operator/reviewer who has to read what an AI agent actually changed before approving a merge, and wants it in the diff tool they already trust (delta/difftastic/vimdiff) or a browser PR view — not a wall of inline terminal text.
+- **(B)** *Before:* you reconstruct an agent's work by hand — `git log`, ad-hoc `git diff main`, guessing the base branch, scrolling raw diff through a default pager. *After:* `px diff [<slug>]` resolves the mission worktree and the correct base, computes `primary..HEAD`, and launches your configured specialized diff tool (`git difftool` when `diff.tool` is set, otherwise a non-default `pager.diff`/`core.pager` such as delta or difftastic); when the review provider is Forgejo, the same change is also viewable as a PR in the browser.
+- **(E)** `px diff` is a registered command: `index.js:39` (command list), `:158` (dispatch), `:224` (help text). Implementation: `lib/commands/diff.js:42-43` (base resolution → `primary..HEAD`), `:89-93` (`git difftool` when `diff.tool` configured), `:97-111` (specialized `pager.diff`/`core.pager` path), `:51-68` (rejects plain `less`/`cat`/`more`, accepts delta/difft/diff-so-fancy). Forgejo PR web view: `lib/tools/forgejo.js:170,178` (`getPrStatus` surfaces `pr.html_url`), reached via `lib/review/review-adapter.js:56,83`. Tested: `test/diff.test.js` — `node parallix diff resolves correct target branches`, `node parallix diff detects pager.diff`, `node parallix diff detects core.pager`; Forgejo PR flows in `test/forgejo.test.js`.
+- **(C)** **Confirmed** for the `px diff` mechanic — base resolution and specialized-tool launch are tested code. The Forgejo PR-viewer half is **Partial**: it only renders when the review provider is Forgejo and a Forgejo instance is reachable (`review-adapter.js` no-ops to a "skipped" status otherwise), so position UC-7 as "local mission-branch diff in your own tool, *plus* an optional PR web view when Forgejo is configured."
+
+### UC-8 — Sustain feature-scale mission throughput at roughly the rate of a dedicated AI factory
+
+- **(P)** Operator/buyer judging whether the Parallix workflow actually moves more work than a serial single-agent setup, and how it compares to a purpose-built agent factory.
+- **(B)** *Before:* "AI makes me faster" is a vibe with no denominator. *After:* completed missions are counted directly from `stats.csv`, giving a defensible per-week figure that can be compared like-for-like against both a human baseline and an external automated factory.
+- **(E)** Measured ceiling: **58 completed missions in a 15-day window = ~27 missions/week** (`~3.86/day`), counted from `stats.csv` via `node workflow stats` (`../visualBoard/docs/missions/2026/task-1247/research.md:51-57`). The Q2 normalization shows the acceleration that produced it: P5 total `2.96/day`, P6 total `3.29/day`, with user-value delivery at `0.44/day` (P5) and `0.48/day` (P6) over a `0.28/day` human baseline (`../visualBoard/docs/missions/2026/task-1099/RETROSPECTIVE_Q2_2026.md:18-23`). **Reconciling the operator's ~30/week:** the operator's reported ~30 missions/week is the same completed-mission metric as the measured 58-missions/15-day window (~27/week), reported at the recent peak; it sits just above the highest measured 15-day window and within the sampling error of a 15-day count, so the honest framing is "~27/week measured, ~30/week at recent peak," not a single rounded "30." The like-for-like external comparison: an upstream AI factory (`you-agent-factory`) shipped ~26–35 PRD-scale mission-equivalents/week against Parallix's ~27/week — **roughly parity (~1×) on feature-scale work** (`research.md:70-75`).
+- **(C)** **Partial.** The throughput is real and counted from telemetry, but it is **measured-but-caveated**: the figure is completed-mission throughput (not user-value-only delivery, which is `0.44–0.54/day`), it carried 85% AI-SDLC overhead in P5/P6 and only 7% C2 review coverage (`EVALUATION_SUMMARY.md:66`), and the parity comparison is low-medium confidence (where to draw the PRD/micro-task line — `research.md:75`). Do not state "~30/week" without the ~27/week measured anchor and these caveats.
+
+### UC-9 — Start a mission from a feature branch, not just from main
+
+- **(P)** Developer mid-way through a feature branch who wants to hand a sub-task to an agent without first merging or rebasing onto main, and without the agent's mission branch silently forking from the wrong base.
+- **(B)** *Before:* tools that assume every branch cuts from `main` either refuse to start on a feature branch or cut the agent's branch from the wrong base, so the diff is polluted with unrelated `main` changes. *After:* `draft` detects whatever branch HEAD is on at draft time, records it as the mission's base, cuts the `mission/<slug>` branch from that recorded base, and writes a machine-readable `Base-Branch:` line into MISSION.md so later steps resolve against the right base.
+- **(E)** `lib/commands/draft.js:173-188` (detect the branch HEAD is on; a non-primary feature branch is recorded as the mission base), `:223` (pass `baseBranch: recordedBase` to branch creation), `:411-430` (`ensureMissionBranch` cuts from the recorded base, falling back to `getPrimaryBranch()` at `:428` for a primary/detached launch — byte-identical to legacy single-branch behaviour), `:439-468` (`ensureMissionBaseBranchRecorded` writes/idempotently maintains the `Base-Branch:` line). Primary-branch resolution: `lib/core/mission-utils.js:67-99` (`getPrimaryBranch`). Tested: `test/draft.test.js` — `ensureMissionBranch creates the mission branch from the recorded feature base`, `ensureMissionBaseBranchRecorded inserts a machine-readable Base-Branch line under the title`, `ensureMissionBaseBranchRecorded replaces a stale Base-Branch line in place`.
+- **(C)** **Confirmed** — feature-base detection, the branch cut from the recorded base, and the idempotent `Base-Branch:` recording are all covered by named passing tests. Note this is not a separate code path: it is the *same* draft flow with explicit base-branch resolution, which falls back to primary-branch behaviour when launched from main.
+
+### UC-10 — Catch agent mistakes with your standard QA gates before a human reviews
+
+- **(P)** Lead who knows AI agents introduce lint slips, type errors, and test-hygiene violations, and wants those caught by automated QA *before* burning reviewer attention on them.
+- **(B)** *Before:* an agent's change reaches review with mechanical defects (unused vars, `==` vs `===`, untyped JS, skipped/forced tests) that a human reviewer wastes time flagging. *After:* a configured verification gate runs static analysis as a hard checkpoint — ESLint at `--max-warnings 0`, `tsc --checkJs`, and a test-hygiene scan — so agent-introduced defects fail the gate before review.
+- **(E)** Gate script: `scripts/verify-local.sh:14-44` (`static-analysis` runs ESLint `--max-warnings 0` on `lib/`, `tsc --checkJs --noEmit`, then `test-hygiene.sh`; each stage fails the gate on error), `:47-64` (`docs` subcommand verifies required docs exist). ESLint ruleset enforcing the checks: `.eslintrc.cjs:10-19` (`no-unused-vars`, `eqeqeq`, `no-var`, `valid-typeof`, etc., all `error`). The gate is a configurable adapter command with `{{area}}` substitution and a no-op default so any repo can wire its own runner: `lib/core/verification.js:5-12` (no-op notice), `:26-32` (substitution), `:35` (`runVerificationGate`); this repo wires `npm test` (`workflow.config.json:14`). Tested: `test/verification.test.js` — `runVerificationGate is a no-op pass when no command is configured`, `runVerificationGate executes the configured command via bash`.
+- **(C)** **Confirmed** — the gate script stages, adapter resolution, `{{area}}` substitution, and no-op default are all tested code. UC-10 is the *agent-error-reduction* angle (QA gates catch agent mistakes before review); it is deliberately distinct from UC-5, which is the *CI-adoption* angle (run your existing gate verbatim rather than replumb it).
+
 ---
 
 ## 2. Ranking — top 3 for immediate public positioning
@@ -69,6 +97,8 @@ Ranked by *credibility as a public claim given cited evidence*, each naming the
 | **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.") |
 
+**Re-evaluation with UC-7 through UC-10 (task-1378):** the four new use cases were scored against the top-3 and **none displaces UC-1/UC-2/UC-4.** UC-8 (throughput) is the same measured story as UC-1, not an independent claim — it sharpens UC-1's denominator (~27/week measured, parity with an external AI factory) rather than competing with it. UC-7 (`px diff`/PR view) and UC-10 (QA gates) are Confirmed but are convenience/adoption features whose competing tools (any diff viewer; any CI lint gate) make them weak *public differentiators*. UC-9 (feature-branch start) is Confirmed and fairly distinctive but narrow, and ranks below UC-2's failover control loop on credibility-as-a-public-claim. The table therefore retains UC-1, UC-2, UC-4.
+
 **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)."
@@ -95,6 +125,16 @@ The two weakest use cases and the single strongest objection a skeptical senior
    *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.
 
+### New objections raised by UC-7 through UC-10 (task-1378)
+
+3. **UC-8 (throughput) is UC-1's number wearing a second hat — and "~30/week" inflates it.**
+   *Objection:* "You list a separate 'velocity' use case, but its evidence is the same `58 missions/15 days` figure UC-1 already cites, and you headline the operator's `~30/week` when the measured window is `~27/week`. That's double-counting one result and rounding it up."
+   *How the evidence answers it:* It concedes both points by construction. UC-8 is marked **Partial** and explicitly excluded from the ranking *because* it is the same measured story as UC-1, not an independent claim; the §2 re-evaluation states this. The `~30/week` is presented only alongside the `~27/week` measured anchor (`research.md:51-57`) as a recent-peak report within a 15-day sample's error, never as a standalone number.
+
+4. **UC-10 (QA gates) is just UC-5 (adopt your CI) renamed.**
+   *Objection:* "Both use cases point at the same `verification.js` adapter and `verify-local.sh`. Splitting 'adopt your gate' from 'catch agent errors' is positioning, not capability."
+   *How the evidence answers it:* The mechanism is indeed shared (`lib/core/verification.js:35`, `scripts/verify-local.sh`), and this is stated in UC-10's confidence line. The distinction is the *buyer's reason*: UC-5 sells "you don't have to replumb verification to adopt the workflow"; UC-10 sells "the gate that runs is a defect filter on agent output before review." Same code, two different purchase motivations — which is why UC-10 stays out of the top-3 rather than being claimed as a new mechanism.
+
 ---
 
 ## 5. Limitations & honesty constraints (carried into any downstream positioning)
@@ -102,4 +142,8 @@ The two weakest use cases and the single strongest objection a skeptical senior
 - 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`.
+- **UC-7 (px diff / PR view):** the `px diff` mechanic is fully local and Confirmed, but the browser PR-review half depends on a reachable **Forgejo** instance with the review provider set to forgejo; with any other provider the adapter no-ops to a "skipped" status (`lib/review/review-adapter.js:16`). Position the PR-web-view as conditional, not always-on. `px diff` also requires the operator to have a specialized diff tool configured in Git — it deliberately fails rather than fall back to a plain pager (`lib/commands/diff.js:113-116`).
+- **UC-8 (velocity):** the only permitted throughput figures are `~27/week` measured (`58 missions / 15 days`) and `~0.44–0.54/day` user-value; the operator's `~30/week` may appear **only** as a recent-peak report stated next to the `~27/week` anchor, never alone. It carries every UC-1 caveat (85% AI-SDLC overhead, 7% C2 coverage, different mission-output metrics) and the parity-with-`you-agent-factory` comparison is low-medium confidence (`research.md:75`).
+- **UC-9 (feature-branch start):** this is **not a separate code path** — it is the standard `draft` flow with explicit base-branch resolution that falls back to primary-branch behaviour when launched from main (`lib/commands/draft.js:428`). Do not position it as a distinct "feature-branch mode."
+- **UC-10 (QA gates):** the gate is only as strong as what each repo configures; the default adapter is a documented **no-op pass** (`lib/core/verification.js:5-12`), so "catches agent errors" is true only when a real gate command (like this repo's `npm test` or `verify-local.sh static-analysis`) is wired. It shares its mechanism with UC-5 and must not be claimed as a second, independent capability.
 - 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 ✓).