opencode-autoresearch 3.1.0-beta.2

package/skills/autoresearch/references/results-logging.md

@@ -0,0 +1,29 @@
+# Results Logging
+
+`research-results.tsv` is the primary append-only results log per run.
+
+The runtime maintains `autoresearch-results.tsv` as the canonical iteration log.
+
+## Required Columns
+
+The TSV header is:
+
+`timestamp iteration decision metric_value verify_status guard_status hypothesis change_summary labels note`
+
+## Logging Rules
+
+1. Record exactly one row per completed iteration.
+2. Treat each row as the orchestrator-owned result for that iteration, even when several subagents contributed evidence.
+3. Use `keep`, `discard`, or `needs_human` as the decision.
+4. Store the observed metric value as text; leave it blank only when no metric was produced.
+5. Keep `change_summary` short and specific to the experiment that just finished.
+6. Use `labels` for compact tags such as `test`, `perf`, `retry`, `docs`, or `security`.
+7. Put blocker details, rollback notes, or subagent evidence worth preserving in `note`.
+
+## Interpretation
+
+- `verify_status=pass` means the primary metric command completed successfully.
+- `guard_status=pass` means the regression guard also passed.
+- `decision=keep` means the change survived verification and stays in the working tree.
+- `decision=discard` means the change should be rolled back before the next experiment.
+- `decision=needs_human` means the run hit ambiguity or risk that should stop autonomous progress.

package/skills/autoresearch/references/runtime-hard-invariants.md

@@ -0,0 +1,13 @@
+# Runtime Hard Invariants
+
+Use this checklist when a run starts, resumes, or feels out of sync.
+
+## Re-anchor
+
+- Re-state the goal, scope, metric, and verify command before making the next change.
+- Re-check the latest state and results artifacts so you are not acting on stale context.
+- Re-anchor the standing subagent pool with the latest findings, objections, and open questions before the next iteration.
+- Make one focused change at a time and record it before moving on.
+- Re-run the verify command after a keep-worthy change and before the next iteration.
+- Honor any keep/stop label gates, duration limits, and human-blocker flags.
+- If the current state no longer matches reality, stop and surface the mismatch instead of guessing.

package/skills/autoresearch/references/scenario-workflow.md

@@ -0,0 +1,15 @@
+# Scenario Workflow
+
+Use this when the user wants edge cases, use cases, or stress scenarios derived from a seed idea.
+
+## Goal
+
+Expand a seed situation into a practical set of testable scenarios.
+
+## Steps
+
+1. Read the seed scenario and target subsystem.
+2. Expand along scale, failure, misuse, timing, dependency, and data-shape axes.
+3. Deduplicate similar cases.
+4. Rank the scenarios by risk or value.
+5. Feed the selected scenarios into tests, debug, or fix work if requested.

package/skills/autoresearch/references/security-workflow.md

@@ -0,0 +1,15 @@
+# Security Workflow
+
+Use this when the user wants a structured security pass.
+
+## Goal
+
+Find concrete security issues with enough evidence to prioritize and fix them.
+
+## Steps
+
+1. Define the in-scope attack surface.
+2. Review it through common categories such as input handling, authz/authn, secrets, injection, unsafe deserialization, file access, and dependency exposure.
+3. Prefer reproducible evidence over broad claims.
+4. Rank findings by severity and exploitability.
+5. If the user wants remediation, hand the highest-value issue into the fix workflow.

package/skills/autoresearch/references/ship-workflow.md

@@ -0,0 +1,15 @@
+# Ship Workflow
+
+Use this when the user wants release-readiness or structured closeout.
+
+## Goal
+
+Move from "changes exist" to "this is ready to ship" with a bounded checklist.
+
+## Steps
+
+1. Confirm the target artifact or release unit.
+2. Verify tests and guards.
+3. Review open risks and missing docs.
+4. Summarize user-visible changes.
+5. Produce the final checklist: verification, rollback note, release note, and follow-up monitoring items.

package/skills/autoresearch/references/state-management.md

