exekiel179/psyclaw/academic-pipeline

Academic Pipeline v3.21.1 — Full Academic Research Workflow Orchestrator

A lightweight orchestrator that manages the complete academic pipeline from research exploration to final manuscript. It does not perform substantive work — it only detects stages, recommends modes, dispatches skills, manages transitions, and tracks state.

Routing discipline (v3.9.2): see .claude/CLAUDE.md "Routing Discipline (v3.9.2)" + shared/references/intent_clarification_protocol.md for cross-skill routing rules. This skill assumes routing has already settled — ambiguous cross-phase materials should have been clarified upstream.

v3.6.3 (opt-in): Set ARS_PASSPORT_RESET=1 to promote FULL checkpoints to context-reset boundaries. Use resume_from_passport=<hash> in a fresh session to continue from the recorded stage. See `references/passport_as_reset_boundary.md`.

v3.8 (opt-in): Set ARS_CLAIM_AUDIT=1 to enable the L3 claim-faithfulness audit gate at the Stage 4 → Stage 5 transition. When the flag is set, the orchestrator dispatches claim_ref_alignment_audit_agent after the v3.7.1 Cite-Time Provenance Finalizer and before formatter_agent's hard gate. The audit emits claim_audit_results[] + uncited_assertions[] + claim_drifts[] + constraint_violations[] + audit_sampling_summaries[] aggregates per the 8-row matrix; HIGH-WARN classes gate-refuse output via the formatter REFUSE rules 6-10. Default OFF for v3.8.0 — ramp-on plan deferred to post-calibration evidence (spec §5 mode flag rationale). See agents/claim_ref_alignment_audit_agent.md and the orchestrator §3.6 prose.

v2.0 Core Improvements:

1. Mandatory user confirmation checkpoints — Each stage completion requires user confirmation before proceeding to the next step
2. Academic integrity checks — After paper completion and before review submission, run the declared reference, registered-claim, and reported-data checks; expose denominators, sampling, unknown states, and blocking verdicts
3. Two-stage review — First full review + post-revision focused verification review
4. Final integrity check — After revision completion, rerun the final-check contract from fresh inputs; 100% applies only where the named registered population is explicitly complete
5. Auditable — Version, hash, and retain workflow artifacts; deterministic checks are replayable, while generative outputs are not promised byte-identical
6. Process documentation — Stage 6 generates a "Paper Creation Process Record" PDF documenting the human-AI collaboration history (delivered before the terminal acknowledgement that completes the pipeline)

Quick Start

Full workflow (from scratch):

I want to write a research paper on the impact of AI on higher education quality assurance

--> academic-pipeline launches, starting from Stage 1 (RESEARCH)

Mid-entry (existing paper):

I already have a paper, help me review it

--> academic-pipeline detects mid-entry, starting from Stage 2.5 (INTEGRITY)

Revision mode (received reviewer feedback):

I received reviewer comments, help me revise

--> academic-pipeline detects, starting from Stage 4 (REVISE)

Resume from passport (cross-session context reset, opt-in):

resume_from_passport=<hash> [stage=<n>] [mode=<m>]

--> Loads the Material Passport (Schema 9), locates the kind: boundary entry matching <hash>, and confirms it has no later kind: resume entry consuming it. If pending_decision is set, the decision prompt fires first to capture the user's branch choice for the audit ledger; the prompt is never skipped, even when the user supplies stage=. After the prompt (or immediately if no pending_decision), the next stage is determined by: (a) stage=<n> CLI override if provided, else (b) the matched option's next_stage, else (c) the next field recorded in the boundary entry. CLI stage=/mode= overrides win over option routing.

• Gate (emit): ARS_PASSPORT_RESET=1 must be set in the emitting session. Without the flag, no kind: boundary entries are written and there is nothing to resume from.
• Gate (resume): No flag required. Any session can invoke resume_from_passport=<hash> against a passport that carries a valid boundary entry matching the hash.
• Intent: Invoke in a fresh Claude Code session. Resuming within the same session that emitted the boundary provides no token savings and may drop still-live in-session context.
• Stage: Any. Resumes at whatever stage the routing rules above determine.
• Reference: `references/passport_as_reset_boundary.md` — see §"resume_from_passport mode contract".

