agentic-team 6.1.0 → 6.3.0

package/template/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: "Independent code reviewer. Reviews a task's pull request — findings inline on the lines they are about, the verdict as a label. No memory of writing the code. Called by lead once the PR exists."
 model: opus
-effort: xhigh
+effort: high
 disallowedTools: [Write, Edit, NotebookEdit]
 ---
 
@@ -127,8 +127,10 @@ and neither is "looks fine" — the app has a token module precisely so this is
 a number rather than an opinion.
 
 If the design and the token module genuinely disagree — a value the tokens
-cannot express — that is a blocker to report, not a difference to split. See
-`.claude/rules/design-parity.orchestra.md`.
+cannot express — that is a blocker to report, not a difference to split. When
+the pull request has a design source, read
+`.claude/rules/design-parity.orchestra.md` before you start; it is not loaded
+for you.
 
 **And look for what no number catches:**
 
@@ -266,8 +268,8 @@ determine a base, say so and review the full working tree instead.
 Severity is the impact on the product, not how interesting the finding is.
 Blocking and Important are fixed in this pull request. A Suggestion does not
 hold it: it is an inline comment tagged `[suggestion]` like any other finding,
-and lead records each one — a `tech_debt` task with a provider, a line in
-`context.md` with `tracker.provider: none`. One run left the
+and lead records each one — a `tech_debt` task with a provider,
+`context.mjs decide <m> tech_debt` with `tracker.provider: none`. One run left the
 scale undefined, and a reviewer probing a measuring tool's maths found a new
 "medium" corner every round, nine rounds running.
 

package/template/agents/scaffolder.md

@@ -71,6 +71,23 @@ convention is worse than an absent one, because it looks decided.
 |---|---|
 | Task tracker | none · GitHub Projects · ClickUp |
 | Shared UI kit? | yes · no |
+| Base branch — where tasks branch off and squash into | `main` · another (name it) |
+
+Write the answer to `delivery.base_branch` in `.orchestra/config.yml`. Do not
+read it from the repository's default branch: that is often the release
+branch, not the one work lands on.
+
+Write the platforms from Round 1 and 2 to `project.platforms`: Web → `web`,
+Expo → `expo`, Native mobile → `ios, android`, Backend → `backend`. Desktop
+and Game have no pack and add nothing. Step 5 narrows the install to this
+list.
+
+Add to the list, never replace it. With `--force` on a project that already
+has apps, its platforms stay listed — Step 5 would otherwise retire the
+existing app's skills and rule sections. If the stack you need is not under
+`.orchestra/stacks/`, the install was narrowed before this app was asked
+for: write the list now and run `npx -y agentic-team@<version>` (the version
+in `.orchestra/.installed.json`) to bring the stack back, then scaffold.
 
 If the user wants a shared UI kit **and** picked `standalone`, stop and
 resolve the conflict now: standalone apps cannot import a workspace package.
@@ -168,6 +185,15 @@ command. Report that to the user; do not try to install it yourself.
 Fix failures before reporting. If a fix fails 3 times, stop and report —
 follow `.claude/rules/stuck-detection.orchestra.md`.
 
+Then narrow the install to the platforms you wrote: run
+`npx -y agentic-team@<version>`, where `<version>` is the `version` in
+`.orchestra/.installed.json`. Same version, so nothing changes except what is
+installed: the other platforms' stacks, skills and rule sections are retired.
+Run it only now — Step 4 still needed the stacks. If that version cannot be
+fetched — staged on npm and not yet approved, or installed from a checkout —
+say so in the report and give the user the command; never substitute
+`@latest`, which could install a different version over this one.
+
 Commit once: `chore(setup): scaffold {platforms}`.
 
 ## Step 6 — Report

package/template/commands/help.md

@@ -30,6 +30,7 @@ AGENTS:
   scaffolder                       Interactive project setup (/orchestra:setup)
   lead                             Team assembler + milestone executor (/orchestra:start)
   reviewer                         Independent code review (called by lead)
