dsh-aris-panel 0.1.0

package/skills/skills-codex/shared-references/integration-contract.md

@@ -0,0 +1,372 @@
+# Integration Contract
+
+When one ARIS skill delegates work to another (or to persistent project
+state), the coupling must be **engineered**, not assumed. This document
+formalizes what every cross-skill integration inside ARIS must provide.
+
+Rule of thumb: **SKILL.md prose can *describe* an integration; it cannot
+*guarantee* one.** Any integration whose silent failure would damage the
+research result needs the components below. Prose-only "MUST invoke X"
+has repeatedly failed in practice — the executor skips under context
+pressure and the caller has no way to detect it.
+
+## Known failure mode (why this contract exists)
+
+Two bugs in the same week, same pathology:
+
+1. **Assurance gate bypass (2026-04-21).** `/paper-writing` ran at
+   `— effort: beast` silently skipped `/proof-checker`,
+   `/paper-claim-audit`, and `/citation-audit` because each phase's
+   content detector could return negative and the outer prose said
+   "audit is optional."
+2. **Research wiki ingest no-op (2026-04-21).** `/research-wiki init`
+   created `research-wiki/papers/` but no paper ever landed there:
+   `/arxiv`, `/alphaxiv`, `/deepxiv`, `/semantic-scholar`, `/exa-search`,
+   raw `Read`/`WebFetch` — none carried a wiki-ingest hook, and the two
+   that did (`/research-lit`, `/idea-creator`) only had soft prose
+   ("optional and automatic").
+
+Both bugs ship through the same gap: **one skill "called" another via
+prose without a canonical helper, a concrete artifact, or a verifier**.
+
+## Required components
+
+Every integration between two ARIS skills (or between a skill and a
+persistent project artifact) must provide all six:
+
+### 1. Activation predicate — single, explicit, observable
+
+A one-line test that says "does this integration fire in this context?"
+Must be observable from outside the LLM (a file exists, an argument is
+set, an environment variable is present). Not a vibe, not "probably
+relevant."
+
+- ✅ `if [ -d research-wiki/ ]`
+- ✅ `if assurance == "submission"`
+- ❌ "if the user seems to want this"
+
+### 2. Canonical helper — one implementation, not copy-pasted
+
+The business logic lives in **exactly one place** — a script under
+`tools/` (canonical name, no path prefix), or a single subcommand
+of an existing helper. Every caller invokes the same entrypoint,
+but every caller must also resolve **where** that entrypoint lives.
+On the Codex side the helper may be at:
+
+- `$ARIS_REPO/tools/<helper>` — env var or auto-resolved from `.aris/installed-skills-codex.txt`
+- `<project>/tools/<helper>` — manual copy or running from inside the ARIS repo
+- `~/.codex/skills/<skill-name>/<helper>` — Codex global install layout
+
+Every caller — including those primarily exercised from inside the
+ARIS repo — MUST use the resolution chain. The chain's middle layer
+(`tools/<helper>`) covers the in-repo case at the same code path,
+with no special-casing needed. The exception that used to live here
+("helpers run from inside ARIS repo may stay plain `tools/...`")
+caused user-visible bugs when a SKILL ran from a downstream paper
+project and could not find the helper.
+
+#### Resolver block (lookup only — failure policy is separate)
+
+```bash
+# Canonical strict-safe variant: works whether or not the caller has
+# `set -e` or `set -u` enabled. The manifest read only runs when the
+# file exists, `|| true` consumes a non-zero awk exit so chain
+# evaluation continues, and `${ARIS_REPO:-}` defaults to empty under
+# `set -u`.
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills-codex.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills-codex.txt 2>/dev/null) || true
+fi
+HELPER=""
+[ -n "${ARIS_REPO:-}" ] && [ -f "$ARIS_REPO/tools/<helper>" ] && HELPER="$ARIS_REPO/tools/<helper>"
+[ -z "$HELPER" ] && [ -f tools/<helper> ] && HELPER="tools/<helper>"
+[ -z "$HELPER" ] && [ -f ~/.codex/skills/<skill-name>/<helper> ] && HELPER="$HOME/.codex/skills/<skill-name>/<helper>"
+```
+
+After the resolver runs, `$HELPER` is either the resolved path, or
+the empty string. Use a semantic variable name in real callers
+(`AUDIT_VERIFIER`, `TRACE_HELPER`, `WIKI_SCRIPT`, `IMAGE2_HELPER`, …)
+so a single SKILL that resolves multiple helpers does not clobber
+one with another.
+
+#### Failure policy (chosen per integration)
+
+The resolver does **not** decide what happens when the helper is
+missing. Each calling SKILL must pick exactly one policy:
+
+**A. Load-bearing gate — unresolved helper must block.** Use for
+verifiers whose exit code gates submission readiness (e.g.
+`verify_paper_audits.sh` under `assurance: submission`).
+
+```bash
+[ -n "$AUDIT_VERIFIER" ] || {
+  echo "ERROR: verify_paper_audits.sh not resolved; assurance=submission cannot proceed." >&2
+  exit 1
+}
+```
+
+**B. Optional side-effect — unresolved helper warns and skips.** Use
+when the primary output is still delivered without the helper (e.g.
+`research_wiki.py ingest_paper`).
+
+```bash
+[ -n "$WIKI_SCRIPT" ] || {
+  echo "WARN: research_wiki.py not resolved; primary output unaffected, wiki side-effect skipped." >&2
+}
+[ -n "$WIKI_SCRIPT" ] && python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ --arxiv-id "$id"
+```
+
+**C. Forensic helper — unresolved means write artifacts directly.**
+Use when the helper produces a record the SKILL is contractually
+required to leave behind (e.g. `save_trace.sh`).
+
+```bash
+if [ -n "$TRACE_HELPER" ]; then
+  bash "$TRACE_HELPER" ...
+else
+  # Required fallback: write trace artifacts directly per
+  # review-tracing.md schema. Do NOT silently skip unless
+  # `--- trace: off` was explicitly requested.
+  ...
+fi
+```
+
+**D1. Primary helper with first-success cascade — try N sources in
+priority order, accept first success.** Use when the SKILL needs
+one paper-discovery source and falls back across alternatives.
+
+POSIX-sh safe (`${VAR:-}` defaults plus explicit `source_used=""`):
+
+```bash
+source_used=""
+if [ -n "${S2_FETCHER:-}" ]; then
+  if python3 "$S2_FETCHER" --query "$Q" > results.jsonl; then
+    source_used="semantic_scholar"
+  else
+    echo "WARN: semantic_scholar_fetch.py invocation failed; trying arxiv." >&2
+    S2_FETCHER=""  # force cascade
+  fi
+fi
+if [ -z "$source_used" ] && [ -n "${ARXIV_FETCHER:-}" ]; then
+  echo "WARN: semantic_scholar_fetch.py not resolved or failed; falling back to arxiv_fetch.py." >&2
+  if python3 "$ARXIV_FETCHER" --query "$Q" > results.jsonl; then
+    source_used="arxiv_fallback"
+  fi
+fi
+if [ -z "$source_used" ]; then
+  echo "ERROR: no fetcher resolved or succeeded; cannot retrieve papers." >&2
+  exit 1
+fi
+```
+
+The `if helper-invocation; then ... else ...` wrapper consumes
+non-zero exits so the cascade actually fires under `set -e`.
+
+**D2. Multi-source aggregate — invoke every resolved source,
+aggregate results.** Use when the SKILL ranks or dedupes across
+all available sources. Each source's success/failure is recorded;
+the SKILL proceeds with a (possibly partial) aggregate if at least
+one source contributed.
+
+POSIX-sh safe (delimited-string accumulator, no bash arrays):
+
+```bash
+sources_used=""
+sources_count=0
+append_source() {
+  sources_used="${sources_used:+$sources_used,}$1"
+  sources_count=$((sources_count + 1))
+}
+
+if [ -n "${S2_FETCHER:-}" ]; then
+  if python3 "$S2_FETCHER" --query "$Q" >> results.jsonl 2>>fetch.log; then
+    append_source "semantic_scholar"
+  fi
+fi
+if [ -n "${ARXIV_FETCHER:-}" ]; then
+  if python3 "$ARXIV_FETCHER" --query "$Q" >> results.jsonl 2>>fetch.log; then
+    append_source "arxiv"
+  fi
+fi
+# ... repeat for openalex, exa, deepxiv ...
+if [ "$sources_count" -eq 0 ]; then
+  echo "ERROR: no fetcher resolved or succeeded; aggregate empty." >&2
+  exit 1
+fi
+```
+
+**E. Diagnostic / report helper — non-zero exit is captured, not propagated.**
+Use when the helper's role is to surface drift to humans rather
+than gate workflow correctness (e.g. `verify_wiki_coverage.sh`
+exits 1 when wiki coverage has gaps, but coverage is not
+load-bearing on any research outcome).
+
+```bash
+if [ -n "$WIKI_COVERAGE_DIAG" ]; then
+  # Wrap in if/then/else so `set -e` does not exit the SKILL when
+  # the helper exits non-zero to report gaps.
+  if bash "$WIKI_COVERAGE_DIAG" research-wiki/ > coverage_report.txt; then
+    diag_exit=0
+  else
+    diag_exit=$?
+  fi
+  echo "Coverage diagnostic written to coverage_report.txt (exit=$diag_exit)" >&2
+  # Do NOT propagate $diag_exit; this is a report, not a gate.
+else
+  echo "WARN: verify_wiki_coverage.sh not resolved; coverage diagnostic skipped (non-load-bearing)." >&2
+fi
+```
+
+#### Per-helper policy assignments
+
+Every helper invoked from any SKILL.md (single-skill or shared
+across skills) is classified below so that downstream SKILLs do
+not have to guess. Pure developer utilities that are never invoked
+from a SKILL.md — installers (`install_aris.sh`,
+`install_aris_codex.sh`), update scripts (`smart_update.sh`,
+`smart_update_codex.sh`), manual setup (`overleaf_setup.sh`),
+generators (`convert_skills_to_llm_chat.py`,
+`generate_codex_claude_review_overrides.py`), the `meta_opt/` hook
+scripts, and `watchdog.py` — are out of scope. Extend the
+taxonomy here first if a future helper does not fit.
+
+| Helper (canonical name) | Policy | Rationale |
+|---|---|---|
+| `verify_paper_audits.sh` | A (gate) | Exit code is the source of truth for submission readiness |
+| `forensics_gate.py` (in `/integrity-forensics`, `/paper-writing` Phase 5.9/6.0, `/resubmit-pipeline`) | A (gate) | Typed policy gate + append-only obligations ledger for the Anti-Autoresearch launcher (deterministic slice in Codex-native sessions); when forensics is in play an unresolved helper blocks the Final Report / Overleaf push (never improvise the gate). `fresh` is the one-command downstream preflight; exit code is the source of truth |
+| `save_trace.sh` | C (forensic) | Trace artifacts are load-bearing for audit traceability |
+| `research_wiki.py ingest_paper` (caller skills) | B (side-effect) | Primary output (idea/paper summary) is delivered without wiki ingestion |
+| `research_wiki.py` (in `/research-wiki` itself) | A (gate) | The SKILL is the wiki tool; missing helper means no functionality |
+| `verify_wiki_coverage.sh` | E (diagnostic) | Reports coverage gaps; not load-bearing |
+| `verify_papers.py` | D1 (cascade) | Filters candidate papers; when unresolved **or** invocation fails, callers emit a degraded `verified_papers.json` tagging every candidate `status=unverified, method=none` with explicit WARN |
+| `arxiv_fetch.py`, `semantic_scholar_fetch.py`, `deepxiv_fetch.py`, `exa_search.py`, `openalex_fetch.py` | D2 (multi-source aggregate) when SKILL queries multiple sources; D1 (cascade) when a single source suffices | Each fetcher is one paper-discovery source; SKILLs aggregate or cascade across resolved sources |
+| `extract_paper_style.py` | A when activation predicate `literal "— style-ref:" or equivalent in $ARGUMENTS` is true; not invoked otherwise | If the user asked for style transfer, missing helper means SKILL cannot satisfy the request |
+| `paper_illustration_image2.py` (`preflight`, `finalize`, `verify`) | A (skill-local gate) | Image2 finalization cannot complete without these checks; verify exits 1 on missing artifacts and that is a skill-local gate (a parent paper-writing workflow may still continue with an alternate illustration path). **Phase 3.2 move**: canonical location is `skills/paper-illustration-image2/scripts/paper_illustration_image2.py`; `tools/paper_illustration_image2.py` retained as `os.execv` shim for legacy resolver layers. |
+| `figure_renderer.py` | A (skill-local gate, single-skill) | `figure-spec` cannot produce vector SVG output without the renderer. **Phase 3.1 move**: canonical location is `skills/figure-spec/scripts/figure_renderer.py`; `tools/figure_renderer.py` retained as `os.execv` shim for legacy resolver layers. |
+| `experiment_queue/queue_manager.py`, `experiment_queue/build_manifest.py` | A (skill-local gate, single-skill) | `/experiment-queue` cannot operate without these. **Phase 3.3 move**: canonical location is `skills/experiment-queue/scripts/{queue_manager.py, build_manifest.py}`; both `tools/experiment_queue/*.py` retained as `os.execv` shims for legacy resolver layers. |
+| `overleaf_audit.sh` | E (diagnostic) | Reports overleaf sync drift; surfaces gaps but does not gate the parent workflow |
+
+#### Layer 0 — self-contained owner SKILL (Arch C, Phase 3+)
+
+Single-owner helpers progressively migrate into the owning SKILL's
+`scripts/` subdirectory. When an owner SKILL invokes its own helper
+it tries the self-contained location FIRST, then falls through to
+the canonical chain so legacy users continue to work. Phase 3.1
+moved `figure_renderer.py` (canonical at
+`skills/figure-spec/scripts/figure_renderer.py`); the legacy entry
+at `tools/figure_renderer.py` is now an `os.execv` shim that
+forwards to the canonical file. Only owner SKILLs use layer 0;
+shared helpers (`research_wiki.py`, `save_trace.sh`, …) stay on
+the standard chain.
+
+#### Examples
+
+- ✅ Resolved-via-chain invocation: `python3 "$WIKI_SCRIPT" ingest_paper <root> --arxiv-id <id>` (where `$WIKI_SCRIPT` was set by the chain above with `<helper>=research_wiki.py`)
+- ✅ Resolver block + policy A above for `verify_paper_audits.sh` (submission-gate verifier)
+- ❌ Hard-coded `python3 tools/research_wiki.py …` from a downstream skill that may run in a project without `tools/` on disk — it silently exits 2 and the caller proceeds with no side effect.
+- ❌ N skills each paraphrasing the same 10-line bash snippet. When one drifts, they all drift.
+
+If the same 3+ lines of prose appear in more than two SKILL.md files,
+factor them into a helper.
+
+### 3. Concrete artifact or log entry
+
+Successful execution must leave an observable side effect: a file, a
+JSON record, a log line. The artifact is the receipt — something a
+third party (verifier, code reviewer, human auditor) can inspect to
+answer "did this integration run?"
+
+- ✅ `paper/PROOF_AUDIT.json` with the 6-state verdict schema
+- ✅ `research-wiki/papers/<slug>.md` + `research-wiki/log.md` append
+- ❌ "the model said it ran"
+
+### 4. Visible checklist — for long workflows
+
+If the integration fires inside a multi-step workflow (paper-writing
+Phase 6, idea-discovery Phase 7, etc.), render a **visible checkbox
+block** at the start of the phase so the executor has to confront each
+row before claiming done. Prose-only "MUST" inside a long SKILL.md is
+the first thing to get skipped.
+
+```
+📋 Submission audits required before Final Report:
+   [ ] 1. /proof-checker   → paper/PROOF_AUDIT.json
+   [ ] 2. /paper-claim-audit → paper/PAPER_CLAIM_AUDIT.json
+   [ ] 3. /citation-audit  → paper/CITATION_AUDIT.json
+   [ ] 4. Resolve $AUDIT_VERIFIER via §2 (canonical name verify_paper_audits.sh)
+          then: bash "$AUDIT_VERIFIER" paper/ --assurance submission
+   [ ] 5. Block Final Report iff verifier exit code != 0
+```
+
+Cheap, and empirically resists lazy skipping. Skip only for single-step
+invocations (one-off skills like `/arxiv 2501.12345`).
+
+### 5. Backfill / repair command — explicit manual fallback
+
+An escape hatch for when the integration didn't fire. Users must be
+able to run a command that **declares** the missed inputs and ingests
+them retroactively. Prefer explicit arguments over trace-scanning — the
+helper should not have to guess what to backfill.
+
+- ✅ `/research-wiki sync --arxiv-ids 2501.12345,1706.03762`
+- ✅ `/research-wiki sync --from-file ids.txt`
+- ⚠️ `/research-wiki sync` that scans `.aris/traces/` for arxiv IDs —
+     only as a best-effort secondary mode, not the primary UX, and
+     clearly labeled as heuristic.
+
+### 6. Verifier or diagnostic (only when load-bearing)
+
+If silent failure of this integration would damage the research result
+(wrong numbers shipped to a conference, claims unsupported by
+evidence, citations in wrong context), a verifier script must exist
+whose exit code is the source of truth for downstream gates.
+
+- ✅ `verify_paper_audits.sh` — exit 1 blocks Final Report (resolved per §2)
+- ✅ `verify_wiki_coverage.sh` — diagnostic only, reports gaps but
+     does not block (coverage is not load-bearing on any research
+     outcome; resolved per §2)
+
+Verifiers must be **external processes** (not LLM self-report), must
+validate **concrete artifacts** (§3) against a schema, and must emit a
+structured report callers can parse.
+
+A diagnostic-only verifier (no exit-1 blocking) is still valuable — it
+surfaces drift to humans. But do not market a diagnostic as a gate.
+
+## Anti-patterns to refuse in review
+
+When reviewing a new integration proposal, reject any of:
+
+- **"Optional and automatic"** — contradicts itself; if it's automatic,
+  it's not optional. Pick one and mean it.
+- **"The skill will intelligently decide"** — indecision surface, not
+  a predicate (§1).
+- **"Copy the following 10 lines into each caller"** — missing helper
+  (§2); will drift within a month.
+- **"The reviewer can see from the logs that..."** — if the evidence is
+  unstructured logs, write a schema and make it an artifact (§3).
+- **"Users should remember to..."** — missing backfill (§5); humans
+  don't reliably remember.
+- **"Trust the LLM to self-report completion"** — missing verifier (§6)
+  when the failure is load-bearing.
+
+## Known ARIS integrations under this contract
+
+Helper names in the table below are **canonical names**; callers
+resolve actual paths via §2.
+
+| Integration | Predicate | Helper | Artifact | Checklist | Backfill | Verifier |
+|---|---|---|---|---|---|---|
+| Submission audits (`max`/`beast`) | `paper/.aris/assurance.txt = submission` | `verify_paper_audits.sh` + 3 audit skills emit JSON | `paper/PROOF_AUDIT.json`, `PAPER_CLAIM_AUDIT.json`, `CITATION_AUDIT.json` + `paper/.aris/audit-verifier-report.json` | Phase 6.0 pre-flight checklist | Rerun the failed audit | `verify_paper_audits.sh` (exit 1 blocks) |
+| Research wiki ingest | `research-wiki/` exists | `research_wiki.py ingest_paper` | `research-wiki/papers/<slug>.md` + `log.md` entry | Step in each paper-reading skill | `research_wiki.py sync --arxiv-ids …` | `verify_wiki_coverage.sh` (diagnostic) |
+
+When adding a new cross-skill integration, add a row to the table above
+and confirm all six columns are populated.
+
+## See Also
+
+- `shared-references/assurance-contract.md` — implementation of the
+  paper-writing submission gate under this contract
+- `shared-references/reviewer-independence.md` — the adjacent contract
+  for cross-model review (executor never filters reviewer inputs)
+- `tools/verify_paper_audits.sh`, `tools/research_wiki.py ingest_paper`,
+  `tools/verify_wiki_coverage.sh` — current canonical helpers

