@azure-id/orc 0.55.0

package/templates/skills/orc-budget/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: orc-budget
+description: >
+  What a run will cost, in the unit YOU are billed in. Use for "/orc-budget",
+  "what will this plan cost", "which lane is cheaper here", "how much did that run
+  burn", "will this hit my limit". Given a PLAN — not a sentence — it forecasts a
+  token vector (fresh input, cache write, cache read, output kept separate) per
+  scoring band, then renders it four ways: tokens, dollars from a dated price
+  table, percent of your 5-hour session window, and context-window risk per task.
+  Every number is a range with a sample count, joined from Claude Code's own usage
+  transcripts and ORC's traces. It never blocks a run and never invents a figure.
+---
+
+# ORC-BUDGET
+
+The lane that **measures** — forwards.
+
+Account-level burn tracking is solved: `/usage`, cc-budget, eight commercial
+dashboards. What none of them can answer is the only question that changes a
+decision: **given THIS plan — 14 tasks, 4 waves, top score 78 — what will it burn,
+and what does each lane burn instead?**
+
+**The one-sentence contract: a forecast is a RANGE WITH A SAMPLE COUNT, never one
+number, and never a figure ORC did not measure.**
+
+## Tokens are the unit of truth. Everything else is derived.
+
+The core object is a **token vector**, never a scalar. Four kinds, because they
+price and behave completely differently:
+
+| Kind | Typical share | Relative price | Why it must stay separate |
+|---|---|---|---|
+| `input` | small | 1× | fresh, uncached prompt |
+| `cache_write` | medium | ~1.25× | writing the cache — a real cost |
+| `cache_read` | **usually the largest** | ~0.1× | nearly free, and it dominates the raw count |
+| `output` | small | ~5× | the most expensive tokens in the run |
+
+A forecast of "407k tokens" hides that ~80% of it is cache reads costing a tenth
+of list. A forecast of "$7.02" hides that a Max user does not pay it. **So the CLI
+computes the vector once and renders it four ways.** Never a blended token count as
+the headline; `cache_read` is always separable.
+
+Plus one non-token line, because it bills separately and is in the data:
+`server_tool_use` → web search and web fetch requests.
+
+## Four views of the same vector (`budget_units`, default `auto`)
+
+| View | Unit | Who it is for |
+|---|---|---|
+| **tokens** | in / cache-write / cache-read / out, per band | everyone — always shown |
+| **usd** | dollars from a dated table | API-billed, enterprise |
+| **quota** | % of the 5-hour window, % of the weekly limit | **Pro / Max — most users** |
+| **context** | peak prompt per dispatch vs its window | shown when a task is at risk |
+
+**A dollar figure is the wrong headline for most Claude Code users.** On Pro or Max
+you do not pay per token — you burn a 5-hour session window and a weekly ceiling.
+"$7.02" means nothing to that user; "18% of your 5-hour window" means everything.
+`budget_units: auto` picks from `budget_plan`; `--as tokens|usd|quota|context|all`
+overrides.
+
+## Context pressure — a forecast output nobody else has
+
+A run does not only cost money. It can hit **compaction**, which silently degrades
+quality and is invisible in every spend tool. ORC can forecast it because ORC
+composes the slice, and the corpus records the **peak prompt** of every past
+dispatch. A task forecast above 90% of its model's window is reported before the
+wave, not after the damage — with three options: split the task, drop a doc nobody
+uses from the slice (`orc wiki usage`), or raise the band so a larger-window model
+takes it.
+
+## Where the numbers come from — and the join is the moat
+
+```
+  transcript  →  isSidechain block, model, effort, 4 token counts, peak, timestamp
+  ORC trace   →  DISPATCH line: task, score, band, expect=<model>/<effort>,
+                 the wiki: continuation, RETURN with actual_model
+  join key    →  the run's time window + sidechain grouping + model match
+```
+
+Claude Code writes a JSONL transcript per session under
+`~/.claude/projects/<slug>/`. That gives the **cost**. ORC's own traces give the
+**meaning** — which task, which band, which model was expected, whether it was
+requeued. **Neither is enough alone, and nobody else has the right-hand column.**
+Details and honesty rules: `references/corpus.md`.
+
+## Honesty rules — all six, always
+
+1. **No transcripts?** Forecast in **tokens only** from ORC trace metadata and
+   print *"dollars and quota unavailable: no local usage data"*. Never invent a
+   price.
+2. **`unattributed` is ALWAYS printed**, including when zero. A sidechain block that
+   could not be joined to a task counts into it and is never silently dropped.
+3. **Cache reads get their own p50/p90**, not a share of a blended number. They are
+   the most variable component.
+4. **No dollar figure without a dated price table** (`budget_price_table`; default
+   the shipped one). Older than 90 days → a staleness warning beside every figure.
+   **No quota figure without a known plan** — `budget_plan` is asked ONCE and
+   stored, because a wrong guess rendered as a percentage is worse than no
+   percentage.
+5. **A band below `budget_min_samples` (default 5) is printed as low-confidence.**
+   The top of the range is soft and the output says so.
+
+6. **A foreign dispatch is priced from its OWN dated table, or not at all**
+   (v0.50.0). A task can execute on a non-Claude worker
+   (`_shared/extra-dispatch.md`); its four token kinds arrive the same way and
+   are never blended, but an Anthropic rate applied to somebody else's bill is
+   fiction — so `bin/pricing.json`'s `providers` block is the only source, and
+   **every `models` map in it ships EMPTY on purpose**. Several of these vendors
+   price by peak window or by tier, one sells a subscription rather than tokens,
+   and one is a passthrough with a surcharge; a shipped figure wrong by 2x is
+   worse than none, because a wrong figure gets believed. `orc extra rates`
+   lists the pairs your traces actually used and prints the JSON to paste.
+   Until then: **`usd` reads as an em dash, never zero and never an estimate.**
+
+   Two further foreign-only distinctions, and collapsing either is a wrong
+   number rather than a rounder one:
+
+   - **`usage: null` is not `{0,0,0,0}`.** Engine `cli` frequently reports no
+     token counts. Null means *unknown*; four zeros would mean *free*. Carry the
+     denominator (how many dispatches the vector came from) into every total.
+   - **`cache_write: 0` on engine `api` IS a measurement.** An
+     OpenAI-compatible endpoint caches implicitly and has no write charge to
+     report. That zero is true and must not be smoothed into an average.
+
+   `orc extra stats --json` computes all of this per profile per band. Render
+   it; do not recompute it.
+
+## It refuses a sentence
+
+`orc budget forecast` takes a **plan file**. Forecasting from a request in words is
+guessing, and a guess that looks computed is worse than no answer — the same reason
+`/orc-route` is plan-only. No `- id:` task blocks → exit 3 with the reason and a
+pointer to `/orc-plan`.
+
+**With no history at all:**
+
+```
+BUDGET · no forecast
+  0 joinable dispatches in .claude/orc/logs/ and no usable transcripts.
+  I will not invent numbers. Run /orc or /orc-mini once, then ask again.
+  A floor from the public price table only:  orc budget forecast --naive
+```
+
+---
+
+## Phases
+
+```
+U0  preflight (silent)   orc budget rates --json   (lazily calibrates on a miss)
+U1  input                a plan file · a run slug · "just the rates"
+U2  forecast / actual     the CLI computes; this lane RENDERS and explains
+U3  decide               ONE question: which lane · split a task · proceed
+U4  record               one end-of-run trace packet
+```
+
+**U2 does no arithmetic.** `orc budget forecast|actual|rates` are the only engine —
+this skill never re-derives a band, a price, a percentile or a total. Same rule as
+the wiki tier and the DIY stepper: a second idea of the number is drift no lint
+could see.
+
+**U0 opens the run properly.** Write `log_dir/.current` =
+`run-budget-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step. Both, or neither. A lane the protocol declares must be a lane
+something OPENS, or every counting tool reports it as a permanent zero.
+
+**U1 asks `budget_plan` ONCE** if it is `auto`, as a single line, and stores it:
+
+```
+Which plan are you on? It changes the primary unit, and I will not guess.
+  1 Max 20x    2 Max 5x    3 Pro    4 API (billed per token)    5 Skip — tokens only
+```
+
+**U3 is a real question, not a summary.** The forecast exists to change a decision:
+
+```
+1  Proceed on /orc            1.23M raw · 564k weighted · 18% of a window
+2  Run /orc-mini instead      0.41M raw · 188k weighted ·  6%   (no review/verify phase)
+3  Split T12                  it forecasts 189k of a 200k window — likely to compact
+4  Your own — re-plan smaller, or just show me the numbers again
+```
+
+## Where this shows up in `/orc`
+
+- **Phase 2 intake** — the forecast at the batch-pause confirmation, so the pause
+  schedule doubles as a budget checkpoint.
+- **Every pause** — spend so far vs forecast to here, in the primary unit.
+- **`/orc-route`** — a cost column per lane, so routing stops being qualitative.
+- **Ship** — actual vs forecast, fed to `/orc-retro`.
+- **Context risk** — a task above 90% of its window is reported to the planner
+  BEFORE the wave.
+
+**It never blocks a run.** Advisory always. The one hard stop in this area is the
+existing `run_budget_dispatches` gate, which counts dispatches, not tokens, and is
+not part of this lane.
+
+## Behavior trace (always on)
+
+Follow `../orc/references/trace-protocol.md`. Lane name `budget`.
+**Single-dispatch lane: exactly ONE end-of-run packet** to
+`orc-trace-writer-haiku-4-5` after U4 and BEFORE `.current` is deleted. It carries
+`run_meta`, the events (probe, forecast, the units rendered) and the U3 answer as
+`decisions`. A run that ends with
+`zero new trace lines is a protocol violation`.
+
+Zero new agents. There is nothing to dispatch: the whole forecast is deterministic.
+
+## How this lane fails — and the rule that prevents each
+
+| Failure | Prevention |
+|---|---|
+| One confident number | A range with a sample count, always |
+| A blended token total as the headline | Four kinds, always separable |
+| A dollar figure for a Max user | `budget_units: auto` off `budget_plan` |
+| A price from an undated table | Dated table, 90-day staleness warning |
+| A quota percent from a guessed plan | Asked once, stored, never inferred |
+| Tokens silently dropped from the total | `unattributed` always printed |
+| A forecast from a sentence | Plan-only, exit 3 with the reason |
+| It blocks a run | Advisory always |
+| The skill recomputes a band | The CLI is the only engine |
+
+## Rules this lane always keeps
+
+Never one number · never a blended headline · never an invented price · never a
+guessed plan · never drop `unattributed` · never forecast from prose · never block ·
+never compute what the CLI computes.

package/templates/skills/orc-budget/references/corpus.md

@@ -0,0 +1,87 @@
+# Reference — the corpus, the join, and what may be claimed from it
+
+Loaded at U2 when a number needs explaining. Nothing here is computed by the
+skill — `orc budget calibrate` owns all of it. This file exists so a user can be
+told WHY a number is what it is, and where it stops being trustworthy.
+
+## The two halves
+
+**Half one — the cost.** Claude Code writes a JSONL transcript per session at
+`~/.claude/projects/<project-slug>/*.jsonl`, one line per message. Every assistant
+line carries:
+
+```json
+"usage": { "input_tokens": 2, "cache_creation_input_tokens": 44439,
+           "cache_read_input_tokens": 18432, "output_tokens": 582,
+           "server_tool_use": { "web_search_requests": 0, "web_fetch_requests": 0 } }
+```
+
+and the LINE carries `model`, `timestamp`, `cwd`, `sessionId` and — the field that
+makes this work — **`isSidechain`**, which is how a subagent dispatch is told apart
+from the main thread.
+
+**Half two — the meaning.** ORC's own trace: the `DISPATCH` line's task, the
+`SCORE` line's band and facet vector, `expect=<model>/<effort>`, the `wiki:`
+continuation, `RETURN`'s `actual_model`, `OUTCOME`'s retries and requeues.
+
+## The join
+
+1. Group contiguous `isSidechain` lines in one session on one model into **one
+   dispatch**. A gap over 20 minutes starts a new group.
+2. For each trace, take the run's own time window from its first and last
+   timestamped lines.
+3. Match each `DISPATCH` line to the nearest unclaimed group in that window whose
+   model equals the dispatch's expected model.
+4. Anything left over goes to **`unattributed`**.
+
+**Timestamps come from two clocks and both are honoured as written:** a trace line
+carries LOCAL wall clock, a transcript line carries ISO UTC. Both resolve to the
+same instant on the same machine. A join that silently treated one as the other
+would be off by the timezone offset and quietly attribute nothing.
+
+## What `unattributed` really means
+
+It is not an error and it is not waste. Common, legitimate causes:
+
+- the main thread's own tokens (never a sidechain, never joined to a task)
+- a dispatch from a lane that writes no trace (`/orc-retro`, `/orc-explain`)
+- an ad-hoc read-only recon dispatch (`/orc-quick`, `/orc-brainstorm`,
+  `/orc-boundary`) — deliberately unpinned, so the hook writes no `SPAWN`
+- a session where `.current` was lost mid-run
+
+**It is always printed anyway.** A total that quietly excludes tokens somebody paid
+for is the one number in this lane that must never be silently wrong.
+
+## What may be claimed, and what may not
+
+| May be claimed | May NOT be claimed |
+|---|---|
+| "This band cost this much, over N samples" | "This run will cost exactly X" |
+| "Cache reads were 74% of raw tokens" | "You will be charged $X" — unless `budget_plan: api` |
+| "This task's peak prompt was 189k of 200k" | "This task will compact" — it is a forecast |
+| "2 bands have fewer than 5 samples" | Filling a thin band from the band next door |
+| "Weighted 564k / raw 1.23M" | One of the two on its own |
+
+**Why report both weighted and raw:** raw is what fills a context window and a rate
+limit; weighted (cache reads at 0.1×) is what fills an invoice. They move
+differently, and a single number hides whichever one is about to bite.
+
+## The price table
+
+`bin/pricing.json`, or whatever `budget_price_table` points at. Four rates per
+model — never one, for the same reason the vector has four components. Dated:
+`as_of`, and older than 90 days puts a staleness warning next to every dollar
+figure. **Never patch a rate to make a forecast look right.**
+
+The `plans` block holds WEIGHTED-token capacities for the quota view. They
+approximate a published allowance; they are not a metered balance. The renderer says
+so, and that honesty is why the quota view is usable at all.
+
+## Feeding `/orc-retro`
+
+`orc budget actual <run-slug>` emits per-band forecast-vs-actual with a diff
+percent. `/orc-retro` already calibrates the score→model table from process signals
+(retries, requeues, downgrades); this adds the cost signal, so a band can be judged
+on what it COST as well as on how smoothly it ran. A band that always lands inside
+p90 is calibrated; one that lands at +151% twice has a facet problem, not a price
+problem.

package/templates/skills/orc-challenge/README.md

@@ -0,0 +1,142 @@
+# Build your own `/orc-challenge` cycle
+
+This is the maintainer's guide to the lane. If you just want to use it, run
+`/orc-challenge` and answer the seven intake questions.
+
+## The one design decision everything else follows from
+
+**The judge and the fixer must never share a context.**
+
+Everything unusual about this lane is downstream of that one sentence:
+
+- there is no in-session repair loop, because a session that wrote the fix would
+  grade its own homework
+- the judge's dispatch slice is paths and ids only, because a summary of what
+  changed is written by the party with an interest in passing
+- PASS is computed by the CLI, because a judge that CAN pass something can be
+  talked into passing something
+- the stop is the deliverable, not an interruption
+
+If you are tempted to add a `challenge_same_session` escape hatch: that config
+key is how the premise dies. It is deliberately not there.
+
+## The shape of one iteration
+
+```
+C2 lint (free)  →  C3 the council  →  C4 judge  →  C5 record (the CLI decides)
+                    (parallel, <=3)                       ├── PASS → C7 final report
+                                                          └── FAIL → C6 advise → C8 STOP
+```
+
+One iteration is C2 → C8. The user then fixes in a **different session** and
+comes back, and the whole thing runs again with the carried findings.
+
+## The eight agents, and why each is pinned where it is
+
+| Agent | Effort | Why that effort |
+|---|---|---|
+| `orc-challenge-judge-opus-5-high` | high | D2 is the only dimension no computer can reach, and it is the expensive one |
+| `orc-challenge-advisor-opus-5-med` | medium | grouping twelve findings into three causes is pattern work, not deep reasoning |
+| `orc-challenge-reader-opus-5-low` | **low, on purpose** | a harder-thinking reader reasons AROUND the gaps D4 exists to find. A stronger configuration is a WORSE instrument |
+| `orc-challenge-contrarian-opus-5-high` | high | a shallow contrarian returns the three surface complaints the free lint already caught |
+| `orc-challenge-outsider-opus-5-low` | **low, on purpose** | a harder-thinking outsider reasons its way AROUND an unexplained acronym and reports the document is fine |
+| `orc-challenge-executor-opus-5-med` | medium | pattern work against a concrete artifact — the same class as the advisor |
+| `orc-challenge-principles-opus-5-high` | high | rebuilding a problem statement from the ground up is the deepest reasoning in the lane |
+| `orc-challenge-expansionist-opus-5-med` | medium | pattern work again, pointed at upside instead of at defect |
+
+All eight are `claude-opus-5`, so **`opus5_only` is a no-op for this lane** —
+zero new agent pairs, no `LEGACY_KEYS` entry, no rename churn. The lane is
+unaffected, not exempt.
+
+**Effort here is a MEASUREMENT choice, not a cost choice.** That is why there is
+no model or effort config key: a key that lets `outsider: low` be tuned is a key
+that lets the instrument be broken.
+
+## The council (v0.49.1)
+
+Five of those eight are new, and the design is in `references/council.md`. Three
+sentences carry it:
+
+- **A lens raises; only the judge resolves.**
+- **ORC proposes the council; the user picks it.** `--council` has no default and
+  `init` refuses by name — **a lane that picks its own council has broken this
+  contract.**
+- **Two lenses never touch the pass gate.** The expansionist returns
+  `opportunity`, the first-principles thinker returns `premise`; neither has a
+  severity, and forcing either to have one would make it lie.
+
+The gate that makes five extra reviewers safe is `council_coverage_pct`, derived
+by `orc challenge record` from `iteration-NN/council/*.json` on disk — **not from
+the judge's account of them.** The judge cannot shrink the set by omission.
+
+They are pinned and dispatched BY NAME for one reason beyond the trace hook: **a
+verdict must be attributable.** `/orc-retro` can then mine downgrade behaviour on
+judging runs like any other lane.
+
+## Adding a lens
+
+1. `references/council.md` — the roster row, what it is for, how it fails, and
+   why its effort is what it is.
+2. `bin/cli.js` — `CHALLENGE_LENSES` and `CHALLENGE_LENS_META`. Pick a prefix
+   nothing else uses; prefixes are the raiser's signature and `record` gates on
+   them.
+3. The agent file, named in `bin/verify-package.js`, with a `MODEL-MAPPING.md`
+   row that states the reason for the effort.
+4. A golden test comparing 1 and 2. The roster is documented drift the token
+   lint cannot see, because it is a list, not a token.
+
+Decide its CLASS first. If it cannot honestly carry a `serves`, it is not a
+finding lens and it must never enter `findings[]`.
+
+## Adding a dimension
+
+1. `references/dimensions.md` — the definition, the evidence a finding must
+   carry, and which agent produces it.
+2. `bin/cli.js` — `CHALLENGE_DIMS` and the `--dimensions` validator.
+3. `references/kinds.md` — whether any kind selects it by default.
+4. A golden test comparing 1 and 2. The enum is documented drift the token lint
+   cannot see, because it is a list, not a token.
+
+## Adding a lint check
+
+1. `bin/cli.js` — the check itself, in `challengeLint`. Emit `L-###` with a
+   dimension and a line number.
+2. `references/plain-english.md` — the row in the table, and the word list if it
+   has one.
+3. A fixture in `test/`.
+
+Keep both honesty rules intact: it is a signal, not a verdict, and it is
+heuristic. A lint that starts blocking is a lint that starts being argued with.
+
+## Adding an artifact kind
+
+`references/kinds.md` and `CHALLENGE_KINDS` in `bin/cli.js`. A kind is a
+PROPOSAL of a dimension set and a template hint — never a silent application of
+one.
+
+## What this lane must never grow
+
+- **an in-session fix.** See above.
+- **a hard loop cap.** Each turn is a separate human sitting down to work.
+  `stalled` measures instead, and offers three real options.
+- **a model or effort config key.** That is the pinned agents' job, and the
+  efforts are measurements.
+- **a `challenge_council` config key.** A global default roster would silently
+  answer the one question the council exists to ask.
+- **a `block` mode on any council output.** Opportunities and premises never
+  gate; the finding lenses gate through the EXISTING severity bar and nothing
+  else.
+- **auto-severity from corroboration.** Two lenses agreeing is a signal, and
+  churn is a signal, not a verdict.
+- **a `block` mode on `challenge_gate`.** The `/orc-pact` precedent: the payoff
+  is knowing, not gating.
+- **a second definition of "a plan", "a state", or "fresh".** If a state exists,
+  the CLI computes it and everything else renders it.
+
+## Reading order for a new maintainer
+
+`references/intake.md` (it defines what every later file grades against) →
+`council.md` → `sealed-slice.md` → `rubric.md` → `conservation.md` →
+`cycle-state.md` → `fix-brief.md`. Then `examples/tsd-two-iterations.md` for the
+whole thing end to end, and `examples/council-full-roster.md` for a run where
+the first-principles thinker lands a premise challenge and the goal moves.