psyclaw 0.27.22 → 0.28.0

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

@@ -0,0 +1,193 @@
+# Consumer Protocol — `literature_corpus[]` Reading
+
+**Status**: Released in v3.6.5 (both Phase 1 consumers wired)
+**Applies to**: any agent in this repo that reads `literature_corpus[]` from a Material Passport
+**Authoritative spec**: [`docs/design/2026-04-26-ars-v3.6.5-consumer-integration-design.md`](../../docs/design/2026-04-26-ars-v3.6.5-consumer-integration-design.md)
+
+## What this document covers
+
+This is the contract every literature-reading consumer agent must follow. The v3.6.4 input port (`shared/contracts/passport/literature_corpus_entry.schema.json`) defines what enters a Material Passport; this document defines how Phase 1 agents read it.
+
+The `corpus-first, search-fills-gap` flow has five steps; the four Iron Rules are non-negotiable; the PRE-SCREENED block is the reproducibility surface; failures are surfaced honestly via the `[CORPUS PARSE FAILURE: <cause>]` graceful fallback.
+
+## Reading flow (shared by every consumer)
+
+```
+Step 0: Detect literature_corpus[] presence and minimal shape
+Step 1: Pre-screen corpus against current RQ
+Step 2: Search-fills-gap — case A / B / B' / C
+Step 3: Merge included + external_included for downstream
+Step 4: Emit Search Strategy Report with PRE-SCREENED block
+```
+
+The full flow specification lives in spec §3.1. Each consumer agent's `agent.md` must include the full Step 0–4 description and all four Step 2 case markers (case A / case B / case B' / case C). The lint enforces presence (L6).
+
+## PRE-SCREENED block template
+
+Every consumer emits the block in this exact shape (alphabetical ordering for citation_keys; truncate at 50 entries with appendix file). Spec §3.2 has the complete template plus truncation rules.
+
+```markdown
+PRE-SCREENED FROM USER CORPUS:
+- Adapter: <obtained_via enum value | "<unspecified>" | "mixed (...)">
+                                          # e.g., zotero-bbt-export, or "<unspecified>" per F4a,
+                                          # or "<value> (N of M entries declared)" per F4b,
+                                          # or "mixed (zotero-bbt-export: K, ..., undeclared: U)" per F4c
+- Snapshot date: <max(obtained_at)>        # ISO 8601, or "<unspecified>" per F4d,
+                                          # or "<date> (M of N entries declared)" per F4e,
+                                          # or append "(spans <N> days; corpus may not be a single snapshot)" per F4f
+- Total entries scanned: <N>
+- Pre-screening result:
+  - Included: <K> entries
+    citation_keys:
+      - <k1>
+      - <k2>
+  - Excluded by inclusion / exclusion criteria: <E> entries
+    citation_keys:
+      - <e1>
+    (omit this sub-block if 0)
+  - Skipped (criteria cannot be applied): <S> entries
+    citation_keys with reasons:
+      - <key>: <reason>
+    (omit this sub-block if 0)
+- Zero-hit note (emit per F3 only when Included: 0):
+  Zero-hit note (corpus non-empty, 0 included after screening): possible
+  causes are (a) corpus is stale relative to current RQ, (b) RQ has
+  shifted away from what the user originally curated, (c) adapter
+  exported entries unrelated to this RQ.
+- Note: presence in corpus does not imply inclusion;
+  same criteria applied to corpus and external sources.
+```
+
+## The four Iron Rules
+
+### Iron Rule 1 — Same criteria
+
+Apply the same Inclusion / Exclusion criteria to corpus entries and external database results. No exceptions. A corpus entry is not "pre-approved"; it must clear the same screening as a fresh database hit.
+
+### Iron Rule 2 — No silent skip
+
+Any skipped corpus entry must be recorded in the PRE-SCREENED block's skipped sub-section with a reason. Silently dropping an entry is a prompt-layer violation. The lint enforces structural markers; behaviour is enforced by the BAD / GOOD example pair below and observed in real runs.
+
+<!-- BAD -->
+```
+[corpus has 5 entries]
+agent includes 3, excludes 1 (off-topic), and silently drops 1 with empty
+abstract because "I cannot evaluate it".
+
+PRE-SCREENED block reports:
+- Total entries scanned: 5
+- Included: 3 entries
+- Excluded: 1 entry
+(no Skipped sub-block)
+
+(1 entry silently disappeared from the pipeline: 3 + 1 ≠ 5 — Iron Rule 2 violation.)
+```
+
+<!-- GOOD -->
+```
+[corpus has 5 entries]
+agent excludes 1 (off-topic), keeps 3 in pre_screened_included[].
+agent records 1 with empty abstract as Skipped: "abstract empty after privacy clearing; criteria reference research method but only title is present, criteria cannot be applied".
+
+PRE-SCREENED block reports:
+- Included: 3 entries
+- Excluded by inclusion / exclusion criteria: 1 entry
+- Skipped (criteria cannot be applied): 1 entry
+  - smith2024foo: abstract empty after privacy clearing; criteria reference research method but only title is present
+- Note: presence in corpus does not imply inclusion;
+  same criteria applied to corpus and external sources.
+```
+
+### Iron Rule 3 — No corpus mutation
+
+Consumer agents never modify, backfill, or derive new content into `literature_corpus[]`. Read only. The Material Passport's corpus is the user's curated list; any rewriting belongs to the user's adapter (v3.6.4 input port), not Phase 1 prompt-layer agents.
+
+### Iron Rule 4 — Graceful fallback on parse failure
+
+Consumer agents do NOT re-validate schema, do NOT parse JSON Schema at runtime, and do NOT dereference `source_pointer` URIs. The v3.6.4 input-port lint validates adapter output, but a passport may reach a Phase 1 agent through other paths (hand-edits, `resume_from_passport`, assembled passports). When a consumer cannot parse `literature_corpus[]`, emit `[CORPUS PARSE FAILURE: <cause>]` in the Search Strategy Report and fall back to external-DB-only flow. Do not abort Phase 1, do not attempt schema repair, do not invent contents.
+
+## Tortured-phrase advisory rows (#660)
+
+`bibliographic-integrity-signal/1.2` tortured-phrase rows are read-only
+advisories, not pre-screening criteria. A consumer may preserve and surface the
+row, but must not use it to include, exclude, rank, downgrade, relabel, or
+rewrite a corpus entry. In particular, a phrase-list match is not evidence of
+AI/author origin, paper-mill production, misconduct, source quality, or
+contextual invalidity. A checked zero-match is not a clean certificate and is
+not evidence that screening coverage is complete.
+
+The two cited surfaces remain independent: `cited_title` and
+`cited_abstract` each have one current row when the check is invoked. A missing
+abstract remains visible as `not_checked` / `unresolved` with
+`ABSTRACT_MISSING`; a consumer must not copy the title result into the abstract
+slot or silently drop the row. Manual entries have no exemption from this
+local metadata check.
+
+Only the dedicated producer may call the non-in-place enricher. It consumes an
+explicitly named local canonical snapshot plus detached manifest whose SHA-256
+binds the exact snapshot bytes; accepted supply is `user_supplied` or
+`synthetic_fixture`. Phase 1 consumers do not build, fetch, import, repair, or
+redistribute a PPS list, do not dereference `source_pointer`, and do not run a
+model, external API, human/model judge, or ambient clock for this advisory.
+They never modify `literature_corpus[]`; a producer returns a separate passport
+copy and takes explicit timestamps.
+
+Every v1.2 row stays `HEURISTIC-INDICATOR` with
+`HEURISTIC-ADVISORY` / `UNMEASURED` context. It composes only in the existing
+single `Bibliographic Integrity Advisories` section. It creates no ref-marker
+token, terminal policy, gate, replacement text, or automatic rewrite. The
+separate own-draft advisory follows the same claim boundary and is not a corpus
+screening input.
+
+## Zero-hit and provenance reporting (F3 / F4)
+
+Two reproducibility surfaces sit inside the PRE-SCREENED block. Every consumer agent must emit each one when the corresponding trigger fires; both are non-blocking and independent of which Step 2 case dispatches next.
+
+**Zero-hit note (F3).** When `pre_screened_included[]` is empty after Step 1 — corpus is non-empty but no entry survived screening — the consumer emits a zero-hit note inside the PRE-SCREENED block listing the three plausible causes:
+
+```
+- Zero-hit note (corpus non-empty, 0 included after screening): possible causes
+  are (a) corpus is stale relative to current RQ, (b) RQ has shifted away from
+  what the user originally curated, (c) adapter exported entries unrelated to
+  this RQ.
+```
+
+The note appears regardless of which Step 2 case fires next. Step 2 dispatch follows F3 in spec §4.1.
+
+**Provenance reporting (F4a–F4f).** `obtained_via` and `obtained_at` are optional in v3.6.4 schema. The PRE-SCREENED block's `Adapter:` and `Snapshot date:` lines reflect actual coverage; consumers never invent enum values or guess timestamps.
+
+| Sub-case | Trigger | `Adapter:` line content |
+|---|---|---|
+| F4a | Zero entries declare `obtained_via` | `Adapter: <unspecified>` + trailing note `Adapter origin not declared; user-written adapter should populate obtained_via per v3.6.4 schema recommendation.` |
+| F4b | At least one entry declares; all declared share single value | `Adapter: <enum value> (N of M entries declared)` |
+| F4c | Two or more distinct enum values among declared entries | `Adapter: mixed (zotero-bbt-export: K, obsidian-vault: L, ..., undeclared: U)` |
+
+| Sub-case | Trigger | `Snapshot date:` line content |
+|---|---|---|
+| F4d | Zero entries declare `obtained_at` | `Snapshot date: <unspecified>` + trailing note `Snapshot date not declared; reproducibility is reduced. Adapter should populate obtained_at per v3.6.4 schema recommendation.` |
+| F4e | Partial coverage | `Snapshot date: <max(obtained_at)> (M of N entries declared)` |
+| F4f | Wide spread (>90 days between min and max) | append `(spans <N> days; corpus may not be a single snapshot)`. Composes with F4e. |
+
+F4a/b/c are mutually exclusive by trigger. F4d applies only when zero entries declare `obtained_at`; F4e and F4f compose. See spec §4.2 for the full precedence reasoning.
+
+## Consumer: bibliography_agent
+
+**Status**: Wired in v3.6.5
+**Skill**: deep-research
+**Phase**: 1 (literature search and curation)
+**Agent file**: [`deep-research/agents/bibliography_agent.md`](../../deep-research/agents/bibliography_agent.md)
+
+The deep-research bibliography agent applies the corpus-first flow during its systematic literature search. The PRE-SCREENED block sits inside the Search Strategy section of its Annotated Bibliography output (per the agent's existing Output Format), preceding the existing DATABASES / Inclusion-Exclusion / RESULTS structure.
+
+When `literature_corpus[]` is non-empty and parses cleanly, the agent enters Step 1 pre-screening. When the corpus is absent, empty, or fails the minimal shape check, the agent runs its existing external-DB-only flow (Iron Rule 4 graceful fallback for the failure cases).
+
+## Consumer: literature_strategist_agent
+
+**Status**: Wired in v3.6.5
+**Skill**: academic-paper
+**Phase**: 1 (literature search and curation)
+**Agent file**: [`academic-paper/agents/literature_strategist_agent.md`](../../academic-paper/agents/literature_strategist_agent.md)
+
+The academic-paper literature strategist agent applies the corpus-first flow during its literature search strategy phase. The PRE-SCREENED block sits inside the Search Strategy section of the Literature Search Report (per the agent's existing Output Format), immediately before the `Databases` line. The merged `final_included` set feeds the agent's downstream Annotated Bibliography, Literature Matrix, Research Gap Identification, and Recommended Sources by Paper Section outputs without altering their formats.
+
+When `literature_corpus[]` is non-empty and parses cleanly, the agent enters Step 1 pre-screening, and Step 2 search-fills-gap dispatches the external 4-Layer Progressive Strategy. When the corpus is absent, empty, or fails the minimal shape check, the agent runs its existing 4-Layer external-DB-only flow unchanged (Iron Rule 4 graceful fallback for the failure cases).

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

@@ -0,0 +1,135 @@
+# Mode Advisor — Unified Cross-Skill Decision Tree
+
+## Purpose
+
+Helps users (and the pipeline orchestrator) select the right skill and mode for their current situation. Eliminates the most common routing mistakes by mapping user intent to the optimal entry point.
+
+---
+
+## Quick Decision Matrix
+
+| What do you want? | How far along? | Time? | Skill + Mode |
+|-------------------|---------------|-------|--------------|
+| Explore a topic | Starting fresh | 30 min | deep-research quick |
+| Explore a topic | Starting fresh | 2+ hr | deep-research full |
+| Think through a research idea | Have vague idea | Any | deep-research socratic |
+| Systematic review | Have clear PICO | 3+ hr | deep-research systematic-review |
+| Verify claims | Have specific claims | 30 min | deep-research fact-check |
+| Write a paper | Have research done | 2+ hr | academic-paper full |
+| Plan a paper step by step | Have RQ, need structure | 1+ hr | academic-paper plan |
+| Fix citations | Have draft | 30 min | academic-paper citation-check |
+| Convert format | Have final draft | 15 min | academic-paper format-convert |
+| Review a paper | Have paper to evaluate | 1 hr | academic-paper-reviewer full |
+| Check revision quality | Have revised draft | 30 min | academic-paper-reviewer re-review |
+| Full pipeline (zero to publication) | Starting fresh | 5+ hr | academic-pipeline |
+| Handle real reviewer feedback | Have review comments | 1+ hr | academic-pipeline (Stage 4 entry) |
+
+---
+
+## Common Misconceptions
+
+| User Says | They Probably Need | Why |
+|-----------|-------------------|-----|
+| "Write me a paper on X" | deep-research first, THEN academic-paper | Writing without research produces shallow papers with unsupported claims |
+| "Review my paper" (but no draft exists) | academic-paper plan mode | They need to write first, not review |
+| "Check my citations" (but paper isn't done) | academic-paper full mode | Finish writing first, then check citations as a separate pass |
+| "I need a systematic review" | deep-research systematic-review mode | NOT academic-paper lit-review structure (different methodology: PRISMA vs narrative) |
+| "Just give me a quick paper" | deep-research quick + academic-paper full | Quick research is fine, but paper writing still needs the full mode for quality |
+| "Format my paper as APA" | academic-paper format-convert mode | Not a rewrite; purely formatting transformation |
+| "I got reviewer comments" | academic-pipeline Stage 4 entry (External Review) | Needs structured intake + strategic coaching, not just "fix what they said" |
+
+---
+
+## User Archetype Recommendations
+
+| Archetype | Recommended Workflow | Rationale |
+|-----------|---------------------|-----------|
+| Graduate student (first paper) | deep-research socratic -> academic-paper plan -> full pipeline | Socratic mode builds research thinking; plan mode structures the paper incrementally; pipeline ensures quality gates |
+| Experienced researcher (submission prep) | academic-pipeline (full, from Stage 1 or mid-entry) | Knows what they want; benefits from the automated quality assurance and integrity checks |
+| Advisor reviewing student work | academic-paper-reviewer full | Provides structured multi-perspective feedback the advisor can use in mentoring |
+| Quick literature scan | deep-research quick or lit-review | Fast turnaround; no need for full pipeline overhead |
+| Journal revision response | academic-pipeline (Stage 4 entry with review comments) | External Review Protocol handles real reviewer feedback with strategic coaching |
+| Conference paper (short deadline) | deep-research quick -> academic-paper full (conference type) | Compressed timeline; quick research + full writing with conference structure |
+| Thesis chapter | deep-research full -> academic-paper full | Each chapter treated as a standalone paper; full depth needed |
+| Policy brief | deep-research quick -> academic-paper full (policy_brief type) | Evidence-based but concise; quick research sufficient for policy scope |
+
+---
+
+## Skill Capability Boundaries
+
+Understanding what each skill can and cannot do prevents misrouting:
+
+| Skill | Can Do | Cannot Do |
+|-------|--------|-----------|
+| deep-research | Literature search, synthesis, RQ refinement, fact-checking | Write papers, review papers, format documents |
+| academic-paper | Write papers, revise papers, format documents, check citations | Conduct original research, review papers (as reviewer), verify integrity |
+| academic-paper-reviewer | Review papers (5-person panel), re-review revisions | Write papers, conduct research, fix issues (only identifies them) |
+| academic-pipeline | Orchestrate all stages, manage transitions, track state | Perform any substantive work (purely dispatching and coordinating) |
+| integrity_verification_agent | Verify references, citations, data, originality | Fix issues (only identifies them), review paper quality |
+
+---
+
+## Decision Flowchart
+
+```
+START: What does the user want?
+  |
+  +--> "I want to research/explore/investigate"
+  |      |
+  |      +--> Have specific claims to verify? --> deep-research fact-check
+  |      +--> Have clear PICO/systematic question? --> deep-research systematic-review
+  |      +--> Want guided exploration? --> deep-research socratic
+  |      +--> Want direct results, have time? --> deep-research full
+  |      +--> Want direct results, short on time? --> deep-research quick
+  |
+  +--> "I want to write a paper"
+  |      |
+  |      +--> Have research/literature ready? --> academic-paper (plan or full)
+  |      +--> No research done yet? --> deep-research FIRST, then academic-paper
+  |      +--> Want full quality assurance? --> academic-pipeline (from Stage 1)
+  |
+  +--> "I want someone to review my paper"
+  |      |
+  |      +--> Have a complete draft? --> academic-paper-reviewer full
+  |      +--> Want integrity check + review? --> academic-pipeline (Stage 2.5 entry)
+  |      +--> No draft yet? --> academic-paper first
+  |
+  +--> "I need to revise based on feedback"
+  |      |
+  |      +--> From AI reviewers (pipeline)? --> Continue pipeline (Stage 4)
+  |      +--> From real journal reviewers? --> academic-pipeline Stage 4 entry (External Review)
+  |
+  +--> "I want the full treatment (research to publication)"
+         |
+         +--> academic-pipeline (Stage 1 entry)
+```
+
+---
+
+## Pipeline Stage Entry Points
+
+For users entering the pipeline mid-stream, this table clarifies what materials are needed:
+
+| Entry Point | Required Materials | What Gets Skipped | Integrity Implications |
+|------------|-------------------|-------------------|----------------------|
+| Stage 1 (RESEARCH) | None | Nothing | Full pipeline |
+| Stage 2 (WRITE) | RQ Brief + Bibliography | Stage 1 | Full pipeline from Stage 2 |
+| Stage 2.5 (INTEGRITY) | Paper draft | Stages 1-2 | Integrity check runs on provided draft |
+| Stage 3 (REVIEW) | Verified paper + integrity report | Stages 1-2.5 | User must provide integrity evidence |
+| Stage 4 (REVISE) | Paper + review comments | Stages 1-3 | Pipeline runs Stage 4 -> 3' -> 4' -> 4.5 -> 5 |
+| Stage 5 (FINALIZE) | Paper + integrity pass report | Stages 1-4.5 | Must show Stage 4.5 passed |
+
+---
+
+## Anti-Patterns
+
+These are common workflow mistakes to avoid:
+
+| Anti-Pattern | Problem | Correct Approach |
+|-------------|---------|-----------------|
+| Skipping research | Paper lacks evidence depth | Always do at least deep-research quick |
+| Writing then researching | Confirmation bias in source selection | Research first, write second |
+| Reviewing before integrity check | Wasted review effort on fabricated citations | Always Stage 2.5 before Stage 3 |
+| Accepting all reviewer comments blindly | May introduce inconsistencies or weaken valid arguments | Use External Review Protocol's strategic coaching |
+| Running pipeline for a 1-page abstract | Overhead far exceeds benefit | Use academic-paper full directly |
+| Using fact-check mode for literature review | Different purpose and methodology | Use deep-research full or systematic-review |

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

@@ -0,0 +1,132 @@
+# Passport as Reset Boundary (v3.6.3)
+
+## Purpose
+
+Defines how `pipeline_orchestrator_agent` converts FULL checkpoints into reset boundaries when `ARS_PASSPORT_RESET=1` is set. This is the authoritative protocol; any divergent behavior in agent prompts is a bug.
+
+## When this protocol applies
+
+| Flag state | Mode | Behavior at FULL checkpoint |
+|------------|------|-----------------------------|
+| `ARS_PASSPORT_RESET` unset / `=0` | any | Continuation (pre-v3.6.3 default). No reset tag emitted. |
+| `ARS_PASSPORT_RESET=1` | `systematic-review` | **Mandatory reset** at every FULL checkpoint. |
+| `ARS_PASSPORT_RESET=1` | any other mode | **Strong-default reset** at every FULL checkpoint. User `continue` response overrides back to continuation for the next stage only. |
+
+MANDATORY checkpoints (integrity Stage 2.5 / 4.5, review decisions, Stage 5 finalization) are orthogonal: reset can co-occur with MANDATORY. SLIM checkpoints never trigger reset.
+
+## The reset boundary protocol
+
+When the orchestrator reaches a FULL checkpoint with the flag ON:
+
+1. **Freeze state.** `state_tracker` stages the current stage's deliverables and prepares a new `kind: boundary` ledger entry — but does NOT yet write `hash` (append happens in Step 2 after hash is known).
+2. **Compute hash.** Canonical byte serialization is normative; two implementations must produce the same bytes from the same ledger:
+   - Each entry is serialized as **JSON Canonical Form (RFC 8785 / JCS)**: UTF-8, no insignificant whitespace, keys sorted ASCII-ascending at every object level, numbers in JCS canonical form.
+   - Entries are separated by a single `\x0a` (LF) byte. The first entry has no leading separator; the last entry has a trailing LF.
+   - The new entry is serialized with `hash` set to the canonical placeholder `"000000000000"` and all other fields populated; concatenated AFTER every prior entry (each already carrying its own finalized `hash`).
+   - SHA-256 the byte stream. Take the lowercase hex digest. Take the first 12 characters. That IS the new entry's `hash`. Overwrite the placeholder before appending to the ledger.
+   - **Iron rule (see §Iron rules 2 + 7):** never hash an entry that already contains a non-placeholder `hash` for itself; never reorder prior entries; never include `kind: resume` entries in a boundary hash computation.
+3. **Emit reset tag.** In the checkpoint notification block, append a machine-stable line:
+   ```
+   [PASSPORT-RESET: hash=<hash>, stage=<completed>, next=<next>]
+   ```
+4. **Emit human instruction.** In the same checkpoint notification, include a `### Resume Instruction` subsection with:
+   - Passport file path (absolute or repo-relative)
+   - The exact resume command the user pastes into a fresh session:
+     ```
+     resume_from_passport=<hash>
+     ```
+   - A one-line note that the next stage should be invoked in a fresh Claude Code session to realize the token-savings intent.
+5. **Halt after emission.** The orchestrator stops after emitting the reset boundary and awaits resume in a fresh session.
+6. **In-session override (non-SR modes).** If the user pastes `continue` in the same session, the orchestrator acknowledges but treats the passport as the only input to the next stage. Working-memory content from prior turns is non-authoritative and must not be replayed.
+7. **Systematic-review hard stop.** In `systematic-review` mode, in-session continuation is refused outright. The orchestrator repeats the Resume Instruction and asks the user to start a fresh session.
+8. **Pending MANDATORY decision.** If the reset co-occurs with a MANDATORY checkpoint that requires a user decision with multiple valid branches (e.g., Stage 3 review outcome: `revise` / `restructure` / `abort`; Stage 5 finalization format choice), the orchestrator sets `pending_decision` on the ledger entry. Each option is an object with required fields `value` (branch identifier) and `next_stage` (stage to route to, or `null` to terminate), plus optional `next_mode` for downstream mode override. On resume, the orchestrator looks up the user's chosen `value` in `options[]` and uses that entry's `next_stage`/`next_mode` to determine actual routing. The boundary entry's `next` field is populated as a best-guess default only; it is advisory and is superseded by the matched option's `next_stage` at resume time. `next` must NOT be used to auto-advance when `pending_decision` is present. `next` MAY be `null` when all branches of `pending_decision` terminate or when no sensible default exists.
+
+## `resume_from_passport` mode contract
+
+Invocation shape (prompt-layer, user-pasted or auto-dispatched in a new session):
+
+```
+resume_from_passport=<hash> [stage=<stage_number_or_name>] [mode=<downstream_mode>]
+```
+
+Required:
+- `resume_from_passport=<hash>` — must match the 12-hex `hash` from a `[PASSPORT-RESET: ...]` tag emitted in a prior session. Orchestrator verifies the hash against the passport ledger on disk; mismatch is a hard error.
+
+Optional:
+- `stage=<stage_number_or_name>` — override the `next=` recorded in the reset tag. Useful when the user wants to re-run a stage rather than proceed. If omitted, the orchestrator uses `next=` from the reset tag.
+- `mode=<downstream_mode>` — override the mode of the next stage (e.g., swap `full` for `quick`). Orchestrator validates the override against Mode Advisor rules.
+
+Orchestrator obligations on resume:
+- Locate the target `kind: boundary` entry by matching `hash`. Hard error if no match, or if a later `kind: resume` entry already carries `consumes_hash == <hash>` (double-resume is forbidden).
+- Do NOT ask the user to re-summarize prior stages; the passport is authoritative. Load artifacts by reference (paths or IDs recorded in the entry).
+- Honor the `verification_status` field. If `STALE` or `UNVERIFIED`, display a warning and prompt the user to re-verify before continuing. If `VERIFIED`, proceed without prompting.
+- If `pending_decision` is set on the ledger entry, re-prompt the user for that decision BEFORE invoking any downstream stage. Display `pending_decision.question` and each option's `value`. After the user picks, look up the matching entry in `options[]` by `value`, then use that entry's `next_stage` and `next_mode` to determine actual routing. Record the chosen `value` as `chosen_branch` on the new `resume` entry. `next` on the boundary entry is advisory and is superseded by the matched option's `next_stage`. A user-supplied `stage=<n>` override on the resume command does NOT satisfy `pending_decision` — the decision prompt always fires when `pending_decision` is present. CLI `stage=`/`mode=` overrides still win over option routing if the user supplies them after the decision prompt.
+- Emit a `### Resume Acknowledged` section at the start of the new session with: hash, source session `session_marker` + `generated_at`, recovered stage, and next-stage plan.
+- Append a new `kind: resume` entry to `reset_boundary[]` with `consumes_hash = <hash>`, fresh `generated_at` and `session_marker`, and (if applicable) `chosen_branch` + `user_override`. This is how resume leaves an append-only trace and lets downstream readers compute `awaiting_resume` from the ledger alone.
+
+## Append-only ledger semantics
+
+Material Passport ledger (`compliance_history[]` + new `reset_boundary` entries) is append-only:
+- Every checkpoint with the flag ON appends one `reset_boundary` entry of kind `boundary` under Schema 9's `reset_boundary` field.
+- Re-running a stage (e.g., after a review rejection) appends a new entry with `version_label` bumped (`v1.0 → v1.1-revised`).
+- `resume_from_passport` consumption appends one entry of kind `resume` to the same ledger, carrying the `consumes_hash` pointer to the `boundary` entry it resolves. This is how resume leaves a trace — no mutation of prior entries.
+- Prior entries are never deleted, reordered, or mutated.
+- Stage-re-run cases produce adjacent entries for the same `stage`; both are preserved.
+
+### Computing `awaiting_resume` from the ledger
+
+A `boundary` entry with hash `H` is considered **awaiting resume** iff no `resume` entry exists later in the ledger with `consumes_hash == H`. Downstream readers (state machine, observers, external audit tools) compute this by a single pass over `reset_boundary[]` — no out-of-band state required.
+
+## Concurrency model
+
+Resume consumption is a three-step read-modify-write on the passport ledger:
+
+1. Read the ledger and locate the target `boundary` entry by `hash`.
+2. Verify no `resume` entry later in the ledger carries `consumes_hash` equal to that hash.
+3. Append a new `resume` entry.
+
+Without coordination, two processes can complete step 2 in parallel before either reaches step 3, both observe "no prior resume", and both append. The append-only-ledger invariant survives, but the "one boundary, one resume" invariant breaks. To prevent this, every compliant orchestrator implementation MUST hold an exclusive advisory lock on the passport's stable sidecar `.<passport-basename>.lock` for the entire read-check-append sequence. Every ARS passport writer, including the #743 inquiry-ledger transaction, uses that same sidecar domain.
+
+**POSIX requirement.** On POSIX systems, open or create the adjacent sidecar as a regular non-symlink file and take an `fcntl` exclusive advisory lock on that stable descriptor (`fcntl.flock(fd, fcntl.LOCK_EX)` in Python, `flock(fd, LOCK_EX)` in C). Acquire before step 1, release after step 3 is durable, and do not release between steps. Locking the passport inode is forbidden: compliant transactions may atomically replace that inode, which would split writers across two lock domains.
+
+**Lock timeout.** Acquisition MUST use a bounded timeout not exceeding 60 seconds; 30 seconds is RECOMMENDED. The passport write is a few-KB append and fsync, so this bound is two orders of magnitude above any reasonable write latency. 60 s is the hard ceiling because a user waiting longer will assume the orchestrator hung; 30 s leaves slack for slow fsync on NFS or sandboxed filesystems. A timeout at this scale indicates a stuck or crashed peer rather than lock contention. Timeout is a hard error; the orchestrator surfaces it to the user with a "passport locked by another session" message and does NOT retry automatically.
+
+**Non-POSIX (Windows).** `fcntl` is unavailable. Compliant implementations use `msvcrt.locking` with `LK_NBLCK`/`LK_LOCK`, or a cross-platform library like `portalocker`. Implementations that cannot provide OS-level exclusion MUST fail loudly on resume with a "concurrency protection unavailable on this platform" error and refuse to consume the boundary. Silent best-effort is forbidden.
+
+**Compatibility amendment (2026-08-24, #743).** Implementations built from the earlier text that lock the passport inode are not concurrency-compatible with atomic passport replacement. They must be upgraded before running alongside a sidecar-aware writer; acquiring both locks cannot bridge the rename race. A current implementation must never advertise mixed-version writer safety.
+
+**Observability.** The sidecar lock is advisory: external readers and pre-amendment writers that do not honor the protocol can still access the passport. Only current cooperating writers get safety. This is acceptable because the passport is intended to be consumed by one tool family (ARS-compatible orchestrators), and the mixed-version exclusion is explicit.
+
+## Iron rules
+
+1. Flag OFF is pre-v3.6.3 behavior, bit-for-bit.
+2. Ledger is append-only. No exception, no "clean up" operation.
+3. Reset tag is the sole machine-stable handoff. Human-readable `### Resume Instruction` is for user ergonomics; consumers parse the tag.
+4. `systematic-review` with flag ON refuses in-session continuation across FULL checkpoints.
+5. Hash mismatch on resume is a hard error; orchestrator never proceeds on a guessed or coerced hash.
+6. MANDATORY checkpoints are not downgraded by reset; they co-occur.
+7. Hash is computed over the entry with the canonical placeholder `"000000000000"` in the `hash` field, serialized per the byte rules in §"The reset boundary protocol" step 2. `kind: resume` entries are never included in a `boundary` hash computation — the hash covers only prior `boundary` entries plus the new boundary entry itself. Any other convention (exclude-field, variable-length placeholder, post-hoc mutation, including resume entries) breaks cross-implementation interoperability and is forbidden.
+8. A `boundary` entry is "consumed" only by appending a `resume` entry with matching `consumes_hash`. If a `boundary` entry has `pending_decision` set, the orchestrator MUST re-prompt the user on resume and MUST NOT auto-advance using `next`. Each option in `pending_decision.options[]` carries its own routing (`next_stage`/`next_mode`); the boundary entry's `next` field is advisory only and MAY be `null` when all branches terminate or no sensible default exists. Actual routing on resume comes from the matched option's `next_stage`/`next_mode`, not from the boundary `next` field.
+9. Resume consumption and every other passport read-modify-write MUST hold the exclusive advisory lock on the adjacent stable `.<passport-basename>.lock` sidecar for the entire operation. Locking the replaceable passport inode is non-conforming. Releasing the sidecar lock between the no-prior-resume check and the resume-entry append reopens the double-resume race the rule exists to prevent. Non-POSIX implementations that cannot provide OS-level exclusion MUST refuse to resume rather than degrade silently.
+
+## Interaction with existing features
+
+- **Collaboration Depth Observer (v3.5.0):** fires on FULL/SLIM as before. Observer output is included in the checkpoint notification regardless of reset state. Observer state does NOT carry across resets; each fresh session observes only its own stage.
+- **Compliance agent (v3.4.0):** `compliance_history[]` remains append-only and is consumed from the passport on resume. No change to Schema 12.
+- **Sprint contract (v3.6.2):** reviewer sprint contracts load from the passport on resume (Phase 1 paper-content-blind stage remains valid across the reset boundary because the contract + paper metadata are carried in the passport).
+- **Socratic reading probe (v3.5.1):** reading probe fires at most once per session. Across a reset boundary, the probe counter resets — the next session may fire its own probe. This is by design: each session is its own Socratic unit.
+- **Audit artifact ledger (v3.6.7):** Schema 9's `audit_artifact[]` ledger ([`shared/handoff_schemas.md`](../../shared/handoff_schemas.md) "Audit Artifact Ledger") is also append-only and survives reset by the same mechanism as `reset_boundary[]` and `compliance_history[]` — the passport carries it intact across the session break. On `resume_from_passport`, the orchestrator does NOT replay prior audit runs; it re-verifies on demand at each gate transition. Per [`docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md`](../../docs/design/2026-04-30-ars-v3.6.7-step-6-orchestrator-hooks-spec.md) §5.6, the orchestrator first runs Path A — selecting the latest `audit_artifact[]` entry matching the current gate's `(stage, agent, deliverable_sha)` tuple by `verified_at` — after the §5.6 A1.5 superseding-proposal preflight against `<output-dir>` (which preempts the selected entry if a higher-`verdict.round` proposal exists, e.g., from a between-session `another_round` wrapper run). Path A then re-runs the §5.2 verification sequence against the selected entry: L2-1 / L3-1 file-existence + schema preconditions over `artifact_paths.{jsonl,sidecar}`, followed by the eleven Layer 2 + Layer 3 gating checks (L2-2 / L2-3 / L2-4 / L2-5 + L3-2 through L3-8) over the JSONL stream, sidecar metadata, and the current on-disk deliverable + bundle files. After the §5.2 sequence passes, §5.6 Path A step A5 separately validates the verdict file against `audit_verdict.schema.json` and reconciles its mirror in the persisted entry (the verdict file is NOT inside the eleven §5.2 gates — it is A5's responsibility). The selected entry falls through to Path B (fresh proposal merge) on any §5.2 precondition / gate failure or A5 verdict-validation failure: e.g., a missing or schema-invalid jsonl/sidecar (L2-1 / L2-2 / L3-1), the JSONL `thread.started` `thread_id` drifting from the sidecar's `stream.jsonl_thread_id` (L3-2), the on-disk deliverable's SHA-256 drifting from the entry's `deliverable_sha` (L3-3, the canonical "deliverable mutated since audit" trigger), the bundle manifest hash recomputed over current primary + supporting + template files drifting from `bundle_manifest_sha` (L3-4), or the verdict file failing its schema/mirror check at A5. Stale or non-selected historical entries remain in the ledger as audit history and do NOT block unrelated future transitions; only the gate currently being audited must reach a fresh PASS / MINOR / MATERIAL verdict. This closes the post-reset attack surface where a forged passport carries `verified_at` / `verified_by` timestamps but no recoverable evidence behind them.
+
+## What this protocol does NOT do
+
+- Does not define Zotero / Obsidian / folder-scan adapter shapes (defined in [`academic-pipeline/references/adapters/overview.md`](adapters/overview.md) from v3.6.4+).
+- Does not define `literature_corpus` entry shape (defined in [`shared/contracts/passport/literature_corpus_entry.schema.json`](../../shared/contracts/passport/literature_corpus_entry.schema.json) from v3.6.4+).
+- Does not add runtime CLI tooling. Passport resolution is the user's responsibility — the orchestrator loads from the path the user provides.
+- Does not claim specific token savings numbers. Empirical measurement goes in `docs/PERFORMANCE.md` only after real runs.
+
+## Related references
+
+- [`shared/handoff_schemas.md`](../../shared/handoff_schemas.md) — Schema 9 definition
+- [`academic-pipeline/agents/pipeline_orchestrator_agent.md`](../agents/pipeline_orchestrator_agent.md) — orchestrator integration
+- [`academic-pipeline/references/pipeline_state_machine.md`](pipeline_state_machine.md) — state transitions
+- [`docs/PERFORMANCE.md`](../../docs/PERFORMANCE.md) — long-running session guidance