psyclaw 0.27.22 → 0.28.0

package/vendor/ars/academic-pipeline/references/process_summary_protocol.md

@@ -0,0 +1,209 @@
+# Stage 6: Process Summary Protocol (Added in v2.4)
+
+**Trigger**: After the user confirms the Stage 5 completion checkpoint (FULL). Stage 6 is non-mandatory — the user may decline it at that checkpoint; it is then marked `skipped` and the pipeline still terminates `completed` (see `pipeline_state_machine.md` § Stage 6 terminal semantics)
+**Purpose**: Document the complete human-AI collaboration history for the paper creation process, for user sharing, reporting, or reflection
+
+## Workflow
+
+```
+1. Ask user language preference:
+   "Which language version of the process record would you like to generate first?"
+   - Chinese (Traditional Chinese)
+   - English
+   - Both (default: generate the user's primary conversation language first)
+
+2. Review session history and compile the following:
+   - User's initial instructions (verbatim quote)
+   - Key decision points and user interventions at each stage
+   - Direction correction moments and reasons
+   - Iteration count and review result summaries
+   - Intellectual insights raised by the user (e.g., questions that spawned new chapters)
+   - Quality requirement evolution (e.g., formatting, tone adjustments)
+   - Pipeline statistics (stage count, review rounds, integrity verification count, etc.)
+
+2b. Dispatch collaboration_depth_agent in whole-pipeline mode (range = all
+   stages, v3.5); its advisory report becomes the "Collaboration Depth
+   Trajectory" chapter of the Process Record — this dispatch happens BEFORE
+   record generation so the chapter is inside the record the user acknowledges
+
+3. Generate Markdown version (paper_creation_process.md / paper_creation_process_en.md)
+
+4. Convert to LaTeX and compile PDF:
+   - pandoc MD -> LaTeX body
+   - Package complete LaTeX document (with cover page, table of contents, headers/footers)
+   - tectonic compile PDF
+   - Chinese version requires xeCJK + Source Han Serif TC VF
+
+5. Terminal acknowledgement (pipeline terminal checkpoint):
+   - After delivering the process record, prompt the user to close the pipeline.
+   - 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.
+   - On acknowledgement: state_tracker marks Stage 6 completed and sets the pipeline global state to completed. There is no next stage.
+     (See pipeline_state_machine.md § Stage 6 terminal semantics.)
+   - Persist that terminal transition first and without consulting #673
+     adjudication-activity metadata. If the user selected a local activity
+     store, seal/build/append/render runs only afterward as best-effort
+     post-terminal work; its failure cannot change completion.
+```
+
+## Adjudication-activity exclusion (#673)
+
+The Process Record may describe the user-visible decisions already present in
+the ordinary dialogue and state history. It MUST NOT read, copy, summarize,
+score, or mention activity metadata. It MUST NOT include
+`pending_adjudication_activity_bindings[]`, the sealed
+`adjudication_activity_sources` inventory, the selected store/path, stored
+records, renderer output, or diagnostics. Those artifacts are a
+separate local advisory side channel, not Process Record evidence. They also
+must not be passed to `collaboration_depth_agent` or any model/judge/eval call.
+The Stage 6 compilation rules do not perform an ambient filesystem scan for
+them. See `../agents/state_tracker_agent.md` § "Adjudication-activity metadata"
+for the single producer/state authority.
+
+## Required Content in Process Record
+
+| Section | Content |
+|---------|---------|
+| Paper Information | Title, final deliverables list |
+| Stage-by-Stage Process | Input/output/key decisions for each stage, with verbatim user quotes |
+| Iteration Details | Review comment summaries, revision items, re-review results |
+| Interaction Pattern Summary | User role, Claude role, intervention count, key turning points — statistics table |
+| User Key Decisions | Chronological list of every important decision made by the user |
+| Key Lessons | Reusable lessons learned from the process |
+| **Collaboration Quality Evaluation** | **Final chapter: 1-100 score + dimensional analysis + improvement suggestions** (see below) |
+
+## Collaboration Quality Evaluation (Final Chapter, Mandatory)
+
+The final chapter of the process record is a "Collaboration Quality Evaluation" that honestly and constructively assesses the user's performance in the human-AI collaboration. Format follows the Claude Code CLI `/insight` feature.
+
+### Scoring Dimensions (each 1-100, weighted average for overall score)
+
+```
++--------------------------------------------------+
+|  Collaboration Quality Score: [XX]/100            |
++--------------------------------------------------+
+|                                                   |
+|  Direction Setting          [----------  ] XX     |
+|  Clarity, timing, scope definition                |
+|                                                   |
+|  Intellectual Contribution  [------------ ] XX    |
+|  Insight depth, original questions, concept        |
+|  challenges                                       |
+|                                                   |
+|  Quality Gatekeeping        [---------   ] XX     |
+|  Visual inspection, formatting requirements,       |
+|  quality standards                                |
+|                                                   |
+|  Iteration Discipline       [----------  ] XX     |
+|  Timely direction correction, willingness to       |
+|  re-run pipeline, refusing to settle              |
+|                                                   |
+|  Delegation Efficiency      [-------     ] XX     |
+|  When to intervene/when to let go, instruction     |
+|  precision, checkpoint efficiency                 |
+|                                                   |
+|  Meta-Learning              [------------ ] XX    |
+|  Feeding experience back to skills, requesting     |
+|  lesson recording, process improvement awareness  |
+|                                                   |
++--------------------------------------------------+
+```
+
+### Scoring Criteria
+
+| Score Range | Meaning |
+|------------|---------|
+| 90-100 | Exceptional — User intervention significantly elevated the paper's intellectual quality beyond what AI could produce independently |
+| 75-89 | Excellent — User made correct directional decisions and effectively leveraged the pipeline's iteration capabilities |
+| 60-74 | Good — User completed necessary decisions but some opportunities were missed |
+| 40-59 | Basic — User primarily served as a "continue" button with little substantive intervention |
+| 1-39 | Needs Improvement — User intervention may have disrupted the workflow or lacked critical quality gatekeeping |
+
+### Required Subsections
+
+1. **Overall Score**: Total score + one-sentence evaluation
+2. **What Worked Well**: 2-4 specific behaviors, with verbatim user quotes
+3. **Missed Opportunities**: 1-3 things the user could have done but didn't
+4. **Recommendations for Next Time**: 3-5 specific, actionable improvement suggestions
+5. **Human vs AI Value-Add**: Clearly identify which aspects of the final paper quality came from user intervention (not achievable by AI independently)
+
+### Evaluation Principles
+
+- **Honesty first**: No inflation, no pleasantries. If the user only pressed "continue," reflect that truthfully
+- **Evidence-based**: Every score is supported by specific behaviors or conversation records
+- **Constructive**: Every criticism must include actionable improvement suggestions
+- **Acknowledge uncertainty**: If certain dimensions cannot be evaluated (e.g., mid-entry skipped the research stage), mark as N/A
+- **Bidirectional reflection**: Also candidly point out Claude's shortcomings during the process (e.g., areas requiring multiple corrections)
+
+## AI Self-Reflection Report (Mandatory)
+
+The second-to-last chapter of the process record is an "AI Self-Reflection Report" that honestly documents AI's own behavioral patterns during the pipeline. This complements the Collaboration Quality Evaluation (which assesses the user) by assessing the AI.
+
+### Tracked Metrics
+
+All metrics below are derived from existing agent logs (`[DA-DECISION]`, `[DA-REBUTTAL]`, `[HEALTH-CHECK]`, state tracker JSON) — no additional per-stage instrumentation is required. The orchestrator aggregates these at Stage 6 by scanning the dialogue transcript:
+
+```
++--------------------------------------------------+
+|  AI Self-Reflection Report                        |
++--------------------------------------------------+
+|                                                   |
+|  DA Concession Rate           X/Y (Z%)           |
+|  (concessions / total rebuttals received)         |
+|                                                   |
+|  DA Consecutive Concessions   [list if any]       |
+|  (violations of no-consecutive rule)              |
+|                                                   |
+|  Checkpoints Skipped          X/Y                 |
+|  (SLIM or user-skipped / total checkpoints)       |
+|                                                   |
+|  User Overrides               X                   |
+|  (times user overruled AI recommendation)         |
+|                                                   |
+|  Dialogue Health Alerts       X                   |
+|  (health check interventions triggered)           |
+|  - Persistent Agreement:      X                   |
+|  - Conflict Avoidance:        X                   |
+|  - Premature Convergence:     X                   |
+|                                                   |
+|  Intent Mode Transitions      X                   |
+|  (exploratory ↔ goal-oriented switches)           |
+|                                                   |
+|  Cross-Model Disagreements    X (if enabled)      |
+|  (integrity + DA combined)                        |
+|                                                   |
++--------------------------------------------------+
+```
+
+### Required Subsections
+
+1. **Behavioral Summary**: One paragraph describing the overall AI behavioral pattern during this pipeline run
+2. **Sycophancy Risk Assessment**: Screening thresholds based on concession rate and health alerts — LOW (concession <50%, 0 health alerts) / MEDIUM (50-65% or 1-2 alerts) / HIGH (>65% or 3+ alerts). These are screening thresholds, not diagnostic criteria — a MEDIUM rating means the metrics warrant human review, not that sycophancy occurred (a high concession rate may reflect genuinely strong rebuttals). If HIGH, include a warning: "AI may have been too accommodating in this run. Human review of DA findings and integrity results is strongly recommended."
+3. **Frame-Lock Incidents**: List any `[CROSS-MODEL-FINDING]` that the primary DA missed (if cross-model was enabled), or any frame-lock detections triggered during checkpoints. If none, state "No frame-lock incidents detected — note this could mean either good coverage or undetected frame-lock."
+4. **Convergence Pattern**: In Socratic dialogue stages, was intent correctly detected? Did the mentor try to converge prematurely? Report mode transitions and any premature-convergence health alerts.
+5. **What AI Got Wrong**: Candid list of AI errors or shortcomings during the run — corrections needed, checkpoint failures, integrity issues found. This is not a failure report; it is evidence that quality gates are working.
+6. **Failure Mode Audit Log** (v3.2): For each of the 7 AI research failure modes from the Stage 2.5 / 4.5 checklist (see `references/ai_research_failure_modes.md`), report (a) final status at 4.5 — `CLEAR` / `OVERRIDDEN`, (b) history — was it ever `SUSPECTED` during the pipeline? At which stage? How was it resolved? (c) if `OVERRIDDEN`, the user's recorded reasoning. This makes the failure-mode defences part of the permanent process record. Modes with no history can be listed as `CLEAR (no flags)` in one line; expand only on modes that were flagged.
+- **Reading Probe Outcomes (if present)** — transcribes the `### Reading Probe Outcomes` subsection from the Research Plan Summary verbatim, with a one-line note that the AI did not verify paraphrase accuracy. If the Research Plan Summary has no such subsection (i.e., `ARS_SOCRATIC_READING_PROBE` was unset), this item is omitted entirely (no "not applicable" noise). Pickup rule (two sources, either sufficient): (a) copy the entire `### Reading Probe Outcomes` subsection body verbatim — this is the authoritative human-readable record; (b) additionally grep for `[READING-PROBE: status=..., paper=..., outcome=..., turn=...]` which the Mentor emits once in the summary as a machine-stable anchor (including for `not_fired_*` statuses). If both are present use (a) as the display source and keep (b) as the final line of the transcribed block so downstream tooling can still parse it. If only raw inline tags from dialogue turns (`[READING-PROBE: paper=..., outcome=..., turn=...]` without the `status=` field) are found and no subsection exists, the Mentor compilation step was skipped — log this as a pipeline anomaly rather than silently dropping the probe data.
+- **Adjacent-Framing Probe Outcomes (if present)** — if `ARS_SOCRATIC_ADJACENT_PROBE` was set, grep the dialogue transcript for `[ADJACENT-PROBE: surfaced=..., anchor=internal_knowledge, turn=..., outcome=...]` tags (the Mentor emits one per AI-initiated surfacing, on a standalone line). Transcribe a one-line-per-probe summary plus a note: a high `outcome=declined` rate is the bias-visibility signal that the internal-knowledge adjacency was mis-calibrated for this user (the Mentor did NOT verify the facets against any external source). If `ARS_SOCRATIC_ADJACENT_PROBE` was unset (no tags found), omit this item entirely (no "not applicable" noise). Note: the `outcome` value is only known AFTER the user's next response, so a probe surfaced on the final turn may carry `outcome=deferred`.
+
+### Output Length Guidance
+
+For dimensions with no findings, state the null result in one sentence. Expand only when issues are detected. The real risk is generating verbose "everything is fine" paragraphs for empty subsections — resist this.
+
+### Principles
+
+- **Self-honesty**: AI must not minimize its own shortcomings. If the DA conceded too easily, say so.
+- **Not self-flagellation**: The purpose is transparency, not performative humility. Report facts with interpretation.
+- **Actionable**: Every finding should suggest what could be done differently next time (e.g., "Consider enabling cross-model verification for the next run" or "The user might want to push back harder on DA concessions")
+- **The irony is noted**: This self-reflection is itself produced by the same AI that may have been sycophantic during the pipeline. The user should read it with that awareness. This caveat must be stated in the report.
+
+## Output Specifications
+
+- **Filename**: `paper_creation_process.md` (Chinese) / `paper_creation_process_en.md` (English)
+- **PDF**: `paper_creation_process_zh.pdf` / `paper_creation_process_en.pdf`
+- **LaTeX template**: `article` class, 12pt, A4, Times New Roman + Source Han Serif TC VF
+- **Includes table of contents**: `\tableofcontents`
+- **Header**: left = document title (italic), right = date
+- **Compilation**: tectonic (same toolchain as Stage 5)

