agentic-team 6.1.0 → 6.2.0

package/template/.orchestra/stacks/_repo/setup.sh

@@ -507,7 +507,7 @@ jobs:
       # One script, not a second copy of these steps. It carries the
       # locale, the Sentry opt-out, the JDK check maestro needs and the
       # Release/--no-bundler reasoning — see the file. Anyone can reproduce a
-      # red e2e by running it, and the orchestrator's own CI runs the same
+      # red e2e by running it, and the agentic-team repo's own CI runs the same
       # thing rather than a paraphrase of it.
       - name: e2e
         run: ./e2e-ios.sh
@@ -1078,12 +1078,15 @@ fi
 # URL design into .fetched/, and the capture the PR shows lands in .captures/.
 # Committed, both of them: gh cannot upload an image, so a screenshot that is
 # not in the branch cannot appear in a pull request.
-mkdir -p designs/.captures designs/.fetched
+mkdir -p designs/.captures designs/.fetched designs/.reports
 # git does not track an empty directory, so without these the two folders
 # vanish on the next clone and the first phase with a design has to invent a
 # location — which is how two of them end up disagreeing.
 : > designs/.captures/.gitkeep
 : > designs/.fetched/.gitkeep
+# Machine output of a comparison is regenerated from the images and never
+# committed; one project committed ~100k lines of JSON reports here.
+printf '*\n!.gitignore\n' > designs/.reports/.gitignore
 cat > designs/README.md <<'MD'
 # designs
 
@@ -1093,7 +1096,8 @@ The source of truth for any screen this repo builds.
 designs/
 ├── <screen>.png     the design. mirrors the screen structure.
 ├── .fetched/        a design given as a URL, fetched once when the phase starts
-└── .captures/       what was actually built, so a pull request can show both
+├── .captures/       what was actually built, so a pull request can show both
+└── .reports/        a comparison tool's output — regenerated, never committed
 ```
 
 A phase points at one with `design:` in its frontmatter — a path in here, or a

package/template/.orchestra/stacks/mobile-expo/setup.sh

@@ -318,7 +318,7 @@ yarn biome check --write . >/dev/null 2>&1 || true
 # ── e2e, as a script rather than only as CI steps ─────────────────────────
 # The workflow used to carry the build and the maestro run inline, which made
 # it unrunnable anywhere else: nobody could reproduce a red e2e locally, and
-# the orchestrator's own CI could only test a *copy* of those steps. A copy
+# the agentic-team repo's own CI could only test a *copy* of those steps. A copy
 # that drifts proves nothing. One script, called by both.
 cat > e2e-ios.sh <<'E2E'
 #!/usr/bin/env bash

package/template/CLAUDE.md

@@ -48,7 +48,7 @@ Role IDs: orchestrator, product-manager
 
 - Two-terminal model: PM plans in one terminal, lead executes in another
 - Each role writes only to its ownership scope (defined in role file)
-- Rules (`.claude/rules/*.orchestra.md`) auto-loaded. Skills loaded per phase.
+- Rules (`.claude/rules/*.orchestra.md`) auto-loaded, except those with `paths:` frontmatter, which load with their files and are read where named. Skills loaded per phase.
 - **PROTECTED:** Non-Orchestrator roles NEVER modify `.orchestra/roles/`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.orchestra/stacks/`, `.orchestra/trackers/`, `.orchestra/scripts/`, `.claude/agents/`, `.claude/hooks/`, `.claude/rules/*.orchestra.md`, `.claude/skills/*/SKILL.md`, `.claude/commands/orchestra/`, `CLAUDE.md`, or `docs/`.
 
 <!-- /orchestra -->

package/template/agents/lead.md

@@ -12,6 +12,12 @@ You NEVER implement code yourself.
 
 ## Startup
 
+Some rules load only when an agent touches the files they govern — `paths:`
+in their frontmatter — so an engineer is not handed the tracker or the
+pull-request rule on every call. Those paths match from the project root, and
+a sub-agent in a worktree does not trigger them, so wherever this file names a
+rule, read it rather than assume it is loaded.
+
 | Command | Behavior |
 |---------|----------|
 | `/orchestra:start` | Asks user at approval gates |
@@ -41,8 +47,8 @@ When started:
    severity scale nobody defined, and went nine rounds on one phase.
 3. Read `.orchestra/README.md` for orchestration rules.
 3b. Read `tracker.provider`. If it is not `none`, the tracker owns the
-   requirements and this changes where you read work from — see
-   `.claude/rules/tracker-authority.orchestra.md`.
+   requirements and this changes where you read work from — read
+   `.claude/rules/tracker-authority.orchestra.md` now.
    - Fetch each task once, at the start of the run, into
      `.orchestra/milestones/<slug>/.cache/`. That directory is gitignored and
      is not authority after the run — it exists so a run that started does not
@@ -55,15 +61,14 @@ When started:
    - Read each to check Status field
    - `status: in-progress` → resume | `status: planning` → start
    - `status: failed` → do NOT silently skip. Report it to the user with the
-     recorded reason from context.md, and ask whether to retry or move on.
+     recorded reason from `journal.md`, and ask whether to retry or move on.
      In `--auto`, skip it but list it in the final report.
    - all `done` → report complete
-6. If milestone scope spans 3+ directories or 20+ files, launch a scout sub-agent (`subagent_type: engineer-low`, `model: {pipeline.model}`):
-   - Scan project structure within milestone's phase scopes
-   - Return max 30-line map: `path/file — one-line description`
-   - Write map to context.md under `## Codebase Map`
-   - For smaller scopes, skip — sub-agents can explore directly.
-7. Begin execution loop.
+6. Begin execution loop: one milestone agent per milestone — see Milestone
+   Agent Delegation. Phase work never starts in this session:
+   `.claude/hooks/enforce-role.sh` refuses an `engineer-*`, `reviewer` or
+   `re-reviewer` launched from it, because one run kept two milestones here
+   and grew to 738 calls and a 925k-token context.
 
 ## Pipeline Selection
 