package/skills/skills-codex/shared-references/output-composition.md

@@ -0,0 +1,98 @@
+# Output Composition Protocol
+
+> **Codex mirror adaptation (normative).** The `— composed:` and `— standalone`
+> interface is unchanged. Codex subagents return their unique content to the
+> parent; only the parent writes shared deliverables. Resolve trace helpers via
+> the Codex manifest and `$ARIS_REPO/tools/`.
+
+When a skill runs **inside an orchestrating pipeline** (e.g. `/idea-discovery`,
+`/research-pipeline`, `/grant-proposal`, `/kill-argument`), its intermediate
+findings should fold into the pipeline's single canonical deliverable instead of
+each sub-skill scattering its own overlapping `.md` files. When the same skill
+runs **on its own**, it writes its files exactly as documented — unchanged.
+
+This protocol defines the two states, the explicit signal that switches between
+them, and the **enforced default**: with no signal, behave standalone.
+
+> Past idea-discovery runs scattered `LIT_LANDSCAPE.md` + `RESEARCH_REVIEW.md` +
+> `MANIFEST.md` + multiple pilot logs whose content was *also* summarized inside
+> `IDEA_REPORT.md` — pure duplication. This contract is the fix, lifted out of the
+> individual skills so the ~20 skills that compose these don't each carry (and
+> drift) their own copy.
+
+## The two states
+
+- **Standalone (DEFAULT).** The skill writes its own output files exactly as its
+  SKILL.md documents. This is the behavior whenever no composed-mode signal is
+  present — see the fail-safe rule below.
+- **Composed.** The skill is running under an orchestrator that owns one canonical
+  deliverable. The skill's unique findings are folded into that deliverable (as a
+  section, appendix, or linked sub-file the orchestrator manages); the skill does
+  **not** emit standalone overlapping files.
+
+## Composed-mode signal (explicit, fail-safe)
+
+A skill is in composed mode **if and only if** an explicit signal is present:
+
+1. **Orchestrator directive (canonical signal).** The invoking skill passed
+   `— composed: <canonical-report-path>` in the arguments, e.g.
+   `— composed: idea-stage/IDEA_REPORT.md`. The value names the canonical doc to
+   fold into (it may not exist yet — the orchestrator creates/owns it). Orchestrators
+   MUST pass this directive to every sub-skill they want folded.
+2. **Escape hatch.** `— standalone` (or `— composed: false`) forces standalone even
+   if an orchestrator would otherwise pass the directive. Standalone always wins a
+   conflict.
+
+### Fail-safe rule (the one regression we cannot ship)
+
+**When no `— composed:` directive is present, the skill MUST behave standalone and
+write its files as normal.** This is enforced by the contract, not left to per-skill
+discretion.
+
+In particular: **the mere existence of a canonical report file (e.g. a leftover
+`idea-stage/IDEA_REPORT.md` from a previous run) does NOT trigger composed mode.**
+Inferring "composed" from a file on disk would silently swallow a standalone user's
+output the moment they happen to have an old report around — exactly the regression
+to avoid. Composed mode is a decision the orchestrator makes and signals explicitly;
+a sub-skill never guesses it.
+
+## What "fold in" means
+
+When in composed mode, a sub-skill:
+
+1. Returns / hands its unique content to the orchestrator for inlining into the
+   canonical deliverable, rather than writing `LIT_LANDSCAPE.md`,
+   `RESEARCH_REVIEW.md`, or similar standalone summaries.
+2. If it must use a scratch file mid-phase, deletes that scratch once its content is
+   inlined and the phase closes.
+3. Keeps **audit-trail** outputs where they belong — cross-model review traces always
+   go to `.aris/traces/…` per [`review-tracing.md`](review-tracing.md); the canonical
+   report cites the trace path instead of carrying a duplicate human-facing copy.
+4. Keeps **reusable** artifacts (a pilot script, a small results file) but discards
+   disposable scratch (launcher logs, smoke files, redundant `*_summary.json`) once
+   the numbers are in the canonical report.
+
+## Orchestrator responsibilities
+
+An orchestrator that wants folding:
+
+1. Owns exactly one canonical deliverable and passes its path via `— composed: <path>`
+   to each sub-skill.
+2. Inlines each sub-skill's returned findings into the canonical deliverable (or into
+   a small set of stage-scoped files it explicitly manages — e.g. `refine-logs/` —
+   which the report *links to*, not copies).
+3. Does not create a `MANIFEST.md` for a handful of files — see the threshold in
+   [`output-manifest.md`](output-manifest.md). A manifest is itself a duplicate index
+   that has to be kept in sync.
+4. On finish, the deliverable's directory top level should be roughly: the canonical
+   report (+ its `.html`), any reusable script + results, and explicitly-managed
+   stage sub-dirs. Nothing else unless it carries content not in the report.
+
+## Relationship to the other output protocols
+
+- [`output-versioning.md`](output-versioning.md) — *how* to write a file you do write
+  (timestamp + fixed-name copy). Composition decides *whether* a sub-skill writes a
+  standalone file at all.
+- [`output-manifest.md`](output-manifest.md) — only maintain a manifest above the
+  artifact threshold; below it the manifest is itself duplication.
+- [`output-language.md`](output-language.md) — orthogonal; applies in both states.

