@azure-id/orc 1.8.2 → 1.9.0

package/templates/skills/_shared/phases/rules.md

@@ -1,159 +1,172 @@
-# Phase — Rules   (id: `rules`)
-
-> **Library file.** New at v1.7.0 W5. Layers declared: `core` only — single-layer
-> for the same reason `house-rules.md` is: it is a standing card injected
-> VERBATIM into a slice, and a layered card would be a different card. What
-> varies between lanes is DATA (which packs, whether a task is front-end), not
-> prose. `orc lane phases <lane> --json` names the file and the layers to read.
->
-> **What is NOT here:** the rules. They are `../rules/` — four packs, read-only,
-> shipped. This file is the SHAPE: who assembles the card, where it sits in a
-> slice, what comes back, and what the phase must never do.
->
-> **`/orc-doc` does not run this phase.** That lane has its own ledger
-> (`orc doc rules`) and its own frozen-per-document mechanic. Excluded means
-> excluded, and `orc rules slice --lane orc-doc` refuses by name.
-
-<!-- orc:layer core -->
-
-## One assembler, and it is not you
-
-```
-orc rules slice --lane <lane> [--pack ui] [--json]
-```
-
-That command is the **only** thing that builds this card. A lane never
-concatenates the packs itself, never re-orders them, never summarises a rule and
-never drops one it judges irrelevant.
-
-Two reasons, and both have cost this repo money elsewhere:
-
-1. **Drift.** A card assembled in twenty-eight spines is twenty-eight ideas of
-   the precedence order. The same argument as `orc lane phases`: *a second idea
-   of the pipeline is the drift this exists to make impossible.*
-2. **Cost.** This card rides on **every spawn**. One assembler is the only place
-   its token weight can be measured, and therefore the only place it can be cut.
-
-Print the command's `line` VERBATIM at preflight. Never compute it:
-
-```
-rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
-rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
-```
-
-**Both spellings are mandatory in their state.** `yours none` is an ANSWER — it
-says the project has not written its own rules, which is a different fact from
-the CLI failing to look.
-
-## Where it sits in a slice — the order IS the contract
-
-```
-1  HOUSE RULES              ./house-rules.md, injected verbatim
-2  YOUR PROJECT'S RULES     from the slice, P0 then P1 then P2, verbatim
-3  ORC RULES                from the slice, the packs this lane carries
-4  the task                 the lane's own dispatch contract
-```
-
-Nothing goes above 1. Nothing goes between 2 and 3. The assembler emits 2 and 3
-as one block in that order, so the lane's job is to place that block directly
-under the house card and before the task.
-
-**The slice field is `rules_card`, and it is the `text` field — not the `line`.**
-Run the command at DISPATCH, not only at preflight. The `line` tells the user
-which rules are in force; the `text` is what the agent reads. A lane that prints
-the line and injects only the house card has reported rules that no agent got.
-
-## Precedence, and the one sentence that gets it wrong
-
-```
-house rules  >  your rules  >  ORC rules
-```
-
-**The house card is CODE and BEHAVIOUR only.** It governs how a change is made:
-surgical, simple, honest, in-slice. It says nothing about the words an agent
-writes, so it never overrules a writing rule — *it does not speak about prose at
-all.* A lane that presents the house card as beating `OSW-*` has misread it.
-
-**A project rule beats an ORC rule outright.** Not a waiver and not a
-negotiation: the ORC rule is removed from the slice, and the removal is stated
-inside it. The assembler does that. The lane does not decide it.
-
-Where a lane's preflight prints a report rather than a bare line, the report
-**names** each override. An override the user cannot see is an override they
-cannot audit.
-
-## The `ui` pack rides per TASK, never per lane
-
-`ui` is in no lane's default set. Add it to a single slice, at dispatch time:
-
-> If a task's **declared files** are front-end — `.css`, `.scss`, `.html`,
-> `.jsx`, `.tsx`, `.vue`, `.svelte`, or a directory the wiki or the cached
-> pattern identifies as the UI layer — assemble that task's card with
-> `--pack ui`. Otherwise do not.
-
-A UI rule in a backend slice is tokens paid on every spawn for a rule that
-cannot apply. A lane that dispatches no tasks never passes `--pack ui` at all.
-
-## What comes back
-
-Every return from a slice that carried this card gains three fields
-(`../return-validation.md`):
-
-| Field | What it holds |
-|---|---|
-| `rules_applied[]` | the ids the agent acted on |
-| `rules_conflicts[]` | two rules that disagree. **A gap, never a silent choice** |
-| `rules_overridden[]` | an ORC id a project rule replaced |
-
-A `rules_conflicts[]` entry is relayed to the user as a gap through the lane's
-own gap channel. Resolving it quietly is the failure the field exists to prevent.
-
-## The boundary — declared, never validated
-
-Rules govern **what is written and how it reads**, and **what shape of code is
-acceptable**. They can never change how a lane **runs**: the scoring, the wave
-order, the gates, the dispatch contract, the ship rules, or any lane's
-structural and safety rules.
-
-A rule that asks for one of those comes back as `unsupported_request` and is
-relayed as a gap. **Never a guessed compromise.**
-
-**Do not build a detector for this.** The CLI declares the boundary and does not
-pretend to enforce it, for the reason `orc doc rules` already settled: a
-validator that sometimes works is worse than none, because a clean pass then
-means nothing. The agent is the only reader that can tell a content rule from a
-structural one, so the agent is where the answer comes from.
-
-## The free lint
-
-```
-orc rules lint <path…|--staged|--diff> [--pack w,c,d,u] [--json]
-```
-
-Deterministic, zero tokens. Exit `0` clean · `1` findings · `2` nothing to lint.
-
-It checks only the rules a string match can prove, and it prints — in every
-mode — how many it did not check. **Relay that coverage line whenever you relay
-a lint result.** A clean exit allowed to stand in for a review nobody did is the
-whole failure that line prevents.
-
-Findings are ADVISORY. This phase adds no gate: a style preference that fails a
-build gets switched off within a week, and then nothing is enforced at all.
-
-An exemption is never silent either. The lint skips the rules packs themselves
-(a rule that bans a word has to print that word to define it) and any file
-marked `orc-rules-ignore-file`, and it reports the count of both.
-
-## Cost, and where to cut it
-
-Measured at v1.7.0: roughly **3 600 tokens** per build-lane slice, **4 300** with
-the UI pack, **2 200** for a prose-only lane. The card already carries HARD rules
-in full and PURPOSE/LOCK rules as one line plus the file to open when one
-applies.
-
-If it must come down, the lever is the worked examples inside the HARD bodies,
-and the only place to pull it is `rulesSlice()` in `bin/cli.js`. **Never by a
-lane deciding to trim its own card** — that is the drift this phase exists to
-prevent, arriving disguised as a saving.
-
-<!-- /orc:layer -->
+# Phase — Rules   (id: `rules`)
+
+> **Library file.** New at v1.7.0 W5. Layers declared: `core` only — single-layer
+> for the same reason `house-rules.md` is: it is a standing card injected
+> VERBATIM into a slice, and a layered card would be a different card. What
+> varies between lanes is DATA (which packs, whether a task is front-end), not
+> prose. `orc lane phases <lane> --json` names the file and the layers to read.
+>
+> **What is NOT here:** the rules. They are `../rules/` — four packs, read-only,
+> shipped. This file is the SHAPE: who assembles the card, where it sits in a
+> slice, what comes back, and what the phase must never do.
+>
+> **`/orc-doc` does not run this phase.** That lane has its own ledger
+> (`orc doc rules`) and its own frozen-per-document mechanic. Excluded means
+> excluded, and `orc rules slice --lane orc-doc` refuses by name.
+
+<!-- orc:layer core -->
+
+## One assembler, and it is not you
+
+```
+orc rules slice --lane <lane> [--pack ui] [--json]
+```
+
+That command is the **only** thing that builds this card. A lane never
+concatenates the packs itself, never re-orders them, never summarises a rule and
+never drops one it judges irrelevant.
+
+Two reasons, and both have cost this repo money elsewhere:
+
+1. **Drift.** A card assembled in twenty-eight spines is twenty-eight ideas of
+   the precedence order. The same argument as `orc lane phases`: *a second idea
+   of the pipeline is the drift this exists to make impossible.*
+2. **Cost.** This card rides on **every spawn**. One assembler is the only place
+   its token weight can be measured, and therefore the only place it can be cut.
+
+Print the command's `line` VERBATIM at preflight. Never compute it:
+
+```
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours 9 lines (P0 4 · P1 2 · P2 3) · 1 override
+rules:    ORC 65 (W 23 · C 22 · D 10 · U 10) · yours none
+```
+
+**Both spellings are mandatory in their state.** `yours none` is an ANSWER — it
+says the project has not written its own rules, which is a different fact from
+the CLI failing to look.
+
+## Where it sits in a slice — the order IS the contract
+
+```
+1  HOUSE RULES              ./house-rules.md, injected verbatim
+2  YOUR PROJECT'S RULES     from the slice, P0 then P1 then P2, verbatim
+3  ORC RULES                from the slice, the packs this lane carries
+4  the task                 the lane's own dispatch contract
+```
+
+Nothing goes above 1. Nothing goes between 2 and 3. The assembler emits 2 and 3
+as one block in that order, so the lane's job is to place that block directly
+under the house card and before the task.
+
+**The slice field is `rules_card`, and it is the `text` field — not the `line`.**
+Run the command at DISPATCH, not only at preflight. The `line` tells the user
+which rules are in force; the `text` is what the agent reads. A lane that prints
+the line and injects only the house card has reported rules that no agent got.
+
+## Precedence, and the one sentence that gets it wrong
+
+```
+house rules  >  your rules  >  ORC rules
+```
+
+**The house card is CODE and BEHAVIOUR only.** It governs how a change is made:
+surgical, simple, honest, in-slice. It says nothing about the words an agent
+writes, so it never overrules a writing rule — *it does not speak about prose at
+all.* A lane that presents the house card as beating `OSW-*` has misread it.
+
+**A project rule beats an ORC rule outright.** Not a waiver and not a
+negotiation: the ORC rule is removed from the slice, and the removal is stated
+inside it. The assembler does that. The lane does not decide it.
+
+Where a lane's preflight prints a report rather than a bare line, the report
+**names** each override. An override the user cannot see is an override they
+cannot audit.
+
+## The `ui` pack rides per TASK, never per lane
+
+`ui` is in no lane's default set. Add it to a single slice, at dispatch time:
+
+> If a task's **declared files** are front-end — `.css`, `.scss`, `.html`,
+> `.jsx`, `.tsx`, `.vue`, `.svelte`, or a directory the wiki or the cached
+> pattern identifies as the UI layer — assemble that task's card with
+> `--pack ui`. Otherwise do not.
+
+A UI rule in a backend slice is tokens paid on every spawn for a rule that
+cannot apply. A lane that dispatches no tasks never passes `--pack ui` at all.
+
+## What comes back
+
+Every return from a slice that carried this card gains three fields
+(`../return-validation.md`):
+
+| Field | What it holds |
+|---|---|
+| `rules_applied[]` | the ids the agent acted on |
+| `rules_conflicts[]` | two rules that disagree. **A gap, never a silent choice** |
+| `rules_overridden[]` | an ORC id a project rule replaced |
+
+A `rules_conflicts[]` entry is relayed to the user as a gap through the lane's
+own gap channel. Resolving it quietly is the failure the field exists to prevent.
+
+## The boundary — declared, never validated
+
+Rules govern **what is written and how it reads**, and **what shape of code is
+acceptable**. They can never change how a lane **runs**: the scoring, the wave
+order, the gates, the dispatch contract, the ship rules, or any lane's
+structural and safety rules.
+
+A rule that asks for one of those comes back as `unsupported_request` and is
+relayed as a gap. **Never a guessed compromise.**
+
+**Do not build a detector for this.** The CLI declares the boundary and does not
+pretend to enforce it, for the reason `orc doc rules` already settled: a
+validator that sometimes works is worse than none, because a clean pass then
+means nothing. The agent is the only reader that can tell a content rule from a
+structural one, so the agent is where the answer comes from.
+
+## The free lint
+
+```
+orc rules lint <path…|--staged|--diff> [--pack w,c,d,u] [--json]
+```
+
+Deterministic, zero tokens. Exit `0` clean · `1` findings · `2` nothing to lint.
+
+It checks only the rules a string match can prove, and it prints — in every
+mode — how many it did not check. **Relay that coverage line whenever you relay
+a lint result.** A clean exit allowed to stand in for a review nobody did is the
+whole failure that line prevents.
+
+Findings are ADVISORY. This phase adds no gate: a style preference that fails a
+build gets switched off within a week, and then nothing is enforced at all.
+
+An exemption is never silent either. The lint skips the rules packs themselves
+(a rule that bans a word has to print that word to define it) and any file
+marked `orc-rules-ignore-file`, and it reports the count of both.
+
+## Cost, and where to cut it
+
+Measured at v1.7.0: roughly **3 600 tokens** per build-lane slice, **4 300** with
+the UI pack, **2 200** for a prose-only lane. The card already carries HARD rules
+in full and PURPOSE/LOCK rules as one line plus the file to open when one
+applies.
+
+If it must come down, the lever is the worked examples inside the HARD bodies,
+and the only place to pull it is `rulesSlice()` in `bin/cli.js`. **Never by a
+lane deciding to trim its own card** — that is the drift this phase exists to
+prevent, arriving disguised as a saving.
+
+**v1.9.0 — the COMPACT form, and the CLI decides which lanes get it.** The
+lever above is now pulled for **`orc-quick`** and for no one else: every HARD
+rule keeps its id, its title and its first line — the instruction — and the
+worked examples come out, with the pack file named beside them. Measured
+**13 874 → 5 838 chars** (~3 470 → ~1 460 tokens) with every HARD id still
+present. The lane that gets it is the lane with the smallest tasks under the
+largest fixed card, and the card is re-sent on every executor turn.
+
+The answer says which form it is: `compact: true` in the JSON. A reader that
+cannot tell a short card from a stripped one cannot trust either. `line` is
+IDENTICAL in both forms — it counts the rules in force, and compacting changes
+how a rule is written, never whether it applies.
+
+<!-- /orc:layer -->