@@ -154,7 +159,7 @@ their content into the prompt. This eliminates sub-agent startup Read calls.
 Cache skills content in lead context — don't re-read for consecutive
 phases with the same skills.
 
-1. Read skill files from phase `.claude/skills/{name}/SKILL.md` → skills_content (skip already-read skills)
+1. Read skill files from phase `.claude/skills/{name}/SKILL.md` → skills_content (skip already-read skills). A name with no `SKILL.md` is not installed for this project's platforms: say so in the phase result and go on without it — never improvise its content
 2. Read phase file → phase_content
 3. Extract verification commands from config.yml (read once at startup, reuse)
    Determine `{app_dir}` from the phase `## Scope` — the app directory its
@@ -196,7 +201,8 @@ same identity runs consecutive phases), dynamic content last.
 
 ```
 You are executing a phase for Orchestra lead.
-Rules from `.claude/rules/*.orchestra.md` are automatically loaded.
+Rules from `.claude/rules/*.orchestra.md` are loaded for you, except those
+that load with their own files; any rule this prompt names, read yourself.
 
 **Verification (run in this order, stop at first failure):**
 Working directory: {app_dir}
@@ -244,7 +250,8 @@ not a difference to split.
 {codebase_map}
 
 **Previous phase summary:**
-{previous_phase_result_summary — concise summary of decisions and artifacts
+{previous_phase_result_summary — the output of `context.mjs live <m>` (open
+decisions only) plus a concise summary of the artifacts
 that affect this phase. Omit for first phase.}
 
 ## Your Task
@@ -259,7 +266,7 @@ that affect this phase. Omit for first phase.}
 4. Design parity — only when a **Design** section is present above.
    Render the screen, capture it, and compare against the design across
    layout and spacing, typography, colour, component states and content.
-   Fix every blocking discrepancy and repeat. Follow
+   Fix every blocking discrepancy and repeat. Read and follow
    `.claude/rules/design-parity.orchestra.md` — it defines what blocks, how
    to capture on this platform, and where the capture is written.
    Reading the code is not a comparison. If you cannot produce a capture, say
@@ -359,9 +366,11 @@ When generating the identity block, use these domain-specific priorities:
      simulator in this session" is an honest unverified. "Close enough" is not
      a reason and is sent back.
   1. Lead commits
-  2. Update context.md: set phase `done`, add commit hash + files_changed, append decisions from notes
+  2. Record it: `context.mjs phase <m> <phase> done "commit: … | files: …"`,
+     then `decide` / `journal` for what the sub-agent's notes say — see
+     Context Persistence
 - If **failed** (verification failed after max retries):
-  1. Update context.md: set phase `failed`, add error summary + last-error + retry count
+  1. `context.mjs phase <m> <phase> failed "error: … | retries: …"`
   2. Decide: retry with new sub-agent or escalate to user
 
 **Note:** Lead owns commit only. Sub-agents own implementation + verification.
@@ -403,7 +412,9 @@ Unless config says `review: skip`:
 ### `pr` mode
 
 1. Open the pull request first — see Delivery below.
-2. Call the reviewer sub-agent with the PR number. It posts **one review**
+2. Call the reviewer with the PR number — `subagent_type: reviewer` for the
+   first round, at `high`, and `re-reviewer` for every round after, at
+   `medium`. It posts **one review**
    with each finding attached to the line it is about, as the authenticated
    user, and labels the PR with its verdict. Every round is a **new** reviewer
    launch whose prompt carries a line
@@ -416,8 +427,8 @@ Unless config says `review: skip`:
    are this phase's entry in `.orchestra/.sessions/review-rounds.json`; read
    it there after a restart rather than from memory. After **every** review,
    whatever its verdict, record each `[suggestion]` comment it left: a
-   `tech_debt` task with a provider, a line under `## Tech debt` in
-   `context.md` with `tracker.provider: none`. A later round
+   `tech_debt` task with a provider, `context.mjs decide <m> tech_debt` with
+   `tracker.provider: none`. A later round
    need not repeat it, so one not recorded now is lost.
 3. **`review:approved`** → the task is done; stop for the human, or
    squash-merge under `--auto`.
@@ -445,7 +456,10 @@ Unless config says `review: skip`:
    The verdict is a label rather than a review state because the author cannot
    approve their own pull request — and a label is readable after a crash. A
    run that dies mid-cycle asks the PR what state it is in instead of guessing.
-5. Re-review the same way. Max rounds: `thresholds.stuck_retry_limit`, and
+5. Re-review with `re-reviewer`. Its prompt names the range — the PR head the
+   last review saw to the head the fix pushed — and tells it to read
+   `.claude/rules/pull-request.orchestra.md` for the query that lists the
+   open threads. Max rounds: `thresholds.stuck_retry_limit`, and
    the hook refuses the launch past it. When the last allowed review still
    requests changes, the user decides, not you: give them its open Blocking
    and Important findings and stop. Under `--auto`, set the task `blocked`
@@ -461,7 +475,9 @@ The engineer answers the review, not you. Its context is the code, the diff
 and the thread — all on the pull request, which is why a fresh one can answer
 it and you cannot answer it from a summary.
 
-The commands are in `.claude/rules/pull-request.orchestra.md`.
+The commands are in `.claude/rules/pull-request.orchestra.md`; read it before
+the first pull request, and tell every fix-round engineer to read it before
+it answers a thread.
 
 ## Delivery
 
@@ -477,14 +493,16 @@ which has always said one task one PR. A milestone-wide PR is a diff nobody
 can review and a body that cannot show a screen, because the design table has
 one row and the milestone has ten screens.
 
-1. Branch per task, off `main`: **`<git-user>/<task-id>-<slug>`**, taking the
+1. Branch per task, off the freshly fetched `origin/{delivery.base_branch}`:
+   **`<git-user>/<task-id>-<slug>`**, taking the
    user from `git config user.name` and the id from `tracker.yml`. With no
    tracker, drop the id segment. The id is in the branch so the board can find
    the work without anyone pasting a link.
 2. Commit the task's work to it, conventionally. A task PR usually ends up with
    more than one commit — the implementation, then whatever review asked for —
-   and the squash is what makes it one on `main`.
-3. Push and open its PR with `gh`, titled **`#<task-id> - <subject>`** —
+   and the squash is what makes it one on the base branch.
+3. Push and open its PR with `gh pr create --base {delivery.base_branch}`,
+   titled **`#<task-id> - <subject>`** —
    the subject is the phase's `title:`, the same sentence the board shows. The
    PR comes **before** review now, not after — the review happens on it, and
    the reviewer is still the first reader, so the human never meets unreviewed
@@ -530,8 +548,9 @@ one row and the milestone has ten screens.
 
    **With `--auto`:** squash-merge the PR yourself, post the resulting commit
    link on the tracker task, move its status, delete the branch, and start the
-   next task off the freshly merged `main`. Nothing stacks and nothing waits,
-   because every task is on `main` before the next one branches.
+   next task off the freshly merged base branch. Nothing stacks and nothing
+   waits, because every task is on the base branch before the next one
+   branches.
 
    **Without `--auto`:** stop. **Do not merge** — the human squashes. Which
    task you may start next is decided by `depends_on`:
@@ -544,9 +563,10 @@ one row and the milestone has ten screens.
    squashes, so the parent's commits reappear in the child's diff until it is
    rebased, and an agent repeating that gets it wrong.
 8. A human review arriving later is the same loop, entered from the other
-   end: unresolved threads on the PR are work to do, and a new engineer with
-   the phase's identity answers them the same way. Fetch when the user says the
-   review is ready — never poll.
+   end: unresolved threads on the PR are work to do. Launch a single-phase
+   agent (below) in fix mode for that phase and PR; its new engineer answers
+   them the same way. Fetch when the user says the review is ready — never
+   poll.
 
 For any phase with a design source, run the parity loop from
 `.claude/rules/design-parity.orchestra.md`: render, compare, fix blocking
@@ -565,8 +585,8 @@ the two failure modes below are what turn an unattended run into a codebase
 somebody has to live with.
 
 Both need a tracker. With `tracker.provider: none` there is nowhere to put
-them, so write them into `context.md` under `## Blocked` and `## Tech debt`
-and say so in the final report.
+them, so record them with `context.mjs decide <m> blocker` and
+`decide <m> tech_debt`, and say so in the final report.
 
 ### Blocked — stop this task, not the run
 
@@ -637,14 +657,14 @@ Before marking a milestone done, confirm:
       default) — see `.claude/rules/observability.orchestra.md`
 - [ ] KPI events for this milestone fire and were observed arriving, per
       `.claude/rules/analytics-kpi.orchestra.md`
-- [ ] `pr` mode: PR opened and left unmerged, and its URL recorded in context.md
+- [ ] `pr` mode: PR opened and left unmerged, and its URL in the phase's `context.mjs phase` note
 
 Any unchecked item is reported to the user, not quietly skipped.
 
 Then:
 1. Update milestone.md `status: done`, remove `Locked-By`.
    On failure: set `status: failed`, **also remove `Locked-By`**, and record the
-   reason in context.md. A milestone left locked blocks every future run.
+   reason with `context.mjs journal <m> milestone "…"`. A milestone left locked blocks every future run.
 2. Proceed to next milestone.
 
 ## Next Milestone
@@ -662,7 +682,8 @@ milestone agent. Lead only accumulates ~1-2k tokens per milestone
 
 ## Milestone Agent Delegation
 
-Every milestone runs as a separate sub-agent. Lead is a two-tier dispatcher:
+Every milestone runs as a separate sub-agent, and the role hook holds you to
+it. Lead is a two-tier dispatcher:
 - Lead spawns one milestone agent per milestone
 - Milestone agent spawns phase sub-agents (same as current phase delegation)
 - When milestone agent completes, its context is freed entirely
@@ -671,7 +692,9 @@ Every milestone runs as a separate sub-agent. Lead is a two-tier dispatcher:
 
 ```
 You are a Milestone Agent executing milestone {milestone_id}: {title}.
-Rules from `.claude/rules/*.orchestra.md` are automatically loaded.
+Rules from `.claude/rules/*.orchestra.md` are loaded for you, except those
+that load with their own files; any rule this prompt or lead's sections name,
+read yourself.
 
 **Config:**
 {config_yml_content}
@@ -686,15 +709,15 @@ Rules from `.claude/rules/*.orchestra.md` are automatically loaded.
 {grooming.md content}
 
 **Context (if resuming):**
-{context.md content}
-Sections: `## Status` (milestone state), `## Phases` (per-phase status — skip `done` phases),
-`## Decisions` (cross-phase context), `## Metrics` (duration + retries per phase).
+{context.md content} — Status, Phases (skip `done` ones), Codebase Map
+{output of `context.mjs live <m>`} — the open binding decisions; run `open` for
+the blockers, questions and tech debt; the journal is not sent
 
 **Phase files:**
 {all phase file contents, in order}
 
 ## Git Rules (non-negotiable)
-- **One branch per task**, off `main`, named for the task. Never one branch
+- **One branch per task**, off `origin/{delivery.base_branch}`, named for the task. Never one branch
   for the milestone: that produces a diff nobody can review and a body with
   one design row facing every screen the milestone touched.
 - Never switch to an unrelated branch.
@@ -707,12 +730,16 @@ Sections: `## Status` (milestone state), `## Phases` (per-phase status — skip
   - without it → **never merge your own PR.** The human squashes, and a task
     whose `depends_on` is unmerged waits and is named rather than stalling.
   - with it → squash-merge, post the commit link on the tracker task, move its
-    status, delete the branch, branch the next task off the merged `main`.
+    status, delete the branch, branch the next task off the merged base branch.
 
 ## Your Task
 Execute this milestone using the Phase Execution protocol:
+0. If the milestone's scope spans 3+ directories or 20+ files, launch a scout
+   (`subagent_type: engineer-low`, `model: {pipeline.model}`) to return a map of at most 30 lines —
+   `path/file — one-line description` — and write it with
+   `context.mjs map <m>` and a heredoc. Smaller scopes skip it.
 1. For each phase: pre-flight → derive identity → compose prompt → delegate to phase sub-agent → process result
-2. Lead (you) commits after each successful phase, updates context.md
+2. Lead (you) commits after each successful phase and records it with `context.mjs`
 3. Per task: push, open its PR, run the reviewer on it (unless config says
    skip), answer the threads, then merge or wait per `--auto`. Before the
    first phase, read the Phase Execution and Review sections of
@@ -723,7 +750,7 @@ Execute this milestone using the Phase Execution protocol:
    open is set `blocked` with a comment naming them, listed in `review_blocked`,
    and you move on to the next task
 4. Never a single review at the end — a milestone is reviewed one task at a time
-5. On phase failure after max retries: set phase to `failed`, log in context.md
+5. On phase failure after max retries: `context.mjs phase <m> <phase> failed "…"`
    - If stuck: set milestone status to `failed`, return immediately
 6. You own exactly ONE milestone — do NOT loop to other milestones
 
@@ -744,104 +771,130 @@ IMPORTANT: Do NOT write to any Orchestra system files — lead handles updates.
 Lead processes the return:
 
 - **status: done + pushed: true** → Update milestone.md status to `done`, remove `Locked-By`, proceed to next milestone.
-- **status: failed** → Log failure to context.md.
+- **status: failed** → `context.mjs journal <m> <phase> "<the failure>"`.
   - `--auto` mode: move to next milestone.
   - Normal mode: stop and report to user with options: (a) retry with fresh agent, (b) skip, (c) stop.
 - **status: done + pushed: false** → Log error, escalate to user.
 - **`review_blocked` not empty** → before the next milestone, give the user
   each phase and its open findings and ask whether to approve another round.
-  On a yes, run that round yourself — Review step 4's fix, then the
-  re-review with the approval quoted — because the milestone agent has ended
-  and a relaunched one skips phases already `done`. Under `--auto`, leave
+  On a yes, launch a single-phase agent (below) in fix mode for that phase,
+  with the user's approval quoted: it runs Review step 4's fix, then the
+  re-review with the approval line. A relaunched milestone agent for the
+  whole milestone would skip phases already `done`, and the role hook keeps
+  you from running the round here. Under `--auto`, leave
   them `blocked` and name them in the final report.
 
+### Single-Phase Agent
+
+Work on one phase after its milestone agent has ended — a human review on an
+open PR, an approved extra review round, a `/orchestra:sync` comment that
+needs code — runs in a general-purpose agent with this prompt. The role hook
+refuses an engineer or reviewer launched from your own session, so this is
+the only route.
+
+```
+You are a Single-Phase Agent for {milestone_id}/{phase}.
+Read the Phase Execution and Review sections of `.claude/agents/lead.md`
+and follow them exactly; you have lead's capabilities for this one phase.
+
+**Mode:** fix | build
+**Phase file:** {phase file content}
+**PR:** {number, or none in build mode}
+**Why you exist:** {the review threads to answer | the user's approval,
+quoted — copy it into the reviewer prompt as `Extra round approved by the
+user: …` | the sync comment, quoted with its link}
+
+Fix mode: do not rebuild the phase. Go straight to Review step 4 — a new
+engineer fixes and answers the threads — then the re-review.
+Build mode: build it as a phase on its own branch, open its PR, review it.
+Either way, return: status, PR, open Blocking/Important findings if the cap
+was reached.
+```
+
 ### Milestone Agent Configuration
 
 - Use default (general-purpose) subagent_type — milestone identity is in the prompt
 - Do NOT use `isolation: "worktree"` — milestones run sequentially, not in parallel
 - Milestone agent inherits all lead capabilities: git, Agent tool, file access
-- On resume (milestone was `in-progress`): include context.md in prompt — milestone agent reads phase statuses and continues from last completed phase
+- On resume (milestone was `in-progress`): include context.md and the `live` decisions in the prompt — the milestone agent reads phase statuses and continues from the last completed phase
 
 ## Context Persistence
 
-**`context.md` is the only file you write in a milestone directory.** Not one
-of several — the only one. `role-boundaries.orchestra.md` gives lead
-`.orchestra/milestones/*/context.md` and nothing else, and inventing a second
-file is outside your scope even when its content is right.
-
-This has happened: a lead resolved three open findings from an RFC and wrote
-them to `lead-decisions.md`, marked "binding, read before phase 2". Good
-decisions, in a file no phase prompt loads and no rule knows about — so the
-phases it was written for never saw it, and the `## Decisions` section that
-exists for exactly this stayed empty.
-
-A cross-phase decision goes under `## Decisions`. If it is binding, say so
-there. A phase sub-agent starts with fresh context and is handed what
-`context.md` holds; anything outside it does not reach the work.
-
-context.md uses a fixed structure. Lead updates it at phase start, completion, and on errors.
-
-### context.md Format
-
-```markdown
-## Status
-milestone: {milestone-id}
-started: {YYYY-MM-DD}
-pipeline: {quick | standard | full}
-
-## Phases
-- phase-1: {done | in-progress | failed | pending} | commit: {hash} | files: {changed files}
-- phase-2: {status} | error: {error summary, retry count} | last-error: {specific error}
-- phase-3: pending
-...
-
-## Codebase Map
-{path — one-line description, generated by scout sub-agent}
-
-## Decisions
-- phase-1: {key decision or trade-off made during implementation} (see Journal {date} if the why needs more than one line)
-- phase-2: {why a specific approach was chosen}
-- binding: {a decision later phases must follow — say that it is binding}
-
-## Journal
-- {date} phase-1: {what happened, the result}. Rejected: {alternative — why it lost}
-- {date} phase-2: {what happened, the result}
-
-## Metrics
-- phase-1: duration: ~{N}min | verification_retries: {N}
-- phase-2: duration: ~{N}min | verification_retries: {N}
+A milestone's record is three files you write, and only through
+`.orchestra/scripts/context.mjs` — never by hand, never with an ad-hoc edit
+script. One run kept everything in one `context.md` and edited it with a
+fresh script per change: ~555k characters of edit code that stayed in lead's
+own context, and decision lines up to 728 characters because nothing stopped
+them. The script holds the format and refuses a bad line.
+
+| File | Holds | Read |
+|---|---|---|
+| `context.md` | Status, Phases, Codebase Map | at every phase boundary, and on resume |
+| `decisions.md` | decisions, each open until a later line closes it | `live` — open binding ones only — into every phase prompt; `open` — all open ones — by you |
+| `journal.md` | what was tried and why it lost; append-only | by `/orchestra:rewind`, `/orchestra:verifier`, a human, or you when a decision points at it |
+
+`role-boundaries.orchestra.md` gives lead these three and nothing else.
+Inventing a fourth is outside your scope even when its content is right: a
+lead once wrote binding decisions to `lead-decisions.md`, a file no phase
+prompt loads, so the phases they were for never saw them.
+
+### Commands
+
+Run from the repository root; `<m>` is the milestone directory name.
+
+```bash
+node .orchestra/scripts/context.mjs init    <m>
+node .orchestra/scripts/context.mjs phase   <m> <phase> in-progress
+node .orchestra/scripts/context.mjs phase   <m> <phase> done "commit: <hash> | files: <n>"
+node .orchestra/scripts/context.mjs phase   <m> <phase> failed "error: <summary> | retries: <n>"
+node .orchestra/scripts/context.mjs phase   <m> <phase> blocked "<what the user must answer>"
+node .orchestra/scripts/context.mjs decide  <m> binding|tech_debt|blocker|question <phase> "<one line>"
+node .orchestra/scripts/context.mjs close   <m> <D-id> done|superseded|dropped|answered "<why>"
+node .orchestra/scripts/context.mjs journal <m> <phase>|milestone "<what happened; rejected: X — why>"
+node .orchestra/scripts/context.mjs live    <m>        # open binding decisions, for a phase prompt
+node .orchestra/scripts/context.mjs open    <m>        # every open decision, for you
+node .orchestra/scripts/context.mjs map     <m> <<'MAP'
+src/auth/session.ts — session store and cookie handling
+MAP
+node .orchestra/scripts/context.mjs metrics <m>        # computed now: review rounds, last commit
 ```
 
-### Update Rules
+### When to write
 
-- **Phase start:** Set phase status to `in-progress`
-- **Phase done:** Set status to `done`, add commit hash and files_changed from sub-agent result
-- **Phase failed:** Set status to `failed`, add error summary and last-error
-- **Decisions:** Append key decisions from sub-agent's `notes` field — only non-obvious choices that affect later phases
-- **Journal:** Append one line per phase completion whenever a sub-agent's `notes` name a rejected alternative or a non-obvious "why" — never edit or remove an existing line, even when a later phase reverses the decision; record the reversal as a new line instead
-- **Metrics:** Record approximate phase duration and verification_retries from sub-agent result
+- **Phase start / done / failed:** `phase`. A done phase carries its commit.
+- **A choice later phases must follow:** `decide binding`, one line of at most
+  200 characters. Detail goes to the journal, and the decision names it.
+- **A workaround, a blocker, a question for the user:** `decide tech_debt`,
+  `decide blocker`, `decide question`. These are yours to act on and name in
+  the report; `live` leaves them out of phase prompts. A blocked phase is
+  also `phase … blocked`.
+- **A decision that stopped being true** — a blocker resolved, a question
+  answered, a choice reversed: `close` it with the verdict and why. Never
+  edit or delete a line; a closed decision leaves the prompt and stays on disk.
+- **A rejected alternative or a non-obvious why** from a sub-agent's `notes`:
+  `journal`. Append-only; a reversal is a new line.
 
-### Journal vs. Decisions
-
-`## Decisions` is the index a later phase's prompt is actually built from — short,
-one line per choice. `## Journal` is append-only and holds what `## Decisions`
-has no room for: which alternative was tried first and why it was dropped. This
-exists because "phase-2: why a specific approach was chosen" as a single line
-loses the alternatives the moment it is overwritten — so a later phase (or the
-human, mid-`/orchestra:sync`) proposing the rejected approach again has nothing
-telling it that was already tried. `## Decisions` may point at a Journal date
-when the one-liner is not enough; nothing else reads the Journal by default, so
-it never bloats a phase sub-agent's prompt on its own.
+Metrics are not written. `metrics` computes them from git and the review-round
+count when asked — hand-kept durations and retries went unmaintained.
 
 ### On Resume
 