@@ -0,0 +1,39 @@
+# State Management
+
+`autoresearch-state.json` is the run checkpoint.
+
+## Core Fields
+
+- `run_id`: stable identifier for the current run
+- `status`: `initialized`, `running`, `stopping`, `stopped`, or `completed`
+- `mode`: `foreground` or `background`
+- `goal`: human-readable objective
+- `metric`: name, direction, baseline, latest, and best values
+- `subagent_pool`: standing-pool plan, role activation, and re-anchor guidance
+- `continuation_policy`: launch approval boundary and post-launch stop rules
+- `stats`: total iterations, keep/discard counters, best iteration, and discard streak
+- `flags`: stop request, needs-human marker, and background activity
+- `last_iteration`: summary of the latest completed iteration
+
+## Rules
+
+1. Baseline exactly once when the run is initialized.
+2. Update `updated_at` on every state mutation.
+3. Keep `metric.latest` aligned with the most recent finished iteration.
+4. Only update `metric.best` on strict improvement.
+5. Only the orchestrator records iterations or mutates the authoritative run state.
+6. Set `flags.needs_human=true` when autonomous progress should stop for user input.
+7. For detached runs, `flags.background_active` reflects whether a background owner is currently expected to continue the loop.
+8. If the pool metadata is missing from an older state file, reconstruct it from the goal, scope, and mode before resuming.
+
+## Resume Semantics
+
+- `python scripts/autoresearch_runtime_ctl.py resume` clears `stop_requested` and marks the background run active again.
+- Resume does not create a new run; it continues the existing state snapshot.
+- Resume should re-anchor the standing pool with the latest metric, last iteration, and active role guidance before the next handoff.
+- Completed runs are not resumable; return to the previous state by starting a new run.
+- If the run is not a background run, resume should fail fast.
+
+## Completion Semantics
+
+- `python scripts/autoresearch_runtime_ctl.py complete` moves a background run to `completed`, clears `background_active`, and ends the detached session lifecycle.

package/skills/autoresearch/references/structured-output-spec.md

@@ -0,0 +1,34 @@
+# Structured Output Spec
+
+Interactive runs should use three output phases.
+
+## Setup Summary
+
+Before launch, summarize:
+
+- goal
+- scope
+- metric and direction
+- verify command
+- guard command, if any
+- run mode
+- stop condition or iteration cap
+
+## Iteration Update
+
+After each completed iteration, report:
+
+- iteration number
+- decision (`keep`, `discard`, or `needs_human`)
+- short explanation
+- current best-known metric, if available
+
+## Completion Summary
+
+When the run ends, report:
+
+- why it ended
+- total iterations
+- kept vs discarded counts
+- best recorded metric, if available
+- next action, if a blocker remains

package/skills/autoresearch/references/subagent-orchestration.md

@@ -0,0 +1,42 @@
+# Subagent Orchestration
+
+Use this reference when a run should be subagent-first.
+
+## Orchestration Model
+
+- The main agent is the orchestrator. It owns the goal, scope, metric, direction, verify command, guard, and final keep/discard decision.
+- Subagents form a standing pool for parallel context gathering, alternative synthesis, verification, and critique.
+- The main agent hands bounded questions to the pool, waits for findings, and folds those findings into the next iteration before changing code again.
+- Subagents surface evidence, objections, risks, and candidate next steps. They do not independently advance the run state.
+- Approval belongs before launch. Once the run is launched, keep the same pool moving until the user stops the run, the configured stop condition is met, or a real `needs_human` blocker appears.
+
+## Launch Decision
+
+- Decide whether the standing pool should already be active during setup or only after launch.
+- Default to an active pool for multi-step, uncertain, or unattended work.
+- Fall back to orchestrator-only serial execution when the task is tiny or the environment cannot support clean parallel work.
+
+## Pool Rules
+
+- Keep the pool alive across iterations unless context drift forces a reset.
+- Reuse roles where possible so context compounds instead of resetting.
+- Prefer a small pool with distinct jobs over one-off ad hoc spawning.
+- Re-anchor the pool after every keep/discard decision with the latest goal, state, and results.
+- Feed findings back into the loop before the next code change.
+
+## State Ownership
+
+- Only the orchestrator records iterations, mutates `autoresearch-state.json`, and decides whether the latest step is `keep`, `discard`, or `needs_human`.
+- Subagents may disagree, critique, or verify, but their output is supporting evidence.
+- If several subagents contribute to one change, roll that evidence into one orchestrator-owned iteration result.
+
+## Fallback Rules
+
+- If one subagent times out, conflicts with another role, or stops adding value, replace or drop that role without stopping the whole run.
+- If the whole pool becomes unhelpful, continue serially under the orchestrator instead of rerunning setup.
+- Only surface `needs_human` when the orchestrator cannot continue safely after folding in the latest pool findings.
+
+## Local Scope
+
+- This bundle stays compact and narrower than the reference repo.
+- Prefer the references in this repository over broader upstream orchestration patterns unless the user explicitly asks for them.