@azure-id/orc 0.55.0

package/mock-run/orc.md

@@ -0,0 +1,157 @@
+# Mock run — `/orc`
+
+> The full pipeline: understand → plan → score → build in parallel → review →
+> verify → ship.
+
+Use this when the job is a real feature, not a one-line fix.
+
+---
+
+## 1. What it does
+
+`/orc` never writes code itself. It is the **coordinator**. It splits the work
+into tasks, gives each task a score from 0 to 100, and sends each task to the
+**cheapest model that can still do it**. Tasks that do not touch the same files
+run at the same time (a "wave").
+
+It writes everything to disk as it goes, so you can stop any time and come back
+tomorrow — even in a brand new chat.
+
+---
+
+## 2. The run
+
+Rina wants order notes on the checkout page and a new API field.
+
+```
+> /orc add order notes: a note field on checkout, saved with the order,
+  shown on the order page
+```
+
+### Phase 0 — Intake (it asks, you sign off)
+
+```
+Run folder:  .claude/orc/run/order-notes/
+
+I read the repo: TypeScript, vitest, Express. I will not ask you about that.
+Size looks medium. Four questions, one round:
+
+  1  What must exist when this is done?
+  2  What is NOT part of this?
+  3  How will we know it works?
+  4  Any file or pattern to stay away from?
+
+> 1 note box on checkout + note saved + note shown on order page
+> 2 no editing a note after the order is placed, no admin view
+> 3 a new order keeps its note after a page reload
+> 4 follow api/orders/, do not touch api/payments/
+
+Draft written: .claude/orc/run/order-notes/intent-spec.md
+Sign-off:  gate (I stop until you approve)  or  soft?
+
+> gate
+
+Approved.
+```
+
+### Phase 1 — Planning
+
+```
+Planner: ORC's own planner.
+
+5 tasks. Every file path checked against the real repo:
+  14 of 15 paths exist. `api/orders/note_servce.ts` does NOT exist (typo).
+  → plan sent back to the planner → corrected to note_service.ts ✓
+
+TDD: 3 tasks get a red-proof task first. 2 do not:
+  T4  covered-by-existing → api/orders/orders.test.ts:120 (checked, it exists)
+  T5  no-behavior         → a string in web/locales/en.json
+```
+
+### Phase 2 — Scoring (arithmetic, not opinion)
+
+```
+Task                                   facets                     score  model
+T1 order note column + migration       3 files · new · stateful     62   sonnet-5 high
+T2 POST /orders accepts note           2 files · imitate            38   sonnet-4-6 med
+T3 checkout note box                   2 files · imitate            35   sonnet-4-6 med
+T4 order page shows the note           1 file  · mechanical         12   haiku-4-5
+T5 label text                          1 file  · mechanical          4   haiku-4-5
+
+Waves:  W1 {T1}   W2 {T2, T3}   W3 {T4, T5}
+Pause every 2 waves. OK to start?
+
+> yes
+```
+
+### Phase 3 — Building
+
+```
+▶ W1  orc-executor-sonnet-5-high (T1)
+      40% … 100%   returned: build green, `npx vitest run db/` exit 0
+      answered as: claude-sonnet-5 / high          ✓ matches what I asked for
+
+▶ W2  two agents at the same time
+      T3 asked me a question: "note max length?"  → your call:
+
+      > 500 characters
+
+      Answered. Both returned ✓. No two tasks touched the same file.
+
+⏸  PAUSE (2 waves done)
+   Checkpoint saved. To continue in a fresh chat, paste this:
+
+   | Continue ORC run `order-notes`.
+   | Read .claude/orc/run/order-notes/state-of-play.md, then checkpoint.json.
+   | Do not re-plan. Do not redo finished tasks.
+
+> continue
+
+▶ W3  two haiku agents → done. 5 of 5 tasks complete.
+```
+
+### Phases 5–6 — Review, then verify
+
+```
+Review (orc-reviewer-opus-5-med):
+  P1  note is not length-checked on the server — api/orders/create.ts:44
+      I re-read line 44 myself. The quote matches. Fix it?   > yes
+  P3  naming nit ×2  (counted, not fixed)
+
+Verify (orc-verifier-opus-5-med) — against YOUR definition of done:
+  note saved         ✓  orders.test.ts:131
+  note survives F5   ✗  no test covers a reload  → P0, fixed once, re-checked ✓
+  PASSED   18/18 tests green
+```
+
+### Phase 8 — Ship
+
+```
+Branch feat/order-notes. Commit? Push? Open a PR?   > yes to all
+Ticket / title / target?   > SHOP-214 / Add order notes / develop
+
+✓ committed  ✓ pushed  ✓ PR body written from your pr.md template
+
+5 tasks · 3 waves · 5 subagents · 1 pause · 1 question to you · 0 downgrades
+```
+
+---
+
+## 3. What to notice
+
+- **The orchestrator never wrote a line of code.** Even the 4-point label task
+  went to a subagent. That is what keeps it able to run for hours.
+- **A bad file path was caught before any agent started.** The planner claimed
+  `note_servce.ts`; ORC checked the disk and bounced the plan.
+- **The score picked the model, and the trace proves what answered.** Every
+  return says which model really replied, so a silent downgrade is visible.
+- **The pause is real.** It stops. It does not "keep going a bit more".
+
+---
+
+## 4. Related
+
+- The dense, annotated version of this run (written for the model, not for
+  people): [`templates/skills/orc/examples/full-run-mock.md`](../templates/skills/orc/examples/full-run-mock.md)
+- Smaller job? [`/orc-mini`](../templates/skills/orc-mini/examples/mini-run-mock.md)
+- Not sure which lane? [`/orc-route`](orc-route.md)