package/vendor/ars/academic-pipeline/references/progress_dashboard_template.md

@@ -0,0 +1,38 @@
+# Progress Dashboard
+
+Users can say "status" or "pipeline status" at any time to view:
+
+```
++=============================================+
+|   Academic Pipeline Status                   |
++=============================================+
+| Topic: Impact of AI on Higher Education     |
+|        Quality Assurance                    |
++---------------------------------------------+
+
+  Stage 1   RESEARCH          [v] Completed
+  Stage 2   WRITE             [v] Completed
+  Stage 2.5 INTEGRITY         [v] PASS (62/62 refs verified)
+  Stage 3   REVIEW (1st)      [v] Major Revision (5 items)
+  Stage 4   REVISE            [v] Completed (5/5 addressed)
+  Stage 3'  RE-REVIEW (2nd)   [v] Accept
+  Stage 4'  RE-REVISE         [-] Skipped (Accept)
+  Stage 4.5 FINAL INTEGRITY   [..] In Progress
+  Stage 5   FINALIZE          [ ] Pending
+  Stage 6   PROCESS SUMMARY   [ ] Pending
+
++---------------------------------------------+
+| Integrity Verification:                     |
+|   Pre-review:  PASS (0 issues)              |
+|   Final:       In progress...               |
+| Compliance (v3.4.0):                        |
+|   PRISMA-trAIce: pass (17/17)               |
+|   RAISE principles: pass (4/4)              |
++---------------------------------------------+
+| Review History:                             |
+|   Round 1: Major Revision (5 required)      |
+|   Round 2: Accept                           |
++=============================================+
+```
+
+See `templates/pipeline_status_template.md` for the output template.

