Skip to content

CHANGELOG.md

Latest commit

 

History

History
302 lines (264 loc) · 22.3 KB

CHANGELOG.md

File metadata and controls

302 lines (264 loc) · 22.3 KB
Raw

Changelog

All notable Rally release changes live here. This file is the portable release history. docs/VERSIONING.md is the evergreen policy guide.

The format is based on Keep a Changelog.

When you cut a public release:

  1. Copy the release entry template below.
  2. Replace the placeholders.
  3. Move the real change notes into the new release section.
  4. Leave ## Unreleased at the top for the next cycle.

Public release entries must replace every placeholder before make release-tag or make release-draft runs. The helper rejects placeholder release-header text and breaking releases with no real upgrade steps.

Release Entry Template

## vX.Y.Z - YYYY-MM-DD

Release kind: Non-breaking
Release channel: stable
Release version: vX.Y.Z
Affected surfaces: ...
Who must act: ...
Who does not need to act: ...
Upgrade steps: ...
Verification: ...
Support-surface version changes: none

### Added
- Describe backward-compatible user-facing additions.

### Changed
- Describe user-visible behavior or workflow changes.

### Deprecated
- Describe soft-deprecated public surfaces and early move guidance.

### Removed
- Describe removed public surfaces.

### Fixed
- Describe important fixes that matter to users or maintainers.

### YANKED
- Use this only when a bad public release was superseded later.

Unreleased

Use this section for work that is not public yet.

v3.0.0 - 2026-04-20

