loopx 0.4.8__py3-none-any.whl

loopx/capabilities/auto_research/worker_skill/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: loopx-auto-research
+description: Use when a LoopX worker is operating an auto-research lane, demo pane, frontier item, evidence packet, promotion/retirement decision, or visible tmux/Codex auto-research rehearsal. Identity must come from the LoopX role profile and quota/frontier packet; this skill only provides role-specific execution checklists, artifact contracts, and stop conditions.
+---
+
+# 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 objective, metric, editable scope, protected scope,
+budget, and gates.
+
+Allowed actions:
+
+- create or refresh `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;
+- metric direction and protected evaluator are explicit;
+- write scope and protected scope are named;
+- promotion policy says what evidence is sufficient.
+
+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;
+- 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
+```
+
+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.

loopx/capabilities/benchmark_toolkit/__init__.py

@@ -0,0 +1,19 @@
+"""Built-in benchmark experiment toolkit."""
+
+from .integrity import (
+    BENCHMARK_INTEGRITY_POLICY_SCHEMA_VERSION,
+    BENCHMARK_INTEGRITY_QUALIFICATION_SCHEMA_VERSION,
+    BENCHMARK_RUNTIME_INTEGRITY_ATTESTATION_SCHEMA_VERSION,
+    INTEGRITY_EVIDENCE_CATEGORIES,
+    REQUIRED_RUNTIME_ATTESTATIONS,
+    build_benchmark_integrity_qualification,
+)
+
+__all__ = [
+    "BENCHMARK_INTEGRITY_POLICY_SCHEMA_VERSION",
+    "BENCHMARK_INTEGRITY_QUALIFICATION_SCHEMA_VERSION",
+    "BENCHMARK_RUNTIME_INTEGRITY_ATTESTATION_SCHEMA_VERSION",
+    "INTEGRITY_EVIDENCE_CATEGORIES",
+    "REQUIRED_RUNTIME_ATTESTATIONS",
+    "build_benchmark_integrity_qualification",
+]