package/vendor/ars/academic-pipeline/references/reinforcement_content.md

@@ -0,0 +1,15 @@
+# Mid-Conversation Reinforcement Content
+
+Stage-specific reinforcement content for the Mid-Conversation Reinforcement Protocol. At every stage transition, the orchestrator injects the relevant row from this table into the reinforcement template.
+
+| Transition | Reinforcement Focus |
+|-----------|-------------------|
+| Stage 1→2 | IRON RULE: Every claim must have a citation. Anti-Pattern: Fabricated citations. |
+| Stage 2→2.5 | IRON RULE: Gray zone = FAIL. Anti-Pattern: Treating "difficult to verify" as acceptable. |
+| Stage 2.5→3 | IRON RULE: Reviewers are READ-ONLY. Anti-Pattern: Fabricating review comments. |
+| Stage 3→4 | IRON RULE: Max 2 revision loops. Anti-Pattern: Sycophantic revision. |
+| Stage 4→3' | IRON RULE: Each concern independently verified. Anti-Pattern: Rubber-stamp re-review. |
+| Stage 3'→4' | IRON RULE: Max 2 revision loops. Anti-Pattern: Silently dropping reviewer concerns. |
+| Stage 4/4'→4.5 | IRON RULE: PASS with zero issues, or a recorded user decision via the Integrity Check FAIL Loop. Anti-Pattern: Re-verifying only known issues. |
+| Stage 4.5→5 | IRON RULE: PDF from LaTeX only. Anti-Pattern: Orchestrator doing substantive work. |
+| Any FULL/SLIM checkpoint | IRON RULE: `collaboration_depth_agent` output is **advisory only** and never blocks progression. Anti-Pattern: treating the observer's Zone/scores as a gate or a leaderboard. |

