/academic-pipeline

Pipeline State Machine v2.0 — Complete Definition

This document defines all legal states, transition conditions, transition actions, and exception handling for academic-pipeline v2.0.

State Definitions

Stage States

Pipeline Global States

State Transition Diagram (ASCII)

                        +-------------+
                        | INITIALIZING|
                        +------+------+
                               |
                    [Detect entry point & materials]
                               |
         +----------+----------+----------+----------+
         |          |          |          |          |
         v          v          v          v          v
    +--------+ +--------+ +--------+ +--------+ +--------+
    |Stage 1 | |Stage 2 | |Stg 2.5 | |Stage 3 | |Stage 4 |
    |RESEARCH| | WRITE  | |INTEGRIT| | REVIEW | | REVISE |
    +---+----+ +---+----+ +---+----+ +---+----+ +---+----+
        |          |          |          |          |
   [checkpoint]   [checkpoint]   |     [checkpoint]  |
        |          |          |          |          |
        v          v          v          v          v
   +--------+ +--------+ +---+----+    |          |
   |Stage 2 | |Stg 2.5 | |PASS?   |    |          |
   | WRITE  | |INTEGRIT| +---+----+    |          |
   +---+----+ +---+----+     |         |          |
                         +----+----+    |          |
                         |         |    |          |
                        Yes       No    |          |
                         |     [Fix]    |          |
                         |   [Re-verify]|          |
                    [checkpoint]   |    |          |
                         |         |    |          |
                         v         |    |          |
                    +--------+     |    |          |
                    |Stage 3 | <---+    |          |
                    | REVIEW |          |          |
                    +---+----+          |          |
                        |               |          |
                   [DECISION]           |          |
                        |               |          |
              +---------+---------+     |          |
              |         |         |     |          |
            Accept    Minor     Major   |          |
              |       Revision  Revision|          |
              |         |         |     |          |
              |    [checkpoint]  [checkpoint]      |
              |         |         |     |          |
              |         v         v     |          |
              |    +--------+ +--------+|          |
              |    |Stage 4 | |Stage 4 ||          |
              |    | REVISE | | REVISE ||          |
              |    +---+----+ +---+----+|          |
              |        |          |     |          |
              |   [checkpoint]   [checkpoint]      |
              |        |          |     |          |
              |        v          v     |          |
              |    +--------+ +--------+           |
              |    |Stg 3'  | |Stg 3'  |           |
              |    |RE-REV. | |RE-REV. |           |
              |    +---+----+ +---+----+           |
              |        |          |                 |
              |   [DECISION]  [DECISION]            |
              |        |          |                 |
              |     Accept      Major               |
              |     /Minor        |                 |
              |        |     [checkpoint]           |
              |        |          |                 |
              |        |          v                 |
              |        |     +--------+             |
              |        |     |Stg 4'  |             |
              |        |     |RE-REVIS|             |
              |        |     +---+----+             |
              |        |          |                 |
              |   [checkpoint]  [checkpoint]        |
              |        |          |                 |
              v        v          v                 |
         +----+--------+----------+-----+           |
         |     Stage 4.5                |           |
         |   FINAL INTEGRITY            |           |
         +----------+------------------+           |
                    |                               |
               [PASS? Zero issues]                  |
                    |                               |
              +-----+-----+                         |
              |           |                         |
             Yes         No                         |
              |        [Fix]                         |
              |      [Re-verify]                     |
         [checkpoint]     |                         |
              |           |                         |
              v           |                         |
         +--------+       |                         |
         |Stage 5 | <-----+                         |
         |FINALIZE|                                 |
         +---+----+                                 |
             |                                      |
        [checkpoint]---[decline Stage 6]---+        |
             |                             |        |
             v                             |        |
         +--------+                        |        |
         |Stage 6 |                        |        |
         |PROCESS |                        |        |
         |SUMMARY |                        |        |
         +---+----+                        |        |
             |                             |        |
   [terminal acknowledgement]              |        |
             |                             |        |
             v                             |        |
        +---------+                        |        |
        |COMPLETED| <----------------------+        |
        +---------+                                 |

Legal State Transitions

Normal Flow Transitions