package/templates/skills/_shared/phases/trace.md

@@ -227,7 +227,7 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 | Verb | Emitted by | Meaning |
 |------|-----------|---------|
 | `PHASE <name> start\|end` | orc → writer | phase transition |
-| `PHASE-EDGE <role-family> :: first=<agent>` | hook | **deterministic phase inference.** ORC agent names encode their role, so when a SPAWN's role family differs from the previous SPAWN's, the hook segments the run itself — families: `analyst\|scout → analysis`, `planner → planning`, `executor → execution`, `reviewer → review`, `verifier → verify`, `test-author → testgen`, `advisor\|judge → ultra-gate` (the trace writer never opens an edge). Zero model dependence: even a run where every writer dispatch was forgotten still reads planning → execution → review → verify, and `/orc-retro` computes NARRATION COVERAGE from edges with vs without a writer `SPAWN` between them |
+| `PHASE-EDGE <role-family> :: first=<agent>` | hook | **deterministic phase inference.** ORC agent names encode their role, so when a SPAWN's role family differs from the previous SPAWN's, the hook segments the run itself — families: `recon → recon` (v1.9.0 — /orc-quick's read-only half; a question answered for a person is not an analysis), `analyst\|scout → analysis`, `planner → planning`, `executor → execution`, `reviewer → review`, `verifier → verify`, `test-author → testgen`, `advisor\|judge → ultra-gate` (the trace writer never opens an edge). Zero model dependence: even a run where every writer dispatch was forgotten still reads planning → execution → review → verify, and `/orc-retro` computes NARRATION COVERAGE from edges with vs without a writer `SPAWN` between them |
 | `CONFIG <key=value …>` | orc → writer | Phase 1 — the resolved config values this run will consume (ALWAYS `opus5_only` — it selects the executor table AND every fixed role, so retro can segment outcomes by dispatch mode). Runtime proof that the run honored the config; `/orc-retro` audits it against behavior |
 | `WIKI-CONSULT <tier> :: docs=<list>` | orc → writer | project wiki consulted for grounding (full/mini at planning; fast at slice-build) — tier ∈ `fresh` \| `aging` \| `stale` \| `absent` \| `empty`; `docs=` the pages pulled/handed to the executor (comma list) or `none`. Records whether the run grounded in the wiki and whether it was stale (surfaces grounding + staleness for later audit) |
 | `CROSSLINK <state> :: boundaries=<n> peers=<names>` | orc → writer | cross-repo peer-knowledge state at the consult point — state ∈ `cached` (peer cache present) \| `configured-no-cache` (crosslink configured but the cache is not built) \| `none`. Per-task `CROSSLINK inject task=<id> :: <boundary>` when a slice receives a linked contract. Records whether peer contracts were injected this run (full orc consumes only the pre-built crosslink cache — it never reads peer source live; mechanism in `wiki-consult.md`) |
@@ -256,6 +256,7 @@ supplies the fact in a packet, the writer writes the line. `SPAWN`, `RETURN` and
 | `DRIFT loop=<n> :: <user description, compressed>` | orc → writer | mock-example drift-recovery loop opened (`PHASE mock-example`; canonical `_shared/drift-recovery.md`; hard cap 2 loops) |
 | `TDD-RED task=<id> iter=<n> :: <failing tests>` | executor→orc → writer | TDD repair-loop iteration — the plan's acceptance tests still red (cap `tdd_loop_max`; a paired TDD task's red proof also emits iter=0) |
 | `TDD-GREEN task=<id> iter=<n>` | executor→orc → writer | the task's TDD acceptance tests pass (the non-exempt definition-of-done) |
