psyclaw 0.27.22 → 0.28.0

package/vendor/ars/shared/mode_spectrum.md

@@ -0,0 +1,57 @@
+# Mode Spectrum: Fidelity vs Originality
+
+**Status**: v3.2
+**Source**: Lu et al. (2026, Nature 651:914-919) Figure 1c — template-based mode produces higher-quality, lower-variance papers; template-free mode produces more diverse outputs but lower mean quality and higher variance. ARS maps this finding onto its own mode taxonomy.
+
+---
+
+## Why this spectrum exists
+
+Not all modes should treat templates and examples the same way. A `systematic-review` needs rigid structure (PRISMA checklist, predefined sections) — templates are load-bearing. A `socratic` dialogue needs room to wander — heavy templates kill exploration.
+
+Lu et al.'s template-based vs template-free comparison gives us a language for this trade-off: **fidelity** (reproducible, template-heavy, lower variance) vs **originality** (exploratory, template-light, higher variance, higher ceiling on novelty).
+
+ARS modes fall on a spectrum between these poles. This table is the reference for decisions about:
+- How much template/example material to load at mode start
+- Whether to inline templates in SKILL.md or load from sub-files on demand (v3.1 Phase 3)
+- Whether to suggest the mode when the user's goal is "predictable output" vs "creative exploration"
+
+---
+
+## Mode spectrum table
+
+| Skill | Mode | Spectrum position | Template load | Rationale |
+|---|---|---|---|---|
+| deep-research | `systematic-review` | Fidelity | Heavy | PRISMA protocol, predefined search strategy, reproducible steps |
+| deep-research | `lit-review` | Fidelity | Heavy | Structured annotated bibliography, fixed output format |
+| deep-research | `three-way-scan` | Fidelity | Medium | Fixed WHY/HOW/WHAT per-paper frame + cross-paper synthesis, lighter than lit-review |
+| deep-research | `fact-check` | Fidelity | Heavy | Claim → evidence → verdict pipeline, no room for drift |
+| deep-research | `quick` | Fidelity | Heavy | Time-boxed brief, fixed 3-section format |
+| deep-research | `review` | Balanced | Medium | Review has structure but allows domain-specific adaptation |
+| deep-research | `full` | Balanced | Medium | Structured output but methodology selection is exploratory |
+| deep-research | `socratic` | Originality | Light | User-led dialogue, templates constrain exploration |
+| academic-paper | `full` | Balanced | Medium | Section templates loaded, but writing adapts to argument |
+| academic-paper | `outline-only` | Balanced | Medium | Structure templates needed, but outline is creative |
+| academic-paper | `revision` | Fidelity | Heavy | R&R tracking template, point-by-point responses |
+| academic-paper | `revision-coach` | Balanced | Medium | Coaching is semi-structured; roadmap template loaded |
+| academic-paper | `abstract-only` | Fidelity | Heavy | Fixed abstract structure (background/method/results/conclusion) |
+| academic-paper | `lit-review` | Fidelity | Heavy | Annotated bibliography format |
+| academic-paper | `format-convert` | Fidelity | Heavy | Format conversion is purely mechanical |
+| academic-paper | `citation-check` | Fidelity | Heavy | Citation audit is checklist-driven |
+| academic-paper | `plan` | Originality | Light | Socratic planning dialogue, no forced chapter sequence |
+| academic-paper | `disclosure` (v3.2) | Fidelity | Heavy | Venue policy database → templated output |
+| academic-paper | `rebuttal-audit` | Fidelity | Heavy | Per-comment coverage checklist against an existing rebuttal draft, advisory QA |
+| academic-paper-reviewer | `full` | Balanced | Medium | Review rubric loaded, but reviewer perspectives are dynamic |
+| academic-paper-reviewer | `re-review` | Fidelity | Heavy | R&R traceability matrix, checklist-driven |
+| academic-paper-reviewer | `quick` | Fidelity | Heavy | Fixed Journal-Fit Reviewer quick-assessment format |
+| academic-paper-reviewer | `methodology-focus` | Fidelity | Heavy | Focused on statistical/methods rubric |
+| academic-paper-reviewer | `guided` | Originality | Light | Socratic dialogue, adaptive to what the user needs |
+| academic-paper-reviewer | `calibration` (v3.2 + #611) | Fidelity | Heavy | Explicit 3×1 directional tier or default 5× ensemble (3× override), fixed reporting boundaries |
+
+---
+
+## Mode recommendation
+
+- User wants "predictable" / "consistent" → suggest **Fidelity** modes
+- User wants to "explore" / "think through" → suggest **Originality** modes
+- Unclear → suggest **Balanced** modes as default

package/vendor/ars/shared/model_tiering.md

@@ -0,0 +1,83 @@
+# Model Tiering (#517)
+
+Opt-in routing of ARS agents to different model tiers, exploiting intelligence asymmetry across pipeline tokens (Lance Martin, "Cost effective harnesses with Fable", 2026-07-10: an advisor-checkpoint configuration reached ~90% of frontier-solo quality at ~34% of token cost; delegation pays only when workers absorb enough tokens to offset the per-handoff coordination cost).
+
+**This is entirely optional.** When `ARS_MODEL_TIERING` is absent, every agent runs on the session model (`model: inherit`) — byte-equivalent to pre-#517 behavior. Same opt-in philosophy as `terminal_policies`: absence of the switch means nothing changes.
+
+## The switch
+
+```bash
+# Pick ONE direction, or leave unset (default: session model everywhere).
+export ARS_MODEL_TIERING="economy"        # frontier session: execution agents step down one tier (floor: Opus-class)
+export ARS_MODEL_TIERING="quality-boost"  # below-frontier session: judgment agents step UP to the frontier tier at the gates
+```
+
+Any other value is warned once (one line) and treated as absent — misconfiguration must never silently change models.
+
+## Relative tiers, never hard-pinned ids
+
+Tier positions are expressed relative to the session: "session model", "frontier tier of the session's model family", "one tier below the session model", "the Opus-class floor". Concrete model ids are NEVER pinned in this mechanism's FILES — a hard-pinned floor becomes a downgrade ceiling on the next model generation (the v3.7.0 `opus` command floor, retired in the 2026-06 Fable 5 harness pass, is the precedent).
+
+### Resolving a tier at dispatch time
+
+The no-hard-pinning rule is about what lives in the repo, not about the dispatch call — a subagent invocation ultimately needs a model value the runtime accepts (an alias such as `opus`/`sonnet`, or a concrete current-generation id). The dispatching session resolves the relative target at the moment of dispatch:
+
+1. Determine the session's model family and current-generation lineup (from the runtime's own model information — never from a list stored in this repo).
+2. Map the direction to a target: `economy` → the tier exactly one below the session model, bounded below at the Opus-class tier; `quality-boost` → the family's frontier tier.
+3. Pass whatever identifier the runtime accepts for that target (alias preferred where supported; otherwise the current generation's concrete id). The concrete value exists only in that ephemeral call — it is never written into agent files, manifests, or this doc.
+4. If the session cannot resolve the target (unknown lineup, runtime exposes no model choice): the direction is a no-op for that call — announce `[MODEL-TIERING: could not resolve target tier — ran on the session model]` once per run. Fail-open, never a guessed id.
+
+## Direction 1 — `quality-boost` (for sessions below the frontier tier)
+
+- **Who:** judgment-type agents (table below) **when dispatched at a checkpoint surface**: the Stage 2.5 / 4.5 integrity gates (`integrity_verification`, `compliance_agent`); the Stage 4→5 claim–ref alignment audit (`claim_ref_alignment_audit` — dispatched only when `ARS_CLAIM_AUDIT=1`, so this surface exists only on opted-in runs); and the final-review surfaces (Stage 3 full panel: `eic`, the three reviewers, `devils_advocate_reviewer`, `editorial_synthesizer`). Stage 3' uses three dedicated contract judgment calls plus any scoped Phase 2B′ verification calls; when `quality-boost` applies, the orchestrating layer dispatches those checkpoint calls at the frontier tier directly. They are protocol calls, not agent-manifest identities; `field_analyst` remains execution-type and is unaffected except for the visibly marked card-regeneration fallback.
+- **What:** dispatch those calls AT the frontier tier of the session's model family — a jump to the frontier, however many tiers away the session sits, not a single-increment step. Everything else stays on the session model.
+- **Why there:** the measured value of a stronger model concentrates at mid-task re-ranking and verification, not upfront planning.
+- **No-op condition:** a session already at the frontier tier has nothing to upgrade to — announce `[MODEL-TIERING: quality-boost is a no-op at the frontier tier]` once and proceed. quality-boost NEVER downgrades anything.
+
+## Direction 2 — `economy` (for frontier-tier sessions)
+
+- **Who:** execution-type agents (table below), at every dispatch.
+- **What:** dispatch exactly ONE tier below the session model, **floor: the Opus-class tier, never Sonnet-class**. Judgment-type agents stay on the session model. This is a documented quality-for-cost trade: the ~90%/34% numbers above came from ML-tuning tasks, not scholarly writing, and academic-prose tolerance is untested — hence the conservative floor.
+- **No-op condition:** a session already at or below the Opus-class floor has nowhere lower to go — announce `[MODEL-TIERING: economy is a no-op at or below the floor]` once and proceed. economy NEVER touches judgment-type agents.
+- **Highest-risk downgrade:** `draft_writer` is the suite's highest-token and therefore highest-savings agent, and also its most quality-sensitive downgrade point (it writes the prose the whole pipeline exists to produce). The one-tier floor bounds the risk; if measured quality degrades, the remedy is reclassifying it to judgment-type in `scripts/model_tiering_manifest.json` + this table — one place, no agent-file edit.
+
+## Where the decision is made
+
+A different tier is physically selectable only where a role runs as a **separate subagent** (the built-in Agent tool's `model` parameter, or a plugin-exposed agent). Today many ARS roles execute **inline** in the main session as prompt templates (see `docs/PERFORMANCE.md` § "v3.7.0 Plugin agents and model routing") — inline execution has no per-role model choice. The mechanism therefore works like this:
+
+- **Flag unset:** nothing changes — roles execute exactly as they do today (inline or subagent, session model). No role is spun out, no dispatch shape changes; byte-equivalent.
+- **A direction applies to a role:** the session dispatches that role as a subagent pinned to the target tier — including roles that would otherwise have executed inline (the dispatch-as-subagent IS the mechanism for them).
+- **Dispatching as a subagent is not possible in the runtime** (no Agent tool available, or the role's step is inseparable from the main conversation): the role runs inline on the session model and the direction is a no-op for that call — announce `[MODEL-TIERING: <role> ran inline on the session model — tiering not applicable]` once per run. Fail-open, never a silently wrong model claim.
+
+Agent files are untouched — frontmatter stays `model: inherit`, and this mechanism never edits an agent file (the sha256-locked `bibliography_agent.md` included). The machine-readable classification lives in `scripts/model_tiering_manifest.json`; `scripts/check_model_tiering.py` fails CI when an agent file exists without a classification (drift guard), when a tier value is invalid, or when this table and the manifest disagree.
+
+## Prompt-caching guidance (article item 4)
+
+When a tiering direction is active, route repeated same-stage calls to the SAME worker so its cache accumulates where the protocol permits. Do not reuse Stage 3 `eic` or `editorial_synthesizer` workers for Stage 3' contract calls: their first-round agent prompts are not the dedicated three-gate protocol. A provider-level prompt cache may be shared across separate Stage 3' calls only when the Phase 1 / 2A / 2B withholding boundaries remain intact; cached transport never turns them into one conversational context. `field_analyst` is not re-invoked on the normal Stage 3' path because the Round-1 cards travel as data; only the visible regeneration fallback may dispatch it. With the flag unset this guidance imposes nothing: default behavior stays byte-equivalent, dispatch shapes included.
+
+## Classification table (39 agents; frozen 2026-07-11, #517)
+
+One tier per agent; membership changes require editing BOTH this table and `scripts/model_tiering_manifest.json` (the lint pins them together).
+
+### Judgment-type (26) — session model; quality-boost upgrade candidates at checkpoint surfaces
+
+| Skill | Agents |
+|---|---|
+| deep-research (10) | `socratic_mentor`, `research_question`, `research_architect`, `synthesis`, `devils_advocate`, `editor_in_chief`, `ethics_review`, `risk_of_bias`, `meta_analysis`, `source_verification` |
+| academic-paper (6) | `socratic_mentor`, `argument_builder`, `structure_architect`, `peer_reviewer`, `revision_coach`, `literature_strategist` |
+| academic-paper-reviewer (6) | `eic`, `methodology_reviewer`, `domain_reviewer`, `perspective_reviewer`, `devils_advocate_reviewer`, `editorial_synthesizer` (mechanical by v3.6.2 design but emits the final decision letter — judgment-type conservatively until data says otherwise) |
+| academic-pipeline (3) | `pipeline_orchestrator`, `claim_ref_alignment_audit`, `integrity_verification` |
+| shared (1) | `compliance` (holds tier-based block authority) |
+
+### Execution-type (13) — economy-direction downgrade candidates (one tier, floor Opus-class)
+
+| Skill | Agents |
+|---|---|
+| deep-research (4) | `bibliography` (citation existence is handled by the deterministic verification gate, so the lookup layer does not depend on this agent's tier), `timeline_extraction`, `report_compiler`, `monitoring` |
+| academic-paper (6) | `intake`, `draft_writer` (highest-savings / most quality-sensitive — see Direction 2), `abstract_bilingual`, `citation_compliance`, `visualization`, `formatter` (STAMP-ONLY by design) |
+| academic-paper-reviewer (1) | `field_analyst` |
+| academic-pipeline (2) | `collaboration_depth` (advisory-only, never blocks), `state_tracker` |
+
+## Interaction with cross-model verification
+
+Orthogonal layers: `ARS_CROSS_MODEL` chooses an EXTERNAL verifier for specific checks (see `shared/cross_model_verification.md`); `ARS_MODEL_TIERING` chooses which Anthropic tier runs each ARS agent. They compose without coordination — e.g. an economy session still sends cross-model integrity samples if `ARS_CROSS_MODEL` is set, and the #518 blind disagreement checkpoints compare against the primary decision whatever tier produced it.

package/vendor/ars/shared/policy_data/nature_policy.md

@@ -0,0 +1,56 @@
+# Nature Portfolio — Canonical AI Policy Source
+
+**Status**: Source of truth for Nature substantive policy content cited by both:
+
+1. `academic-paper/references/policy_anchor_table.md` — Nature anchor (#108 policy-anchor track, verbatim quotes per 16 fields)
+2. `academic-paper/references/venue_disclosure_policies.md` — Nature venue entry (v3.2 venue track, summary form)
+
+**Provenance**: extracted from the Nature Portfolio AI editorial policy page (`https://www.nature.com/nature-portfolio/editorial-policies/ai`), wayback snapshot `nature:wayback=20260513075542` (sha256 `cf691cba…`). Section structure: `§AI authorship`, `§Generative AI images`, `§AI use by peer reviewers`, `§Editorial use`. ARS author-side matrix covers `§AI authorship` + `§Generative AI images` only.
+
+**G4 invariant** (Decision Doc §4.3): edits to Nature substantive policy content must go through **this file** first; both downstream consumers (policy_anchor_table.md Nature section and venue_disclosure_policies.md Nature entry) re-cite from here. Direct edits to either consumer that change Nature substantive content are non-conformant.
+
+**Dedup lint**: `verify_nature_dedup_with_venue()` in `scripts/check_policy_anchor_table.py` confirms (a) this file exists, (b) both consumers reference the path `shared/policy_data/nature_policy.md` as their canonical pointer.
+
+---
+
+## Nature substantive policy quotes (verbatim, source-of-truth)
+
+### §AI authorship — text-use policy
+
+> "Large Language Models (LLMs), such as ChatGPT, do not currently satisfy our authorship criteria. Notably an attribution of authorship carries with it accountability for the work, which cannot be effectively applied to LLMs. Use of an LLM should be properly documented in the Methods section (and if a Methods section is not available, in a suitable alternative part) of the manuscript."
+
+> "In all cases, there must be human accountability for the final version of the text and agreement from the authors that the edits reflect their original work."
+
+### §AI authorship — copyediting carve-out
+
+> "The use of an LLM (or other AI-tool) for "AI assisted copy editing" purposes does not need to be declared."
+
+The carve-out predicate (paraphrased policy framing, partial verbatim): AI-assisted improvements to human-generated texts for readability and style — explicitly **excluding** generative editorial work and autonomous content creation.
+
+### §Generative AI images — image-rights regime
+
+> "Springer Nature journals are unable to permit its use for publication."
+
+> "All exceptions must be labelled clearly as generated by AI within the image field."
+
+Carve-outs (per Nature policy text, three categories): figures using AI to enhance or compose existing scientific data; AI-generated images that are themselves the subject of academic study (e.g., AI-art history); image-generation tools used to produce illustrations clearly marked as conceptual rather than scientific.
+
+### §Generative AI images — non-generative ML caption rule
+
+> "should be disclosed in the relevant caption upon submission"
+
+---
+
+## Consumer integration notes
+
+- `policy_anchor_table.md` Nature anchor: extracts these quotes per 16-field matrix (3 explicit-mandate + 2 explicit-recommend + 4 implicit + 7 not-addressed).
+- `venue_disclosure_policies.md` Nature entry: summarises the same source as venue-track guidance (Methods placement default, full responsibility statement requirement, no AI authorship).
+- Renderer (LLM-prose): when the user selects either `--venue=Nature` or `--policy-anchor=nature`, the renderer cites this file's verbatim quotes in the emitted disclosure paragraph. Both tracks share the substantive policy content; placement (Methods vs anchor-specific) is the track-specific rendering decision.
+
+---
+
+## Related
+
+- Discovery doc §4.5 — Nature anchor matrix with cross-anchor observation
+- Decision Doc §2.4 G4 (renderer target) + §4.3 G4 invariant (Nature dedup)
+- Impl spec §3 concern #5 resolution (hybrid image output channel)

package/vendor/ars/shared/prisma_trAIce_protocol.md

@@ -0,0 +1,157 @@
+---
+title: PRISMA-trAIce Protocol (v3.4.0 snapshot)
+snapshot_date: "2025-12-10"
+upstream_source: "https://github.com/cqh4046/PRISMA-trAIce"
+upstream_version_commit: "main"
+update_policy: "Manual sync. CI freshness check runs weekly; drift emits warning, not merge block."
+citation: "Holst D, et al. Transparent Reporting of AI in Systematic Literature Reviews: Development of the PRISMA-trAIce Checklist. JMIR AI. 2025. doi:10.2196/80247"
+---
+
+# PRISMA-trAIce Protocol
+
+Verbatim snapshot of the 17-item PRISMA-trAIce checklist from the GitHub canonical source (`cqh4046/PRISMA-trAIce`), dated 2025-12-10, with per-item ARS check procedures and tier-based behaviour.
+
+**Used by**: `compliance_agent` (Task 8), `scripts/check_prisma_trAIce_freshness.py` (Task 12).
+
+> ⚠️ **Upstream sync warning.** If `cqh4046/PRISMA-trAIce` updates, a freshness CI check emits an annotation but does not block merges. Maintainers must manually re-sync this file and bump `snapshot_date` + `upstream_version_commit`. See `scripts/check_prisma_trAIce_freshness.py`.
+
+## Status disclaimer
+
+**PRISMA-trAIce is a foundational proposal, not a Delphi-consensus standard.** Holst et al. (2025) explicitly characterize their checklist as a "well-reasoned albeit preliminary guideline," developed via systematic adaptation of PRISMA 2020 rather than "a formal, broad-based Delphi study or consensus meeting," and note that the 17 items "have not yet been empirically validated across diverse research contexts." The authors frame PRISMA-trAIce as a "foundational proposal" and a "living standard" intended for the research community to "immediately adopt and refine."
+
+ARS adopts the authors' Mandatory / Highly Recommended / Recommended / Optional tier system as defined upstream, and treats Mandatory failures as Stage 2.5 / 4.5 blocks (per the Tier legend below). This block-on-Mandatory choice follows the authors' own argument that the risk of non-transparent AI use outweighs the risk of adopting a preliminary guideline. Future revisions of the upstream living standard are pulled in via the existing freshness CI (`scripts/check_prisma_trAIce_freshness.py`).
+
+> See Holst D, et al. JMIR AI. 2025. doi:[10.2196/80247](https://doi.org/10.2196/80247) — Discussion and Limitations sections.
+
+## Tier legend
+
+| Tier | Behaviour when item FAILs |
+|---|---|
+| Mandatory (M) | **Block**: pipeline halts; user must backfill, retreat a stage, or use the 3-round override ladder (see [`shared/compliance_checkpoint_protocol.md#override-ladder-3-round-friction`](./compliance_checkpoint_protocol.md#override-ladder-3-round-friction)) |
+| Highly Recommended (HR) | **Warn**: surfaced at checkpoint; user can skip |
+| Recommended (R) | **Info**: logged in compliance_report, shown as dashboard bullet |
+| Optional (O) | **Info**: same as R |
+
+> **Gap-tag vocabulary.** Tags `[MATERIAL GAP]`, `[WEAK EVIDENCE]`, `[GAP]` used in this protocol's `reason` fields are defined in [`shared/compliance_checkpoint_protocol.md#canonical-gap-tag-vocabulary`](./compliance_checkpoint_protocol.md#canonical-gap-tag-vocabulary).
+
+## Stage assignment
+
+| Checked at | Items |
+|---|---|
+| Stage 2.5 (Methods) | M1, M2, M3, M4, M5, M6, M7, M8, M9, M10 |
+| Stage 4.5 (remaining) | T1, A1, I1, R1, R2, D1, D2 |
+
+## Items
+
+### T1 — Title
+**Tier:** Optional
+**Original (upstream verbatim):** "Indicate the use of AI in the title or subtitle if it played a substantial role."
+**ARS check procedure:** If `user_metadata.ai_tools_used[].stage` includes any of `{screening, data_extraction, synthesis, writing}` (i.e. substantial involvement), verify manuscript title OR subtitle mentions AI. If none of the AI tools are substantial, pass automatically.
+**Pass criterion:** Substring match for one of: "AI-assisted", "AI-augmented", "artificial intelligence", "LLM-assisted", or language-equivalent.
+
+### A1 — Abstract
+**Tier:** Optional
+**Original:** "Briefly summarize the AI tool(s) used, the review stage(s) where they were applied."
+**ARS check procedure:** Locate manuscript abstract. Verify it names ≥1 AI tool AND the review stages.
+**Pass criterion:** Both named. Absence of either → fail.
+
+### I1 — Introduction
+**Tier:** Recommended
+**Original:** "Briefly state the rationale for using AI tools for specific tasks."
+**ARS check procedure:** In introduction, locate one sentence or more that explains why AI was chosen for its task.
+**Pass criterion:** Rationale present and tied to ≥1 specific AI task.
+
+### M1 — Protocol registration
+**Tier:** Mandatory
+**Original:** "State if the use of AI was pre-specified in a protocol, and document deviations."
+**ARS check procedure:** Check `material_passport.protocol_registration` field OR manuscript §Methods for explicit pre-registration statement. If AI was added mid-review, check for a "deviation from protocol" paragraph.
+**Pass criterion:** Either (a) pre-registration clearly stated, or (b) deviation explicitly disclosed.
+
+### M2 — Tool identification and access
+**Tier:** Mandatory
+**Original:** "Specify name, version, and provider/developer for each tool, with access details."
+**ARS check procedure:** For each entry in `user_metadata.ai_tools_used`, require `name`, `version`, `developer`. If tool is open-source, require repository URL or DOI.
+**Pass criterion:** All three fields non-empty for every tool.
+
+### M3 — Purpose and stage
+**Tier:** Mandatory
+**Original:** "Describe the specific SLR stage and the precise task the AI performed."
+**ARS check procedure:** For each tool, verify stage-level task description exists (not just "used AI for screening").
+**Pass criterion:** Per-tool, per-stage prose description of ≥1 sentence in manuscript §Methods.
+
+### M4 — Input data
+**Tier:** Mandatory
+**Original:** "Describe data provided to the AI (e.g., training data for fine-tuning)."
+**ARS check procedure:** If any tool was fine-tuned or custom-trained, verify dataset description (source, size, preprocessing). If no fine-tuning, verify this is explicitly stated.
+**Pass criterion:** Either (a) dataset described, or (b) explicit "no fine-tuning performed" statement.
+
+### M5 — Output data
+**Tier:** Mandatory
+**Original:** "Describe the output format (e.g., JSON, scores) and any automated post-processing."
+**ARS check procedure:** Verify manuscript §Methods documents output format per tool + any post-processing pipelines.
+**Pass criterion:** Format + post-processing both described.
+
+### M6 — Prompt engineering
+**Tier:** Mandatory
+**Original:** "Report prompt engineering process, full prompts, key parameters for LLMs."
+**ARS check procedure:** If any tool is an LLM, verify full prompt text is included (main text or supplementary) AND model parameters (temperature, top_p, max tokens, model version) are documented.
+**Pass criterion:** All three present for every LLM tool.
+
+### M7 — Operational details
+**Tier:** Highly Recommended
+**Original:** "Describe key operational settings, algorithms, or configurations for non-LLM AI."
+**ARS check procedure:** For classical ML tools (e.g. ASReview, Abstrackr), verify algorithm + hyperparameters documented.
+**Pass criterion:** Algorithm name + at least 2 hyperparameters.
+
+### M8 — Human-AI interaction
+**Tier:** Mandatory
+**Original:** "Describe human interaction (number of reviewers, verification process)."
+**ARS check procedure:** Verify manuscript §Methods states reviewer count, qualifications, and oversight mechanism (e.g., independent dual screening, adjudication).
+**Pass criterion:** Reviewer count + oversight mechanism both present.
+
+### M9 — AI performance evaluation methods
+**Tier:** Mandatory
+**Original:** "Describe methods used to evaluate AI performance (metrics, reference standards)."
+**ARS check procedure:** Verify manuscript §Methods describes what performance metrics were computed (e.g., sensitivity, agreement) and against what gold standard.
+**Pass criterion:** Metric + reference standard both stated.
+
+### M10 — Data management
+**Tier:** Recommended
+**Original:** "Describe data management, storage, privacy measures, and compliance."
+**ARS check procedure:** Verify manuscript §Methods addresses data handling (where stored, privacy controls, GDPR/IRB compliance if applicable).
+**Pass criterion:** ≥2 of {storage, privacy, compliance} addressed.
+
+### R1 — Study selection (AI-assisted)
+**Tier:** Mandatory
+**Original:** "In the PRISMA flow diagram/text, distinguish between records handled by AI versus human reviewers."
+**ARS check procedure:** Verify PRISMA flow diagram or accompanying text explicitly separates AI-handled vs human-handled records at each screening stage.
+**Pass criterion:** Explicit AI/human split in flow diagram numbers OR prose.
+
+### R2 — AI performance metrics (results)
+**Tier:** Mandatory
+**Original:** "Report results of any AI performance evaluations (e.g., agreement rates)."
+**ARS check procedure:** Verify manuscript §Results reports numeric performance outcomes referenced by M9.
+**Pass criterion:** ≥1 quantitative metric (% agreement, Cohen's κ, sensitivity, etc.).
+
+### D1 — Limitations of AI use
+**Tier:** Recommended
+**Original:** "Discuss limitations (technical issues, biases, hallucinations) and their impact."
+**ARS check procedure:** Verify manuscript §Discussion has ≥1 paragraph specifically on AI limitations (not generic review limitations).
+**Pass criterion:** Dedicated AI-limitations paragraph of ≥3 sentences.
+
+### D2 — Implications of AI use
+**Tier:** Optional
+**Original:** "Briefly discuss the experience of using AI tools for future reviews."
+**ARS check procedure:** Verify manuscript §Discussion reflects on the usability/experience of AI for this review, forward-looking.
+**Pass criterion:** ≥1 forward-looking sentence about AI utility.
+
+## Summary counts
+
+- Mandatory: 10 — M1, M2, M3, M4, M5, M6, M8, M9, R1, R2
+- Highly Recommended: 1 — M7
+- Recommended: 3 — I1, M10, D1
+- Optional: 3 — T1, A1, D2
+
+Total: 17 items.
+
+> **ARS promotion note.** Upstream's README header summary says "Mandatory: 9". Per-item tier annotations in upstream (and mirrored here) mark **both R1 and R2 as Mandatory**, summing to 10. ARS treats the per-item annotation as authoritative, since the Results-stage items (R1: AI/human split in flow diagram; R2: AI performance metric reporting) are both operationally block-level for a compliance audit. If upstream clarifies the discrepancy, re-sync.

package/vendor/ars/shared/raise_framework.md

@@ -0,0 +1,129 @@
+---
+title: RAISE Framework (v3.4.0 snapshot)
+snapshot_date: "2025-07-17"
+upstream_source: "https://eppi.ioe.ac.uk/CMS/Portals/0/RAISE%20ESG%20BPWG.pdf"
+upstream_version: "NIHR ESG Best Practice Working Group consultation draft, 17 July 2025"
+citation: "Thomas J, Flemyng E, Noel-Storr A, et al. Responsible Use of AI in Evidence Synthesis (RAISE). NIHR ESG Best Practice Working Group in AI/Automation, EPPI-Centre, UCL Social Research Institute. 17 July 2025."
+related: "Position Statement on AI Use in Evidence Synthesis (Cochrane, Campbell, JBI, CEE), Campbell Systematic Reviews, 2025, doi:10.1002/cl2.70074"
+---
+
+# RAISE Framework
+
+## Scope disclaimer (required, do not remove)
+
+RAISE's official scope is **evidence synthesis** (systematic review, meta-analysis, scoping review, rapid review, evidence mapping). When ARS applies RAISE **principles** to non-evidence-synthesis work — e.g., `academic-paper full` on primary research — this is a **principle extension**, not official RAISE compliance. ARS's `compliance_agent` will only claim RAISE compliance for outputs produced in `systematic_review` or `other_evidence_synthesis` modes.
+
+**Used by**: `compliance_agent` (Task 8).
+
+## Four principles
+
+Each principle carries a definition, ARS check procedure, and pass/warn/fail criteria. These are the universal kernel of RAISE and are checked in every mode.
+
+### Principle 1 — Human oversight
+
+**Definition:** AI and automation in evidence synthesis should be used with meaningful human oversight, not as an autonomous replacement.
+**ARS check (Stage 2.5 focus):** At Stage 2.5, verify `methodology_blueprint` specifies reviewer count, qualifications, and adjudication mechanism. At Stage 4.5, verify manuscript describes the human oversight applied in practice.
+**Pass:** Reviewer count + adjudication mechanism + qualifications all present, each with evidence path.
+**Warn:** Any one missing, OR only present in vague form ("authors reviewed AI output").
+**Fail:** Two or more missing.
+
+### Principle 2 — Transparency
+
+**Definition:** Any AI or automation use that makes or suggests judgements must be fully and transparently reported.
+**ARS check (Stage 4.5 focus):** Verify manuscript lists every AI tool used, at what stage, with prompts/parameters/versions. Cross-reference against `user_metadata.ai_tools_used`.
+**Pass:** All declared tools reported AND all reported tools declared.
+**Warn:** Mismatch in ≤1 tool, or reporting lacks one of {stage, prompt, parameters, version}.
+**Fail:** Multiple tools undeclared OR systematically missing prompts/parameters.
+
+### Principle 3 — Reproducibility
+
+**Definition:** AI-assisted evidence synthesis should be reproducible to a stated level.
+**ARS check:** Verify presence of `passport.repro_lock` (v3.3.5 feature) OR equivalent manuscript description (model version, seeds, prompt, data access details). Stochasticity must be declared per `artifact_reproducibility_pattern.md`.
+**Pass:** Repro_lock present AND stochasticity declared.
+**Warn:** One of the two missing.
+**Fail:** Both missing.
+
+### Principle 4 — Fit-for-purpose
+
+**Definition:** AI tools should be chosen and validated for specific tasks within the evidence synthesis, not applied generically.
+**ARS check (Stage 2.5 focus):** Verify manuscript describes why each AI tool was chosen for its specific task. Look for pilot-phase evidence OR prior validation citation.
+**Pass:** Per-tool justification + ≥1 validation reference.
+**Warn:** Justification present without validation reference.
+**Fail:** Generic "we used AI to save time" with no task-level justification.
+
+## Full 8-role matrix (SR mode only)
+
+Used when `raise.mode == "full"` (SR and other_evidence_synthesis). Each role carries 2–3 responsibilities extracted from the RAISE consultation PDF. The agent maps ARS users and ARS itself onto the roles they occupy.
+
+**Default role attribution:**
+- ARS user (the human running the skill): Evidence Synthesists
+- ARS itself (the skill suite): AI Development Teams + Methodologists (dual role)
+
+### Role 1 — Evidence Synthesists
+
+1. Remain ultimately responsible for the evidence synthesis, regardless of AI assistance.
+2. Report AI use in the evidence synthesis manuscript transparently.
+3. Ensure ethical, legal, and regulatory standards are adhered to when using AI.
+
+**ARS check:** manuscript contains author responsibility statement; AI-usage disclosure is present; ethics/IRB section addresses AI use.
+
+### Role 2 — AI Development Teams
+
+1. Adhere to open-science practices when designing, building, testing, and validating tools.
+2. Be transparent about when AI works best, its limitations, and any interests.
+3. Commit to continued learning, development, and monitoring.
+
+**ARS self-declaration:** ARS is open-source (CC BY-NC 4.0); CHANGELOG tracks limitations; calibration results published per `calibration_mode_protocol.md`.
+
+### Role 3 — Methodologists
+
+1. Adhere to open science practice when researching and evaluating AI systems.
+2. Commit to independent evaluations and validation of AI systems.
+
+**ARS self-declaration:** ARS cross-model verification per `cross_model_verification.md` provides blind, typed-provenance cross-model checks — integrity samples, DA critique, and disagreement checkpoints at two irreversible decisions. Different model families may reduce one source of correlated error, but these checks are not a claim of independent validation or improved accuracy. The once-planned sixth-reviewer design was retired in #518 (its failure modes matched ARS's documented anti-patterns).
+
+### Role 4 — Publishers of evidence synthesis
+
+1. Ensure best-practice standards for responsible AI use are clear and integrated into policies and guidelines for authors.
+2. Request transparency and honesty from authors on their use of AI in evidence synthesis.
+
+**ARS note:** Out of ARS's direct control; surfaced in compliance_report as stakeholder context.
+
+### Role 5 — Users of evidence synthesis
+
+1. Critically consider the potential influence of AI use in a synthesis before use.
+2. Underscore the potential impacts of AI use in downstream documents and decision-making processes.
+3. Communicate the need for transparent reporting of tool accuracy and biases.
+
+**ARS note:** Out of direct scope; listed for ecosystem completeness.
+
+### Role 6 — Trainers of evidence synthesis methods
+
+1. Ensure best-practice standards for responsible AI are embedded within training materials.
+2. Equip trainees with the knowledge they need to determine if an AI tool is appropriate.
+3. Undertake continuous training and development to stay up to date with emerging AI tools.
+
+**ARS note:** Out of direct scope.
+
+### Role 7 — Organisations producing evidence synthesis
+
+1. Ensure best-practice standards for responsible AI are clear and integrated into policies and guidelines.
+2. Promote, guide, and support responsible AI use in evidence synthesis activities.
+3. Monitor the development and use of AI within the organisation.
+
+**ARS note:** Out of direct scope.
+
+### Role 8 — Funders of evidence synthesis
+
+1. Encourage the responsible use of AI.
+2. Consider sustainability and generalisability of the products they support.
+
+**ARS note:** Out of direct scope.
+
+## Usage in compliance_agent
+
+- SR mode: `raise.mode = "full"`, both principles AND roles populated
+- primary_research mode: `raise.mode = "principles_only"`, `roles` field absent or empty
+- other_evidence_synthesis mode: `raise.mode = "full"`, roles populated with adaptation noted in evidence paths
+
+Block decisions follow tier semantics: any principle at `fail` status + `systematic_review` mode → `block`. `primary_research` mode **never** blocks.