+  re-reviewer                      Review rounds 2+ at lower effort (called by lead)
   tracker                          Milestone export to an external tracker (/orchestra:export)
 
 PIPELINE (set by PM via milestone Complexity field):

package/template/commands/hotfix.md

@@ -4,7 +4,9 @@ Usage: `/orchestra:hotfix {description}`
 
 The lead will:
 1. Auto-create a hotfix milestone + single phase
-2. Implement the fix (minimal, focused change)
+2. Implement the fix (minimal, focused change) — through an engineer whose
+   prompt starts with a line `Hotfix: {description}`, the one engineer the role
+   hook lets lead start from its own session
 3. Run verification gate (test + lint MUST pass)
 4. Commit with `fix({scope}): {description}`
 5. Push immediately — no RFC, no review, no approval gates

package/template/commands/rewind.md

@@ -9,13 +9,16 @@ Review milestone execution history for actionable insights. PM role only.
    - No arguments: all milestones with `status: done`
    - With numbers: only milestones matching those numbers (e.g., `1` matches `M1-*`)
 3. For each milestone, read execution artifacts:
-   - `context.md` — structured sections:
-     - `## Decisions` — key choices made during implementation
-     - `## Journal` — append-only: what happened, and which alternatives were rejected and why
-     - `## Metrics` — phase duration and verification retries
-     - `## Phases` — status, commits, errors per phase
+   - `context.md` — `## Phases`: status, commits, errors per phase
+   - `decisions.md` — choices made during implementation; a line naming a
+     decision as `closed` says how it ended
+   - `journal.md` — append-only: what happened, and which alternatives were
+     rejected and why
+   - `node .orchestra/scripts/context.mjs metrics <m>` — review rounds and the
+     last commit per phase, computed now. Durations and retries are not
+     stored; say so rather than estimating them
    - `grooming.md` — original scope vs what actually happened
-   - Review verdict and comments (from context.md or git log)
+   - Review verdict and comments (from the pull requests or git log)
 4. Extract and present — focus on **what the user needs to know**, not execution mechanics:
 
 ```
@@ -29,8 +32,7 @@ Review milestone execution history for actionable insights. PM role only.
 
 ### Performance
 - Total phases: 5 | Completed: 5 | Failed: 0
-- Longest phase: phase-3 (~12min) — complex UI with form validation
-- Verification retries: 3 total (phase-2: 2, phase-4: 1)
+- Review rounds: phase-2: 3, phase-4: 1 (from `context.mjs metrics`)
 - Stuck: No
 
 ### Review Findings

package/template/commands/setup.md

@@ -8,7 +8,8 @@ The scaffolder will:
 3. Scaffold each app with its official create tool
 4. Install the shared baseline (TypeScript, Biome, Vitest, CI, Node pin)
 5. Write per-app `CLAUDE.md` and `.claude/` from `.orchestra/stacks/`
-6. Run the verification gate and report what was created
+6. Run the verification gate, narrow the install to the chosen platforms,
+   and report what was created
 
 Refuses to run if the working tree already contains a scaffolded app,
 unless you pass `--force`.

package/template/commands/start.md

@@ -19,8 +19,8 @@ sub-agents are unaffected either way; their effort comes from the phase.
 The lead will:
 1. Scan milestones for pending work
 2. Assemble the right team for each phase (identity derived from phase content)
-3. Delegate phases to sub-agents, load skills, implement code
-4. Trigger code review via reviewer agent
+3. Run each milestone in a milestone agent, which delegates phases to sub-agents
+4. Have each task's pull request reviewed there, by the reviewer agent
 5. Push automatically after review passes
 6. After milestone: `--auto` continues to next automatically, normal mode asks user
 

package/template/commands/status.md

@@ -7,5 +7,5 @@ Show full milestone status report. PM role only.
    - All milestones with status, current phase, next action
    - Phase details for active milestone (status, effort, metrics)
    - Git status (branch, unpushed commits)
-   - Metrics summary from context.md `## Metrics` section (duration + retries per phase)
+   - Metrics from `node .orchestra/scripts/context.mjs metrics <m>` — review rounds and last commit per phase, computed now; nothing else is stored
    - Actions needed (specific next steps)

