v5.8.0 to v5.8.0

49 added, 84 removed. Audit A to A.

---

name: research-direction-selector

description: Choose and audit theoretical or empirical research steps with scoped evidence, budgets and authorized execution. Supports proof obligations, experiment comparisons and native research records; domain-specific solvers and scientific evidence are still required.

metadata:

version: v5.8.0

engine: rds-cli-v5.8

---

# Research Direction Selector

- Agent pseudocode; not an executable language or a new kernel contract.

- ```text

- DISCOVER: name + description

- ON applicable research request:

- LOAD this SKILL.md

- skill_dir := directory containing this file

- project_root := user's research project

- CLI := python -B "<skill_dir>/scripts/rds_cli.py" --root "<project_root>"

- RESOLVE bundled scripts/references/examples relative to skill_dir

- RESOLVE user inputs explicitly; NEVER create .rds in installation/plugin cache

- LOAD supporting resources only when the current decision needs them

+ Pick the goal type, run its one command, and drive the work from the kernel's own next step. All commands run from the RDS checkout as `python -B scripts/rds_cli.py …`; `--root <dir>` selects the project directory. This file is the entry point, not the rulebook: acceptance philosophy lives in the linked docs and is loaded only when the current decision needs it.

- INPUT := user request + current project evidence + authorized resources

- INFER goal, acceptance, evidence, budget FROM INPUT; NEVER invent them

- IF evaluation is missing: define a minimal protocol BEFORE material commitment

- ASK only for an uninferable material goal, method, or resource choice

- KEEP missing evidence = UNKNOWN; preserve existing authorization and gates

- BRANCH via the route table below

- IF the needed capability is outside the quick routes:

- READ docs/command-map.md; SELECT the supported entry and its prerequisites

- CHECK CLI <command path> --help (or the documented helper's --help)

- USE only the capability needed for this task; DO NOT run the whole catalog

+ ## Decision tree

- IF substantive research direction choice:

- SUPPLY serious alternatives/explanations + sources + distinguishing observation

- IF project has a saved dependency map: ADD --saved-dependencies TO advise

- READ the returned search.selection_review: basis, flags, relevant next_move

- IF brief output omits decision-critical detail: READ its saved record

- CHECK single direction, missing/overlapping predictions, unknown premises,

- truncated search, and submitted goal/dependency links

- REPAIR consequential gaps OR state the comparison still unresolved

- EXPLAIN why this next step follows from the evidence BEFORE --choose

- RECOMMEND one default + at most one serious alternative

- INCLUDE deciding observation, fair comparison, stop/revision condition

- DO NOT equate a preselected candidate + recording/budget checks with comparison

- DO NOT use a later call to endorse an already executed route

- IF fixed user-requested task OR single proof obligation:

- KEEP the requested scope; DO NOT invent rival experiments

- NOTE: program checks only supplied inputs; omitted dependencies remain unassessed

- review/recording grants no new resources or execution authority

+ | Goal | Run | Detail on demand |

+ | --- | --- | --- |

+ | Start from a plain-language request (first time) | Follow the [plain-language quick start](docs/quickstart.md) — copyable prompts, a generated first project, and `[RDS-REJECT]` recovery | [Project runner example](examples/project-runner/README.md) |

+ | Start a locked experiment campaign | `project init --contract <contract.json>` with a frozen `advisor_policy` for goal-driven selection | [Program-owned Advisor](docs/program-owned-advisor.md) |

+ | Advance a running campaign | `project next` to inspect; `project advance` executes one program-selected step in a policy-bound project | [Program-owned Advisor](docs/program-owned-advisor.md) |

+ | Decide a research direction | `advise --brief` reads the policy, current graph and complete run inventory; legacy context-based advice remains available for older projects | [Program-owned Advisor](docs/program-owned-advisor.md) and [research discipline](references/research-discipline.md) |

+ | Audit evidence into the ledger | `artifacts import --manifest <manifest.json>` | [Agent entry](docs/agent-entry.md) |

+ | Check a mathematical claim | `formal verify --spec <spec.json> --tactics rational` | [Formal framework](references/formal_framework.md) |

+ | Reuse or register a local tool | `rsi extract --source <file> --entry <function> --name <id>`, then `rsi validate --name <id> --cases <cases.json>` → `rsi register --name <id>` | [Native research](docs/native-research.md) |

+ | Wrap one frozen tool job | `exec --name <id> --timeout 30 -- <command…>` — receipt-bound execution without contract JSON | [Agent entry](docs/agent-entry.md#wrap-a-command) |

+ | Record a decision or rejection | `checkpoint save --id <id> --decision <decision.json>` (kind auto-selects from the root); `reject --reason '<text>' --evidence <file>` reuses the current choice | [Local decision workflow](docs/lightweight-workflow.md) |

- AFTER campaign-changing command:

- READ project status --brief OR project next

- REBIND printed scripts/rds_cli.py commands TO CLI above; preserve arguments

- FOLLOW ledger-derived next_move within existing authorization

- REPORT actual backend + assurance; unresolved results stay UNKNOWN

- KEEP runner, Lean, RSI optional; Advisor/rule lint remain heuristic

- NEVER infer scientific acceptance FROM exit 0, self-signed success, or call count

- ```