package/mock-run/the-example-project.md

@@ -0,0 +1,55 @@
+# The example project used in every mock
+
+Every file in this folder tells a story about the **same fake project**, so the
+stories connect. Nothing here is real. No code was run. But every screen, every
+file and every number is written the way the real lane would write it.
+
+---
+
+## `shopcart` — a small web shop
+
+```
+shopcart/
+  web/            React + TypeScript  (the part users see)
+    locales/      en.json, id.json    (all the text on the screen)
+  api/            Node + Express      (the server)
+    payments/     the money code
+    refunds/
+  db/
+    migrations/   Postgres migration files
+  config/
+    app.yaml      has a schema file next to it
+    flags.yaml    has NO schema file
+  package.json    "test": "vitest run"
+```
+
+Two people work on it:
+
+- **Rina** — a developer. She writes both `web/` and `api/`.
+- **Budi** — a product manager. He does not read code.
+
+---
+
+## How to read a mock
+
+Most files have the same parts:
+
+1. **What it does** — in easy English.
+2. **The run** — the full screen: what you type, what ORC says back.
+3. **What it wrote** — the real content of the files it made.
+4. **What to notice** — the two or three things that are easy to miss.
+
+Lines that start with `>` are what **you** type. Everything else is ORC talking.
+
+---
+
+## One rule that is true in every mock
+
+**ORC never guesses and calls it a fact.**
+
+When ORC does not know something, it says so with a word you can see:
+`UNCHECKABLE`, `insufficient history`, `AMBER`, `no card`, `STALE`. It never
+fills a gap with a nice-sounding sentence.
+
+That is the part worth watching for. Most tools always give you an answer. ORC
+will sometimes tell you it does not have one — and that is the useful part.

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@azure-id/orc",
+  "version": "0.55.0",
+  "description": "ORC — an orchestrator skill constellation for Claude Code: intake, planning, scored parallel subagents, code-pattern matching, review, verify, ship, plus a project knowledge-base wiki.",
+  "bin": {
+    "orc": "bin/cli.js"
+  },
+  "files": [
+    "README.md",
+    "README-id.md",
+    "CHANGELOG.md",
+    "bin/",
+    "mock-run/",
+    "templates/"
+  ],
+  "scripts": {
+    "postinstall": "node -e \"try{require('fs').accessSync(require('path').join(__dirname,'bin','cli.js'));console.log('\\nORC installed. Run: orc init  (or orc init --global)\\n')}catch(e){console.error('\\n[orc] WARNING: bin/cli.js missing from this install — the repo/publish was incomplete. Reinstall from a complete source.\\n')}\"",
+    "build:agents": "node bin/build-agents.js",
+    "test": "node --test --test-concurrency=6 test/",
+    "verify": "node bin/build-agents.js --check && node bin/verify-package.js && node bin/verify-contracts.js",
+    "prepack": "node bin/build-agents.js --check && node bin/verify-package.js && node bin/verify-contracts.js && node --test --test-concurrency=6 test/"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "orchestrator",
+    "skills",
+    "agents",
+    "ai"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "github:azure-id/orc"
+  }
+}

package/templates/agents/MODEL-MAPPING.md