package/template/commands/sync.md

@@ -40,8 +40,11 @@ other's and stops. See `.claude/rules/tracker-authority.orchestra.md`.
 6. **Plan change, as the PM:** revise the phase file, run
    `/orchestra:export {id}` so the board carries the new text, reply under
    the comment saying what changed. **As lead:** surface it and stop.
-7. **Anything else, as lead:** build it, run the full verification gate, open
-   a pull request. Reply under the triggering comment with the pull request
+7. **Anything else, as lead:** launch a single-phase agent
+   (`.claude/agents/lead.md`, Single-Phase Agent) — fix mode for the task's open
+   PR, build mode for new work — with the comment quoted. It builds, runs the
+   full verification gate and opens or updates the pull request; lead itself
+   starts no engineer. Reply under the triggering comment with the pull request
    link. Move the task to `in_review`. **As the PM:** surface it and stop.
 
 ## What it refuses

package/template/commands/verifier.md

@@ -15,8 +15,8 @@ Verify that implemented milestones match their requirements. PM role only.
    - `grooming.md` — scope decisions and phase breakdown
    - All `phases/*.md` — phase acceptance criteria
 4. For each milestone, read execution context:
-   - `context.md` — `## Decisions` section (why specific approaches were chosen)
-   - `context.md` — `## Journal` section (rejected alternatives, useful when a requirement shows as "deviated")
+   - `decisions.md` — why specific approaches were chosen, and which were later closed
+   - `journal.md` — rejected alternatives, useful when a requirement shows as "deviated"
    - `context.md` — `## Phases` section (which phases completed, which failed)
 5. For each milestone, read the actual implementation:
    - Run `git log --oneline` filtered to commits from that milestone's phases

package/template/hooks/audit-context.sh

@@ -79,7 +79,7 @@ printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e
         const section = /(?:^|\r?\n)## Phases\r?\n([\s\S]*?)(?=\r?\n## |$)/.exec(text);
         const body = section ? section[1] : "";
         for (const line of body.split(/\r?\n/)) {
-          const m = /^-\s*(\S+):\s*(done|in-progress|failed|pending)\b/i.exec(line.trim());
+          const m = /^-\s*(\S+):\s*(done|in-progress|failed|pending|blocked)\b/i.exec(line.trim());
           if (!m) continue;
           const [, phase, statusRaw] = m;
           const status = statusRaw.toLowerCase();
@@ -90,6 +90,19 @@ printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e
           }
         }
       }
+      // decisions.md: one source for what a valid line is — the script that
+      // writes it — rather than a second parser here that drifts from it.
+      const script = path.join(root, ".orchestra", "scripts", "context.mjs");
+      if (fs.existsSync(script)) {
+        try {
+          require("node:child_process").execFileSync(process.execPath, [script, "check"], {
+            cwd: root,
+            stdio: ["ignore", "pipe", "ignore"],
+          });
+        } catch (e) {
+          for (const f of String(e.stdout || "").split("\n").filter(Boolean)) findings.push(f);
+        }
+      }
       return { findings, open };
     }
 
@@ -132,7 +145,7 @@ printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" node -e
 
       const lines = [];
       if (result.findings && result.findings.length) {
-        lines.push("Context audit after compaction — context.md has unresolved defects:");
+        lines.push("Context audit after compaction — the milestone record has unresolved defects:");
         for (const f of result.findings) lines.push(`  - ${f}`);
       }
       if (result.open && result.open.length) {

package/template/hooks/enforce-role.sh

@@ -14,6 +14,8 @@
 # judged against the recorded role. Two terminals are two sessions, so the
 # PM's marker never applies to lead.
 #
+# Lead is held to one rule: phase work starts inside a milestone agent.
+#
 # No marker means no role — discussion mode — and nothing is blocked.
 #
 # Reads the tool call on stdin. Exit 0 allows, exit 2 blocks.
@@ -89,10 +91,26 @@ verdict="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD
     } catch {
       return;
     }
