Skip to content

R1 · Consistency across specs

Done 2026-10-26 · 53 findings: 5 blockers, 33 majors, 15 minors · 0 dropped · 14 questions for Thomas

What changed

  • New review file: docs/reviews/R1-consistency.md. It holds:
    • the 53 findings SR-001 to SR-053, each with quoted passages, a proposal, "Found by" and Status: open;
    • a findings table ranked by severity, then by the number of documents touched;
    • 14 questions for Thomas;
    • 7 proposed spikes, three of them extensions of planned steps T2, T3 and T4.
  • No spec was edited. This is a review round (see the review rules in docs/reviews/README.md).
  • The file was committed on autopilot/integration in ad6bc9b, together with the other W1 review files, the nav entry and map.md.

Why

The specs were written over several days, and names and decisions changed along the way. Before any code, the specs must agree with each other and with the decision log. R1 looks for contradictions, undefined contracts and topics with no owning spec.

Prompt: next-phase.md · R1. It runs as an autopilot step: decision log, 2026-10-26, autopilot. The round reads the specs against the latest decisions, in particular decision 0001 and the MVP scope entry.

Evidence

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

Item Value
Commit read autopilot/integration at 3b209d3; every line number in the file refers to it
Reviewers spec-reviewer, four instances in parallel; all four returned output, none failed
Scopes (a) synthesis + ui-spec; (b) api-and-data-model + admin-and-operations; (c) architecture-plugins-and-packaging + cli-and-shared-libraries + dev-environment-and-testing; (d) checking-scenarios + schedulers-and-monitoring + depictio-ecosystem-reuse. Each scope was also checked against the decision log.
Renames checked maintainer→editor, agent→runner, Settings→Administration, spectio-runner merged into spectio, broker split into tasks/pubsub. Leftovers of the last three are filed as SR-039, SR-040 and SR-049.
Raw output 82 findings, as rated by the reviewers: 8 blockers, 50 majors, 24 minors
Merge duplicates merged into one finding that credits every reviewer. Where two ratings differed, the higher one was kept when the problem touches the 0.1 scope.
Merger's check every quoted passage of every blocker and major was opened at 3b209d3. All reproduced, so 0 findings were dropped.
Earlier rounds findings already open in R12 (UX-) and R8b (DEP-T-) are cited, not repeated

Counts, checked against the file's headings:

$ for s in blocker major minor; do printf "%s " $s; grep -c "^### SR-[0-9]* · $s ·" docs/reviews/R1-consistency.md; done
blocker 5
major 33
minor 15

These match the summary table in the file (total 53, dropped 0) and the merge summary returned by the step's workers.

Exit criterion. R1 is done when its review file exists, so that TRIAGE1 can read it:

$ ls docs/reviews/R1-consistency.md
docs/reviews/R1-consistency.md

The wave W1 exit check in pipeline.yaml also lists docs/reviews/R11-docs.md, which does not exist yet. That file belongs to step R11, not to R1.

Figures and media

None required (review step).

Findings and open questions

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

  1. SR-001 · blocker: no contract for how engines send events to the server. Nothing defines the payload, the run handshake for runs started from a terminal, the ingest credential and scope, or what the plugin does when the server is down. Decision 0001 removed Tower's /trace/create with no replacement. Found by 3 of the 4 reviewers.
  2. SR-002 · blocker: the runner ↔ server protocol has no owner. api §5 says WebSocket; architecture §7.6, admin §3.2 and the log say outbound HTTPS pull. There is no command catalogue and no ack or replay rule. The runner credential rotates in one spec and lives until revoked in another. Found by all 4 reviewers.
  3. SR-003 · blocker: check providers run on the server in three specs and on the runner in three others. This decides the runner's dependencies and whether its 80 MB budget holds.
  4. SR-004 · blocker: spectio.yml has four incompatible shapes and no owner. Proposal: a new checking §12 reference backed by a JSON Schema.
  5. SR-007 · major: phase labels (MVP, 1b, 1c, 2, 3) do not map to release stages (0.1, alpha, beta, 1.0). "1b" means four different things. Proposal: a new dev-env §15 "what ships in which stage" table. The WES facade's four dates are SR-010.

The fifth blocker, SR-005, is two tables both named tasks. The fix is a rename.

Questions for Thomas. The full wording, with the reviewers' recommendations, is in the review file. In short:

# Topic Question
1 WES facade (SR-010) 0.1, private alpha, public beta, or unscheduled? All reviewers say not in 0.1. Same question for MCP and OIDC.
2 Stage contents (SR-007) Kubernetes launcher in 0.1 or the alpha? Are Postgres and OIDC needed for the design-partner alpha?
3 Observed runs (SR-001) Are terminal-started runs in 0.1? Long-lived user token with an ingest scope, or a wrapper (spectio run nextflow …) that gets a run token?
4 Runner transport (SR-002) WebSocket with long-poll fallback, or HTTPS long-poll / SSE? Does an EMBL proxy or SSH-tunnel constraint decide it?
5 Snakemake steering (SR-008) Command-line head job (--until, --forcerun, relaxing the "no subprocess" constraint) or the Python API inside the workflow's environment?
6 Nextflow boundary (SR-011) Confirm that the generated ext.when config is the only mechanism and that --stage cooperation is dropped.
7 Pause (SR-018) Is "stop now, keep the cache" in scope next to "pause after stage"? Is either needed in 0.1?
8 Roles (SR-025) May a reviewer decide gates without being allowed to launch? This decides ladder vs capability flags.
9 Project visibility (SR-029) Drop the group value and use depictio's two-value model?
10 Shared clusters (SR-014) One runner per user, or a site service account?
11 Checks in 0.1 (SR-023) Only Spectio's own bindings, or depictio catalogue recipes on the runner too?
12 Version skew before 1.0 (SR-022) May runners lag the server by one minor, at the cost of a backward-compatible API during 0.x?
13 Restore (SR-030) Runs launched after the backup: adopt or cancel by default?
14 Single-user mode (SR-031) Supported on shared login nodes, or laptops and service nodes only?

Next. TRIAGE1 sorts these findings with the triage policy. It moves the questions it cannot settle to the inbox. APPLY1 then changes the specs and adds the decision-log entries.