@azure-id/orc 0.55.0

package/templates/skills/orc/config.md

@@ -0,0 +1,389 @@
+# ORC — Config
+
+This file is the **shipped defaults**. Central knobs the orchestrator reads at
+run start. Override any value for a single run without editing the file.
+
+## Config resolution (defaults ← override file)
+
+At run start, resolve **each key independently** as: **default (this file), then
+the user override on top.** The override lives at `.claude/orc.config.yaml`
+(project `.claude/` root), holds ONLY the keys the user changed, and is written
+exclusively by the **`orc config`** CLI. It sits OUTSIDE `templates/`, so `orc
+update` never clobbers it.
+
+Per-key means: a key present in `orc.config.yaml` uses the override value; a key
+NOT present there falls back to this file's default — independently, key by key.
+Example: if the override contains only `max_wave_tasks: 5`, then `max_wave_tasks`
+is 5 and every other key (`batch_pause_every`, `rubric_bands`, `max_scouts`,
+`default_analysis_depth`, …) still comes from this file's defaults. If the
+override file is absent entirely, use these defaults unchanged. A per-run inline
+override still wins over both.
+
+> Config editing is a CLI concern, not a slash command — it's pure file I/O, so
+> it runs deterministically with zero model tokens. Users run **`orc config`**
+> (interactive menu) or `orc config set <key> <value>` in their terminal; this
+> skill only READS the resolved values at run start.
+
+```yaml
+# --- Wave grouping ---
+max_wave_tasks: 3          # max parallel tasks per wave (hard cap; overflow → next wave).
+                           # Waves are computed for EVERY run (sequential too) —
+                           # dispatch style is intra-wave concurrency only.
+
+# --- Batch pausing ---
+batch_pause_every: 2       # waves between MANDATORY stop-and-continue pauses.
+                           # After wave W, if W % N == 0 AND a later wave exists,
+                           # the stop is a HARD gate (not orchestrator judgment) —
+                           # see references/stop-and-resume.md. The exact schedule
+                           # is confirmed at intake (Phase 2) and stored as
+                           # pause_schedule in the checkpoint.
+
+# --- Rubric width (the "metrix") ---
+rubric_bands: 5            # how many scoring bands the rubric REPORTS. Range 2–8.
+                           # Granularity only — it no longer selects a preset.
+                           # The score→model mapping is the SINGLE 8-band table
+                           # below, used regardless of this value.
+
+# --- Analysis (System Analyst) ---
+max_scouts: 3              # max parallel read-only code scouts in DEEP analysis mode
+default_analysis_depth: standard   # standard | deep — depth gate default (run still confirms)
+
+# --- Test authoring (opt-in Phase 6.5; ORC writes test cases, never runs them) ---
+generate_tests: false      # author test cases before ship? (run confirms at intake)
+
+# --- Code-pattern findings (make executors match the project's house style) ---
+pattern_findings: ask      # ask | on | off — on an FE/BE cache miss during /orc:
+                           #   ask → P0 prompt (learn via orc-pattern, or agnostic)
+                           #   on  → auto-codify on miss, no prompt
+                           #   off → always agnostic (invariants only), never ask
+orc_wiki_pattern_findings: false  # orc-wiki also codifies ALL detected langs during
+                                  #   its scan (rides under the wiki's scan-consent)
+
+# --- Repair memory (gotchas — what this project has already gotten wrong) ---
+gotchas: on                # on | off — record a gotcha when a repair loop goes
+                           #   red → green, and inject the SCOPE-MATCHING ones
+                           #   into executor slices. Lives at
+                           #   .claude/orc/gotchas.md — outside templates/, never
+                           #   in the install manifest, so update/prune can never
+                           #   touch it. NEVER injected unfiltered.
+gotchas_max: 40            # live entries before the lowest-value tail is archived
+                           #   to gotchas-archive.md (archived, never deleted).
+
+# --- Mock example + drift recovery (Phase 6.7 — implementation lanes only) ---
+mock_example: ask          # ask | on | off — post-verify mocked runnable example
+                           #   (mock-examples/<change-slug>/ at project root; NEVER
+                           #   committed — ship never stages it, no .gitignore edit):
+                           #   ask → MANDATORY offer after a green verify/smoke gate
+                           #   on  → always build; off → never. Drift answer →
+                           #   DRIFT-FROM recovery (_shared/drift-recovery.md, cap 2).
+
+# --- TDD anchor (plan-time acceptance tests; full orc + ultra ALWAYS on) ---
+# SCOPED (v0.41.0): each tdd_spec entry carries a `disposition` derived from the
+# planner's facets — new-surface | behavior-change get tests; covered-by-existing
+# (cites an existing test) and no-behavior (constants, translation strings, docs,
+# config) get NONE; no-runner is the whole-run exemption. A task with a cited
+# facets.risk[] can NEVER be scoped out. There is no key for this: a switch here
+# would just restore the tautological tests it removes.
+tdd_loop_max: 3            # max implement→test→repair iterations per task in the
+                           #   TDD gate; cap hit → STOP SEQUENCE + honest red report.
+                           #   Lane policy (fixed, not configurable): full orc +
+                           #   ultra always on · orc-mini ONE intake question ·
+                           #   orc-fast off (no planner) · orc-diy `tdd` flow key ·
+                           #   standalone /orc-plan ON (a saved plan's only consumers
+                           #   are the TDD-always build lanes, so a plan with no
+                           #   tdd_spec is unusable by the lane that runs it).
+
+# --- Stacked PRs (Phase 8 gate; full /orc + /orc-ultra only) ---
+stacked_pr: ask             # ask | on | off — what happens when the change is too
+                            #   big for one PR (threshold below):
+                            #   ask → ONE P0 question (stack it, or one regular PR)
+                            #   on  → take "yes" without asking
+                            #   off → never offer; always one regular PR
+                            #   Never fires in orc-mini / orc-fast (the fast lane
+                            #   never stops the chat) or orc-diy (compile-owned).
+stacked_pr_loc: 1000        # change LoC (additions+deletions, exclusions applied)
+                            #   >= this → stack candidate. SAME number is the
+                            #   per-layer LoC ceiling: a change that cannot fit in
+                            #   one layer's budget is what is worth stacking.
+stacked_pr_files: 20        # changed files >= this → stack candidate; also the
+                            #   per-layer hard max (soft target = half of it).
+stacked_pr_max_layers: 6    # soft layer cap: <= cap proceed · cap+1..cap+2 warn +
+                            #   explicit override · beyond → STOP (multiple stacks
+                            #   or a phased release). N layers = N full CI runs.
+
+# --- Security pass (opt-in Phase 5.5; OFF by default) ---
+security_review: off       # off | ask | on — fires only on runs where a task
+                           #   scored ≥ 70 (the existing risk floor):
+                           #   off → skip silently (default)
+                           #   ask → one prompt after review, user decides
+                           #   on  → dispatch the security pass without asking
+
+# --- Run cost budget (opt-in hard stop; OFF by default) ---
+run_budget_dispatches: 0   # 0 = off. Above 0, the Phase-1 `forecast:` block
+                           #   estimates how many subagents this run will
+                           #   dispatch; exceeding this number STOPS the run
+                           #   before wave 1 — a hard gate with the batch
+                           #   pause's discipline, never a hint — and offers
+                           #   proceed / a cheaper lane / re-plan smaller.
+
+# --- Opus-5-only dispatch (HARD-GATED, FORCING — default off) ---
+opus5_only: false          # true → EVERY dispatched role resolves to a claude-opus-5
+                           #   agent, effort as the only cost dial. Outranks BOTH
+                           #   rubric_bands_override and the whole fable5_* block.
+                           #   Never forced: the Haiku trace writer, orc-diy (compile-
+                           #   owned). Needs an Opus 5 main session or every dispatch
+                           #   downgrades. See _shared/opus5-only.md.
+
+# --- Fable 5 role override (HARD-GATED — nothing changes unless enabled) ---
+#     (entirely INERT while opus5_only: true)
+fable5_enabled: false      # master gate. false = inert (this whole block does nothing).
+fable5_effort: medium      # medium | high | xhigh | max — effort for the Fable 5 role agents.
+                           #   The `orc config set fable5_effort` CLI rewrites the effort:
+                           #   line in the installed orc-<role>-fable-5 agents.
+fable5_roles: []           # subset of [analyze, plan, advisor, judge, review]. Each listed
+                           #   role dispatches its orc-<role>-fable-5 variant instead of the
+                           #   default. advisor/judge are ultra-lane only. Empty = no effect.
+
+# --- Artifact locations (internal by default) ---
+run_dir: .claude/orc/run                  # run folders (checkpoint, state-of-play,
+                                          #   intent-spec). Lives OUTSIDE the payload
+                                          #   trees `orc update` replaces, so an
+                                          #   update/doctor --fix can never destroy a
+                                          #   mid-run checkpoint. Pre-0.34.1 state at
+                                          #   .claude/skills/orc/run/ is migrated once.
+analyzer_dir: .claude/skills/orc/analyzer
+planner_dir:  .claude/skills/orc/planner
+report_out_dir: analyst_report            # project-root copy target on report-only
+
+orchestrator_model: claude-opus-4-8       # main session; high effort (never downgraded)
+
+# --- Retro delivery (/orc-retro files its report upstream; PR preferred, issue fallback) ---
+retro_repo: azure-id/orc      # GitHub owner/repo that receives retro reports.
+                              # /orc-retro REQUIRES a delivery channel (authed gh
+                              # CLI or a GitHub MCP) and refuses to run without one.
+
+# --- Behavior trace logging (PERMANENT — always on, not a toggle) ---
+# Every ORC run writes a persistent behavior trace; there is no on/off key.
+log_dir: .claude/orc/logs     # persistent trace folder — NEVER deleted on completion
+
+# --- Wiki freshness (COVERAGE-RELATIVE, computed on read by `orc wiki status`) ---
+wiki_fresh_max: 10            # per-doc commit distance < this → FRESH (silent)
+wiki_aging_max: 30            # distance ≤ this → AGING (notice); beyond → STALE
+wiki_refresh_ask_tasks: 3     # post-ship refresh ask fires when tasks ≥ this…
+wiki_refresh_ask_files: 10    # …or the run's touched files exceed this (full/ultra lanes)
+
+# --- Cross-repo crosslink snapshot freshness (Signal-B; DAY-based, computed on read) ---
+crosslink_fresh_days: 10      # days since sync ≤ this → FRESH cross-repo hint
+crosslink_aging_days: 15      # ≤ this → AGING; beyond → STALE (advisory only, never blocks)
+
+# --- Wiki delta refresh (`orc wiki impact` — the default refresh path) ---
+wiki_delta_full_threshold: 30 # TOUCHED docs above this % of registered docs →
+                              #   impact recommends a FULL refresh (user decides;
+                              #   never silently full)
+```
+
+## Score → model table (executor agent dispatched by name)
+
+The orchestrator scores each task 0–100, then maps to a model via this SINGLE
+canonical 8-band table, and dispatches the matching **executor agent**. There is
+no longer a narrow/wide preset choice — `rubric_bands` sets scoring granularity
+only, never which table is used.
+
+| Score | Model | Effort | Executor agent |
+|-------|-------|--------|----------------|
+| [0,30)   | claude-haiku-4-5  | —      | orc-executor-haiku-4-5 |
+| [30,40)  | claude-sonnet-4-6 | medium | orc-executor-sonnet-4-6-med |
+| [40,55)  | claude-sonnet-4-6 | high   | orc-executor-sonnet-4-6-high |
+| [55,65)  | claude-sonnet-5   | high   | orc-executor-sonnet-5-high |
+| [65,70)  | claude-opus-4-7   | medium | orc-executor-opus-4-7-med |
+| [70,80)  | claude-opus-4-7   | high   | orc-executor-opus-4-7-high |
+| [80,90)  | claude-opus-4-8   | high   | orc-executor-opus-4-8-high |
+| [90,100] | claude-opus-5     | high   | orc-executor-opus-5-high |
+
+(Haiku has no effort ladder — that agent carries no `effort:` field.) The risk
+floor (≥70) lands `orc-executor-opus-4-7-high` at minimum in THIS table — under
+the Opus-5-only preset below it lands `orc-executor-opus-5-med` instead. The top
+band dispatches **Opus 5 high** — it needs an Opus 5 MAIN session or it silently
+falls back to the session model (the tier-honesty rule reports the downgrade).
+
+### The Opus-5-only ladder (`opus5_only`, default **false**)
+
+One model, EFFORT as the cost dial. Off by default; nothing changes until set.
+
+| Score | Model | Effort | Executor agent |
+|-------|-------|--------|----------------|
+| [0,40)   | claude-opus-5 | low    | orc-executor-opus-5-low |
+| [40,80)  | claude-opus-5 | medium | orc-executor-opus-5-med |
+| [80,100] | claude-opus-5 | high   | orc-executor-opus-5-high |
+
+Rationale (why the key exists): deep SWE-benchmark work on cost vs efficiency
+across Claude models finds a single Opus 5 agent with the effort ladder the
+most efficient setup — model-class variety traded for effort variety.
+**Tier cost:** today ONE band in eight needs an Opus 5 main session; with this
+on, EVERY dispatch does, so a lower session downgrades every task (warn-only —
+a hook can gate effort, never model). **Scope:** this key is NOT executor-only.
+It also forces every fixed role (see below) across every lane. orc-diy's table
+stays compile-owned and reads only `orc-diy.config.yaml`, never this file.
+
+### Resolution — highest wins
+
+1. `opus5_only: true` — the 3-band preset above, and every fixed role forced to
+   its Opus 5 variant. It FORCES: while on, it outranks BOTH a hand-written
+   `rubric_bands_override` and the whole Fable 5 role override.
+2. `rubric_bands_override` — hand-written `{min, max, agent}` rows (hand-edit
+   only; deliberately not a CLI key). Wins over the default table.
+3. the default 8-band table.
+
+`rubric_bands` sets scoring GRANULARITY only, in every case — it never selects a
+table. Whichever table resolves, **show it** with the Phase 2 scoring table and
+record the mode in the `CONFIG` trace line: an un-shown table is as unaccountable
+as an un-shown number.
+
+### Override
+To use custom band edges/models, set `rubric_bands_override:` with your own
+list of `{min, max, agent}` rows; the orchestrator uses it instead of the table.
+
+## Fixed-role agents (not score-mapped)
+| Role | Agent |
+|------|-------|
+| System Analyst | orc-system-analyst-opus-5-high |
+| Requirement Planner | orc-planner-opus-5-med |
+| Reviewer | orc-reviewer-opus-5-med |
+| Verifier | orc-verifier-opus-5-med |
+| Mini analyst | orc-analyze-mini-sonnet-5-high |
+| Mini planner | orc-planner-mini-sonnet-5-high |
+| Mini executor | orc-executor-sonnet-5-high (reused) |
+| Pattern codifier | orc-pattern-codifier-sonnet-5-high |
+| Ultra advisor (/orc-ultra only) | orc-advisor-opus-5-xhigh |
+| Ultra judge (/orc-ultra only) | orc-judge-opus-5-xhigh |
+
+**Opus-5-only override (forcing):** when `opus5_only: true`, every role above
+that is not already `claude-opus-5` dispatches its Opus 5 variant instead —
+mini analyst → `orc-analyze-mini-opus-5-med`, mini planner →
+`orc-planner-mini-opus-5-med`, mini executor → `orc-executor-opus-5-low`,
+pattern codifier → `orc-pattern-codifier-opus-5-med` — plus the roles owned by
+other lanes (scout, wiki scanner, CLAUDE.md writer, retro miner, fast
+executor). The full mapping, the two exclusions (the Haiku trace writer and
+orc-diy) and the tier consequence are in `../_shared/opus5-only.md`. It
+outranks the Fable 5 override below.
+
+**Fable 5 role override:** (INERT while `opus5_only: true`) when
+`fable5_enabled: true`, each role in
+`fable5_roles` dispatches its `orc-<role>-fable-5` variant INSTEAD of the default
+above (`analyze`→`orc-analyst-fable-5`, `plan`→`orc-planner-fable-5`,
+`advisor`→`orc-advisor-fable-5`, `judge`→`orc-judge-fable-5`,
+`review`→`orc-reviewer-fable-5`). Same slice, same contract. See
+`../_shared/fable5-override.md`.
+
+## Rules
+- Read at run start via the resolution rule above (defaults ← `orc.config.yaml`
+  override). Missing values use defaults (max_wave_tasks 3, batch_pause_every 2,
+  rubric_bands 5, max_scouts 3, default_analysis_depth standard,
+  generate_tests false, pattern_findings ask, security_review off).
+  Behavior-trace logging is not listed here — it is PERMANENT (always on).
+- `generate_tests` gates the opt-in Phase 6.5 (Test Authoring, default OFF). When
+  on, after Verify the orchestrator dispatches `orc-test-author-opus-5-med` to
+  WRITE test cases (automated files + `TEST-PLAN.md` + a curl bundle for HTTP
+  APIs) — it never runs them; the user tests manually. The manual deliverables
+  are pinned to a visible **`test-generator/<change-slug>/`** folder at the
+  project root (not `.claude/`, not the run folder) and are committed on ship.
+  Full lane runs it as Phase 6.5; orc-mini also offers it (opt-in end-of-run ask
+  on a GREEN smoke gate).
+- `max_scouts` caps the parallel scouts fanned out in the analyst's DEEP mode
+  (never exceeds it, same as max_wave_tasks caps a wave).
+- `default_analysis_depth` only presets the analyst's standard/deep gate — the
+  run still confirms; deep never auto-escalates without consent.
+- `rubric_bands` sets HOW MANY bands the rubric REPORTS (finer or coarser score
+  granularity) — it no longer selects a preset. The score→model mapping is the
+  single 8-band table above, used regardless of `rubric_bands`.
+- max_wave_tasks is a hard cap in wave-grouping.
+- `batch_pause_every` is a DETERMINISTIC hard gate, not a cadence hint: after
+  wave W, `W % N == 0` with a later wave remaining forces the stop sequence
+  (references/stop-and-resume.md). The schedule is computed and confirmed at
+  Phase 2 intake and persisted as `pause_schedule` so resumes enforce it too.
+- Behavior-trace logging is PERMANENT (always on) — there is no `logging` key.
+  Every run, the orchestrator follows `references/trace-protocol.md` and the
+  `orc-trace.js` hook writes a persistent `.txt` under `log_dir`. The hook is the
+  deterministic guarantee: it bootstraps `log_dir` + the run pointer itself and
+  segments the run with `PHASE-EDGE` lines, so a usable trace exists even if the
+  orchestrator never narrates. The RICH narration is dispatched per phase to the
+  pinned Haiku trace writer — never appended from memory.
+- `log_dir` is the persistent trace folder; its top level holds the run `.txt`
+  plus its sidecars (`.pending.json`, `.jsonl`). Unlike the decision log
+  (`run/…md`, deleted on success) traces are NEVER auto-deleted — post-hoc
+  review is the point.
+- `retro_repo` is where `/orc-retro` files its calibration report (PR preferred,
+  issue fallback, AI-readable markdown). The retro hard-gates on a delivery
+  channel — an authed gh CLI or a GitHub MCP server — and does not run at all
+  when neither exists. See the `orc-retro` skill.
+- `pattern_findings` gates the code-pattern subsystem (default `ask`). On an FE/BE
+  cache MISS during Phase 3 dispatch: `ask` → P0 prompt (learn conventions via the
+  `orc-pattern` skill, or proceed language-agnostic); `on` → auto-codify, no prompt;
+  `off` → always agnostic (invariants enforced, conventions imitate neighbor files),
+  never ask. A cache HIT is used silently regardless. The codifier
+  (`orc-pattern-codifier-sonnet-5-high`) writes `.claude/orc/patterns/<lang>-pattern.md`,
+  reused by future runs. See the `orc-pattern` skill.
+- `orc_wiki_pattern_findings` (default `false`, on/off only — no `ask`, because the
+  wiki's scan already has consent) makes `orc-wiki` codify ALL detected languages as
+  a byproduct of its full scan, pre-warming the pattern cache so later `/orc` runs
+  never hit the `pattern_findings` prompt.
+- `fable5_enabled` / `fable5_effort` / `fable5_roles` gate the **Fable 5 role
+  override** (default OFF — a hard P0 gate). Nothing changes unless
+  `fable5_enabled: true`. Then each role in `fable5_roles` (subset of
+  `analyze, plan, advisor, judge, review`) dispatches its `orc-<role>-fable-5`
+  agent instead of the default; `advisor`/`judge` apply only under `/orc-ultra`.
+  `fable5_effort` (medium default) sets those agents' effort — the CLI rewrites
+  their frontmatter on set. Enabled with empty `fable5_roles` = no effect (the
+  CLI warns). The whole block is INERT while `opus5_only: true`. See
+  `../_shared/fable5-override.md`.
+- `opus5_only` (default `false`) is a **forcing** dispatch mode: every scored
+  executor AND every fixed role resolves to a `claude-opus-5` agent, with effort
+  as the only cost dial. While on it outranks `rubric_bands_override` and the
+  entire `fable5_*` block. Two things are never forced: the pinned Haiku trace
+  writer, and orc-diy (compile-owned). Every dispatch then needs an Opus 5 main
+  session — including `/orc-fast`, whose Sonnet-medium session premise holds
+  only while this is off. See `../_shared/opus5-only.md`.
+- **Ultra lane has no config key** — `/orc-ultra` forces its overrides
+  run-scoped (deep analyze, `pattern_findings` on, `generate_tests` on,
+  `security_review` on, executor tier floor) and NEVER writes them to
+  `orc.config.yaml`. See the orc skill's `references/ultra-mode.md`.
+- `wiki_fresh_max` / `wiki_aging_max` set the wiki freshness tier edges. The
+  tier is ALWAYS computed on read, and **`orc wiki status` is the only thing
+  that computes it** (v0.41.0 — `--json` for a machine-readable `.tier`): never
+  hand-run a `git rev-list` against `.claude/orc/wiki-meta.json`. Freshness is
+  **coverage-relative** — a doc is stale only when commits since ITS OWN
+  `scanned_commit` touched files IT covers, and the wiki's tier is its worst
+  doc. (Measuring from the manifest's `scan_commit` — the OLDEST doc's anchor,
+  which a delta refresh deliberately leaves frozen — reported the same hash and
+  a growing distance forever, so the wiki read STALE no matter how often it was
+  refreshed.) A STRUCTURAL blind spot degrades the tier ONE step, never past
+  AGING: that is a coverage gap, not doc rot. FRESH → silent, AGING → notice,
+  STALE → warn (full/mini lanes) or the orc-fast user gate. See
+  `../orc-wiki/references/staleness.md`.
+- `wiki_refresh_ask_tasks` / `wiki_refresh_ask_files` set the BIG-run trigger
+  for the post-ship wiki refresh ask (full + ultra lanes only; guarded on a
+  non-empty wiki). Judged by FINAL counts at ship time.
+- `crosslink_fresh_days` / `crosslink_aging_days` set the day edges for the
+  cross-repo crosslink snapshot age (Signal B — the only day-based tier in the
+  constellation; two repos share no commit axis). The effective cross-repo tier
+  is `min(Signal-A provider-wiki-tier, Signal-B snapshot-age)`, computed on read,
+  advisory only — a stale crosslink warns, never blocks. See
+  `../orc-wiki/references/crosslink.md` + `../orc-wiki/references/staleness.md`.
+- `run_budget_dispatches` (default `0` = off) is the only cost gate ORC has that
+  fires BEFORE money is spent. The Phase-1 `forecast:` block already estimates
+  the run's subagent count from the plan (`references/preflight-report.md`); this
+  key turns that estimate into a **hard stop before wave 1** when it is exceeded
+  — same discipline as `batch_pause_every`, so a run never dispatches past an
+  unacknowledged budget stop. It offers proceed · switch to a cheaper lane ·
+  re-plan smaller, and emits `GATE budget stop|pass :: forecast=<n> limit=<m>`.
+  At `0` the gate never fires and no `GATE budget` line is emitted at all.
+  The estimate is a floor: repairs and requeues push the real count up, never
+  down — so set the budget as a "stop and make me think" line, not a quota.
+- `security_review` gates the opt-in Phase 5.5 security pass (default `off`).
+  The trigger is the EXISTING risk floor: it can only fire on a run where at
+  least one task scored ≥ 70 (security/money/migrations/auth). `ask` → one
+  prompt after review; `on` → dispatch without asking; `off` → skip silently.
+  The pass reuses the reviewer (`phase=security`) with the checklist from
+  `references/security-checklist.md`, sweeping only the run's changed files
+  (wraps Semgrep if installed, never installs tooling). Findings use the same
+  P0–P3 ladder + hard-rule-5 handling.

package/templates/skills/orc/examples/full-run-mock.md

@@ -0,0 +1,73 @@
+# Example — Annotated Full Run (v2.2, dry run)
+
+O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
+orchestrator NEVER implements — it always spawns scored subagents.
+
+U: Orchestrate: merchant notification system — in-app, email digest, prefs page.
+
+## Phase 0 — Intake
+O: Creates run folder run/merchant-notifications/ FIRST.
+   [reads repo: TS/yarn/jest — asks nothing about stack] Rough size: medium+ → 4-question tier (one batched round):
+   1) What should exist when done? 2) Out of scope? 3) How do we know it's done? 4) Patterns/files to avoid?
+U: [answers] no push, no admin; bell count + both digest schedules + prefs persist; follow services/ pattern, don't touch auth_service.
+O: [drafts run/merchant-notifications/intent-spec.md] Sign-off: gate or soft? (default gate)
+U: gate → approved
+
+## Phase 1 — Planning
+O: Planner? U: OpenSpec
+O: [6 tasks with declared_files incl. tests + per-file grounding attestations + sliced acceptance[], depends_on, spec_ref] ⚠ T1/T2 share models/notification.ts → scheduling separates them.
+   Grounding spot-check (Phase 1 exit): globs all `exists` paths — 13/14 present, models/notifcation.ts MISSING (typo) → plan bounced to planner with the miss list → corrected to models/notification.ts ✓.
+
+## Phase 2 — Effort, dispatch style, scoring
+O: Refined: medium, partially dependent. Recommend PARALLEL waves. Confirm? U: yes. Batch pause? U: every 2 waves.
+O: Facet scoring (planner facets → formula → band; facet gate: breadth + fan recomputed, risk cites checked):
+   T1 3·new-surface·stateful·new-tests·fan0/3·low = 6+18+16+8+9 = 57 → sonnet-5-high (keystone — every later task imports its enum)
+   T2 3·imitate·branching·new-tests·fan1/0·low = 6+8+8+8+5 = 35 → sonnet-4-6-med
+   T3 3·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
+   T4 2·imitate·branching·update-existing·fan1/0·low = 6+8+8+4+5 = 31 → sonnet-4-6-med
+   T5 1·mechanical·none·update-existing·fan0/0·low = 2+0+0+4 = 6 → haiku-4-5
+   T6 1·mechanical·none·none·fan0/0·low = 2+0+0+0 = 2 → haiku-4-5
+   Plan: 6 tasks, 3 waves W1{T1} W2{T2,T3,T4} W3{T5,T6}, all spawned. Anticipated escalations? U: none, go.
+
+## Phase 3 — Execution (ALL spawned; orchestrator coordinates only)
+O: [checkpoint + state-of-play written into run/merchant-notifications/ BEFORE dispatch]
+▶ W1: spawn Agent-A(T1, sonnet-5-high) — milestones 40%→100% — return validated ✓ (evidence: `yarn jest models/` exit 0, tail quoted; unmet[] empty) — log: DECISION type enum.
+▶ W2: spawn 3 agents (sonnet-4-6-med each).
+   Agent-C needs_context (1/2): "needs T1's enum interface" → O adjudicates in-scope → re-slices → resumes. (User never bothered.)
+   Agent-C user escalation: "digest send time?" → U: 07:00 fixed → ANSWER broadcast to log.
+   Returns validated ✓ · collision audit clean.
+⏸ BATCH PAUSE (stop sequence):
+   checkpoint ✓ → state-of-play ✓ → dispatch report shown (models/scores) → "Run /usage to see your remaining limits."
+   → resume block:
+   | Continue ORC run `merchant-notifications`.
+   | Read run/merchant-notifications/state-of-play.md, then run/merchant-notifications/checkpoint.json.
+   | Resume from checkpoint phase/wave. Intent-spec approved — do not re-plan. Do not redo done tasks.
+   "Reply continue here, or paste in a fresh session (recommended if long)."
+
+U: [next day, FRESH session, pastes block]
+O: [state-of-play → checkpoint → re-anchored] "Resuming: merchant notifications (in-app+digest+prefs). Still correct?" U: yes.
+▶ W3: spawn T5+T6 (haiku-4-5) → done. All 6 complete.
+
+## Phase 5 — Review (spawned worker, Opus 5 medium)
+O: Code pattern? U: none. Findings (P0–P3 ladder, each P0–P2 anchored file:line + verbatim quote):
+   P1 T2 no pagination — services/notification_list.ts:88 — O spot-checks: Reads line 88, quote matches ✓ → asks user, U: fix it
+   · P3 email_digest naming ×2 · 12 tests added. (An unanchored finding would be auto-P3 — never fixed unasked.)
+
+## Phase 6 — Verify (spawned worker, Opus 5 medium; criteria = definition-of-done)
+   criteria[] with per-line evidence: bell ✓ (test name) · both schedules ✗ (weekly cron missing = P0, unmet criterion, evidence: no cron entry in scheduler.ts) · prefs ✓ → FAILED → quote spot-check ✓ → P0 auto-fix (single attempt, no ask) → re-verify → PASSED. 14/14.
+
+## Phase 7 — Summary
+O: 6 tasks/3 waves/6 spawns/1 pause/1 fresh-session resume · 1 needs_context · 1 escalation · verify fixed_then_passed · branch green. P2 fix-batch: none · Apply the 2 P3 cosmetics? U: no.
+
+## Phase 8 — Ship (orc-pr, reads pr.md)
+O: Branch: feat/notifications. Commit? Push? PR? U: yes all.
+O: Ticket/title/target? U: DRP-482 / Add merchant notification system / develop
+O: ✓ committed → pushed → run/merchant-notifications/DRP-482-add-merchant-notification-system.md from pr.md (base develop).
+   Log deleted · checkpoint + dispatch log KEPT · completion dispatch report shown → "Run /usage to see your remaining limits."
+
+## What this exercises
+always-spawn (even cheap tasks get a subagent) · facet-scored arithmetic · 8-band ladder ·
+per-run folder run/merchant-notifications/ · usage reminder (no programmatic /usage) ·
+planner grounding spot-check catching a hallucinated path · executor evidence (verbatim
+build/test proof) · reviewer quote spot-check before any P0/P1 action ·
+definition-of-done catching the weekly-cron gap · needs_context resolved internally · fresh-session resume.