+    // ── Lead ─────────────────────────────────────────────────────────────
+    // Phase work runs inside a milestone agent, so each milestone'"'"'s context is
+    // dropped when it ends. One run kept two milestones in the lead session
+    // instead: 738 calls, context up to 925k tokens. A call from a sub-agent
+    // carries agent_id; one from the lead session itself does not.
+    if (role === "lead") {
+      if (tool !== "Agent" || call.agent_id) return;
+      const type = input.subagent_type || "";
+      if (!/^(engineer-\w+|reviewer|re-reviewer)$/.test(type)) return;
+      if (/^engineer-/.test(type) && /^\s*Hotfix:/.test(String(input.prompt || ""))) return;
+      process.stdout.write(
+        `Lead runs phase work inside a milestone agent, not in its own session — launch a general-purpose agent with the Milestone Agent or Single-Phase Agent prompt in .claude/agents/lead.md, and let it start ${type}. A hotfix engineer'"'"'s prompt starts with a line "Hotfix: <description>".\n`,
+      );
+      return;
+    }
+
     if (role !== "product-manager") return;
 
     // ── The PM ───────────────────────────────────────────────────────────
-    // Writes milestones. Commits them to main and pushes. Nothing else.
+    // Writes milestones. Commits them to delivery.base_branch and pushes. Nothing else.
     const deny = (why) => {
       process.stdout.write(`Outside the PM'"'"'s scope: ${why}\n`);
     };
@@ -140,10 +158,10 @@ verdict="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD
     const cmd = input.command || "";
 
     if (/\bgh\s+pr\s+(create|merge|edit|close|ready|checkout)\b/.test(cmd)) {
-      return deny("the PM never opens, edits or merges a pull request. Milestone files go to main directly; code is lead'"'"'s.");
+      return deny("the PM never opens, edits or merges a pull request. Milestone files go to delivery.base_branch directly; code is lead'"'"'s.");
     }
     if (/\bgit\s+(checkout|switch)\s+(-b|-c|--create|-B)\b/.test(cmd)) {
-      return deny("the PM never creates a branch. Milestone files are committed to main.");
+      return deny("the PM never creates a branch. Milestone files are committed to delivery.base_branch.");
     }
     if (/\bgit\s+(merge|rebase|cherry-pick|reset\s+--hard)\b/.test(cmd)) {
       return deny("the PM never rewrites history or merges.");

package/template/hooks/protect-system-files.sh

@@ -56,7 +56,7 @@ blocked="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD
     }
     if (!root) return;
 
-    // The orchestrator repo is where these files are source. That is a fact
+    // The agentic-team repo is where these files are source. That is a fact
     // about the tree, not about who is asking.
     if (fs.existsSync(path.join(root, "bin/build-template.js"))) return;
 
@@ -114,7 +114,7 @@ Orchestra put it there. Editing it here is lost work: the next upgrade
 overwrites it, and the next project meets the same problem you were about to
 fix.
 
-Change it in the orchestrator repo and reinstall. If it is genuinely
+Change it in the agentic-team repo and reinstall. If it is genuinely
 project-specific, it belongs in the app's own CLAUDE.md, a project skill of
 your own, or .orchestra/config.yml — none of which is overwritten.
 

package/template/hooks/review-rounds.sh

@@ -44,7 +44,7 @@ verdict="$(printf '%s' "$input" | CLAUDE_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD
     }
     if (call.tool_name !== "Agent") return;
     const input = call.tool_input || {};
-    if (input.subagent_type !== "reviewer") return;
+    if (input.subagent_type !== "reviewer" && input.subagent_type !== "re-reviewer") return;
     const prompt = String(input.prompt || "");
 
     // The installer writes into the directory it ran in, which can be an app

package/template/rules/code-standards.orchestra.md

@@ -20,7 +20,8 @@
 This governs volume, never correctness. Validation, error handling, security
 and accessibility are never on this ladder — they apply at every rung,
 covered by their own rules (`security.orchestra.md`,
-`observability.orchestra.md`, the `accessibility` skill), regardless of how
+`observability.orchestra.md`, and the `accessibility` skill where the
+platform has one), regardless of how
 small the change looks. Rung 5 does not skip the wrapper
 `testing-standards.orchestra.md` requires for anything calling a third-party
 library (`src/integrations/<provider>/`) — that wrapper exists for the seam
