Frontier Run

Frontier Run is a model-availability sprint operating system. It turns a short window with a frontier model into a governed, resumable run across one or more projects, while leaving routine continuation work to cheaper workers.

The repository is designed to be pointed at directly:

1. The model reads START_HERE.md once.
2. It reads the target project's generated room/ directory.
3. It works only in the isolated workspace declared by the active sprint.
4. It closes the sprint by producing a machine-valid RESULT.json.

Frontier Run is the successor to the useful operating lessons in Fable Ops. It fixes four structural weaknesses:

• one canonical room schema, referenced consistently by every protocol;
• an immutable governance commit pinned into every room and result;
• worktree or sandbox isolation for every code-changing sprint;
• executable validation of room setup and sprint close-out.

Quick start

From a committed clone of this repository:

python -m frontier_run init-room /path/to/project \
  --project-name Example \
  --repository https://github.com/owner/example \
  --project-ref 0123456789abcdef0123456789abcdef01234567 \
  --canonical-path /path/to/project

python -m frontier_run init-sprint /path/to/project/room \
  --sprint-id 2026-07-frontier-1 \
  --objective "Reduce the parser without changing accepted inputs" \
  --success-criterion "All parser tests pass and source bytes decrease" \
  --isolation-mode git_worktree \
  --work-path /path/to/worktrees/example-frontier-1 \
  --branch frontier/2026-07-parser

python -m frontier_run validate /path/to/project/room

To hand an improvable-code run to Vineyard, first bind the envelope with Vineyard, then seal it into the active sprint:

python -m vineyard bind-frontier run.json --room /path/to/project/room
python -m frontier_run attach-output /path/to/project/room run.json \
  --kind vineyard-run
# Fill the remaining RESULT.json close-out fields and set DONE or PARTIAL.
python -m vineyard validate-frontier \
  /path/to/project/room/sprints/2026-07-frontier-1/OUTPUTS/run.json \
  --room /path/to/project/room

The copied artifact and its SHA-256 digest become part of RESULT.json; the original working file is no longer the authoritative handoff.

For a multi-project window, create a portfolio run and attach validated rooms:

python -m frontier_run init-run /path/to/frontier-runs/2026-08 \
  --run-id 2026-08-frontier
python -m frontier_run add-room /path/to/frontier-runs/2026-08 \
  --room /path/to/project/room --priority 1
python -m frontier_run validate-run /path/to/frontier-runs/2026-08

At close-out, fill room/sprints/<id>/RESULT.json, then run:

python -m frontier_run validate /path/to/project/room --close

The validator uses only the Python standard library. See ROOM_CONTRACT.md for the project contract and PORTFOLIO_RUN.md for multi-project traversal.

Autonomous cohort orchestration

A portfolio run can be driven by a deterministic state-to-decision loop instead of a human walking it manually. A pure decide_room function reads a normalized snapshot of one room and returns exactly one governed Decision; the thin executor performs (or idempotently records) that decision. Reserved actions (merge, deploy, enable, publish, accept-policy) always dominate, and sealing a result is never accepting it — those decisions stay human-only.

python -m frontier_run run-cohort /path/to/frontier-runs/2026-08 \
  --once --judge-adapter deterministic-fake-allow

--once evaluates at most one decision per eligible room and is the deterministic integration-test surface; omit it to loop until every room is blocked or its epic is complete. --judge-adapter selects a judge; only deterministic test fakes (deterministic-fake-allow|block|revise|escalate) are wired in this repository today — selecting or implementing a real judge model is a separate, explicitly reserved decision. See design/run-cohort/ARCHITECTURE.md for the full design.

Scope

Frontier Run can manage any project regime. It does not define the project's correctness oracle. For improvable-code projects, point the sprint at Vineyard; Vineyard then coordinates CPCs, Cellar verification, optimization engines, and promotion evidence.