+| `REPRO red\|green :: <cmd> exit=<n>` | executor→orc → writer | a DEFECT task's reproduction, before and after the fix (`_shared/return-validation.md` §5d). TWO lines per reproduced defect, in this order: the `before` run must be RED and the `after` run GREEN, or the return was malformed. `REPRO none :: <reason>` when no reproduction could be written — an honest answer, never a missing line. A reproduction is NOT a plan-time acceptance test, so it never reuses `TDD-RED`/`TDD-GREEN`: `/orc-retro` counts "we proved the bug first" apart from "we drove the plan's acceptance tests" |
 | `NOTE :: <decisions>` | writer | the packet's `decisions` field — the WHY layer (scoring rationale, user answers verbatim, what was rejected). One line per packet, only when `decisions` is non-empty |
 | `STATS lane=<l> slug=<s> dispatches=<n> waves=<n> tasks=<n> bands=<h:n,m:n,l:n> downgrades=<n> duration_ms=<n>` | orc → writer | ONE deterministic summary line per run, in the `FINISH` packet, immediately BEFORE the `FINISH` line. This is what `orc stats` reads — one line per file, never a parse of the whole trace. Omit a field you genuinely do not have (a lane with no waves omits `waves=`); never guess one. Every trace-owning lane emits it, not just `orc` |
 | `PACT <state> :: <ids>` | orc → writer | invariant-ledger state at the Phase-1 probe (`pact_gate`), and `PACT inject task=<id> :: <PACT-id>` when a DRIFTED/BROKEN promise is appended to a task's `constraints[]`. `PACT recheck pass\|fail :: <ids>` at Phase 6. Records whether last month's decisions constrained this month's plan |

