R3 · End-to-end journeys

Done 2026-10-27 · 27 findings: 7 blockers, 18 majors, 2 minors · 10 merged · 6 questions for Thomas · 8 spikes ranked

The four 0.0.1 journeys as rows of steps; a tick marks a specified step, a pin marks the finding that breaks it (red blocker, amber major, grey minor).

What changed

• New review file: docs/reviews/R3-journeys.md. It holds:
  • the journeys walked: the four journeys as 75 numbered steps. Each step ends with the spec section that covers it, or with the finding that reports the gap;
  • 27 findings (SR-054 to SR-067, CH-041 to CH-051, UX-243, UX-249, UX-250). Each has the spec passages it quotes, a proposal, "Found by" and Status: open;
  • a findings table ranked by severity, then by the number of documents touched, with a one-line stub for each of the 10 merged IDs;
  • cited, not repeated: earlier findings from R1, R2, R4, R7 and R12 that the reviewers cited instead of raising again;
  • 6 questions for Thomas, each with options and a recommendation;
  • 8 proposed spikes, ranked by risk removed per hour.
• Round map embedded at the top of the review file's summary and above. Script: tools/diagrams/r3_journeys_map.py, first committed in b2804e4, redrawn in 275054e with the merged counts and primary IDs only (the pins for UX-241, SR-060 and UX-244 are gone; SR-060's step now carries CH-042). After the docs review it was redrawn again, in the autopilot(R3) commit: it pins every blocker and major, and a key under the journeys defines the three severities in the pin colours.
• No spec was edited. This is a review round (see the review rules in docs/reviews/README.md). The file proposes one new subsection, "Local launcher: detach, adopt, exit" under schedulers §3.1 (CH-041). Its number is assigned at apply time.
• The review file, the redrawn figure and the mkdocs.yml nav entry "R3: journeys" were committed in 275054e.

Why

Earlier rounds read the specs topic by topic. R3 walks them in the order a user meets them, for the 0.0.1 cut only (mvp-0.0.1.md): one user, no sign-in, engines on the same machine, SQLite, spectio serve --with-runner. Every step that has no screen, endpoint, event, state or error is a gap that would stop the first release.

Prompt: next-phase.md · R3. The 0.0.1 scope comes from the decision log, 2026-10-27, first version is 0.0.1. The round map follows the decision log, 2026-10-27, a sketch for every step.

Evidence

