@azure-id/orc 0.55.0

package/templates/skills/orc-learn/references/deepen.md

@@ -0,0 +1,70 @@
+# Reference — Deepen Protocol (wiki topic → functions & full flow)
+
+What the writer does AFTER the boundary is known. The wiki (when fresh)
+answers "which files make up feature X and what are its contracts"; deepening
+answers what the wiki deliberately does not carry: **which functions, in what
+order, and why** — the level a human needs to change the code safely.
+
+Precedence throughout: `code > fresh wiki > stale wiki (hints) > model
+priors`. Every wiki claim used here is re-verified against the file it
+anchors; on conflict the code wins and the doc records what the code shows.
+
+## Inputs
+
+- `covers[]` — the feature's file set (from the chosen wiki area's globs, or
+  from the user's directory/focus pointer when the wiki couldn't seed it).
+- `wiki_tier` + the topic's wiki doc path when one exists (fresh or aging →
+  trust its boundary/contract claims as a starting map; stale → hints only,
+  verify before use; none → skip).
+- `focus_hint|null` — biases which invocation the walkthrough follows.
+
+## Step 1 — enumerate the feature's surface
+
+Read every file matched by `covers[]` (targeted — NEVER expand to a
+repo-wide scan; a file outside `covers` is read only when step 2's flow
+provably calls into it, and then it is added to the doc's fingerprint map).
+Record each function/method/entrypoint that participates in the feature:
+
+- name + `file:line` anchor (the definition line, verified this run)
+- role in one line (what it contributes to the feature)
+- classification: entrypoint (route/command/hook/export) · core logic ·
+  helper · boundary (I/O, external service, other feature)
+
+Skip vendored/generated files and trivial one-line re-exports. The count of
+recorded functions is returned as `functions_mapped`.
+
+## Step 2 — trace ONE real flow, entry to exit
+
+Pick the feature's most representative invocation (the `focus_hint` wins if
+it names one; else the primary entrypoint). Follow the actual call chain
+through the recorded functions — reading the code, not inferring — until the
+flow leaves the feature (response returned, event emitted, write committed).
+
+Produce an ordered chain of anchors: `entry (a.ts:12) → validate (a.ts:40) →
+compute (b.ts:88) → persist (c.ts:15) → exit`. Note at each hop WHY the hop
+exists when it is not obvious. Branches: trace the main path fully; name the
+significant branches and where they diverge, without fully expanding each.
+`flow_traced: true` in the return means this chain is complete entry-to-exit
+with every hop anchored — anything less returns `false` and says why.
+
+## Step 3 — harvest while it's cheap
+
+During steps 1–2, collect the raw material the templates need, so nothing is
+invented at writing time:
+
+- **Invariants/contracts**: assertions, validation, ordering constraints,
+  error conventions actually enforced in the code (→ knowledge.md).
+- **Why-this-way findings**: places the implementation takes a non-obvious
+  route — these seed the FAQ (→ learning.md).
+- **Couplings**: where the flow crosses into other features/modules — FAQ +
+  gotchas material.
+- **Change seams**: the spots a next iteration would extend (→ recipes +
+  extension points).
+
+## Output
+
+Everything feeds the two templates (`template-learning.md`,
+`template-knowledge.md`). The knowledge.md "Functions & flow" section and the
+learning.md "Guided walkthrough" MUST describe the same step-2 flow — one
+anchored tersely, one narrated pedagogically. Divergence between them is a
+defect.

package/templates/skills/orc-learn/references/refresh.md

