@azure-id/orc 0.55.0

package/templates/skills/orc/references/preflight-report.md

@@ -0,0 +1,220 @@
+# Reference — Phase-1 Preflight Report
+
+One compact, user-visible block printed ONCE at Phase 1, after the planning
+input is settled (wiki consulted, crosslink probed, waves computed at Phase 2 —
+so print it at the point all inputs exist, typically end of Phase 1 / start of
+Phase 3). This is **presentation only** — no new probes; every value is already
+computed by the wiki consult (Change 3), the crosslink probe (Change 5), the
+pattern resolve gate (Change 4), and wave grouping.
+
+The point is that the four knowledge gates the run used to keep silent are now
+always surfaced: the user always knows whether the run is grounded (wiki),
+whose house style is in force (pattern), whether peer contracts are in play
+(crosslink), where the trace is, and when the run will pause.
+
+## Template
+
+```
+── run preflight ──
+wiki:      FRESH — 12 docs consulted · 4 docs pending refresh, 335k tok / $0.94
+pattern:   js cached · ts cached
+gotchas:   12 known · 3 match this change's files
+pact:      11 holding · 2 drifted · 3 uncheckable
+bound:     9 execute · 2 escalate · 1 refuse (2 stale)
+after:     src/payments — 2 shipped files rewritten within 30 days of run store-credit
+crosslink: 2 boundaries (payments-api) — advisory
+extra:     ON — 4 of 9 tasks foreign · deepseek/deepseek-v4-flash via api [0,30)
+                · glm/glm-4.7 via cli [30,70) · 2 held back (risk: auth, money)
+scoring:   8-band default table
+tdd:       3 tasks with tests (T3, T6, T9) · 2 covered-by-existing · 2 no-behavior
+           skipped: R4 translation strings (no-behavior) · R7 file split
+                    (covered-by-existing → test/api/health.test.js:41)
+trace:     .claude/orc/logs/run-orc-<slug>-210726-154500.txt
+waves:     3 planned — will pause after wave 2 (batch_pause_every=2)
+```
+
+## Line rules
+
+- **wiki:** the exact tier line from `wiki-consult.md` Step 1 (one of the four
+  freshness tiers, `absent` included). Never omit — `absent` still prints.
+- **pattern:** one token per resolved language (`<lang> cached` /
+  `<lang> codifying` / `<lang> agnostic`), joined by ` · `. No FE/BE language
+  in the run → `none (no FE/BE work)`.
+- **gotchas:** ALWAYS printed — repair memory is knowledge like the wiki and the
+  pattern, and a silent one is the same defect. Exactly one of
+  `<n> known · <m> match this change's files` (from `orc gotcha status` +
+  the scope-glob count against the plan's `declared_files`) ·
+  `none yet` · `off`. `off` still prints: a user who turned it off should see
+  that the run is not learning from its own repairs, and a user who did not should
+  see that it is. Canonical: `../../_shared/gotchas.md`. `.claude/orc/gotchas.md`
+  is where the entries live.
+- **wiki, the debt tail (v0.46.0):** append `· <n> docs pending refresh, <tok> /
+  <$>` from `orc wiki debt --json` **only when debt exists** (exit 1). Exit 0
+  appends nothing — a tail that says "no debt" on every run is a tail people stop
+  reading, and this one has to be legible the time it matters.
+- **pact:** the `line` field from `orc pact status --json`, VERBATIM — never
+  re-worded, never recounted here (`pact_gate: off` omits the line entirely; no
+  ledger prints `none — /orc-pact harvests one from this run's
+  spec_invariants[]`). Canonical: `../../orc-pact/references/gate.md`.
+- **bound:** the `line` field from `orc boundary status --json`, VERBATIM, and the
+  ACTIVE mode is named whenever a verdict is later printed (`boundary_gate: off`
+  omits the line). Uncarded areas are `unknown`, never REFUSE. Canonical:
+  `../../orc-boundary/references/gate.md`.
+- **after:** printed **ONLY when the area this run is about to touch has a recent
+  churn signal** (`orc aftermath status --json`, exit 1 or 2, intersected with the
+  plan's `declared_files`). A clean run prints nothing at all — the whole value of
+  this line is that it is rare. Never a verdict, never a name.
+- **crosslink:** the crosslink line from `wiki-consult.md` when a probe hit
+  (`cached` or `configured-no-cache`); omit the whole line when crosslink is
+  not in play (state `none`).
+- **extra:** (v0.50.0) printed on **every** run where `config.extra_enabled` is
+  true — including a run where nothing routed foreign (`ON — 0 of 9 tasks
+  foreign; no route row covers this plan's scores`). This is the P0 line
+  (`a lane that sends work off Claude without saying so`), so unlike every other
+  line here it is not allowed a quiet branch. `extra_enabled: false` omits it
+  entirely — an off subsystem is not news.
+
+  One row per route row that MATCHED, each naming `provider/model via <engine>
+  [band]`, taken from `orc extra resolve --json` — never re-derived. Then, when
+  either applies and only then:
+
+  - `· <n> held back (risk: <the cited risks>)` — the cited-risk hold-back.
+    REQUIRED whenever it is non-zero, and it names the risks, because the whole
+    value of the count is that the user can tell it apart from a forgotten task.
+  - `· <profile> re-pinged: <result>` after a STALE verification was refreshed,
+    and `· <profile> LOCKED (vault) — falling back to <agent> for [band]` when a
+    vaulted key could not be opened at dispatch time. A locked vault is a cost
+    event, not just a routing one.
+
+  - `· <n> foreign dispatch(es) from an earlier run never reported back` —
+    the ORPHAN line, printed whenever `orc extra preflight --json` returns a
+    non-empty `orphans[]`, each row ending in its own `orc extra reconcile
+    <task>`. Render them VERBATIM: the CLI composes them, this
+    report renders them. It is a FINDING, never a stop — preflight's exit code
+    does not move — and ORC never resumes one on its own. Emit the pre-composed
+    `EXTRA orphan` line from `trace_extras[]` once you have reported it.
+
+  Canonical: `../../_shared/extra-dispatch.md`.
+- **scoring:** which executor table RESOLVED for this run — `8-band default
+  table` · `Opus-5-only ladder (opus5_only)` · `custom
+  (rubric_bands_override, <n> rows)`. An un-shown table is as unaccountable as
+  an un-shown number, and the Opus-5-only ladder in particular means EVERY
+  dispatch needs an Opus 5 main session — the user should see that before the
+  first dispatch, not in a trace full of downgrades. When `opus5_only` is on,
+  append ` · all fixed roles forced to Opus 5` and name any selector it
+  shadowed (`rubric_bands_override` / `fable5_*` present but INERT) — a setting
+  the user tuned and the run then ignored has to be said out loud. With Extra in
+  play the table is a COMPOSITE and reads as one (`8-band default table + extra
+  rows [0,30) [30,70)`) — Extra is an overlay, so naming only one of the two would
+  be naming the wrong half for every covered score.
+- **tdd:** ALWAYS printed on a lane whose TDD policy is on — BOTH branches, not
+  only the exemption. Counted straight from the plan's `tdd_spec`, broken down
+  by `disposition` so the user sees **what got no test and why** (v0.41.0):
+
+  ```
+  tdd:  3 tasks with tests (T3, T6, T9) · 2 covered-by-existing · 2 no-behavior
+        skipped: R4 translation strings (no-behavior) · R7 file split
+                 (covered-by-existing → test/api/health.test.js:41)
+  ```
+
+  The `skipped:` continuation is REQUIRED whenever any entry is
+  `covered-by-existing` or `no-behavior`, one line per entry, each naming its
+  `reason` (or its `covered_by` path). Scoping TDD down is only safe if the
+  scoping is visible: a silently skipped test is indistinguishable from a
+  forgotten one, and this is the line that keeps the token saving honest.
+
+  Whole-run exemption →
+  `EXEMPT (whole run) — no test runner detected in this project`, which is the
+  ONE line `SKILL.md` mandates for that case. A plan where NO task needed a test
+  → `no tasks required tests (all covered-by-existing / no-behavior)` plus the
+  same `skipped:` breakdown — never silence. A lane whose policy is off
+  (orc-fast, or orc-mini when the user declined) prints `off (<lane> policy)`.
+  This line is the producer the mandate previously lacked — without it an
+  orchestrator that prints only what the payload compels prints nothing at all
+  about TDD on a normal run.
+- **trace:** the run's `trace_path`.
+- **waves:** `K planned — will pause after wave(s) [list] (batch_pause_every=N)`,
+  or `K planned — no pause (run straight through)` when the user chose to run
+  through / the schedule is empty.
+
+The pattern and crosslink lines reuse Changes 4/5's already-emitted content — do
+NOT recompute. If the pattern resolve gate has not run yet when the block is
+printed, show the tagged languages as `pending resolve` rather than delaying the
+block.
+
+---
+
+# The `forecast:` block (v0.42.0) — printed EARLIER, and separately
+
+A second, shorter block. It is NOT part of the preflight block above and does not
+change it. It answers the one question ORC never answered: **what will this run
+cost me in time, before it starts?**
+
+## When
+
+**The moment the Phase 1 exit gate passes**, and *before* the pause-schedule
+question, and long before the first executor dispatch.
+
+That timing is the whole design. It is the EARLIEST point where every number is
+real — the plan exists, so tasks, dependencies and facets are all in hand, which
+makes waves and scores computable. It is also the LAST cheap moment to walk away:
+nothing dispatched, nothing written, nothing wasted. Printed any later it would
+still be honest and would be useless.
+
+On a `/orc-plan` **Save & stop** it prints alongside the routing question
+(`../../orc-route/SKILL.md`), so price and recommended lane arrive together.
+
+## Template
+
+```
+── forecast ──
+tasks:     7 · waves: 3 · subagents: about 17
+models:    2 high · 3 medium · 1 low
+time:      about 45-80 minutes in this lane
+cheaper:   /orc-mini would be about 15 minutes with 3 subagents
+           (it skips full review and verification)
+```
+
+## Line rules
+
+- **Presentation only — NO new probes.** Every value is already in hand at this
+  instant: `tasks` and `waves` from the plan and the wave grouping, `subagents`
+  from the dispatch count the lane's phases imply, `models` from the score→model
+  table that was already resolved for the `scoring:` line above.
+- **`subagents` is an estimate and says so** (`about N`). The honest floor is
+  one per task plus the lane's fixed roles plus one trace-writer per phase; a
+  repair round or a requeue makes the real number higher, never lower.
+- **`time:` is a RANGE, calibrated from measured runs, never invented.** The
+  corpus behind the current ranges: `/orc-fast` ≈ 9 min / 3 dispatches ·
+  `/orc-mini` ≈ 15 min / 3 · `/orc` 48–84 min / 15–23. Scale within the lane's
+  range by task count. If a lane has no measured corpus, print
+  `time: not measured for this lane` rather than a guess — a fabricated number
+  here is worse than no number, because it looks computed.
+- **`cheaper:` names ONE alternative and what it costs you**, never a bare
+  "X is faster". Omit the line when no cheaper lane can run this plan (say why in
+  one clause instead — e.g. `cheaper: none — /orc-fast needs a fresh wiki`).
+- **The full lane can cost six times more than the fast lane.** That ratio is the
+  reason this block exists; do not bury it in prose.
+
+## `run_budget_dispatches` — the optional hard stop
+
+Config key, `common` tier, default `0` (off). When set and the forecast's
+`subagents` estimate EXCEEDS it, the run **stops before wave 1** with the same
+discipline as the batch pause — a gate, not a hint. Never dispatch wave 1 past
+an unacknowledged budget stop.
+
+```
+── budget ──
+This run forecasts about 17 subagents; your run_budget_dispatches is 12.
+
+  1  proceed anyway
+  2  switch to /orc-mini (about 3 subagents — skips full review and verify)
+  3  stop and re-plan smaller
+```
+
+Emit `GATE budget stop :: forecast=<n> limit=<m>` before stopping, and
+`GATE budget pass :: forecast=<n> limit=<m>` when the forecast is within the
+limit (so a run that silently passed is distinguishable from one where the key
+was unset). `0` means the gate never fires and no `GATE budget` line is emitted
+at all.
+

package/templates/skills/orc/references/security-checklist.md

@@ -0,0 +1,39 @@
+# Reference — Security-Pass Checklist (Phase 5.5, opt-in)
+
+Loaded ONLY when the Phase 5.5 security pass fires (config `security_review`
+`on`/`ask` + a task scored ≥ 70 in the run). Passed to the reviewer as
+`security_checklist[]` — the worker sweeps ONLY the run's changed files against
+these items, wrapping Semgrep if it is already installed (never installing it).
+
+Severity mapping (same P0–P3 ladder): an item the DIFF makes exploitable = P0 ·
+a hardening gap on a touched path = P1 · defense-in-depth suggestions = P2/P3.
+
+## Checklist (OWASP/STRIDE-derived, impact-ordered — the closed set; never extend ad hoc)
+
+1. **Injection** — SQL/NoSQL/command/LDAP built from user input without
+   parameterization or a safe builder anywhere in the diff.
+2. **Broken auth on new surface** — any new endpoint/route/handler reachable
+   without the auth check its siblings carry (spoofing).
+3. **Broken authorization** — object/record access without an ownership or role
+   check (IDOR); privilege boundaries crossed by the new code (elevation).
+4. **Secrets in code** — credentials, tokens, keys, or connection strings
+   hardcoded or logged; secrets reaching client bundles or responses
+   (information disclosure).
+5. **Unvalidated input** — request bodies/params/headers/files used before
+   schema validation; mass-assignment of writable model fields (tampering).
+6. **Injection into output** — XSS via unescaped user data in HTML/JS contexts;
+   unsafe redirects/headers from user input.
+7. **Insecure data handling** — sensitive data stored/transmitted unencrypted,
+   PII in logs, cache keys/values leaking secrets.
+8. **CSRF/replay on state changes** — new state-changing browser endpoints
+   without CSRF protection; missing idempotency where retries can double-apply
+   (repudiation/tampering).
+9. **Resource exhaustion** — new unbounded loops/queries/uploads/allocations an
+   attacker controls (denial of service): missing pagination, no timeout, no
+   size cap.
+10. **Dependency risk** — a newly added dependency that is unmaintained,
+    typosquat-suspicious, or pulled for something the stdlib/project already does.
+11. **Error-path leaks** — stack traces, internal paths, or raw driver errors
+    surfaced to callers by the new error handling.
+12. **Crypto misuse** — home-rolled hashing/encryption, weak algorithms (MD5,
+    SHA1 for passwords), missing salts, static IVs in the diff.

package/templates/skills/orc/references/stop-and-resume.md

@@ -0,0 +1,160 @@
+# Reference — Stop Sequence, Usage Report, and Fresh-Session Resume
+
+The token-saving heart of ORC. Load whenever a stop fires (batch
+boundary, token pressure, phase transition worth guarding, or user request).
+
+## When a stop is MANDATORY vs a judgment call
+
+Most stops are yours to judge (token pressure, a phase worth guarding, a user
+request). **The batch boundary is NOT a judgment call — it is a hard gate.**
+Waves are computed for every run regardless of dispatch style (sequential runs
+have waves too — see `wave-grouping.md`), so the boundary binds to wave numbers
+in both styles. After completing wave W, if `W % batch_pause_every == 0` **and at
+least one wave remains** (`W < total_waves`), the stop sequence below is MANDATORY
+and deterministic: **never dispatch wave W+1 past an unacknowledged boundary.** The
+boundary is computed from the answered pause schedule at intake (Phase 2) and
+stored as `pause_schedule` in the checkpoint, so a resumed session enforces the
+same boundaries. Emit `GATE wave-boundary :: wave=W of K → STOP (batch_pause_every=N)`
+before the stop. Token pressure and user request remain judgment; the batch
+boundary is not.
+
+## The stop sequence (order is mandatory)
+
+1. **Decide** to stop (your judgment for token/phase/user stops; the batch
+   boundary above is not a decision but a hard gate). The checkpoint skill
+   never decides.
+2. **Write the checkpoint** into the run subfolder via
+   `subskills/orc-checkpoint/SKILL.md`. VALIDATE the
+   return. If the write fails → DO NOT STOP; surface the write failure instead.
+   Stopping without a good checkpoint is the one thing that loses work.
+3. **Update `run/{run-slug}/state-of-play.md`** — the 10-line human-readable re-anchor:
+   current phase, wave, done/pending tasks, last decision, next action.
+3b. **Write `{run_dir}/{run-slug}/RESUME.md`** — the same breath as steps 2–3,
+   by YOU, never a dispatched agent. Overwrite; never append. Shape below.
+4. **Usage report** (see below).
+5. **Generate the resume block** (see below) — regenerate FRESH at every stop,
+   never reuse an old one. It is printed inline AND is the body of `RESUME.md`.
+6. Tell the user: what's done / remaining, then BOTH continue paths:
+   "Reply **continue** here, or paste the block below in a **fresh session**
+   (recommended if this conversation is long — cheaper and cleaner than
+   dragging this context forward)."
+7. End the turn.
+
+## Usage report (at EVERY stop and ALSO at run completion)
+
+Do NOT attempt to invoke `/usage` — it cannot be called programmatically.
+Instead, at every stop and at run completion:
+1. Report the **dispatch log** you fully control: every subagent's model,
+   effort, and score. At completion, show the full per-task table (task, score
+   + override reason, model, effort) so the user sees where tokens went.
+2. **Remind the user to run `/usage` themselves** for their 5-hour and weekly
+   limit numbers: "Run `/usage` to see your remaining limits."
+
+Never skip either part.
+
+## The resume block — printed inline AND written to `RESUME.md`
+
+A fresh session + disk state is cheaper AND higher-fidelity than a long compacted
+session: near-empty context, perfect state. Offer it proactively at every pause
+once the run is more than ~2 waves old or usage is heavy — do not wait to be
+forced.
+
+**The problem this file fixes.** ORC used to print the block and nothing else. If
+the user closed the window, got distracted, or came back three days later, the
+work was safe (the checkpoint is on disk) but the *way back in* was gone.
+
+### Where it goes, and why there
+
+```
+{run_dir}/{run-slug}/RESUME.md
+```
+
+Inside the run folder — with `checkpoint.json` and `state-of-play.md`, where run
+state has lived safely since v0.34.1 — **never at the project root**.
+`/orc-quick` and `/orc-grill` put their docs at the root because those are
+deliverables a human reads later. A resume prompt is *transient run state*: dead
+the moment the run finishes, and it must never be at risk of being committed.
+Discovery is `orc resume`'s job, not the filesystem's.
+
+### Lifecycle — the file existing IS the "unfinished" flag
+
+- **Written at EVERY stop**, as the third write in the same breath as
+  `checkpoint.json` and `state-of-play.md`. ORC writes it itself — no dispatch.
+  A dispatch inside the stop sequence would mean a stop can fail because a
+  subagent did, at the one step whose entire job is not losing work.
+- **ONE per run slug, always overwritten, never appended.** This is already the
+  protocol's rule above ("regenerated FRESH at every stop, never reuse an old
+  one"), because a stale resume block points at a wave that is already done. This
+  gives that rule a place on disk.
+- **Deleted at `FINISH`** — in the same Phase 8 step that deletes
+  `log_dir/.current`. So a `RESUME.md` existing means **this run is still waiting
+  for you**, with no stale entries and no separate "is this consumed?"
+  bookkeeping.
+- **NOT deleted when a resume merely starts.** If that session then dies, the
+  pointer must still be there.
+
+### Contents (deterministic — this shape, not an improvisation)
+
+```
+Continue ORC run `merchant-notifications`.
+
+Read .claude/orc/run/merchant-notifications/state-of-play.md,
+then .claude/orc/run/merchant-notifications/checkpoint.json.
+Resume from the checkpoint's phase and wave.
+The intent-spec is approved — do not re-plan. Do not redo tasks marked done.
+
+Where it stands:  /orc · phase execution · wave 2 of 4 done
+Done:             T1, T2, T3, T5
+Left:             T4 (requeued — see failure_reason), T6, T7
+Watch out for:    T4 failed once on a missing migration; the gotcha is recorded
+Next action:      dispatch wave 3 (T6, T7)
+```
+
+Every blank is a value you hold at that instant (phase, wave, task states,
+failure reasons) — which is exactly why no model is needed to fill them in.
+
+**Keep the `Where it stands:` line in exactly that shape** — lane, then phase,
+then `wave K of N`, separated by ` · `. It is the ONE line `orc resume` and
+`orc run list` parse, which is how they can list every waiting run without ever
+opening a `checkpoint.json`. Prose elsewhere in the file is free-form.
+
+### Always tell the user both paths
+
+```
+Paused after wave 2 of 4.
+
+To continue in a NEW session (cheaper and cleaner than this long one):
+open a fresh session and paste the contents of
+
+  .claude/orc/run/merchant-notifications/RESUME.md
+  (or just run `orc resume` and pick it from the list)
+
+Or reply `continue` here.
+```
+
+Name the path AND the command. A user who lost the chat has neither the block nor
+the slug in front of them.
+
+## Compaction-proofing (always on, not just at stops)
+
+- **Disk is truth.** Everything needed to continue lives in `run/` files you
+  created: intent-spec, checkpoint, state-of-play, decision log. Conversation
+  is a disposable cache.
+- Write the checkpoint EAGERLY: after every wave, every escalation answer,
+  every phase transition — so a surprise compaction never catches state that
+  exists only in conversation.
+- On ANY suspicion of compaction (context feels summarized, details missing):
+  re-read state-of-play → checkpoint → re-anchor BEFORE acting.
+
+## Resume procedure (both paths: "continue" here, or fresh session)
+
+1. Read `run/{run-slug}/state-of-play.md` (one-glance orientation).
+2. Read the newest valid checkpoint (`updated_at` wins).
+3. One-line intent reconfirm (fresh session only): "Resuming: <scope>. Still
+   correct?"
+4. From task_state: done stays done; partial resumes from
+   `progress.files_written` (last milestone); pending awaits its wave;
+   requeued/failed re-dispatch reading `failure_reason`; stale_review gets a
+   review pass.
+5. Re-attach the decision log, regenerate the digest, continue from the
+   checkpoint's phase.