@azure-id/orc 1.8.1 → 1.9.0

package/CHANGELOG.md

@@ -10,6 +10,392 @@ Format: `### v<version> — <title> _(<date>)_`.
 
 ---
 
+### v1.9.0 — the lean lanes learn to look before they leap _(2026-09-21)_
+
+**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`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+`/orc-quick` and `/orc-mini` are the two lanes people reach for most, and both
+were working half blind. The code graph could tell them WHERE a symbol is, and
+was forbidden from telling them WHAT BREAKS. A bug fix was never shown failing
+before it was fixed. Read-only work was dispatched by model name, so nothing in
+ORC could see it. This release fixes those three things and trims what the two
+lanes cost to load.
+
+**Nothing you have to do.** No new config key. No new prerequisite. If the code
+graph is off, every new call says so in one line and the lanes work as before.
+
+**A bug is now shown RED before it is fixed.**
+
+- A request like *"the orders page returns 500, find it and fix it"* is sorted
+  as a **defect**, and the slice carries a `repro` field. The executor writes
+  the reproduction FIRST — a failing test in your own framework, or a command —
+  runs it, captures the red run, implements, and runs it again for the green.
+- Both runs are printed, and the trace carries `REPRO red :: <cmd> exit=1` and
+  `REPRO green :: <cmd> exit=0`. `/orc-retro` counts them apart from a TDD
+  cycle, because a reproduction is not a `tdd_spec`.
+- **A reproduction that cannot be written is `repro: none` with a reason**, and
+  the entry says *not reproduced* — repeated at the commit offer, so a fix
+  nobody has seen work is never quietly shipped as one. It is never faked.
+- A `done` return whose `before` run was green, or whose `after` run is still
+  red, is a malformed return and is treated as a failure.
+
+Why: without the red run, a fix is proven against your test suite — which was
+green before and is green after. With it, the fix is proven against the bug you
+reported. It costs one extra run of one command.
+
+**The two lanes may now ask what breaks.**
+
+- `/orc-quick` gained `orc graph map`, `changes` and `coverage`; `/orc-mini`
+  gained `map`, `impact`, `changes` and `cochange`. Until now both could ask
+  only `ctx`.
+- **Affected tests run first.** After a dispatch that wrote code, `orc graph
+  changes` names the tests that reach the change — a test that arrives through
+  a URL included — and those run before the suite. A runner that takes no file
+  list says so in one line and runs the suite.
+- **Every entry carries a blast-radius line:** `3 symbols touched · callers 7 in
+  4 files · tests reach 2 · risk high: <symbol> (exported, fan-in 4, no test
+  reaches it)`. A `risk` word never appears without its reason. Nothing indexed
+  means it says that instead of a number.
+- **A request that names no file** starts with `orc graph map --focus`, so
+  *"where is the retry logic?"* no longer begins with a guess at a filename.
+
+**`/orc-mini`'s complexity read now carries numbers.**
+
+It used to be a sentence of judgment. It is now one line with counts behind it,
+and four thresholds that each carry their reason:
+
+```
+complexity: recommend /orc — 6 files · callers 27 in 9 files · risk auth (src/routes/orders.js:12) · cochange src/auth.js x3 not in plan
+```
+
+Confident callers in 4 or more files outside the plan · 8 or more confident
+callers · any cited risk class · a file that history says is always touched
+alongside one of yours. `AMBIGUOUS` callers are counted and printed as
+`maybe <n>`; they never trip a threshold alone. **It is an offer, never a
+switch**, and continuing writes the NUMBERS into the decision log so a later
+`/orc-retro` can move a threshold instead of anyone arguing about it. With the
+graph off it says `(graph off)` and decides from the cited risk classes alone —
+it never invents a number.
+
+The mini planner is dispatched WITH those facts (`graph_facts`), so it grounds
+its own file list on them. A file that history says belongs in the change, and
+that the plan does not name, becomes an open question — never a file the planner
+adds in silence.
+
+**Read-only work is a real agent now.**
+
+- `/orc-quick`'s recon is a pinned pair — `orc-recon-sonnet-4-6-med` and
+  `orc-recon-opus-5-low` — with one return contract: a short answer (12 lines at
+  most), evidence with `file:line`, what it searched, what it did NOT find and
+  the queries that prove it, and `graph_used`.
+- They are **traced**. The hook writes `SPAWN` and `RETURN` for them, they show
+  up in `orc run inflight` while they run, and `/orc-retro` can count them. Each
+  is dispatched through the same gate as everything else — the gate still asks
+  every time.
+- A blast-radius answer keeps four kinds of caller APART — a direct caller, one
+  that reaches through a URL, one through an alias, one through a base class —
+  and when a list rests on the map alone it carries the sentence that says so:
+  *A card lists every caller that NAMES the symbol. A card's silence is not
+  proof of absence.*
+- **`other — name a model` stays** as the escape hatch, and it now names a MODEL
+  only. The Agent tool has no per-call effort knob, so the old "effort" option
+  was a setting that did not exist.
+
+**The gate can now recommend, and it still never chooses.**
+
+A menu line may carry an arrow marked `suggested` WITH its reason from the dig —
+8 or more callers, a visible risk class, or more than three files changing. It
+is a recommendation printed beside the option, never a pre-selection, and every
+menu still ends with `Your choice — nothing runs until you answer.`
+
+**Both lanes cost less to load.**
+
+- The two skill descriptions load into **every** session. `/orc-quick`'s went
+  619 to 326 characters and `/orc-mini`'s 493 to 294, with every trigger phrase
+  kept word for word and a test that holds them there. Across all 33 skills that
+  is 492 characters off what every session pays before it does anything.
+- The anti-slop rules card in a `/orc-quick` slice is now a **compact** form:
+  about 1,460 tokens instead of about 3,469, on every dispatch and re-sent every
+  executor turn. Every HARD rule keeps its id, its title and its instruction and
+  loses only the worked examples, the pack file is named beside it, and the JSON
+  says `compact: true` — a reader that cannot tell a short card from a stripped
+  one cannot trust either.
+- `/orc-quick`'s spine went 379 to 325 lines and gained a budget it never had;
+  `/orc-mini`'s went 268 to 280 against a pin raised 270 to 280 with its reason
+  written into the guard. What left both spines is stated once, in the file that
+  owns it.
+
+**Smaller things.**
+
+- `orc graph update --notes-pending` replaces two calls with one in both lanes.
+- One `orc graph gain` line at the close of a code-writing request, copied word
+  for word: what the map put in (recorded) and an estimate, always a range, of
+  what it kept out.
+- `/orc-mini` passes wiki **paths**, not page bodies, to its planner and its
+  executor — the orchestrator's own context is the surface that fills up first.
+- `wiki_used: none` and `graph_used: none` are recorded rather than dropped. Two
+  runs in a row of `wiki_used: none` on fresh pages prints one line suggesting
+  you check those pages' TL;DRs.
+- `/orc-quick`'s `gh` probe is lazy — it runs on the first PR request, not at
+  every preflight.
+- Each `/orc-quick` trace packet is built from a running record with the time
+  each event actually happened, instead of one timestamp for the whole packet.
+
+**What this release does NOT promise.** It does not lower your bill. ORC
+measured that in v1.8.2 and the answer has not changed: search results are a
+fraction of one percent of what a session adds to its context. The claim here is
+correctness, traceability and fewer round trips — a bug proven fixed, a dig that
+shows up in the trace, and the affected tests run before the suite.
+
+**Limits, with the numbers.**
+
+- **The live-session evaluation in `eval/` did not run for this release.** The
+  deterministic half is covered by the suite — the shipped trace hook is driven
+  with a real recon dispatch and asserted to emit `SPAWN` and the `PHASE-EDGE`,
+  the `repro` contract is asserted across all ten executor agents, and the
+  compact rules card is asserted to keep every HARD rule id. What is NOT
+  measured is the part that needs a person driving a lane: whether a defect run
+  shows red then green three times out of three, whether recon's recall on
+  URL-reached callers beats the graph-off run, and whether a request with no
+  filename finds its files in fewer reads than the v1.8.2 baseline. Those are
+  the gates in the plan, and they are unmet, not passed.
+- **`/orc-quick` still cannot call `orc graph impact`.** It has no planner and
+  no declared-file set before the gate, so the two planning reads stay out of
+  its catalogue. Its recon agent calls them instead.
+- The complexity thresholds (4 files · 8 callers · any risk · 3 co-commits) are
+  a starting point chosen with reasons, not measured ones. They are printed in
+  the `GATE complexity` trace line precisely so a retro can move them.
+
+---
+
+### v1.8.2 — the map that finds what a grep cannot _(2026-09-21)_
+
+**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`
+
+**Do not use `npm i -g -f`.** Full detail in v0.56.0 below.
+
+v1.8.0 shipped the code graph with a known hole. A card listed every caller that
+NAMES a symbol, so a test that reaches a route by its URL was not a caller, and
+the card was silent about it. On one real question the graph declared eleven
+route-level tests absent. This release closes that hole and four more like it,
+adds five languages, and makes the map answer faster than it could before.
+
+**Nothing you have to do.** The index upgrades itself. Engine `graph@5` re-reads
+every record the first time you run `orc graph update` after this release; a
+Django-sized repository takes about 14 s once, and every update after that is
+small again. The graph is still **off by default**: `orc config set code_graph on`.
+
+**A URL is now an edge.**
+
+- `request(app).get("/orders/search")`, `client.post("/api/orders/")` and
+  `httptest.NewRequest("GET", "/p")` reach the route they resolve to. The card
+  prints `← reached via GET /orders/search tests/orders.test.js:27 ROUTE`,
+  `orc graph impact` follows it, `orc graph changes` counts it, and the `tests`
+  line names the test file.
+- A decorated handler keeps its own symbol and gains a `<METHOD> <path>` alias,
+  with the class or router prefix folded in — `@Controller("orders")` plus
+  `@Get(":id")` is `GET /orders/:id`. A mount from another file (`app.use`,
+  `include_router`, `register_blueprint`, Django `include`) is applied when the
+  card is read. `ctx "GET /orders/:id"` and `ctx OrdersController.find` both
+  answer.
+- A URL whose prefix is built at run time (`BASE + "/p"`) matches by its tail.
+  Two routes that match one URL are `AMBIGUOUS`, with both listed. **The graph
+  still never guesses.** `ROUTE` is a new state word beside `LOCAL`, `IMPORT`
+  and `UNIQUE`.
+
+**Four more ways the map used to lose a caller.**
+
+- **An instance alias.** `const svc = new OrderService(); svc.run()` now links to
+  `OrderService.run`. An alias head is a class name, so `router.get` with
+  `router = Router()` is `UNRESOLVED (external)` — not a list of every `get` in
+  the repository.
+- **An inherited member.** `this.ok()` in a subclass finds `Base.ok`, and
+  `super.m()` skips the class's own `m`. The edge carries the state the base
+  class resolved with, plus `inherited`.
+- **A barrel re-export.** An import searches the file it names first, then the
+  files that file re-exports, three deep. A barrel that defines the name itself
+  wins over one that passes it on.
+- **A guess we removed.** A bare call with no receiver (`get("/p")`) no longer
+  resolves to the only method in the repository with that name. In v1.8.1 every
+  supertest `.get(...)` was recorded as a caller of some class method. That was
+  an invented edge, and it is gone.
+
+Measured on two real repositories, v1.8.1 to v1.8.2:
+
+| | django/django | nestjs/nest |
+|---|---|---|
+| confident edges | 65,379 → **72,955** | 7,288 → **9,426** |
+| `UNIQUE` guesses | 23,866 → **6,442** | 1,957 → **275** |
+| `AMBIGUOUS` hints | — | 81,485 → **33,906** |
+| routes found | **656** | **344** |
+| first build | 12.5 → 13.7 s | 3.1 → 4.0 s |
+
+**Five more languages.** Ruby, Rust, Kotlin, Vue and Svelte single file
+components (the `<script>` block, at the file's own line numbers) and C / C++.
+The measurement that matters is how much of a real repository the parser could
+not finish: rubocop **2.4%**, tokio **0.3%**, ktor **1.4%**, primevue **0.5%**,
+sveltejs/svelte **0%**, abseil-cpp **1.7%**, redis **4.5%**.
+
+**Borrowed parsers, where your project already has the tool.** Python already
+used the `ast` of a Python on PATH. TypeScript and JavaScript now use your own
+`node_modules/typescript`, and Go uses the `go` on PATH. ORC still has zero
+dependencies, the record names the rung that read it (`extractor:
+typescript@5.9.3`), and a failure falls back file by file. `ORC_GRAPH_NO_BORROW=1`
+forces the heuristic everywhere.
+
+> **This one missed its gate and ships anyway, on the maintainer's call.** The
+> gate was a 10-point rise in the share of calls resolved with confidence. It
+> measured **+1.0** on nestjs/nest, **−0.3** on vuejs/core and **−0.3** on hugo.
+> The gate measured the wrong thing: that share is held down by calls into
+> packages outside the repository, which no parser can resolve. What did move is
+> INVENTED edges — `UNIQUE` guesses fell 36–40% and `IMPORT` facts rose. The
+> borrow is more correct, not more complete. It costs +0.24 s (TypeScript) and
+> +0.70 s (Go) on a one-file update. There is no new config key, on purpose.
+
+**Fewer round trips.**
+
+- **`orc graph ctx … --source [N]`** appends the target's own lines to the card
+  (80 by default, 200 at most), charged to the same budget. The card and the
+  range arrive in one call.
+- **`orc graph ctx --for-slice <files…>`** prints only the OUTSIDE view of each
+  declared file: who calls into it and from which line, who imports it without
+  calling, which routes it answers, which tests cover it. No symbol table. An
+  executor reads its own files in full anyway, so a file card repeated what it
+  was about to read — on every later turn of that agent. The outside view is
+  30–51% smaller than the card it replaces.
+- **`orc graph update --notes-pending`** answers the update and the notes batch
+  in one process and one lock.
+- **A card prints one-letter states with a legend only when that is smaller**
+  than the words. A three-row card keeps the words. Always-short made small
+  cards bigger, which is the opposite of the point.
+- **A card that hid nothing prints no footer.**
+
+**The hook learned two more moments.** A shell search (`grep`, `rg`, `git grep`,
+`findstr`, `Select-String`, `ag`, `ack`) is the same question as a Grep, and now
+gets the same answer. And with `orc config set code_graph_hooks on,read`, a
+whole-file read of a file with many symbols gets one line naming its six most
+reached symbols and their ranges, so the NEXT read can ask for a range. **The
+read always runs.** The hook never blocks a tool call and never rewrites one.
+
+**Doc notes — the author's own sentence, for free.** The parser now takes the
+first sentence of a docstring, a JSDoc block, a `///` run or a `#` block and
+prints it on the card as `doc <sentence> (parser · current)`. It costs no model
+tokens, and it is re-extracted with the body, so it cannot go stale on its own.
+A comment can still lie, so a CURRENT model note outranks it: the order is
+current note → doc → stale note.
+
+> **We expected this to cover most of a repository. It does not.** The plan said
+> more than 60% of symbols would carry a doc. Measured: **19.9%** on django
+> (30.6% of non-test source), **7.1%** on nest (9.0%). The extractor is right —
+> the comments are simply not there. The number in this file is the measured
+> one.
+
+**`orc graph gain` — what the map put in, and an estimate of what it kept out.**
+Every read appends one line to a local ledger. The command adds them up and
+keeps three kinds of knowing apart, because merging them produces a number
+nobody can check:
+
+- **paid** — the tokens the graph put into a context. Recorded, exact.
+- **avoided** — what searching would have cost for the same question. **An
+  estimate**, always a range, never one number.
+- **measured** — `--measured` reads your own runs with the graph on against your
+  runs with it off, and prints nothing until there are three of each.
+
+It never prints a percent of a session, it never blocks a read, and `orc stats`
+reports `graph: null` when there is no ledger — never a confident zero.
+
+**`orc graph map` — the question you ask before you know a file name.** It ranks
+every indexed file by how much of the repository's own call and import traffic
+flows through it, and prints the top files with their most important symbols and
+line ranges, inside a token budget. `--focus src/orders/service.js,createOrder`
+re-ranks the whole repository around those files or names; it never filters it.
+A test file ranks lower (by ten), a file whose every symbol is private ranks
+lower (by half), and an edge is weighted by the square root of its call count, so
+one import used in a loop does not outrank ten separate callers. **Rank is a hint
+about where to look first, never proof that a file matters to this change** — the
+card says so itself.
+
+> **`map` is wired to PLANNING only, and that was a measurement, not a
+> preference.** The gate was three answerable planning calls per run. Replaying
+> real transcripts measured **0.39** (16 sweeps over 41 main windows), so the
+> plan's own fallback applied and the analyst and `/orc-quick` wiring was
+> removed again. The honest caveat: those transcripts drive lanes over a
+> fourteen-file toy app, where a planner has nothing to sweep. It will be
+> re-measured on a real repository.
+
+**A one-symbol card is about twice as fast.** Working out who calls a symbol used
+to mean parsing the whole index. The resolution cache is now also written as
+shards, one file per name prefix, and a one-symbol `ctx` reads only the shards it
+needs. On django: **881 → 480 ms** for the whole command, **361 → 50 ms** for the
+work inside the process. The floor is Node's own start-up, about 300 ms on the
+test machine.
+
+The shards answer exactly what the full index answers, **or they decline**. 577
+cards on django and nest were compared with and without them: **0 different.**
+The fast path steps aside for a path, a URL, a `file:line`, a name that is not
+exactly one symbol, `--for-slice`, a file card and any multi-target call, and
+every answer says which path produced it. The cost is disk: django's shards are
+**30 MB**, taking `.claude/orc/graph` from about 87 MB to about 117 MB. The
+update pays nothing measurable.
+
+**Also in this release**
+
+- **`code_graph_ignore`** — extra paths the graph never indexes, as a
+  comma-separated list of globs (`vendor/**,*.gen.ts`). The engine already
+  skipped `node_modules`, root `dist/` and `build/`, caches, bundles, `.d.ts`
+  and generated files; this adds to that list. A skipped file is reported
+  `excluded` by `orc graph coverage`, never in silence.
+- `code_graph_hooks` gains the value `on,read` (see the hook above). `on` and
+  `off` behave as before.
+- `orc graph gain` also appears on the `orc ui` Knowledge panel and in one ship
+  line, marked an estimate in both places.
+
+**Limits we know about**
+
+- **Fixed since v1.8.1, with its new limit stated:** a caller that reaches a
+  symbol through a URL is now an edge. A caller that reaches it through a job
+  runner, a string dispatch, reflection, or a URL assembled at run time from
+  parts the parser cannot see is still not an edge and never will be. The file
+  still reads as fully parsed, and the card is still silent. **A card's silence
+  is not proof of absence.**
+- TypeScript and Go are exact only where the project has the tool. Everything
+  else is a heuristic, which is why a card can say `coverage partial`.
+- Java, PHP, Swift, Scala and Dart have no borrowed parser. Ruby's own parser
+  (`Prism`) was gated on the heuristic missing more than 5% of a real
+  repository. It missed 2.4%, so it was not built.
+- The status line component compares HEAD with the index. Only
+  `orc graph status` sees uncommitted edits.
+- The graph hook's delivery on `SubagentStart` is confirmed in a live session.
+  The other delivery events are still unconfirmed, and the hook stays silent and
+  free if they never are.
+- **It is still NOT a token optimisation, and that is still measured, not
+  guessed.** `Grep` and `Glob` results are 0.06% of what a session adds to its
+  context, and a perfect locator would save 0.1% of a run. Turn the map on for
+  the cards: what calls what, what a change would touch, where the parser could
+  not finish. `orc graph gain` reports an estimate and says the word "estimate"
+  every time.
+
+**How to check it.** `orc config set code_graph on`, then `orc graph update`,
+then `orc graph map` to see the repository ranked, and
+`orc graph ctx <a route or a function>` to see a card. Run `orc update` in your
+project to get the lane changes.
+
+---
+
 ### v1.8.1 — the guard that only failed on Windows _(2026-09-16)_
 
 **Still on the unscoped `orc` package?** Do this once first - your `orc upgrade`