@@ -0,0 +1,65 @@
+# Reference — Refresh Protocol (per-feature freshness, multi-select)
+
+REFRESH regenerates the onboarding pair for features the user picks. It
+never runs unprompted, never regenerates everything by default, and never
+persists a freshness status — freshness is computed on read, every time,
+from each feature's fingerprint header.
+
+## Inputs (all read from disk)
+
+Per feature folder `learning-docs/<slug>/`, the `orc-learn:meta` header in
+its `knowledge.md` (`template-knowledge.md`): `source_commit` +
+`covered_files` (path → 6-hex md5).
+
+## Computing freshness (on read — never stored)
+
+The same two-pass recipe as the wiki's staleness reference, run per feature
+against its own `source_commit`:
+
+```
+distance = git rev-list --count <source_commit>..HEAD
+drift    = git diff --name-only <source_commit>..HEAD    (pass 2, when needed)
+```
+
+| Tier | Condition |
+|-------|-----------|
+| FRESH | distance < `wiki_fresh_max` (default 10) |
+| AGING | `wiki_fresh_max` ≤ distance ≤ `wiki_aging_max` (default 30) |
+| STALE | distance > `wiki_aging_max`, OR pass-2 drift intersects the feature's `covered_files` paths |
+
+Pass 2 runs only when pass 1 lands AGING or worse: intersect `drift` with the
+feature's `covered_files` paths. Drift hitting covered files upgrades the
+tier to STALE; drift entirely elsewhere may read as "old but still accurate
+for this feature". Thresholds are the existing `wiki_fresh_max` /
+`wiki_aging_max` config keys — orc-learn adds no config keys of its own.
+
+A `knowledge.md` with a missing/unparseable header cannot prove anything →
+show it as STALE (header will be rewritten on regeneration). A feature
+folder missing its `knowledge.md` entirely → show as BROKEN; regeneration is
+the fix.
+
+## The refresh flow
+
+1. Enumerate `learning-docs/*/knowledge.md`; compute each feature's tier as
+   above. None found → "nothing generated yet; run `/orc-learn` first", stop.
+2. Present the FULL list — every feature, each with its computed tier — and
+   let the user multi-select which to regenerate. FRESH features stay
+   selectable (the user may want a rewrite after learning more); STALE ones
+   are flagged, never auto-selected. Nothing picked → stop, zero writes.
+3. Per selected feature the writer re-runs the full deepen (`deepen.md`) on
+   the feature's `covers` set and regenerates BOTH files: new
+   `source_commit` = current HEAD, recomputed `covered_files` hashes, a new
+   line in the doc changelog, `updated:` set to today (DD-MM-YYYY). Files
+   that vanished since generation drop out of the map; files the new flow
+   pulls in are added.
+4. After the last selected feature, re-derive `learning-docs/INDEX.md` from
+   every feature's current header (all features, not just the refreshed
+   ones).
+
+## Invariants
+
+- Freshness/tier is NEVER written to any file — not the header, not the
+  index. Only `source_commit` + `covered_files` (facts) persist.
+- Only user-selected features are regenerated; the rest are byte-untouched.
+- DD-MM-YYYY everywhere a date is written.
+- A refresh that regenerates nothing (user picked none) writes nothing.

package/templates/skills/orc-learn/references/template-knowledge.md