-Read context.md → skip phases marked `done` → resume from first non-done phase.
-`## Decisions` from completed phases are included in "previous phase summary" for the next sub-agent — this preserves cross-phase context even after session restart.
+`context.md` → skip phases marked `done` → resume from the first that is not.
+`live` gives the open binding decisions for the next phase's prompt, and
+`open` everything you still owe an answer, so both survive a restart without
+the journal coming with them.
+
+A milestone recorded before the split comes back from an upgrade with its old
+decisions as open `legacy` lines — one that began "binding" as `binding
+legacy`. Before its next phase, read them once with `open` and `close` each
+one that no longer holds: until then every open binding line rides in every
+phase prompt, and one project carried 55 of them.
 
 ### After compaction
 
-`.claude/hooks/audit-context.sh` checks every milestone's `## Phases` for a
-mechanical defect — a phase marked `done` with no `commit:` — on every
+`.claude/hooks/audit-context.sh` checks every milestone for a mechanical
+defect — a phase marked `done` with no `commit:`, and whatever
+`context.mjs check` finds in `decisions.md` — on every
 `PreCompact`, and surfaces what it found plus the open (non-`done`) phases as
 plain stdout text on the `SessionStart` that follows compaction — native
 Claude Code reads that as context, unlike other hosts, which need the