package/templates/skills/_shared/phases/wiki-consult.md

@@ -74,12 +74,16 @@ in play.
   whenever the request uses project jargon, `orc-reference-config-env` for
   config/env work.
 
-**Lane delta — orc-fast passes POINTERS, not content:** fast selects 1–3 page
-PATHS from `wiki/INDEX.md` and puts the paths in the executor slice with the
+**Lane delta — orc-fast and orc-mini pass POINTERS, not content:** each selects
+1–3 page PATHS from `wiki/INDEX.md` and puts the paths in its slices with the
 instruction to READ them first (TL;DR for orientation, `Contracts & shapes` for
-specifics). Fast never pastes wiki bodies into a slice (a Sonnet-medium
-orchestrator curating wiki prose defeats the lane). Full/mini read the content
-themselves at planning time.
+specifics). Neither pastes a wiki body into a slice, and neither reads one into
+its OWN context — for fast, a Sonnet-medium orchestrator curating wiki prose
+defeats the lane; for mini (v1.9.0), the orchestrator's context is the surface
+that fills up first, and the planner and the executor can read a page far more
+cheaply than it can carry one. The FULL lane still reads the content itself at
+planning time, because it has a reviewer and a verifier to spend that context
+on.
 
 ## Step 3 — Precedence (everywhere the wiki is consumed)
 

