arc

# Agent Research Copilot (ARC) ARC is a cache-first research toolkit for theoretical-physics papers and research-domain construction. Use ARC tools instead of scraping arXiv/INSPIRE or reimplementing paper/domain workflows. ## Preflight Gate Choose one entry path before any ARC CLI call: - **Implicit paper entry:** activate for any task owned by `arc-paper`, even when the user does not name ARC. This includes its complete paper-access, acquisition, search, citation, paper-cache, and summary surfaces. LLM-backed paper summaries and summary batches remain eligible for implicit activation; whether an `arc-paper` operation uses an LLM is not a trigger boundary. - **Explicit ARC entry:** require the user to name ARC, invoke `$arc`, or make an unambiguous continuation of an already-started explicit ARC task before selecting an AC Foundation capability or a managed ARC workflow. Supporting calls that `arc-paper` explicitly requires remain part of the selected paper task; they do not authorize an independent non-paper capability. Do not infer broader opt-in from a general research request, a paper identifier, or a successful `arc-paper` call. Route only the requested capability. This package boundary is the complete trigger policy; do not add a separate cost, duration, or LLM-call classifier. After entry, decide whether the request is a managed ARC workflow run or a direct ARC tool task. All accepted requests default to `automation_level: auto`; never ask the user to choose an execution mode at startup. Use `interactive` only when the user explicitly asks for manual, step-by-step, or major-step review or confirmation. A request to discuss before running creates a pre-run pause rather than a third mode. Managed workflow runs follow `workflows/domain.md`, `workflows/ideas.md`, `workflows/check.md`, `workflows/plan.md`, or `workflows/calculate.md`, and create project-local workflow artifacts such as domain references, ranked ideas, work notes, note-check records, calculation records, reports, rankings, recommendations, research directions, or follow-up project directories. They always require the explicit ARC entry. For these, read `rules/interaction.md` and only the workflow and manuals selected by the requested capability. Use the latest explicit user steer as the current automation level through the end of the managed run or until another explicit steer changes it. Perform exactly the workflow scope requested by the caller. Finish at that scope boundary: an automatic domain request does not authorize idea generation, and automatic idea generation does not authorize planning or calculation. Required prerequisites named by the owning workflow may still run, but they do not expand the requested outcome. Direct ARC tool tasks use the same default-auto and explicit-review policy. Implicitly activated direct tasks stay within `arc-paper`. These include bounded paper facts such as title, authors, abstract, citation count, section text, or equation context, plus paper-tool orchestration such as collecting citers or references, filtering papers by date, generating paper summaries or summary batches, or combining those steps into a non-evaluative paper-data output. An explicit ARC request may instead select a direct AC Foundation tool. Direct tasks must not produce recommendations, research directions, scientific rankings, ARC reports, or managed-workflow artifacts; route those through the owning managed workflow. Durable state and outputs owned by the selected `arc-paper` operation remain allowed. Run direct tasks automatically with safe defaults unless the user explicitly asks to review or confirm steps. Example: `download papers that cited 0911.3380 since 2024 and create a full summary of these papers` may implicitly activate direct `arc-paper` orchestration; it is not a managed workflow mode prompt. AC model calls have no default runtime or inactivity timeout. A caller may set an explicit positive idle timeout through the owning command when operationally needed. Use the owning package's status command or the host's background-command facility for long-running work. Do not stop merely because the call is long or quiet. An explicit user stop pauses the current attempt for same-run resume. ## Required References Read the relevant reference before calling ARC tools. These reads are required, not optional. - For an implicit paper entry, read `manuals/arc-paper.md`. Read another rule or manual below only when the selected `arc-paper` operation requires that topic. Do not read or start a managed workflow. - For an explicit ARC entry, read only the rules, workflow, and manuals needed by the requested capability. Do not preload unrelated capability documents. - User choices, automation mode, and confirmation behavior: read `rules/interaction.md`. Use its Selection Protocol only for a real business choice; mandatory safety or scientific gates may require a direct question. - Scientific claims, gap scoring, automated workflow decisions, warning behavior, or robustness-sensitive execution: read `rules/integrity.md`. - General ARC operating rules: read `rules/operating.md`. - User-facing Markdown math and TeX typesetting: read `rules/math_typeset.md`. - Explicit ARC note-checking, verification, or audit requests: read `workflows/check.md` before any parse, section read, or equation extraction call. - When an explicit ARC request selects a workflow-specific file (`workflows/check.md`, `workflows/domain.md`, `workflows/ideas.md`, `workflows/plan.md`, or `workflows/calculate.md`), read that workflow file and follow its steps. Reading the workflow file is a blocking requirement before any workflow CLI call. - Managed ARC workflow completion checks and improvement notes: read `rules/self-reflection.md`. - Single-paper metadata, full text, sections, equations, citers, references, paper summaries, or summary batches: read `manuals/arc-paper.md`. - Local source import/parsing, exact cached-document reads, neutral text or equation search, keyword inventories, rich-document export, or document-cache administration: read `manuals/ac-document.md`. - Research field/domain construction, foundation-paper selection, domain networks, evidence packs, graph HTML, or field briefings: read `manuals/arc-domain.md`. - Durable run inspection, validation, live work-group concurrency adjustment, or stop requests: read `manuals/ac-jobs.md`. - Host LLM/provider detection, model choice, direct prompt tests, or provider troubleshooting: read `manuals/ac-llm.md`. - Typed proposer-reviewer batch construction, resume, or safe observation of committed rounds: read `manuals/ac-proposer-reviewer.md`. - User-facing Markdown report export: use the ordinary blocking Pandoc/XeLaTeX command in `rules/math_typeset.md`; see `manuals/ac-jobs.md` for the workflow failure boundary. ## CLI Resolution Use `ac-document`, `arc-paper`, `arc-domain`, `ac-llm`, and `ac-jobs` directly when the host plugin exposes them on `PATH`. In DeepSeek Harness, prefer the trusted launcher exported as `$DSH_ARC_RUNTIME` when it is present; this avoids assuming that a plugin's package-local `bin/` directory has already been added to the model shell's `PATH`. The core-only `ac-proposer-reviewer` tool deliberately has no plugin-bin wrapper; invoke it through the runtime launcher. For a standalone Skill install, or when a bare command is unavailable, invoke the same command through: ```bash <skill-dir>/scripts/arc-runtime <arc-command> [args...] ``` Within DeepSeek Harness, the equivalent portable form is: ```bash "$DSH_ARC_RUNTIME" arc-paper <subcommand> [args...] ``` For example: ```bash <skill-dir>/scripts/arc-runtime ac-proposer-reviewer trace \ --run-root <run-root> --run-id <run-id> ``` Run Skill-owned Python workflow adapters inside that same private environment: ```bash <skill-dir>/scripts/arc-runtime script <skill-dir>/scripts/<workflow>.py [args...] ``` `inspect`, `trace`, and `show-round` are the only public observation surface for a proposer-reviewer batch. `inspect` activity is best effort and cannot drive ranking, recovery, retries, or resume. `trace` exposes only verified committed-round refs and revision vectors; `show-round` alone expands a committed proposal/review JSON payload. Never read durable loop or artifact layout to substitute for these queries. The first real CLI call lazily installs the immutable locked runtime. Managed, CI, or offline-preparation environments may prewarm it with `<skill-dir>/scripts/arc-runtime setup`; diagnose it with `<skill-dir>/scripts/arc-runtime doctor`. The base Skill never installs or starts MCP. The launcher defaults `AC_HOME` to `$HOME/.ac`; set `AC_RUNTIME_HOME` for an explicit portable runtime location. Neutral document cache defaults to `.ac/cache/ac-document/`, while paper cache defaults to `.arc/cache/arc-paper/` below the launch directory. Set `AC_DOCUMENT_CACHE` or `ARC_PAPER_CACHE` for explicit portable locations. Durable workflow state belongs in each project's hidden `.arc/` directory. `doctor` reports the resolved runtime identity and environment. Provider selection remains owned by the installed `ac-llm` package. ## Workflow Follow the workflow step by step. Do not skip any step, and do not kill or stop any job because it is slow or time consuming. ### Phase 1: Setup Step 1: Set the automation level and requested scope. Use this step only for managed ARC workflow runs. For direct ARC tool tasks, skip the Workflow section and use the relevant manuals and CLI tools directly. Default to `auto` without asking. If the user explicitly requests manual, step-by-step, staged review, or confirmation at key steps, use `interactive`. Follow runtime steering, one-shot checkpoints, and hard-gate rules in `rules/interaction.md`. Preserve the caller's requested workflow boundary; `auto` suppresses routine confirmation questions but never opts the caller into downstream workflows. Step 2: Extract `<user-intent>`. Keep the research/scientific request. Remove operational instructions such as automation mode, project directory, and output formatting. Preserve scientific domain anchors in `<user-intent>`, including phrases such as "in the field started by arXiv:..." or "in the literature around ...". Those phrases are part of the scientific request, not workflow metadata. Keep the same paper identifiers separately in `seed_paper_list` as structured routing data. If the request references or attaches accessible files such as `.md`, `.pdf`, `.doc`, or `.jpg`, read or extract the relevant content and summarize it as part of `<user-intent>`. Treat collaborator notes or images as source context for routing, domain building, checking, or later workflows. Step 3: Resolve `<seed-paper-list>`. Use explicit paper identifiers when present. Otherwise infer seed papers from `<user-intent>` through ARC paper tools. For a domain request whose relative date applies to field papers (for example, “field X in the last two years”), do not treat that date as a seed-paper filter: first resolve a date-unbounded canonical origin, then use the date window for its citers as specified in `workflows/domain.md`. Keep the candidate evidence and origin-selection result separately; only each selected/explicit foundation becomes an entry in `seed_paper_list` for its domain build. See `manuals/arc-paper.md` for paper identifier inference and `manuals/ac-jobs.md` for background jobs. Step 4: Resolve `<project-dir>`. Capture `<arc-run-root>` by running `pwd -P` in the directory where the user launched the agent command. Do not use host-internal project/cache locations. If `<arc-run-root>` is under `.claude`, `.codex`, a plugin directory, or a cache directory, print `WARNING:` and stop before writing artifacts. Use a user-specified project directory when present. Otherwise derive `<project_dir_name>` as a safe directory stem from `<seed-paper-list>` with ARC paper tools, then resolve `<project-dir>` with: ```bash python3 <skill-dir>/scripts/resolve-project-dir.py \ --name <project_dir_name> \ --run-root <arc-run-root> \ --json ``` The generated `<project-dir>` must be the direct child `<arc-run-root>/<project_dir_name>`. Do not create `arc-output/<project_dir_name>`, do not wrap the safe name in another directory, and do not write generated workflow artifacts under `.claude`, `.codex`, plugin dirs, or cache dirs. If the directory already exists, follow the automation policy in `rules/interaction.md`. Step 5: Write `<project-dir>/context.json`. Include `automation_level`, `workflow`, `original_request`, `user_intent`, `arc_run_root`, `project_dir_name`, `project_dir`, `run_id`, `created_at`, `skill_version`, `skill_dir`, `skill_workflow_json_dir`, `seed_paper_list`, `provider`, `model_tier`, `workers`, `refresh`, `recent_window_days`, and `as_of_date`. A domain origin-resolution path additionally records `origin_candidates`, `origin_selections`, `origin_selection_run_ids`, `domain_deduplications`, `foundation_mode`, `citer_selection_mode`, and, when required, `source_provenance` plus the requested refactor ancestor. Default `recent_window_days` to `365` and freeze `as_of_date` to the run's UTC date. When the request says "the last two years", use the exact number of days between `as_of_date` and the corresponding calendar date two years earlier. Set `provider` to `auto` unless the user pins a provider. Set `model_tier` to `medium` unless the user explicitly asks otherwise. Never select the `max` model tier automatically; use it only when the user explicitly requests the `max` model tier. See `manuals/ac-llm.md` for model tiers. Use a stable safe `run_id`: lowercase ASCII letters, digits, and underscores, for example a short intent slug plus UTC timestamp. Set `skill_dir` to the ARC skill directory and `skill_workflow_json_dir` to `<skill-dir>/workflows/json`. When resuming a managed run, reconcile `automation_level` with the latest explicit user steer and update the existing `context.json` in place. Do the same after a runtime switch. Direct tool tasks do not create a state file solely for this field; follow the latest explicit instruction in the current session. ### Phase 2: Route Selection Resolve the user's intent and classify it into one of the six cases below. Choose only the case needed for the requested outcome. Run another case only when it is an explicit prerequisite below or the caller also requested that outcome. Never interpret `auto` as permission to advance to a later case. Case 1: Build domain references only. Read and execute `workflows/domain.md`. Case 2: Suggest ideas from a request without a concrete idea. First complete Case 1. Then read and execute `workflows/ideas.md`. The workflow owns one public `BatchRequest` in its project-local `RunRepository`; inspect and rank only its verified committed rounds. Do not substitute private loop files, worker sessions, retired intermediary artifacts, nested ARC CLIs, or MCP calls for that contract. Case 3: Check note files or collaborator notes. Use when the request asks to check, verify, audit, or mark work-note premises and claims in one or more accessible `.md` or `.pdf` notes. `workflows/check.md` was already loaded in Required References. Follow its 5-phase workflow: Parse -> Preflight -> Write Planning Handoff -> Execute `plan.md` and `calculate.md` -> Record Note-Check Status. Do not skip directly to parsing results; the preflight, planning handoff, and owned-workflow execution steps are mandatory. Before leaving Case 3 or sending a final response, read `<project-dir>/.arc/calculate/<run-id>/work-note.md`. If any ready detailed step exists, execute `workflows/calculate.md`. If no ready detailed step exists but rough or pending coverage remains from the original note-check request, return to `workflows/plan.md`. Adjudicate every item in `Rough Steps For Later Planning`: promote and execute it, remove or mark it obsolete/not triggered, or record an explicit stop condition in `Open Questions` or `Calculation Status`. Only stop when requested coverage is complete and no triggered rough/pending item remains. Case 4: Calculate from an explicit idea. If the idea is not explicit enough, first complete Case 1 and Case 2, then ask the user to select one concrete idea only in `interactive` mode. In `auto` mode, use ranked idea #1 without asking. If the idea is explicit enough: Step 1: Read and execute `workflows/plan.md`. It writes or updates the hidden current work note under `<project-dir>/.arc/calculate/<run-id>/` and publishes the visible `<project-dir>/work-note.pdf`. Step 2: Read and execute `workflows/calculate.md`. If `calculate.md` requests macro expansion or blocked-step refinement, return to Step 1 for that region. Before leaving Case 4 or sending a final response, read `<project-dir>/.arc/calculate/<run-id>/work-note.md`. If any ready detailed step exists, execute `workflows/calculate.md`. If no ready detailed step exists but rough or pending coverage remains from the original calculation request, return to `workflows/plan.md` to promote the next coherent chunk. Adjudicate every item in `Rough Steps For Later Planning`: promote and execute it, remove or mark it obsolete/not triggered, or record an explicit stop condition in `Open Questions` or `Calculation Status`. Only stop when requested calculation coverage is complete and no triggered rough/pending item remains. ### Phase 3: Self-Reflection Read and follow `rules/self-reflection.md`.