Release kind: Breaking Release channel: stable Release version: v3.0.0 Affected surfaces: Rally package metadata Doctrine floor, supported Doctrine package line, Rally stdlib output-schema authoring inherited from Doctrine Language 5.0, host-repo .prompt files that still use the retired type: string plus enum: form on output schema fields, and downstream consumers of rally-agents whose pyproject.toml still pins rally-agents<3. Who must act: (1) host authors whose .prompt files still declare output schema fields with the retired type: string plus enum: form or the retired inline type: enum plus values: form (Doctrine v5 emits E320); (2) host authors who consumed Rally's RallyTurnKind or ReviewVerdict enum values through bare string literals — v3 exports both as top-level enum declarations in stdlib/rally/prompts/rally/turn_results/AGENTS.prompt and stdlib/rally/prompts/rally/review_results/AGENTS.prompt and the inherited schemas now reference them with type: EnumName; (3) host repos that still ship a doctrine-agents<5 pin alongside Rally; (4) downstream consumers of rally-agents (e.g. psflows) whose pyproject.toml still pins rally-agents<3. Who does not need to act: users who resolve doctrine-agents only through Rally's declared range, users whose .prompt files already use the type: <EnumName> form with a declared top-level enum, and users who consume emitted schemas/<output-slug>.schema.json wire shape (the lowered JSON Schema only gains a One of ... description suffix, the type contract is preserved). Upgrade steps: (1) install rally-agents v3.0.0 so Rally pulls doctrine-agents>=5.0.0,<6; (2) refresh any lockfile or dependency pin that still points at doctrine-agents<5 to doctrine-agents>=5.0.0,<6; (3) in host .prompt files, replace every output schema field that used type: string plus enum: or type: enum plus values: with a top-level enum X: "..." decl plus type: X on the field (Doctrine compile errors cite E320); (4) downstream flow authors who want per-gate review reject ... when ... lines, per-case override gates:, typed schema ... gates:, typed_as: handoff identity, skill mode binding, typed abstract parameters, or declarative rule primitives can now adopt them directly — the shipped poem_loop and software_engineering_demo flows are worked exemplars under flows/*/prompts/; (5) rerun uv run rally build (or make emit in the Rally repo) after the upgrade so emitted build artifacts regenerate against the Doctrine 5.0 language. Verification: make verify Support-surface version changes: minimum Doctrine release v4.0.0 -> v5.0.0; supported Doctrine package line doctrine-agents>=4.0.0,<5 -> doctrine-agents>=5.0.0,<6; inherited Doctrine language 4.0 -> 5.0; workspace manifest 1 (unchanged); compiled contract version 1 (unchanged)

Added

  • Doctrine v5 exemplar adoption across Rally's stdlib and shipped flows. Top-level export enum RallyTurnKind and export enum ReviewVerdict declarations live in stdlib/rally/prompts/rally/turn_results/AGENTS.prompt and stdlib/rally/prompts/rally/review_results/AGENTS.prompt; every flow-local schema references them with type: EnumName. Every gate in every shipped review contract carries a reject contract.<gate> when ... line closed by accept "..." when contract.passes. The poem review contract migrated from prose workflow to typed schema ... gates:. A new shared WorkRoleTurnResultSchema parent factors the work-role turn-result fields so role schemas only declare their own next_route field. The rally-learn skill refs teach the v5 canonical shapes (typed enums, typed gates, per-gate accept, anti-patterns for contract.passes and legacy type: string + enum:).
  • Installable rally-learn skill (13 refs + SKILL.md + openai.yaml) teaching flow authoring end-to-end inside Codex and Claude Code. skills/rally-learn/ is the authoring source; skills/.curated/rally-learn is the shipped export. make skills emits the bundle and shells out to npx skills add . for interactive install. tests/unit/test_emit_skill.py covers emit-drift and end-to-end npx-skills install into a sandboxed HOME.
  • Six enduring reference docs: docs/RALLY_PRINCIPLES.md, docs/RALLY_QUICK_START.md, docs/TURN_RESULT_CONTRACT.md, docs/FLOW_YAML_REFERENCE.md, docs/ERROR_REFERENCE.md, and docs/SKILL_AUTHORING.md. README grew Learn Rally + Reference sections.
  • Flow-code CLI aliases. Every command that takes a run-id now also accepts the bare three-letter flow code, e.g. rally watch POM -f, rally status POM, rally issue current --run-id POM. Resolver lives in src/rally/services/run_store.py::resolve_run_id. Mutating commands require an active run and surface a hint at the latest archived id when only archives exist.
  • runs/latest/<CODE> symlinks, atomically maintained by create_run and archive_run via a new replace_symlink helper. Targets are relative so runs/ stays relocatable. Native unix tools work without a Rally wrapper: tail -f runs/latest/POM/logs/rendered.log, bat runs/latest/POM/home/issue.md. Symlink updates are best-effort.
  • rally run <flow> --detach and rally resume <id> --detach start a Rally run in the background via a double-fork. The parent prints the grandchild pid and returns immediately; the detached worker continues the normal loop with stdio redirected into runs/active/<id>/logs/stdout.log and stderr.log. run in the background via a double-fork. The parent prints the grandchild pid and returns immediately; the detached worker continues the normal loop with stdio redirected into runs/active/<id>/logs/stdout.log and stderr.log.
  • rally stop <run-id> asks a run to stop at the next turn boundary by writing control/stop.requested. The runner loop observes the file, finalizes the run as STOPPED, appends a "Rally Stopped" entry to issue.md, and emits a STOPPED event. Idempotent.
  • rally stop <run-id> --now [--grace <secs>] escalates to SIGTERM, then SIGKILL after the grace window, targeting the run's recorded process or process group.
  • rally watch <run-id> [--since N] [--follow] renders logs/events.jsonl for one run; --follow polls for new events until the run reaches a terminal status.
  • Reconciled status (CRASHED / ORPHANED / STALE) surfaces in rally status for runs whose recorded state no longer matches the live process.
  • Per-run heartbeat.json (updated every 15s by a background thread) and done.json clean-exit sentinel — their combination lets the reconciler distinguish orderly termination from a crash.
  • New event codes: DETACH, STOPPED, STOP_REQUESTED, HEARTBEAT, CRASH_DETECTED.
  • Always-on run timing. At every terminal turn event (handoff, done, blocker, sleep), Rally writes runs/<id>/timing.json (cumulative snapshot), appends to runs/<id>/timing_turns.jsonl and runs/<id>/tool_calls.jsonl, and emits a SUMMARY event that renders an inline receipt showing where the last turn and the whole run spent time. At done, a one-line summary is appended to workspace-level runs/timings.ndjson. Both adapters now project tool_use_id, input_digest, is_error, and exit_code on tool-call events. Input digests are secret-scrubbed. See docs/RALLY_RUN_TIMING.md for schema and rendering details.
  • Anomaly flags on every receipt. Six rules — command_always_fails, tool_error_rate, single_call_hot, model_spin, retry_group, high_idle — evaluate against the current RunTiming at every terminal turn event and render inline under the cumulative block. high_idle is suppressed in --step mode.
  • rally status <run-id> gains a three-line time footprint derived from timing.json (wall/active/idle, top tools, token totals). Silently omitted when timing.json is not yet present.
  • rally watch <run-id> now inlines SUMMARY receipts in the event stream and prints a compact per-turn progress line after every tool-end event.
  • rally runs time [--flow CODE] [--last N] reports longitudinal trends across runs/timings.ndjson — recent-run table plus p50 / p90 / mean for wall, active, errors, tools, and tokens.

Changed

  • runs/active/<id>/state.yaml and run.yaml writes are now atomic (tempfile + fsync + os.replace + directory fsync). State gains schema_version (default 2), pid, process_create_time, and pgid fields. schema_version: 1 (pre-detach) state is tolerated and upgraded on the next write.
  • Per-flow lock migrated from O_EXCL+PID-file to fcntl.flock. The lock is now held on an open file description, so it automatically releases on process death and survives fork into detached children — closing the old PID lock file as a side effect used to orphan the lock.
  • rally status uses a reconciler that computes status from (state.yaml + heartbeat.json + done.json + probe(pid)). Stored terminal states (DONE / BLOCKED / STOPPED) remain sticky; all other computed statuses are presentation-only and never persisted.

Added (deps)

  • psutil>=6,<7 for durable (pid, create_time) process identity. Isolated to rally.services.process_identity; no other module imports psutil.

v2.0.0 - 2026-04-18

Release kind: Breaking Release channel: stable Release version: v2.0.0 Affected surfaces: Rally package metadata Doctrine floor, supported Doctrine package line, Rally stdlib prompt layout on disk, packaged data-files glob, host-repo .prompt authoring inherited from Doctrine Language 4.0, and downstream provider-root prompt authoring (e.g. psflows' curriculum_shared/). Who must act: (1) host authors whose .prompt files still use same-flow import lines between siblings under one AGENTS.prompt or SKILL.prompt root (Doctrine 4.0 emits E315); (2) host authors whose cross-flow imports reach declarations that are not marked export (Doctrine 4.0 emits E314); (3) authors of shared provider roots registered through additional_prompt_roots whose modules are flat .prompt files rather than directory-backed flows (v4 requires every import target to live under a flow root); (4) host repos that still ship a doctrine-agents<4 pin alongside Rally; (5) downstream consumers of rally-agents (e.g. psflows) whose pyproject.toml still pins rally-agents<2. Who does not need to act: users who resolve doctrine-agents only through Rally's declared range, users whose flows already live under one flow root with cross-flow import lines and no same-flow imports, and users who do not register shared provider roots. Upgrade steps: (1) install rally-agents v2.0.0 so Rally pulls doctrine-agents>=4.0.0,<5; (2) refresh any lockfile or dependency pin that still points at doctrine-agents<4 to doctrine-agents>=4.0.0,<5; (3) in host .prompt files, delete same-flow import lines — under Doctrine v4 every .prompt under one AGENTS.prompt or SKILL.prompt root shares a flat namespace and siblings resolve by bare name (Doctrine compile errors cite E315); (4) mark every declaration consumed across flow boundaries with the export modifier (Doctrine compile errors cite E314); (5) restructure shared provider-root trees so each shared module is its own flow root with an AGENTS.prompt or SKILL.prompt entrypoint — the Rally stdlib restructure at stdlib/rally/prompts/rally/<module>/AGENTS.prompt is the canonical example; (6) keep each review block in the same .prompt file as its contract workflow declaration (v4 review contract resolution is per-file, not flow-wide); (7) rerun uv run rally build (or the host equivalent) after the upgrade so emitted build artifacts regenerate under the new Doctrine namespace rules; (8) downstream consumers of Rally (e.g. psflows) must bump their rally-agents pin to >=2.0.0,<3 and apply steps (3)–(6) to their own flows and provider roots before they can run. Verification: make verify Support-surface version changes: minimum Doctrine release v2.0.0 -> v4.0.0; supported Doctrine package line doctrine-agents>=2.0.0,<3 -> doctrine-agents>=4.0.0,<5; inherited Doctrine language 3.0 -> 4.0; Rally stdlib disk layout retires stdlib/rally/prompts/rally/<module>.prompt in favor of stdlib/rally/prompts/rally/<module>/AGENTS.prompt (one flow root per shared module); package data-files glob updated to ship the new stdlib tree; workspace manifest 1 (unchanged); compiled contract version 1 (unchanged)

Changed

  • Raised Rally's public Doctrine floor to doctrine-agents>=4.0.0,<5 so Rally installs resolve against the Doctrine 4.0 release line and pick up the new Doctrine language (4.0) flow-namespace rules: directory-backed flow roots, retired same-flow import, required export for cross-flow visibility, and retired relative imports.
  • Restructured Rally's stdlib so each shared module is its own directory-backed flow root at stdlib/rally/prompts/rally/<module>/AGENTS.prompt. Downstream import rally.<module> keeps resolving; declarations consumed cross-flow carry the new export modifier.
  • Colocated review blocks with their contract workflow declarations inside each shipped flow (Doctrine v4 resolves review contracts per-file).
  • Updated the [tool.setuptools.data-files] globs so pip install rally-agents keeps shipping the new stdlib tree.
  • Updated docs/VERSIONING.md, README.md, docs/RALLY_RUNTIME.md, docs/RALLY_MEMORY.md, docs/RALLY_COMMUNICATION_MODEL.md, docs/RALLY_SOFTWARE_ENGINEERING_FLOW_SHOWCASE.md, and the tests-side packaged-install proof to carry the new paths and floor in one place.
  • Added a "Provider Roots Under Doctrine v4" section to docs/RALLY_PORTING_GUIDE.md so downstream repos (psflows and similar) can mirror the same pattern when they port their shared prompt roots.

v1.0.0 - 2026-04-17

Release kind: Breaking Release channel: stable Release version: v1.0.0 Affected surfaces: Rally package metadata Doctrine floor, supported Doctrine package line, host-repo prompt compatibility inherited from Doctrine 3.0, and host-repo readers of emitted Doctrine contracts and ## Outputs Markdown. Who must act: (1) host authors whose .prompt files still use retired Doctrine 2.x forms that Doctrine 3.0 rejects, especially required: or optional: inside output schema fields and route fields (Doctrine emits E236 and E237); (2) downstream readers of emitted AGENTS.contract.json, which Doctrine 2.0 retired in favor of final_output.contract.json plus schemas/<output-slug>.schema.json; (3) downstream snapshot, parser, or scraper users of emitted ## Outputs Markdown, the old _ordered list_ or _unordered list_ helper lines, and the old compiler-owned review-semantics and single-child * Binding wrappers; (4) host repos that still ship a doctrine or doctrine-agents<2 pin alongside Rally. Who does not need to act: users who resolve doctrine-agents only through Rally's declared range, users who consume schemas/<output-slug>.schema.json wire shape, and users who stay on a source checkout with an editable ../doctrine that already tracks Doctrine 3.0 syntax. Upgrade steps: (1) install rally-agents v1.0.0 so Rally pulls doctrine-agents>=2.0.0,<3; (2) refresh any lockfile or dependency pin that still points at doctrine or doctrine-agents<2 to doctrine-agents>=2.0.0,<3; (3) in host .prompt files, replace authored required: and optional: inside output schema fields and route fields with nullable where the field may be null (Doctrine compile errors cite E236 and E237); (4) stop reading emitted AGENTS.contract.json — read final_output.contract.json for final-output, review-control, and the new top-level route and io metadata, and read schemas/<output-slug>.schema.json for structured-output wire shape; (5) refresh downstream emitted-Markdown snapshots and parsers to the new ## Outputs grouped-contract layout (no _ordered list_ or _unordered list_ helper lines, compacted review-semantics and single-child * Binding wrappers); (6) run uv run rally run <flow> (or the host equivalent) once after the upgrade to regenerate emitted build artifacts under the new Doctrine output shapes. Verification: make verify Support-surface version changes: minimum Doctrine release v1.0.2 -> v2.0.0; supported Doctrine package line doctrine-agents>=1.0.2,<2 -> doctrine-agents>=2.0.0,<3; inherited Doctrine language 2.2 -> 3.0; emitted AGENTS.contract.json retired in Rally-managed host builds; emitted schemas/<output-slug>.schema.json is now the sole structured-output wire contract; workspace manifest 1 (unchanged); compiled contract version 1 (unchanged)

Changed

  • Raised Rally's public Doctrine floor to doctrine-agents>=2.0.0,<3 so Rally installs resolve against the Doctrine 2.0 release line and pick up the new Doctrine language (3.0), retired authored required: and optional: inside output schema fields, the new grouped ## Outputs Markdown layout, and the retired AGENTS.contract.json by default.
  • Updated docs/VERSIONING.md and README.md to carry the new minimum Doctrine release and supported package line so host repos see the new floor in one place.

v0.1.1 - 2026-04-14

Release kind: Non-breaking Release channel: stable Release version: v0.1.1 Affected surfaces: external host-workspace bootstrap, Rally package metadata, and clean package install proof. Who must act: users who install Rally from package indexes and maintainers who cut Rally releases. Who does not need to act: users staying on a source checkout and users who already work from unreleased repo commits. Upgrade steps: Install rally-agents v0.1.1. Refresh lockfiles or dependency pins that still mention the old doctrine distribution name. The Rally CLI stays rally. Verification: make verify Support-surface version changes: workspace manifest 1 (unchanged); compiled contract version 1 (unchanged); minimum Doctrine release v1.0.2 (unchanged)

Added

  • Added rally workspace sync so a host repo can sync Rally-owned built-ins into stdlib/rally/, skills/rally-kernel/, and skills/rally-memory/ before the first rally run or manual doctrine.emit_docs.

Changed

  • Updated the external host-repo setup story and Rally design docs to use rally workspace sync as the front door for host-local built-ins.
  • Removed Rally's own [tool.uv.sources] override for Doctrine so Rally resolves the public doctrine-agents release by default and sibling repos can choose their own local editable Doctrine source cleanly.

Fixed

  • Switched Rally's public Doctrine dependency to doctrine-agents>=1.0.2,<2, which matches the first clean renamed-package Doctrine release on PyPI.
  • Removed the package-proof path that preinstalled Doctrine from git before installing Rally, so make verify-package, make verify, and CI now prove clean consumer installs.

v0.1.0 - 2026-04-14

Release kind: Non-breaking Release channel: stable Release version: v0.1.0 Affected surfaces: packaged runtime assets, explicit package metadata, the public release flow, and external host-repo setup. Who must act: maintainers cutting Rally releases and users installing Rally as a Python package. Who does not need to act: users who stay on unreleased commits and users who are not consuming Rally through package installers yet. Upgrade steps: Install rally-agents v0.1.0. The CLI stays rally. If you were running from a source checkout only, switch to the published package and follow the README host-repo setup flow. Verification: make verify Support-surface version changes: workspace manifest 1 (unchanged); compiled contract version 1 (unchanged); minimum Doctrine release v1.0.1

Added

  • Shipped Rally's packaged built-ins under src/rally/_bundled/ so installed runtimes no longer depend on a Rally source checkout.
  • Added a built-artifact external-user proof that installs the wheel, runs rally --help, runs rally run demo, and verifies host doctrine.emit_docs stays inside the host project root.
  • Added a repo-owned public release flow with make release-prepare, make release-tag, make release-draft, and make release-publish.
  • Added public support and security docs plus GitHub workflow hardening surfaces for release and dependency review.

Changed

  • Moved Rally release policy and compatibility guidance into the canonical docs/VERSIONING.md and CHANGELOG.md pair.
  • Switched Rally package metadata to explicit [project].version.
  • Published Rally on package indexes under distribution name rally-agents while keeping the import package and CLI name rally.
  • Replaced the tag-push-only publish path with a GitHub release publish workflow that rebuilds artifacts, reruns the external-user smoke proof, uploads release assets, and can publish to package indexes through Trusted Publishing.

Fixed

  • Stopped Rally-native stdlib support files from escaping host project roots in external Doctrine emit targets.

YANKED

  • Superseded by v0.1.1 because v0.1.0 still depended on the old doctrine package line and failed fresh package installs.