@@ -28,7 +29,7 @@ test, not for swapability, and the ladder governs what sits on top of it,
 never whether it exists.
 
 **Zero-tolerance rules:**
-- No workarounds — if the right solution is hard, do it right. Flag effort in report or context.md.
+- No workarounds — if the right solution is hard, do it right. Flag the effort in your report.
 - No unused code — delete dead imports, functions, files. Don't comment out.
 - No breaking changes without migration — update every consumer.
 - Current library versions only — verify before using, don't assume from memory.

package/template/rules/design-parity.orchestra.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - "designs/**"
+---
+
 # Design Parity
 
 ## What a design source is
@@ -49,9 +54,15 @@ skipped. That is an honest unverified, not a pass.
 designs/
 ├── <screen>.png          the design, committed, mirroring the screen structure
 ├── .fetched/             a URL design, fetched once at milestone start
-└── .captures/            what was built, committed so the PR can show it
+├── .captures/            what was built, committed so the PR can show it
+└── .reports/             machine output of a comparison, gitignored
 ```
 
+Only the images a pull request shows are committed. A comparison tool's
+output — JSON reports, logs, diffs — goes to `designs/.reports/`, which is
+never committed: it is regenerated from the images, and one project committed
+~100k lines of it, which agents then read back as context.
+
 A URL is fetched **once** into `designs/.fetched/`, when lead composes the
 phase, not at each comparison. The capture goes to `designs/.captures/` and is
 committed with the change, because `gh` cannot upload an image and a

package/template/rules/observability.orchestra.md

@@ -35,6 +35,7 @@ Depth on what "handled" means — typed errors, propagation, what the user
 sees, degrading instead of crashing — in
 `.claude/skills/error-handling/SKILL.md`.
 
+<!-- platforms: backend -->
 ## Structured logging
 
 Logs are data, not prose. JSON, one event per line.
@@ -57,6 +58,7 @@ Logs are data, not prose. JSON, one event per line.
 - Every line carries the release and environment, so a log and an error
   report line up against the same deploy.
 
+<!-- platforms: backend -->
 ## Health is two endpoints, not one
 
 - **`/health`** — liveness. The process is up. Cheap, no dependencies.
@@ -76,6 +78,7 @@ anyway.
 that makes it fail; if you add a dependency, add its probe and its failing
 test in the same change.
 
+<!-- platforms: backend -->
 ## Releasing
 
 There is no percentage canary on Railway. What protects a release is:

package/template/rules/performance.orchestra.md

@@ -122,6 +122,7 @@ Where the runtime is single-threaded, a synchronous call on a request path
 stops every other request, not just this one. Blocking work there is a defect
 even when it is fast in isolation.
 
+<!-- platforms: web, expo, ios, android -->
 ## Rendering and interaction, wherever the UI runs
 
 The words differ per platform; the constraints do not.
@@ -137,6 +138,7 @@ The words differ per platform; the constraints do not.
 - **Never block the thread that draws.** Move parsing, crypto, image work and
   large loops off it.
 
+<!-- platforms: web -->
 ## The shipped size is a budget
 
 Whatever the user downloads or installs has a number, and the number only goes
@@ -144,6 +146,7 @@ down. `.claude/rules/testing-standards.orchestra.md` holds the ratchet: it may
 fall and may not rise, and deliberate growth is re-recorded in its own commit
 so it is a decision rather than a drift.
 
+<!-- platforms: web, expo, backend -->
 ## What is enforced
 
 Only what can be decided precisely. Complexity, cache lifetime, index choice
@@ -181,6 +184,7 @@ as a library version.
 ## Depth
 
 `.claude/skills/code-optimizer/SKILL.md` is for optimising code that already
-exists. `.claude/skills/core-web-vitals/SKILL.md` is web-specific. Neither
+exists. `.claude/skills/core-web-vitals/SKILL.md` is web-specific, and installed
+only for web. Neither
 covers writing something performant the first time, which is what this rule is
 for.

package/template/rules/phase-limits.orchestra.md

@@ -1,3 +1,3 @@
 # Phase Limits
 
-**Scope guard:** Working on something NOT in phase acceptance criteria → STOP. Note in context.md, don't implement.
+**Scope guard:** Working on something NOT in phase acceptance criteria → STOP. Name it in your result's notes, don't implement; lead records it with `.orchestra/scripts/context.mjs journal`.

package/template/rules/pull-request.orchestra.md

@@ -1,3 +1,8 @@
+---
+paths:
+  - ".github/**"
+---
+
 # Pull Requests
 
 **One task, one PR.** Always — there is no mode in which work reaches the
@@ -44,7 +49,7 @@ Open with a body file, never an inline string — the body contains newlines,
 a table, and backticks:
 
 ```bash
