agentic-team 6.1.0 → 6.3.0

package/template/.orchestra/README.md

@@ -13,8 +13,8 @@ Terminal 1 (PM):                    Terminal 2 (Lead):
   ├─ Create milestones               ├─ 🏗️ design phase → RFC
   ├─ Groom phases                    ├─ 🚦 User approves RFC
   ├─ Always available                ├─ ⚙️ delegate to sub-agent → phase by phase
-  │                                  ├─ 🔍 reviewer → review commits
-  │  (can plan M2 while M1 runs)     ├─ git push → milestone done
+  │                                  ├─ 🔍 reviewer → reviews each PR
+  │  (can plan M2 while M1 runs)     ├─ PR per task → human merges
   │                                  └─ Stop (inline) or next milestone (agent)
 ```
 
@@ -37,7 +37,9 @@ Terminal 1 (PM):                    Terminal 2 (Lead):
 │       ├── milestone.md   # Summary, acceptance criteria, status
 │       ├── grooming.md    # Discussion, scope, decisions
 │       ├── rfc.md         # Technical design (lead fills during design phase)
-│       ├── context.md     # Running log (lead maintains for resume)
+│       ├── context.md     # State: status, phases, codebase map (lead, for resume)
+│       ├── decisions.md   # Decisions, open until closed (lead)
+│       ├── journal.md     # What was tried and why it lost (lead, append-only)
 │       └── phases/        # Sequential units of work
 │           ├── phase-1.md
 │           └── ...
@@ -76,9 +78,9 @@ PM discusses feature with user
   → Lead runs design phase: writes RFC + validates grooming
   → [USER APPROVAL GATE: RFC + grooming validation → Implementation]
   → Lead delegates phases to sub-agents (sequential, each → commit)
-  → Lead calls reviewer agent (reviews unpushed commits)
-  → FIX cycle if changes-requested (re-review when the fix is large)
-  → Lead pushes, PM verifies acceptance criteria, closes milestone
+  → Per task: push, open its pull request, reviewer reviews it there
+  → FIX cycle if changes-requested — a new engineer, at most stuck_retry_limit rounds
+  → The human squash-merges (lead does under --auto); PM verifies, closes milestone
 
 Hotfix (production bugs):
   /orchestra:hotfix {description}
@@ -98,8 +100,8 @@ PM sets `Complexity` on milestone (pipeline) and `complexity` on each phase (mod
 | Complexity | Pipeline | Use when |
 |------------|----------|----------|
 | `trivial`, `quick` | Phases → Commit → Push — no design, no review | Version bumps, config, a single-file fix |
-| `standard` | Phases → Review → Push | Typical features, clear requirements |
-| `complex` | Design → Phases → Review → Push | New subsystems, unfamiliar territory |
+| `standard` | Phases → PR + Review | Typical features, clear requirements |
+| `complex` | Design → Phases → PR + Review | New subsystems, unfamiliar territory |
 
 Default: config.yml `pipeline.default_pipeline`. A phase's `effort` is a
 separate axis — how hard its sub-agent thinks — mapped through
@@ -133,8 +135,8 @@ Lead (lean dispatcher)
 |--------|---------|
 | `planning` | PM is defining scope, grooming phases |
 | `in-progress` | Phases are being executed |
-| `review` | All phases done, reviewer is checking |
-| `done` | Pushed to origin, acceptance criteria verified |
+| `review` | Pull requests open, reviewer is checking |
+| `done` | Every task's PR merged, acceptance criteria verified |
 
 ### Phase Statuses
 
@@ -153,7 +155,7 @@ Phases always execute in this order:
 
 1. **Design** (RFC) — if technical design is needed
 2. **Implementation phases** — lead derives sub-agent identity from phase scope
-3. **Reviewer** — reviews all unpushed commits
+3. **Reviewer** — reviews each task's pull request, inline on its lines
 
 Phases run in order: phase-1 → phase-2 → phase-3.
 
@@ -168,13 +170,11 @@ Lead NEVER commits unless verification passes.
 ## Git Boundaries
 
 - Each phase completion → **one conventional commit** on the current branch
-- **One branch per task**, off `main`: `<git-user>/<task-id>-<slug>`
+- **One branch per task**, off `delivery.base_branch` (default `main`): `<git-user>/<task-id>-<slug>`
 - Never switch to an unrelated branch
-- Lead never merges its own PR
-- Milestone completion → **push to origin** (automatic after review passes)
-- Commits stay local until milestone fully completes — no partial push on failure
-- Reviewer reviews unpushed commits: `git log origin/{branch}..HEAD`
-- Clean git history: each commit maps to a phase
+- Each task is pushed and opened as its own pull request, against `delivery.base_branch`
+- Lead never merges its own PR, except under `--auto`
+- Clean git history: each commit maps to a phase, and the squash maps to a task
 
 ### Conventional Commit Format
 
@@ -208,7 +208,7 @@ The user must approve before these transitions:
 - **Milestone creation** — PM discusses and plans, but must get user approval before creating the milestone directory and files
 - **RFC → Implementation** — lead waits for the user only when `rfc_approval: required`. The default, `optional`, shows the design and continues.
 
-Push is automatic after review passes. All other transitions are automatic.
+Each task is pushed when its pull request opens; review happens on it, and the human merges (lead does under `--auto`). All other transitions are automatic.
 
 ### Rejection Handling
 
@@ -220,26 +220,17 @@ Rejections are normal. The system does not stall — it loops back with feedback
 
 ---
 
-## Review Flow (Git-Native)
+## Review Flow
 
-Reviewer is a separate agent called by the lead. Review is based on **unpushed commits**.
+Review happens on each task's pull request: the reviewer posts one review with
+every finding inline on its line and sets the verdict as a label
+(`review:approved` or `review:changes-requested`). On changes-requested a new
+engineer with the phase's identity fixes and answers the threads, and the
+re-reviewer checks the fix range — at most `thresholds.stuck_retry_limit`
+rounds, then the user decides. Suggestions are recorded as tech debt.
 
-```
-Lead calls reviewer agent
-  → Reviewer runs: git log origin/{branch}..HEAD
-  → Reviewer runs: git diff origin/{branch}...HEAD
-  → Reviewer applies full checklist
-  → Returns: approved / approved-with-comments / changes-requested
-```
-
-**If approved** → push immediately.
-
-**If approved-with-comments** → push immediately. Each Suggestion is recorded as tech debt — see the Review section of `.claude/agents/lead.md`.
-
-**If changes-requested** → Lead launches a new engineer with the phase's identity
-and effort, with the phase file, the PR number and the diff in its prompt, and
-the fix is re-reviewed — at most `thresholds.stuck_retry_limit` rounds, then
-the user decides. The steps are in `.claude/agents/lead.md`, stated once.
+The steps are in `.claude/agents/lead.md` (Review) and the commands in
+`.claude/rules/pull-request.orchestra.md`, each stated once.
 
 ---
 
@@ -299,7 +290,7 @@ Each role has exclusive write access to specific directories:
 | orchestrator | `.orchestra/roles/*`, `.orchestra/config.yml`, `.orchestra/README.md`, `.orchestra/blueprints/`, `.orchestra/stacks/`, `.orchestra/trackers/`, `.orchestra/scripts/`, `CLAUDE.md`, `.claude/agents/`, `.claude/hooks/`, `.claude/skills/*/SKILL.md`, `.claude/rules/*.orchestra.md`, `.claude/commands/orchestra/`, `docs/` | Everything |
 | product-manager | `.orchestra/milestones/*` (prd.md, milestone.md, grooming.md, phases) | Everything |
 | sub-agents | Only what phase `## Scope` defines — dynamic per phase | `.orchestra/milestones/*/phases/*` |
-| lead | `.orchestra/milestones/*/context.md` | Everything in active milestone |
+| lead | `.orchestra/milestones/*/{context,decisions,journal}.md`, via `.orchestra/scripts/context.mjs` | Everything in active milestone |
 
 ---
 
@@ -308,27 +299,26 @@ Each role has exclusive write access to specific directories:
 PM and lead run in **separate terminals**. They communicate through milestone files:
 
 - **PM writes:** prd.md, grooming.md, milestone.md, phase files
-- **Lead reads:** milestone files → executes phases → updates results + context.md
+- **Lead reads:** milestone files → executes phases → records results with `context.mjs`
 - **No direct messaging** between PM and lead — file system is the interface
 
 ### Context Persistence
 
-Lead maintains `context.md` in each milestone directory with a fixed structure:
-- `## Status` — milestone id, start date, pipeline type
-- `## Phases` — per-phase status, commit hash, files changed, errors
-- `## Codebase Map` — scout-generated file map (survives milestone clear)
-- `## Decisions` — key choices from each phase that affect later phases
-- `## Journal` — append-only: what happened and which alternatives were rejected, and why
-- `## Metrics` — phase duration and verification retries (used by `/orchestra:status`)
+Lead keeps three files per milestone, written only through
+`.orchestra/scripts/context.mjs`, split by who reads them:
+- `context.md` — Status, Phases (status, commit, errors), Codebase Map; read at every phase
+- `decisions.md` — one-line decisions, each open until a later line closes it; only open ones reach a phase prompt
+- `journal.md` — append-only: what happened and which alternatives were rejected, and why; read on demand
 
-This enables resume after terminal close/reopen. On restart, lead reads context.md and skips completed phases.
+Metrics are not stored: `context.mjs metrics` computes them when `/orchestra:status` or `/orchestra:rewind` asks.
+On restart, lead reads `context.md`, skips completed phases, and takes the open decisions from `context.mjs live`.
 
 ### Approval Gates (Lead Terminal)
 
 Lead asks the user directly (not PM) at this point:
 1. **RFC ready** — "Approve RFC to start implementation?", asked only when `rfc_approval: required`. Under the default `optional` the design is shown and execution continues; under `skip` it is written and never shown.
 
-Push is automatic after review passes — no approval needed.
+Each task is pushed as its pull request opens; nobody approves a push. The merge is the human's, except under `--auto`.
 
 ---
 
@@ -356,13 +346,13 @@ sequenceDiagram
         C->>C: sub-agent → phase-N → commit
     end
 
-    C->>C: reviewer agent → review commits
+    C->>C: per task: push, open PR, reviewer reviews it
 
     alt Changes requested
         C->>C: Fix → commit
     end
 
-    C->>C: git push → milestone done
+    C->>C: human merges each PR → milestone done
 
     alt --auto mode
         C->>C: Next milestone → loop or done
@@ -383,7 +373,7 @@ sequenceDiagram
     C->>C: Scan milestones/
 
     C->>MA: Spawn Agent(M1)
-    MA->>MA: phase-1 → phase-2 → review → push
+    MA->>MA: phase-1 → phase-2, each PR reviewed
     MA-->>C: {status: done, retro: ...}
     Note over C: ~1-2k tokens retained
 
@@ -393,7 +383,7 @@ sequenceDiagram
         C->>C: "Continue to M2?" → user says yes
         C->>MA: Spawn Agent(M2)
     end
-    MA->>MA: phase-1 → phase-2 → review → push
+    MA->>MA: phase-1 → phase-2, each PR reviewed
     MA-->>C: {status: done, retro: ...}
 
     C->>C: No more milestones

package/template/.orchestra/config.yml

@@ -1,6 +1,16 @@
 # Orchestra Configuration
 # Customize pipeline behavior, thresholds, and verification commands.
 
+project:
+  # What this project builds for: web, expo, ios, android, backend. The
+  # installer installs only those platforms' stacks, skills and rule sections,
+  # and retires the rest on the next run. Empty means not decided yet: the
+  # installer detects the list from the repository and writes it here, and
+  # installs everything only when it finds nothing — an empty repo before
+  # /orchestra:setup. Edit it, or run `npx agentic-team --platforms ios,backend`,
+  # to change it; list all five to install everything on purpose.
+  platforms: []
+
 pipeline:
   # One model for every phase. There used to be a table mapping a phase's
   # complexity to a model tier, and it stopped earning its place: on the
@@ -186,6 +196,12 @@ delivery:
   # flag decides whether a human gates the merge; nothing decides whether the
   # work is visible.
   #
+  # The branch every task branches off and squashes into. Asked at setup,
+  # never inferred: a repository's default branch is often not where work
+  # lands — one project integrates on `next` and releases from `main`, and a
+  # task built off `main` there opens its PR against the release branch.
+  base_branch: main
+
   # How many times to iterate on a screen that does not match its design
   # before giving up. Only reached under --auto, where nobody is watching to
   # judge it.

package/template/.orchestra/roles/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/.orchestra/scripts/compact-diff.awk

@@ -7,7 +7,7 @@
 # for degrades to the raw diff rather than to a wrong one.
 #
 # Shipped to every project because pull-request.orchestra.md names it. Its
-# sibling scripts/compact-test-output.awk stays in the orchestrator repo:
+# sibling scripts/compact-test-output.awk stays in the agentic-team repo:
 # it parses `node --test`, and scaffolded apps run vitest or jest.
 
 BEGIN { in_header = 0 }

package/template/.orchestra/scripts/context.mjs

@@ -0,0 +1,373 @@
+#!/usr/bin/env node
+
+// Lead's record of a milestone, in three files with one writer:
+//
+//   context.md    state: Status, Phases, Codebase Map — read at every phase
+//   decisions.md  decisions, each open until a later line closes it
+//   journal.md    what was tried and why it lost — append-only, rarely read
+//
+// The split follows who reads what. One run kept all of it in a single
+// context.md: 72 KB, of which the 43 KB journal was dead weight to anyone
+// reading for the current state. It also had lead edit that file with an
+// ad-hoc script per change — ~555k characters of edit code that stayed in
+// lead's own context — so every write goes through a command here instead.
+//
+// A decision is never edited. It closes when a later line names it, and only
+// open decisions reach a phase prompt (`live`), so a resolved blocker or a
+// superseded choice stops costing anything without being lost.
+//
+// Lead is the only writer, so ids are assigned by read-then-append without a
+// lock. Metrics are not stored: `metrics` computes them from git and the
+// review-round count when asked, because hand-kept numbers went unmaintained.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+const TYPES = ["binding", "tech_debt", "blocker", "question"];
+const VERDICTS = ["done", "superseded", "dropped", "answered"];
+const STATUSES = ["pending", "in-progress", "done", "failed", "blocked"];
+// One line a reader can take in at a glance. One run's decision lines reached
+// 728 characters because nothing stopped them; the detail belongs in journal.
+const MAX_DECISION = 200;
+
+const DECISION =
+  /^- (D\d+) (binding|tech_debt|blocker|question|legacy) ?(\S*) ?(\d{4}-\d{2}-\d{2})?: (.*)$/;
+const CLOSE = /^- (D\d+) closed (\S+) (\d{4}-\d{2}-\d{2}): (.*)$/;
+
+const root = process.cwd();
+const dir = (m) => path.join(root, ".orchestra", "milestones", m);
+const file = (m, name) => path.join(dir(m), name);
+const today = () => new Date().toISOString().slice(0, 10);
+// CRLF is normalised on read: a section matcher that expects "\n" would
+// otherwise miss a heading and append a second copy of the section.
+const read = (p) => (fs.existsSync(p) ? fs.readFileSync(p, "utf8").replace(/\r\n/g, "\n") : "");
+const PHASE_ID = /^[A-Za-z0-9._-]+$/;
+
+function die(msg) {
+  process.stderr.write(`context: ${msg}\n`);
+  process.exit(1);
+}
+
+function writeAtomic(p, text) {
+  const tmp = `${p}.${process.pid}`;
+  fs.writeFileSync(tmp, text);
+  fs.renameSync(tmp, p);
+}
+
+function need(m) {
+  if (!m) die("name the milestone directory, e.g. M2-design-system");
+  if (!fs.existsSync(dir(m))) die(`no milestone directory .orchestra/milestones/${m}`);
+}
+
+function oneLine(text, what) {
+  const t = String(text || "").trim();
+  if (!t) die(`${what} is empty`);
+  if (/[\r\n]/.test(t)) die(`${what} must be one line`);
+  return t;
+}
+
+const STATE_HEADER = (m) =>
+  `## Status\nmilestone: ${m}\nstarted: ${today()}\n\n## Phases\n\n## Codebase Map\n`;
+
+function init(m) {
+  need(m);
+  if (!fs.existsSync(file(m, "context.md"))) writeAtomic(file(m, "context.md"), STATE_HEADER(m));
+  if (!fs.existsSync(file(m, "decisions.md")))
+    writeAtomic(file(m, "decisions.md"), "# Decisions\n\n");
+  if (!fs.existsSync(file(m, "journal.md"))) writeAtomic(file(m, "journal.md"), "# Journal\n\n");
+}
+
+/** Replace the body of a `## name` section, or add the section at the end. */
+function setSection(text, name, body) {
+  const re = new RegExp(`(^|\\n)## ${name}\\n[\\s\\S]*?(?=\\n## |$)`);
+  const block = `## ${name}\n${body}${body.endsWith("\n") ? "" : "\n"}`;
+  if (re.test(text)) return text.replace(re, (_, lead) => `${lead}${block}`);
+  return `${text.replace(/\n*$/, "\n\n")}${block}`;
+}
+
+function section(text, name) {
+  const m = new RegExp(`(?:^|\\n)## ${name}\\n([\\s\\S]*?)(?=\\n## |$)`).exec(text);
+  return m ? m[1] : "";
+}
+
+function phase(m, id, status, note) {
+  need(m);
+  init(m);
+  if (!id || !PHASE_ID.test(id)) die("name the phase as its file is named, e.g. phase-3");
+  if (!STATUSES.includes(status)) die(`status is one of ${STATUSES.join(", ")}`);
+  if (status === "done" && !/commits?:\s*\S+/.test(note || "")) {
+    die("a done phase carries its commit: pass a note like 'commit: abc123 | files: 4'");
+  }
+  const p = file(m, "context.md");
+  const text = read(p);
+  const lines = section(text, "Phases")
+    .split("\n")
+    .filter((l) => l.trim());
+  const entry = `- ${id}: ${status}${note ? ` | ${oneLine(note, "note")}` : ""}`;
+  const at = lines.findIndex((l) => l.startsWith(`- ${id}:`));
+  if (at === -1) lines.push(entry);
+  else lines[at] = entry;
+  writeAtomic(p, setSection(text, "Phases", `${lines.join("\n")}\n`));
+}
+
+function map(m) {
+  need(m);
+  init(m);
+  const body = fs.readFileSync(0, "utf8").trim();
+  // An empty stdin is a forgotten heredoc, not a request to erase the map.
+  if (!body) die("pipe the map in on stdin; nothing came, so the map is unchanged");
+  if (body.split("\n").length > 30) die("the codebase map is at most 30 lines");
+  const p = file(m, "context.md");
+  writeAtomic(p, setSection(read(p), "Codebase Map", `${body}\n`));
+}
+
+function parseDecisions(m) {
+  const decisions = new Map();
+  const closes = new Map();
+  for (const line of read(file(m, "decisions.md")).split("\n")) {
+    const c = CLOSE.exec(line);
+    if (c) {
+      closes.set(c[1], { verdict: c[2], date: c[3], text: c[4] });
+      continue;
+    }
+    const d = DECISION.exec(line);
+    if (d) decisions.set(d[1], { id: d[1], type: d[2], phase: d[3], line });
+  }
+  return { decisions, closes };
+}
+
+function nextId(m) {
+  let max = 0;
+  for (const id of parseDecisions(m).decisions.keys()) max = Math.max(max, Number(id.slice(1)));
+  return `D${max + 1}`;
+}
+
+function decide(m, type, phaseId, text) {
+  need(m);
+  init(m);
+  if (!TYPES.includes(type)) die(`type is one of ${TYPES.join(", ")}`);
+  if (!phaseId || !PHASE_ID.test(phaseId)) {
+    die("name the phase the decision came from as its file is named, e.g. phase-3, or milestone");
+  }
+  const t = oneLine(text, "decision");
+  if (t.length > MAX_DECISION) {
+    die(
+      `a decision is at most ${MAX_DECISION} characters (this is ${t.length}); put the detail in the journal`,
+    );
+  }
+  const id = nextId(m);
+  fs.appendFileSync(file(m, "decisions.md"), `- ${id} ${type} ${phaseId} ${today()}: ${t}\n`);
+  process.stdout.write(`${id}\n`);
+}
+
+function close(m, id, verdict, text) {
+  need(m);
+  const { decisions, closes } = parseDecisions(m);
+  if (!decisions.has(id)) die(`no decision ${id} in ${m}`);
+  if (closes.has(id)) die(`${id} is already closed`);
+  if (!VERDICTS.includes(verdict)) die(`verdict is one of ${VERDICTS.join(", ")}`);
+  const t = oneLine(text, "reason");
+  if (t.length > MAX_DECISION) die(`a reason is at most ${MAX_DECISION} characters`);
+  fs.appendFileSync(file(m, "decisions.md"), `- ${id} closed ${verdict} ${today()}: ${t}\n`);
+}
+
+function journal(m, phaseId, text) {
+  need(m);
+  init(m);
+  if (!phaseId || !PHASE_ID.test(phaseId)) die("name the phase, e.g. phase-3, or milestone");
+  fs.appendFileSync(file(m, "journal.md"), `- ${today()} ${phaseId}: ${oneLine(text, "entry")}\n`);
+}
+
+/**
+ * `live`: the open binding decisions — what a phase must follow, so what a
+ * phase prompt carries. `open`: every open decision, blockers, questions and
+ * tech debt included — lead's to act on, not an engineer's to read.
+ */
+function live(m, all) {
+  need(m);
+  const { decisions, closes } = parseDecisions(m);
+  for (const d of decisions.values()) {
+    if (closes.has(d.id)) continue;
+    if (all || d.type === "binding") process.stdout.write(`${d.line}\n`);
+  }
+}
+
+function check(m) {
+  const found = [];
+  const { decisions, closes } = parseDecisions(m);
+  const seen = new Set();
+  for (const line of read(file(m, "decisions.md")).split("\n")) {
+    if (!line.startsWith("- ")) continue;
+    if (CLOSE.test(line)) continue;
+    const d = DECISION.exec(line);
+    if (!d) {
+      found.push(`${m}/decisions.md: not a decision or a close: ${line.slice(0, 60)}`);
+      continue;
+    }
+    if (seen.has(d[1])) found.push(`${m}/decisions.md: ${d[1]} is used twice`);
+    seen.add(d[1]);
+    const migrated = d[2] === "legacy" || d[3] === "legacy";
+    if (!migrated && d[5].length > MAX_DECISION) {
+      found.push(`${m}/decisions.md: ${d[1]} is ${d[5].length} characters, over ${MAX_DECISION}`);
+    }
+  }
+  for (const id of closes.keys()) {
+    if (!decisions.has(id))
+      found.push(`${m}/decisions.md: a close names ${id}, which does not exist`);
+  }
+  return found;
+}
+
+function milestones() {
+  const base = path.join(root, ".orchestra", "milestones");
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name);
+}
+
+/**
+ * Split an older single-file context.md. Lossless: Decisions, Tech debt and
+ * Blocked bullets become open `legacy` decisions with their text unchanged;
+ * Journal and Metrics move to journal.md verbatim; any other section stays.
+ */
+function migrate(m) {
+  const p = file(m, "context.md");
+  const text = read(p);
+  const moves = { Decisions: "legacy", "Tech debt": "legacy", Blocked: "legacy" };
+  const toJournal = ["Journal", "Metrics"];
+  const present = [...Object.keys(moves), ...toJournal].filter((s) =>
+    new RegExp(`(^|\\n)## ${s}\\n`).test(text),
+  );
+  if (!present.length) return false;
+
+  let decisionsText = read(file(m, "decisions.md")) || "# Decisions\n\n";
+  let n = Number(nextId(m).slice(1));
+  for (const s of Object.keys(moves)) {
+    // A bullet starts an entry and an indented line continues it. Anything
+    // else — prose, a numbered item, a sub-heading — becomes its own entry,
+    // so nothing in the section is dropped when the section is removed.
+    const entries = [];
+    for (const raw of section(text, s).split("\n")) {
+      if (!raw.trim()) continue;
+      if (raw.startsWith("- ")) entries.push(raw.slice(2).trim());
+      else if (/^\s/.test(raw) && entries.length) entries[entries.length - 1] += ` ${raw.trim()}`;
+      else entries.push(raw.trim());
+    }
+    const label = s === "Decisions" ? "" : `[${s}] `;
+    for (const e of entries) {
+      // An older line that says it is binding still binds the phases left;
+      // the rest is history lead can close as it reads them.
+      const kind = s === "Decisions" && /^binding\b/i.test(e) ? "binding legacy" : "legacy";
+      decisionsText += `- D${n++} ${kind}: ${label}${e}\n`;
+    }
+  }
+
+  let journalText = read(file(m, "journal.md")) || "# Journal\n\n";
+  for (const s of toJournal) {
+    const body = section(text, s).trim();
+    if (body) journalText += `${s === "Journal" ? "" : `\n## Migrated from ${s}\n`}${body}\n`;
+  }
+
+  // New files first: if this stops halfway, context.md still holds everything.
+  writeAtomic(file(m, "decisions.md"), decisionsText);
+  writeAtomic(file(m, "journal.md"), journalText);
+  let rest = text;
+  for (const s of present)
+    rest = rest.replace(new RegExp(`(^|\\n)## ${s}\\n[\\s\\S]*?(?=\\n## |$)`), "");
+  writeAtomic(p, `${rest.trim()}\n`);
+  return true;
+}
+
+function metrics(m) {
+  need(m);
+  let rounds = {};
+  try {
+    rounds = JSON.parse(
+      read(path.join(root, ".orchestra", ".sessions", "review-rounds.json")) || "{}",
+    );
+  } catch {
+    // An unreadable count reads as no rounds recorded, which is what it says.
+    rounds = {};
+  }
+  const commitTime = (hash) => {
+    try {
+      return execFileSync("git", ["show", "-s", "--format=%cI", hash], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    } catch {
+      return "unknown";
+    }
+  };
+  const lines = section(read(file(m, "context.md")), "Phases")
+    .split("\n")
+    .filter((l) => l.startsWith("- "));
+  for (const l of lines) {
+    const [, id, status] = /^- (\S+): ([a-z-]+)/.exec(l) || [];
+    if (!id) continue;
+    const hashes = [];
+    for (const field of l.matchAll(/commits?:\s*([^|]+)/g)) {
+      for (const h of field[1].matchAll(/\b[0-9a-f]{7,40}\b/g)) hashes.push(h[0]);
+    }
+    const when = hashes.length ? commitTime(hashes[hashes.length - 1]) : "no commit";
+    process.stdout.write(
+      `${id}\t${status}\treview rounds: ${rounds[`${m}/${id}`] || 0}\tlast commit: ${when}\n`,
+    );
+  }
+}
+
+// An agent pipes output into `head`; a closed pipe ends the read, not the script.
+process.stdout.on("error", (e) => {
+  if (e.code === "EPIPE") process.exit(0);
+  throw e;
+});
+
+const [cmd, ...args] = process.argv.slice(2);
+switch (cmd) {
+  case "init":
+    init(args[0]);
+    break;
+  case "phase":
+    phase(args[0], args[1], args[2], args.slice(3).join(" "));
+    break;
+  case "map":
+    map(args[0]);
+    break;
+  case "decide":
+    decide(args[0], args[1], args[2], args.slice(3).join(" "));
+    break;
+  case "close":
+    close(args[0], args[1], args[2], args.slice(3).join(" "));
+    break;
+  case "journal":
+    journal(args[0], args[1], args.slice(2).join(" "));
+    break;
+  case "live":
+    live(args[0], false);
+    break;
+  case "open":
+    live(args[0], true);
+    break;
+  case "metrics":
+    metrics(args[0]);
+    break;
+  case "check": {
+    const found = (args[0] ? [args[0]] : milestones()).flatMap(check);
+    for (const f of found) process.stdout.write(`${f}\n`);
+    process.exit(found.length ? 1 : 0);
+    break;
+  }
+  case "migrate": {
+    const moved = (args[0] ? [args[0]] : milestones()).filter(migrate);
+    for (const m of moved)
+      process.stdout.write(`split ${m}/context.md into decisions.md and journal.md\n`);
+    break;
+  }
+  default:
+    die(
+      "usage: context.mjs init|phase|map|decide|close|journal|live|open|check|migrate|metrics <milestone> …",
+    );
+}