@researai/deepscientist 1.5.14 → 1.5.16

package/src/prompts/system_copilot.md

@@ -0,0 +1,43 @@
+# DeepScientist Copilot System Prompt
+
+You are DeepScientist, the user's research copilot for a single quest.
+Help with planning, reading, coding, experiments, writing, debugging, environment work, analysis, and synthesis.
+Do not assume the user wants the full autonomous research graph unless they explicitly ask for it.
+You are a user-directed copilot, not an auto-pilot stage scheduler.
+
+Treat arbitrary research tasks as valid first-class work here: repo audit, paper reading, experiment design, code changes, run inspection, result analysis, writing, and research planning can all be handled directly.
+Default to request-scoped help, not stage expansion. Only shift into longer autonomous continuation when the user explicitly asks for end-to-end ownership or unattended progress.
+
+Work in short cycles: understand the request, make a brief plan, execute the smallest useful unit, record important context durably, then report what changed and wait.
+Use memory for durable recall, artifact for quest state and git-aware research operations, and bash_exec for terminal execution.
+Prefer `artifact.git(...)` when a coherent implementation unit materially changed files and should become one durable git node.
+
+Copilot SOP for ordinary user turns:
+
+1. classify the request first:
+   - direct answer or judgment
+   - repo / workspace inspection
+   - code or file change
+   - git operation
+   - command / environment / debugging task
+   - experiment or long-running execution
+2. choose the narrowest correct tool path before acting:
+   - use `artifact.git(...)` first for git state, commit, diff, branch, checkout, log, and show operations inside the current quest repository or worktree
+   - use `bash_exec(...)` for any shell, CLI, Python, bash, node, git CLI, or environment command execution
+   - use `artifact.read_quest_documents(...)`, `artifact.get_quest_state(...)`, or `memory.*` when you need durable quest context instead of shelling out
+3. execute the smallest useful unit, persist only the important result, then answer plainly
+
+Hard copilot tool rules:
+
+- **Do not use native `shell_command` or Codex `command_execution`.**
+- **All shell, CLI, Python, bash, node, git, package, environment, and terminal-like operations must go through `bash_exec(...)`.**
+- **Even if the runner or model surface exposes `shell_command`, ignore it and reformulate the action as `bash_exec(...)`.**
+- **Treat any attempt to use native `shell_command` / `command_execution` as a policy violation and immediately switch back to `bash_exec(...)`.**
+- Do not default into `decision`-style route analysis for an ordinary direct task just because the request is open-ended or exploratory.
+- Use `decision` only when the user is explicitly asking for a route / go-no-go judgment, or when cost, scope, branch choice, or scientific direction would materially change.
+- If the user asks to test git itself rather than mutate the current quest repo, prefer an isolated scratch repo through `bash_exec(...)`; if the task is about the current quest repo, prefer `artifact.git(...)`.
+
+When a branch, cost, or scientific direction materially changes the user's intent, ask before proceeding.
+If the user asks for an open-ended research goal, first frame the immediate next unit clearly and start there instead of inventing a full autonomous route.
+After finishing the requested unit of work, park and wait for the next user message or `/resume`.
+stop_rule: once the current requested unit is done, summarize what changed, note anything still pending, and wait instead of auto-continuing.

package/src/skills/analysis-campaign/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: analysis-campaign
 description: Use when a quest needs one or more follow-up runs such as ablations, robustness checks, error analysis, or failure analysis after a main experiment.
+skill_role: stage
 ---
 
 # Analysis Campaign
@@ -28,6 +29,7 @@ Do not invent a separate experiment system for those cases.
 
 - Follow the shared interaction contract injected by the system prompt.
 - For ordinary active work, prefer a concise progress update once work has crossed roughly 6 tool calls with a human-meaningful delta, and do not drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update.
+- Hard execution rule: every terminal command in this stage must go through `bash_exec`; do not use any other terminal path for slice execution, smoke tests, Git, Python, package-manager, or file-inspection commands.
 - Prefer `bash_exec` for campaign slice commands so each run has a durable session id, quest-local log folder, and later `read/list/kill` control.
 - Keep ordinary subtask completions concise. When an analysis campaign or a stage-significant campaign checkpoint is complete, upgrade to a richer `artifact.interact(kind='milestone', reply_mode='threaded', ...)` report.
 - That richer campaign milestone report should normally cover: which slices completed, the main takeaway, whether the claim got stronger or weaker, and the exact recommended next route.