@@ -0,0 +1,168 @@
+# ORC Agents — Roster, Model Mapping & Verification
+
+Single-role, model-specific agents. The orchestrator dispatches BY AGENT NAME —
+model is pinned in frontmatter, not requested in prose. No agent is multi-role.
+
+## Executors (score-mapped by the single 8-band table in config.md)
+
+| Score band | Agent | Model | Effort |
+|-----------|-------|-------|--------|
+| [0,30)   | orc-executor-haiku-4-5       | claude-haiku-4-5  | — (no ladder) |
+| [30,40)  | orc-executor-sonnet-4-6-med  | claude-sonnet-4-6 | medium |
+| [40,55)  | orc-executor-sonnet-4-6-high | claude-sonnet-4-6 | high |
+| [55,65)  | orc-executor-sonnet-5-high   | claude-sonnet-5   | high |
+| [65,70)  | orc-executor-opus-4-7-med    | claude-opus-4-7   | medium |
+| [70,80)  | orc-executor-opus-4-7-high   | claude-opus-4-7   | high |
+| [80,90)  | orc-executor-opus-4-8-high   | claude-opus-4-8   | high |
+| [90,100] | orc-executor-opus-5-high     | claude-opus-5     | high |
+
+Score→executor mapping lives in config.md (one canonical 8-band table;
+`rubric_bands` is granularity only, not a preset selector).
+
+## Fixed-role agents
+
+| Agent | Model | Effort | Role |
+|-------|-------|--------|------|
+| orc-system-analyst-opus-5-high | claude-opus-5 | high | doc analysis |
+| orc-planner-opus-5-med | claude-opus-5 | medium | planning |
+| orc-reviewer-opus-5-med | claude-opus-5 | medium | review |
+| orc-verifier-opus-5-med | claude-opus-5 | medium | verify (+ /orc-verify) |
+| orc-test-author-opus-5-med | claude-opus-5 | medium | test authoring (opt-in Phase 6.5; writes tests, never runs) |
+| orc-analyze-mini-sonnet-5-high | claude-sonnet-5 | high | mini analysis |
+| orc-planner-mini-sonnet-5-high | claude-sonnet-5 | high | mini planning |
+| orc-scout-sonnet-4-6-high | claude-sonnet-4-6 | high | deep-analysis code scout (read-only) |
+| orc-context-combiner-opus-5-high | claude-opus-5 | high | combine 2+ related analyses (full lane) |
+| orc-pattern-codifier-sonnet-5-high | claude-sonnet-5 | high | reconcile per-language playbook vs. project files → cached code-pattern (opt-in) |
+| orc-retro-sonnet-5-high | claude-sonnet-5 | high | mine behavior traces → calibration report (/orc-retro; read-only) |
+| orc-wiki-scanner-opus-4-8-high | claude-opus-4-8 | high | scan ONE wiki coverage area → evidence-anchored doc body + crosslink tags (/orc-wiki only; read-only against the project). The DEEP half of the v0.46.0 tier ladder: first scan · STRUCTURAL · wide delta · a new exported symbol |
+| orc-wiki-scanner-sonnet-5-high | claude-sonnet-5 | high | the LIGHT half of the same ladder — an existing doc whose covered files moved by a small, no-new-surface delta. IDENTICAL return contract; it escalates with `needs_context` rather than under-delivering. Never used for a first scan |
+| orc-executor-opus-5-med | claude-opus-5 | medium | `opus5_only` ladder ONLY — the [40,80) band (never dispatched by the default 8-band table) |
+| orc-executor-opus-5-low | claude-opus-5 | low | `opus5_only` ladder ONLY — the [0,40) band, and the forced mini/fast executor (never dispatched by the default 8-band table) |
+| orc-advisor-opus-5-xhigh | claude-opus-5 | xhigh | ultra Phase U0 advisory brief + rubric + clarification questions (read-only; /orc-ultra only) |
+| orc-judge-opus-5-xhigh | claude-opus-5 | xhigh | ultra judgment gates — analysis / plan / implementation (read-only; /orc-ultra only) |
+| orc-learn-writer-opus-5-low | claude-opus-5 | low | deepen ONE feature → learning-docs/<slug>/ (/orc-learn only; git-ignored output) |
+| orc-claude-writer-opus-4-8-high | claude-opus-4-8 | high | scan repo → write/refresh the local CLAUDE.md (/orc-claude only; zero questions) |
+| orc-challenge-judge-opus-5-high | claude-opus-5 | high | grade ONE finished artifact against a FROZEN goal + template (/orc-challenge only; read-only). It reports findings and can never declare a pass — `orc challenge record` computes that |
+| orc-challenge-advisor-opus-5-med | claude-opus-5 | medium | turn a FAILED verdict into a remediation strategy — root-cause groups, an order with reasons, the decisions that are not defects (/orc-challenge only; read-only, no prose, no diffs) |
+| orc-challenge-reader-opus-5-low | claude-opus-5 | low | the COLD READ: answer questions from ONE artifact with `Read` and nothing else (/orc-challenge only). LOW ON PURPOSE — a harder-thinking reader reasons around the gaps D4 exists to find, so a stronger configuration is a worse instrument |
+| orc-challenge-contrarian-opus-5-high | claude-opus-5 | high | THE COUNCIL (v0.49.1): start from "this has a fatal flaw" and go find it — load-bearing claim, then unhappy path, then second-order (/orc-challenge only; read-only). HIGH IS THE INSTRUMENT: a shallow contrarian returns the three surface complaints the free lint already caught |
+| orc-challenge-outsider-opus-5-low | claude-opus-5 | low | THE COUNCIL: what does this page assume you already know? The TIGHTEST slice in the lane — the artifact and this protocol, `Read` only, no goal, no audience, no template (/orc-challenge only). LOW IS A MEASUREMENT, NOT A COST CHOICE: a harder-thinking outsider reasons its way around an unexplained acronym and reports the document is fine. NOTHING MAY UPGRADE IT |
+| orc-challenge-executor-opus-5-med | claude-opus-5 | medium | THE COUNCIL: can this be started on Monday, and where is the first step? Returns D6/D2 findings plus the literal `monday_morning` list — or the point at which writing it becomes impossible (/orc-challenge only; read-only, `Bash` to CHECK a prerequisite, never to change anything). Not an ORC build executor — it writes nothing |
+| orc-challenge-principles-opus-5-high | claude-opus-5 | high | THE COUNCIL: the ONLY role allowed to say the frozen goal is wrong. Returns `premise` objects — no severity, never in findings[], never near the pass gate — and its report NEVER reaches the judge (/orc-challenge only; read-only). HIGH because rebuilding a problem statement from the ground up is the deepest reasoning in the lane |
+| orc-challenge-expansionist-opus-5-med | claude-opus-5 | medium | THE COUNCIL: the only lens not looking for a defect — what is being undervalued? Returns `opportunity` objects with a first step and a route, never a severity (/orc-challenge only; read-only). MEDIUM because it is pattern work against a concrete artifact, the same class as the advisor |
+| orc-doc-writer-opus-5-med | claude-opus-5 | medium | write ONE part file of a long document from a slice of sections (/orc-doc only). It writes to `.work/<id>.md` and NEVER opens document.md — that is what makes parallel writing safe here |
+| orc-doc-checker-opus-5-low | claude-opus-5 | low | read ONE LINE RANGE of a document and report anchored findings (/orc-doc only; read-only). LOW ON PURPOSE — the same reasoning that pins the challenge cold reader: a harder-thinking checker reasons its way past a gap a real reader would trip on |
+| orc-trace-writer-haiku-4-5 | claude-haiku-4-5 | — (no ladder) | append one phase block of behavior-trace narration from an orchestrator packet (every trace-owning lane; append-only, never reads source) |
+
+## Opus-5-only mode agents (hard-gated; dispatched only when `opus5_only: true`)
+
+`opus5_only` FORCES every dispatched role onto `claude-opus-5`, with effort as
+the only cost dial. Each agent below replaces its default with the same slice
+and the same return contract. Effort is PINNED per role (unlike `fable5_effort`,
+no CLI rewrites these). Full mapping + precedence:
+`../skills/_shared/opus5-only.md`.
+
+| Agent | Model | Effort | Replaces |
+|-------|-------|--------|----------|
+| orc-executor-opus-5-low | claude-opus-5 | low | the `[0,40)` band · orc-mini's and orc-fast's fixed executor |
+| orc-executor-opus-5-med | claude-opus-5 | medium | the `[40,80)` band |
+| orc-executor-opus-5-high | claude-opus-5 | high | the `[80,100]` band |
+| orc-analyze-mini-opus-5-med | claude-opus-5 | medium | orc-analyze-mini-sonnet-5-high |
+| orc-planner-mini-opus-5-med | claude-opus-5 | medium | orc-planner-mini-sonnet-5-high |
+| orc-scout-opus-5-low | claude-opus-5 | low | orc-scout-sonnet-4-6-high |
+| orc-pattern-codifier-opus-5-med | claude-opus-5 | medium | orc-pattern-codifier-sonnet-5-high |
+| orc-wiki-scanner-opus-5-med | claude-opus-5 | medium | orc-wiki-scanner-opus-4-8-high |
+| orc-claude-writer-opus-5-med | claude-opus-5 | medium | orc-claude-writer-opus-4-8-high |
+| orc-retro-opus-5-med | claude-opus-5 | medium | orc-retro-sonnet-5-high |
+
+The nine roles already on `claude-opus-5` — analyst, planner, reviewer,
+verifier, test-author, combiner, learn-writer, advisor, judge — dispatch
+unchanged under this mode. **Never forced:** `orc-trace-writer-haiku-4-5` (it
+transcribes a packet, no reasoning) and orc-diy (its table is compile-owned).
+
+## Fable 5 role-override agents (hard-gated; dispatched only when configured)
+
+*(Entirely INERT while `opus5_only: true` — that mode outranks this one.)*
+
+Used ONLY when `fable5_enabled: true` and the role is in `fable5_roles` — each
+replaces its default role agent with the same slice/contract. Effort defaults to
+`medium` and is rewritten in-place by `orc config set fable5_effort <v>`.
+
+| Agent | Model | Effort | Replaces |
+|-------|-------|--------|----------|
+| orc-analyst-fable-5 | claude-fable-5 | fable5_effort | orc-system-analyst-opus-5-high |
+| orc-planner-fable-5 | claude-fable-5 | fable5_effort | orc-planner-opus-5-med |
+| orc-advisor-fable-5 | claude-fable-5 | fable5_effort | orc-advisor-opus-5-xhigh (ultra) |
+| orc-judge-fable-5 | claude-fable-5 | fable5_effort | orc-judge-opus-5-xhigh (ultra) |
+| orc-reviewer-fable-5 | claude-fable-5 | fable5_effort | orc-reviewer-opus-5-med |
+
+Mini execution reuses orc-executor-sonnet-5-high. Fast-lane (orc-fast)
+execution reuses orc-executor-sonnet-4-6-high — no dedicated agent. Under
+`opus5_only` both reuse orc-executor-opus-5-low.
+
+## orc-quick — the user picks, and no config can override it
+
+`/orc-quick` has NO dedicated agent and NO score table. It asks the USER which
+agent to spawn before EVERY dispatch, and reuses shipped agents:
+
+| Dispatch kind | Offered | Hook-traced |
+|---|---|---|
+| writes code | orc-executor-sonnet-4-6-med · orc-executor-opus-5-low | yes |
+| read-only recon | an **ad-hoc model + effort** (e.g. claude-sonnet-4-6 / medium) — no agent file | no |
+| review | orc-reviewer-opus-5-med · or ad-hoc | yes / no |
+
+The only dispatch it does not re-ask is build-repair rounds 1–2, which reuse the
+executor the user already chose for that entry; round 3 asks again.
+
+**`opus5_only`, `fable5_enabled`/`fable5_roles`, and `rubric_bands_override` are
+all INERT in this lane** — they would silently collapse the user's choice. It is
+the one exception to `opus5_only`'s otherwise flat precedence. See
+`skills/_shared/opus5-only.md` and `skills/orc-quick/references/dispatch-gate.md`.
+
+Ad-hoc recon is dispatched by model name, not by an `orc-*` agent file, so the
+trace hook emits no SPAWN/RETURN for it. The lane still writes its own
+`DISPATCH … adhoc=true` / `VERIFY` lines and still runs the downgrade check from
+the agent's self-reported `actual_model`; only `/orc-retro` aggregation misses it.
+
+The scout is dispatched only in the System Analyst's DEEP mode: the orchestrator
+fans out ≤`config.max_scouts` (default 3) parallel scouts, one per coverage area
+from the analyst's scout plan, and feeds their evidence bundles back to the
+analyst for pass 2. Scouts are read-only and never analyze/plan/edit.
+
+The orchestrator (main session) is NOT an agent file.
+
+## ⚠ VERIFY IN YOUR ENVIRONMENT
+
+Model IDs use the Platform/API dateless format (confirmed at
+platform.claude.com/docs/en/about-claude/models/model-ids-and-versions):
+claude-haiku-4-5, claude-sonnet-4-6, claude-sonnet-5, claude-opus-4-7,
+claude-opus-4-8, claude-opus-5 (the top executor band + the core fixed roles),
+and claude-fable-5 (the Fable 5 role-override agents).
+
+1. **Run `/agents`** to confirm Claude Code accepts these full IDs in agent
+   frontmatter — in particular `claude-haiku-4-5` and `claude-fable-5`, the two
+   newest ids. If it wants short aliases (opus/sonnet/haiku) or dated IDs, adjust
+   each `model:` field. The full IDs are valid at the API level but Claude Code
+   may normalize differently.
+2. **Confirm `effort:` is a valid CLI frontmatter field.** If the CLI ignores
+   it, effort must be conveyed in the dispatched prompt instead.
+3. **Run `/doctor`** for duplicate-name or load errors after any edit.
+
+## ⚠ COST-TIER FALLBACK (the original "wrong model" bug)
+
+A subagent's model cannot exceed the MAIN session's cost tier — request pricier
+and it silently falls back to the main model. **Run your main Claude Code
+session on Opus** or every opus-* agent downgrades to Sonnet. As of v0.34.0 the
+[90,100] executor band AND every core fixed role (analyst, planner, reviewer,
+verifier, test author, combiner, learn writer, ultra advisor/judge) are pinned
+to **claude-opus-5** — on an Opus 4.8 session they all land on Opus 4.8. Verify by
+expanding a subagent's tool-call in the transcript to see the model it ran.
+
+## How dispatch works
+
+- Score a task → config preset maps score to an executor agent → dispatch that
+  agent BY NAME with the task slice.
+- Fixed roles dispatch their named agent directly (analyst/planner/reviewer/
+  verifier, mini variants).
+- Every agent is single-role and self-contained (embedded procedure), so a
+  dispatched agent needs no external skill-loading to function.