package/vendor/ars/academic-pipeline/references/reproducibility_audit.md

@@ -0,0 +1,55 @@
+# Auditability and Re-execution Documentation
+
+The pipeline standardizes stage contracts and records artifacts so a run can be inspected. This does not ensure identical model behaviour, judgements, or manuscript quality across executions.
+
+## Standardized Workflow
+
+| Contract surface | Mechanism and boundary |
+|---------------|-----------|
+| Integrity check every time | Stage 2.5 + Stage 4.5 are **mandatory** stages, cannot be skipped |
+| Declared review angles | Journal-Fit Reviewer + R1/R2/R3 + Devil's Advocate — five role-separated perspectives; this is not evidence of independent errors or consistent findings |
+| Declared verification procedure | integrity_verification_agent uses standardized templates and records coverage; semantic decisions and retrieval availability can vary |
+| Explicit gate rules | Integrity PASS/FAIL criteria are inspectable; passing applies only to the registered/checked population and named verdict classes |
+| Traceable workflow | Every stage's deliverables are recorded, enabling retrospective audit |
+
+## Audit Trail
+
+When the pipeline ends, state_tracker_agent produces a complete audit trail:
+
+```
+Pipeline Audit Trail
+====================
+Topic: [topic]
+Started: [time]
+Completed: [time]
+Total Stages: [X/9]
+
+Stage 1 RESEARCH: [mode] -> [output count]
+Stage 2 WRITE: [mode] -> [word count]
+Stage 2.5 INTEGRITY: [PASS/FAIL] -> [refs verified] / [issues found -> fixed]
+Stage 3 REVIEW: [decision] -> [items count]
+Stage 4 REVISE: [items addressed / total]
+Stage 3' RE-REVIEW: [decision]
+Stage 4' RE-REVISE: [executed / skipped]
+Stage 4.5 FINAL INTEGRITY: [PASS/FAIL] -> [refs verified]
+Stage 5 FINALIZE: Ask format style -> MD -> DOCX via Pandoc when available (otherwise instructions) -> LaTeX (apa7/ieee/etc.) -> tectonic -> PDF
+Stage 6 PROCESS SUMMARY: Ask language -> MD -> LaTeX -> PDF (zh/en)
+
+Integrity Summary:
+  Pre-review: [X] refs checked, [Y] issues found, [Y] fixed
+  Final: [X] refs checked, [Y] issues found, [Y] fixed
+  Overall: [CLEAN / ISSUES NOTED]
+```
+
+## Re-execution boundary (v3.3.5+)
+
+This document defines a PROCESS CONTRACT — declared stages, reviewer roles,
+gate rules, and retained artifacts. It does not promise consistent outputs.
+
+For computational re-execution documentation, see
+[`../../shared/artifact_reproducibility_pattern.md`](../../shared/artifact_reproducibility_pattern.md).
+
+The pipeline enforces process routing and deterministic validators where specified.
+The Material Passport's optional `repro_lock` records configuration for inspection;
+it is not a byte-replay guarantee for LLM output. The audit trail supports comparison,
+not proof of equivalent outcomes or quality.