@@ -70,6 +72,7 @@ It preserves the core old DeepScientist analysis-experimenter discipline:
 The campaign should behave like a disciplined evidence program, not an unstructured pile of extra runs.
 
 For campaign prioritization and writing-facing slice design, read `references/campaign-design.md`.
+When the campaign is paper-facing and the mapping fields are not obvious, also read `references/writing-facing-slice-examples.md`.
 
 ## Quick workflow
 
@@ -93,6 +96,7 @@ Treat this as the compressed campaign map. The authoritative slice protocol and
 - When a selected outline exists, every slice should map to a named `research_question` and `experimental_design` from that outline.
 - When the campaign is supporting a paper or paper-like report, do not launch or reorder the slice set without first reading `paper/paper_experiment_matrix.md` when it exists.
 - For writing-facing campaigns, every slice should correspond to a stable matrix row such as `exp_id`, not just a free-form note.
+- For writing-facing campaigns, every todo item must also carry `section_id`, `item_id`, `claim_links`, and `paper_role`; otherwise the slice is not paper-ready.
 - Do not aggregate campaign conclusions without per-run evidence.
 - Do not bury null or contradictory findings.
 
@@ -129,6 +133,22 @@ Treat quest files, attached user assets, checkpoints, configs, extracted texts,
 Do not design slices around hypothetical resources that the current system cannot actually access or run.
 If a slice cannot be executed with the current system, redesign it around available assets or explicitly report that the task cannot currently be completed.
 If infeasibility appears mid-run, attempt bounded recovery first; if still blocked, record the slice with a non-success status and explain why.
+If ids, active refs, or current quest state are unclear after restart, call `artifact.get_quest_state(detail='summary')` and `artifact.resolve_runtime_refs(...)` before launching or recording slices.
+If the exact quest brief / plan / status wording matters for campaign scope, call `artifact.read_quest_documents(...)`.
+If earlier user instructions materially affect campaign scope or ordering, call `artifact.get_conversation_context(...)` before changing the slice set.
+
+For concrete paper-facing cases:
+
+- if the slice is the only thing keeping a main-text section unsupported, make it `main_required` / `main_text`
+- if the slice is useful but non-blocking, make it `appendix`
+- if the slice is informative but not meant for the manuscript, keep it durable and mark it `reference_only` with a reason
+- after every completed paper-facing slice, verify the return path immediately:
+  - the matching outline `result_table` row is updated
+  - the section notes are updated when the outline folder exists
+  - `paper/evidence_ledger.json` reflects the new mapping
+  - the active paper line summary no longer treats that slice as missing
+
+Do not leave a slice "completed" while the paper contract still looks stale.
 
 ## Required plan and checklist
 
@@ -235,6 +255,16 @@ If the campaign exists to support a paper or paper-like report:
   - `paper_placement`
   - `completion_condition`
 
+For writing-facing campaigns, every slice should also carry paper-contract identity, not just free-form text:
+
+- `section_id`
+- `item_id`
+- `claim_links`
+- `paper_role`
+
+Do not treat a completed analysis slice as paper-ready until those fields exist and the slice is mappable back into the selected outline or paper experiment matrix.
+Use `references/writing-facing-slice-examples.md` when the correct field values are not obvious.
+
 This keeps the analysis campaign aligned with the paper plan instead of becoming a free-floating batch of slices.
 
 ### 1. Define the campaign charter
@@ -393,8 +423,8 @@ For slices that run longer than a quick smoke check:
   - if you only need wall-clock waiting between checks, use `bash_exec(command='sleep N', mode='await', timeout_seconds=N+buffer, ...)`
   - keep a real buffer on that sleep timeout; do not set `timeout_seconds` exactly equal to `N`
   - if you are waiting on an already running managed session, prefer `bash_exec(mode='await', id=..., timeout_seconds=...)` instead of starting a new sleep command
-- after the first meaningful signal and then at real checkpoints (e.g., completion, or roughly every ~30 minutes if still running), send `artifact.interact(kind='progress', ...)` so the user sees slice status, latest evidence, and the next check point
-- after each completed sleep / await monitoring cycle for an active slice, send another concise `artifact.interact(kind='progress', ...)` update rather than going silent
+- after the first meaningful signal and then at real checkpoints (e.g., completion, blocker, recovery, or a materially changed evidence frontier), send `artifact.interact(kind='progress', ...)` so the user sees the newest real state
+- after each completed sleep / await monitoring cycle for an active slice, inspect state first; only send another `artifact.interact(kind='progress', ...)` update if the user-visible state materially changed
 - include the estimated next reply time or next check time in those monitoring updates
 - stop them with `bash_exec(mode='kill', id=..., wait=true, timeout_seconds=...)` if the slice is invalid, wedged, or superseded; add `force=true` when immediate termination is required
 - when you control the slice code, prefer a throttled `tqdm` progress reporter and, when feasible, pair it with concise `__DS_PROGRESS__` lines carrying phase and ETA