Experiment intake (#925). A run through Stage 1 asks the experiment intake question at the Stage 1 checkpoint; a run that enters or resumes after Stage 1 asks it at entry. No Stage 2 writer or integrity gate is dispatched before the declaration is recorded. When the question is skipped, its wording, and how the answer is recorded: ../agents/pipeline_orchestrator_agent.md § Experiment Intake Question (#925).

Special Flow Transitions

Prohibited Transitions (Illegal)

Stage 5 and Stage 6 Boundary Semantics (#528)

The two boundaries below were under-specified before v3.17 (different runtimes could resolve them differently). This section is the authority; SKILL.md and pipeline_orchestrator_agent.md mirror it.

Stage 5 boundary semantics

"Before finalization (Stage 5): always MANDATORY" refers to exactly ONE checkpoint: the Stage 5 entry gate — the checkpoint between Stage 4.5 PASS and the Stage 5 dispatch. It is MANDATORY because it carries the finalization decisions:

• explicit confirmation to proceed to finalization (no auto-advance);
• the finalization-format decision: citation style (APA 7.0 / Chicago / IEEE, ...) — the "Stage 5 finalization format" pending decision the passport-reset machinery records at this boundary.

Transition state: awaiting_confirmation → on user confirmation → Stage 5 in_progress.

#660 and #672 surface inside this same one checkpoint, after the same exact Stage 4.5 PASS and before the confirmation. The orchestrator runs #660 first and #672 second against the identical accepted-draft artifact ID/SHA-256. They do not create a second checkpoint or transition state. A schema-valid #660 degraded artifact (exit 1) is preserved; a #672 failure writes no carrier and records only bounded ADVISORY_UNAVAILABLE:<CODE>. Neither result blocks/delays confirmation, changes Stage 4.5, adds remediation routing, or changes Stage-5 dispatch.

Any manuscript revision stales both carriers and returns through integrity before the fixed #660-then-#672 sequence reruns on the new accepted bytes. Reusing only one old carrier is invalid handoff cargo, not a new state-machine branch.

Other confirmations near Stage 5 are NOT this MANDATORY boundary:

1. The in-stage interactions of the Stage 5 output process — the "Need LaTeX?" question (Step 3) and the content confirmation before the final PDF (Step 4) — are part of Stage 5 execution, not pipeline checkpoints; they are asked during the stage, never at the gate.
2. The Stage 5 completion checkpoint (Final Paper delivered, before Stage 6) follows the global stage-completion rule: it is a FULL checkpoint — never SLIM, because final-deliverable acceptance must not be downgraded — but it is not on the MANDATORY list.

Stage 6 terminal semantics

Stage 6 is a non-mandatory stage (it is absent from the orchestrator's non-skippable list). At the Stage 5 completion checkpoint the user may decline it: Stage 6 is marked skipped and the pipeline still terminates completed (the Final Paper was already produced at Stage 5).

When Stage 6 runs, its completion is the pipeline's terminal checkpoint:

1. After delivering the Process Record (MD + PDF per the user's language choice), the orchestrator prompts for a terminal acknowledgement.
2. Terminal acknowledgement vocabulary: finish / end / done / confirm, or an unambiguous natural-language equivalent that accepts the deliverables. Change requests (the other language version, content corrections) keep Stage 6 in_progress — they are not acknowledgements.
3. On acknowledgement: state_tracker marks Stage 6 completed and sets the pipeline global state to completed. This is the terminal transition — there is no next stage.
4. After completed, no stage transition is legal (see Prohibited Transitions). New requests start a new pipeline run or a targeted single-skill invocation (mid-entry).

Checkpoint decision provenance

Every checkpoint decision, terminal acknowledgement, override, consent grant, and authorization input in this state machine exists only when it appears in a user turn. A subagent report, a hook or tool result, a template's default branch, an orchestrator-written checkpoint summary, or a paraphrase of an earlier turn is never the user's decision; a checkpoint whose decision has not appeared in a user turn is still open. Re-transmission to a subagent quotes the user's words (or the exact deterministic authorization artifact) and never widens them. Where a deterministic authorization artifact exists (the #670 integrity-correction authorization, the /ars-mark-read scope) it is the enforced form of this rule; elsewhere the rule is prompt-level. Mirrored operationally in pipeline_orchestrator_agent.md § Checkpoint authority fidelity; the risk is indexed as R11 in docs/RISK_REGISTER.md.

Run ledger (#887). When the run has a passport file, the orchestrator appends each checkpoint's opening and the user's answer in their exact words, as they happen, to the run ledger beside the passport (<passport-stem>_run_ledger.yaml, written by scripts/run_ledger.py), with the other records its mirror lists. After compaction, on resume, and after a subagent return, a decision that neither the ledger records in the user's words nor a user turn in the session shows is still open. The ledger records decisions; it never creates one, so an entry written without a user turn is not a decision (R11). Mirrored in pipeline_orchestrator_agent.md § Run ledger and handoff check; the loss risk is indexed as R12.

Post-terminal adjudication-activity side channel (#673)

The ordinary state machine is authoritative and always terminates first. A completed run durably records Stage 6 with status completed or skipped as defined above. An aborted run durably records its first replayable terminal stage. The closed replayable activity vocabulary is Stage 1, 2, 2.5, 3, 3-prime, 4, 4-prime, 4.5, 5, and 6; there is no Stage 0.

Only after that terminal write succeeds, and only for an explicitly selected local store, may the orchestrator invoke the state tracker's #673 post-terminal sequence. It passes explicit state/artifact-root paths plus the explicit five-row pending_adjudication_activity_bindings[] value to seal_terminal_inventory(state_path, artifact_root, pending_bindings). Pending captured artifact bindings carry id, role, group id, artifact_group_stage, and relative path but no hash; the helper computes raw hashes. Non-applicable/unavailable rows carry empty artifacts and a closed reason. The helper neither reads the pending field itself nor infers or scans for sources.

The helper seals the exact root adjudication_activity_sources inventory while leaving terminal state, stage, and status byte-semantically unchanged. The terminal file's root run_id plus that sealed root inventory are exact source/run authority; pending rows are not. build-input can project only the sealed inventory and cannot accept caller-reported hashes. Idempotent append and optional render follow. Any post-terminal failure is advisory, creates no substitute record, and cannot change the already-durable terminal state.

This side channel is never a legal transition, precondition, gate, verdict, checkpoint input, passport/handoff/Process Record field, or model/observer/ compliance input. It uses no live model, judge, eval, network/API, ambient clock, directory scan, or glob. Producer details are single-homed in ../agents/state_tracker_agent.md § "Adjudication-activity metadata".

Material Dependency Matrix

Exception State Handling

Timeout

If a stage shows no progress for an extended period (e.g., Socratic mode exceeds 15 rounds without convergence):

1. state_tracker marks the stage as stalled
2. orchestrator provides options:
   • Switch mode (socratic -> full)
   • Narrow scope
   • Skip this stage (non-mandatory stages only)

Missing Materials

If required materials are found missing during transition:

1. state_tracker reports the material gap
2. orchestrator suggests returning to the stage that produces that material
3. User can choose: backfill / skip (at own risk, but cannot skip integrity checks)

Integrity Check FAIL Loop

If Stage 2.5 or 4.5 corrections exceed 3 rounds without passing:

1. List all unverifiable items
2. User decides:
   • Manually handle unverifiable items
   • Remove unverifiable citations
   • Continue to next stage (with "partially unverified" warning)

Session Interruption

If the user leaves and returns:

1. orchestrator displays Progress Dashboard
2. Confirm whether to continue from breakpoint
3. Check if any outdated materials need refreshing

Revision Loop Rules (v2.0)

Simplified Revision Cycle

v2.0's revision cycle is simpler and more explicit than v1.0:

Stage 3 (First REVIEW)
  -> Decision: Accept -> Stage 4.5
  -> Decision: Minor/Major -> Stage 4
      -> Stage 4 (REVISE)
          -> Stage 3' (RE-REVIEW, verification)
              -> Decision: Accept/Minor -> Stage 4.5
              -> Decision: Major -> Stage 4' (last revision)
                  -> Stage 4.5 (go directly to final verification, no return to review)

Maximum 1 round of RE-REVISE, no infinite loops.
Unresolved issues -> Acknowledged Limitations.

Differences from v1.0

Reset-boundary transitions (v3.6.3, flag-gated)

When ARS_PASSPORT_RESET=1, every FULL checkpoint carries an implicit state transition to a terminal awaiting_resume state. The next stage only starts when a new session posts resume_from_passport=<hash>.

Transition semantics:

Stage N [working]
  -> FULL checkpoint
    -> [flag OFF]  Stage N+1 [working]           (pre-v3.6.3 continuation)
    -> [flag ON]   append boundary entry -> awaiting_resume
         -> resume_from_passport=<hash>
              -> append resume entry (consumes_hash=<hash>)
              -> Stage N+1 [working]              (fresh session, passport-loaded)

Iron rules:

• awaiting_resume is not persisted in state_tracker; it is computed from the passport ledger. A boundary entry with hash H is awaiting resume iff no later resume entry in reset_boundary[] carries consumes_hash == H. Single pass over the ledger, no out-of-band state.
• systematic-review under flag ON cannot transition Stage N → Stage N+1 without a fresh-session resume. In-session continuation is refused.
• Other modes under flag ON allow in-session continuation as a fallback, but the orchestrator must still load Stage N+1 input strictly from the passport (no replay of prior turns).
• SLIM checkpoints never enter awaiting_resume.
• MANDATORY checkpoints enter awaiting_resume when they are also FULL and flag is ON. Integrity gates remain MANDATORY; the reset does not downgrade them. The ### Resume Instruction subsection emitted alongside [PASSPORT-RESET: ...] carries the passport file path and resume command — it does NOT carry the user decision prompt. The decision prompt happens on resume, after the fresh session loads the passport (see next rule).
• If a boundary entry carries pending_decision, next is advisory only. The user's branch choice happens AFTER resume_from_passport=<hash> in the fresh session, never in the reset checkpoint itself. The orchestrator re-prompts the user in the new session before transitioning to any Stage N+1. The resume entry records the chosen branch via chosen_branch. Actual routing comes from the matched option's next_stage/next_mode; next is a fallback default only.
• pending_decision stays authoritative for the reset path when the run ledger (#887) also records the checkpoint. The ledger's opened entry names the boundary hash (reset_boundary_hash), and the answer closes both: the resume entry that consumes that hash records it, and so does the ledger's closing entry for the same checkpoint.

See passport_as_reset_boundary.md for the full protocol.