psyclaw 0.27.22 → 0.28.0

package/vendor/ars/deep-research/references/preregistration_guide.md

@@ -0,0 +1,324 @@
+# Preregistration Guide — Research Preregistration Guide
+
+## Purpose
+Decision guide and operational manual for research preregistration. Assists the research_architect_agent in determining whether preregistration is needed during the methodology design stage, and guides researchers through the preregistration process.
+
+---
+
+## 1. Preregistration Decision Tree
+
+```
+Does your research have the following characteristics?
+│
+├── Confirmatory research (hypothesis testing)
+│   └── Strongly recommend preregistration
+│       ├── Has pre-specified statistical hypotheses → Preregister
+│       ├── Will conduct significance testing → Preregister
+│       └── Has primary outcome variables → Preregister
+│
+├── Exploratory research
+│   └── Preregistration not required (but optional)
+│       ├── Qualitative research → Typically not preregistered
+│       ├── Data mining / EDA → Typically not preregistered
+│       └── But you can preregister the research design and analysis process
+│
+├── Systematic review / Meta-analysis
+│   └── Strongly recommend registration (PROSPERO)
+│       └── Many journals require systematic reviews to be pre-registered
+│
+├── Randomized controlled trial (RCT)
+│   └── Must register
+│       ├── ICMJE requires RCTs to be pre-registered
+│       └── Most journals will not accept unregistered RCTs
+│
+├── Replication study
+│   └── Strongly recommend preregistration
+│       └── Preregistration clearly distinguishes original from modified hypotheses
+│
+└── Secondary data analysis
+    └── Recommend preregistration
+        └── Prevents HARKing (Hypothesizing After Results are Known)
+```
+
+### When Preregistration Is Not Needed
+
+- Purely qualitative research (grounded theory, phenomenology)
+- Exploratory data analysis (no pre-specified hypotheses)
+- Theoretical or philosophical research
+- Literature reviews (except systematic reviews)
+- Case reports or case studies
+
+### When Preregistration Is Strongly Recommended
+
+- Any research involving hypothesis testing
+- Research involving multiple comparisons
+- Research needing to distinguish confirmatory vs. exploratory analyses
+- Research that may be questioned for p-hacking or HARKing
+- When applying for research funding (demonstrates research rigor)
+- When journals explicitly require or encourage preregistration
+
+---
+
+## 2. Preregistration Platform Overview
+
+| Platform | Applicable Field | Features | Cost |
+|------|---------|------|------|
+| **OSF Registries** | All disciplines | Most widely used, multiple templates, DOI, permanent preservation | Free |
+| **PROSPERO** | Systematic reviews | Dedicated to systematic reviews and meta-analyses | Free |
+| **AEA Registry** | Economics | American Economic Association's RCT registration platform | Free |
+| **AsPredicted** | All disciplines | Simplified preregistration (9 questions), quick to complete | Free |
+| **ClinicalTrials.gov** | Clinical trials | US FDA-required RCT registration | Free |
+| **EGAP** | Political science | Experiments in Governance and Politics | Free |
+| **RIDIE** | Development economics | Registry for International Development Impact Evaluations | Free |
+
+### Platform Selection Guide
+
+```
+What is your research?
+│
+├── Systematic review / meta-analysis → PROSPERO
+├── Clinical trial / medical intervention → ClinicalTrials.gov
+├── Economics RCT → AEA Registry
+├── Just need simple preregistration → AsPredicted
+└── All other research → OSF Registries (recommended)
+```
+
+---
+
+## 3. 21-Item Core Content Checklist
+
+Based on the OSF Standard Pre-Data Collection Registration format, the following are the 21 core items:
+
+### A. Study Information
+
+| # | Item | Description |
+|---|------|------|
+| 1 | **Study title** | Descriptive title |
+| 2 | **Authors/Research team** | All researchers' names and affiliations |
+| 3 | **Research questions** | Main research questions (clear, specific) |
+| 4 | **Hypotheses** | Pre-specified hypotheses (including directional predictions) |
+
+### B. Design Plan
+
+| # | Item | Description |
+|---|------|------|
+| 5 | **Study design** | Experiment/observational, between/within-subjects, factorial design, etc. |
+| 6 | **Randomization** | Randomization method (if applicable) |
+| 7 | **Blinding** | Blinding level and implementation (if applicable) |
+| 8 | **Conditions/manipulations** | Specific description of each experimental condition/group |
+
+### C. Sampling Plan
+
+| # | Item | Description |
+|---|------|------|
+| 9 | **Existing data** | Whether existing data is being used; nature and status of data |
+| 10 | **Data collection procedures** | How data will be collected (survey, interview, experiment, archival) |
+| 11 | **Sample size** | Planned sample size and basis for determination |
+| 12 | **Sample size rationale** | Power analysis or other sample size calculation method |
+| 13 | **Stopping rule** | When to stop collecting data (fixed N / target power reached / time cutoff) |
+
+### D. Variables
+
+| # | Item | Description |
+|---|------|------|
+| 14 | **Manipulated variables** | Operational definition of independent variables |
+| 15 | **Measured variables** | Operational definition and measurement instruments of dependent variables |
+| 16 | **Indices** | Specific indicators for each variable (scales, items, scoring methods) |
+
+### E. Analysis Plan
+
+| # | Item | Description |
+|---|------|------|
+| 17 | **Statistical models** | Primary statistical methods for analysis |
+| 18 | **Transformations** | Data transformation plan (e.g., log transformation, standardization) |
+| 19 | **Inference criteria** | Significance level (alpha), correction methods, effect size reporting |
+| 20 | **Data exclusion** | Exclusion criteria (outlier definition, attention check failure, etc.) |
+| 21 | **Exploratory analyses** | Planned but non-primary hypothesis analyses |
+
+---
+
+## 4. Higher Education Research Preregistration Examples
+
+### Example: Effect of Teaching Strategy on Learning Outcomes
+
+```
+Title: The Effect of Flipped Classroom on University Students' Critical Thinking
+       Skills: A Randomized Controlled Trial
+
+Hypotheses:
+H1: Students receiving flipped classroom instruction will score significantly
+    higher on the CCTST than students receiving traditional lectures
+H2: The benefit of flipped classroom will be greater for students with low
+    prior knowledge than for those with high prior knowledge
+
+Design: Cluster-randomized controlled trial (class as randomization unit)
+Sample: 12 classes (6 experimental / 6 control), approximately 40 students
+        per class, total 480
+Power: 80% power to detect d = 0.4, alpha = .05, ICC = 0.05
+
+Primary outcome: CCTST post-test score (controlling for pre-test)
+Secondary outcomes: Final exam grade, learning motivation scale
+Analysis: Multilevel modeling (students nested in classes)
+
+Exclusion criteria:
+- Attendance rate < 50%
+- Both pre-test and post-test incomplete
+- Attention check questions answered incorrectly
+
+Exploratory analyses:
+- Gender × teaching method interaction effect
+- Learning motivation as a mediating variable
+```
+
+### Example: Systematic Review of University Dropout Factors
+
+```
+Title: Factors Influencing University Student Dropout Decisions in Taiwan:
+       A Systematic Literature Review
+
+Research question: What factors influence university student dropout decisions
+                   in Taiwan?
+Databases: Airiti Library, TSSCI, Scopus, Web of Science
+Search strategy: (dropout OR withdrawal OR leave)
+                 AND (university OR higher education)
+                 AND (Taiwan)
+Time range: 2010-2025
+Inclusion criteria:
+- Studies with Taiwan university students as research subjects
+- Explore causes or factors of dropout/withdrawal
+- Peer-reviewed journal articles or theses/dissertations
+Exclusion criteria:
+- Research subjects below high school level
+- Pure policy commentary (no empirical data)
+Quality assessment: Mixed Methods Appraisal Tool (MMAT)
+Synthesis method: Thematic synthesis
+Registration platform: PROSPERO
+```
+
+---
+
+## 5. Preregistration Disclosure Statement Templates
+
+### Disclosing Preregistration in a Paper
+
+#### Standard Statement (Preregistered)
+```
+This study was preregistered on [Platform] prior to data collection
+(registration number: [NUMBER]; URL: [URL]). All hypotheses, sample size
+rationale, and analysis plans were specified before data collection began.
+Deviations from the preregistered plan are noted in [section/supplementary
+materials].
+```
+
+#### Disclosure of Deviations from Preregistration
+```
+Deviations from preregistered plan:
+1. [Deviation description]: [Reason for deviation]
+2. [Deviation description]: [Reason for deviation]
+These deviations do not affect the confirmatory nature of the primary analyses.
+The preregistered analyses are reported as planned; additional exploratory
+analyses are clearly labeled.
+```
+
+#### Disclosure When Not Preregistered
+```
+This study was not preregistered. While the hypotheses were formulated before
+data analysis, the distinction between confirmatory and exploratory analyses
+should be interpreted with this limitation in mind.
+```
+
+---
+
+## 6. Preregistration vs. Registered Reports
+
+| Aspect | Preregistration | Registered Reports |
+|------|-------------------------|-------------------------------|
+| **Definition** | Research plan publicly registered in advance | Research plan submitted to a journal for pre-review |
+| **Review** | Does not undergo peer review | Stage 1 peer review (research design) |
+| **Acceptance timing** | Paper submitted only after completion | Receives "In-Principle Acceptance" (IPA) after passing Stage 1 |
+| **Results bias** | Reduced but not eliminated (researchers can still selectively report) | Substantially eliminated (published regardless of results) |
+| **Publication bias** | Cannot solve | Effectively solved (null results also published) |
+| **Applicable journals** | All journals | Only journals accepting Registered Reports |
+| **Difficulty** | Low (just fill in a form) | High (requires complete methodology and passing review) |
+| **Flexibility** | Higher (deviations require disclosure but don't block submission) | Lower (major deviations may affect acceptance) |
+
+### Registered Reports Process
+
+```
+Stage 1: Submit research plan
+├── Introduction (theoretical background, literature review)
+├── Methods (complete methodology, analysis plan)
+├── Pilot data (if available)
+└── Interpretation plan for predicted results
+         ↓
+Stage 1 Review (research design quality)
+├── Accept (In-Principle Acceptance, IPA)
+├── Revise and resubmit
+└── Reject
+         ↓
+Stage 2: Conduct research, write results
+├── Strictly follow the Stage 1 plan
+├── Report all preregistered analyses (including null results)
+├── Exploratory analyses clearly labeled
+└── Deviations disclosed and explained
+         ↓
+Stage 2 Review (execution quality)
+├── Was the Stage 1 plan faithfully executed?
+├── Are results reported completely?
+└── Typically not rejected due to null results
+         ↓
+Publication
+```
+
+### Selected Higher Education Journals Supporting Registered Reports
+
+- *Studies in Higher Education*
+- *Higher Education*
+- *Assessment & Evaluation in Higher Education*
+- *Teaching in Higher Education*
+- *Educational Research Review*
+- *Learning and Instruction*
+
+> Full list: [COS Registered Reports](https://www.cos.io/initiatives/registered-reports)
+
+---
+
+## Quick Reference: 3 Steps to Preregistration
+
+1. **Decide whether to preregister**: Determine if your research involves hypothesis testing
+2. **Choose a platform**: Use PROSPERO for systematic reviews, OSF for everything else
+3. **Fill in the 21-item checklist**: Use the `templates/preregistration_template.md` template
+
+> Preregistration is not a perfect solution, but it is currently the most practical transparency tool. Even an imperfect preregistration is better than no preregistration at all.
+
+---
+
+## Completed-artifact handoff boundary (#672)
+
+The templates in this guide help an author plan or disclose a preregistration.
+They are never evidence that a study was preregistered and must not be supplied
+as a completed artifact. Cross-document comparison may use only a completed
+artifact explicitly supplied by the caller in the current handoff.
+
+The non-shell research architect records only the caller-declared status
+(`provided`, `not_provided`, `access_failed`, or `retrieval_failed`) and, for
+`provided`, the explicitly named companion handle. It does not compute a digest
+or construct a sidecar. Before handoff, a shell-capable orchestrator runs the
+deterministic `build-preregistration-artifact` subcommand in
+`scripts/build_cross_document_consistency_advisory.py` with an explicit RFC3339
+`declared_at`. That builder emits exactly one closed
+`preregistration-artifact/1.0`, including an explicit unavailable receipt.
+
+The sidecar and provided companion bytes are validated and carried unchanged
+through academic-paper and every pipeline handoff. Later explicit user supply
+requires a new builder-produced, fully bound sidecar; omission or silent
+substitution is invalid. A manuscript/preregistration advisory may identify an
+undisclosed deviation only with exact manuscript and preregistration quotes plus
+an exact named manuscript disclosure scope checked for that same deviation.
+Missing, blank, generic, incomplete, or inaccessible scope means not checked.
+
+#672 does not judge whether preregistration was required, timely, authentic,
+complete, or whether a deviation was justified. Its output is
+`LLM-ADVISORY` / `UNMEASURED`, not a score, gate, agreement certificate, or
+revision instruction. Consent/protocol comparison stays under the separate
+#667/#681 human-subjects authority path.

package/vendor/ars/deep-research/references/semantic_scholar_api_protocol.md

@@ -0,0 +1,107 @@
+# Semantic Scholar API Verification Protocol
+
+**Status**: v3.3
+**Used by**: `source_verification_agent`, `bibliography_agent`, `integrity_verification_agent`
+**API base**: `https://api.semanticscholar.org/graph/v1`
+**Rate limit**: 1 request/second (unauthenticated), 10 requests/second (with API key)
+**API key env var**: `S2_API_KEY` (optional; graceful degradation if unset)
+
+---
+
+## Purpose
+
+Provides programmatic verification of reference existence and bibliographic accuracy using the Semantic Scholar Academic Graph API. This supplements (not replaces) WebSearch-based verification by adding a structured, API-grounded check that returns machine-readable metadata.
+
+PaperOrchestra (Song et al., 2026) demonstrated that a two-phase citation pipeline — (1) broad discovery via web search, (2) sequential verification via Semantic Scholar API — achieves significantly higher citation coverage (P0 Recall +2-6%, P1 Recall +12-14% over baselines). ARS adopts the verification phase as an additional tier in the existing multi-tier verification strategy.
+
+---
+
+## Query Patterns
+
+### Pattern 1: Title Search (primary)
+
+```
+GET /paper/search?query={url_encoded_title}&limit=5&fields=title,authors,year,externalIds,venue,publicationDate
+```
+
+**Matching rule**: Compute Levenshtein similarity between query title and each result title (case-insensitive, stripped of punctuation). Accept if similarity >= 0.70 (matching PaperOrchestra's threshold). If multiple results >= 0.70, prefer the one with matching year.
+
+### Pattern 2: DOI Lookup (when DOI is available)
+
+```
+GET /paper/DOI:{doi}?fields=title,authors,year,externalIds,venue,publicationDate,citationCount
+```
+
+**Matching rule**: DOI match is exact. Cross-check that returned title matches the reference title (Levenshtein >= 0.70). If title mismatch despite DOI match, flag as `DOI_MISMATCH` — a known hallucination pattern where a fabricated DOI resolves to an unrelated paper.
+
+### Pattern 3: Semantic Scholar ID Lookup (for re-verification)
+
+```
+GET /paper/{paperId}?fields=title,authors,year,externalIds,venue,publicationDate,citationCount
+```
+
+Used when re-verifying a reference that was previously resolved to a Semantic Scholar ID (stored in the bibliography's `semantic_scholar_id` field).
+
+---
+
+## Verification Tiers (Updated with S2 API)
+
+| Tier | Method | Coverage | Purpose |
+|------|--------|----------|---------|
+| **Tier 0 (NEW)** | Semantic Scholar API | 100% of references | Programmatic existence check + metadata extraction |
+| Tier 1 | DOI resolution | 100% of DOI-bearing refs | URL-level existence check |
+| Tier 2 | WebSearch spot-check | 50% of sources | Human-readable verification |
+
+**Execution order**: Tier 0 first (batch, 1 req/sec). References that PASS Tier 0 skip Tier 2 unless flagged for other reasons. References that FAIL Tier 0 proceed to Tier 1 + Tier 2 for manual investigation.
+
+---
+
+## Response Handling
+
+### On successful match
+
+Record the following in the reference's verification audit trail:
+- `semantic_scholar_id`: the S2 paper ID (e.g., `"649def34f8be52c8b66281af98ae884c09aef38b"`)
+- `s2_title`: returned title
+- `s2_authors`: returned author list
+- `s2_year`: returned year
+- `s2_venue`: returned venue
+- `s2_citation_count`: citation count (informational)
+- `match_score`: Levenshtein similarity score
+- `verification_method`: `"s2_title_search"` or `"s2_doi_lookup"`
+
+### On no match
+
+- If 0 results with Levenshtein >= 0.70: classify as `S2_NOT_FOUND`
+- `S2_NOT_FOUND` does NOT automatically mean fabrication — the paper may exist but not be indexed in Semantic Scholar (e.g., very recent, non-English, grey literature)
+- Proceed to Tier 1 (DOI) and Tier 2 (WebSearch) for further investigation
+- If ALL tiers fail: classify as `NOT_FOUND` per existing protocol
+
+### On API failure
+
+- HTTP 429 (rate limit): back off 2 seconds, retry up to 3 times
+- HTTP 5xx: skip S2 for this reference, proceed to Tier 1
+- Network error: skip S2 entirely for remaining batch, log `[S2-API-UNAVAILABLE]`
+- **Never block the pipeline on S2 API failure** — graceful degradation to existing WebSearch-only verification
+
+---
+
+## Deduplication via S2 ID
+
+When two references resolve to the same `semantic_scholar_id`, flag as duplicate. The `bibliography_agent` uses this for deduplication during search (matching PaperOrchestra's approach of deduplicating via Semantic Scholar IDs).
+
+---
+
+## Cost and Performance
+
+- **API calls per paper**: ~30-80 (one per reference, typical paper has 30-80 references)
+- **Time**: At 1 req/sec (unauthenticated), 30-80 seconds for a full paper. With API key (10 req/sec): 3-8 seconds
+- **Cost**: Free (Semantic Scholar API is free for academic use)
+- **Recommendation**: Set `S2_API_KEY` for faster verification. Obtain from https://www.semanticscholar.org/product/api#api-key
+
+---
+
+## References
+
+- Song, Y., Song, Y., Pfister, T., & Yoon, J. (2026). PaperOrchestra: A Multi-Agent Framework for Automated AI Research Paper Writing. *arXiv preprint arXiv:2604.05018*. — Section 4 Step 3 (Literature Review Agent), Appendix D.3 (Citation Verification).
+- Semantic Scholar API documentation: https://api.semanticscholar.org/

package/vendor/ars/deep-research/references/socratic_mode_protocol.md

@@ -0,0 +1,99 @@
+# Socratic Mode: Guided Research Dialogue — Full Protocol
+
+## Core Principle
+
+From the perspective of a Q1 international journal editor-in-chief, guide users to clarify their research questions through Socratic questioning. **IRON RULE while non-generation Socratic mode is active**: Never give direct answers; instead, use follow-up questions to help users think through the issues themselves. The explicit candidate-generation exit below ends that mode before candidate content appears.
+
+See `agents/socratic_mentor_agent.md` for the detailed agent definition.
+See `references/socratic_questioning_framework.md` for the questioning framework.
+
+### Research-question authorship boundary
+
+Socratic mode is non-generation by default. Non-convergence never authorizes
+the Mentor or `research_question_agent` to invent candidate RQs. They may
+summarize only directions the user has already expressed, identify unresolved
+choices, continue with focused questions, or suggest `lit-review` before the
+user returns to question framing.
+
+If the user explicitly asks the system itself to propose candidates, candidate
+generation happens only after a visible exit from non-generation Socratic mode.
+The response must announce that transition and emit the following exact marker
+on a standalone line before any candidate content:
+
+`[SOCRATIC-NON-GENERATION-EXIT: explicit_user_request]`
+
+Candidate questions after that marker are labeled AI-generated starting points,
+not user-derived insights. The system does not silently re-enter Socratic mode.
+
+## 5-Layer Dialogue Flow
+
+```
+User: "Guide my research on [topic]"
+     |
+=== Layer 1: PROBLEM FRAMING (corresponds to first half of Phase 1) ===
+     |
+     +-> [socratic_mentor_agent] -> Follow-up on research motivation and problem definition
+         [research_question_agent] -> Provide FINER guidance framework
+         - "What is the question you truly want to answer?"
+         - "Why does this question matter? To whom?"
+         - "If your research succeeds, how would the world be different?"
+         Extract [INSIGHT: ...] each round
+         At least 2 rounds of dialogue before entering Layer 2
+     |
+=== Layer 2: METHODOLOGY REFLECTION (corresponds to second half of Phase 1) ===
+     |
+     +-> [socratic_mentor_agent] -> Follow-up on rationale for methodology choices
+         [devils_advocate_agent] -> Challenge methodology assumptions at end of Layer 2
+         - "How do you plan to answer this question? Why this approach?"
+         - "Is there a completely different method that could also answer your question?"
+         - "What is the biggest weakness of your method?"
+         At least 2 rounds of dialogue before entering Layer 3
+     |
+=== Layer 3: EVIDENCE DESIGN (corresponds to Phase 2-3) ===
+     |
+     +-> [socratic_mentor_agent] -> Follow-up on evidence strategy
+         - "What kind of evidence would convince you of your conclusion?"
+         - "What evidence would make you change your conclusion?"
+         - "What are you most worried about not finding?"
+         At least 2 rounds of dialogue before entering Layer 4
+     |
+=== Layer 4: CRITICAL SELF-EXAMINATION (corresponds to Phase 5) ===
+     |
+     +-> [socratic_mentor_agent] -> Follow-up on limitations and risks
+         [devils_advocate_agent] -> Challenge conclusion assumptions
+         - "What does your research assume? What if those assumptions don't hold?"
+         - "How would someone with the opposite view refute you?"
+         - "What negative impact could your research have?"
+         At least 2 rounds of dialogue before entering Layer 5
+     |
+=== Layer 5: SIGNIFICANCE & CONTRIBUTION (conclusion) ===
+     |
+     +-> [socratic_mentor_agent] -> Follow-up on "so what?"
+         - "Why should readers care about your findings?"
+         - "What aspects of our understanding of this issue does your research change?"
+         At least 1 round of dialogue
+     |
+     +-> Compile all [INSIGHT]s into Research Plan Summary
+         Can directly hand off to academic-paper (plan mode)
+```
+
+## Dialogue Management Rules
+
+- At least 2 rounds of dialogue per layer before moving to the next (Layer 5 requires at least 1)
+- Users can request to skip to the next layer at any time
+- Mentor responses limited to 200-400 words
+- If no convergence after 10 rounds -> summarize only user-expressed directions
+  and suggest continued questioning, `lit-review`, or an explicit switch to
+  `full` mode (see Failure Paths F1/F6); do not generate candidates as a fallback
+- If dialogue exceeds 15 rounds -> automatically compile INSIGHTs and end
+- If user requests direct answers -> gently decline and explain the value of
+  guided learning; an explicit request for system-proposed candidates follows
+  the visible exit contract above
+
+## Reading Probe (opt-in, goal-oriented only)
+
+When `ARS_SOCRATIC_READING_PROBE=1`, the Mentor runs a one-time honesty probe at the Layer 2 → Layer 3 transition, but only for goal-oriented sessions where the user has already cited a specific paper.
+
+The probe asks the user to paraphrase one passage from that paper. The user may decline; the decline is logged without penalty. The probe is not a gate — it records user self-report only. It does not change convergence signals, intent classification, or any scoring.
+
+Default is OFF. Exploratory sessions never probe. See `agents/socratic_mentor_agent.md` §"Optional Reading Probe Layer" for the full trigger, wording, and logging rules.