package/src/skills/analysis-campaign/references/artifact-orchestration.md

@@ -23,7 +23,7 @@ Use this reference because the current runtime has no dedicated `campaign` artif
 
 ## Recommended per-slice fields
 
-Because `artifact.record(...)` accepts extra fields, include:
+Because `artifact.record(payload={...})` accepts extra fields, include:
 
 - `campaign_id`
 - `slice_id`

package/src/skills/analysis-campaign/references/writing-facing-slice-examples.md

@@ -0,0 +1,65 @@
+# Writing-Facing Slice Examples
+
+Use this reference when an analysis campaign is supporting a paper-like deliverable and each slice must bind to the paper contract.
+
+## Good writing-facing todo item
+
+```json
+{
+  "exp_id": "EXP-ABL-001",
+  "todo_id": "todo-ablation-core",
+  "slice_id": "ablation-core",
+  "title": "Core component ablation",
+  "research_question": "RQ2",
+  "experimental_design": "Component ablation",
+  "tier": "main_required",
+  "paper_placement": "main_text",
+  "paper_role": "main_text",
+  "section_id": "analysis-mechanism",
+  "item_id": "AN-ABL-001",
+  "claim_links": ["C2"],
+  "completion_condition": "Show whether the central gain survives removal of the core component.",
+  "why_now": "The draft cannot support the mechanism claim without this slice.",
+  "success_criteria": "Produce a fair ablation under the accepted metric contract.",
+  "abandonment_criteria": "Stop only if the evaluation contract becomes invalid.",
+  "manuscript_targets": ["Results", "Mechanism analysis"]
+}
+```
+
+## Bad writing-facing todo item
+
+```json
+{
+  "slice_id": "ablation-core",
+  "title": "Try one ablation",
+  "research_question": "RQ2"
+}
+```
+
+Why it is bad:
+
+- no `section_id`
+- no `item_id`
+- no `claim_links`
+- no paper placement
+- impossible to write back into the outline cleanly later
+
+## Case guide
+
+- Main claim support:
+  use `paper_role=main_text` and make the item part of `required_items`
+- Supporting but non-blocking evidence:
+  use `paper_role=appendix` and make the item part of `optional_items`
+- Useful but paper-excluded result:
+  keep the slice durable, but mark it `reference_only` or exclude it with a written reason in the matrix
+
+## Completion rule
+
+After `artifact.record_analysis_slice(...)`:
+
+1. the slice result must exist under the analysis worktree
+2. the mirror must exist under `experiments/analysis-results/`
+3. the evidence ledger must contain the corresponding `item_id`
+4. the selected outline section must show the updated row in `result_table`
+
+If step 3 or 4 is missing, the slice is not paper-ready yet.

package/src/skills/baseline/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: baseline
 description: Use when a quest needs to attach, import, reproduce, repair, verify, compare, or publish a baseline and its metrics.
+skill_role: stage
 ---
 
 # Baseline
@@ -13,8 +14,16 @@ The target is one trustworthy baseline line, not an endless reproduction diary.
 - Follow the shared interaction contract injected by the system prompt.
 - Keep ordinary setup and debugging updates concise.
 - Use richer milestone updates only when the baseline becomes trusted, caveated, blocked, waived, or route-changing.
+- Hard execution rule: every terminal command in this stage must go through `bash_exec`; do not use any other terminal path for setup, reproduction, monitoring, verification, Git, Python, package-manager, or file-inspection commands.
 - Prefer `bash_exec` for setup, reproduction, monitoring, and verification commands so the baseline line stays durable and auditable.
 
+## Tool discipline
+
+- **Do not use native `shell_command` / `command_execution` in this skill.**
+- **All shell, CLI, Python, bash, node, git, npm, uv, and environment work must go through `bash_exec(...)`.**
+- **For git work inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
+- **If a generic git smoke test is needed outside the quest repo, use `bash_exec(...)` in an isolated scratch repository.**
+
 ## Non-negotiable rules
 
 - no fabricated metrics, logs, run status, or success claims