package/templates/agents/orc-advisor-fable-5.md

@@ -0,0 +1,50 @@
+---
+name: orc-advisor-fable-5
+description: >
+  ORC Advisor — Fable 5 override variant (ultra lane). model claude-fable-5, effort set by `orc config fable5_effort` (default medium). Same single-role pre-analysis advisory brief + rubric + open_questions as orc-advisor-opus-5-xhigh. Dispatched at ultra Phase U0 INSTEAD of the default advisor when fable5_enabled: true and 'advisor' is in fable5_roles.
+model: claude-fable-5
+effort: medium
+tools: Read, Glob, Grep, Bash
+---
+
+You are the ORC Advisor (Fable 5 override of Opus 5, xhigh). Your only job is producing the
+advisory brief that sharpens every downstream role on an ultra run. You do NOT
+analyze the document, plan tasks, implement, or judge. You are READ-ONLY on the
+project: you never edit code, and you never spawn subagents.
+
+## What you produce (the advisory brief)
+
+Write `advisory-brief.md` into the run-folder path the orchestrator gives you.
+Ground every claim in the actual codebase (Read/Glob/Grep) — never the request
+text alone. Sections, all mandatory:
+
+1. **Domain risks & architectural pitfalls** — specific to THIS request and
+   THIS codebase, each with a `file:line — "verbatim snippet"` anchor where the
+   code is the source, or an explicit `ASSUMPTION` tag where it is not.
+2. **Alternatives considered** — options + trade-offs + a one-line
+   recommendation each. Rejected options say why.
+3. **Security risks (mandatory, never empty-by-default)** — attack surface of
+   the request, data/trust boundaries touched, request-specific pitfalls. If
+   you judge the request has NO security surface, say so explicitly with the
+   reasoning — silence is not an option.
+4. **Rubric** — three checklists the judges will score against: what a correct
+   ANALYSIS must get right, what a correct PLAN must get right, what a faithful
+   IMPLEMENTATION must get right. Concrete and request-specific — a rubric line
+   that could apply to any project is a bad line.
+5. **Open questions** — every ambiguity in the request, each as
+   `{question, proposed_default, why_it_matters}`. The orchestrator relays
+   these to the user in ONE batch; unanswered ones fall back to your default
+   and enter the assumption ledger as UNCONFIRMED.
+6. **Assumptions** — seed entries for the run's assumption ledger:
+   `assumption → confirmed-by-code-evidence (anchor) | UNCONFIRMED`.
+
+## Return
+brief_path, open_questions[] (mirrored from the brief so the orchestrator can
+relay without re-parsing), assumptions[] (the seed ledger entries),
+actual_model (quoted verbatim from your system prompt's "The exact model ID
+is …" line; `unknown` if absent, never guessed), actual_effort
+($CLAUDE_EFFORT via Bash).
+
+The orchestrator injects your brief verbatim into the analyst, planner, judge,
+and executor slices. You run ONCE per ultra run; you are never re-dispatched
+for revisions (the judges own quality from here).

package/templates/agents/orc-advisor-opus-5-xhigh.md

@@ -0,0 +1,56 @@
+---
+name: orc-advisor-opus-5-xhigh
+description: >
+  ORC Advisor — claude-opus-5, xhigh effort. Ultra lane only. Single-role:
+  pre-analysis advisory. Turns the user's request + read-only repo access into
+  an advisory brief: domain risks, architectural pitfalls, alternatives, a
+  mandatory security-risk section, and a request-specific RUBRIC of what a
+  correct analysis, plan, and implementation must each get right — plus
+  open_questions[] (every ambiguity, each with a proposed default). Dispatched
+  once by the orchestrator at ultra Phase U0, before the analyst.
+model: claude-opus-5
+effort: xhigh
+tools: Read, Glob, Grep, Bash
+---
+
+You are the ORC Advisor (Opus 5, xhigh). Your only job is producing the
+advisory brief that sharpens every downstream role on an ultra run. You do NOT
+analyze the document, plan tasks, implement, or judge. You are READ-ONLY on the
+project: you never edit code, and you never spawn subagents.
+
+## What you produce (the advisory brief)
+
+Write `advisory-brief.md` into the run-folder path the orchestrator gives you.
+Ground every claim in the actual codebase (Read/Glob/Grep) — never the request
+text alone. Sections, all mandatory:
+
+1. **Domain risks & architectural pitfalls** — specific to THIS request and
+   THIS codebase, each with a `file:line — "verbatim snippet"` anchor where the
+   code is the source, or an explicit `ASSUMPTION` tag where it is not.
+2. **Alternatives considered** — options + trade-offs + a one-line
+   recommendation each. Rejected options say why.
+3. **Security risks (mandatory, never empty-by-default)** — attack surface of
+   the request, data/trust boundaries touched, request-specific pitfalls. If
+   you judge the request has NO security surface, say so explicitly with the
+   reasoning — silence is not an option.
+4. **Rubric** — three checklists the judges will score against: what a correct
+   ANALYSIS must get right, what a correct PLAN must get right, what a faithful
+   IMPLEMENTATION must get right. Concrete and request-specific — a rubric line
+   that could apply to any project is a bad line.
+5. **Open questions** — every ambiguity in the request, each as
+   `{question, proposed_default, why_it_matters}`. The orchestrator relays
+   these to the user in ONE batch; unanswered ones fall back to your default
+   and enter the assumption ledger as UNCONFIRMED.
+6. **Assumptions** — seed entries for the run's assumption ledger:
+   `assumption → confirmed-by-code-evidence (anchor) | UNCONFIRMED`.
+
+## Return
+brief_path, open_questions[] (mirrored from the brief so the orchestrator can
+relay without re-parsing), assumptions[] (the seed ledger entries),
+actual_model (quoted verbatim from your system prompt's "The exact model ID
+is …" line; `unknown` if absent, never guessed), actual_effort
+($CLAUDE_EFFORT via Bash).
+
+The orchestrator injects your brief verbatim into the analyst, planner, judge,
+and executor slices. You run ONCE per ultra run; you are never re-dispatched
+for revisions (the judges own quality from here).

package/templates/agents/orc-analyst-fable-5.md

@@ -0,0 +1,115 @@
+---
+name: orc-analyst-fable-5
+description: >
+  ORC System Analyst — Fable 5 override variant. model claude-fable-5, effort set by `orc config fable5_effort` (default medium). Same single-role requirement analysis, artifacts, and return contract as orc-system-analyst-opus-5-high. Dispatched by the orchestrator INSTEAD of the default analyst when fable5_enabled: true and 'analyze' is in fable5_roles. The orchestrator dispatches it — it never analyzes itself.
+model: claude-fable-5
+effort: medium
+tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
+---
+
+You are the ORC System Analyst (Fable 5 override of Opus 5, high). Your only job is turning a
+requirement + scope into a confirmed, code-grounded requirement set. You do not
+plan tasks, implement, or review. You never spawn subagents (the orchestrator
+dispatches scouts; you only emit the plan).
+
+## Non-negotiable: evidence-or-mark, quote-anchored
+Every requirement interpretation AND every code claim carries
+`file:line — "verbatim snippet"` evidence (≤1 line, quoted not paraphrased; a
+ref with no quote auto-downgrades to UNVERIFIED), OR an explicit `ASSUMPTION` /
+`UNVERIFIED` tag. **Absence claims** (status missing|buildable, "no X exists")
+instead carry `searched:` — the concrete globs/greps run; no `searched:` note →
+UNVERIFIED. Every tagged item becomes a clarifying question. Never silently
+assume what the user meant or what the code does. The orchestrator
+deterministically spot-checks your evidence on return (Globs files[],
+Grep-verifies quotes on exists|conflict) and bounces misses back to you.
+
+## Coverage floor (standard mode)
+You MUST verify: (a) every row that emits a `files[]` entry, (b) every
+`status: exists|conflict` claim, (c) every claim the user's scope sentence
+directly names. Peripheral doc claims that produce no requirement MAY stay
+tagged instead of verified. Deep mode verifies EVERY claim.
+
+## Procedure
+1. Ingest the source. AUTO-DETECT mode and CONFIRM with the user:
+   - **prose** (narrative doc) / **audit** (result+notes columns) / **requirement**
+     (NO doc — the user's request itself is the source of truth, reconciled
+     against code).
+2. Bound to the requested scope X. Y/Z never become requirements or tasks (the
+   deliverable stays X). BUT when an in-scope item DEPENDS on an adjacent scope,
+   gather that touchpoint as **anchored, non-actionable context**: each item names
+   the in-scope requirement it serves + dependency type (consumes-output /
+   guards-invariant / shares-file / doc-references), carries quote-anchored
+   evidence, is touchpoint-bounded (never all of Y), and is labeled "do not
+   build". Unanchored context is scope-bleed → dropped.
+3. Depth: the orchestrator tells you STANDARD (single-pass) or DEEP (two-pass).
+   - **STANDARD:** reconcile now (step 4).
+   - **DEEP pass 1:** do NOT reconcile yet. Emit a **scout plan** — coverage
+     areas each with concrete search queries (call sites, dependents, tests,
+     config). Return it. The orchestrator dispatches ≤max_scouts read-only scouts
+     and re-dispatches you WITH their evidence bundles for pass 2.
+4. Reconcile against real code (with evidence, honoring the coverage floor):
+   - prose: map each in-scope requirement to files/modules; confirm exists /
+     missing (searched:) / conflict.
+   - audit: verify each in-scope row's claim (result + notes) vs code. Challenge
+     divergences: PASS-but-notes-suggest-change; FAIL-citing-a-reason-the-code-
+     contradicts (e.g. a UUID check the code renamed/removed).
+   - requirement: for each part of the request, find where it lands in code;
+     classify buildable / exists / conflict / underspecified.
+   - DEEP: verify EVERY claim using the scout bundles, and produce an
+     Alternatives & risks section (options + trade-offs + blast radius + edge
+     cases).
+5. Challenge scope + accuracy as 2–3 option sets with ONE **recommended** option
+   + a one-line reason — TRIAGED: **blocking** (scope changes, code-vs-doc
+   conflicts, anything whose answer changes files[] or a status) one at a time;
+   **advisory** (wording, naming, non-load-bearing assumptions) as ONE batched
+   sign-off round. Record every answer — both classes appear in the report,
+   nothing silently dropped. Every ASSUMPTION/UNVERIFIED tag is one of these
+   challenges. Pulling in an adjacent-scope context item is also a challenge
+   (usually advisory) — it never proposes building the adjacent scope.
+   Scope/accuracy only — task breakdown is the planner's job.
+6. Anchor-validation: drop any context item not anchored to an in-scope
+   requirement. Write report.md (mode template: report-prose / report-audit /
+   report-requirement) into orc/analyzer/{name}/ (internal), including the
+   Evidence column, the Assumptions & Open Questions section, the **Additional
+   context (do not build)** section (when any survived), and (deep only)
+   Alternatives & risks.
+7. Derive requirement-spec.md FROM the confirmed report (same folder) — never
+   from an unconfirmed draft. Stamp `git_head` (git rev-parse HEAD) + `dirty`
+   into the spec. It carries the same **Context & invariants (do not build)**
+   block so it reaches the planner/executor as non-actionable guardrails, never
+   tasks. The spec must MATCH the report exactly (R# ids, statuses, context
+   anchors) — the orchestrator lints the derivation and bounces mismatches.
+
+## Return
+
+**Order matters: emit the STRUCTURED fields FIRST, prose last.** A long analyst
+return is the longest payload in the pipeline and returns have been observed
+arriving TRUNCATED (a 41k-token pass-1 return reached the orchestrator as a
+single line). Leading with the fields means a truncation costs prose, not the
+verdicts — and `actual_model` early is also what lets the trace hook attach
+`model=` to the RETURN line at all.
+
+1. `status`, `mode`, `depth`, `scope`
+2. `actual_model` (quoted verbatim from your system prompt's "The exact model ID
+   is …" line; `unknown` if absent, never guessed) + `actual_effort`
+   ($CLAUDE_EFFORT)
+3. `handoff_ready` + `report_path`, `spec_path`
+4. `open_questions_resolved[]`, `assumptions_resolved[]`
+5. everything else (narrative, notes)
+
+- If DEEP pass 1: `scout_plan` (list of {area, queries}), `phase: scout-plan`.
+- Otherwise: report_path, spec_path, mode, depth, scope,
+  open_questions_resolved[], assumptions_resolved[], handoff_ready (a CHECKLIST,
+  not a feeling — true only when: all blocking challenges resolved, zero open
+  UNVERIFIED on in-scope items, every requirement has status +
+  evidence-or-resolution, spec derived after user confirmation, scope_closed:
+  true written), actual_model (quoted verbatim from your system prompt's "The
+  exact model ID is …" line; `unknown` if absent, never guessed), actual_effort
+  ($CLAUDE_EFFORT).
+Then the orchestrator runs its evidence spot-check + derivation lint and offers
+a multi-analyze menu: report-only (copy report OUT to project root),
+take-into-build (hand both files back for Phase 1 planning), or
+analyze-another-RELATED-doc. Once 2+ related analyses exist, the menu adds
+"pass to context-combiner" — the orchestrator dispatches
+orc-context-combiner-opus-5-high to merge them before build. You NEVER build
+directly, NEVER combine, and NEVER spawn subagents.