-gh pr create --title "#<task-id> - <subject>" --body-file .git/PR_BODY.md
+gh pr create --base <delivery.base_branch> --title "#<task-id> - <subject>" --body-file .git/PR_BODY.md
 ```
 
 ## Naming
@@ -68,7 +73,7 @@ accepts `#<task-id> - <subject>` alongside the conventional form for exactly
 this case. Without that, the delivery flow would produce the one commit the
 repo's own gate rejects.
 
-Record the returned URL. Lead reports it and stores it in `context.md`, so a
+Record the returned URL. Lead reports it and stores it in the phase's note (`context.mjs phase … "pr: <url>"`), so a
 later session can find the PR without searching.
 
 Reading the change is `gh pr diff <n>`, and a diff read straight into

package/template/rules/role-boundaries.orchestra.md

@@ -1,3 +1,10 @@
+---
+paths:
+  - ".orchestra/**"
+  - ".claude/**"
+  - "CLAUDE.md"
+---
+
 # Role Boundary Enforcement
 
 Before writing ANY file, check your role's ownership scope.
@@ -8,8 +15,8 @@ Before writing ANY file, check your role's ownership scope.
 |------|-----------|----------------|
 | Orchestrator | `.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`, `docs/` | Refuse |
 | PM | `.orchestra/milestones/*` (prd, milestone, grooming, phases) | Refuse |
-| Lead | `.orchestra/milestones/*/context.md` | Refuse |
-| Scaffolder | `.orchestra/config.yml` (verification, tracker, observability keys only), scaffolded app files, repo config | Refuse |
+| Lead | `.orchestra/milestones/*/{context,decisions,journal}.md`, through `.orchestra/scripts/context.mjs` | Refuse |
+| Scaffolder | `.orchestra/config.yml` (verification, tracker, observability, `delivery.base_branch`, `project.platforms` keys only), scaffolded app files, repo config | Refuse |
 | Tracker | Tracker id frontmatter in `.orchestra/milestones/*` | Refuse |
 | Sub-agents | Only what phase `## Scope` defines | Refuse |
 | Reviewer | Review verdict in phase file only | Refuse |
@@ -38,7 +45,7 @@ Two questions decide it, and neither is "which role is running": a slash
 command is a markdown prompt and cannot export anything a hook could read on
 its own, so a guard built only on the role would never fire.
 
-**Which repo is this?** In the orchestrator repo these files are source, and
+**Which repo is this?** In the agentic-team repo these files are source, and
 the hook allows everything. Elsewhere they are build output.
 
 **Did Orchestra put this file here?** `.orchestra/.installed.json` records
@@ -63,7 +70,7 @@ Neither are `.orchestra/milestones/`, `blueprints/`, roles you create, or
 skills and rules you write: none of them is in the manifest, because the
 installer preserves them.
 
