academic-research-suite

# ARS-Codex This is a Codex adapter for the ARS suite. The vendored ARS content lives under `ars/`; keep it as source material and route through this file first. ## Versioning This Codex package is version `3.22.0`. The repo-root `VERSION`, this `SKILL.md` metadata version, and `manifest.json` `adapter_version` must match. Starting at `3.22.0`, this release number also matches the vendored ARS suite. The exact upstream version, tag, and commit are recorded in `manifest.json`; historical `0.1.x` package releases retain their original numbers. ## First Rule Do not load the whole suite by default. Select one workflow, read that workflow's `WORKFLOW.md`, then load only the agent, reference, template, or shared files needed for the user's current stage. The internal workflow entry files are named `WORKFLOW.md`, not `SKILL.md`, so Codex registers only this root router skill instead of exposing every vendored upstream workflow as a separate skill. ## Workflow Router Choose the workflow by intent: | User intent | Read first | |---|---| | Deep research, literature review, systematic review, meta-analysis, fact-checking, research question refinement | `ars/deep-research/WORKFLOW.md` | | Academic paper writing, paper outline, abstract, revision, citation formatting, AI disclosure, LaTeX/DOCX/PDF formatting guidance | `ars/academic-paper/WORKFLOW.md` | | Paper review, peer review simulation, editorial decision, reviewer calibration, re-review after revision | `ars/academic-paper-reviewer/WORKFLOW.md` | | End-to-end research-to-paper pipeline, integrity gate, staged review/revision/finalization workflow | `ars/academic-pipeline/WORKFLOW.md` | | Experiment planning, code experiment execution plan, human study protocol, statistical interpretation, reproducibility validation | `ars/experiment-agent/WORKFLOW.md` | If the request spans multiple workflows, start with `ars/academic-pipeline/WORKFLOW.md` unless the user clearly asked for a single phase. ### Spanish Intent Routing Use the same intent boundaries as the vendored Spanish trigger phrases: | Spanish intent | Workflow and mode | |---|---| | revisión de literatura / revisión sistemática / metaanálisis | `deep-research`: `lit-review` / `systematic-review` | | guía mi investigación / ayúdame a razonar | `deep-research`: `socratic` | | revisar artículo / revisa este artículo / revisión entre pares | `academic-paper-reviewer`: `full` | | enmendar mi artículo / enmienda mi artículo | `academic-paper`: `revision` | | recibí comentarios de revisores / ruta de revisión | `academic-paper`: `revision-coach` | | escribir resumen / verificar citas / convertir formato | `academic-paper`: `abstract-only` / `citation-check` / `format-convert` | | artículo de revisión bibliográfica | `academic-paper`: `lit-review` | | flujo de trabajo académico / investigación a artículo | `academic-pipeline`: `pipeline` | Keep review and revision intent distinct. Apply topic scoping below to vague paper topics in Spanish too; an explicit research question permits direct planning. These activation phrases do not add supported output-language pairs. ### Paper Topic Scoping Override Apply this override before the general paper/pipeline routing rule and before the Claude-Style Alias Router below. The override applies regardless of whether the user invokes ARS via natural language or via an `ars-*` alias. If the user says they want to write a paper, thesis, proposal, article, journal article, or manuscript, but they only provide a broad topic, tentative title, research interest, or "題目/主題/方向" and do **not** provide a clear, answerable research question, route to `ars/deep-research/WORKFLOW.md` in `socratic` mode first. This matches the upstream ARS experience where vague paper-topic requests start with SCR/Socratic narrowing instead of immediate outline or drafting. Treat these as Socratic triggers even when the wording contains paper-writing intent: - "I want to write a paper on ..." - "I have a paper topic/title ..." - "我想做一篇論文，題目是..." - "我有一個研究方向/主題，但還不確定問題" - "幫我想論文題目/收斂研究問題" - "논문을 쓰고 싶은데 연구 질문이 아직 명확하지 않아" - "논문 주제/연구 방향은 있지만 무엇을 연구할지 모르겠어" First response in this path: 1. State that the request is being routed to `deep-research` `socratic` mode because the research question is not yet precise. 2. Ask only the material narrowing questions needed now, using `socratic_mentor_agent` and `research_question_agent` guidance. 3. Do not produce an outline, draft, literature review, or full pipeline dashboard until the user has converged on at least one candidate RQ. Route directly to `ars/academic-paper/WORKFLOW.md` only when the user already has a clear RQ, approved study frame, data/results, literature matrix, draft, or explicitly asks to skip scoping and proceed to outline/drafting. Route to `ars/academic-pipeline/WORKFLOW.md` only when the user explicitly asks for the full research-to-paper pipeline or says to continue after Socratic scoping. ## Claude-Style Alias Router Codex does not install Claude slash commands, but this package emulates their intent. If the user's request starts with a slash alias (`/ars-plan`) or a plain alias (`ars-plan`), treat it as a mode shortcut, strip the alias token from the task text, read the matching `ars/commands/ars-*.md` prompt recipe, then route to the workflow `WORKFLOW.md` below. The `model:` field in command frontmatter is a Claude routing hint only. Codex does not translate it into an Opus/Sonnet model pin. Apply the Codex model policy below and preserve explicit user or runtime model choices. | Alias | Read command recipe | Then route to | |---|---|---| | `/ars-plan`, `ars-plan` | `ars/commands/ars-plan.md` | `ars/academic-paper/WORKFLOW.md` in `plan` mode | | `/ars-outline`, `ars-outline` | `ars/commands/ars-outline.md` | `ars/academic-paper/WORKFLOW.md` in `outline-only` mode | | `/ars-abstract`, `ars-abstract` | `ars/commands/ars-abstract.md` | `ars/academic-paper/WORKFLOW.md` in `abstract-only` mode | | `/ars-lit-review`, `ars-lit-review` | `ars/commands/ars-lit-review.md` | `ars/academic-paper/WORKFLOW.md` in `lit-review` mode; if the user wants source discovery and synthesis instead, route to `ars/deep-research/WORKFLOW.md` in `lit-review` mode | | `/ars-3w`, `ars-3w` | `ars/commands/ars-3w.md` | `ars/deep-research/WORKFLOW.md` in `three-way-scan` mode | | `/ars-citation-check`, `ars-citation-check` | `ars/commands/ars-citation-check.md` | `ars/academic-paper/WORKFLOW.md` in `citation-check` mode | | `/ars-disclosure`, `ars-disclosure` | `ars/commands/ars-disclosure.md` | `ars/academic-paper/WORKFLOW.md` in `disclosure` mode | | `/ars-format-convert`, `ars-format-convert` | `ars/commands/ars-format-convert.md` | `ars/academic-paper/WORKFLOW.md` in `format-convert` mode | | `/ars-revision-coach`, `ars-revision-coach` | `ars/commands/ars-revision-coach.md` | `ars/academic-paper/WORKFLOW.md` in `revision-coach` mode | | `/ars-revision`, `ars-revision` | `ars/commands/ars-revision.md` | `ars/academic-paper/WORKFLOW.md` in `revision` mode | | `/ars-rebuttal-audit`, `ars-rebuttal-audit` | `ars/commands/ars-rebuttal-audit.md` | `ars/academic-paper/WORKFLOW.md` in `rebuttal-audit` mode; requires both reviewer comments and an existing response draft | | `/ars-reviewer`, `ars-reviewer` | `ars/commands/ars-reviewer.md` | `ars/academic-paper-reviewer/WORKFLOW.md` in `full` mode unless another reviewer mode is explicit | | `/ars-mark-read`, `ars-mark-read` | `ars/commands/ars-mark-read.md` | Record a user-attested read declaration against the active Material Passport; every new mark requires a user-owned `read_scope`, with locators allowed only for `sections` scope | | `/ars-unmark-read`, `ars-unmark-read` | `ars/commands/ars-unmark-read.md` | Rescind a prior human-read mark against the active Material Passport | | `/ars-cache-invalidate`, `ars-cache-invalidate` | `ars/commands/ars-cache-invalidate.md` | Invalidate cached verification entries for one citation key | | `/ars-full`, `ars-full` | `ars/commands/ars-full.md` | `ars/academic-pipeline/WORKFLOW.md` | If the request body after the alias is a vague topic, tentative title, research direction, or "題目/主題/方向" without a clear research question, defer to the Paper Topic Scoping Override above before routing to the alias's target mode. This applies to `ars-plan`, `ars-outline`, `ars-abstract`, `ars-lit-review`, and `ars-full`. If the Codex client reserves slash-prefixed input before it reaches the model, tell the user to use the plain alias form, for example `ars-plan my topic`. ## Model and Execution Policy Use GPT-6 Astra (`gpt-6-astra`) for new Codex research sessions and supported explicit dispatches. Preserve an explicit user/runtime model choice. A skill cannot change an already-running session; report the actual model when known and never present a planned model as observed execution. Read [`codex/model-runtime-policy.md`](codex/model-runtime-policy.md) when configuring models, delegating roles, or running a long research/review task. Complete the authorized deliverable through its requested stopping point. Resolve routine implementation choices from context and continue independent work while material questions are pending. Reuse existing authorization; a checkpoint display alone is not a new permission request. Keep the actual ARS author-decision, review-criteria, consent, and institution-owned authority gates. If a skill requirement blocks work, identify the exact file and rule and explain which missing decision it needs. Use task-appropriate reasoning, concise progress updates, and the native tool orchestration surface. Batch independent reads/searches, keep dependent work ordered, and judge completion from source evidence and final artifacts. Increase effort or add a reviewer to resolve a concrete uncertainty; avoid generic self-scoring, repeated unchanged checks, fixed retry rituals, and unrequested extra deliverables. Preserve useful state and the user's latest steering across long runs or context compaction. ## Codex Runtime Mapping The upstream ARS files were written for Claude Code. Apply these mappings when using them in Codex: | Upstream wording | Codex behavior | |---|---| | Agent Team, agent, dispatch, handoff | Read the referenced `agents/*.md` as a scoped role contract. Execute inline or delegate independent work using the native runtime, as described below. | | Agent tool, Task tool, subagent | Delegate bounded, independent work when native collaboration is available and it improves quality or time. Continue useful local work while it runs; respect user limits and available slots. Use `codex/agents/*.md` for role boundaries. Fixed planner topologies remain optional. | | AskUserQuestion | Ask concise clarification questions, or use Codex's structured user-input tool when available in the active mode. | | WebSearch | Use Codex web browsing for current facts, source verification, citation checks, and external evidence. Provide source links. | | Bash, Write, Edit | Treat as capability descriptions, not required tool names. Follow Codex safety rules and the user's filesystem constraints. | | Agent frontmatter `tools: Read, Write, Edit, Grep, Glob` | Preserve this as a least-privilege role boundary. The three protected top-level agent roles do not receive Bash or network transport when dispatched separately; inline execution must not use those roles to widen the current task's authority. | | Claude, Claude Code, model-specific wording | Interpret as "the current Codex agent" unless the text is part of a disclosure template or historical example. | | `ARS_MODEL_TIERING=economy|quality-boost` | Unset remains the default and preserves current-model behavior. The upstream relative Opus/Sonnet tier names are not hard-mapped to Codex model ids. Apply tiering only when the active Codex runtime supports an explicit per-dispatch model override; otherwise announce a one-line no-op and keep every role on the active model. Use `ars/shared/model_tiering.md` and `ars/scripts/model_tiering_manifest.json` as the classification contract. | | `ARS_CROSS_MODEL`, `ARS_CROSS_MODEL_REASONING_EFFORT`, `ARS_OPENAI_COMPAT_BASE_URL`, `ARS_OPENAI_COMPAT_API_KEY` | Treat upstream secondary-model dispatch instructions as no-op unless the user explicitly asks for cross-model review. When explicitly enabled in this Codex package, follow `ars/shared/cross_model_verification.md`: identify the provider/model/id status/content class, obtain explicit user consent before any external upload, preserve risk-stratified sampling and blind-disagreement checkpoint rules, and call only the configured provider API. A dispatched owner emits the canonical `[CROSS-MODEL-HANDOFF v1]` envelope; the dispatching Codex context validates it, sends only the payload, applies the mechanical result routing, and returns judgment work to the owner. In reviewer `full` mode, the consented cross-model track swaps the existing Reviewer 2 seat rather than adding a reviewer; re-review runs the independent Priority-1 judge pass and records the Judge Record. Disclose single-family or fallback execution and never simulate either track through the active Codex model. | | `ARS_CROSS_MODEL_TRANSPORT=codex`, `scripts/cross_model_codex_transport.py` | This explicit selector is limited to contained, one-reference citation checks at Stage 2.5 / 4.5 through a ChatGPT-subscription Codex app-server. Require Codex CLI 0.147.0 or newer, `ARS_CROSS_MODEL`, the exact `Logged in using ChatGPT` attestation on stdout or stderr, and the normal provider/content/cost consent gate; do not accept caller-authored prompts or paths, widen the selector to reviewer/DA/calibration/re-review/handoff calls, or fall back automatically to an API. The provider schema omits unsupported `uniqueItems`, but local validation still rejects duplicate sources. Keep `code_mode` disabled while allowing the bounded search host required by the standalone search tool; the closed event allowlist remains authoritative. A result is accepted only after `turn/completed`, clean process exit, and stdout/stderr EOF; late forbidden or malformed events, drain timeout, nonzero exit, reader failure, or stderr overflow fail visibly. | | `S2_API_KEY`, `OPENALEX_API_KEY`, `OPENALEX_POLITE_EMAIL`, `CROSSREF_POLITE_EMAIL` | These are optional upstream bibliographic lookup settings. Use them only when the user explicitly runs contamination-signal migration or programmatic reference verification; normal Codex routing does not require them. Never log credential-bearing query strings, and do not use browser retrieval to bypass API rate limits. | | `ARS_VERIFICATION_CACHE_PATH`, `ARS_CACHE_STALE_ADVISORY_DAYS`, `ARS_CACHE_REVALIDATE` | These configure the local SQLite citation-verification cache, the advisory-only stale-row threshold (default 30 days; `0` disables), and opt-in live re-validation. Preserve cached-by-default behavior when the programmatic citation gate is run. Live re-validation may call external bibliographic services, so use it only within the user's verification task and normal network/credential boundaries; an advisory never becomes a gate failure. | | Local PDF page anchors, `scripts/pdf_read_preflight.py` | Before trusting a `page` anchor from a locally read PDF, run the structural preflight once and carry its sidecar by `ref_slug`. Treat `FAIL` as positive read-integrity evidence against the page anchor and `UNAVAILABLE` as an explicit advisory; never convert a missing dependency, encrypted file, parser repair, or absent sidecar into `PASS`. The v3.20 `--classify-content` extension is opt-in and process-isolated, depends on the separately pinned `requirements-pdf-content-classifier.txt`, and emits only a `TEXT_AVAILABLE` / `OCR_RECOMMENDED` / `unavailable` advisory while the verdict scope remains `STRUCTURE_ONLY`; never turn it into an automatic OCR or anchor-acceptance gate. | | `scripts/research_workflow_profile.py` | Treat research-workflow profiles as a deterministic, default-off substrate, not an automatic router. Use only an explicit selection or the visible `field_general` fallback; never infer a research family from the manuscript. Corrections append receipts and mark prior-profile outputs stale without rewriting scholar-owned artifacts. | | `ARS_INQUIRY_LEDGER=1`, `scripts/inquiry_branch_ledger.py` | The inquiry branch ledger is an opt-in local alpha. When explicitly active, preserve author-owned append events, bounded summaries, project/path identity, locking, recovery, and individually visible stale causes. The flag authorizes no external model, API, or search call and yields no novelty, correctness, value, or usability claim. | | `scripts/check_promotion_bakeoff_preregistration.py` | Preserve the sealed commitment/reveal contracts and use the hermetic unit tests in this package. Do not run direct `verify-tree` against the re-rooted vendored subtree: it intentionally lacks the complete canonical upstream Git history required by that release-discipline check. A real future bakeoff must run from the upstream repository and still requires explicit consent for every live model call and cost. | | `fresh Claude Code session`, `Claude Code session` | Read as "a new Codex conversation". Material Passport reset semantics still apply; only the runtime changes. This rule covers `ars/academic-pipeline/WORKFLOW.md`, `ars/academic-pipeline/agents/pipeline_orchestrator_agent.md`, `ars/academic-pipeline/references/passport_as_reset_boundary.md`, `ars/experiment-agent/README.md`, `ars/experiment-agent/README.zh-TW.md`, and `ars/docs/PERFORMANCE.md`. | | `/ars-*` slash command, Claude plugin command | Treat `ars/commands/ars-*.md` as optional prompt recipes. Codex does not register slash commands from this package. | | SessionStart hook, SubagentStop hook, `hooks/hooks.json`, `scripts/ars_update_check.sh` | Treat as upstream Claude Code hook metadata only. The v3.18 update checker is vendored for traceability and tests but is not installed or executed by Codex; Codex package updates remain manual unless the user explicitly asks to port hook behavior. | ### Bibliographic Network Routing The upstream prompt contracts, Python resolver clients, and v3.21 claim-standing adapters are distinct execution paths. Apply this table before following any vendored instruction that says a lookup happens automatically: | Path | Default ARS-Codex behavior | Dedicated client trigger | |---|---|---| | Ordinary topic or candidate discovery | Use Codex browsing and authoritative web sources. | Never launches the Semantic Scholar, OpenAlex, Crossref, or arXiv Python resolver clients. | | Agent-side ingest, deduplication, and source verification | In the default route, translate prompt-level `WebSearch` or index lookups into Codex browsing or official metadata pages. | Upstream prompt wording such as “automatic S2 lookup” does not itself launch a Python client in Codex. | | Script-backed citation-existence gate | Do not infer this from an `ars-full` request alone. Stage 2.5 and 4.5 remain mandatory integrity checkpoints, but default Codex routing performs their source work through browsing unless the user also requests programmatic verification. | An explicit request to run `verify_passport.py`, `verification_gate`, or equivalent programmatic reference verification. Once invoked, cache misses may call Crossref, OpenAlex, and Semantic Scholar for non-manual references; arXiv runs only when `arxiv_id` is present. Manual references skip all four. | | Claim-standing discovery | Offer only after an eligible Claim Registry row at Stage 2.5 or 4.5. It is advisory and separate from citation verification. | A separate user request plus affirmative, plan-bound consent. It uses the v3.21 keyword-discovery adapters, not the four single-reference resolver clients; absent, cancelled, invalidated, or stale consent means no call. | | Contamination backfill or migration | No automatic migration. | Only the explicitly selected migration CLI and its documented indexes. | The canonical upstream network map remains available at `ars/docs/DATA_FLOWS.md`; this section is the Codex adapter override for when those flows are actually launched here. ### ARS v3.22.0 Contract-Honesty Boundaries - For abstract outputs, follow `ars/shared/output_language_pair.md`. The Phase-1 registry accepts only `zh-tw-en`; an omitted field preserves legacy Traditional Chinese/English surfaces and remains omitted from Schema 4. Reject malformed or unsupported values visibly. The pair does not select manuscript-body language or abstract cardinality. Spanish intent triggers do not imply a Spanish locale pack. - Phase E evidence rows are deterministic, source-bound checkpoint artifacts. They preserve the existing citation verdict and gate, do not mark a source as human-read, and must replay against explicit session-held source bytes. - Revision roadmaps remain non-ranking proposals. Only an explicit author adjudication may authorize exact choices or integrity-correction targets; never infer, fabricate, or auto-apply author decisions. Optional cross-run adjudication-activity capture is local, best-effort, and advisory only. - Review-target context must be author-confirmed, and criteria are carried by resolved pointers across formative, internal, and external review. Do not infer a missing venue/track, invent evidence, or let binding conformance alter