@@ -0,0 +1,83 @@
+# Template — `knowledge.md` (reference; jump-to lookup)
+
+The lookup half of a feature's onboarding pair, and the file that carries the
+feature's freshness fingerprints. Sections are required unless marked
+optional; empty-scan sections are OMITTED, never stubbed. Every claim is
+anchored `file:line`, verified this run.
+
+## The fingerprint header (required, machine-readable)
+
+The first thing in the file — an HTML comment block the refresh protocol
+parses (`refresh.md`). Field names are orc-learn's own (`source_commit`, not
+the wiki's scan fields) so the two schemas can never be confused:
+
+```markdown
+<!-- orc-learn:meta
+feature: <feature-slug>
+generated: <DD-MM-YYYY>
+updated: <DD-MM-YYYY>
+source_commit: <full git hash — HEAD when this doc was written>
+covered_files:
+  <repo-relative path>: <6-hex md5>
+  <repo-relative path>: <6-hex md5>
+-->
+```
+
+- `covered_files` lists every source file the doc's claims rest on, with a
+  6-hex md5 of its content — computed with the real `node -e` md5 one-liner
+  (same command as `orc-claude/references/refresh.md`), never mentally.
+- Refresh recomputes freshness FROM this header on read; no freshness status
+  is ever stored here.
+
+## Body sections
+
+```markdown
+# Knowledge — <Feature Name>
+
+## Architecture summary
+
+<5–15 lines: the pieces, their responsibilities, how data moves. A compact
+diagram if the shape warrants it.>
+
+## Functions & flow
+
+<THE deepened section — the value-add over any wiki doc. One row/entry per
+function or entrypoint that composes the feature: name, file:line anchor,
+role in one line. Then the full call flow of one real invocation, entry to
+exit, as an ordered chain of those anchors — the SAME flow learning.md
+walks through pedagogically.>
+
+## Contracts & invariants
+
+<What must not break when you touch this feature: shapes, ordering rules,
+error conventions, cross-feature promises. Anchored to where each is
+enforced or assumed.>
+
+## Dependencies & extension points
+
+<In: what this feature consumes (modules, config, env names — never values).
+Out: who consumes it. Extension points: the seams a next iteration should
+use, anchored.>
+
+## How to verify a change
+
+<The build/test/lint invocations that prove a change to THIS feature is
+safe — taken from the wiki manifest's `commands` map when one exists, else
+from the project's real manifests. Only invocations that provably exist;
+never invented. Include the narrowest test scope that covers the feature.>
+
+## Doc changelog
+
+<One line per generation/refresh: DD-MM-YYYY — init|refresh — short note.>
+```
+
+## Rules
+
+- `covered_files` is the refresh contract: any file the doc leans on that is
+  missing from the map silently escapes staleness detection — err on
+  including it.
+- Unanchored claims are omitted, never guessed. On any wiki-vs-code conflict
+  the code wins and the doc records what the code shows.
+- `INDEX.md` (derived by the writer from every feature's header) carries per
+  feature: slug · one-liner · generated/updated dates · path. Freshness is
+  NOT stored in the index — it is computed on read by refresh mode.

package/templates/skills/orc-learn/references/template-learning.md

@@ -0,0 +1,67 @@
+# Template — `learning.md` (pedagogy; read top-to-bottom once)
+
+The teaching half of a feature's onboarding pair. Written for ONE reader —
+the dev who has to extend this feature next iteration — and since
+`learning-docs/` is local and git-ignored, it addresses that reader directly
+as "you". Every section below is required unless marked optional; a section
+whose scan came back empty is OMITTED, never stubbed.
+
+Style: narrative prose over bullet walls. Every code reference is a real
+`file:line` anchor the writer verified this run — never a guessed path.
+
+```markdown
+# Learning — <Feature Name>
+
+> <One sentence: what this feature does and why it exists.>
+
+## Mental model
+
+<The big picture in plain language. One analogy if it genuinely helps. A
+small text/mermaid diagram of the moving parts. 10–20 lines.>
+
+## Guided walkthrough — one real request, entry to exit
+
+<Follow ONE concrete invocation through the code, step by step. Each step:
+what happens, in which function (file:line), and why that step exists.
+This is the heart of the doc — it must trace the SAME flow the knowledge.md
+"Functions & flow" section anchors.>
+
+## Key concepts & vocabulary
+
+<The feature's own terms, each defined in 1–2 lines, anchored where the
+concept lives in code.>
+
+## How to make common changes
+
+<2–4 recipes for the changes the next iteration will plausibly need:
+"add a new X", "change how Y is computed", "extend Z". Each recipe: which
+files/functions to touch (anchored), in what order, and what to re-run to
+verify. This is the section that pays for the whole doc.>
+
+## Gotchas / footguns
+
+<Non-obvious traps found during the scan: ordering constraints, implicit
+couplings, things that LOOK safe to change but aren't. Anchored.>
+
+## FAQ
+
+<REQUIRED, minimum 5 questions. Seed from real scan findings — never generic
+filler. Good sources: "why is it done this way and not the obvious way",
+cross-feature couplings, and "how do I add/change/remove …". Each answer
+2–4 lines, linking into knowledge.md sections or real files for depth.>
+
+## Where to look next
+
+<Pointers: the paired knowledge.md, the 3–5 most load-bearing source files,
+and any wiki doc that covers the surrounding area.>
+```
+
+## Rules
+
+- FAQ is a hard requirement: ≥5 questions or the doc is incomplete — the
+  writer's return reports `faq_count` and the skill relays it.
+- Anchors are verified this run; a claim that cannot be anchored to a real
+  file is omitted, never guessed (same evidence bar as the wiki).
+- No fingerprint header here — freshness lives in the paired knowledge.md;
+  this file carries only a `Generated: <DD-MM-YYYY> · source: <short-commit>`
+  line under the title.

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

@@ -0,0 +1,226 @@
+---
+name: orc-mini
+description: >
+  Lightweight ORC for fast implementation. Use for
+  "use orc-mini to implement X" or "/orc-mini". Same
+  intake → intent-spec → planning → dispatch → smoke-gate → ship spine as the full
+  orchestrator, but SKIPS full code review, verification, and the summary phase.
+  Dispatches ONE Sonnet 5 high-effort subagent for implementation, then runs a
+  build+test smoke gate (blocks ship on red) and offers opt-in test authoring.
+  Switchable to full flow mid-run. The orchestrator never implements — it spawns.
+---
+
+# ORC-MINI
+
+A trimmed orchestrator for when you want speed over the full quality pipeline.
+Everything in the main spine (`../orc/SKILL.md`) applies EXCEPT the
+differences below. Load the main skill's references and schemas by path — the
+HOT-PATH essentials (dispatch names, return-contract fields, artifact path)
+are inlined here so nothing is reconstructed from "full minus deltas."
+
+Run as **Opus 4.8 high**, or Opus 5 / Fable 5 at medium+ (as full; never downgrade).
+**You never implement — you spawn.** The one exception is the **smoke gate**:
+a read-only build+test run, not implementation — you still never write code.
+
+**Worked example** (orient only — never execute from it): `examples/mini-run-mock.md`.
+
+## Differences from the full orchestrator
+
+1. **Skip full Phase 5 (Review), Phase 6 (Verify), and Phase 7 (Summary).**
+   Instead: the **smoke gate** after execution, then the opt-in
+   **test-authoring ask**, then ship.
+2. **Implementation is ONE subagent, Sonnet 5, high effort.** No waves. **No
+   scoring table** — replace it with a **one-line complexity read** (mini-ok?
+   or recommend switching to full); log that line, never render the matrix.
+3. **No dispatch-style and no batch-pause questions** — a single subagent
+   makes both meaningless; never ask them.
+4. **Lighter intake.** Ask only the **Always + medium tier** (Q1–Q4 in
+   `../orc/references/intake.md`); skip the high tier (Q5/Q6). Run the Step
+   3.5 repo cross-check at NAMES-ONLY depth (Glob/Grep-confirm what the draft
+   names, tag the rest `UNVERIFIED`, resolve tags in the sign-off line; >3
+   tags → recommend the full flow or `orc-analyze`). Sign-off **defaults to
+   SOFT**, not GATE.
+5. **Still write tests** if the project has a test setup (the executor
+   creates/updates them in its task).
+6. **Everything else is identical:** run folder + intent-spec, planning,
+   checkpoint/state-of-play, stop sequence, usage reminder, ship flow.
+
+## Mini flow (the phase set)
+
+```
+Phase 0  intake (Q1–Q4, soft sign-off) + run folder + intent-spec
+Phase 1  planning (dispatch orc-planner-mini; analyst first only on real docs)
+         → one-line complexity read (mini-ok? or recommend switch-to-full)
+Phase 3  dispatch ONE executor (orc-executor-sonnet-5-high) — slice carries
+         the standing `house_rules` card (../orc/references/house-rules.md,
+         injected literally) + the cached `postgres` pattern on a data-access
+         task (cache HIT only) — collect + validate return
+Phase M  SMOKE GATE — run build+test → GREEN proceed · RED block ship + surface
+Phase X  MOCK EXAMPLE (config mock_example) — offer/build after a GREEN gate
+Phase T  TEST-AUTHORING ASK (opt-in) — offer to write test cases (never run them)
+Phase 8  ship (commit / push / PR — never stages mock-examples/)
+```
+(No Phase 2 scoring table, no dispatch-style/batch-pause asks, no full
+review/verify/summary.)
+
+**Postgres query grounding.** On a Postgres project, if the task touches the
+data-access layer AND `orc pattern status postgres` reports cached (the
+deterministic probe in `../_shared/detecting-artifacts.md`, never an ad-hoc
+`find` for `.claude/orc/patterns/postgres-pattern.md`), inject it LITERALLY into
+the slice (conventions + blocking query invariants).
+Cache MISS → skip — mini never codifies (that's the full lane /
+`/orc-pattern`); universal invariants + neighbor imitation still cover it.
+
+**Gotchas (repair memory; config `gotchas`) — mini READS and WRITES.** Probe at
+Phase 1 (`orc gotcha status`, one row, never silent), inject the SCOPE-MATCHING
+entries into the Phase 3 slice (cap 3; zero matches = no block, never
+unfiltered), and append a returned `gotcha_recorded` YOURSELF after the return.
+Trimmed mechanics + `.claude/orc/gotchas.md`: `../_shared/gotchas.md` §10.
+
+## Phase M — Smoke gate (build + test; blocks ship on red)
+
+After the executor return validates (`../_shared/return-validation.md` —
+including `done` with non-empty `unmet[]` = partial, and §6's worktree delta: a path changed outside `declared_files` is a violation whatever the return said), YOU run the smoke gate
+per `../_shared/smoke-gate.md`: read-only build+test. **GREEN** →
+test-authoring ask, then ship. **RED** → never offer commit/ship; one repair
+re-dispatch, second red → STOP and surface. Docs-only → gate N/A, say so.
+
+## Phase X — Mock example + drift recovery (config `mock_example`, default ask)
+
+Canonical: `../_shared/drift-recovery.md` — load it when the phase fires. After
+a GREEN Phase M, before ship: `ask` → MANDATORY offer (never silently
+skipped/run) · `on` → build · `off` → skip. Deliverable
+`mock-examples/<change-slug>/` at project root (EXAMPLE.md + one runnable
+mocked artifact) — **never committed, never staged** (no `.gitignore` edit).
+One question after the user runs it: matches expectation? [yes / drift:
+<describe>]. Drift → `DRIFT-FROM` handoff (gap analysis → patch plan → dispatch
+→ re-gate → re-offer), hard cap 2 loops, then an honest unresolved report.
+Trace: `PHASE mock-example`, `DRIFT loop=<n>`.
+
+## Phase T — Test-authoring ask (opt-in; writes tests, never runs them)
+
+Same opt-in as full Phase 6.5 — mini **only asks** (never gates the ship).
+Default from `config.generate_tests`; at the end of a GREEN run ask: *"Write
+test cases for these changes? (I'll author them — automated files +
+TEST-PLAN.md + a curl bundle for HTTP APIs — but never run them; you test
+manually.)"* Yes → dispatch `orc-test-author-opus-5-med` (subskill
+`../orc/subskills/orc-testgen/`) with the run's `actual_files`,
+definition-of-done, touched flows, constraints, stack; the two manual
+deliverables land in **`test-generator/<change-slug>/` at the project root**.
+Validate the returned `test_plan_path`/`curl_bundle_path` are under that folder
+(else malformed → re-dispatch); relay + state the exact path (committed on ship,
+not gitignored). No → ship. Either way this NEVER runs tests.
+
+## Behavior trace (PERMANENT — same rule as full; always on)
+
+Mini does NOT drop the trace. Follow `../orc/references/trace-protocol.md` (load
+at run start): create `log_dir`, write `.current` =
+`run-mini-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file` of that name
+in the SAME step, store `trace_path`. Narration is
+**dispatched, never remembered**: record each event with its REAL timestamp into
+a packet (`PHASE`, `DISPATCH`, `VERIFY` per return — `actual_model`/
+`actual_effort` vs expected, surface any ⛔ DOWNGRADE — `OUTCOME … band=mini`,
+`VERDICT`, plus `decisions` = the WHY), then dispatch
+`orc-trace-writer-haiku-4-5` PAIRED with the next dispatch; mini batches to
+**3 packets** (intake+plan, execution, ship). A phase with
+zero new trace lines is a protocol violation — dispatch its packet NOW.
+Run end: the `FINISH` packet returns, then delete `log_dir/.current`.
+
+## Complexity read (replaces the scoring table)
+
+ONE judgment before dispatch: is this genuinely mini-sized (single coherent
+area, low interdependency, low blast radius)? State it in one line and log it.
+Complex/high-risk (many interdependencies, core/shared surface,
+security-sensitive) → **recommend switching to full** — let the user choose.
+
+## Fallback intake (arriving from orc-fast)
+
+orc-fast falls back HERE whenever its prerequisites fail — never by stopping
+the chat. Follow the reader side of `../_shared/fallback-handoff.md`: the
+`FALLBACK-FROM` block in the shared run folder names the reason; acknowledge
+it in one line, skip re-deriving whatever is carried, reuse the run folder.
+
+## Switching to full flow mid-run
+
+On "switch to full" (or when the complexity read / a mid-run surprise clearly
+needs review/verify): the run folder, checkpoint, and intent-spec already live
+in the shared `.claude/orc/run/{run-slug}/` format, so the full flow resumes from
+the current checkpoint and adds the phases mini skipped. Record the switch in
+the decision log.
+
+## Dispatch via named agents (canonical name-map — dispatch BY these names)
+
+Models pinned in `.claude/agents/`; look up here, never reconstruct a name (agent = skill-name + model-effort suffix). See `.claude/agents/MODEL-MAPPING.md`. `opus5_only: true` FORCES the right column and needs an Opus 5 main session — mini's cheap-lane premise is off while it is on (`../_shared/opus5-only.md`).
+
+**Extra (`extra_enabled`, `../_shared/extra-dispatch.md`):** mini's ONE executor may run off Claude. It has no score, so resolve the pinned executor's **BAND, both edges, and require them to agree** — a partially covering row keeps the run on Claude and the preflight says so. Print the `extra:` line at intake whenever the gate is on (P0: `a lane that sends work off Claude without saying so`); dispatch via `orc extra dispatch --task <file> --json` with the IDENTICAL slice; validate with `return-validation.md` **§2b, not §2** (⛔ SUBSTITUTION replaces the downgrade check); a failure runs `orc extra reconcile <task_id>` FIRST — a worktree that moved is RESUMED, never re-done — then falls back to the pinned Claude agent, announced. A cited-risk change never leaves Claude (`extra_risk_tasks`, default `off`) — and mini's complexity read is not a substitute for that gate.
+
+| Role | Agent (dispatch this) | Model / effort | When `opus5_only` |
+|------|-----------------------|----------------|-------------------|
+| mini analysis (docs only) | `orc-analyze-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-analyze-mini-opus-5-med` |
+| mini planning | `orc-planner-mini-sonnet-5-high` | claude-sonnet-5 / high | `orc-planner-mini-opus-5-med` |
+| mini execution | `orc-executor-sonnet-5-high` | claude-sonnet-5 / high | `orc-executor-opus-5-low` |
+| test authoring (opt-in) | `orc-test-author-opus-5-med` | claude-opus-5 / medium | unchanged |
+
+## Config
+
+Resolve at run start: `../orc/config.md` defaults merged with
+`.claude/orc.config.yaml` — read `generate_tests` (the Phase T offer default),
+`mock_example`, `tdd_loop_max`, and `log_dir`. Wave/scoring/scout keys never
+apply to mini — never render or ask them.
+
+**TDD (ONE intake question — mini's whole TDD policy):** at intake ask once:
+*"Anchor this in plan-time acceptance tests (TDD — red tests first, implement
+to green)? [yes/no]"*. Yes → the planner slice carries `tdd: on` (the mini
+planner authors `tdd_spec` per requirement, **scoped by the same `disposition` set the full lane uses** — `new-surface | behavior-change | covered-by-existing | no-behavior | no-runner`, derived from the `facets`, same safety floor: a cited `risk[]` is never scoped out, so a constant or a translation string gets no test but an auth change always does). Mini keeps its SINGLE executor — no paired TDD task; that executor materializes the failing tests FIRST, then implements to green
+(implement→test→repair, cap `tdd_loop_max`; emit `TDD-RED`/`TDD-GREEN` per
+iteration; cap hit → STOP + honest red report), and Phase M's smoke gate runs
+the TDD suite as part of build+test. Scoped-out requirements are named with their
+reason at preflight — never silent. No → skip entirely; never re-ask.
+
+## Analyst & planner (mini lane)
+
+orc-mini dispatches the FAST variants (Sonnet 5 high): `orc-analyze-mini` and
+`orc-planner-mini` — same artifacts and output contracts as full, trimmed
+depth. The mini analyst is **doc-optional**: on real doc input it runs first,
+then the mini planner; on a merely ambiguous request, prefer one inline
+clarifying question over a cold analyst spawn. Always single-pass — **no deep
+mode, no scouts**; it escalates to `/orc-analyze` deep on its concrete
+thresholds and the user chooses. You never analyze or plan yourself.
+
+**Mini-lane gates (yours, deterministic — same as full; full detail in
+`../orc/references/analyst-gates.md`; emit `GATE` trace lines).** On
+mini-analyst return: evidence spot-check + derivation lint; refuse
+take-into-build on open `UNVERIFIED`/missing `scope_closed`; `git_head` ≠
+HEAD at plan time → re-run the spot-check first. On mini-planner return: Glob
+every `disposition: exists` path, recompute coverage (no orphan
+requirements), cycle + collision checks. Any miss → bounce (one retry, then
+escalate). At dispatch, append the task's `spec_invariants` to the slice's
+`constraints[]` verbatim.
+
+## Wiki consult (if present)
+
+Same rule as the full skill — load `../orc/references/wiki-consult.md` at the
+planning/complexity-read step: compute the FRESH / AGING / STALE tier from
+`.claude/orc/wiki-meta.json`, pull the relevant pages (incl. cross-cutting
+maps like `orc-reference-api-surface` when their domain applies), apply
+`code > fresh wiki > stale wiki (hints) > model priors`, and **emit
+`WIKI-CONSULT <tier> :: docs=<pages pulled>`**. Crosslink: a task touching a
+boundary in `.claude/orc/crosslink/needs.json` gets the cached contract
+injected per that reference — advisory, never blocking. Mini never generates
+the wiki; after a code-changing run apply the passive stale-flag note only
+(the post-ship refresh ASK is full-lane/ultra behavior).
+
+## Shared artifacts
+
+Writes to the SAME location as the full skill
+(`.claude/orc/run/{run-slug}/`) — a switch needs no migration.
+
+## What mini still enforces (from the main hard rules)
+
+Never implement yourself (the smoke gate is read-only, not implementation) ·
+all RUN-STATE artifacts in the run subfolder, never project root (the one
+exception is the opt-in `test-generator/<change-slug>/` self-QA deliverable,
+which lands at the project root by design) · validate every
+subagent return (malformed = failure) · report the dispatch log + remind the
+user to run `/usage` (never invoke it programmatically) · **never offer commit
+on a red build** (enforced by Phase M).