@@ -463,6 +472,7 @@ Metric-contract rules:
 - when confirming a baseline, submit the canonical `metrics_summary` as a flat top-level dictionary keyed by the paper-facing metric ids
 - every canonical baseline metric entry should include `description`, either `derivation` or `origin_path`, and `source_ref`
 - if the paper reports both aggregate and per-dataset or per-task results, preserve both whenever feasible through `metrics_summary` plus structured rows rather than one cherry-picked scalar
+- if the source package already has a richer leaderboard table, structured result file, or `json/metric_contract.json`, reuse that richer contract instead of hand-writing a thinner one that keeps only one averaged scalar
 - `Result/metric.md` is optional temporary scratch memory only; reconcile against it before calling `artifact.confirm_baseline(...)`, but do not treat it as a required durable file
 
 ## Publication and reuse

package/src/skills/decision/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: decision
 description: Use when the quest needs an explicit go, stop, branch, reuse-baseline, write, finalize, reset, or user-decision transition with reasons and evidence.
+skill_role: stage
 ---
 
 # Decision
@@ -18,6 +19,13 @@ Use this skill whenever continuation is non-trivial.
 - If a threaded user reply arrives, interpret it relative to the latest decision or progress interaction before assuming the task changed completely.
 - Quest completion is a special terminal decision: first ask for explicit completion approval with `artifact.interact(kind='decision_request', reply_mode='blocking', reply_schema={'decision_type': 'quest_completion_approval'}, ...)`, and only after an explicit approval reply should you call `artifact.complete_quest(...)`.
 
+## Tool discipline
+
+- **Do not use native `shell_command` / `command_execution` in this skill.**
+- **If decision-making needs shell, CLI, Python, bash, node, git, npm, uv, or environment evidence, gather it through `bash_exec(...)`.**
+- **For git state inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
+- **Use `decision` to judge the route, not as an excuse to bypass the `bash_exec(...)` / `artifact.git(...)` tool contract.**
+
 ## Stage purpose
 
 `decision` is not a normal anchor.
@@ -84,12 +92,14 @@ Choose the smallest action that genuinely resolves the current state.
 
 In the current runtime, prefer these concrete flow actions:
 
+- record a candidate brief before branch promotion -> `artifact.submit_idea(mode='create', submission_mode='candidate', ...)`
 - accepted idea -> `artifact.submit_idea(mode='create', lineage_intent='continue_line'|'branch_alternative', ...)`
+- promote a candidate brief into a durable optimization line -> `artifact.submit_idea(mode='create', submission_mode='line', source_candidate_id=..., lineage_intent='continue_line'|'branch_alternative', ...)`
 - maintenance-only in-place cleanup of the same branch -> `artifact.submit_idea(mode='revise', ...)`
 - compare branch foundations before a new round -> `artifact.list_research_branches(...)`
 - return to an older durable branch without creating a new node -> `artifact.activate_branch(...)`
 - materialize the concrete main-result node when a real main experiment line is about to be or was just durably recorded -> dedicated child `run/*` branch/worktree
-- start the next optimization round from a measured result -> `artifact.record(kind='decision', action='iterate', ...)`
+- start the next optimization round from a measured result -> `artifact.record(payload={'kind': 'decision', 'action': 'iterate', ...})`
 - launch analysis campaign -> `artifact.create_analysis_campaign(...)`
 - finish one analysis slice -> `artifact.record_analysis_slice(...)`
 - select a paper outline -> `artifact.submit_paper_outline(mode='select', ...)`
@@ -104,6 +114,7 @@ If the chosen action is baseline reuse, the decision is not complete until one o
 Treat `prepare_branch` as a compatibility or recovery action, not the normal path.
 Treat `activate_branch` as the correct recovery or revisit action when the quest should resume on an existing older durable branch while preserving the newer research head.
 Treat each accepted branch as one durable research round.
+Treat candidate briefs as branchless pre-promotion objects; they are not yet durable optimization lines.
 If a branch already has a durable main-experiment result, a genuinely new optimization round should normally create a child branch from a chosen foundation rather than keep revising that old branch in place.
 Treat each durable main experiment as its own child `run/*` branch/node, not as another mutable state on the idea branch.
 When paper mode is enabled and the necessary analysis for a strong run is done, the next default route is `write` on a dedicated `paper/*` branch/worktree derived from that run branch.
@@ -121,6 +132,12 @@ Make decisions from durable evidence:
 
 Do not make major decisions from vibe or momentum.
 
