@azure-id/orc 0.56.0 → 1.0.0

package/README.md

@@ -7,14 +7,14 @@
 *Intake → analyze → plan → score → parallel subagents → review → verify → ship.*
 
 ![npm](https://img.shields.io/npm/v/%40azure-id%2Forc?style=for-the-badge&color=cb3837&logo=npm)
-![Version](https://img.shields.io/badge/version-0.56.0-blue.svg?style=for-the-badge)
+![Version](https://img.shields.io/badge/version-1.0.0-blue.svg?style=for-the-badge)
 ![License](https://img.shields.io/badge/license-MIT-green.svg?style=for-the-badge)
 ![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg?style=for-the-badge)
 ![Claude Code](https://img.shields.io/badge/Claude_Code-Skills-purple.svg?style=for-the-badge)
 ![Dependencies](https://img.shields.io/badge/dependencies-zero-lightgrey.svg?style=for-the-badge)
 ![GitHub stars](https://img.shields.io/github/stars/azure-id/orc?style=for-the-badge&color=yellow)
 
-**Latest: v0.56.0** · updated 2026-08-27 · [full changelog](CHANGELOG.md)
+**Latest: v1.0.0** · updated 2026-08-30 · [full changelog](CHANGELOG.md)
 
 **On npm: [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc)** — `npm i -g @azure-id/orc`
 
@@ -359,6 +359,8 @@ orc ui --stop          # shut this project's server down
 | Crosslink | **Design** (the boundary as a graph) and **Settings** (each peer's freshness) | `crosslink add` / `remove` |
 | Promises · Boundary · Self-serve | the pact ledger, the boundary cards, and the surfaces a non-developer can change | `pact check`, `pact sync`, `handoff set` |
 | **Docs** | every `/orc-doc` document as a **ribbon** — one block per section, sized by its length and coloured by its state — plus the section files with their sub-parts, the wave strip, the lint health card and the wave preview | `doc compile` · `doc migrate` |
+| **Extra** | **six tabs**: the connection setup, the local tools and their state, the band ladder and the six positions, spending per profile per band, and **Recovery** — every dispatch that never reported back, with what it left on disk | `extra add` / `ping` / `route` / `role` |
+| **Challenge** | every `/orc-challenge` cycle: the frozen goal, the council roster and what each lens raised, the findings with their dispositions, and whether the pass is computed or blocked | `challenge record` · `accept` · `rebut` |
 | **Mocked Skill Use** | every mocked run that ships with ORC, grouped and searchable, with a reading pane | — |
 | Learn | the `orc onboarding` walkthrough, one section at a time | — |
 | Experiment | every lane with a copy button; opens a Claude session in a terminal | — |
@@ -384,6 +386,77 @@ CSS.
 
 ---
 
+## Running part of the ladder somewhere else — `orc extra`
+
+**The orchestrator is always Claude.** What Extra changes is *who executes a
+slice*: a score band you own, or one of six named positions, can point at
+DeepSeek, GLM, Kimi, MiniMax, Qwen, a local Ollama, or a coding CLI you already
+have signed in (opencode, codex). Everything downstream — the smoke gate, the TDD
+gate, the reviewer, the worktree-delta check — is engine-blind, so nothing learns
+the work was foreign.
+
+**Off by default, and it cannot be armed until something has actually answered.**
+
+```bash
+orc extra providers              # the shipped, dated catalog — providers, never models
+orc extra tools                  # local CLIs: absent · outdated · unauthenticated · ready
+orc extra add ds --provider deepseek --engine api --env-key DEEPSEEK_API_KEY
+orc extra ping ds                # the connection gate: a ladder, and nothing reads stronger than it is
+orc extra models ds --test <id>  # a LISTED model can still be dead upstream
+orc extra health ds --model <id> # …and a working model is not one that FINISHES
+orc extra route set 40-55 ds/deepseek-chat     # a score band
+orc extra role set doc-writer ds/deepseek-chat # or a named position
+orc config set extra_enabled true
+```
+
+- **The catalog ships providers and never models.** A shipped model id is wrong
+  within a quarter and wrong *silently* — a 404 mid-wave. `orc extra ping` reads
+  the live list and caches it; nothing invents a name. Same for price: a cost
+  figure ORC did not price itself is never printed, it reads as an em dash.
+- **Every armed run says so before wave 1.** Routing work off Claude silently is
+  the failure this whole subsystem is shaped around.
+- **Two hard hold-backs**: a task with a cited `risk[]` (auth, money, migration,
+  security, concurrency, data-integrity) stays on Claude unless you say
+  otherwise, and a `/orc-boundary` REFUSE area holds even in `warn`.
+- **A foreign return is foreign input.** It is the only foreign class that edits
+  your worktree, so what it says it did is a *claim*, checked against the tree.
+- **Your key never reaches a command line.** It travels on stdin into an
+  encrypted vault, or it stays in an environment variable, or the tool holds its
+  own — and the passphrase is a **deadline**, not a second factor.
+- **Six positions for the lanes that pin an agent instead of scoring a task**:
+  `quick-executor` · `fast-executor` · `doc-writer` · `doc-checker` ·
+  `wiki-scanner-deep` · `wiki-scanner-light`. A position with no row keeps its
+  slot and reads as its pinned Claude agent — "I left the checker on Claude on
+  purpose" and "there is no checker" must never look the same.
+
+**When a foreign worker fails, it is a position and not a blank page.** ORC
+journals the baseline *before the first byte leaves the machine*, so a worker cut
+off mid-write is **reconciled and resumed** — never re-dispatched from scratch
+onto a file that is already two-thirds written.
+
+- **`extra_stall_s` (default 180)** stops a worker that has produced nothing for
+  that long. It is reset by observable progress — the worker's stream, its
+  stderr, or a declared file that changed on disk — so it never fires on one that
+  is merely slow. `stalled` is retryable, which is what makes the resume ORC's
+  own spelling of typing `continue`.
+- **`extra_fallback_agent` (default `band`)** decides who picks the task up.
+  `ask` stops and puts the menu to you; any installed agent name pins one. It
+  changes *who*, never the score, the declared files or the acceptance criteria.
+- **Every dispatch writes its own spend record**, so a cost report never depends
+  on a run remembering to narrate what it spent. `orc extra stats` merges the
+  spend log, the traces and saved returns, and always says how many rows came
+  from each.
+
+**`/orc-quick` is inert here** and announces it — that lane asks which agent
+before every dispatch, so no setting may pre-answer it. **`/orc-challenge` never
+routes foreign**: swapping a lens for a different model does not make the lane
+cheaper, it changes what is being measured.
+
+**The whole subsystem, with every command and key:
+[guides/extra-models.md](guides/extra-models.md).**
+
+---
+
 ## How the model is picked
 
 Each task is scored 0–100 by **arithmetic, not judgement**: the planner reports
@@ -424,12 +497,13 @@ clobbers. `orc ui` ▸ Settings edits the same keys through the same validators.
 
 ```
 templates/
-├── skills/       29 skills — the lanes above, plus the ones with no command of
-│                 their own: context-combiner, orc-advisor, orc-judge,
-│                 orc-analyze-mini, and _shared/ (cross-lane contract prose)
-├── commands/     27 slash commands
+├── skills/       31 skill folders, 38 SKILL.md files (a lane may ship subskills) —
+│                 the lanes above, plus the ones with no command of their own:
+│                 context-combiner, orc-advisor, orc-judge, orc-analyze-mini,
+│                 and _shared/ (cross-lane contract prose)
+├── commands/     29 slash commands
 ├── hooks/        effort guard (PreToolUse) · statusline warning · behavior trace
-└── agents/       40 model-pinned subagents + MODEL-MAPPING.md
+└── agents/       51 model-pinned subagents + MODEL-MAPPING.md
 bin/cli.js        installer, config editor, flow composer, run-state reader, and
                   the deterministic half of every lane. Every read speaks --json
 bin/webui/        `orc ui` — the local control panel: css/ + js/ + i18n/<lang>/ +
@@ -500,102 +574,49 @@ a current audit: [EVAL-REPORT.md](EVAL-REPORT.md).
 **Full history: [CHANGELOG.md](CHANGELOG.md)** — or `orc changelog`, which prints
 only what is newer than the version you have.
 
-### v0.56.0 - a rename moved the command, and nobody could reach the fix _(2026-08-27)_
-
-**READ THIS FIRST IF YOUR `orc upgrade` IS FAILING.** On a version before
-v0.56.0, this release cannot install itself - your `orc upgrade` is the OLD one.
-Run these three lines once, by hand:
-
-- **Step 1 - release the command from the old package:** `npm uninstall -g orc`
-- **Step 2 - install the current package:** `npm i -g @azure-id/orc`
-- **Step 3 - re-apply it to your project:** `orc update` (add `--global` to also
-  refresh `~/.claude`)
-
-Then `orc version` should print 0.56.0 or newer. Your `.claude/` and your
-`orc.config.yaml` are untouched. **Do not use `npm i -g -f`.**
-
-**The package moved from the unscoped `orc` to `@azure-id/orc`, and every
-upgrade path in the field died at once.** Both names declare the same `orc` bin,
-and npm will not link it for the new package while the old one owns it - so the
-tarball, the `github:` spec and the registry all failed with the same `EEXIST`
-on the command file. It is a FILE conflict, not a source problem, which is why
-changing sources never helped and `npm i -g -f` was the only thing that worked.
-
-- **`orc upgrade` evicts the legacy package BEFORE trying any source**, because
-  the collision fails every source identically. Announced, never silent.
-  Detection is by OWNERSHIP - a package that does not declare the `orc` bin is
-  never touched.
-- **The npm registry is tried first**, then the tarball, then the `github:` spec.
-  `freshCliPath()` now resolves the SCOPED directory, so step 2 stops re-applying
-  the templates step 1 just superseded.
-- **`--force` is kept for the one case it fits** - an orphaned command file no
-  package owns - and never for an unrelated `EEXIST`.
-- **`orc doctor` reports `legacy-global-package` by name.** Not `--fix`-able on
-  purpose: `--fix` is scoped to this project's `.claude/`.
-- **A CAUTION at the top of this README** carries the one-time manual fix, since
-  anyone still on the old package does not have this code yet.
-
-### v0.55.2 - a gate that is never probed is a gate that is always off _(2026-08-27)_
-
-**`/orc-quick` and `/orc-fast` documented the foreign-worker option and then
-never went and looked for it.** Both carried the whole `orc extra` slot contract
-but neither preflight ever ran the probe that answers whether a position is
-held, so an armed `extra_enabled` plus a slot row still offered only the shipped
-Claude executors.
-
-- **orc-quick Q0 gains one PROBE** - `orc extra resolve --slot quick-executor
-  --json`, the single exception to "read no other key" - so the menu can render
-  line 3. Still an option: never a default, never sticky.
-- **orc-fast F0 gains gate `d`** - `orc extra resolve --slot fast-executor
-  --json` - and prints the P0 `extra:` line where the prose always said it
-  would, naming the agent it displaces.
-- **`/orc-doc` was never affected**: `orc doc next` resolves its targets in the
-  CLI, which is the shape the other two now borrow.
-
-### v0.55.1 — ORC is on npm _(2026-08-27)_
-
-**ORC is published as [`@azure-id/orc`](https://www.npmjs.com/package/@azure-id/orc).**
-The GitHub tarball still works and nothing about the payload changed — this is
-the install path getting a name.
-
-- **`npm i -g @azure-id/orc`** is the install, and
-  **`npm i -g @azure-id/orc@latest`** is the update. `orc upgrade` already did
-  both steps for you and continues to; `--from @azure-id/orc` names npm
-  explicitly.
-- **The GitHub tarball is now the fallback**, not the headline — it is kept in
-  the Quick start behind a fold for forks and for anyone pinning a branch.
-
-### v0.55.0 — a score is what a band needs, and four lanes do not have one _(2026-08-26)_
-
-**`/orc-quick`, `/orc-fast`, `/orc-doc` and `/orc-wiki` pin an agent to a
-position instead of scoring a task. `orc extra` routed them by reading that
-agent's score band — arithmetic on a number nobody chose. It was wrong twice and
-dead once.**
-
-- **`orc extra role` holds six POSITIONS** — `quick-executor` · `fast-executor` ·
-  `doc-writer` · `doc-checker` · `wiki-scanner-deep` · `wiki-scanner-light`. One
-  connection and one model each, and a row's presence is the arming. All six are
-  always listed: an unrouted one keeps its slot and reads as the Claude agent it
-  falls back to.
-- **`orc extra resolve --slot` never touches a band**, and the Claude answer it
-  carries is a pinned NAME rather than an interval. Nine hold-backs, each named.
-- **Precedence, one sentence:** extra decides *whether* a Claude agent runs at
-  all; `opus5_only` and the score tables only decide *which* one runs where extra
-  did not take it. Under a taken position `opus5_only` is not consulted — and it
-  stays fully live for every position with no row.
-- **The bridge accepts a slot** (`band` becomes `slot:<slot>`, so cost reporting
-  splits per position for free) with **zero new engines, zero new dispatch paths
-  and zero new agents**. A doc checker now resolves its OWN position, `/orc-wiki`
-  can route at all, and `/orc-quick` gets a THIRD OPTION on its menu — never a
-  default, never sticky, re-asked after a failure.
-- **A second ladder in `orc ui ▸ Extra ▸ Routing`**, and **zero config keys
-  added**.
-
-Before that: **v0.54.0 — a failed dispatch is a POSITION, not a blank page**,
-**v0.53.4 — the reload that dropped its own token**, **v0.53.3 — the key it never
-sent**, **v0.53.2 — the cost that was paid and never written down**, and
-**v0.53.1 — "up to date" now names what it checked**.
-[Read them in the changelog](CHANGELOG.md).
+### v1.0.0 - config, phases and calls stop being prose _(2026-08-30)_
+
+**Still on the unscoped `orc` package?** Do this once first — your `orc upgrade`
+is the pre-v0.56.0 one and cannot install itself. Full detail in the CAUTION at
+the top of this file.
+
+- **Step 1 — release the command from the old package:** `npm uninstall -g orc`
+- **Step 2 — install the current package:** `npm i -g @azure-id/orc`
+- **Step 3 — re-apply it to your project:** `orc update`
+
+**Nothing you configure changes meaning, and no command you run is renamed.**
+Three things actually change behaviour; everything else is ORC finally reading
+its own payload the way it has been telling you to read yours.
+
+- **The score to model table ends `opus-5-low [65,90)` · `opus-5-med [90,100]`.**
+  Two bands in six now want an Opus 5 main session where one in eight did.
+- **A foreign worker that stalls twice in one run steps aside** for the rest of
+  that run. Two clocks, never merged; it writes no new measurement and never
+  writes your config; a promote is a watermark, not a mute, and needs a reason.
+- **`orc diy init` defaults to `opus-5-high`.** The old default silently
+  collapsed the top third of your ladder onto one agent before you chose
+  anything.
+
+The structural half - **config, phases and calls stop being prose**:
+
+- **`orc lane config <lane>`** answers what a lane's config resolved to, with
+  every shadow already worded. A lane never merges the config file itself again,
+  and **a rank below a resolved rank is not read at all**.
+- **`orc lane phases <lane>`** and **`orc lane calls --all`** do the same for the
+  shared phase library and the CLI call catalogue - one canonical copy each,
+  where there were 14-59 restatements per call.
+- **`orc ui` renders all of it**: a rank ladder showing which setting ANSWERED,
+  the lanes that read each key, a Lanes panel, and Extra ▸ Recovery's demotion
+  row with Promote. `orc doctor` gains `lane-keys-drifted`.
+
+**It did not make the payload smaller** - 208 files became 291, 26,507 lines
+became 33,204. Most waves measured as correctness, not deduplication. What
+changed is that there is now one place to fix each of these, and a lint that
+fails when a copy grows back. Two planned deletions were **measured and
+refused**, and the test suite's four-wave flake was diagnosed - with the honest
+caveat that three green runs are the gate and not proof.
+
+**Full entry: [CHANGELOG.md](CHANGELOG.md).**
 
 ---
 

package/bin/build-agents.js

@@ -22,24 +22,31 @@ const TEMPLATE = path.join(ROOT, "agents-src", "executor.template.md");
 const OUT_DIR = path.join(ROOT, "templates", "agents");
 
 // Score→model bands mirror templates/agents/MODEL-MAPPING.md and the single
-// 8-band score→model table in skills/orc/config.md (documented drift — change
+// score→model table in skills/orc/config.md (documented drift — change
 // together). `effort: null` = a model with NO effort ladder (haiku): the
 // generator omits the `effort:` frontmatter line entirely.
+//
+// v1.0.0 W4 — the table is SIX bands, not eight, and the `opus5_only` ladder is
+// TWO, not three. Four of these agents are named by NO default row:
+// names them, and they ship anyway (D14). They stay reachable through
+// `rubric_bands_override`, `orc diy` `fixed_executor` and `extra_fallback_agent`,
+// and deleting a generated file that no row happens to name today would be a
+// rename-shaped migration for what is only a table change. Their `band` string
+// says so rather than naming a range that no longer exists — a band label that
+// lies is worse than one that admits it is unreachable by default.
 const VARIANTS = [
-  { name: "orc-executor-opus-5-high",    model: "claude-opus-5",    effort: "high",   band: "highest-complexity [90,100]" },
-  { name: "orc-executor-opus-4-8-high",  model: "claude-opus-4-8",  effort: "high",   band: "very-high-complexity [80,90)" },
-  { name: "orc-executor-opus-4-7-high",  model: "claude-opus-4-7",  effort: "high",   band: "high-complexity [70,80)" },
-  { name: "orc-executor-opus-4-7-med",   model: "claude-opus-4-7",  effort: "medium", band: "upper-mid-complexity [65,70)" },
+  { name: "orc-executor-opus-5-med",     model: "claude-opus-5",     effort: "medium", band: "highest-complexity [90,100]" },
+  { name: "orc-executor-opus-5-low",     model: "claude-opus-5",     effort: "low",    band: "upper-complexity [65,90)" },
   { name: "orc-executor-sonnet-5-high",  model: "claude-sonnet-5",  effort: "high",   band: "mid-complexity [55,65)" },
   { name: "orc-executor-sonnet-4-6-high", model: "claude-sonnet-4-6", effort: "high",  band: "low-mid-complexity [40,55)" },
   { name: "orc-executor-sonnet-4-6-med", model: "claude-sonnet-4-6", effort: "medium", band: "low-complexity [30,40)" },
   { name: "orc-executor-haiku-4-5",      model: "claude-haiku-4-5",  effort: null,     band: "lowest-complexity [0,30)" },
-  // v0.35.0, widened v0.36.0 — the `opus5_only` ladder ONLY (default off). Same model,
-  // effort as the cost dial: [0,40) low · [40,80) medium · [80,100] high (the
-  // existing opus-5-high covers the top band in BOTH tables). These two are
-  // never dispatched by the default 8-band table.
-  { name: "orc-executor-opus-5-med",     model: "claude-opus-5",     effort: "medium", band: "opus5-only mid [40,80)" },
-  { name: "orc-executor-opus-5-low",     model: "claude-opus-5",     effort: "low",    band: "opus5-only low [0,40)" },
+  // NAMED BY NO BAND since v1.0.0 W4 (D14) — kept on disk, dispatched only when a
+  // user names one explicitly.
+  { name: "orc-executor-opus-5-high",    model: "claude-opus-5",    effort: "high",   band: "no default band — reachable via rubric_bands_override, orc diy fixed_executor, or extra_fallback_agent" },
+  { name: "orc-executor-opus-4-8-high",  model: "claude-opus-4-8",  effort: "high",   band: "no default band — reachable via rubric_bands_override, orc diy fixed_executor, or extra_fallback_agent" },
+  { name: "orc-executor-opus-4-7-high",  model: "claude-opus-4-7",  effort: "high",   band: "no default band — reachable via rubric_bands_override, orc diy fixed_executor, or extra_fallback_agent" },
+  { name: "orc-executor-opus-4-7-med",   model: "claude-opus-4-7",  effort: "medium", band: "no default band — reachable via rubric_bands_override, orc diy fixed_executor, or extra_fallback_agent" },
 ];
 
 function render(template, v) {