package/templates/skills/_shared/return-validation.md

@@ -231,6 +231,28 @@ A rule the slice could not honour because this lane structurally cannot do it
 comes back as `unsupported_request`, relayed as a gap. **Never a guessed
 compromise.**
 
+## 5d. Reproduce-first attestation (when a `repro` was requested — v1.9.0)
+
+A slice that carried `repro: {required: true, kind, hint}` must come back with a
+`repro` field. Either both runs, quoted verbatim, or an honest `none`:
+
+```
+repro: { command, before: {exit_code, tail}, after: {exit_code, tail} }
+repro: none  — <one line of reason>
+```
+
+Two malformed shapes, and they are the whole point of the field. **`status=done`
+with `before.exit_code` 0** means the "reproduction" never failed, so it proved
+nothing; **`status=done` with a non-zero `after.exit_code`** means the bug is
+still there. Either one is a failure of the return, not a finding about the
+code. A `repro: none` is a valid answer — a defect with no reachable entry point
+and no runner cannot be shown red — and the lane says **not reproduced** out
+loud rather than letting a green suite imply a fixed bug.
+
+`repro` is required ONLY when the slice carried `repro.required: true`. A slice
+that asked for none gets none back, exactly like `tdd_spec`, `wiki_used` and
+`graph_used`.
+
 ## 6. Worktree delta (post-wave, every lane that dispatches executors)
 
 Compare `git status --short` before and after each dispatch. A path that