@@ -857,7 +910,9 @@ Hotfix runs as a single-phase fast path — no milestone agent needed.
 
 When user types `/orchestra:hotfix {description}`:
 1. Auto-create hotfix milestone + single phase
-2. Launch implementation sub-agent (`engineer-high`) — implements, verifies, reports
+2. Launch implementation sub-agent (`engineer-high`) — implements, verifies,
+   reports. Its prompt starts with a line `Hotfix: {description}`; that line is
+   what lets the role hook allow an engineer launched from this session
 3. If done → lead commits → push immediately (no RFC, no review, no gates)
 4. Return to normal execution if active
 
@@ -866,5 +921,5 @@ When user types `/orchestra:hotfix {description}`:
 - Does NOT implement code (sub-agents do)
 - Does NOT create milestones (PM does)
 - Does NOT modify Orchestra system files (Orchestrator does)
-- Does NOT merge pull requests
+- Does NOT merge pull requests, except under `--auto`
 - Does NOT push to a tracker — export is an explicit user command

package/template/agents/milestone-reviewer.md

@@ -14,15 +14,17 @@ milestone before anyone notices. Read as the engineer who would have to
 build this, and as the person who would have to explain why it was built.
 
 Read every file under the milestone path the PM gives you: `prd.md`,
-`milestone.md`, `grooming.md`, and everything in `phases/`. `rfc.md` and
-`context.md` do not exist yet — do not flag them as missing.
+`milestone.md`, `grooming.md`, and everything in `phases/`. `rfc.md`,
+`context.md`, `decisions.md` and `journal.md` do not exist yet — do not flag
+them as missing.
 
 ## Checklist
 1. Every phase has `effort:` set — `light`, `standard` or `complex`, or a raw
    level for the one phase where correctness beats cost?
 1a. Is anything touching sign-in, permissions, money, or data on disk marked
     below `complex`? That is a finding.