package/templates/skills/orc/references/analyst-gates.md

@@ -0,0 +1,124 @@
+# Reference — Analyst, Combiner & Plan Gates (orchestrator side)
+
+The orchestrator's deterministic gates around the analyst, the
+context-combiner, and the planner. The roles themselves are defined in
+`../../orc-analyze/SKILL.md`, `../../context-combiner/SKILL.md`, and
+`../subskills/orc-planner/SKILL.md` — this file is what YOU do around their
+dispatches and returns. Load at Phase 0 (analyst dispatch) and Phase 1
+(planner return). Emit a `GATE` trace line (pass|bounce) per check when
+logging.
+
+## Deep-mode scout dispatch (yours)
+
+When the analyst runs in deep mode it returns a `scout_plan` (pass 1). You then
+dispatch ≤ `config.max_scouts` (default 3) parallel
+`orc-scout-sonnet-4-6-high` agents (`orc-scout-opus-5-low` when `opus5_only`
+— `../../_shared/opus5-only.md`; scouts fan out in PARALLEL, so this is the
+mode's largest single cost multiplier) — one coverage area each, read-only — and
+re-dispatch the analyst WITH their evidence bundles for pass 2. Same "return a
+request → you re-slice → re-dispatch" shape as `needs_context`. You never
+analyze; you only dispatch and relay.
+
+## Analyst-return gates (deterministic, before any build option)
+
+1. **Evidence spot-check:** Glob every `files[]` path in the spec +
+   Grep-verify the quoted snippet on **EVERY quote-anchored ref, whatever its
+   `status`** (v0.34.6). It used to check only `exists|conflict` — but the two
+   statuses a GOOD audit most often produces are `resolved` (a challenged row
+   the user decided) and `buildable` (the actual work), so a correctly-triaged
+   analysis was the one the gate barely checked: a real spec had zero
+   `exists|conflict` rows, so the mandated verification covered 0 of 5 refs and
+   a `file:5` citing a quote that lives at `file:4` went through. It is one
+   Grep per ref, and it is the ONLY mechanical defence against a wrong line
+   number reaching the planner. Note the causal shape: that ref started as a
+   line RANGE with no quote (auto-UNVERIFIED per hard rule 2); narrowing it to
+   one line + quote was the CORRECT fix and is what introduced the off-by-one —
+   tightening evidence granularity is itself an error surface, so the gate has
+   to be what catches it.
+2. **Derivation lint:** R# ids, statuses, and context-anchor set must match
+   between report.md and requirement-spec.md.
+
+Any miss → bounce to the analyst with the miss list (one retry, then escalate
+to the user). Refuse take-into-build when the spec has open `UNVERIFIED` or
+lacks `scope_closed: true` (a one-Grep check).
+
+## Combiner tracking (yours; full lane only)
+
+`context-combiner` (`orc-context-combiner-opus-5-high` — Opus 5 high, v0.34.0)
+merges 2+ RELATED, already-confirmed
+analyses from the same run into ONE combined requirement-spec before build.
+
+- **Track the analysis set:** hold the confirmed spec paths of every analysis
+  this run in run state (survives checkpoint/resume).
+- When the user picks "pass to context-combiner" at orc-analyze's Phase F
+  branch menu (offered only once 2+ analyses exist), dispatch
+  `orc-context-combiner-opus-5-high` with that list.
+- The return carries `combined_spec_path` + `coverage_pct` (conservation
+  proof — every source requirement accounted for; must be 100) + `dropped[]` +
+  `stale_evidence[]` + `handoff_ready` — or `combined: false` if the user chose
+  keep-separate at the combiner's relatedness challenge (then fall back to
+  per-analysis stop/build).
+- Offer the build option ONLY when `handoff_ready` is true (the combiner sets
+  it false when `coverage_pct` < 100 OR a conflict is open). On build, continue
+  at Phase 1 with the combined spec exactly like a single requirement-spec.
+
+You never combine; you only track, dispatch, and relay.
+
+## Spec staleness valve (Phase 1, before dispatching the planner)
+
+If the requirement-spec's `git_head` ≠ current HEAD (analysis and build in
+different sessions), re-run the analyst evidence spot-check (paths + quotes)
+BEFORE dispatching the planner; on misses offer re-analyze vs
+proceed-with-flagged.
+
+## Phase 1 exit gate (deterministic, before scoring)
+
+1. **Grounding spot-check:** Glob every path the plan marks
+   `disposition: exists`. A task whose declared paths lack `grounding[]`
+   entries counts as a miss.
+2. **Coverage check:** recompute the planner's coverage echo — every in-scope
+   spec R# / intent-spec DoD line must appear in ≥ 1 task's `requirements[]`;
+   an `orphan` requirement is a miss (the user may explicitly descope instead).
+3. **Graph checks:** cycle detection over `depends_on` + same-file collision
+   over `declared_files` (two tasks sharing a file need a serializing dep or a
+   merge). Both trivial at ≤ 20 tasks — never trust the planner's self-check
+   alone.
+4. **TDD/test-task collision (v0.34.4):** a `tdd_spec` entry whose target file
+   is in the `declared_files` of a task whose `facets.test_surface` is
+   `new-tests` is a miss. The paired TDD task materializes `tdd_spec` BEFORE the
+   task it guards, so that task's planned work is already on disk and
+   green by the time its wave opens — leaving only bad options (dispatch a
+   no-op, silently drop promised coverage, or re-slice mid-run). The planner
+   authored both mechanisms and folds them together itself: extend the
+   materialized file, never re-author it.
+5. **TDD disposition gate (v0.41.0)** — this gate is what lets TDD be skipped
+   safely. Skipping a test is cheap to claim and expensive to get wrong, so
+   every skip must be checkable, and it is checked in BOTH directions: a rule
+   that only ever prevents tests is a rule that deletes coverage.
+   - `disposition` outside the closed set
+     `new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`
+     → miss. (Absent on a pre-v0.41.0 plan → derive from `kind`; never bounce an
+     old plan — see the legacy exception below.)
+   - `covered-by-existing` **without a resolvable `covered_by`** → miss. Glob the
+     cited `path` exactly as check 1 does for `disposition: exists`. "A test
+     already covers this" is the one claim that, if false, silently removes
+     coverage the run promised.
+   - `no-behavior` whose task has `facets.test_surface != none` → miss
+     (self-contradiction: the planner said the surface is testable and that it
+     isn't).
+   - **Safety floor:** any entry that is `covered-by-existing` or `no-behavior`
+     on a task with non-empty `facets.risk[]` → miss, no exceptions. Auth,
+     money, migration, security, concurrency and data-integrity requirements do
+     not ride on another test's coincidence.
+   - `new-surface` / `behavior-change` missing `skeleton` or `given_when_then`
+     → miss.
+   - A disposition that DEVIATES from the derivation table in
+     `../schemas/planning-output.md` without a `reason` → miss. The derivation
+     is the default; departing from it is the thing that needs justifying.
+
+Any miss → the plan is malformed: bounce it back to the planner WITH the miss
+list (one retry), then escalate to the user. **Legacy exception:** a
+pre-v0.7.0 plan resumed from an old checkpoint has no `grounding[]`
+(pre-v0.9.0: no `requirements[]`/`spec_invariants[]`; pre-v0.41.0: no
+`disposition`) — resume it without the
+missing checks; never bounce an old plan.