package/templates/skills/context-combiner/SKILL.md

@@ -11,10 +11,10 @@ description: >
   collapsed, conflicts, ordering) one issue at a time; proves NOTHING WAS LOST
   via a source coverage matrix and a 100% coverage gate before handoff;
   spot-checks inherited evidence and marks stale anchors; writes
-  combined-report.md + combined-requirement-spec.md (the merged spec reuses the
-  requirement-spec schema, so the planner/build pipeline is unchanged). Full
-  lane only (Opus 5 high). The orchestrator DISPATCHES this to a subagent —
-  it never combines itself, and the combiner never builds or spawns subagents.
+  combined-report.md + combined-requirement-spec.md, which reuse the
+  requirement-spec schema, so the planner/build pipeline is unchanged. Full
+  lane only. The orchestrator DISPATCHES this to a subagent — it never
+  combines itself, and the combiner never spawns subagents.
 ---
 
 # CONTEXT-COMBINER
@@ -211,12 +211,12 @@ exit code, and never re-derive a state word — the CLI's state words are the on
 state words, and **an exit code is an ANSWER wherever that contract says so, not
 a failure**. A call the answer does not name is a call this lane does not make.
 Exit ≠ 0 from the catalogue itself → say the CLI is unavailable and name the
-command you are about to run, out loud, before running it.
-
-## Rules — the anti-slop card (`../_shared/phases/rules.md`)
-
-`orc rules slice --lane context-combiner --json` is the ONLY assembler; never build
-the card here. It rides under the house rules and above the task —
-**house rules > your project's rules > ORC's own packs** — and its `line` prints
-VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
-never a silent choice) and `rules_overridden[]`.
+command you are about to run, out loud, before running it.
+
+## Rules — the anti-slop card (`../_shared/phases/rules.md`)
+
+`orc rules slice --lane context-combiner --json` is the ONLY assembler; never build
+the card here. It rides under the house rules and above the task —
+**house rules > your project's rules > ORC's own packs** — and its `line` prints
+VERBATIM at preflight. Returns gain `rules_applied[]`, `rules_conflicts[]` (a gap,
+never a silent choice) and `rules_overridden[]`.