-When it blocks: make the change in the orchestrator repo and reinstall, or —
+When it blocks: make the change in the agentic-team repo and reinstall, or —
 if it is genuinely project-specific — put it in the app's own `CLAUDE.md`, a
 project skill of your own, or `config.yml`, none of which is overwritten.
 
@@ -85,14 +92,22 @@ any `Agent` launch other than `milestone-reviewer` and `tracker`; any
 backlog one. The last three came from one afternoon: the word "ultracode" in
 a message told the platform to use the Workflow tool, and a PM whose role
 said "cannot review code" ran a multi-agent code review, recommended itself
-for it, and opened the task straight into `in progress`. Lead and the
-Orchestrator are recorded and, for now, not restricted — lead's sub-agents
-write code in the same session, and a restriction there would block the
-work it exists to do.
+for it, and opened the task straight into `in progress`.
+
+Lead is held to one rule: phase work starts inside a milestone agent. An
+`engineer-*`, `reviewer` or `re-reviewer` launched from the lead session
+itself is refused; one launched by a milestone agent passes, because a call
+from a sub-agent carries `agent_id` and one from the session does not —
+verified against a live payload. A hotfix engineer whose prompt starts with
+`Hotfix:` passes. One run kept two milestones in the lead session and grew
+to 738 calls and a 925k-token context. Sub-agents share the session id, so
+the role marker reaches them; lead's own sub-agents still write code, which
+is why nothing else is restricted. The Orchestrator is recorded and not
+restricted.
 
 Two things are structural rather than hook-judged, because they do not
 depend on the role. `Workflow` is denied in the project's `settings.json`;
-no role runs one. The reviewer and the milestone reviewer carry
+no role runs one. The reviewer, the re-reviewer and the milestone reviewer carry
 `disallowedTools: [Write, Edit, NotebookEdit]` in their frontmatter; they
 review, and Claude Code removes the tools rather than asking them not to.
 

package/template/rules/security.orchestra.md

@@ -52,7 +52,7 @@ staged changes, where it is still cheap to fix.
 `scripts/policy-check.mjs` runs in the gate. These are the checks it makes
 that belong to this rule — it decides others too;
 `.claude/rules/performance.orchestra.md` and
-`.claude/rules/comments.orchestra.md` each list their own:
+`.claude/rules/comments.orchestra.md` each list their own where they apply:
 
 | Check | What fails |
 |---|---|

package/template/rules/stuck-detection.orchestra.md

@@ -9,7 +9,7 @@ You are **stuck** when any of these happen:
 ## Recovery Protocol
 
 1. **STOP immediately.** Do not attempt another fix.
-2. **Log** in context.md: phase name, symptom, attempts, root cause hypothesis.
+2. **Log** it: `node .orchestra/scripts/context.mjs journal <m> <phase> "stuck: <symptom>; tried <attempts>; likely <cause>"` — or, as a sub-agent, put it in your result's notes for lead to record.
 3. **Try a different approach** (ONE attempt):
    - Same code fix failed? → entirely different implementation strategy
    - Dependency broken? → alternative library

package/template/rules/testing-standards.orchestra.md

@@ -15,6 +15,7 @@ if the suite covers the seams where our code meets someone else's.
 Snapshot tests do not satisfy this. A snapshot passes while a handler
 silently stops firing — assert behaviour, not markup.
 
+<!-- platforms: backend -->
 ## Backend — the shape
 
 The test pyramid is wrong for a backend. It comes from an era when starting
@@ -52,7 +53,7 @@ forbids this.
 - Each test creates the data it needs. A shared seed fixture is what makes
   a suite unmaintainable somewhere around test three hundred.
 
-### Fake external services at the network boundary
+## Fake external services at the network boundary
 
 Intercept the HTTP call — MSW or a stub server. Do **not** mock your own
 `sendEmail()`.
