references/ensure-store.md
# Ensure the current project has an orchestra store
This plugin is installed once. Do **not** copy skills, rules, or this
repo into the work project. Store selection comes from the versioned
`.canon/store-binding.json`; `.canon/config.json` contains store mechanics.
Project verification and landing policy comes from the root `orchestra.toml`.
In this repository,
records live in the shared SQLite database outside the worktree. Planning
commands opened from any worktree use that same database.
Requires `canon` and `orchestra` on PATH. Call both by name. Never
resolve a checkout path or a plugin root to run them.
## Which store
Dashboard and `orchestra store` resolve one SQLite database for this
repository under `~/.canon/<repo-name>/`. The tracked
`.canon/store-binding.json` selects `{"store":"global"}`, so every
worktree uses the same records. `.canon/config.json` selects the SQLite
backend, and `.canon/schemas/` keeps the schema snapshots used for
validation.
Run `canon` from any worktree in this repository. Do not pass a checkout
path or a plugin path to select the database. Use `orchestra store path`
to inspect the resolved location.
Run `canon backup` to create a retained backup in the repository's
`~/.canon/<repo-name>/backups/` directory before maintenance. SessionStart checks
the newest backup and creates one when it is older than 24 hours.
## Runtime commands
These are named commands, not files inside a checkout:
- `canon` writes and reads store records. `canon apply <file>` runs
many create, update, supersede, and correct operations from NDJSON
in one call.
- `orchestra handoff`, `orchestra view plan|status|verification`, and
`orchestra brief <work-item>` print derived views. They write no
files.
- `orchestra check` and `orchestra close-batch` run acceptance and
close work.
- `orchestra analyze <phase-slug>` checks a phase's specification,
work-items, and acceptances for consistency. It writes no files.
- `orchestra review-brief` builds the phase-end reviewer brief.
`orchestra suite policy`, `orchestra suite start`,
`orchestra suite poll`, `orchestra suite collect`, and
`orchestra suite record` run the configured phase suite and write
its check-run.
- `orchestra store path` prints the resolved store;
`orchestra store run -- <args>` runs `canon` against it.
- `orchestra verify` judges a claim in `.tuner/manifest.json`.
Do not hardcode a plugin directory or a home checkout in a command.
## Reference fields
A payload field that names another record holds that record's
**subject**, never its `rec-…` id. This covers `effort`, `milestone`,
`phase`, `work_item`, `assignment`, `acceptance`, and each entry of
`depends_on`. For example, an execution-report sets
`"work_item":"<task-slug>"`.
`canon` checks every reference when it writes. A write fails when no
record of the target type has that subject. Write the target record
first. An empty string skips the check.
Pinned fields take a record id instead: `informed_by` and
`contradicted_by` (JSON arrays of ids). The check-run `criterion_id`
is a plain string: an acceptance id, or a phase-level criterion such
as `<phase-slug>-review` or `<phase-slug>-suite`.
List fields are JSON arrays: `requirements`, `decisions`, `test_ids`,
`oracle_hashes`, `failing_node_ids`, `claim_ids`, `old_hashes`,
`new_hashes`, `merged_from`, `depends_on`.
## First run in a work repo
A store is marked by `.canon/config.json`. If it exists, the store
is ready. Do not run `init` again.
If it does not exist, run this from the work repo:
```bash
canon init --schemas score,conductor,tuner
```
`canon init` needs a git repo. If cwd is not git, say so and stop. Do
not write a plan document or extra skill copies.
After you upgrade orchestra or tuner, bring the store schemas up
to date:
```bash
canon schemas sync
```
`canon` validates against the schema snapshots in
`.canon/schemas/`, not against the installed tools.
## Project policy
The root `orchestra.toml` is required for project policy. Its `[suite]`
section controls the phase suite:
```toml
[suite]
mode = "none"
command = ""
gate = "required"
```
Read it with `orchestra suite policy`. Do not waive it. A human changes
`[suite]` in `orchestra.toml`. Keep `.canon/config.json` for store format,
schema versions, backend, and related store mechanics.
## Store records and commits
Records are stored in the SQLite database outside the Git worktree.
Database writes are not Git changes and must not be staged or committed.
The config, binding, and schema snapshots under `.canon/` are versioned
metadata and should be committed with code changes when they change.
A record edited by hand, outside the runtime, fails validation:
```
record revision tamper detected: .canon/records/.../rec-....md
```
Fix that by redoing the edit through `canon update` rather than by
hand-patching the file.
references/execute-mechanics.md
# execute mechanics
Full step-by-step mechanics. SKILL.md keeps the judgment; this file is the manual fallback and the record of every contract.
## Execute the focused effort
Requires `canon` and `orchestra` on PATH and a live
orchestra store. If missing,
follow [ensure-store.md](references/ensure-store.md) then `init` (if no goal
for the focus) and `tasks`. Follow
[kinds-and-focus.md](references/kinds-and-focus.md). Follow `verify`
after each task finishes (subagent return or inline).
**Single-writer:** only this parent may write via `canon`.
Subagents never write — including under any future `--read-only`
executor mode (that mode names what may be *read*; a subagent write
would race `--expected-revision`).
Task lifecycle is `planned -> in_progress -> done` (or `withdrawn`).
Orchestra moves a work-item to `in_progress` (step 4) and to `done`
(`verify`). The planner creates work-items.
`derived.ready` / `derived.wave` are engine-computed from `depends_on`
— never write them.
Each dispatch is recorded by the `in_progress` update of the
work-item (it carries `assignee` and `write_root`) and by a
`conductor:execution-report` (evidence verbatim). Write no
`conductor:assignment`. Executors take method / verify_command /
findings / constraints from `orchestra brief <task-slug>`. The brief
renders `## Orientation`: it quotes (verbatim, by id) work-item
Description/Approach, linked requirement text, design
Invariants/Assumptions, and named decisions. The dispatch prompt adds
territory and concurrency notes only. Do not paraphrase claims or
treat empty/legacy `criterion` as the lead claim.
Write a phase `score:position` only for a human-readable note. Phase
progress is derived from work-item states. The effort position still
changes at phase close.
## Steps
1. Run `orchestra handoff` if the handoff was not injected. Resolve
**focus**. Read `orchestra view plan --effort <focus>` and blocking
`continuity-question`s for that subject. Do not dispatch while a
blocking question is open on this focus. A question with `scope`
`plan-review:<phase-slug>` gates only that phase; clear on approve:
```bash
canon update --type score:continuity-question --id <question-id> \
--transition answered --expected-revision <revision>
```
Do not dispatch another effort's tasks.
Before planned ready work, re-dispatch retryable `in_progress`
items (same executor mode) — see
[retry-loop.md](references/retry-loop.md). Then continue with the
planned ready list.
2. Select dispatchable work-items (plan view omits `derived.ready`/`wave`):
```bash
canon list --type score:work-item --state planned \
--where payload.effort=<focus> --where payload.phase=<current-phase-slug> \
--where derived.ready=true
```
For `incidental`, drop `payload.phase` (it is `""`) and expect at
most one result. `current-phase-slug` is the `score:phase` for
this effort with `lifecycle_state` `in_progress` — never
`score:position` `scope`. If none exist, stop and point to
`tasks`. If several phases are `in_progress`, use the one
named in context; ask if none is named.
After plan review is answered and before the first wave, read
`## Landing` from the phase body:
```bash
canon get --type score:phase --id <phase-id>
```
When `## Landing` is present, ensure branch `phase/<phase-slug>`
from `main` and worktree `<repo>/.worktrees/<phase-slug>`:
```bash
git branch phase/<phase-slug> main
mkdir -p <repo>/.worktrees
git worktree add <repo>/.worktrees/<phase-slug> phase/<phase-slug>
```
When Landing is present, code writes only under the worktree and
store writes on the primary checkout (on `main`). `.canon`
stays on that primary checkout. Task commits exclude `.canon`.
When Landing is absent, a missing Landing section
stays in the current checkout (incidental too); do not create a
branch or worktree. When Landing is absent, execute does not
create a `task/<phase-slug>/<task-slug>` branch. When Landing is
absent, execute does not add a
`<repo>/.worktrees/<phase-slug>--<task-slug>` worktree.
3. Group results by `derived.wave`. Lower waves first; waves stay
serial. Re-run the step-2 `list` before each wave — wave numbers
can shift.
When Landing is present, at the start of a wave, execute
creates branch `task/<phase-slug>/<task-slug>` from the current
`phase/<phase-slug>` tip for every task in that wave except the
work-item that depends_on every other phase work-item. When Landing
is present, at the start of a wave, execute adds worktree
`<repo>/.worktrees/<phase-slug>--<task-slug>` checked out on that
task branch for every task in that wave except the work-item that
depends_on every other phase work-item. execute does not
create a task branch for the work-item that depends_on every other
phase work-item. execute does not add a task worktree for the
work-item that depends_on every other phase work-item. The
work-item that depends_on every other phase work-item is dispatched
in `<repo>/.worktrees/<phase-slug>` on `phase/<phase-slug>`.
Re-dispatch of a task other than the work-item that depends_on
every other phase work-item reuses branch
`task/<phase-slug>/<task-slug>`. Re-dispatch of a task other than
the work-item that depends_on every other phase work-item reuses
worktree `<repo>/.worktrees/<phase-slug>--<task-slug>`. Before a
re-dispatch continues, the parent merges `phase/<phase-slug>` into
the task branch when the task branch does not already contain the
phase tip. If that merge conflicts, leave it unresolved, open a
blocking continuity question on the effort, and do not start the
next wave (same conflict rules as wave end).
Create the branch and worktree only when they are missing, and only
for a task other than the work-item that depends_on every other
phase work-item. On re-dispatch, reuse them. Run the merge only
when the task branch does not already contain the phase tip:
```bash
git branch task/<phase-slug>/<task-slug> phase/<phase-slug>
git worktree add <repo>/.worktrees/<phase-slug>--<task-slug> task/<phase-slug>/<task-slug>
git -C <repo>/.worktrees/<phase-slug>--<task-slug> merge-base --is-ancestor phase/<phase-slug> HEAD \
|| git -C <repo>/.worktrees/<phase-slug>--<task-slug> merge phase/<phase-slug>
```
Read `payload.executor` on each ready task (`inline` | `subagent`;
missing/empty → `subagent`). If the wave disagrees, or any value is
other than those two, stop and name the tasks — do not spawn or
transition. Follow `## Approach` in the brief; do not ask the user
for an implementation recipe when it is present.
4. When the wave agrees, transition each task to `in_progress` and set
`assignee` (`inline` for inline; a short label for subagent) and
`write_root` in the same update. `write_root` is the executor's
write root. For a task other than the work-item that depends_on
every other phase work-item, it is
`<repo>/.worktrees/<phase-slug>--<task-slug>`. For the work-item
that depends_on every other phase work-item, it is
`<repo>/.worktrees/<phase-slug>` on `phase/<phase-slug>`. When
Landing is absent, it is the current checkout. Work-item
`payload.executor` is only the wave mode. Use
`--expected-revision` from `list`/`get`:
```bash
canon update --type score:work-item --id <id> \
--transition in_progress \
--expected-revision <revision> \
--payload '{"assignee":"<assignee>","write_root":"<write-root>"}'
```
Print the brief. It quotes the work-item `## Description` and
`## Approach`, each requirement by id, the phase design
`## Invariants` / `## Assumptions`, and each named decision. Write
no assignment record.
```bash
orchestra brief <task-slug>
```
Write territory and concurrency notes for the dispatch prompt. The
dispatch prompt names the write root. The dispatch prompt does not
tell the executor to avoid `git add -A`. Do not restate
`criterion`, `verify_command`, or findings — brief already has
those.
Unfrozen tdd tests can be written during execution. Record red through
`orchestra check` before implementation, then green. Require explicit
parent approval before changing method or oracle policy.
If any active acceptance is **oracle-backed** (non-empty `test_ids`
and `oracle_hashes`), list those frozen paths in the dispatch
prompt and forbid editing them. Pushback → oracle amendment path
below; never silently rewrite a frozen oracle. Add this section to
the dispatch prompt, and omit it when no acceptance is
oracle-backed:
```text
### Frozen oracle (do not edit)
Files listed in acceptance oracle_hashes for this task are frozen.
Do not edit them. Report proposed hash or test-id changes to the parent for oracle amendment approval.
For manifest claims:
An oracle hash or test-id change is a signed amendment in `.tuner/manifest.json`.
A non-zero exit means the acceptance is not done.
```
**Oracle amendment (parent only):** every frozen hash change requires an
approved `tuner:oracle-amendment` with hashes matching the green tree.
The parent creates or supersedes that record with the acceptance subject,
effort, phase, old_hashes, new_hashes, status approved, and Reason/Change.
Executors never create or approve these records. Do not replace acceptance
freeze fields. For manifest claims, Parent adds a signed amendment in `.tuner/manifest.json`, then:
```bash
orchestra verify verdict --cwd <repo-or-worktree> --at <revision> <claim-id>
```
`<claim-id>` is that claim's `id` in `.tuner/manifest.json`.
Exit 0 accepts; non-zero → acceptance not done; leave `in_progress`.
5. Dispatch by the shared `payload.executor`.
**`subagent`:** one `generalPurpose` subagent per task, parallel
within the wave. Give each only:
- repo path — that write root
(`<repo>/.worktrees/<phase-slug>--<task-slug>` for a task other
than the work-item that depends_on every other phase work-item;
`<repo>/.worktrees/<phase-slug>` on `phase/<phase-slug>` for that
work-item; current checkout when Landing is absent) — plus task
`subject`/title, `kind`, focus `effort`
- the output of `orchestra brief <task-slug>` — verbatim
- the territory notes from step 4, the frozen oracle paths when any
- kind instruction:
- `deliver` / `incidental` — implement (except verification task)
- `repair` — reproduce, observe, name root cause if found, then fix
- `evaluate` — run campaign; return metrics; do not "fix" unless
requirement / verify_command says so
- follow `## Approach`; do not ask for an implementation recipe
- verification task (depends_on every other phase work-item): run
phase checks; return `fail`; do not edit the tree
- return the evidence block below; never call `canon`
or edit `.canon/`
**`inline`:** this session implements with the same brief,
orientation, and kind instructions; still writes the
execution-report and runs `verify` once in step 7. Same
verification-task and Landing rules as subagent.
With Landing, after each task's code lands and before verify, the
parent does a commit per task so a passing check-run can carry a real
SHA. The per-task commit for a task other than the work-item that
depends_on every other phase work-item runs in that task worktree.
That per-task commit stages with `git add -A` excluding
`.canon`. That commit excludes `.canon`. Put that commit
SHA in evidence `revision`. A passing check-run for a task other
than the work-item that depends_on every other phase work-item
records that task's commit as its revision. When a task other than
the work-item that depends_on every other phase work-item has
nothing to commit, execute does not create an empty commit.
Skip when nothing to commit, no Landing, or the work-item that
depends_on every other phase work-item. Subject `type(scope):
summary` (`feat|fix|docs|refactor|test|chore`); body 1–2 sentences
naming the task slug.
```bash
git -C <repo>/.worktrees/<phase-slug>--<task-slug> add -A -- . ':!.canon'
git -C <repo>/.worktrees/<phase-slug>--<task-slug> commit -m "$(cat <<'EOF'
feat(<scope>): <summary>
Land <task-slug> so a passing check-run can carry a real SHA.
EOF
)"
```
Evidence block (subagent return or inline record):
```
subject: <task-slug>
kind: deliver | repair | evaluate | incidental
result: pass | fail | blocked | abandoned
revision: <git sha or "dirty">
evidence: <what was run>
observations: <repair/evaluate: what was seen>
root_cause: <repair, if known>
verdict: pass | fail | delta | inconclusive
metrics: <evaluate: baseline vs candidate>
claim: <evaluate/repair finding text, if any>
needs_human: <true/false — if the verdict needs a maintainer call>
attempted_action: <only if abandoned>
retry_when: <only if abandoned>
blocker: <only if blocked>
```
6. Mid-flight term changes (not status pings): message the subagent
directly (it cannot read the store) and record the amendment,
keyed to the work-item. Inline: record the same amendment and keep
implementing:
```bash
canon create --type conductor:assignment-amendment \
--subject "<task-slug>" \
--payload '{"work_item":"<task-slug>","effort":"<focus>"}' \
--body "## Correction
<the correction, as sent to the executor>"
```
7. When the task finishes, the per-task Landing commit (step 5) must
already exist before `verify`. Record the evidence block
verbatim — it is the record, not raw material to cherry-pick:
```bash
canon create --type conductor:execution-report \
--subject "<task-slug>" \
--payload '{"work_item":"<task-slug>","result":"<pass|fail|blocked|abandoned>","verdict":"<pass|fail|delta|inconclusive>","revision":"<git sha or dirty>"}' \
--body "<the evidence block, verbatim>"
```
Then run `verify` here. verify for a task other than the
work-item that depends_on every other phase work-item runs in that
task worktree. It derives investigation / finding /
check-run from this execution-report (not chat memory) and closes
or leaves `in_progress`. `tdd`/`check` results come from
`orchestra check` (verify runs it). Manual/review check-runs
and the suite check-run (`orchestra suite record`, subject
`<phase-slug>-suite`) stay parent writes.
When the acceptance claim is in `.tuner/manifest.json`, run
`orchestra verify verdict` before `done` (same command as step 4). Non-zero →
leave `in_progress`.
Do not supersede or re-derive readiness — dependents flip
`derived.ready` when a dependency reaches terminal success; the
next wave's `list` sees it.
8. At wave end, the parent merges each passing task branch of a task
other than the work-item that depends_on every other phase
work-item into `phase/<phase-slug>`. Run those merges in the phase
worktree `<repo>/.worktrees/<phase-slug>`. Those wave-end merges
run in task-slug order. The wave-end integration does not rebase
the task branch. The parent does not merge a task branch whose
check did not pass. Use `git merge` only.
```bash
git -C <repo>/.worktrees/<phase-slug> merge task/<phase-slug>/<task-slug>
```
When a merge between a task branch and the phase branch conflicts,
the parent leaves that conflict unresolved. When a merge between a
task branch and the phase branch conflicts, the parent opens a
blocking continuity question on the effort. Scope that question
`merge:<task-slug>`. When a merge between a task branch and the
phase branch conflicts, the parent does not start the next wave.
Do not abort the merge. When both tasks can keep their behavior,
edit the conflicted files in the phase worktree to keep both changes, stage them with `git add`
and run `orchestra wave resolve <phase-slug> <task-slug>`. When the
two tasks need competing behavior, leave the question open and ask
the user.
```bash
canon create --type score:continuity-question \
--subject "<focus>" \
--payload '{"owner":"user","blocking":true,"scope":"merge:<task-slug>"}'
```
Next wave only after every passing task branch in this wave has
merged cleanly. After the last implementation wave's
execution-reports, return to step 3 for the closing verification
task (do **not** write an integration-report before verification).
## Record versus bind
Techniques and audit may record an unbound evidence-observation. It
does not earn a manifest claim. Path: claim id → evidence-binding →
evidence-observation. `orchestra verify bind` writes the
evidence-binding; then `orchestra verify recheck` before treating the
claim as earned. Inspect with `orchestra verify trail`.
```bash
orchestra verify trail --cwd <repo-or-worktree>
orchestra verify bind --cwd <repo-or-worktree> \
--observation <evidence-observation-id> \
--claim <claim-id> --base <base-rev> --head <head-rev>
orchestra verify recheck --cwd <repo-or-worktree> --claim <claim-id>
```
## Do not
- Write a plan document as authority
- Let subagents write records (any executor mode) — store is single-writer
- Restate `criterion` / verify_command / findings in the dispatch prompt, or
paraphrase work-item / requirement claims — brief owns the quotes
- Write a `conductor:assignment`; the `in_progress` update carries
`assignee` and `write_root`
- Write a phase `score:position` for progress; write one only for a
human-readable note
- Skip `conductor:execution-report` and derive check-runs from chat memory
- Ask for an implementation recipe when `## Approach` is present
- Spawn a subagent for `inline`, or spawn when the wave disagrees on executor
- Dispatch when `derived.ready` is false, or another focus's work
- Write or recompute `ready`/`wave`
- Load the whole store; route by focus, then phase
- Close a phase whose phase-end gate does not hold (see phase-end.md)
- Write integration-report `pass` from a clean git merge alone, or write
it before closing verification / reviewer, or invent its body
- Call the phase complete (or merge) without a proof-packet at phase-head
when code or claims changed
- Merge without passing review at phase-head, or without required suite
at phase-head when `suite.gate` is `required`
- Waive / skip / override configured suite policy in `orchestra.toml`
- Let the reviewer call `canon` or write `.canon`
- Re-run the reviewer more than once after fix tasks for the same phase-end
- Fix-and-rerun inside the suite step (`required` → fix tasks + re-run at
new head; `advisory` → finding only)
- Create a branch or worktree without Landing; create a task branch or
task worktree for the work-item that depends_on every other phase
work-item; let code leave the worktree when Landing is present;
write `.canon` off the primary checkout or include it in a task
commit
- Skip the per-task commit when Landing is present and that task's
code changed; create an empty commit when there is nothing to commit
- Rebase a task branch, merge a task branch whose check did not pass,
resolve a task-branch merge conflict by any path other than
`orchestra wave resolve`, or start the next wave while that conflict
is unresolved
- Do not resolve a merge conflict outside `orchestra wave resolve`
- Do not push from phase close
- Tell the executor to avoid `git add -A`
- Let the verification executor edit the tree
- Reopen `done` — create a fix work-item and `depends_on` instead
- Re-dispatch after retry budget exhaustion without `scope: retry:<task-slug>`
- Skip the retryable `in_progress` pass
- Put a whole-suite command on a per-task `verify_command`
- Let an executor edit frozen oracle files or write
`tuner:oracle-amendment`; or `create`/`correct` a task check-run
with method `tdd`/`check` (those come from `orchestra check`). Suite
(`orchestra suite record`) and `manual`/`review` stay parent writes
- Let a subagent sign an amendment or write `test_ids` / `oracle_hashes`
## Do not (moved from SKILL.md)
- Re-dispatch after retry budget exhaustion without `scope:
retry:<task-slug>`; skip the retryable `in_progress` pass
- Put a whole-suite command on a per-task `verify_command`; let the
reviewer call `canon`
references/intent-qa.md
# Intent Q&A
Use this guide during specification and design work. Read relevant context
before you ask the user for information.
## Read
- Read the active phase, its prerequisites, and current effort context.
- Read the approved specification before design work.
- Read relevant code and system constraints before technical questions.
- Read existing decisions, constraints, and assessments that affect the phase.
Do not ask the user to repeat information already present in the current
records or code.
## Reflect
State the user's goal in plain terms. Separate known facts from assumptions.
Name the decisions that can change behavior, cost, scope, or recovery.
Ask an open question when a necessary fact is unknown. Offer concrete options
only when the user must choose between real alternatives.
## Ask
Ask one focused question at a time. Say why the answer changes the result.
Keep choices distinct and include the practical trade-off for each.
Do not ask about implementation details before you check the code or current
technical facts. Research unstable or unfamiliar facts before asking the user
to choose a preference.
## Test answers
Check each answer against the goal, current records, constraints, and earlier
answers. Name conflicts and ask about the smallest unresolved choice.
Preserve settled choices unless the user changes them.
Do not infer approval from silence, a partial answer, or a request to continue.
Ask for approval of the complete specification or design before recording it.
## Present once
After the open choices are settled, present the complete proposed artifact.
State its scope, assumptions, invariants, risks, and unresolved items. Ask for
approval or explicit delegation to record it.
After the user approves, write only the artifact owned by the current step.
Record the matching workflow review only when the user explicitly approves or
delegates. Do not create work-items from either discussion step.
references/kinds-and-focus.md
# Kinds and focus
Shared rules for every orchestra skill. Do not invent extra skills for
bugs, one-offs, or evals.
## Kinds
`kind` is `deliver` | `repair` | `evaluate` | `incidental`. Put it on
`score:effort` and each `work-item`. Missing `kind` means
`deliver`.
| Kind | Unknown | Done | Records |
|---|---|---|---|
| `deliver` | how | change + binary check | work-item + acceptance + check-run |
| `repair` | what is wrong | cause + repro gone | those, plus observation / finding |
| `evaluate` | whether it holds / which is better | campaign result | check-run if binary; finding if comparative or inconclusive |
| `incidental` | usually nothing | change landed | none, or one work-item (see below) |
`acceptance.method` stays `tdd` | `check` | `manual`; `verify_command`
holds the literal command that backs it (empty string for a `manual`
check with no script). Do not stuff a metric delta into
`check-run.result`. Use `tuner:finding` (`claim`, `basis`,
`invalidated_when`, `needs`).
`executor` on a work-item is `inline` or `subagent`. Every task in a
wave uses the same executor. Missing `executor` means `subagent`.
The phase body includes a `## Landing` section with branch
`phase/<phase-slug>`, worktree
`<repo>/.worktrees/<phase-slug>`, base `main`. When Landing is
present and the phase gate holds, commit the phase branch from the
phase worktree. Then run `orchestra land --phase <phase-slug>`. Land
runs `orchestra gate` first and runs the land adapter only when the
gate holds. The Landing section names branch, worktree, base and repo
only. `orchestra.toml` `[land]` and `[suite]` configure the adapter and
the suite. Merge stays human. On a non-zero exit, stop and ask.
Incidental work has no Landing section. A phase body that omits
Landing is not ready for plan review.
## Focus
A **live** goal is a `score:effort` in lifecycle `active` whose
`payload.status` is not `closed` (missing means open).
### Closing and reopening
`status` (`open` | `closed`) on `score:effort` and `score:position`
says whether an effort is live. It is a payload field, not the
lifecycle. Closing and reopening both `supersede` the effort's goal and
position with the new `status`; `supersede` merges the payload, so the
other fields carry over.
- **Close** only when the user says no more phases follow.
`run` asks when an effort's last phase is done. An effort
whose phases and tasks are all done is "finished" on the dashboard,
but it stays open until the user closes it.
- **Reopen** when work returns to a closed effort: supersede its goal
and position with `status: open`, then add the phase. Never create a
second goal with a closed effort's subject.
Closed goals do not show in views. Find them with:
```bash
canon list --type score:effort --state active --where payload.status=closed
canon supersede --type score:effort --id <goal-id> \
--expected-revision <revision> --payload '{"status":"open"}'
canon supersede --type score:position --id <position-id> \
--expected-revision <revision> --payload '{"status":"open"}'
```
Focus is a **subject string**, not a record. Name it (from `engage`, the
user, or the only live `score:effort` subject). Then:
- Read `orchestra handoff --effort <focus>` and the focus's phases in
`orchestra view plan --effort <focus>`.
- Ignore other live goals. Do not supersede `score:effort` or
`score:position` that belongs to another effort.
- Task-scoped records (`work-item`, `acceptance`, `check-run`,
`decision`, `failed-attempt`, `investigation-observation`, `finding`,
`assignment-amendment`, `execution-report`) use
`subject` = task slug and `payload.effort` = focus. Skills write no
`assignment`; the `in_progress` work-item update carries `assignee`
and `write_root`.
- Goal, the effort position, and continuity-question use `subject` =
focus. A phase has its own position only for a note a person must
read: `subject` = phase slug, `scope` = `phase`, `payload.effort` =
focus. Phase progress is derived from work-item states. Each chat
writes only its own phase's position; the effort position changes
when a phase closes.
An effort is a product area or objective, not one ask. New work in
an area a live goal already covers is a new phase of that effort. A
new effort is a new subject only when no live goal covers the area.
Create its goal/position. Leave the others active.
Hierarchy inside an effort:
- **milestone** (`score:milestone`) — optional time-bounded outcome
that groups phases (e.g. cutover, harden). Payload: `title`,
`ordinal`, `effort`. Not a focus subject; focus stays the effort.
- **phase** (`score:phase`) — one settle → plan → execute → verify
loop. Optional payload `milestone` references a milestone subject.
Phase `ordinal` is effort-scoped (not reset per milestone).
Skills stay phase-scoped. A milestone is a grouping and done-gate for
its phases, not a second chat focus.
## Incidental
- Fits this chat and is not an interrupt of another live effort: **no
records**. Do the work in this session.
- May span chats, or it interrupts a live phase: one `work-item` +
`acceptance`, `kind=incidental`, `phase=""` (no phase record exists
for incidental work; canon checks a non-empty `phase` against
real `score:phase` subjects and skips an empty string), `effort` = a **new** subject (not the interrupted effort).
Work-item `subject` may equal that effort slug when there is only one
task. Do not supersede the main goal.
## Needs-you clears
Human-dismissible Needs-you kinds are `blocking-question`,
`open-question`, `needs-human`, and `unsigned-check` only (not
loop-route, integration, or merge-branch). When the user settles one
in an agent session, the parent session clears that source at the
event — the same CLI outcomes the dashboard dismiss uses. Do not keep
a separate dismiss cache.
| Kind | Source | Clear at the event |
|---|---|---|
| `blocking-question` / `open-question` | `score:continuity-question` still open | `update --transition answered` |
| `needs-human` | active `tuner:finding` with `needs` `human` | `update` with `needs` `none` |
| `unsigned-check` | latest `method=manual` `tuner:check-run` with empty `signed_by` | `correct` setting `signed_by` |
```bash
canon update --type score:continuity-question --id <question-id> \
--transition answered --expected-revision <revision>
canon update --type tuner:finding --id <finding-id> \
--expected-revision <revision> \
--payload '{"needs":"none"}'
canon correct --type tuner:check-run --id <check-run-id> \
--payload '{"signed_by":"<signer>"}'
```
Findings advertise a supersedes relationship but have no superseded
lifecycle state, so clear with `update` (same as dashboard dismiss).
Signer identity comes from config, env, or a short prompt.
## Writing rules
- **Capture at the event.** Write the record when the decision,
observation, or commitment happens. Do not batch writes for session
end or write them from memory.
- **One writer per store.** Only the parent session calls `canon` in
any form that writes. Subagents return evidence in their response
text and never call `canon` or edit `.canon/`. This holds for
every executor mode, including a read-only one: that mode names what
an executor may read, it does not make the store multi-writer.
- **Views are derived.** Records are the authority. Render views with
`orchestra handoff`, `orchestra view plan|status|verification`, and
`orchestra brief <work-item>`. They print to stdout and write no
files. A view may lag a record; read the record before you act on a
claim.
- **Validate before finishing.** Run `canon validate` and fix every
error. The Stop hook runs the same check and blocks on new errors.
- **Follow the lifecycle.** `supersede` a `current` record (new id);
never `update` it to `superseded`. Event records stay `recorded`;
`correct` writes a successor. A stale `--expected-revision` is a
rejected write: re-read, then retry. Never hand-edit a record file.
- **Read by relevance.** Route by focus, then phase. Never bulk-read
the store.
references/record-mechanics.md
# Record mechanics
Only the parent session writes the shared store. Use `canon` and
`orchestra`; never edit record files by hand.
## Plan records
- Put phase requirement ids in each `deliver` or `repair` work-item's
`requirements` array. Keep each id atomic.
- Put one acceptance on each requirement it verifies. Use one acceptance with
a `requirements` array only when one check proves every listed requirement.
- Put task dependencies in `depends_on` as work-item subjects. Create the
prerequisite before its dependents.
- Give each work-item `## Description`, `## Approach`, `executor`, `size`, and
`estimate_minutes`. Every wave uses one executor type.
- Put all work-items and acceptances in one ordered NDJSON batch. Create the
phase verification task last. It depends on every other phase task.
- Run `canon validate` after applying the batch.
## TDD and checks
An acceptance names the literal `verify_command`. `orchestra check` writes
runner evidence for `tdd` and `check`. Never create those check-runs by hand.
For `tdd`, record a failing run before the passing run. Close-batch needs the
runner-produced red and green ids. The green revision must equal or descend
from the red revision. A dirty red also needs its diff hash.
Frozen-oracle acceptances require assertion-level red and matching hashes at
green. Never edit frozen oracle files or invent freeze fields.
## Execute and close
`orchestra wave start` selects the lowest ready wave. It writes `in_progress`,
`assignee`, and `write_root`. Dispatch only tasks whose derived `ready` is
true. Return evidence as JSON; the parent writes records.
`orchestra task land <task> --evidence <file>` commits the task worktree,
writes its execution report, and runs active acceptance checks. Use
`orchestra close-batch` for the verified close request, then `canon apply`.
Never reopen a done task. Create a dependent fix task instead.
End each passing wave with `orchestra wave end`. Do not merge branches by
hand. Keep check-runs, findings, and execution reports as separate evidence.
references/retry-loop.md
# Retry loop
Parent-only. Run at the start of each dispatch cycle, before the
planned ready `list` in execute step 2. Evidence escalation
still chooses `level` / `next`; the budget only decides when to stop.
## Re-dispatch selection
```bash
canon list --type score:work-item --state in_progress \
--where payload.effort=<focus> --where payload.phase=<current-phase-slug>
```
For each result, load the latest `conductor:assessment` (structured) or
latest `tuner:check-run` (simple). A written non-verified assessment
wins over derivation. Retry when assessment `next` is
`execute`, or check-run `result` is `fail`. Skip a task whose executor
is still running for its current dispatch, or that has an open
blocking `continuity-question` with `scope` `retry:<task-slug>`.
Re-dispatch with the same `payload.executor` as the prior wave
(`inline` or `subagent`; missing means `subagent`). Do not change mode.
## Budget (hard backstop)
Defaults (override in the phase body's run facts):
- `retry_max_redispatches`: 2 re-dispatches per task
- `retry_time_multiplier`: 2 (stop when cumulative executor time
≥ 2× `estimate_minutes` when set; count or time, whichever first)
- `retry_max_fix_tasks`: 3 fix work-items created for the phase
Omit a key → use the default. If cumulative time cannot be computed
from execution-report timestamps, use re-dispatch count
only. `attempts` is that count (absent → 0).
When a per-task or per-phase fix-task budget is exhausted, do not
re-dispatch. Open Needs you and stop selecting it:
```bash
canon create --type score:continuity-question \
--subject "<focus>" \
--payload '{"owner":"user","blocking":true,"scope":"retry:<task-slug>"}'
canon create --type tuner:finding \
--subject "retry-<task-slug>" \
--payload '{"claim":"retry budget exhausted for <task-slug> after <attempts> re-dispatches","basis":"<attempts, check-runs, assessments>","invalidated_when":"human raises the budget or withdraws the task","effort":"<focus>","needs":"human"}' \
--body "## Evidence
<attempts, failing check-runs, latest assessment>
## Consequence
Dispatch of this task stops until the human answers.
## Follow-up
Raise the run-fact budget, withdraw the task, or choose another approach."
```
When the user answers or clears the finding, clear at the event
(kinds-and-focus, Needs-you clears):
```bash
canon update --type score:continuity-question --id <question-id> \
--transition answered --expected-revision <revision>
canon update --type tuner:finding --id <finding-id> \
--expected-revision <revision> \
--payload '{"needs":"none"}'
```
## Amendment, attempts, re-dispatch
For each retryable task still inside budget: record an
`assignment-amendment` keyed to the work-item whose `## Correction`
quotes the failing check-run evidence (runner output tail) and the
assessment's `## Reason` when present; set `attempts` to prior+1
(absent → 0, so first re-dispatch writes `1`) in a work-item update
that also carries `assignee` and `write_root`. Write no new
`conductor:assignment`.
Dispatch as in execute steps 4–5 (same executor mode), with the
brief and territory notes. Work-item stays `in_progress` — never
reopen `done`.
```bash
canon create --type conductor:assignment-amendment \
--subject "<task-slug>" \
--payload '{"work_item":"<task-slug>","effort":"<focus>"}' \
--body "## Correction
Re-dispatch after failure.
## Failing check-run
<runner output tail from the failing check-run>
## Reason
<assessment ## Reason when present, else omit>"
canon update --type score:work-item --id <id> \
--expected-revision <revision> \
--payload '{"attempts":1,"assignee":"<assignee>","write_root":"<write-root>"}'
```
Then dispatch with that mode through execution-report + `verify`.
## Fix tasks (closing verification)
When the closing verification task fails and the cause is another
task's code, create a new fix work-item in the same phase — never
reopen `done`. The fix has no `depends_on`. Approach comes from the
failure; acceptance is the failing check. Then add the fix's subject to
the verification task's `depends_on` (send the full array) so
`derived.ready` re-gates verification. Count against `retry_max_fix_tasks`. If that budget is
exhausted, use the budget-exhaustion Needs-you path above
(`scope: retry:<verification-slug>` or `retry:<fix-slug>`) instead.
```bash
canon create --type score:work-item \
--subject "fix-<failing-area>" \
--payload '{"title":"Fix <failing area>","phase":"<current-phase-slug>","kind":"deliver","assignee":"","effort":"<focus>","executor":"<same mode as phase wave>","size":"S","estimate_minutes":8,"requirements":["<id>"],"decisions":["<decision-subject>"]}' \
--body "## Description
Fix the failure that blocked closing verification.
## Approach
<from the failing check-run / node ids>"
canon create --type score:acceptance \
--subject "fix-<failing-area>" \
--payload '{"method":"tdd","oracle_policy":"none","phase":"<current-phase-slug>","effort":"<focus>","verify_command":"<command>","requirement":"<id>"}'
canon update --type score:work-item --id <verification-work-item-id> \
--expected-revision <revision> \
--payload '{"depends_on":["<existing-dependency-slug>","<fix-work-item-slug>"]}'
```
Never transition a `done` work-item back to `in_progress` or
`planned`. Fix tasks stay in the current phase.
references/reviewer.md
---
name: reviewer
description: >-
Read-only phase-end reviewer for orchestra. Compares phase specs,
acceptances, invariants, and the phase diff to the tree. Returns structured
PASS/NEEDS_WORK. Invoked by run after closing verification and
before merge.
mode: subagent
tools: Read, Grep, Glob, Bash
deny: Write, Edit, NotebookEdit
store_writes: false
bash: read-only
---
You are the orchestra phase-end reviewer. You grade the phase against its
stated intent, not against the builder's self-reports.
## Tool restrictions
Allowed tools only: **Read**, **Grep**, **Glob**, **Bash**.
Configured **without Write** and **without Edit** (or any write/mutate file
tool). Do not call Write, Edit, NotebookEdit, or equivalent.
Bash is read-only in practice:
- Allowed: `git diff`, `git show`, `git log`, `git status`, listing, `rg`/`grep`,
reading files via shell when needed.
- Forbidden: any mutating command (`rm`, `mv`, `cp` into the tree, `git add`,
`git commit`, `git checkout` that changes files, redirects that write,
`sed -i`, package installs, chmod, etc.).
- Forbidden: `canon` and any write into `.canon/` (records,
log, history). Reviewer writes **no store records**. The parent session is
the single writer.
If a host cannot hard-block Write/Edit, the prompt forbid still applies; refuse
any request to mutate the tree or store. Under a host with a read-only or
explore-style subagent mode, use that mode; otherwise this prompt is the
restriction.
## Input contract
You receive only:
- Work-item titles, descriptions, and Approach goals
- Acceptance criteria
- Structured requirements / invariants (for structured work)
- `git diff <base>..<phase-head>` and read access to the tree at phase head
You must **not** use or request:
- execution-report bodies
- check-run results
- assessments
- assignment notes or builder self-grades
If the brief contains excluded material, ignore it and note that under
`integration.assumptions`.
## What to check
Compare intent (specs, acceptances, invariants) to the phase diff and tree:
- **spec-gap** — description/requirements promise more than acceptances or
delivered code cover
- **behavior-bug** — delivered code contradicts stated requirements
- **missing-test** — acceptance/`verify_command` claims unbacked by tests
visible in the diff/tree
- **invariant-violation** — design invariants broken by the change
Do not reopen `done` tasks; gaps become findings for new fix tasks (parent
creates them). Severity: `blocker` | `major` | `minor` | `judgment`
(`judgment` → parent may set `needs: human`).
## Output schema
Return **only** this structured block (YAML-like). No prose outside it.
```
verdict: PASS | NEEDS_WORK
findings:
- task: <work-item subject or "phase">
kind: spec-gap | behavior-bug | missing-test | invariant-violation
expected: <what specs/acceptances/invariants require>
observed: <what the diff/tree shows>
severity: blocker | major | minor | judgment
blocking: true | false
requirement: <agreed requirement or invariant the change violates>
trigger: <condition under which the violation shows>
consequence: <what breaks when it triggers>
escape: <missing-test only: a regression that passes every existing check>
integration:
interfaces: <what landed and how pieces connect>
assumptions: <assumptions you relied on>
invariants: <invariant checks performed and outcome>
conflicts: <conflicts or empty>
```
Rules:
- Every finding carries `blocking`. Set `blocking: true` only when you can fill
`requirement`, `trigger` and `consequence` (and `escape` for `missing-test`).
A finding that lacks one is advisory: set `blocking: false`.
- A `judgment` finding is for a choice that changes what was agreed. It always
blocks and needs no basis fields.
- `verdict: PASS` when no finding is blocking. A `PASS` may list advisory findings.
- `verdict: NEEDS_WORK` when any finding is blocking. Orchestra derives the final
verdict from the findings and ignores a verdict line that disagrees.
- Always fill `integration`; parent copies it into the integration-report.
- Do not invent check-run or store record IDs. Do not write records yourself.
references/verification-policy.md
# Verification method and oracle policy
Choose `method` separately from `oracle_policy`. Record both choices during planning.
| Method | Oracle policy | Evidence needed to close |
|---|---|---|
| `tdd` | `none` | Runner-produced red before runner-produced green |
| `check` | `none` | Passing runner check |
| `tdd` | `frozen` | Assertion-level red, green, and matching frozen hashes |
| `check` | `frozen` | Green and matching frozen hashes; no red required |
| `manual` | `none` | Human sign-off |
`manual` with `frozen` is invalid. An approved oracle amendment can authorize hash changes.
Manifest claims also retain their separate verdict and recheck gates.
## Select and record
Prefer `tdd` for behavior where a failing test helps define the contract.
Prefer `check` for documentation, packaging, and final verification.
Select `frozen` when independent tests against a stable interface justify the authoring cost.
Bug reproductions and compatibility contracts are good candidates.
Do not select frozen oracles for every deliver or repair task automatically.
A phase can set `oracle_policy` to `none` or `frozen`. The default is `none`.
An acceptance can override that default. Stamp the resolved `oracle_policy` on every new acceptance.
A phase default is a planning convenience; explicit acceptance policy fixes the choice for execution.
Existing acceptance freeze metadata still selects `frozen` when explicit policy is absent.
Never remove existing hashes or set `none` to bypass an existing freeze.
Reject partial freeze metadata, `none` with freeze metadata, and `frozen` without complete metadata.
An ordinary acceptance has `oracle_policy: none` and omits `test_ids` and `oracle_hashes`.
Its tests need not exist during planning. An executor writes unfrozen TDD tests during execution,
records red through `orchestra check`, implements the behavior, and records green.
An import or collection failure does not prove that an assertion detects incorrect behavior.
For a new API, create the minimum importable interface and confirm a behavior failure before implementing that behavior.
## Selected frozen acceptances
Skip oracle authoring when no acceptance selects `frozen`.
Otherwise use one independent oracle-author for only the selected frozen acceptances.
The author receives requirement text and the method, not implementation hints.
For frozen `tdd`, require assertion-level red before freezing.
For frozen `check`, tests can pass when authored; red is not required.
Create the acceptance with its policy, test ids, and hashes together.
Do not silently change selected policy when authoring cannot meet its contract.
## Changes during execution
The parent remains the only store writer. Require explicit parent approval before changing an acceptance's method or oracle policy.
The executor reports a proposed change and its reason. It does not weaken the verification contract itself.
Frozen file changes use the existing oracle amendment approval path.
Every frozen hash change requires a parent-approved `tuner:oracle-amendment` record, including changes to manifest claims.
The parent creates or supersedes that record with the acceptance subject, effort, phase, old hashes, new hashes, and approval reason.
Close-batch accepts approved `tuner:oracle-amendment` records whose new hashes match the green tree.
For manifest claims, the parent also uses the signed manifest and verdict path.
Unfrozen tests can change during implementation, but the declared TDD red-first contract still applies.
SKILL.md
---
name: execute
description: >-
Dispatch ready work-items within the selected phase scope and land their
evidence. Use when the workflow routes to execute.
---
# Execute tasks
Requires `canon` and `orchestra` on PATH. Follow
[ensure-store.md](references/ensure-store.md),
[kinds-and-focus.md](references/kinds-and-focus.md), and
[record-mechanics.md](references/record-mechanics.md). Follow
[retry-loop.md](references/retry-loop.md) for interrupted work and
[execute-mechanics.md](references/execute-mechanics.md) for task dispatch.
Follow [verification-policy.md](references/verification-policy.md) when
checking frozen oracle evidence. All frozen changes require a parent-approved oracle amendment.
For manifest claims, follow the signed manifest and verdict path in the verification policy.
## Own
- Dispatch only ready work-items in the requested phase scope.
- Record execution evidence through task landing.
- Integrate passing task branches at each wave boundary.
- Stop after the selected execution step. Verification stays separate.
## Steps
1. Resolve the focus and selected phases from the handoff. Read
`orchestra view plan --effort <focus>` and blocking questions for that
effort. Do not dispatch another effort or work blocked by an open plan
review. Retry eligible `in_progress` tasks first.
2. Run:
```bash
orchestra wave start <phase-slug>
```
Dispatch only the lowest ready wave. Stop if executors disagree, no task is
ready, or a task branch conflicts while refreshing the phase tip.
3. Follow each task brief verbatim. A subagent receives only its assigned
write root, brief, scope, constraints, frozen oracle paths, and kind
instruction. Subagents return evidence as JSON. They never write the store
or `.canon/`. Inline work follows the same boundary.
4. Land each task with `orchestra task land`. It commits the task branch,
records the report, and runs active acceptance checks. On a non-zero result,
stop and follow verify; do not merge that branch.
5. Run `orchestra wave end <phase-slug>`. Do not resolve merge conflicts or
merge task branches by hand. A merge conflict opens a blocking question;
leave it unresolved and stop.
When tasks need competing behavior, leave the question open and ask the user.
6. Continue ready waves only while the selected operation includes execute.
After the last passing wave, report what landed and hand off to verify.
## Do not
- Dispatch when `derived.ready` is false
- Recompute wave numbers or expand selected phase scope
- Write execution reports from chat memory
- Close tasks directly or reopen a done task
- Edit frozen oracle files or create runner check-runs by hand
- Resolve a merge conflict outside `orchestra wave resolve`
- Run reviewer, suite, phase gate, proof packet, or phase closure here