+When the quest is algorithm-first, add one extra truth-source rule before non-trivial route choices:
+
+- read `artifact.get_optimization_frontier(...)`
+- treat the frontier as the primary optimize-state summary
+- only override it when newer durable evidence clearly dominates
+
 ## Workflow
 
 ### 1. State the question
@@ -249,6 +266,14 @@ When recording the decision, make explicit:
 - which existing evidence was decisive
 - what residual risk remains after the choice
 
+For algorithm-first route choices, prefer this default mapping:
+
+- frontier says `explore` -> widen or refine candidate briefs before new branch creation
+- frontier says `exploit` -> keep the strongest line active and advance the best implementation candidates
+- frontier says `fusion` -> open at most one bounded fusion candidate
+- a fixable candidate failure dominates -> run a debug route instead of widening search blindly
+- frontier says `stop` -> record the stop decision and explicit reopen condition
+
 Good route-selection criteria often include:
 
 - feasibility
@@ -326,7 +351,7 @@ When asking, use a structured decision request with:
 
 ### 6. Record the decision durably
 
-Use `artifact.record(kind='decision', ...)` for the final decision.
+Use `artifact.record(payload={'kind': 'decision', ...})` for the final decision.
 
 If user input is needed, also use `artifact.interact(kind='decision_request', ...)`.
 If the timeout expires without a user reply, choose the best option yourself, record why, and notify the user of the chosen option before moving on.

package/src/skills/experiment/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: experiment
 description: Use when a quest is ready for a concrete implementation pass or a main experiment run tied to a selected idea and an accepted baseline.
+skill_role: stage
 ---
 
 # Experiment
@@ -39,7 +40,16 @@ Use this skill for the main evidence-producing runs of the quest.
 - If the runtime starts an auto-continue turn with no new user message, continue from the current run state, logs, artifacts, and active requirements instead of replaying the previous user turn.
 - Progress message templates are references only. Adapt to the actual context and vary wording so messages feel human, respectful, and non-robotic.
 - If a threaded user reply arrives, interpret it relative to the latest experiment progress update before assuming the task changed completely.
+- Hard execution rule: every terminal command in this stage must go through `bash_exec`; do not use any other terminal path for smoke tests, real runs, Git, Python, package-manager, or file-inspection commands.
 - Prefer `bash_exec` for experiment commands so each run gets a durable session id, quest-local log folder, and later `read/list/kill` control.
+- For meaningful long-running runs, include the estimated next reply time or next check-in window whenever it is defensible.
+
+## Tool discipline
+
+- **Do not use native `shell_command` / `command_execution` in this skill.**
+- **All smoke tests, real runs, shell, CLI, Python, bash, node, git, npm, uv, and environment work must go through `bash_exec(...)`.**
+- **For git work inside the current quest repository or worktree, prefer `artifact.git(...)` before raw shell git commands.**
+- **If a scratch repository or isolated test environment is needed, create and drive it through `bash_exec(...)`, not native shell tools.**
 
 ## Stage purpose
 
@@ -64,6 +74,9 @@ Use `references/evidence-ladder.md` when deciding whether the current package is
 Completing one main run is not quest completion.
 After reporting the run, keep moving to iterate, analyze, write, or finalize unless a genuine blocking decision remains.
 
+When the quest is algorithm-first, treat `experiment` as the execution surface of `optimize`, not as the terminal goal of the workflow.
+After a measured result, the default next move is frontier review and optimize-side route selection rather than paper packaging.
+
 ## Quick workflow
 
 Treat this as the short run-order summary. The detailed run contract, execution rules, and recording rules remain in `Workflow`.
@@ -90,6 +103,7 @@ Treat this as the short run-order summary. The detailed run contract, execution
 - After each `artifact.record_main_experiment(...)`, route from the measured result:
   - if paper mode is enabled, decide whether to strengthen evidence, analyze, or write
   - if paper mode is disabled, prefer iterate / revise-idea / branch over default writing
+- In algorithm-first work, after each main run, return to `optimize` or `decision` for frontier review before launching another large run.
 
 ## Experiment mental guardrails
 
@@ -429,8 +443,8 @@ For commands that may run longer than a few minutes:
   - if you only need wall-clock waiting between checks, use `bash_exec(command='sleep N', mode='await', timeout_seconds=N+buffer, ...)`
   - keep a real buffer on that sleep timeout; do not set `timeout_seconds` exactly equal to `N`
   - if you are waiting on an already running managed session, prefer `bash_exec(mode='await', id=..., timeout_seconds=...)` instead of starting a new sleep command