package/templates/skills/orc-mini/examples/mini-run-mock.md

@@ -0,0 +1,50 @@
+# Example — Annotated Mini Run (dry run)
+
+O: = orchestrator (Opus 4.8 high, always) · U: = user. Nothing real. The
+orchestrator NEVER implements — it spawns ONE Sonnet-5-high executor, then runs a
+read-only build+test smoke gate itself.
+
+U: /orc-mini add a `--json` flag to the `report` CLI command
+
+## Phase 0 — Intake (lighter: Q1–Q4, soft sign-off)
+O: Creates run folder run/report-json-flag/ FIRST.
+   [reads repo: Python/poetry/pytest — asks nothing about stack]
+   Batched round (medium tier): 1) What should exist? 2) Out of scope?
+   3) How do we know it's done? 4) Patterns/files to avoid?
+U: report --json prints machine-readable output; no other commands touched;
+   `pytest tests/test_report.py` green; follow the existing click option style.
+O: [drafts intent-spec.md] Sign-off defaults to SOFT — proceeding unless you object.
+
+## Phase 1 — Planning + complexity read
+O: [dispatches orc-planner-mini] → 1 task, declared_files: cli/report.py,
+   tests/test_report.py — both grounded `exists` (globbed) + acceptance sliced
+   from the intent-spec. O spot-checks: both paths present ✓.
+O: Complexity read (one line, no scoring table): single coherent area, low blast
+   radius → mini-appropriate. (If it read complex/high-risk → I'd recommend /orc.)
+
+## Phase 3 — Execute (ONE subagent)
+O: → claude-sonnet-5 / high :: DISPATCH orc-executor-sonnet-5-high :: add --json flag
+   [executor edits cli/report.py + updates tests, returns actual_files + actual_model
+   + evidence {`pytest tests/test_report.py`, exit 0, tail quoted} + empty unmet[]]
+O: VERIFY actual=claude-sonnet-5/high ✅ MATCH · evidence present ✓
+
+## Phase M — Smoke gate (build + test; blocks ship on red)
+O: [runs `pytest tests/test_report.py`]  ⛔ RED — 1 failure: JSON missing trailing key.
+   Not offering commit. Auto-fix ONCE → re-dispatch executor with the failure output.
+   [re-run] ✅ GREEN — build + tests pass.  VERDICT pass
+
+## Phase T — Test-authoring ask (opt-in; writes, never runs)
+O: Write test cases for these changes? (I author them — files + TEST-PLAN.md — but
+   never run them; you test manually.)  [default from config.generate_tests]
+U: yes
+O: [dispatches orc-test-author-opus-5-med] → automated tests in
+   tests/test_report.py; manual deliverable at test-generator/report-json-flag/TEST-PLAN.md
+   (non-API project → curl_bundle_path null). Validate: path under
+   test-generator/report-json-flag/ ✓.
+O: Self-QA plan: test-generator/report-json-flag/TEST-PLAN.md (committed on ship).
+
+## Phase 8 — Ship
+O: Current branch: feat/report-json. Commit? Push? PR?
+U: commit
+O: [commits] Done. Usage: dispatch log below + run /usage for your limits.
+   (Switch to full flow any time — the run folder + checkpoint are shared.)