+ **Driving pattern:** after any campaign-changing command, run `project status --brief` or `project next` and execute the printed `next_move` — register, execute, recover, compare, record — instead of memorizing a command sequence. The kernel derives the step from recorded ledger state only.

- ## Routes

+ For a new goal-driven research campaign, freeze the real objective, permitted routes, output readers and budget in `advisor_policy`. Let the program receive every submitted run's results and derive Advisor input from the current graph. Supply inspectable proposals; do not hand-select favorable evidence, replace the program's context, omit returned warnings, or bypass its selected route through quick execution. Completion returns the original receipt plus an automatic Advisor update; a failed update calls for collection recovery, not another training run. The [CPU example](examples/owned-advisor/prepare.py) generates a complete small contract. Existing legacy ledgers retain their original boundaries; configuration and tool checks do not create OS-wide enforcement or independent scientific proof.

- All commands below use `CLI` above. Links load detail on demand.

+ **Non-negotiables** (details in the linked docs): infer goal, acceptance conditions, evidence and budget from the request and project — never invent a metric, threshold or goal, and missing evaluation calls for a minimal protocol before material commitments. Missing evidence stays `UNKNOWN`; exit code 0 and self-signed success are execution records, not science. Recommend one default and at most one serious alternative, with a deciding observation, fair comparison and a stop/revision condition. Ask only for an uninferable material goal, method or resource choice.

- | Trigger | Command | Detail |

- | --- | --- | --- |

- | First plain-language request | Follow [quick start](docs/quickstart.md): copyable prompts, first project, `[RDS-REJECT]` recovery | [Project runner](examples/project-runner/README.md) |

- | Start locked campaign | `project init --contract <contract.json>` | [Contract template](docs/project-contract.md), [project tools](docs/development-loop.md) |

- | Advance campaign | `project next` | [Development loop](docs/development-loop.md) |