How the round ran (from the round's header in the review file):

Item	Value
Commit read	autopilot/integration at e22e376; every line number in the file refers to it
Reviewers	three in parallel; all returned output, none failed
spec-reviewer	journeys 1 and 2 (Nextflow with a passing gate; Snakemake with a failing gate and a relaunch)
constraints-hunter	journeys 3 and 4 (a failing task and Resume; a server restart mid-run)
ux-reviewer	all four journeys. It rendered the 11 boards of the 0.0.1 map plus RunFailed, WorkflowImport and WorkflowOverlay with tools/canvas/render.js (renders in /tmp/r3-ux/, not kept)
External code read	none in this round; facts about Nextflow, Snakemake and systemd keep the sources the specs or earlier rounds give, or are marked [to be validated]
Raw input	37 findings: spec-reviewer 15 (SR-054 to SR-068), constraints-hunter 11 (CH-041 to CH-051), ux-reviewer 11 (UX-241 to UX-251)
Merge	10 findings absorbed into a primary, which takes their evidence and "Found by". 0 dropped, 0 downgraded. Result: 37 − 10 = 27
Merger's check	every quoted passage of the blockers and majors was re-opened at e22e376: 25 primaries plus 9 absorbed, 34 in all. All reproduced. 4 citations corrected: SR-055, UX-246 (now in CH-041), CH-044, UX-250; the CH-046 citation was confirmed

Counts, checked against the file's headings and tables:

$ for s in blocker major minor; do printf "%s " $s; grep -cE "^### (SR|CH|UX)-[0-9]+ · $s ·" docs/reviews/R3-journeys.md; done
blocker 7
major 18
minor 2
$ grep -c "| merged into " docs/reviews/R3-journeys.md
10
$ grep -oE "^\| (SR|CH|UX)-[0-9]+ \|" docs/reviews/R3-journeys.md | cut -c3-4 | sort | uniq -c
     11 CH
     15 SR
     11 UX
$ sed -n "/^## Questions for Thomas/,/^## Proposed spikes/p" docs/reviews/R3-journeys.md | grep -cE "^[0-9]+\. "
6
$ sed -n "/^## Proposed spikes/,\$p" docs/reviews/R3-journeys.md | grep -cE "^\| [0-9]+ \|"
8

The findings table has 37 rows, one per raw ID (SR 15, CH 11, UX 11). That matches the raw input. 27 open rows plus 10 merged rows match the summary table (total 27, merged 10, dropped 0).

Journey steps, specified or not:

$ sed -n "/^## Journeys walked/,/^## Findings table/p" docs/reviews/R3-journeys.md > /tmp/j.md
$ grep -cE "^[0-9]+\. " /tmp/j.md
75
$ grep -cE "^[0-9]+\. .*GAP →" /tmp/j.md
61
$ grep -E "^[0-9]+\. " /tmp/j.md | grep -vc "GAP →"
14

61 of the 75 steps (journeys of 18, 16, 20 and 21 steps) end on a gap. None of the four journeys can be finished from the specs as written.

Corrected and confirmed citations, re-checked by doc-writer at e22e376:

$ git show e22e376:docs/specs/architecture-plugins-and-packaging.md | sed -n 331p
- `spectio serve --with-runner` also starts a local runner in the same process, which is the default in personal mode.
$ git show e22e376:docs/specs/synthesis.md | grep -nE "^## 5ter\.|^### 6\. Launcher|^## 6\."
218:## 5ter. Implementing pause, check and resume
278:### 6. Launcher
284:## 6. Results visualisation
$ git show e22e376:docs/specs/architecture-plugins-and-packaging.md | grep -c "whichever comes first (the bound the ingest contract sets"
1
$ git grep -l RunsCompare e22e376 -- "design/ui-canvas/*.dc.html"
e22e376:design/ui-canvas/Coverage.dc.html
e22e376:design/ui-canvas/RunFailed.dc.html
e22e376:design/ui-canvas/RunLiveChecks.dc.html
e22e376:design/ui-canvas/RunOutputs.dc.html
$ git show e22e376:docs/specs/schedulers-and-monitoring.md | grep -no "an OOM-killed head ends without \`onFlowComplete\`"
64:an OOM-killed head ends without `onFlowComplete`
$ git show e22e376:docs/specs/schedulers-and-monitoring.md | sed -n 62p
### 3.1 Head job

• The SR-055, UX-246, CH-044 and UX-250 corrections reproduce.
• CH-046 is confirmed: the quote "an OOM-killed head ends without onFlowComplete" is at l.64 under §3.1 Head job. The merge notes had first marked it missing; the review file cites it next to the §3.5 row. The finding stands: that sentence is about the HPC head job, and nothing says what the local launcher does when a head ends with no terminal event.

Exit criterion. R3 is done when its review file exists, so that TRIAGE2 can read it (writes in pipeline.yaml):

$ ls docs/reviews/R3-journeys.md
docs/reviews/R3-journeys.md
$ wc -l docs/reviews/R3-journeys.md
870 docs/reviews/R3-journeys.md

The wave W2 exit check is python3 tools/docs/check.py. Its result for this page is under Findings and open questions.

Figures and media

• Round map (sketch pair, at the top of this page and of the review file's summary): docs/assets/diagrams/r3_journeys_map_{light,dark}.{svg,png}, from python3 tools/diagrams/r3_journeys_map.py (listed in docs/assets/media.yaml). Every blocker and major is pinned on the step it hits; minor UX-249 is only in the findings table.
• No screenshots or casts: a review step needs only the round map (documentation-system §3.1). The ux-reviewer's board renders stayed in /tmp/r3-ux/.

Findings and open questions

The five findings that matter most (the review file's summary explains the choice):

1. CH-042 · blocker (absorbs SR-060): the run state machine. A gated launch ends normally, so the run is marked succeeded and never reaches its gate. failed is terminal, yet the UI offers Resume on it.
2. SR-062 · blocker (absorbs UX-242): "relaunch with changed parameters" at a failed gate is two incompatible flows, one run or two runs, and no 0.0.1 screen draws either.
3. SR-057 and SR-058 · blockers: the rnaseq gate cannot exist and cannot be evaluated. rnaseq declares no stages and 0.0.1 has no overlay path. After stage 1, MultiQC has not run, and the default install has no MultiQC.
4. CH-041 · blocker (absorbs UX-246): the engine head is a child of spectio serve. A restart can kill it. If it survives, nothing finds it again, reads its exit code or stops a second head from starting.
5. SR-054 and SR-055 · blockers: the ingest contract (api §14) and the local environment and in-process runner are parked as "not needed for 0.0.1", yet no bridge and no launch can work without them.

Questions for Thomas. These go to TRIAGE2 first. TRIAGE2 then copies the ones it cannot settle to inbox.md. The full wording, options and recommendations are in questions for Thomas.

#	Refs	Question	Reviewers recommend
1	SR-062, CH-042, SR-063, UX-243	At a failed gate, and after a failure, does the same run continue, or is a child run created?	a child run through :relaunch for both; ux-reviewer proposed the same run (go_back) for the gate
2	SR-059	When every check passes, does the gate wait for a person or continue by itself?	always create a gate row; decide.auto_approve: when_checks_pass opt-in; default "wait for a person" in 0.0.1
3	SR-057, SR-056	How does nf-core/rnaseq get its stages and gate?	a built-in rnaseq overlay plus a spectio.yml passed at launch; the editor UI later
4	SR-058	Is MultiQC in the default install?	document spectio[server,checks]; a missing value gives verdict error
5	SR-067, SR-055, SR-061	Who installs Java, Nextflow and Snakemake, and how is nf-spectio delivered?	the user installs the engines; nf-spectio ships in the wheel [to be validated]
6	SR-054, CH-041	May inbox #11 be split so the driven-run part of api §14 is written for 0.0.1? Do heads keep running when spectio serve stops?	split #11; heads keep running

Proposed spikes. The top three of the ranked list are head survival and adoption across a server stop (CH-041, CH-046), Resume semantics on both engines (CH-042, CH-043, CH-050, SR-063), and rnaseq gated after alignment (SR-058, SR-057). Each costs half a day.

Overlap with earlier rounds. The table of earlier findings cited, not repeated has 33 rows; they are not counted in the 27. Where an R3 finding adds a 0.0.1 angle (for example SR-054 to R1 SR-001, CH-041 to R4 CH-028), it carries a Related line, so TRIAGE2 can sort the pair together.

Open on this page.

• review is null until doc-reviewer scores the page. Until then, python3 tools/docs/check.py reports "a done step needs review: approve" for this page.

Next. TRIAGE2 sorts the R3 and R6 findings with the triage policy. APPLY2 then changes the specs and adds the decision-log entries.