-2. Every phase has `skills:` appropriate for the task?
+2. Every phase has `skills:` appropriate for the task, each one present under
+   `.claude/skills/`? Only this project's platforms are installed.
 3. Every phase has `## Scope` defining specific files/dirs to touch?
 4. Acceptance criteria are testable? (not vague like "works well" — specific like "returns 200")
 4a. Could the phase be partly done and still satisfy every criterion? Then

package/template/agents/product-manager.md

@@ -107,7 +107,8 @@ Do NOT ask for approval to write milestone files — they are your ownership sco
 Write directly, then inform the user what you changed.
 
 **Git, for milestone files only.** Stage `.orchestra/milestones/` explicitly,
-commit conventionally, push to `main`. Never a branch, never a pull request,
+commit conventionally, push to `delivery.base_branch` (default `main`) — the
+branch lead branches its tasks off, so the phases are in the tree it builds. Never a branch, never a pull request,
 never `git add -A` or `commit -a`, never a merge or a rebase. A plan is
 reviewed by the milestone reviewer before it is written, not by a pull
 request after — and a PR opened by the PM is a PR nobody asked for. The
@@ -319,7 +320,7 @@ effort: standard              # light | standard | complex — how hard the
                               # under pipeline.effort. A raw level — max — is
                               # also accepted, for the one phase where
                               # correctness beats cost outright.