package/skills/skills-codex/shared-references/output-language.md

@@ -0,0 +1,45 @@
+# Output Language Protocol
+
+## Language Detection
+
+Determine the output language using this priority:
+1. Check `AGENTS.md` for a `language:` field in `## Pipeline Status` — if `language: zh` or `language: cn`, output in Chinese
+2. If the user's most recent message is in Chinese, output in Chinese
+3. Default: English
+
+## What to Localize
+
+- Section headings and labels
+- Descriptions, analysis, commentary, recommendations
+- Template boilerplate text
+- Status messages and warnings
+
+## What NOT to Localize
+
+- Code, shell commands, file paths, directory names
+- Paper titles, author names, venue names, BibTeX entries
+- Technical terms with no standard Chinese translation (keep English, optionally annotate: "attention mechanism (注意力机制)")
+- LaTeX content — paper-writing workflow always outputs English for venue submission
+- JSON state files — keys and structure remain English
+- **Machine-parsed markers** — never localize the following, regardless of language setting:
+  - Markdown frontmatter keys (e.g., `outcome:`, `node_id:`, `title:`, `type:`)
+  - Research Wiki schema fields parsed by `tools/research_wiki.py` (e.g., `outcome: negative`, `outcome: positive`, `node_id:`)
+  - `MANIFEST.md` column headers and table structure
+  - Any field that downstream tools or scripts read programmatically
+
+## Skill-Specific Rules
+
+| Skill | Language Support | Notes |
+|-------|-----------------|-------|
+| /idea-creator | Full | IDEA_REPORT.md follows language setting |
+| /idea-discovery | Full | Inherits from sub-skills |
+| /analyze-results | Full | Result analysis follows language setting |
+| /auto-review-loop | Partial | AUTO_REVIEW.md follows setting; reviewer prompts stay English |
+| /experiment-plan | Full | EXPERIMENT_PLAN.md follows setting |
+| /experiment-bridge | Full | EXPERIMENT_RESULTS.md follows setting |
+| /research-refine | Full | FINAL_PROPOSAL.md follows setting |
+| /research-refine-pipeline | Full | PIPELINE_SUMMARY.md follows setting |
+| /research-pipeline | Full | Inherits from sub-skills |
+| /result-to-claim | Full | Claim descriptions follow setting |
+| /paper-writing | Skip | Always English LaTeX for submission |
+| /paper-write | Skip | Always English LaTeX |

