## Summary A third playbook mode. A `mode: stint` playbook declares roles instead of nodes, and the driver compiles one sub-agent graph per round, so a stint is not a sibling of a `dag` run but a layer over it: one fan-out is one graph, and many rounds are one graph each. Thirty rounds is thirty graphs on the shared dispatch path, which is what makes the validation, the dispatch budget, the approval gate and the detached-run bookkeeping the ones already there rather than a second set. The stint is a file. Nothing depends on the process that started it still being alive: a gateway restart, a machine restart, or a `raven playbook stints resume` all pick it up, and the resume is node-granular, so a round that died with two roles done re-runs the third. **One noun, singular and plural.** The mode is `mode: stint`; one run of such a playbook is a stint, with its own id, checkout and record; the plural is the command family and the RPC namespace. `round` keeps its own meaning as the unit inside -- one pass of every role -- and `stage` as one role's turn in it, so "the stint is on round 7 of 30" says three different things with three different words. The whole surface sits under `raven playbook`: `stints` answers what has run on this machine, `stint` acts on one project's layout and the backlog its roles share. **Handover is files, not a conversation.** Every role opens a fresh conversation each round, which is a decision rather than a limitation: which instance serves which role changes, processes restart, transcripts get compacted. What a role learned this round reaches the next one only by being written down. That makes the journal the contract -- an append-only file, windowed by recent rounds and by characters, because a forty-round journal would otherwise fill the prompt it exists to inform. **The boundary is three layers.** `owns` and `appends` are declared in the playbook, rendered into the role's prompt from the same declaration the enforcement reads, measured by the role's own checks, and undone afterwards with the file the role wrote kept under `violations/`. Declaring without telling is a trap; telling without undoing is a suggestion; and the undo reads the stage's own commits as well as the worktree, because a role that commits a stray write disappears from the working tree and a boundary any role can step around by committing is not one. Nothing refuses a write before it lands: a charter narrows a role's tools only where the playbook declares a `playbook:` block, and `owns` is not derived into one, so the shipped playbook's roles have no tool gate and the undo is the boundary rather than its backstop. Two shapes the boundary cannot hold are refused where they are written rather than left to surface as violations in round four: - **Two roles that can run at once where either is enforced.** They share one checkout, so the first judged is graded against the difference the whole tree shows and quarantines the other's work. Observed before it was refused: two roles with disjoint `owns`, each writing only what it owned, and the first judged came back as `dev-a wrote 1 path(s) it may not write: src/b/work.py`, with that file gone. The message names both ways out, because which one is right is the author's call. What would make it work is a checkout per concurrent role, which is a merge problem, not a validation rule. - **`enforce.read: hard`.** It reaches the guard text, which then tells the role that reads outside its paths are refused at the tool gate, and no gate refuses one. The wording stays in `rounds_prompt` for whoever wires the gate; until then the grade is not offered. **Checks come before any model's opinion.** `verify[]` runs real commands, and a failure goes back to the role that caused it with the failure text, up to `maxHandbacks`. When that budget runs out the round records the failure and carries on rather than failing the node: a failed node skips every role downstream, and a failed build is exactly what the reviewer downstream has to see. **One approval, and it names what it is approving.** The whole stint is confirmed once, at the start, and the text states the round budget and every command the stint may run -- a playbook is a distribution unit, so a file somebody handed you does not get to run shell thirty times on one unexamined yes. Every round is charged against the hourly dispatch budget like any graph; a round the budget turns down pauses the stint rather than failing it, and `stints resume` takes it up once the allowance recovers. From the CLI the same approval is put to the terminal, and with no terminal to ask at the run is refused rather than approved on nobody's behalf. A stint works a checkout of its own, cut from the project's head, so hours of its commits do not collide with the conversation that started it. `stop.maxRounds` defaults to 10 and is capped at 99. `stop.until` lets a role end a stint early by reporting a marker on a line of its own -- a whole line, so a role quoting the marker mid-sentence does not end the plan -- and only a terminal role is told the marker, because a role that knows how to stop the stint has a reason to reach for it. **Surfaces.** `raven playbook stints list/get/extend/pause/stop/resume/sweep/answer`, where `resume` and `extend` are relayed to the raven serving the page when one is up, so a round runs in the process that owns the conversation; `playbooks.stints.*` RPC methods, the read-only ones reading the record off disk so opening the page does not cost what a dispatch costs; a Stint tab on the playbook page showing the roles, what each owns, the checks with their full commands, and what carries between rounds; and a Runs tab listing every stint with its standing, how far into its budget it is, each round's checks and what was undone, with pause, stop and resume. `raven playbook stint` lays a project out for one. The shipped playbook is `rounds`: a planner, a builder and a verifier, on any project that has a specification. `init` writes `.stint/`: a guard file per role, the shared prose, and a link to the project's own specification, chosen by two sieves -- the file name first, then how much of the document says something is required, so an empty `SPEC.md` stub does not send thirty rounds off a blank page. `task`, `ask` and `confirm` work the backlog the roles share. New package `raven/stint/` carries the parts a stint needs that are not the playbook: the record, its checkout, the ownership grades, the journal window and the check runner. `CONTEXT.md`, `CHANGELOG.md` and the two `docs-site` repo-layout tables gain their rows; `README.md` is not touched. Three unrelated changes ride along. Two are the same shape -- a web change that does not show: - `index.html` went out with no caching header, so browsers fell back to heuristic freshness and served a rebuilt page from cache without asking, which reads exactly like a server that never picked the change up. `no-cache` keeps the entry and revalidates; the ETag still saves the transfer. - `make ui` is one target for the two-step page build, because running only vite leaves the served one-file page unchanged with nothing to say so. The third is `raven agent` (`raven/cli/agent_commands.py`): `--message-file` reads the prompt from a file, `--permission-mode` picks the tier for the run, and `--no-markdown` prints a soft-wrapped `Text` rather than a markdown render; 92 lines of tests in `tests/test_cli_agent_commands.py`. Designed and deliberately not built, so a reviewer knows where the edges are: a checkout per concurrent role with each role merging itself in when it is judged (`docs/plans/2026-09-18-stint-acceptance.md`), and the backlog-writing round zero. `raven playbook stint confirm` records a person's word on the plan and nothing in the rounds path reads the flag yet, which that document also says. ## Type - [ ] Fix - [x] Feature - [ ] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification ``` uv run ruff check --no-cache raven evolver agents plugins-dist tests scripts uv run ruff format --check --no-cache raven evolver agents plugins-dist tests scripts uv run lint-imports make lint-types make lint-ui make lint-tui uv run pytest -q uv run python scripts/check_commit_messages.py main..HEAD uv run python scripts/check_source_language.py main..HEAD uv run python scripts/check_large_files.py main..HEAD ``` Ruff clean over 2,004 files. Import contracts: 10 kept, 0 broken. `ty` clean, which caught one real defect on the way in: `StintStore.list` shadowed the builtin for every annotation after it in the class body, so `-> list[StintRecord]` on it and on `live()` resolved to the method. The UI gates include the generated-file drift checks (`gen:check`, `lint:rpc`, `lint:i18n`) and both type-checks; eslint reports 23 warnings and 0 errors, none of them in a file this branch touches. `make lint-bridge` was not run: this checkout has no `bridge/node_modules`, and nothing here touches `bridge/`. Suite: the whole `uv run pytest -q` runs in CI as four shards, and every shard is green at this head, with the import-cycle budget (44 modules, the same as `main`), the coverage gate and the three content gates over the commit range. Locally the suites this branch touches are run per change; the full run is CI's. Behaviour, driven rather than asserted: - A stray write by a concurrent role was reproduced end to end before the validation refused the shape: `dev-b's own file still there after dev-a was judged: False`, `violations recorded against dev-a: ['dev-a wrote 1 path(s) it may not write: src/b/work.py']`. - The check runner's timeout kills the process group, not just the direct child. Proved as a regression guard: red with `process.kill()`, green with the group teardown. - The round budget refuses rather than wrapping: extending a real stint past the ceiling answered `that would give it a budget of 104, and 99 is the most any stint may have`, and the file was not written. - The spec picker's two sieves, over a real project: `KEPT docs/PRD.md | weight 12`, `dropped SPEC.md | len 12 | weight 0`, `dropped notes.md | len 868 | weight 0`. - Only a terminal role is told the stop marker: `planner=False builder=False verifier=True` on the shipped example. - The shipped example is discoverable with no user layer: `listed: ['rounds']`, `origin: builtin`. - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed ## Risk Additive. `mode: stint` is a new value; `dag` and `prompt` playbooks load, validate, dispatch and report exactly as before, and the sections the new mode reads are withheld from the generator's emit schema, so no generated playbook can reach them. That withholding is pinned by a test that fails when a section is added to the spec without being added to the refusal. Nothing outside the new mode changes behaviour: `spawn` and the DAG path keep the per-session in-memory dispatch window they have on `main`. A plan runs shell from `verify[]`. It is gated on the approval, the approval text lists every command, and a playbook carrying `verify` cannot be generated -- only written by hand or shipped. The builtin layer ships exactly one playbook, `rounds`, pinned by name in a test, for that reason: withheld from the generator and not shipped either, the mode would be reachable only by transcribing YAML out of prose. Rollback is a revert of the merge commit. A plan's on-disk record is under the sub-agent history root and is read by nothing else; nothing else's on-disk shape changes. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: Ethan Wang <ethan.wang@evermind.ai> Co-authored-by: Claude (claude-opus-5[1m]) <noreply@anthropic.com>
238 lines
10 KiB
Python
238 lines
10 KiB
Python
"""Laying out a project that has never run a stint, before the stint starts.
|
|
|
|
The case this exists for: somebody says "run rounds" in a repository that
|
|
was never set up. Before, that cost seven commands to discover; without them
|
|
the stint started and every round failed rendering a file reference, for as many
|
|
rounds as its budget allowed.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import json
|
|
from pathlib import Path
|
|
|
|
from raven.i18n.zh_lexicon import SAYS_WHAT_IS_REQUIRED as SAYS_WHAT_IS_REQUIRED_ZH
|
|
from raven.stint.bootstrap import says_what_is_required
|
|
from raven.stint.setup import lay_out
|
|
|
|
SPEC = """# Ledger
|
|
|
|
A plain-text double-entry bookkeeping library.
|
|
|
|
## Requirements
|
|
|
|
- Every posting must balance: debits equal credits, or it is rejected.
|
|
- The CLI should print a trial balance with `ledger balance`.
|
|
- A malformed entry must exit with code 2 and a message on stderr.
|
|
|
|
## Acceptance
|
|
|
|
- `uv run pytest -q` passes. The scope is journals, accounts and reports.
|
|
"""
|
|
|
|
|
|
def _repo(tmp_path: Path, spec: str | None = SPEC, where: str = "docs/PRD.md") -> Path:
|
|
project = tmp_path / "project"
|
|
(project / "docs").mkdir(parents=True)
|
|
(project / ".git").mkdir()
|
|
if spec is not None:
|
|
(project / where).write_text(spec, encoding="utf-8")
|
|
return project
|
|
|
|
|
|
class TestPickingTheSpecification:
|
|
"""Name first, then content. The name is only a promise."""
|
|
|
|
def test_a_stub_named_like_a_specification_is_not_one(self, tmp_path: Path) -> None:
|
|
"""An empty `SPEC.md` would otherwise send every round to stint from a
|
|
blank page, on the strength of its filename."""
|
|
project = _repo(tmp_path, spec="# SPEC\n\nTODO\n", where="SPEC.md")
|
|
|
|
found = lay_out(project, "stint")
|
|
|
|
assert not found.ready
|
|
assert "nothing to stint from" in found.missing
|
|
|
|
def test_a_long_document_that_requires_nothing_is_not_one_either(self, tmp_path: Path) -> None:
|
|
project = _repo(tmp_path, spec="# Notes\n\n" + "we talked about the weather. " * 40, where="docs/notes.md")
|
|
|
|
assert not lay_out(project, "stint").ready
|
|
|
|
def test_the_document_that_says_what_has_to_be_true_is_the_one(self, tmp_path: Path) -> None:
|
|
project = _repo(tmp_path)
|
|
(project / "docs" / "notes.md").write_text("# Notes\n\n" + "chatter. " * 60, encoding="utf-8")
|
|
|
|
found = lay_out(project, "stint")
|
|
|
|
assert found.ready
|
|
assert found.spec == "docs/PRD.md"
|
|
assert found.also_matched == 0, "the notes were dropped, not ranked second"
|
|
|
|
def test_the_standing_orders_are_not_candidates(self, tmp_path: Path) -> None:
|
|
"""They are full of "must" and "should" and they are requirements about
|
|
the roles, not about the project. Laying out twice must not start
|
|
offering them as the thing to stint from."""
|
|
project = _repo(tmp_path)
|
|
lay_out(project, "stint")
|
|
|
|
again = lay_out(project, "stint")
|
|
|
|
assert again.spec == "docs/PRD.md"
|
|
assert again.also_matched == 0
|
|
|
|
def test_a_specification_written_where_the_refusal_asked_for_one_is_found(self, tmp_path: Path) -> None:
|
|
"""The refusal names `.stint/SPEC.md`. A finder that did not look there
|
|
would ask for the file again on the next run."""
|
|
project = _repo(tmp_path, spec=None)
|
|
first = lay_out(project, "stint")
|
|
assert not first.ready and ".stint/SPEC.md" in first.missing
|
|
|
|
(project / ".stint" / "SPEC.md").write_text(SPEC, encoding="utf-8")
|
|
|
|
assert lay_out(project, "stint").spec == ".stint/SPEC.md"
|
|
|
|
def test_the_count_is_of_words_that_say_something_is_required(self) -> None:
|
|
assert says_what_is_required("the release notes for October") == 0
|
|
assert says_what_is_required("Every posting must balance. Acceptance: it is rejected.") == 2
|
|
# The zh half of the table, composed from the catalog rather than written
|
|
# here: CJK in a test outside `tests/test_i18n_*` is a source-language
|
|
# violation, and the words themselves are language data with one home.
|
|
must, acceptance = SAYS_WHAT_IS_REQUIRED_ZH[0], SAYS_WHAT_IS_REQUIRED_ZH[4]
|
|
assert says_what_is_required(f"{must}{acceptance}") == 2
|
|
|
|
|
|
class TestWhatALayoutLeavesBehind:
|
|
def test_a_project_that_has_never_run_a_plan_is_laid_out(self, tmp_path: Path) -> None:
|
|
project = _repo(tmp_path)
|
|
|
|
found = lay_out(project, "stint")
|
|
|
|
assert found.ready
|
|
for name in ("planner.md", "builder.md", "verifier.md", "HUMAN_DECISIONS.md"):
|
|
assert (project / ".stint" / name).is_file(), name
|
|
assert all(name.startswith(".stint/") for name in found.wrote), found.wrote
|
|
|
|
def test_laying_out_twice_writes_nothing_the_second_time(self, tmp_path: Path) -> None:
|
|
"""A second stint on a set-up project is not a second setup, and a person
|
|
told to try again must not be risking their edits."""
|
|
project = _repo(tmp_path)
|
|
lay_out(project, "stint")
|
|
(project / ".stint" / "planner.md").write_text("my own orders\n", encoding="utf-8")
|
|
|
|
again = lay_out(project, "stint")
|
|
|
|
assert again.wrote == []
|
|
assert (project / ".stint" / "planner.md").read_text(encoding="utf-8") == "my own orders\n"
|
|
|
|
def test_a_directory_that_is_not_a_repository_is_refused_before_anything_is_written(self, tmp_path: Path) -> None:
|
|
"""A stint cannot be held to its boundaries without one, so laying the
|
|
project out first would leave files behind for a run that was never
|
|
going to happen."""
|
|
project = tmp_path / "loose"
|
|
project.mkdir()
|
|
|
|
found = lay_out(project, "stint")
|
|
|
|
assert not found.ready and "git init" in found.missing
|
|
assert not (project / ".stint").exists()
|
|
|
|
def test_a_recipe_this_build_does_not_have_is_refused_rather_than_guessed(self, tmp_path: Path) -> None:
|
|
"""The closed set is what makes `setup` safe to honour from a file
|
|
somebody else wrote."""
|
|
found = lay_out(_repo(tmp_path), "whatever-i-like")
|
|
|
|
assert not found.ready and "no setup recipe" in found.missing
|
|
|
|
def test_a_backlog_is_counted_when_the_project_has_one(self, tmp_path: Path) -> None:
|
|
project = _repo(tmp_path)
|
|
lay_out(project, "stint")
|
|
(project / ".stint" / "backlog.json").write_text(
|
|
json.dumps({"tasks": [{"id": "T1"}, {"id": "T2"}]}), encoding="utf-8"
|
|
)
|
|
|
|
assert lay_out(project, "stint").backlog == 2
|
|
|
|
def test_no_backlog_is_told_apart_from_an_empty_one(self, tmp_path: Path) -> None:
|
|
project = _repo(tmp_path)
|
|
assert lay_out(project, "stint").backlog == -1
|
|
|
|
(project / ".stint" / "backlog.json").write_text(json.dumps({"tasks": []}), encoding="utf-8")
|
|
assert lay_out(project, "stint").backlog == 0
|
|
|
|
|
|
class TestWhatTheBuilderMayWrite:
|
|
"""The grant has to cover the work the round's own check measures."""
|
|
|
|
def test_a_greenfield_project_grants_the_tests_directory(self, tmp_path: Path) -> None:
|
|
"""Measured on a greenfield run: the brief asked for `tests/test_x.py`
|
|
by name, the round's own check ran `compileall src tests`, and the
|
|
Builder's grant stopped at the source -- so it wrote the code, wrote the
|
|
tests for it, and had the tests undone as a write it may not make. The
|
|
layout was refusing the write its own check depended on."""
|
|
from raven.stint.bootstrap import source_dirs
|
|
|
|
granted = source_dirs(_repo(tmp_path))
|
|
|
|
assert "tests/**" in granted, granted
|
|
|
|
def test_a_project_with_only_tests_is_still_greenfield(self, tmp_path: Path) -> None:
|
|
"""A test directory is somebody's work but not the thing being built, so
|
|
having one says nothing about where the source will live."""
|
|
from raven.stint.bootstrap import source_dirs
|
|
|
|
project = _repo(tmp_path)
|
|
(project / "tests").mkdir()
|
|
|
|
granted = source_dirs(project)
|
|
|
|
assert "src/**" in granted and "tests/**" in granted, granted
|
|
|
|
def test_a_project_that_keeps_its_code_elsewhere_still_gets_its_own_dirs(self, tmp_path: Path) -> None:
|
|
from raven.stint.bootstrap import source_dirs
|
|
|
|
project = _repo(tmp_path)
|
|
(project / "lib").mkdir()
|
|
|
|
granted = source_dirs(project)
|
|
|
|
assert "lib/**" in granted
|
|
assert "project/**" not in granted, "a detected source tree is not widened by the greenfield set"
|
|
|
|
def test_what_an_interpreter_leaves_beside_the_files_it_read_is_nobodys(self, tmp_path: Path) -> None:
|
|
"""A role that runs the tests has caches written for it. Graded as its
|
|
writes they are a violation it can neither avoid nor undo."""
|
|
from raven.stint.bootstrap import BYPRODUCT_GLOBS
|
|
|
|
lay_out(_repo(tmp_path), "stint")
|
|
guard = (tmp_path / "project" / ".stint" / "builder.md").read_text(encoding="utf-8")
|
|
|
|
for glob in BYPRODUCT_GLOBS:
|
|
assert glob in guard, f"{glob} is not declared as an artifact"
|
|
|
|
|
|
class TestARecipeAndTheRolesThatNameIt:
|
|
def test_a_playbook_whose_roles_the_recipe_does_not_know_is_told_so(self, tmp_path: Path) -> None:
|
|
"""The recipe writes a guard file per role and knows three. A playbook
|
|
naming others got those three written anyway -- files belonging to
|
|
nobody in the run -- and found out later, if at all, when a `{{ref:}}`
|
|
to its own guard resolved to nothing."""
|
|
project = _repo(tmp_path)
|
|
|
|
found = lay_out(project, "stint", roles=["writer", "checker"])
|
|
|
|
assert not found.ready
|
|
assert "writer, checker" in found.missing
|
|
assert "planner, builder, verifier" in found.missing
|
|
assert not (project / ".stint").exists(), "nothing is written when the recipe cannot serve the roles"
|
|
|
|
def test_the_roles_the_recipe_knows_are_laid_out_as_before(self, tmp_path: Path) -> None:
|
|
found = lay_out(_repo(tmp_path), "stint", roles=["planner", "builder", "verifier"])
|
|
|
|
assert found.ready, found.missing
|
|
assert (tmp_path / "project" / ".stint" / "builder.md").is_file()
|
|
|
|
def test_a_caller_that_names_no_roles_is_laid_out_as_before(self, tmp_path: Path) -> None:
|
|
"""The check is on what a playbook declares; a caller with nothing to
|
|
declare -- `stint init` on a terminal -- is not refused for it."""
|
|
assert lay_out(_repo(tmp_path), "stint").ready
|