@@ -60,7 +61,7 @@ Intercept the HTTP call — MSW or a stub server. Do **not** mock your own
 Mocking your own wrapper means the wrapper is never tested, and the wrapper
 is exactly where a provider's API change bites you.
 
-### Test data
+## Test data
 
 Synthetic, built by factories, created per test. Never a copy of production
 data — it carries PII and it drifts.
@@ -94,6 +95,7 @@ Do not chase the global number with unit tests. If the integration tests
 are real, coverage arrives on its own. If tests are being written to move a
 percentage, the gate has started doing harm — say so rather than complying.
 
+<!-- platforms: web, expo, backend -->
 ## Mutation testing
 
 Coverage says a line ran. Mutation says the line was **checked**.
@@ -113,6 +115,7 @@ On an app using TS 7 the scaffolder skips the install and says so — do not
 work around it by pinning TypeScript backwards. The gate turns on by itself
 once Stryker supports the new compiler.
 
+<!-- platforms: web -->
 ## Web — jsdom is not a browser
 
 It has no layout engine. `getBoundingClientRect` returns zeros, nothing
@@ -137,6 +140,7 @@ item here.
 
 Depth in `.claude/skills/web-testing/SKILL.md`.
 
+<!-- platforms: expo -->
 ## Mobile is a different shape
 
 Jest does not run React Native — `jest-expo` runs components in Node against
@@ -151,10 +155,9 @@ expo-doctor
 expo install --check
 ```
 
-Depth in `.claude/skills/mobile-testing/SKILL.md`. Native iOS and Android
-have their own shapes again — `.claude/skills/ios-testing/SKILL.md` and
-`.claude/skills/android-testing/SKILL.md`.
+Depth in `.claude/skills/mobile-testing/SKILL.md`.
 
+<!-- platforms: ios, android -->
 ## Native has two more shapes
 
 **iOS:** a green unit suite does not prove the app launches. A missing
@@ -175,6 +178,7 @@ accessibility instead of review noticing it.
 Depth in `.claude/skills/ios-testing/SKILL.md` and
 `.claude/skills/android-testing/SKILL.md`.
 
+<!-- platforms: web -->
 ## The bundle has a budget, and it is a ratchet
 
 Same shape as the coverage ratchet: the committed baseline is whatever the
@@ -187,6 +191,7 @@ browser downloads.
 Deliberate growth is re-recorded on purpose, in its own commit, so it is a
 decision somebody made rather than a number that drifted.
 
+<!-- platforms: web, expo, backend -->
 ## A build is part of the suite
 
 `tsc --noEmit` accepts an app that fails to bundle, and neither tests nor

package/template/rules/tracker-authority.orchestra.md

@@ -1,3 +1,9 @@
+---
+paths:
+  - ".orchestra/milestones/**"
+  - ".orchestra/trackers/**"
+---
+
 # Tracker Authority
 
 `tracker.provider` in `.orchestra/config.yml` decides who owns requirements.
@@ -24,7 +30,9 @@ The milestone directory holds pointers, and only pointers:
   tracker.yml     committed   provider, epic id, task ids, urls
   phases/*.md     committed   the PM's draft — what export pushes; lead never reads it
   .cache/         gitignored  requirement text, fetched once per run
-  context.md      committed   lead's execution log — local by nature
+  context.md      committed   lead's state: status, phases, codebase map
+  decisions.md    committed   lead's decisions, open until closed
+  journal.md      committed   what was tried and why it lost
 ```
 
 The draft is not a second source of truth, because nothing reads it but

package/template/skills/push-notifications/SKILL.md

@@ -17,7 +17,7 @@ arrives.
 Push needs a build with your own credentials, on a real device, with the app
 in each of three states — foreground, background, terminated. Anything less
 tests the mock. This is the same reason the device layer is not optional in
-`.claude/skills/mobile-testing/SKILL.md`.
+`.claude/skills/mobile-testing/SKILL.md`, on Expo.
 
 Resolve the SDK's current API and constraints from its own docs at
 implementation time. This area changes across SDK releases, and a handler