package/skills/skills-codex/shared-references/output-manifest.md

@@ -0,0 +1,40 @@
+# Output Manifest Protocol
+
+After writing any output file, append an entry to `MANIFEST.md` in the project root.
+
+## Format
+
+If `MANIFEST.md` does not exist, create it with this header:
+
+```markdown
+# Research Output Manifest
+
+> Auto-maintained by ARIS skills. Tracks all generated artifacts across the research lifecycle.
+
+| Timestamp | Skill | File | Stage | Description |
+|-----------|-------|------|-------|-------------|
+```
+
+Then append one row per output file written:
+
+```
+| 2025-06-15 14:30 | /idea-creator | idea-stage/IDEA_REPORT_20250615_143022.md | idea-discovery | 12 ideas generated from "LLM reasoning" direction |
+| 2025-06-15 14:30 | /idea-creator | idea-stage/IDEA_REPORT.md | idea-discovery | latest copy |
+```
+
+## Stage Values
+
+| Stage | Skills |
+|-------|--------|
+| `idea-discovery` | /idea-creator, /idea-discovery, /novelty-check, /research-review |
+| `implementation` | /research-refine, /research-refine-pipeline, /experiment-plan, /experiment-bridge, /run-experiment |
+| `review` | /auto-review-loop |
+| `paper` | /paper-writing, /paper-write, /paper-compile |
+
+## Pre-flight Check
+
+Before writing output, if the skill depends on a prerequisite file from a previous stage:
+1. Check if the prerequisite file exists at its expected stage-scoped path (e.g., `idea-stage/IDEA_REPORT.md`, `review-stage/AUTO_REVIEW.md`)
+2. If not found at the stage-scoped path, check the legacy root-level path (e.g., `./IDEA_REPORT.md`, `./AUTO_REVIEW.md`) — see [Path Fallback Rule](output-versioning.md#path-fallback-rule-backward-compatibility)
+3. If not found at either path, warn: "⚠️ Expected {file} (from {skill}) but not found. Run {skill} first?"
+4. Do not block — the user may have the file elsewhere or want to proceed anyway

package/skills/skills-codex/shared-references/output-versioning.md

@@ -0,0 +1,111 @@
+# Output Versioning Protocol
+
+When writing any output file that would overwrite an existing file, use timestamped filename + fixed-name latest copy:
+
+1. Write output to timestamped file: `{FILENAME}_{YYYYMMDD_HHmmss}.md` (or `.json`, `.tex` as appropriate)
+   - Timestamp precision to seconds to reduce collisions. In the rare case of sub-second conflicts, append `_2`, `_3` etc.
+   - Place the timestamped file in the same directory as the fixed-name file
+2. Copy the same content to the fixed-name file: `{FILENAME}.md` (overwrites the previous latest copy)
+3. Downstream skills always read the fixed-name file — they do not need to know about timestamps
+
+## Directory Structure
+
+All ARIS output files are organized by workflow stage:
+
+```
+project/
+├── AGENTS.md                              # Dashboard / agent instructions (root — read by all stages)
+├── findings.md                            # Cross-stage discovery log (root — append-only)
+├── MANIFEST.md                            # Output tracking manifest (root)
+│
+├── idea-stage/                            # W1: Idea Discovery
+│   ├── IDEA_REPORT.md                     # Latest copy
+│   ├── IDEA_REPORT_20250615_143022.md     # Timestamped version
+│   ├── IDEA_CANDIDATES.md
+│   ├── REF_PAPER_SUMMARY.md
+│   └── docs/
+│       └── research_contract.md
+│
+├── refine-logs/                           # W1.5: Experiment Planning & Refinement
+│   ├── EXPERIMENT_PLAN.md
+│   ├── EXPERIMENT_TRACKER.md
+│   ├── EXPERIMENT_RESULTS.md
+│   ├── FINAL_PROPOSAL.md
+│   ├── PIPELINE_SUMMARY.md
+│   ├── REFINE_STATE.json
+│   ├── REVIEW_SUMMARY.md
+│   ├── REFINEMENT_REPORT.md
+│   └── round_N_*.md
+│
+├── review-stage/                          # W2: Auto Review
+│   ├── AUTO_REVIEW.md
+│   └── REVIEW_STATE.json
+│
+├── paper/                                 # W3: Paper Writing
+│   ├── main.tex
+│   └── roundN/
+│
+└── research-wiki/                         # Persistent knowledge base
+```
+
+## What to Timestamp
+
+Files that get overwritten on re-runs:
+- `IDEA_REPORT.md`, `IDEA_CANDIDATES.md`, `REF_PAPER_SUMMARY.md`
+- `EXPERIMENT_PLAN.md`, `EXPERIMENT_TRACKER.md`, `EXPERIMENT_RESULTS.md`
+- `FINAL_PROPOSAL.md`, `PIPELINE_SUMMARY.md`
+- `AUTO_REVIEW.md` (when starting a new review loop, not within a loop)
+- `paper/main.tex`
+- State files: `REFINE_STATE.json`, `REVIEW_STATE.json`
+
+## What NOT to Timestamp
+
+- **Append-only files**: `findings.md`, `research-wiki/log.md` — these accumulate entries, not overwrite
+- **Per-round files**: `refine-logs/round_N_*.md` — already versioned by round number
+- **Dashboard**: `AGENTS.md` — single source of truth, always latest
+- **MANIFEST.md** — append-only tracking file
+
+Never delete timestamped files. They are the permanent history.
+
+## Path Fallback Rule (Backward Compatibility)
+
+Skills that **read** stage-scoped files must fall back to the old root-level location for projects created before this layout was introduced:
+
+```
+# For idea-stage files:
+Read from idea-stage/IDEA_REPORT.md
+If not found → fall back to ./IDEA_REPORT.md
+
+Read from idea-stage/IDEA_CANDIDATES.md
+If not found → fall back to ./IDEA_CANDIDATES.md
+
+# For review-stage files:
+Read from review-stage/AUTO_REVIEW.md
+If not found → fall back to ./AUTO_REVIEW.md
+
+Read from review-stage/REVIEW_STATE.json
+If not found → fall back to ./REVIEW_STATE.json
+```
+
+Skills that **write** always use the stage-scoped path (never write to root). This ensures new runs migrate output forward while old projects continue to work.
+
+## Migration for Existing Projects
+
+If you find root-level files (`IDEA_REPORT.md`, `AUTO_REVIEW.md`, etc.) and the stage directories do not yet exist, you may optionally offer to migrate:
+
+```
+📁 Found legacy root-level files. Migrate to stage directories?
+  mv IDEA_REPORT.md idea-stage/IDEA_REPORT.md
+  mv AUTO_REVIEW.md review-stage/AUTO_REVIEW.md
+  (etc.)
+Only do this if the user confirms — do not auto-migrate silently.
+```
+
+## Stale State Detection
+
+Before reading a state file (`REFINE_STATE.json`, `REVIEW_STATE.json`, `DSE_STATE.json`):
+1. Check the file's last modified time via `ls -la` or `stat`
+2. Default staleness threshold: **24 hours** (individual skills may override — e.g., `auto-review-loop` uses 24h, `research-refine` uses 24h). If a skill defines its own threshold, that takes precedence.
+3. If older than the threshold, warn the user:
+   "⚠️ State file {filename} is {N} hours/days old. It may be from a previous research direction. Continue with this state, or start fresh?"
+4. If the user chooses to start fresh, write a timestamped archive copy and proceed without the old state