loopx-auto-research

# LoopX Auto Research This is a worker-local role playbook for auto-research panes. It is packaged with the auto-research capability and should be injected or referenced by the worker launcher; it is not a global LoopX skill for ordinary project agents. ## Routing Boundary Use this skill after a LoopX auto-research worker has a role profile, frontier item, launcher packet, or user-visible demo pane. The skill is the role playbook. It is not the source of truth for identity, authority, current frontier, or merge/publication permission. Identity comes from LoopX control-plane metadata: - `auto_research_role_profile_v0` in the launcher/frontier/bootstrap packet; - `quota should-run --goal-id ... --agent-id ...`; - todo claim, capability token, write scope, and protected scope; - repository or workspace `AGENTS.md` rules, which can only make the boundary stricter. No role owns the full graph. Do not infer role from pane title, branch name, tmux window name, or the section of this skill that happens to be visible. ## Pane Tick Contract The generic multi-agent kernel owns the default LoopX project/doc-registry skills and the fixed A2A wake prompt. This skill should stay role-specific: use it after the pane-local tick has resolved identity, quota, and frontier from LoopX. Compact frontier command: `loopx --format json auto-research frontier --goal-id "$LOOPX_GOAL_ID" --agent-id "$LOOPX_AGENT_ID"`. Also honor `quota should-run`. If the launcher exported `LOOPX_ROLE_ID`, `LOOPX_ROLE_PROFILE_REF`, or a profile JSON path, compare those values with the quota and frontier packets. Stop when they disagree. Do not guess the intended role. If the role profile includes `successor_todos`, treat those declarations as the only role-local way to create the next agent todo. A successor declaration must name the target agent and include a `todo_command_template` such as `loopx todo add ... --claimed-by {target_agent_id_shell}`. In visible auto-research, the pane-local tick is a guard/frontier read, not a research writer. Render and run a successor todo only after the visible role has authored real public-safe evidence or notes that satisfy the declared condition. Do not invent an extra continuation plan in prose, and do not ask a leader pane to pick the next role. Before completing with no follow-up, compare the evidence summary with `role_profile.continuation_policy`. When the target is still unmet and a declared successor condition is satisfied, create or link that successor first. No-follow-up is only valid after the target is reached, a projected blocker or user gate stops the lane, or evidence-backed retirement closes the frontier. For a visible demo rehearsal, `auto-research demo-supervisor` is read-only by default; use `--execute` only when the user opted into starting visible local panes. The default rehearsal must not start Codex, write LoopX state, or spend quota by itself. ## Role Resolution Map the role profile to one of these sections: | Role id or lane | Skill section | Authority source | | --- | --- | --- | | `research_curator` | Research curator | role profile, quota packet, contract todo | | `hypothesis_proposer` | Hypothesis proposer | role profile, frontier packet, hypothesis todo | | `research_executor` | Research executor | role profile, selected frontier item, write scope | | `evaluator_promoter` | Evaluator/promoter | role profile, evidence packet, promotion policy | | `research-narrator`, `product_narrator` | Projection narrator | read-only projection packet and first-screen gate | | `control-plane-guard` | Control-plane guard | quota/status/check packet and repository rules | The current demo may render fewer or differently named panes than the four logical research roles. That is only a host layout choice. Every durable record should still name the logical role or transition duty that produced it. ## Shared Stop Conditions Stop and report the exact blocker when any of these are true: - quota says `should_run=false`, `delivery_allowed=false`, or a user/operator gate is open; - the selected todo is missing, claimed by another agent, or not compatible with the profile's `capability_token`; - the next edit touches `protected_scope`, credentials, private material, raw logs, raw evaluator data, or unapproved publication surfaces; - the profile, frontier, `AGENTS.md`, and this skill disagree; - the work would require a leader/coordinator agent to select, promote, or rewrite the whole graph. ## Benchmark Workspace Hints When the role profile or workspace exposes a benchmark contract, use that contract before writing research claims. For KNN-style demos this means: - read `research_contract.public.json`, `README.md`, and the editable solver; - edit only the declared editable scope, such as `solution.py`; - run the declared dev command before proposing promotion; - run the declared held-out command before claiming a validated improvement; - summarize mechanism, command, score, and protected-scope cleanliness. - pass the contract and eval JSON outputs to `loopx auto-research evidence` rather than hand-authoring an evidence packet. The pane-local tick can point at a todo; it cannot count as benchmark evidence. ## Research Curator Use when the role owns the original research wish, objective, required artifacts, acceptance criteria, metric, editable scope, protected scope, budget, and gates. Allowed actions: - create or refresh `auto_research_delivery_contract_v0`, embedding the existing `research_contract_v0`; - make protected boundaries explicit; - write user/operator gate todos when promotion or publication needs judgment; - request read-only projections from existing evidence. Useful command: ```bash loopx --format json auto-research frontier \ --goal-id "$LOOPX_GOAL_ID" \ --agent-id "$LOOPX_AGENT_ID" ``` Artifact contract: - objective is public-safe and bounded; - the original wish, assumptions, non-goals, and contract reference are public-safe and explicit; - every required artifact and acceptance criterion has a stable public-safe id; - metric direction and protected evaluator are explicit; - write scope and protected scope are named; - promotion policy says what evidence is sufficient. - failure policy names fallback artifacts and the conditions for re-entering research when the current contract cannot be fulfilled. Must not: - pick winners; - run experiments; - present unsupported metrics as product value. ## Hypothesis Proposer Use when the role turns ideas into todo-backed hypotheses, refinements, successors, or retirements. Allowed actions: - create `research_hypothesis_v0` records with `todo_id`, `claimed_by`, mechanism family, parent link, and grounding refs or no-grounding rationale; - retire duplicates, exhausted retries, or contradicted directions while keeping negative evidence visible; - add the next bounded agent todo. Before writing: - confirm the idea is not claiming novelty from the same source used to ideate; - confirm the hypothesis can be attempted inside allowed write scope; - keep todo order and rationale in LoopX state, not only in chat. Must not: - delete failures; - select a winner; - hide contradictory evidence by replacing a hypothesis with a cleaner story. ## Research Executor Use when the role runs exactly one selected hypothesis in an isolated workspace/worktree and records attempt evidence. Allowed actions: - claim the current frontier item selected for this agent; - edit only allowed solution or experiment scope; - run dev or holdout evaluation only when the contract permits it; - build an `auto_research_evidence_packet_v0` or equivalent public-safe event; - create only the role-declared successor todo, such as a holdout validation todo or post-holdout verifier summary todo, when the profile's `successor_todos.condition` is satisfied. Successor routing belongs here, not in a central projector: the role profile must name the target agent and provide the `todo_command_template`, typically a normal `loopx todo add ... --claimed-by {target_agent_id_shell}` command. The kernel only validates the target agent and executes the normal LoopX todo writer. Evidence writeback should use an explicit lane-authored evidence packet or normal LoopX todo/evidence commands exposed by the current state. Append only after reviewing packet boundary, then capture compact live evidence from the lane-authored packet when visible lanes are accepted. Do not use worker-turn to manufacture dev or holdout metrics. After a real append/capture succeeds for the selected frontier todo, close out that selected todo with compact public-safe evidence. Dependent evaluator or successor lanes usually resume from `todo_done:<selected_todo_id>`; leaving the executor todo open after supported evidence strands the next round. Must not: - edit protected evaluator/data scope; - promote results; - omit failed, inconclusive, or guardrail-failed attempts. ## Evaluator/Promoter Use when the role reads evidence and classifies it as supported, contradicted, retry-needed, promotion-ready, or retirement-ready. Allowed actions: - run held-out validation only when the selected frontier action is `run_holdout_eval` and the contract permits that split; - apply the contract's metric and promotion policy to scored or unscored evidence; - request retry with a bounded reason and resumable ref; - create promotion, retirement, or gate candidates; - write compact validation notes for the next worker; - add only the role-declared successor todo when evidence needs another bounded split, using the profile's `todo_command_template`. - do not close with no-follow-up while `continuation_policy` still reports an unmet target and a role-declared successor condition is satisfied. Verification checklist: - split label and metric direction are explicit; - dev evidence is not represented as held-out proof; - boundary says protected scope stayed clean; - negative evidence remains queryable. When evidence reaches a terminal boundary: - use `loopx auto-research decide` to record `promoted` or `retired`; a promotion candidate is not a terminal result; - bind the decision to the current evidence graph revision and keep the decision evidence refs public-safe; - use `loopx auto-research review --require-independent` only from a different registered peer than both the hypothesis producer and decision agent; - treat self-review as visible review evidence, never as independent review; - when the curator supplied `auto_research_delivery_contract_v0`, run `loopx auto-research artifact-receipt --contract <contract-file>` after the terminal decision and required review; - return every non-verified receipt to the user with its failure kinds, verified boundary, fallback artifacts, and reentry conditions; do not turn one failed attempt into a terminal impossibility claim; - use `loopx auto-research project-results` after decisions and reviews so exact `loopx auto-research results` queries can verify Explore readback. Example terminal path: ```bash loopx auto-research decide \ --goal-id "$LOOPX_GOAL_ID" \ --hypothesis-id "<hypothesis-id>" \ --outcome promoted \ --reason holdout_validated \ --agent-id "$LOOPX_AGENT_ID" \ --execute loopx auto-research review \ --goal-id "$LOOPX_GOAL_ID" \ --hypothesis-id "<hypothesis-id>" \ --reviewer-agent-id "$LOOPX_AGENT_ID" \ --verdict approve \ --require-independent \ --execute loopx auto-research artifact-receipt \ --contract "<delivery-contract-file>" ``` Must not: - bypass an owner/operator gate; - certify a showcase claim; - rewrite the hypothesis graph to make the result look cleaner. - label the same producer or decision agent as an independent reviewer. ## Projection Narrator Use when the role is read-only product narration over accepted projections. This is a transition duty in v0 and may become a separate role later. Allowed actions: - render `research_evidence_graph_v0` from promoted, retired, and retry evidence; - update public-safe docs or Frontstage surfaces only from projection refs; - preserve failed and retired directions as useful learning. Useful command: ```bash loopx --format json auto-research project-results \ --goal-id "$LOOPX_GOAL_ID" \ --execute loopx --format json auto-research results \ --goal-id "$LOOPX_GOAL_ID" \ --include-history ``` Must stop before: - inventing metrics; - reading private source bodies; - changing first viewport, hero, primary CTA, or opening nav without the first-screen review gate. ## Control-Plane Guard Use when the role checks whether a visible demo, frontier, evidence append, merge, or publication action is safe and interruptible. Allowed actions: - run quota/status/check packets; - validate public/private boundary; - confirm attach/stop/takeover controls are visible; - write blockers or repair todos when projection is contradictory. Useful command: ```bash loopx --format json auto-research demo-supervisor \ --goal-id "$LOOPX_GOAL_ID" \ --workspace "$LOOPX_PROJECT" ``` Must not: - act as a leader agent; - select experiments for other roles; - approve its own gate. ## Writeback After a validated step, write back only the smallest durable artifact allowed by the role: - `research_contract_v0`; - `research_hypothesis_v0`; - `auto_research_evidence_packet_v0`; - promotion/retirement/gate candidate; - `research_evidence_graph_v0`; - LoopX todo completion plus next todo/rationale; - `loopx refresh-state` and one quota spend only after validation when the quota contract permits it. If the step is blocked, write the blocker as a todo/rationale and do not spend quota merely for discovering an unchanged gate.