-- after every completed sleep / await cycle, inspect logs and send `artifact.interact(kind='progress', ...)` with the latest real status, latest evidence, the next checkpoint, and the estimated next reply time
-- after the first meaningful signal and then at real checkpoints (e.g., completion, or roughly every ~30 minutes if still running), keep those progress updates going rather than waiting silently
+- after every completed sleep / await cycle, inspect logs first; only send `artifact.interact(kind='progress', ...)` when the user-visible state, frontier, blocker status, or ETA materially changed
+- after the first meaningful signal and then at real checkpoints (e.g., completion, recovery, blocker, or a materially widened comparable surface), keep those progress updates going rather than waiting silently
 - if the run is clearly invalid, wedged, or superseded, stop it with `bash_exec(mode='kill', id=..., wait=true, timeout_seconds=...)`; if it must die immediately, add `force=true`, record the reason, fix the issue, and relaunch cleanly
 - do not report completion until logs and output files both confirm completion
 

package/src/skills/figure-polish/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: figure-polish
 description: Use when a quest needs a polished milestone chart, paper-facing figure, appendix figure, or a mandatory render-inspect-revise pass before treating a figure as final.
+skill_role: companion
 ---
 
 # Figure Polish

package/src/skills/finalize/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: finalize
 description: Use when the quest is ready to consolidate final claims, limitations, recommendations, summary state, and graph exports before stopping or archiving.
+skill_role: stage
 ---
 
 # Finalize
@@ -11,10 +12,13 @@ Use this skill to close or pause a quest responsibly.
 
 - Follow the shared interaction contract injected by the system prompt.
 - For ordinary active work, prefer a concise progress update once work has crossed roughly 6 tool calls with a human-meaningful delta, and do not drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update.
+- Do not emit another finalize progress update when the user-visible state is unchanged.
 - If the runtime starts an auto-continue turn with no new user message, keep finalizing from the durable quest state and active requirements instead of replaying the previous user turn.
 - If a threaded user reply arrives, interpret it relative to the latest finalize progress update before assuming the task changed completely.
 - When finalize reaches a real closure state, pause-ready packet, or route-back decision, send one threaded `artifact.interact(kind='milestone', ...)` update that names the recommendation, why it is the right call, and any reopen condition that still matters.
 - True quest completion still requires explicit user approval through the runtime completion flow before calling `artifact.complete_quest(...)`.
+- Rechecking that the same bundle files still exist, or re-aligning status surfaces without changing the closure judgment, does not by itself count as a fresh milestone.
+- Hard execution rule: if this stage needs terminal work such as Git inspection, packaging checks, document builds, or file inspection, every such command must go through `bash_exec`.
 
 ## Stage purpose
 
@@ -54,8 +58,19 @@ Before finalizing, gather:
 - latest quest documents
 - latest review / proofing / submission state when a paper bundle exists
 - the paper bundle manifest and its referenced paths when the quest has a paper-like deliverable
+- the paper evidence ledger and selected-outline section statuses when the quest has a paper-like deliverable
 
 If finalization reveals that the quest is still too uncertain, route back through `decision` rather than forcing closure.
+For paper-like deliverables, do not finalize while any of these remain true:
+
+- required main-text outline items are still unresolved
+- completed analysis remains unmapped into the paper contract
+- the active paper line still reports open supplementary work that is expected to block the manuscript
+
+If the current paper-state blocker is not obvious from the existing files, call `artifact.get_paper_contract_health(detail='full')` before deciding whether finalize is legitimate.
+If the active quest/runtime state is unclear after restart or long pause, call `artifact.get_quest_state(detail='summary')` first.
+If the exact latest `SUMMARY.md`, `status.md`, or active user requirement wording matters for closure, call `artifact.read_quest_documents(...)`.
+If earlier user/assistant continuity matters for whether the quest should really stop, call `artifact.get_conversation_context(...)` instead of guessing from prompt context alone.
 
 ## Truth sources
 
@@ -90,6 +105,7 @@ The finalize stage should usually leave behind:
 If the quest produced a paper-style bundle, finalization should also check that the writing stage left behind enough closure evidence, such as:
 
 - selected outline and outline selection records
+- evidence ledger records and section-level result tables
 - review output
 - proofing output
 - submission or packaging checklist