- | Choose research direction | `advise --context <context.json> --graph <graph.json> --brief`; then `--choose <candidate-id> --record <checkpoint-id>` | [Choice review](docs/agent-entry.md#review-the-research-choice), [research discipline](references/research-discipline.md) |

- | Audit evidence | `artifacts import --manifest <manifest.json>` | [Agent entry](docs/agent-entry.md) |

- | Check mathematical claim | `formal verify --spec <spec.json>`; select a supported tactic when needed | [Formal framework](references/formal_framework.md) |

- | Reuse/register local tool | `rsi extract --source <file> --entry <function> --name <id>`; `rsi validate --name <id> --cases <cases.json>`; `rsi register --name <id>` | [Native research](docs/native-research.md) |

- | Wrap frozen job | `exec --name <id> --timeout 30 -- <command...>` | [Command wrapper](docs/agent-entry.md#wrap-a-command) |

- | Record decision/rejection | `checkpoint save --id <id> --decision <decision.json>` (kind from root); or `reject --reason '<text>' --evidence <file>` (current choice) | [Local decision workflow](docs/lightweight-workflow.md) |

+ ## Minimal project contract template

- ## Visible invocation status

+ Validated by `project init`: relative paths, hex SHA-256 of each file, all five binding roles required, `min_useful_delta` as an exact rational string. Optional fields (`objective_sha256`, `execution_policy`, `stop_policy`, `maintenance_allowance`) are documented in [stop policy](docs/stop-policy.md) and [native research](docs/native-research.md). Generate a real, immediately valid contract with `python -B examples/project-runner/prepare.py --root <new-empty-dir>`.

- ```text

- ON actual Skill load, before this task's first CLI call:

- SHOW "RDS | loaded, not invoked"

- ON meaningful CLI event:

- dispatch -> "RDS | {command}: running"

- host/tool error -> "RDS | {command}: error"

- known nonzero exit -> "RDS | {command}: nonzero exit"

- known zero exit -> "RDS | {command}: returned"

- unknown result -> "RDS | {command}: result unknown"

- SHOW one short line FROM observed events; OMIT unchanged/host-displayed duplicates

- NEVER add calls for display; KEEP existing receipts/record locators, no required hash

- session start != Skill loaded != CLI invoked

- returned != sufficient comparison != proof != scientific acceptance

+ ```json

+ {

+ "schema": 1,

+ "description": "CPU demonstration, not scientific confirmation",

+ "bindings": [

+ {"role": "code", "path": "experiment.py", "sha256": "<sha256>"},

+ {"role": "config", "path": "config.json", "sha256": "<sha256>"},

+ {"role": "data", "path": "data.csv", "sha256": "<sha256>"},

+ {"role": "evaluator", "path": "evaluate.py", "sha256": "<sha256>"},

+ {"role": "protocol", "path": "protocol.json", "sha256": "<sha256>"}

+ ],

+ "allowed_commands": [

+ ["python", "-B", "experiment.py", "--arm", "control", "--output", "outputs/control.json"],

+ ["python", "-B", "experiment.py", "--arm", "treatment", "--output", "outputs/treatment.json"]

+ ],

+ "output_roots": ["outputs"],

+ "budget": {"wall_seconds": 20},

+ "primary_metric": {"name": "mse", "direction": "min", "min_useful_delta": "1/100"}

+ }

```

- ## Conditional resources

+ Then `project init --contract <root>/contract.json`, register each arm with `project create --manifest <root>/<arm>.json`, and follow `project next`.

- - All public CLI commands, Advisor modes and supported helper entries: [command map](docs/command-map.md)

- - Goal links, method limits, theory/experiment acceptance: [agent entry](docs/agent-entry.md)

- - Evidence classes, controls, precommitted comparison: [research discipline](references/research-discipline.md)

- - Capacity and parallel batches: [resource planning](docs/resource-planning.md)

- - Stalled formulation or theory-tool lookup: [theory reformulation](docs/theory-reformulation.md)

+ ## Load more only when the decision needs it

+ - Goal-linked dependencies, method limits, theory/experiment acceptance: [agent entry](docs/agent-entry.md)

+ - Evidence classes, output contract, controls, precommitted comparison: [research discipline](references/research-discipline.md)

+ - Capacity, idle resources, parallel batches: [resource-aware planning](docs/resource-planning.md)

+ - Stalled formulation, plateau, theory-tool lookup: [theory reformulation](docs/theory-reformulation.md)

- Anti-loop checkpoint review: [local decision workflow](docs/lightweight-workflow.md)

- - Formal scope, UNKNOWN, `CERTIFICATE_CHECKED`, `LEAN_KERNEL_CHECKED`: [formal framework](references/formal_framework.md)

- - Native objectives, assets, reusable tools: [native research](docs/native-research.md)

- - Optional scoped history: [Obelisk](references/obelisk.md)

- - Explicitly opted-in preferences only: [optional preferences](references/optional-preferences.md)

+ - Formal scope, `UNKNOWN` semantics, Lean backends: [formal framework](references/formal_framework.md)

+ - Native objectives, asset retention, RSI ledger: [native research](docs/native-research.md)

+ - Optional history enhancement: [Obelisk](references/obelisk.md); preferences apply only with explicit opt-in: [optional preferences](references/optional-preferences.md)

+ Runner, Lean and RSI remain optional capabilities with their gates intact. Advisor and rule lint are heuristic; report the actual backend and assurance (`CERTIFICATE_CHECKED` for the rational checker, `LEAN_KERNEL_CHECKED` for native Lean) and keep unresolved results unknown.