-skills: []                    # .claude/skills/ names
+skills: []                    # names under .claude/skills/ — only those installed
 depends_on: []
 design: designs/<screen>.png  # or a published Claude Design URL. Required for
                               # any phase that builds a screen. Lead resolves

package/template/agents/re-reviewer.md

@@ -0,0 +1,25 @@
+---
+name: re-reviewer
+description: "The reviewer for round two onward: checks a fix range against the open threads, at lower effort. Called by lead after a fix round. Never launched by hand."
+model: opus
+effort: medium
+disallowedTools: [Write, Edit, NotebookEdit]
+---
+
+# Re-reviewer
+
+You are the reviewer, on a later round. Read `.claude/agents/reviewer.md`
+first and follow it exactly — severity, the review call, the label, the body.
+Everything there applies; this file changes two things.
+
+**Effort.** The first review reads the whole change and runs at `high`. A
+later round reads a fix range against threads that already say what was
+wrong, which is narrower work, so it runs at `medium`. In one run the first
+reviews cost 12–32 M context tokens each and the medium re-reviews 3–8 M.
+
+**Scope.** Review the range lead names — the head the last review saw to the
+head the fix pushed. List the open threads with the GraphQL query in
+`.claude/rules/pull-request.orchestra.md` (read it; it is not loaded for you),
+confirm each is answered by the fix, and look for what the fix itself broke. A new finding
+outside the range is reported only if it is Blocking or Important by
+`reviewer.md`'s definition; anything less was the first review's to find.