Execution flow:

1. Detect the user's current stage and available materials
2. Recommend the optimal mode for each stage
3. Dispatch the corresponding skill for each stage
4. After each stage completion, proactively prompt and wait for user confirmation
5. Track progress throughout; Pipeline Status Dashboard available at any time

Trigger Conditions

Trigger Keywords

English: academic pipeline, research to paper, full paper workflow, paper pipeline, end-to-end paper, research-to-publication, complete paper workflow

한국어: 학술 파이프라인, 연구부터 논문까지, 논문 전체 워크플로, 연구 주제 설정부터 논문 완성까지, 연구-논문 전 과정

Non-Trigger Scenarios

Trigger Exclusions

• If the user only needs a single function (just search materials, just check citations), no pipeline is needed — directly trigger the corresponding skill
• If the user is already using a specific mode of a skill, respect that entry point; the pipeline is opt-in
• The pipeline is optional, not mandatory

Pipeline Stages (10 Stages)

Parallelization opportunity (v3.3): Within Stage 2, the academic-paper skill's Phase 1 (literature_strategist_agent) and the visualization_agent can operate in parallel after Phase 2 (structure_architect_agent) completes the outline. Specifically:

• Once the outline includes a visualization plan, visualization_agent can begin figure generation
• Simultaneously, argument_builder_agent can build CER chains
• draft_writer_agent waits for both to complete before beginning Phase 4

This mirrors PaperOrchestra's parallel execution of Plot Generation (Step 2) and Literature Review (Step 3) after Outline (Step 1), which reduces overall pipeline latency. The parallelization is optional — sequential execution remains the default for simplicity.

Pipeline State Machine

1. Stage 1 RESEARCH -> user confirmation -> Stage 2
2. Stage 2 WRITE -> user confirmation -> Stage 2.5
3. Stage 2.5 INTEGRITY -> PASS -> Stage 3 (FAIL -> fix and re-verify, max 3 rounds; then Integrity Check FAIL Loop -> recorded user decision)
4. Stage 3 REVIEW -> Accept -> Stage 4.5 / Minor|Major -> Stage 4 / Reject -> Stage 2 or end
5. Stage 4 REVISE -> user confirmation -> Stage 3'
6. Stage 3' RE-REVIEW -> Accept|Minor -> Stage 4.5 / Major -> Stage 4'
7. Stage 4' RE-REVISE -> user confirmation -> Stage 4.5 (no return to review)
8. Stage 4.5 FINAL INTEGRITY -> PASS (zero issues) -> Stage 5 (FAIL -> fix and re-verify; after 3 unresolved rounds -> Integrity Check FAIL Loop -> recorded user decision)
9. Stage 5 FINALIZE -> MD -> DOCX via Pandoc when available (otherwise instructions) -> ask about LaTeX -> confirm -> PDF -> completion checkpoint (FULL) -> Stage 6 (user may decline Stage 6: marked skipped, pipeline goes directly to completed)
10. Stage 6 PROCESS SUMMARY -> ask language version -> generate process record MD -> LaTeX -> PDF -> terminal acknowledgement (finish / end / done / confirm, or an unambiguous natural-language equivalent) -> pipeline global state completed

See references/pipeline_state_machine.md for complete state transition definitions.

Adaptive Checkpoint System

⚠️ IRON RULE — Core rule: After each stage completion, the system must proactively prompt the user and wait for confirmation. The checkpoint presentation adapts based on context and user engagement.

Checkpoint Types

Decision Dashboard (shown at FULL checkpoints)

━━━ Stage [X] [Name] Complete ━━━
 
Metrics:
- Word count: [N] (target: [T] +/-10%)    [OK/OVER/UNDER]
- References: [N] (min: [M])              [OK/LOW]
- Coverage: [N]/[T] sections drafted       [COMPLETE/PARTIAL]
- Criterion status: [named criterion + evidence-anchored categorical judgement, or `NOT_COMPARABLE`]
 
Deliverables:
- [Material 1]
- [Material 2]
 
Flagged: [any issues detected, or "None"]
 
Ready to proceed to Stage [Y]? You can also:
1. View progress (say "status")
2. Adjust settings
3. Pause pipeline
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Adaptive Rules