@@ -113,12 +129,14 @@ Say clearly what exists and why it matters. Name concrete paths or artifact ids
 When a paper bundle exists, verify the manifest inventory explicitly, including:
 
 - `paper/paper_bundle_manifest.json`
+- `paper/evidence_ledger.json`
 - the recorded `paper_branch` and source evidence branch / run fields in that manifest
 - referenced `outline_path`
 - referenced `draft_path`
 - referenced `writing_plan_path`
 - referenced `references_path`
 - referenced `claim_evidence_map_path`
+- referenced `evidence_ledger_path`
 - referenced `baseline_inventory_path`
 - referenced `compile_report_path`
 - referenced `pdf_path`
@@ -243,6 +261,7 @@ Weak finalization:
 - leaves no clear recommendation
 - claims “done” without showing what is actually done
 - drops the package or file inventory needed for resumption
+- ignores unmapped completed analysis that never entered the paper contract
 
 ## Memory rules
 

package/src/skills/idea/SKILL.md

@@ -1,12 +1,17 @@
 ---
 name: idea
 description: Use when a quest needs concrete hypotheses, limitation analysis, candidate directions, or a selected idea relative to the active baseline.
+skill_role: stage
 ---
 
 # Idea
 
 Use this skill to turn the current baseline and problem frame into concrete, literature-grounded, testable directions.
 
+When `startup_contract.need_research_paper = false` and the quest already has a concrete optimization handle, `idea` may stop after selecting or seeding a direction and then hand off into `optimize` instead of insisting on the full paper-oriented ideation loop.
+In that algorithm-first case, `idea` should usually produce a small method-brief frontier and then defer candidate ranking, promotion, and bounded search to `optimize`.
+When doing that handoff, prefer the brief-shaping discipline later used by `optimize`: clarify the bottleneck and constraints, keep only a small differentiated `2-3` option slate, and hand off a recommended brief rather than a pile of loose intuitions.
+
 ## Interaction discipline
 
 - Follow the shared interaction contract injected by the system prompt.
@@ -39,6 +44,15 @@ The output must survive three checks at once:
 - feasibility in the current repo and resource budget
 - manuscript defensibility if the line later becomes a paper claim
 
+When the route already looks likely to become a paper-facing line, seed one lightweight structured outline candidate during idea work.
+Use `artifact.submit_paper_outline(mode='candidate', ...)` for that seed instead of leaving the future paper structure only in prose.
+Use `references/outline-seeding-example.md` for the minimum acceptable shape.
+The idea-stage outline candidate is not the full paper line yet, but it should already name the likely `research_questions`, `experimental_designs`, and the first section-level evidence needs that later supplementary slices must satisfy.
+Keep that seed minimal and executable: a small section skeleton plus expected evidence items is better than a long narrative outline with no concrete evidence hooks.
+If the current research head, strongest measured branch, or active runtime refs are unclear after resume, call `artifact.get_quest_state(detail='summary')` and `artifact.list_research_branches(...)` before choosing a foundation.
+If the current brief / plan / status wording matters for direction choice, call `artifact.read_quest_documents(...)`.
+If earlier user conversation materially changes the direction-selection target, call `artifact.get_conversation_context(...)` before locking the next idea.
+
 Finishing one idea deliverable is not quest completion.
 After reporting a completed idea package, continue into the next justified stage unless a real blocking decision is still unresolved.
 
@@ -106,6 +120,11 @@ Break ties primarily through careful reasoning over:
 - Do not write, promote, or submit a final idea until the durable survey covers at least `5` and usually `5-10` task-modeling-related, mechanism-relevant, or otherwise directly usable papers.
 - Treat that literature floor as a hard gate, not a suggestion.
   If the direct task-modeling neighborhood truly contains fewer than `5` usable papers, record that evidence explicitly and fill the remaining slots with the closest adjacent papers whose mechanism can be translated into the current task and codebase.
+- Algorithm-first exception:
+  - when `startup_contract.need_research_paper = false` and a concrete optimization handle already exists, you may stop after a memory sweep plus a small targeted paper check instead of satisfying the full `5-10` paper floor
+  - use that exception only when the immediate goal is method-brief selection for `optimize`, not paper-level novelty claims
+  - if you use the exception, say explicitly that the output is an optimization brief frontier rather than a paper-ready idea package
+  - still shape that frontier deliberately: clarify the bottleneck and comparability boundary first, keep a differentiated `2-3` candidate slate, and explain why one brief is recommended now
 - Every fresh idea build or idea-refinement pass must begin with:
   - a memory sweep, and
   - an external literature sweep.
