@researai/deepscientist 1.5.14 → 1.5.15

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

@@ -28,6 +28,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 +71,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 +95,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 +132,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 +254,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 +422,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

@@ -13,6 +13,7 @@ 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.
 
 ## Non-negotiable rules
@@ -463,6 +464,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

@@ -84,12 +84,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 +106,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 +124,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 +258,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 +343,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

@@ -39,7 +39,9 @@ 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.
 
 ## Stage purpose
 
@@ -64,6 +66,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 +95,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 +435,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/finalize/SKILL.md

@@ -11,10 +11,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 +57,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 +104,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 +128,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 +260,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

@@ -7,6 +7,10 @@ description: Use when a quest needs concrete hypotheses, limitation analysis, ca
 
 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 +43,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 +119,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 +151,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 +207,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 +1188,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

package/src/skills/idea/references/idea-generation-playbook.md

@@ -0,0 +1,100 @@
+# Idea Generation Playbook
+
+Use this reference when the `idea` stage needs a concrete creation flow for producing a new idea slate.
+
+The goal is not a bag of clever mechanisms.
+The goal is one clear next research object plus a durable record of what was deferred or rejected.
+
+## 1. Start from one limitation card
+
+Write one limitation card before generating ideas:
+
+- observed symptom
+- condition where it appears
+- why it matters for the target metric or claim
+- strongest evidence that this is a real pattern
+
+If the limitation card is weak, do not widen into ideation yet.
+
+## 2. Split the problem into three layers
+
+For the active limitation, separate:
+
+- symptom
+- mechanism hypothesis
+- consequence
+
+Do not skip this split.
+It prevents solution-shopping from becoming the hidden driver.
+
+## 3. Keep competing hypotheses alive
+
+Before selecting mechanisms, record:
+
+- one main hypothesis
+- `2-3` competing hypotheses
+
+If there is only one hypothesis, the idea pass is usually too collapsed.
+
+## 4. Name the lever bucket
+
+Choose the primary lever bucket explicitly:
+
+- data
+- model
+- objective
+- optimization or training dynamics
+- inference
+- evaluation protocol
+- infrastructure
+
+If the lever bucket is unclear, the idea is usually still too fuzzy.
+
+## 5. Generate direction families, not micro-variants
+
+Create a bounded slate of direction families.
+Default target:
+
+- `6-12` raw ideas in one bounded divergent pass
+- collapse to `2-3` serious candidates and at most `5`
+
+Prefer family-level differences over small parameter or implementation variations.
+If several candidates are really the same family with minor tweaks, merge them.
+
+For each serious candidate, record:
+
+- limitation targeted
+- mechanism family
+- why now
+- strongest prior-work overlap
+- expected evidence burden
+- likely falsification path
+
+## 6. Select one and ledger the rest
+
+At the end of the pass, produce three durable buckets:
+
+- selected
+- deferred
+- rejected
+
+For deferred ideas, write why they remain plausible but are not first.
+For rejected ideas, write one-line rejection reasons such as:
+
+- redundant with closer prior work
+- too confounded to test cleanly
+- weak value if positive
+- too broad for current compute or codebase
+- lower priority than the selected route
+
+## 7. Exit criterion
+
+The pass is complete only when the output contains:
+
+- one selected idea or selected direction family
+- one falsifiable claim
+- one minimal experiment concept
+- one abandonment condition
+- deferred and rejected rationale recorded durably
+
+If the result is still a bag of possibilities, stay in `idea`.

package/src/skills/idea/references/outline-seeding-example.md

@@ -0,0 +1,60 @@
+# Outline Seeding Example
+
+Use this reference when the idea stage is strong enough that the next serious step will likely become a paper-facing line.
+
+## Goal
+
+Before analysis begins, seed one lightweight but structured outline candidate so later experiments are not free-floating.
+
+## Minimal seed
+
+```json
+{
+  "title": "Evidence-First Outline Seed",
+  "research_questions": [
+    "RQ1: Does the method outperform the accepted baseline?",
+    "RQ2: Which component is responsible for the gain?",
+    "RQ3: What boundary or failure regime matters most?"
+  ],
+  "experimental_designs": [
+    "Main benchmark comparison",
+    "Component ablation",
+    "Boundary analysis"
+  ],
+  "sections": [
+    {
+      "section_id": "results-main",
+      "title": "Main Results",
+      "paper_role": "main_text",
+      "claims": ["C1"],
+      "required_items": ["run-main-001"]
+    },
+    {
+      "section_id": "analysis-mechanism",
+      "title": "Mechanism Analysis",
+      "paper_role": "main_text",
+      "claims": ["C2"],
+      "required_items": ["AN-ABL-001"]
+    },
+    {
+      "section_id": "analysis-boundary",
+      "title": "Boundary Analysis",
+      "paper_role": "appendix",
+      "claims": ["C3"],
+      "optional_items": ["AN-BND-001"]
+    }
+  ]
+}
+```
+
+## When to seed the outline
+
+- The idea already survived literature and feasibility checks.
+- The likely paper contribution is clear enough to name `1-3` research questions.
+- You can already anticipate the first main experiment and at least one likely follow-up analysis family.
+
+## When not to seed the outline yet
+
+- The task framing is still unstable.
+- The idea frontier is still too wide.
+- You still cannot say what the main claim would be if the route worked.

package/src/skills/intake-audit/SKILL.md

@@ -193,7 +193,7 @@ If the evidence is insufficient for a durable backfill, record that insufficienc
 
 ### 5. Choose the next anchor
 
-After reconciliation, write one durable route decision with `artifact.record(kind='decision', ...)`.
+After reconciliation, write one durable route decision with `artifact.record(payload={'kind': 'decision', ...})`.
 
 Typical next anchors: