@azure-id/orc 1.9.2 → 2.1.0

package/templates/commands/orc-route.md

@@ -1,41 +1,11 @@
----
-description: You have a plan — this says which lane should build it, with the numbers it decided from. Plan-only: it refuses a request in words rather than guess
----
-
-Use the **orc-route** skill. Zero agents, nothing is built.
-
-**It routes a PLAN, and only a plan** — pasted ORC planning-output, a
-`plan-<name>.md` path, or a saved `orc/planner/<name>/` checkpoint (the same
-definition `skills/_shared/phases/plan-handoff.md` already uses). A plan carries real
-numbers: tasks, files per task, dependencies, facets, scores. Routing from those
-is arithmetic; routing from a sentence is guessing, so a request in words gets a
-refusal and a pointer to `/orc-plan`, not a guess.
-
-It reads the plan plus ORC's deterministic probes (`orc wiki status`,
-`orc pattern status`, `orc gotcha status`, `orc diy status`) and answers:
-
-```
-Plan: merchant-notifications — 7 tasks, 3 waves, 14 files touched
-      top score 78, two tasks marked risky
-
-→ /orc          the plan has risky tasks and a task above 70;
-                review and verify are worth paying for here
-   runner-up    /orc-mini — about 3x faster, but it skips full review
-                and verification. Fine only if you will read the diff yourself.
-   not possible /orc-fast — needs a fresh wiki (yours is STALE) and this plan
-                is 7 tasks; that lane runs ONE task
-
-Start /orc now?  [yes / no]
-```
-
-Every runner-up says what choosing it costs you. Every impossible lane names the
-condition blocking it **and** how to fix it. Risk beats size: a small plan with a
-cited risk still earns the full lane.
-
-`/orc-plan` also offers this automatically after **Save & stop**, so you rarely
-need to type it.
-
-New to ORC and wondering which command to use at all? That is
-`orc onboarding first-run`, not this.
-
-Plan (paste it, or give a path): $ARGUMENTS
+---
+description: You have a plan — this says which lane should build it, with the numbers it decided from. Plan-only: it refuses a request in words rather than guess
+---
+
+Use the **orc-route** skill. Zero agents, nothing is built. It routes a PLAN
+only — the same definition `skills/_shared/phases/plan-handoff.md` uses. It reads
+the plan's tasks, files, deps, `facets` and scores plus ORC's probes, then names
+the lane, the runner-up and its cost, and each impossible lane with its fix. A
+request in words gets a pointer to `/orc-plan`, never a guess.
+
+Plan (paste it, or give a path): $ARGUMENTS

package/templates/commands/orc-test.md

@@ -2,65 +2,10 @@
 description: Run the tests against the real running system — happy path to security — and report only what was observed
 ---
 
-Use the **orc-test** skill. Standalone — no plan, no build, no code written into
-your project.
-
-Every other ORC lane reasons about your system. This one **runs it**:
-
-> **A test that ran is a FACT; a test that was written is an OPINION.**
-
-ORC already has a lane that WRITES tests and never runs them (Phase 6.5,
-`test-generator/`). This is the mirror image, and the two never mix: `/orc-test`
-writes nothing into your test tree and runs everything.
-
-**It never edits the system it is testing.** If the server will not come up, it
-prints exactly what it ran and the tail of the output, and hands back. You fix
-it, and re-run for free — the same shape as `/orc-challenge`, and for the same
-reason: a session that just fixed the code cannot be trusted to measure it.
-
-**It never reports a result it did not observe.** Three verdicts and no fourth:
-`pass` (observed, matched), `fail` (observed, did not match), and `unknown` —
-not observed. `unknown` keeps its slot in the report and never becomes a pass.
-A flake is recorded, never retried away: there is no retry count, because if the
-same case answers differently twice, *that instability is the finding*.
-
-One pass:
-
-1. **Target** — `orc test init <slug>` asks what it must not guess: back end or
-   front end, local or remote, the base URL. On a remote target it also requires
-   `--authorized "<who authorized this, and where it is recorded>"`, stored
-   verbatim and reprinted at the head of every report. ORC cannot verify
-   authorization and does not pretend to — it makes the assertion impossible to
-   skip. Frozen, and never asked again.
-2. **Surface** — free, deterministic: an OpenAPI or GraphQL spec on disk, the
-   same spec at the target, route extraction by framework fingerprint, FE router
-   config. Anything ambiguous comes back as `unresolved[]` and is never guessed.
-   The **code-vs-live diff** is a first-class output: routes that answer live and
-   exist in no source file are zombie APIs.
-3. **Flow** — it digs the repo for how a request reaches your endpoint: the
-   route registration, the middleware in order, the handler, what it writes, what
-   must be true first, which fields name an object, and the login flow itself.
-4. **Environment** (local only) — it brings the system up and waits for health.
-   Five states, one next action each.
-5. **Cases** — the CLI derives the bulk for free: equivalence partitions,
-   boundary values, method and content-type negatives, stateful create → read →
-   update → delete sequences. An agent fills only what a schema cannot know.
-6. **Run** — paced, capped, and fenced to the frozen origin. A 429 is a RESULT,
-   not an error: it means rate limiting works. Every case leaves its exact
-   request, its exact response and a reproducible `curl`, with every credential
-   redacted **before the bytes reach disk**.
-7. **Report** — `orc/orc-test/<slug>/REPORT.md`, written for someone who does
-   not read code.
-
-The security tier is a **closed set** mapped to the OWASP API Security Top 10
-(2023), and it demonstrates a CONDITION rather than an extraction — confirming
-an exploit is your decision on your authority. With one identity, BOLA and BFLA
-report `UNCHECKABLE`, which keeps its slot and never becomes a pass.
-
-**The run folder is never staged.** Evidence contains real response bodies from
-a real system. The lane offers you the one `.gitignore` line; it does not edit
-`.gitignore` itself.
-
-Read the state back any time without this lane: `orc test status <slug>`.
+Use the **orc-test** skill. Standalone: no plan, no build, no code written into
+your project. It RUNS the system; Phase 6.5 (`test-generator/`) writes tests and
+never runs them. It never edits the system under test, and it never reports a
+result it did not observe. The report is `orc/orc-test/<slug>/REPORT.md`; the
+run folder is never staged. Read the state back with `orc test status <slug>`.
 
 The slug to open or reopen (or nothing, and it will ask): $ARGUMENTS

package/templates/commands/orc-wiki.md

@@ -1,64 +1,64 @@
----
-description: Build/maintain the project knowledge base (wiki) — Opus 4.8 high, expensive, multi-session, warns before scanning
----
-
-Use the **orc-wiki** skill. Start at Phase 0: auto-detect whether this is a
-repair of an unregistered wiki, a fresh build, a resume of an in-progress scan,
-or a refresh of an existing wiki, and branch accordingly. On a fresh build, show
-the cost warning and scan NOTHING until the user explicitly confirms. Refreshes
-also sweep for coverage gaps (changed files no doc covers → propose new areas)
-and dead docs (covered files gone → archive/delete, user decides). Every run
-registers via `orc wiki sync` and ends with the integrity self-check. Follow the
-skill's SKILL.md exactly.
-
-**Crosslink is always on.** Plain `/orc-wiki` — every scan, resume, incremental,
-full regenerate, or selective refresh — publishes/updates this repo's boundary
-tags (`wiki/crosslink/`) in the SAME pass as the docs, and a refresh never
-deletes them. There is no separate "generate crosslink" step in a wiki's normal
-life; the only crosslink config is the graph (`orc crosslink`), needed only to
-resolve what this repo consumes.
-
-**`/orc-wiki crosslink`** → the CROSSLINK-ONLY branch (Phase 3c) is a LEGACY
-BACKFILL: publish tags + resolve consumption from the existing docs'
-`Contracts & shapes` rows (opening only the files they anchor), for wikis whose
-docs predate v0.24.0 and so have no `wiki/crosslink/` yet. No area is re-scanned,
-no doc rewritten. On a wiki scanned at ≥v0.24.0, missing tags are not this
-branch — `orc wiki sync --check` names the real fix. Never a refresh.
-
-**`/orc-wiki crosslink compile`** → the one-shot CROSSLINK COMPILE branch
-(v0.33.0 — references/crosslink-compile.md): resolve/consume from the graph →
-generate the federation atlas (`wiki/crosslink/atlas.md`) → write it into each
-linked repo → inject/update the CLAUDE.md pointer block locally and in each
-linked repo (in-place, user content byte-preserved). Requires a crosslink
-config with ≥1 edge; every step warn-only; never a re-scan. Peer writes are
-FILE writes only — never a commit or push.
-
-**`/orc-wiki update <doc-or-topic>`** → ONE doc, re-scanned. A filename goes
-straight into the targeted refresh. A topic ("the remittance feature") is
-resolved first with `orc wiki resolve` — free, no scan — and an AMBIGUOUS result
-is a question for you, never a guess. Branch detection and area planning are both
-skipped: the doc exists, so its coverage area is already in its own header.
-
-**`/orc-wiki add "<topic>"`** → ONE new doc, in a wiki that already exists, with
-no other area re-planned. It resolves the topic first (if something already
-covers it, that is an `update` and it says so), proposes a coverage scope from
-path names for you to correct, confirms the slug, the covers, the tier and the
-cost in ONE turn, and scans nothing until you say yes. It ends with
-`orc wiki refs`, the derived-reference sweep — adding a doc moves more derived
-surfaces than changing one does: the registration, the orientation page, the
-architecture overview, the CLAUDE.md pointer's doc count, and any crosslink tag
-left anchored to a file that is gone. Only the registration is repaired for you;
-the rest is reported with its command, because a sweep that silently regenerated
-prose would be spending money nobody asked it to spend.
-
-| Argument | Branch |
-|---|---|
-| *(none)* | Phase 0 auto-branch: repair / fresh / resume / refresh (delta default) |
-| `update <doc>` | targeted refresh of ONE doc (skips branch detection + area planning) |
-| `update "<topic>"` | resolve the topic to a doc, then refresh it |
-| `add "<topic>"` | reserve + scan + write ONE new doc, then sweep every derived reference |
-| `crosslink` | Phase 3c legacy backfill (publish tags from existing docs) |
-| `crosslink compile` | one-shot resolve + atlas + CLAUDE.md injection (local + peers) |
-
-Optional focus (`update <doc>` · `add "<topic>"` · `crosslink` ·
-`crosslink compile`): $ARGUMENTS
+---
+description: Build/maintain the project knowledge base (wiki) — Opus 5.5 low, expensive, multi-session, warns before scanning
+---
+
+Use the **orc-wiki** skill. Start at Phase 0: auto-detect whether this is a
+repair of an unregistered wiki, a fresh build, a resume of an in-progress scan,
+or a refresh of an existing wiki, and branch accordingly. On a fresh build, show
+the cost warning and scan NOTHING until the user explicitly confirms. Refreshes
+also sweep for coverage gaps (changed files no doc covers → propose new areas)
+and dead docs (covered files gone → archive/delete, user decides). Every run
+registers via `orc wiki sync` and ends with the integrity self-check. Follow the
+skill's SKILL.md exactly.
+
+**Crosslink is always on.** Plain `/orc-wiki` — every scan, resume, incremental,
+full regenerate, or selective refresh — publishes/updates this repo's boundary
+tags (`wiki/crosslink/`) in the SAME pass as the docs, and a refresh never
+deletes them. There is no separate "generate crosslink" step in a wiki's normal
+life; the only crosslink config is the graph (`orc crosslink`), needed only to
+resolve what this repo consumes.
+
+**`/orc-wiki crosslink`** → the CROSSLINK-ONLY branch (Phase 3c) is a LEGACY
+BACKFILL: publish tags + resolve consumption from the existing docs'
+`Contracts & shapes` rows (opening only the files they anchor), for wikis whose
+docs predate v0.24.0 and so have no `wiki/crosslink/` yet. No area is re-scanned,
+no doc rewritten. On a wiki scanned at ≥v0.24.0, missing tags are not this
+branch — `orc wiki sync --check` names the real fix. Never a refresh.
+
+**`/orc-wiki crosslink compile`** → the one-shot CROSSLINK COMPILE branch
+(v0.33.0 — references/crosslink-compile.md): resolve/consume from the graph →
+generate the federation atlas (`wiki/crosslink/atlas.md`) → write it into each
+linked repo → inject/update the CLAUDE.md pointer block locally and in each
+linked repo (in-place, user content byte-preserved). Requires a crosslink
+config with ≥1 edge; every step warn-only; never a re-scan. Peer writes are
+FILE writes only — never a commit or push.
+
+**`/orc-wiki update <doc-or-topic>`** → ONE doc, re-scanned. A filename goes
+straight into the targeted refresh. A topic ("the remittance feature") is
+resolved first with `orc wiki resolve` — free, no scan — and an AMBIGUOUS result
+is a question for you, never a guess. Branch detection and area planning are both
+skipped: the doc exists, so its coverage area is already in its own header.
+
+**`/orc-wiki add "<topic>"`** → ONE new doc, in a wiki that already exists, with
+no other area re-planned. It resolves the topic first (if something already
+covers it, that is an `update` and it says so), proposes a coverage scope from
+path names for you to correct, confirms the slug, the covers, the tier and the
+cost in ONE turn, and scans nothing until you say yes. It ends with
+`orc wiki refs`, the derived-reference sweep — adding a doc moves more derived
+surfaces than changing one does: the registration, the orientation page, the
+architecture overview, the CLAUDE.md pointer's doc count, and any crosslink tag
+left anchored to a file that is gone. Only the registration is repaired for you;
+the rest is reported with its command, because a sweep that silently regenerated
+prose would be spending money nobody asked it to spend.
+
+| Argument | Branch |
+|---|---|
+| *(none)* | Phase 0 auto-branch: repair / fresh / resume / refresh (delta default) |
+| `update <doc>` | targeted refresh of ONE doc (skips branch detection + area planning) |
+| `update "<topic>"` | resolve the topic to a doc, then refresh it |
+| `add "<topic>"` | reserve + scan + write ONE new doc, then sweep every derived reference |
+| `crosslink` | Phase 3c legacy backfill (publish tags from existing docs) |
+| `crosslink compile` | one-shot resolve + atlas + CLAUDE.md injection (local + peers) |
+
+Optional focus (`update <doc>` · `add "<topic>"` · `crosslink` ·
+`crosslink compile`): $ARGUMENTS

package/templates/hooks/README.md

@@ -214,18 +214,76 @@ move, and it tells you why.
 Every component can be changed: its words, its colour, its shape, how wide it
 is, and when it is allowed to disappear.
 
-**The shape decides what the other settings can do.** Only these shapes print a
-short name in front of the value: `plain`, `label-value`, `bracket`, `angle`,
-`badge`, `pill` and `stack`. A bar, an icon and a bare value have no room for
-one, so the panel switches the Name box off for them and says so. The same is
-true of the number settings: a bar has a width and a colour ramp, and no number
-format at all.
+**The shape decides what the other settings can do.** The panel switches off a
+setting that the shape does not use, and says so.
+
+**Words around any shape** (v2.0.4). Every shape draws the name you type. You
+choose where it goes: before, after, above or below the part. A bar can also have
+text before and after it (for example `[██░░]`) and its number beside it. If you
+type no name, only `plain`, `label-value`, `bracket`, `angle`, `badge`, `pill` and
+`stack` print the part's built-in name.
+
+**Captions.** A caption is a short text on a row above or below a part, at the
+column of that part. `{value}` and `{label}` in the caption are replaced. A caption
+makes the line one row taller.
+
+**Small text.** A terminal has no font size. The letter styles `small` (ꜱᴍᴀʟʟ
+ᴄᴀᴘꜱ), `super` (ˢᵘᵖᵉʳ) and `sub` (₆₁) use Unicode letters that look smaller.
+A character with no small form stays as it is.
+
+**Bars in your own colours and characters.** A bar can have its own fill colour,
+empty colour, colour range (for example `#22c55e,#eab308,#ef4444`, blended cell by
+cell on `gradient`), and its own fill and empty characters (one cell each).
+
+**Every part** can also have brackets, space on the left and right, a background,
+any `#rrggbb` colour, more than one weight, and its own colour and symbol per
+state. A line can be aligned right or centre, and its separator can have a colour.
+`text`, `divider`, `spacer`, `icon-static`, `fill` (pushes the rest to the right
+edge) and `config` take their text in the part's settings.
+
+**Claude Code removes the spaces at the start of every row.** So when a row of
+your status line starts with a space (a caption row, a line prefix, a
+right-aligned line), ORC makes that first space a braille blank (U+2800). It is one
+cell wide and Claude Code keeps it, so a caption stays above or below its own part.
+Under `ORC_STATUSLINE_ASCII=1` this is not done, because U+2800 is not ASCII.
+
+**Pets that move** (the "Pets and motion" group): a pixel cat drawn in braille
+dots, a mouse, a cat that chases the mouse, the text cat ᓚᘏᗢ, pac-man, a fish, a
+bird and a dog. Each can `run` across its track, `bounce` right and back, or stay
+`idle` and move its legs.
+
+**Motion needs a timer.** Claude Code redraws the status line when something
+happens (a message, typing), or every `refreshInterval` seconds if you set it (at
+least 1). Set it with:
+
+```
+orc statusline refresh 1
+```
+
+and remove it with `orc statusline refresh off`. With the timer the hook runs
+every second even when you do nothing, and each run starts `node`. So a pet moves
+about one step per second.
+
+**Weather** (`weather`, `weather-icon`, `weather-desc`). This is the ONLY part of
+the status line that uses the network. The hook itself never waits for it: it reads
+`.claude/orc/weather.json`, and when that is older than 30 minutes it starts
+`orc-weather-fetch.js` in the background, which asks wttr.in and writes the file.
+With an empty `location`, wttr.in finds your place from your network address. It
+runs only while a weather part is on your layout. `ORC_STATUSLINE_NO_NET=1` stops
+it. Every text it gets back is cleaned of control characters before it is saved.
+
+**The panel shows your unsaved changes.** The picture above the board is drawn
+from a temporary copy with your staged changes, so you see the result before you
+press Apply. Nothing is written until you press Apply.
+
+A layout may not carry a control character (for example ESC) in any text. It is
+printed to your terminal, so the CLI refuses it.
 
 **Three things a terminal cannot do**, said plainly so you do not look for them:
 
 | You may want | What you get |
 |---|---|
-| A bigger font | The terminal owns the font size. Use **bold**, or make a component wider — a bar at width 12 is a big object. |
+| A bigger font | The terminal owns the font size. Use **bold**, a small letter style for the words around it, or make a component wider — a bar at width 12 is a big object. |
 | A blinking part | Refused. Half of terminals turn it off, and no part of a status line needs it. |
 | Icon-font symbols | Not shipped. They need a font we cannot check for, and they draw as empty boxes without it. |
 
@@ -414,6 +472,40 @@ outside an ORC run, and never when the map does not exist.
 
 ---
 
+## The session hook
+
+This is a fourth hook, `orc-session-hook.js`. It has four jobs. All of them are
+silent when no ORC run is open.
+
+- **The bell.** A turn of an ORC run ends, and your terminal rings once. This
+  job is off until you turn it on:
+
+  ```
+  orc config set notify bell   # ring when a turn of a run ends
+  orc config set notify off    # silent (the default)
+  ```
+
+  It rings only when the run moved since the last bell. A normal chat never
+  rings. It sends no OS notification and uses no network.
+- **After a compaction.** Claude Code keeps only the start of each skill when it
+  compacts a long session, so a long run can lose its place. When a run is in
+  flight, the hook adds ONE line: the run name, and the `state-of-play.md` file
+  to read first. It costs about 40 tokens, once per compaction.
+
+- **The narration guard** (v2.0.2). A run dispatched agents but wrote no trace
+  line of its own. Then the hook stops the turn ONCE and says which command
+  writes the trace. It never stops twice, and never stops a subagent.
+- **The review card** (v2.0.2). When a reviewer, verifier or judge starts, the
+  hook asks `orc gotcha card` for the files git sees as changed and gives the
+  card to that agent. No match → nothing. This is why a review always sees the
+  mistakes this project already made, even if the lane forgot the card.
+
+It never writes model text, and it blocks a stop only for the narration guard.
+`orc doctor` tells you whether all three events are wired (`Stop`,
+`SessionStart compact`, `SubagentStart`).
+
+---
+
 ## For maintainers
 
 - The hook is `orc-statusline.js`. `orc init` installs it and wires it into
@@ -438,6 +530,16 @@ outside an ORC run, and never when the map does not exist.
   authored. If the compiled file is missing, stale, or does not pass a cheap
   shape check, the hook silently renders the shipped lines instead and
   `orc doctor` names the reason.
+- **Stale means the parts changed, not the version** (v2.0.3). `orc init` and
+  `orc update` write `catalog_hash` into `hooks/orc-version.json`, and the hook
+  compares it with the `catalog_hash` in `statusline.lock.json`. An install with
+  no hash compares the version, as before. `orc update` also recompiles every
+  layout that exists and validates, so an upgrade never leaves your bar on the
+  shipped lines. A good render deletes `orc/statusline-state.json`, so
+  `orc doctor` never reports a fallback that is already gone.
+- `orc statusline show --json` carries `hook`: the hook the settings point to,
+  its version, whether it will run this layout, the last fallback, and the fix.
+  `orc ui` shows that on the status card.
 - The cache file is `.claude/orc/usage-session.json`. The hook reads it once and
   writes it once, after the text is ready. It stores raw numbers only — never a
   word like `fresh` or `STALE`, which is computed each time it is shown.