package/vendor/ars/academic-pipeline/references/score_trajectory_protocol.md

@@ -0,0 +1,78 @@
+# Criterion Trajectory Protocol
+
+**Compatibility filename**: `score_trajectory_protocol.md`
+**Status**: design contract, not wired to a current machine producer
+**Current runtime**: `pipeline_orchestrator_agent` performs the narrative,
+criterion-local regression check below; it does not emit a trajectory object
+**Future carrier**: Stage 3' Schema 6 field or a closed, validated sidecar
+
+## Purpose
+
+Tracks whether a revision improved, preserved, or weakened each named review criterion. The protocol compares evidence-anchored categorical judgements; it does not calculate rubric scores, numerical deltas, or a paper-quality ranking.
+
+## Comparison rule
+
+In a future typed implementation, compare the previous and current record for every applicable universal dimension:
+
+| Field | Allowed values / content |
+|---|---|
+| previous_judgement | `EXCEEDS`, `MEETS`, `PARTLY_MEETS`, `DOES_NOT_MEET`, or `NOT_ASSESSED` |
+| current_judgement | same enum |
+| change | `IMPROVED`, `UNCHANGED`, `REGRESSED`, or `NOT_COMPARABLE` |
+| previous_evidence | anchors supporting the earlier judgement |
+| current_evidence | anchors supporting the current judgement |
+| rationale | why the criterion is improved, unchanged, regressed, or not comparable |
+| decision_bearing | whether the change affects the current recommendation, with a reason |
+
+`change` is a reasoned, criterion-local comparison. Do not infer it by assigning hidden numbers to judgement labels. Use `NOT_COMPARABLE` when criteria, target venue, article type, manuscript scope, or available evidence changed materially.
+
+## Regression handling
+
+A `REGRESSED` item triggers a MANDATORY checkpoint when it is decision-bearing or when its evidence shows a new material weakness. Present:
+
+1. the criterion and previous/current evidence;
+2. the rationale for regression and its decision impact;
+3. whether the change was an intentional trade-off; and
+4. options to proceed with an explicit limitation, make a targeted fix, or restore the affected revision.
+
+No fixed numerical tolerance determines regression. A presentation-only change must not be promoted into a substantive regression, and a newly exposed core flaw must not be softened because other criteria improved.
+
+## Early stopping
+
+Early stopping is eligible only when:
+
+- no P0 issue remains;
+- no unresolved decision-bearing regression remains;
+- no applicable criterion has a substantive status change requiring another revision; and
+- the author has no outstanding required action under the active revision contract.
+
+The orchestrator must explain these conditions narratively. Label counts and reviewer agreement counts are not substitutes for that explanation.
+
+## Proposed Stage 6 reporting (not current output)
+
+```markdown
+### Criterion Trajectory
+
+| Dimension | Previous judgement | Current judgement | Change | Evidence and rationale | Decision bearing? |
+|---|---|---|---|---|---|
+| Originality | PARTLY_MEETS | MEETS | IMPROVED | <anchors and reason> | no |
+| Methodological Rigor | MEETS | PARTLY_MEETS | REGRESSED | <anchors and reason> | yes |
+| ... | ... | ... | ... | ... | ... |
+
+Unresolved decision-bearing regressions: <list or none>
+Early-stop eligible: <yes/no, with criterion-bound explanation>
+```
+
+## Compatibility
+
+No current producer emits `criterion_trajectory`. A legacy `score_trajectory`
+or experimental `criterion_trajectory` field may be preserved when reading an
+older artifact, but it is historical metadata only: do not recompute it,
+compare it with current judgements, map it to a decision, or emit it as a
+current workflow result. Current checkpoints compare named criteria
+narratively and use `NOT_COMPARABLE` whenever a valid comparison cannot be
+made.
+
+## Reference
+
+This replaces the former score-delta adaptation of PaperOrchestra's refinement loop. The useful idea retained is explicit regression checking; numerical accept/revert thresholds are not adopted.

