Skip to content

Specula v0.3.0

Choose a tag to compare

View all tags
@Qian-Cheng-nju Qian-Cheng-nju released this 26 Jul 17:17
v0.3.0
6d42337
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Specula v0.3.0 makes long, multi-agent runs safer to execute, easier to recover, and much easier to review.

Highlights

  • Pipeline outputs now include a run-level target chooser and a human-readable index for each target. Confirmation and severity reports appear first, run indexes link to them directly, and successful runs print the generated results-index path.
  • --keep-original runs all phases against a private copy of the target checkout, leaves the original unchanged, and writes a Git-format changes.patch that includes ignored and untracked files.
  • A JSON --agent-config can route different phases to different agents, models, and effort levels. OpenCode and Pi join Claude Code, Codex, and Copilot CLI as supported adapters.
  • TLC launches now share a run-wide aggregate memory budget, defaulting to 80% of effective available memory, with an optional aggregate worker limit. Over-budget launches fail before Java starts instead of overcommitting the machine.
  • Provider policy blocks and transient capacity, transport, and 5xx failures now have configurable recovery budgets. When possible, Specula resumes the exact native agent session while preserving worktrees, completed confirmation turns, and per-attempt logs.
  • Confirmation and repair are more robust: downstream handoffs verify their required outputs, invariant repairs preserve still-valid coverage, and stale confirmation worktrees recover through fresh isolated paths.
  • Setup now prompts only for agent CLIs found on PATH, expands ~ in artifact paths, and documents tested agent/model combinations, recommended machine resources, provider-access caveats, and Codex plugin scope.

Upgrade notes

  • Python 3.10 or newer and uv remain required. Java 21 or newer and Maven are required for the bundled TLA+ tooling and CFA build.

  • Install the CLI from a persistent source checkout and rerun setup after updating:

    git clone --branch v0.3.0 --depth 1 https://github.com/specula-org/Specula.git
cd Specula
uv tool install -e .
specula setup

  • Keep the source checkout in place: the editable CLI dispatches to the bundled scripts, skills, and tools.

  • Codex plugin users should choose plugin in specula setup again to update the profile-wide specula-codex@specula installation.

  • Copilot CLI users should upgrade to version 1.0.51 or newer. v0.3 requires --autopilot support, and exact-session resume requires the newer full-UUID --resume behavior.

  • Policy and transient recovery each default to 20 continuations. Use --policy-retries=0 or --transient-resumes=0 to disable them, or set smaller values when a strict time or provider-usage bound is preferred.

  • Concurrent TLC launches may now be rejected by the default aggregate memory budget. Override it with --tlc-memory-limit=SIZE or SPECULA_TLC_MEMORY_LIMIT; use --tlc-worker-limit=N only when an aggregate worker cap is desired.

Compatibility changes

  • --skip-validation has been renamed to --skip-validate; the old spelling is rejected.
  • Final reports moved from .specula-output/spec/confirmed-bugs.md and .specula-output/spec/bug-severity.md to .specula-output/confirmed-bugs.md and .specula-output/bug-severity.md. Confirmation and severity reports also use entry-oriented headings and tables. Update scripts that consume these paths or parse ## Bug N headings.
  • The modeling term Bug Family is now Scenario. findings.json schema version 2 replaces family with scenario, modeling briefs use Scenario N headings, and the bug-tracker helper uses --scenario instead of --bug-family.

Installation limitations

v0.3.0 remains a source release. Plain wheel and PyPI installation are not supported because the runtime depends on repository-local scripts, skills, and tools. Install from a persistent checkout with uv tool install -e . and keep that checkout in place.

GitHub-generated source archives do not contain submodule contents. Use a recursive Git clone when the curated case-study corpus or submodule-hosted research tools are needed.

Known limitations

  • Native Windows is not supported; use WSL2.
  • We recommend at least 32 GB of RAM and 100 GB of free disk space for full runs.
  • --keep-original requires isolated output mode and rejects layouts with external symlinks, linked worktrees, submodules, nested repositories, or externally shared Git objects. Without the optional agent sandbox, it cannot prevent a command from deliberately writing to the original checkout through an absolute path.
  • Exact-session recovery preserves provider-persisted conversation state and files, but cannot restore a terminated CLI process's in-memory state or an in-flight child process.
  • Copilot CLI, OpenCode, and Pi do not support Specula's agent-side stop gate.
  • Some frontier models require additional provider access for Phase 4 bug confirmation; use hybrid agent configuration when a different model or provider is needed for that phase.

Full changelog: v0.2.0...v0.3.0

Assets 2
Loading