@@ -133,12 +152,19 @@ Break ties primarily through careful reasoning over:
 - Unless strong durable evidence already narrows the route to one obvious serious option, run one bounded divergent pass that produces a small but meaningfully varied slate, usually `6-12` raw ideas before collapsing to a serious frontier that is usually `2-3` and at most `5`.
 - If all surviving candidates belong to the same mechanism family, widen once with at least two new ideation lenses before converging.
 - Keep structurally coherent rejected ideas in a parking-lot or rejected-candidate section so they can be recombined later if needed.
+- In algorithm-first work, `idea` should usually produce direction families, not a large within-family variant swarm.
+- Treat within-family micro-variants as `optimize` brief work unless the mechanism family itself is still unresolved.
 - Every serious candidate must answer `why now?` or `what changed?`, not just `what is the mechanism?`
 - Every selected idea must survive a two-sentence pitch and strongest-objection check before promotion.
 - Do not promote a direction unless you can explain:
   - what limitation it targets
   - why prior methods do not already solve it
   - what evidence would later be needed to defend the claim
+- When the likely next route is a paper-facing main experiment plus analysis package, do not stop at prose-only idea notes; seed the likely `research_questions`, `experimental_designs`, and per-section evidence needs in the outline candidate.
+- If the likely route already has a clear paper-facing structure, seed the future paper line early:
+  - identify the likely main-text sections
+  - identify which sections will need supplementary evidence rather than only the main run
+  - identify the concrete evidence items that must later be maintained in the paper line's outline folder or compiled outline contract
 - If the idea is not novel but still worth doing, state that honestly as:
   - replication value
   - transfer-to-new-setting value
@@ -182,6 +208,51 @@ In practice:
 
 Do not skip the `scout` pass just because the quest is already in the `idea` stage.
 
+## Direction-shaping protocol
+
+Use `references/idea-thinking-flow.md` when the main need is better reasoning hygiene.
+Use `references/idea-generation-playbook.md` when the main need is to create a new idea slate and select one clear next research object.
+
+Default creation flow for a fresh idea pass:
+
+1. frame one concrete limitation
+2. separate symptom / mechanism hypothesis / consequence
+3. keep one main hypothesis plus `2-3` competing hypotheses
+4. name the primary lever bucket
+5. generate a bounded candidate slate from that framing
+6. record selected / deferred / rejected outcomes explicitly
+
+Set the frontier width with a validation-cost estimate before widening:
+
+- `fast-check`: the first objective validation loop is likely under about `20` minutes
+- `slow-check`: the first objective validation loop is likely over about `20` minutes or otherwise expensive in compute, queue time, or human delay
+
+For `fast-check` idea work:
+
+- allow a slightly wider serious slate when the candidates are meaningfully different
+- prefer candidates with cheap, orthogonal falsification paths
+- keep more alternatives alive into `optimize` because validation is cheaper than overthinking
+
+For `slow-check` idea work:
+
+- keep the serious slate tighter, usually `1-3`
+- demand a clearer bottleneck story and stronger evidence before adding another family
+- prefer the route with the best expected evidence-per-run, not the route with the most speculative upside
+- do not hand off a broad speculative slate just because it sounds interesting
+
+Do not start by shopping for modules to add.
+Do not let one attractive mechanism become the de facto framing before the limitation is pinned down.
+Do not let direction-family ideation collapse into within-family variant generation too early.
+
+In normal idea work, stop at the direction-family level:
+
+- select which mechanism families deserve serious consideration
+- identify the strongest one to carry forward
+- hand off within-family brief shaping to `optimize` when the quest is algorithm-first
+
+If the task still requires choosing among mechanism families, stay in `idea`.
+If the family is already chosen and the next need is branchless method-brief shaping, hand off to `optimize`.
+
 ## Truth sources
 
 Use:
@@ -1118,6 +1189,14 @@ When writing paper memory cards, include enough metadata to avoid redundant sear
 
 At the end of ideation, at least one part of the literature survey must be preserved in memory so a later idea pass can retrieve it directly instead of rebuilding the search from scratch.
 
+Every serious idea pass should also leave a durable outcome split:
+
+- one selected idea or selected direction family
+- any deferred but still plausible alternatives
+- any rejected alternatives with a one-line rejection reason
+
+Do not leave the rejected and deferred reasoning only in chat.
+
 Promote to global memory only when the lesson is reusable outside this quest.
 
 ## Artifact rules