package/vendor/ars/academic-pipeline/references/team_collaboration_protocol.md

@@ -0,0 +1,261 @@
+# Team Collaboration Protocol
+
+## Purpose
+
+Guidelines for coordinating multi-person academic research teams using the pipeline. Claude Code runs as a single-user session; this protocol documents the **human coordination layer** that wraps around pipeline executions.
+
+---
+
+## Role Definitions
+
+| Role | Pipeline Stages | Responsibilities |
+|------|----------------|-----------------|
+| Research Lead | Stage 1 (RESEARCH) | Defines RQ, manages literature search, approves synthesis, sets theoretical framework |
+| Lead Author | Stage 2 (WRITE), Stage 4/4' (REVISE) | Writes/revises paper, makes final content decisions, owns the manuscript |
+| Methods Specialist | Stage 1 (methodology), Stage 2 (methods section) | Ensures methodological rigor, validates statistical analysis, reviews data integrity |
+| Review Coordinator | Stage 3/3' (REVIEW) | Manages simulated review process, distributes feedback, facilitates revision coaching |
+| Integration Lead | All stages | Ensures consistency across stages, manages handoffs, resolves cross-stage conflicts |
+
+### Role Assignment Rules
+
+- One person may hold multiple roles (common in small teams)
+- Research Lead and Lead Author are the minimum required roles (can be the same person)
+- Integration Lead is recommended for teams of 3+
+- Methods Specialist is strongly recommended for empirical papers
+- All role assignments should be documented at pipeline intake
+
+---
+
+## Handoff Protocol
+
+For each stage transition, the following handoff procedure applies:
+
+### Stage 1 -> Stage 2 (Research -> Write)
+
+| Item | Detail |
+|------|--------|
+| **Who hands off** | Research Lead |
+| **Who receives** | Lead Author |
+| **Materials** | RQ Brief, Bibliography, Synthesis Report (conforming to Schemas 1-3 in `shared/handoff_schemas.md`) |
+| **Approval needed** | Research Lead confirms synthesis is complete and RQ is finalized |
+| **Handoff checklist** | All Material Passports (Schema 9) attached; bibliography coverage is assessed against the planned claims and field-specific evidence needs; synthesis structure fits the material rather than a fixed theme count |
+
+### Stage 2 -> Stage 2.5 (Write -> Integrity)
+
+| Item | Detail |
+|------|--------|
+| **Who hands off** | Lead Author |
+| **Who receives** | Integration Lead (or Lead Author if no Integration Lead) |
+| **Materials** | Paper Draft (conforming to Schema 4) |
+| **Approval needed** | Lead Author confirms draft is ready for verification |
+| **Handoff checklist** | All sections complete; reference list formatted; word count within target range |
+
+### Stage 2.5 -> Stage 3 (Integrity -> Review)
+
+| Item | Detail |
+|------|--------|
+| **Who hands off** | Integration Lead |
+| **Who receives** | Review Coordinator |
+| **Materials** | Stage 2.5 Paper Draft (verified, or carrying the recorded FAIL-loop warning) + Integrity Report (Schema 5) |
+| **Approval needed** | Integrity verdict is PASS (any PASS_WITH_CONDITIONS items acknowledged), or the recorded Integrity Check FAIL Loop user decision |
+| **Handoff checklist** | Integrity Report attached; all SERIOUS/MEDIUM issues resolved, or covered by the recorded FAIL-loop decision |
+
+### Stage 3 -> Stage 4 (Review -> Revise)
+
+| Item | Detail |
+|------|--------|
+| **Who hands off** | Review Coordinator |
+| **Who receives** | Lead Author + Methods Specialist (if methodology issues) |
+| **Materials** | Review Report (Schema 6) + Revision Roadmap (Schema 7) |
+| **Approval needed** | Review Coordinator confirms roadmap is complete; Lead Author reviews before starting |
+| **Handoff checklist** | All revision items categorized and prioritized; coaching session completed (or skipped by Lead Author) |
+
+### Stage 4 -> Stage 3' (Revise -> Re-Review)
+
+| Item | Detail |
+|------|--------|
+| **Who hands off** | Lead Author |
+| **Who receives** | Review Coordinator |
+| **Materials** | Revised Draft + hard-required Original pre-revision Draft + immutable Round-1 Revision Roadmap + exact author-adjudication sidecar + fully replayed Revision-Evidence Bundle + Response to Reviewers + Editorial Decision Letter + Round-1 findings + exact ordered patch/report pairs matching the bundle + Round-1 Reviewer Configuration Cards. This is the default current #576 1.1 re-review transfer; missing original/roadmap/author/bundle fails closed. A user-requested fresh full review at 3' is a separate branch with Revised Draft + available context. |
+| **Approval needed** | Lead Author confirms all addressable items are handled |
+| **Handoff checklist** | Re-review mode: Response to Reviewers covers every roadmap item; new references verified. Fresh full review at 3': no roadmap-coverage check (no Round-1 Roadmap exists); new references verified |
+
+### Stage 4.5 -> Stage 5 (Final Integrity -> Finalize)
+
+| Item | Detail |
+|------|--------|
+| **Who hands off** | Integration Lead |
+| **Who receives** | Lead Author |
+| **Materials** | Final Draft (verified, or carrying the recorded partially-unverified warning) + Final Integrity Report |
+| **Approval needed** | Integrity verdict PASS with zero issues (or the recorded Integrity Check FAIL Loop user decision) |
+| **Handoff checklist** | All previous integrity issues resolved, or covered by the recorded FAIL-loop decision with the partially-unverified warning carried forward; Material Passport `verification_status` set to `VERIFIED` only on a zero-issue PASS (a FAIL-loop continuation keeps `UNVERIFIED`) |
+
+---
+
+## Version Control
+
+### Git Branching Strategy
+
+```
+main
+  |-- paper/draft-v1          (Stage 2 output)
+  |-- paper/post-integrity-v1 (Stage 2.5 output)
+  |-- paper/post-review-v1    (Stage 4 output)
+  |-- paper/final-v1          (Stage 5 output)
+```
+
+### Tagging Convention
+
+| Tag | When | Example |
+|-----|------|---------|
+| `v0.1-draft` | After Stage 2 completion | First complete draft |
+| `v0.2-post-integrity` | After Stage 2.5 PASS | Draft verified for integrity |
+| `v0.3-post-review` | After Stage 4 completion | First revision complete |
+| `v0.4-post-rereview` | After Stage 4' completion (if applicable) | Second revision complete |
+| `v1.0-final` | After Stage 5 completion | Final manuscript |
+
+### Rules
+
+- Never overwrite; always create a new version
+- All versions are preserved for audit trail
+- Version labels must match the Material Passport `version_label` field (Schema 9 in `shared/handoff_schemas.md`)
+- Each team member's changes should be attributable (use git author info)
+
+---
+
+## Conflict Resolution
+
+| Conflict Type | Resolution Authority | Escalation Path |
+|--------------|---------------------|-----------------|
+| Content disagreements | Lead Author has final say | If unresolved: Research Lead mediates |
+| Methodological disagreements | Methods Specialist has final say | If unresolved: cite literature precedent |
+| Scope disagreements | Research Lead has final say | If unresolved: team vote |
+| Formatting/style disagreements | Lead Author has final say | Follow target journal guidelines |
+| Integrity findings disagreements | Integration Lead has final say | Cannot override SERIOUS findings |
+
+### Disagreement Documentation
+
+All disagreements must be documented in the revision tracking:
+
+```markdown
+## Disagreement Record
+
+**Date**: [date]
+**Stage**: [stage]
+**Parties**: [who disagreed]
+**Issue**: [what the disagreement was about]
+**Resolution**: [how it was resolved]
+**Authority**: [who made the final call]
+**Rationale**: [why this decision was made]
+```
+
+---
+
+## Communication Templates
+
+### 1. Handoff Notification
+
+```markdown
+## Handoff: Stage [X] -> Stage [Y]
+
+**From**: [Role] ([Name])
+**To**: [Role] ([Name])
+**Date**: [date]
+
+**Materials Delivered**:
+- [Material 1] (version: [version_label])
+- [Material 2] (version: [version_label])
+
+**Status Summary**:
+[1-2 sentence summary of what was accomplished and any open items]
+
+**Action Required**:
+[What the receiving person needs to do next]
+
+**Deadline**: [if applicable]
+```
+
+### 2. Review Request
+
+```markdown
+## Review Request: [Paper Title]
+
+**From**: [Review Coordinator]
+**To**: [Team / External Reviewer]
+**Date**: [date]
+
+**Paper Version**: [version_label]
+**Word Count**: [N]
+**Review Type**: [Internal simulated / External journal / Team peer review]
+
+**Focus Areas**:
+1. [specific area to focus on]
+2. [specific area to focus on]
+
+**Deadline**: [date]
+**Return Format**: [Use Schema 6 format from shared/handoff_schemas.md]
+```
+
+### 3. Revision Assignment
+
+```markdown
+## Revision Assignment: [Paper Title]
+
+**From**: [Review Coordinator]
+**To**: [Lead Author / Methods Specialist]
+**Date**: [date]
+
+**Revision Round**: [N]
+**Total Items**: [N] (must_fix: [N], should_fix: [N], consider: [N])
+
+**Your Assignments**:
+- [REV-001]: [brief description] — assigned to [name]
+- [REV-003]: [brief description] — assigned to [name]
+
+**Deadline**: [date]
+**Coordination Notes**: [any dependencies between revision items]
+```
+
+---
+
+## Workflow for Teams
+
+### Small Team (2-3 people)
+
+```
+Person A (Research Lead + Lead Author):
+  - Runs Stage 1 (RESEARCH) with their Claude session
+  - Runs Stage 2 (WRITE) with their Claude session
+  - Receives revision items, runs Stage 4/4'
+  - Runs Stage 5 (FINALIZE)
+
+Person B (Methods Specialist + Review Coordinator):
+  - Reviews Stage 1 methodology output
+  - Reviews Stage 2 methods section
+  - Manages Stage 3/3' review process
+  - Handles specific methodology revision items
+
+Handoff: via shared folder or git repo
+Materials: conform to schemas in shared/handoff_schemas.md
+```
+
+### Large Team (4+ people)
+
+```
+Add Integration Lead role:
+  - Monitors all stage transitions
+  - Validates handoff completeness
+  - Resolves cross-stage inconsistencies
+  - Maintains pipeline state document (shared with all team members)
+```
+
+---
+
+## Limitations
+
+- Claude Code runs as a single-user session; this protocol documents the HUMAN coordination layer
+- Each team member runs their own pipeline stages independently in separate Claude sessions
+- Handoff materials (conforming to schemas in `shared/handoff_schemas.md`) ensure consistency across sessions
+- Real-time co-editing is not supported; use git or shared documents for synchronization
+- Pipeline state tracking is per-session; the Integration Lead must manually synchronize state across sessions
+- The pipeline does not enforce team role permissions; discipline is maintained by convention