@azure-id/orc 0.56.1 → 1.1.0

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

@@ -0,0 +1,163 @@
+---
+name: orc-wait
+description: >
+  Wait for wall-clock time to pass without losing the run you are in. Use for
+  "/orc-wait", "/orc-wait 30", "/orc-wait 2h hard", "wait for my quota to
+  reset", "pause this until the window resets". You watched the statusline, you
+  saw the window was almost full, and you decided to stop — this carries that
+  decision out: it writes the hand-back, waits in short detached hops that cost
+  ZERO tokens, and picks the run back up where it left it. Three modes decide
+  how much finishes before it stops: safe (finish the wave), soft (stop now, but
+  force the checkpoint first), hard (stop now, RESUME.md only, can lose work).
+  Also carries the veto — "/orc-wait block <reason>" tells ORC not to stop you
+  at all. It never dispatches an agent, never runs another lane, and never
+  writes your config.
+---
+
+# ORC — the wait
+
+Canonical contract: **`_shared/wait.md`**. Load it before you do anything here.
+This spine is the entry point; that file is the rule.
+
+> **`a lane that waits without a hand-back` has broken this contract.**
+
+A wait is a stop. Every stop writes its hand-back BEFORE it ends, because the
+thing that resumes the run may not be this session.
+
+## What this lane never does
+
+- It never dispatches an agent to do the waiting. An agent runs on the same
+  account and burns the window the wait exists to protect.
+- It never runs another lane, and never changes the work: same tasks, same
+  slice, same agent resolve after the wait as before it.
+- It never writes the user's config.
+- It never computes hops itself. `orc wait plan` does that.
+- It is **command-entry only.** No lane invokes `/orc-wait` for itself.
+
+## W1 — parse (silent)
+
+Run `orc wait plan <spec> --json`. Never do this arithmetic in your head.
+
+| exit | meaning | what you do |
+|---|---|---|
+| 0 | planned | go to W2 |
+| 1 | unparsable | show the `hint` verbatim and STOP. Do not guess a duration. |
+| 2 | no reading | show the `hint` verbatim and STOP. `reset` needs a usage reading; ask for a time instead. |
+
+`block` / `unblock` skip W1 entirely — see **The veto** below.
+
+## W2 — resolve the mode
+
+A named mode always wins. With none, read `wait_default_mode`:
+
+- `ask` (the default) → ask, in ONE turn, with the cost of each spelled out:
+
+  ```
+  Which mode?
+    1. safe — finish the current wave first, then wait. Loses nothing.
+    2. soft — stop at the next turn. Forces the checkpoint first.
+    3. hard — stop at the next turn. No checkpoint. Can lose the wave.
+  ```
+- `safe` | `soft` | `hard` → use it, and say which one you used and why.
+
+If `orc wait lanes --json` reports `modes_differ: false` for the lane in flight
+(nothing to checkpoint), SAY SO and do not ask — the three modes are identical
+there, and asking a question with one real answer wastes a turn.
+
+## W3 — reach the stop point
+
+Answer the user IMMEDIATELY, before you reach it. A queued command that looks
+ignored reads as a broken command.
+
+```
+⏸ I got your wait. 30 minutes, soft.
+   Wave 3 is running. I do not stop a dispatch in the middle.
+   I stop as soon as wave 3's returns are validated.
+```
+
+| mode | stop at |
+|---|---|
+| `safe` | the next SAFE POINT — see the table in `_shared/wait.md` |
+| `soft` | the next model turn |
+| `hard` | the next model turn |
+
+**Never begin a wait** between a dispatch and its validated return, inside the
+stop sequence, during a file write, or before the smoke gate has reported. That
+holds in every mode, `hard` included.
+
+Never write "immediately". `hard` stops at the first moment ORC can act.
+
+## W4 — hand back (the step that is never skipped)
+
+| mode | what you write |
+|---|---|
+| `safe`, `soft` | the FULL stop sequence — `_shared/phases/stop-resume.md`, steps 2–3b |
+| `hard` | `RESUME.md` ONLY, with your own hand, never a dispatched agent |
+
+**`soft` is FORCED.** If the checkpoint write fails, **do not stop**. Report the
+failure and stay in the run. Stopping without a good checkpoint is the one thing
+that loses work.
+
+`hard` is the dispatch-free stop: it writes only what ORC can write itself, and
+that is exactly why it is fast. When you use it, name what may be lost:
+
+```
+⚠ hard: wave 3 had 2 dispatches in flight. Their file writes may still land,
+   but their returns are not validated. RESUME.md records this.
+```
+
+## W5 — hop
+
+Run each hop as a **detached** command so no model is running and no tokens are
+spent. One hop per entry in `hops[]` from W1.
+
+After every hop:
+
+1. `orc usage check --json` (exit 0 → the window recovered; go to W6)
+2. `orc wait status --json` — `cancel_requested: true` → stop hopping, go to W6
+3. otherwise, the next hop
+
+Print the END TIME every hop, not only the length: "hop 2 of 4, ends 19:14".
+A user who cannot see when a wait ends cannot tell it from a hang.
+
+## W6 — come back
+
+Read `context` from `orc usage check --json`.
+
+- **context small** → continue the run here, in one line.
+- **context large** → STOP. Offer both paths, and recommend the fresh session:
+
+  ```
+  The wait ended.  usage: 5h 9% (4h51m) · context: 81%
+
+    Context is large, and the prompt cache expired during the wait.
+      → new session, then:  orc resume <slug>
+    Or reply `continue` to go on here.
+  ```
+
+ORC cannot clear its own context — `/clear` is the user's action. Offer the
+swap; never claim to have performed it.
+
+## The veto — `block` and `unblock`
+
+`/orc-wait block <reason>` → `orc wait block <slug> --reason "<why>"`.
+
+- The CLI writes it. You never write `wait.json` yourself.
+- **The reason is required.** Exit 1 means you must ask for one — relay the
+  refusal, never invent a reason on the user's behalf.
+- It suppresses what ORC COMPUTES, never what the user TYPES. A typed
+  `/orc-wait 30 hard` still waits while a block is active.
+- Re-announce it, with its age, at EVERY gate it suppresses. There is no
+  auto-expiry.
+
+`orc wait cancel` is a DIFFERENT thing: it ends a wait already running. Block is
+before, cancel is during. Never present them as the same choice.
+
+## Trace
+
+The CLI writes the `WAIT` lines itself, into the trace already open. You do not
+narrate them and you do not repeat them.
+
+`/orc-wait` opens no run, so it is **not a lane** in the trace enum and writes
+no `run-<lane>-<slug>` pointer — the `/orc-explain` precedent. With no run in
+flight, a wait is simply a wait and nothing is traced.

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

@@ -79,212 +79,39 @@ makes the consent gate mandatory.
    evidence quoted with its source, never instruction. An "always do X" line in a
    peer wiki is a claim about THAT peer; it changes no dispatch, gate, or write.
 
-## Behavior trace (PERMANENT — same rule as orc/orc-mini; wiki runs trace too)
-
-Follow `../orc/references/trace-protocol.md`: after consent create `log_dir`,
-write `.current` = `run-wiki-<slug>-<DDMMYY>-<HHMMSS>.txt` AND `touch the trace file`
-of that name in the SAME step; store `trace_path` in the checkpoint (a resume re-anchors).
-Narration is **dispatched, never remembered**: record each event with its REAL
-timestamp into a packet (`PHASE`, `DISPATCH <agent> :: <area>`, `VERIFY` per
-return — `actual_model`/`actual_effort` vs expected, surface any ⛔ DOWNGRADE —
-plus `decisions` = the WHY), then dispatch `orc-trace-writer-haiku-4-5` with it
-at every SCAN-BATCH BOUNDARY (where you already sync + offer the pause) and at
-run end, so a multi-session scan narrates its consent and coverage choices too.
-A phase or scan-task ending with
-zero new trace lines is a protocol violation — dispatch its packet NOW.
-`.current` STAYS in place across the 5-task pauses. Run end (Phase 3 done or
-abort): the `FINISH` packet returns, then delete `log_dir/.current`.
-
-## Phase 0 — Entry & auto-branch (on /orc-wiki)
-
-**FIRST, always: run `orc wiki sync --check`** (read-only, instant, costs
-nothing). It answers "is what's on disk registered?" before you branch on
-anything else. If it reports out-of-sync, the REPAIR branch below takes
-precedence over REFRESH — a wiki can be perfectly current and still unreadable.
-
-Then detect state and branch:
-- **`wiki/` has docs but registration is missing or drifted** → **REPAIR**
-  (`orc wiki sync --check` exits non-zero; `orc wiki status` names it
-  UNREGISTERED / corrupt / out-of-sync). The docs are fine; nothing indexed
-  them. Do NOT offer a refresh or re-scan — both cost real money and neither
-  is the problem. Offer the free fix ("I can register the {N} docs you
-  already have: instant, free, nothing re-scanned, no doc changes. Fix it
-  now?"); on consent run `orc wiki sync`, report, then re-branch below.
-  **Never bundle a scan into repair.** REPAIR can coexist with RESUME (a
-  paused scan is the usual cause): register first, THEN offer the resume as a
-  separate, clearly-priced choice.
-- **`/orc-wiki crosslink compile` (explicit)** → **CROSSLINK COMPILE**
-  (references/crosslink-compile.md) — one-shot: resolve/consume → generate the
-  LOCAL atlas → write it into each linked repo → inject the CLAUDE.md pointer
-  block locally AND in each peer (in-place, byte-preserving). Hard
-  precondition: a crosslink config with ≥1 edge (else explain `orc crosslink`
-  and stop). Each step warn-only; never a re-scan, never a doc rewrite; one
-  end-of-run trace packet.
-- **`/orc-wiki crosslink` (explicit), OR a LEGACY wiki (docs predate v0.24.0,
-  `wiki/crosslink/` absent) whose docs show an outward boundary** →
-  **CROSSLINK-ONLY** (Phase 3c) — a legacy BACKFILL: publish/resolve the
-  boundary from existing docs, no re-scan, no doc rewrite. On a wiki scanned at
-  ≥v0.24.0, missing tags are NOT this branch — the `orc wiki sync --check`
-  boundary guard fired and already names the real fix. Auto-detect OFFERS it in
-  one line with a small cost note; never start unasked.
-- **Empty/absent `wiki/` AND no wiki checkpoint** → FRESH. Show the generic
-  cost warning ("scans your code with Opus 4.8 high — expensive, likely
-  multi-session, fixed pause every 5 areas; nothing scanned until you
-  confirm") and wait for explicit consent. Only THEN Phase 1.
-- **Wiki checkpoint exists (mid-scan)** → RESUME. Re-anchor from
-  state-of-play + checkpoint; show "X of Y areas done, ~Z remaining"; light
-  cost note; continue where it stopped.
-- **`/orc-wiki refresh <doc> | --only <glob> | --top N | --all-touched`
-  (explicit)** → **TARGETED REFRESH** (references/partial-refresh.md). Skips
-  branch detection AND area planning — the doc exists, so its coverage area is
-  already in its own header. Probe with `orc wiki plan --json` (free, ranked,
-  priced), confirm the doc + delta + resolved TIER + estimate in ONE turn, scan,
-  `orc wiki sync`, integrity-check that doc. **Free repairs are always offered
-  before anything that costs money** — sync, then the orientation doc, then a
-  crosslink backfill, and only then a paid scan.
-- **Complete wiki, no active checkpoint** → REFRESH. **Run `orc wiki impact`
-  FIRST** (deterministic probe — exit 0 clean / 2 delta / 3 full recommended;
-  staleness.md mode 1). **Delta is the default path**: on exit 2, offer to
-  re-scan only the TOUCHED docs; on exit 3, present the impact table and let
-  the user choose (never silently full). Other modes on request: full
-  regenerate · selective (stale-flagged docs) · pre-push git-diff scan ·
-  nothing — each with a cost note; scan only on consent. Every mode
-  re-publishes crosslink tags in the same pass (hard rule 11), preserves the
-  folder (rule 12), and ends by regenerating the orientation doc + atlas
-  (derived, cheap). A LEGACY wiki with unpublished tags is a backfill, not a
-  refresh — route to CROSSLINK-ONLY.
-
-## Phase 1 — Area planning (after consent)
-
-Infer the knowledge slicing from repo structure (directories, services,
-modules, routes, domains) plus cross-cutting topics (auth, data model, API
-conventions, deployment, build). Produce a scan plan: scan-tasks, each = one
-area/topic with the files it covers. Show the plan (areas, count, where the
-5-task pauses fall). Doc types:
-- `wiki/orc-feature-{x}-overview.md` — a feature/domain area
-- `wiki/orc-reference-{topic}.md` — cross-cutting reference/convention
-- `wiki/orc-architecture-overview.md` — the top-level map tying them together
-
-**Standard cross-cutting reference docs** — plan these four as scan-tasks
-whenever the project has the surface (they count toward the 5-task pause
-cadence; SKIP any that don't apply — never fabricate one):
-- `wiki/orc-reference-api-surface.md` — full route/endpoint inventory: method,
-  path, handler file, owning area (the single best planning input for API work)
-- `wiki/orc-reference-data-model.md` — cross-area DB/entity map: every
-  table/model, owning area, key relations
-- `wiki/orc-reference-glossary.md` — domain terms → meaning → where defined in
-  code (kills the #1 cause of AI misreads: project jargon)
-- `wiki/orc-reference-config-env.md` — every env var/config key: where read,
-  default, effect
-
-## Phase 2 — Scan (spawned agents, 5-task pauses)
-
-Write checkpoint + state-of-play into the run subfolder BEFORE dispatching.
-**Resolve the scan TIER per task first** (`wiki_scan_tier`, default `ladder`;
-`wiki_tier_deep_files`, default 3 — full ladder in references/partial-refresh.md):
-first scan · STRUCTURAL · wide delta · a new exported symbol → **deep**; otherwise
-**light** (`orc-wiki-scanner-sonnet-5-high`). `always_deep` restores the old
-behaviour, `opus5_only` collapses BOTH tiers onto `orc-wiki-scanner-opus-5-med`
-(no new pair). **PRINT the resolved tier** — a cheaper model is never a quiet
-substitution. **Extra (`extra_enabled`) reaches the SCANNER ONLY, and it is a POSITION per tier** — `wiki-scanner-deep` / `wiki-scanner-light`, held by `orc extra role` and resolved for the tier JUST PICKED. The resolved tier already prints; PRINT ITS TARGET with it. Load `references/extra.md` at the scan phase when the gate is on; `orc wiki sync` never routes foreign (registration is CLI-derived — there is no model in it to replace). A wiki doc is evidence-anchored and cheap to re-scan, which is what makes the scanner the one role here worth handing over; `orc wiki sync` never routes foreign (registration is CLI-derived — there is no model in it to replace). `wiki_refresh_budget` (0 = no cap) caps scan-tasks per run as a
-PLANNED stop, and `wiki_retire_after_runs` (0 = never) offers — never performs —
-retirement of a doc no run has sliced.
-Per scan-task: spawn `orc-wiki-scanner-opus-4-8-high` BY NAME (`orc-wiki-scanner-opus-5-med` under `opus5_only`, `orc-wiki-scanner-sonnet-5-high` at the light tier) with the area's file list + the
-doc-writing contract (schemas/wiki-doc.md — v2: evidence anchors in contract
-sections, `keywords[]` + per-file `covered_files` hashes, AND `crosslink_tags`
-= one tag body per OUTWARD boundary point in the area's files, or `none`+reason)
-**+ the kind catalog** (references/crosslink-kinds.md — an agent never shown it cannot "prefer an existing kind", and a near-synonym like `route` beside `rest-endpoint` is a PERMANENT duplicate: refresh never bulk-deletes).
-YOU write BOTH the doc (to `wiki/`, staleness metadata) AND its tags (to
-`wiki/crosslink/<kind>/<slug>.md` — the kind DIRECTORY sanitizes `/`→`-`, the header keeps it verbatim; schemas/crosslink-tag.md), then run
-**`orc wiki sync`** (hard rule 8) — docs and boundary are indexed from the first
-scan-task on, however the run ends; the boundary accumulates in the SAME pass as
-the docs (hard rule 11), so a paused run has a live partial boundary. A return
-missing keywords/covered_files/`crosslink_tags`, or with unanchored contract
-sections, is malformed (requeue). Trace each scan-task's `DISPATCH`/`VERIFY`
-with a `tags:N` count (or `tags:none`).
-
-Every 5 completed scan-tasks → STOP SEQUENCE
-(`../orc/references/stop-and-resume.md`): checkpoint → state-of-play →
-dispatch report → "/usage" reminder → resume block → wait for continue.
-Multi-session resume is expected and normal.
-
-**A pause must never read as a finish.** The stop sequence looks exactly like
-Phase 3's completion report, and users have walked away from a half-scanned
-repo believing it was done. At every pause, lead with the coverage line:
-> ⏸ **PAUSED — not finished.** {N} of {M} areas scanned, {M−N} remaining.
-> The {N} docs so far are registered and usable now. Reply **continue** to scan
-> the rest.
-At completion, say **✅ Wiki complete — all {M} areas scanned.** The two must be
-impossible to confuse at a glance.
-
-## Phase 3 — Assemble & inject
-
-Phase 3 assembles the whole; it is NOT where registration or crosslink first
-happen (both ran per scan-task — hard rules 8, 11). If the user stopped early,
-the docs + tags are already registered and this phase simply hasn't run yet.
-
-1. After all areas are scanned, write/update
-   `wiki/orc-architecture-overview.md` linking the feature + reference docs. **OPTIONAL** — a wiki without one registers cleanly, and its CLAUDE.md pointer is conditional on the file existing.
-2. **Derive `wiki/orc-orientation.md`** (references/orientation.md) from the
-   already-written docs + the overview WHEN IT EXISTS (absent → say so in the doc; degrade explicitly, never silently) — NEVER a new scan
-   area; one assemble-time write. Sections: Repo identity · Reading order · Journeys (each step
-   anchored `file:line`; unanchored = omitted) · Neighbors (only when
-   crosslink is configured AND the cache/atlas exists; else the explicit
-   "no outward boundary"-style line). Standard doc header → registered by sync.
-   Regenerate it (free, derived) whenever any doc it points to refreshes.
-3. **Crosslink resolve + dead-tag sweep + ATLAS** (references/crosslink.md):
-   publish already happened per scan-task (hard rule 11) — here only, if
-   `.claude/orc-crosslink.config.yaml` exists, resolve consumed needs +
-   `.claude/orc/crosslink/cache/` (warn on per-point drift), run the
-   dead-tag sweep (references/staleness.md) — retire per-point ONLY tags whose
-   anchor vanished; never bulk-delete `wiki/crosslink/` — then generate the
-   federation atlas (`wiki/crosslink/atlas.md`) and write the SAME file into
-   each linked repo (sanctioned peer FILE write — never commit/push, warn-only
-   on failure; crosslink.md ATLAS section).
-4. **Run `orc wiki sync`** (hard rule 8) — re-derives `wiki/INDEX.md` +
-   `.claude/orc/wiki-meta.json` from every doc header, including the
-   architecture + orientation docs and the `crosslink_provided` index of the
-   per-scan-task tags (`atlas.md` is derived — sync never registers it). The
-   build/test `commands` you discovered during the scan are the
-   ONE thing no header carries: if the manifest's `commands` is absent or wrong,
-   fix that key by hand — it is the only part of the manifest you ever touch.
-5. **Run the integrity self-check** (hard rule 9 — references/
-   integrity-check.md): registration (`sync --check`), covers-resolve,
-   coverage, anchor + crosslink spot-checks, orientation pointers resolve.
-   Runs AFTER sync (validates the derivation). Fix failures first; emit
-   `WIKI-CHECK` when logging.
-6. Inject/update the managed pointer block in `CLAUDE.md`
-   (see references/claude-md-injection.md) — includes the orientation
-   "read this first" pointer and, when crosslink is configured, the atlas
-   pointer. Pointer only — no summaries; in-place block update, never
-   duplicated.
-7. Final report: lead with **✅ Wiki complete — all {M} areas scanned**
-   (unmistakably distinct from a pause), then the dispatch log + "/usage"
-   reminder. Keep the checkpoint for audit.
-
-## Phase 3c — CROSSLINK-ONLY (legacy backfill: publish/resolve, NO area scan)
-
-Entry: `/orc-wiki crosslink`, or the Phase 0 CROSSLINK-ONLY branch. A LEGACY
-BACKFILL — for wikis whose docs predate v0.24.0 (docs exist, `wiki/crosslink/`
-absent); the boundary is already on disk in the docs' `Contracts & shapes` rows.
-On a ≥v0.24.0 wiki tags publish per scan-task, so missing tags mean the
-`orc wiki sync --check` boundary guard fired — not this branch. **Never a
-re-scan.** **Consent** is small and honest, NOT the scan warning: "reads
-existing docs' rows, opens only the {N} anchored files, no repo scan, no doc
-changes. Proceed?" (Prereq: `wiki/` has docs.)
-
-**Steps:** collect boundary points from the docs' `Contracts & shapes` rows
-(read DOCS, not source) → dispatch Opus 4.8 high over the anchored files ONLY
-(tag bodies per schemas/crosslink-tag.md; unanchorable row = SKIPPED + reported)
-→ write `wiki/crosslink/<kind>/<slug>.md` → resolve the consume half when
-`.claude/orc-crosslink.config.yaml` exists → `orc wiki sync` → crosslink
-integrity (`WIKI-CHECK crosslink …`). **Never** re-scan, rewrite a doc, or touch
-coverage/`pages` — coverage is a scan question; the boundary is not.
-
-**Zero-tag outcome is always explicit + reasoned, never a bare finish:** rows
-too thin/absent to tag → SAY so + recommend an incremental refresh of just those
-areas (an honest cost, not "never a refresh"); pure consumer (inbound-only, no
-API of its own) → valid no-op but NAME the inbound-only edges (references/crosslink.md).
+## Behavior trace (always on)
+
+`../_shared/phases/trace.md` (`core`, at run start; `orc lane phases` names
+the file and the layers). Lane token `wiki`, tier **Multi-dispatch** —
+one packet per SCAN-BATCH boundary (where you already sync + offer the pause)
++ the end-of-run packet.
+At run start write `log_dir/.current` = `run-wiki-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
+`touch the trace file` of that name in the SAME step.
+Nothing else about the protocol is restated here; a phase that ends with
+`zero new trace lines is a protocol violation`.
+
+Store `trace_path` in the checkpoint — a resume re-anchors from it. `.current`
+STAYS in place across the 5-task pauses; it is deleted only when Phase 3 is
+done or the run aborts, after the `FINISH` packet returns.
+
+## Phases
+
+`orc lane phases orc-wiki --json` is this lane's pipeline: the ordered list, the
+file each phase lives in, and how much of it to read. **The CLI owns the order**
+— never derive it from these filenames.
+
+**Read a row when its phase fires, not on activation.** A wiki run reaches FEW
+of them: Phase 0 auto-branches into fresh / resume / refresh / repair, and Phase
+3c is a legacy backfill for pre-v0.24.0 wikis. Each file is this lane's own —
+one consumer, so it stays home.
+
+| # | Phase | File | Read |
+|---|-------|------|------|
+| 0 | Phase 0 | `references/phases/phase-0.md` | `full` |
+| 1 | Phase 1 | `references/phases/phase-1.md` | `full` |
+| 2 | Phase 2 | `references/phases/phase-2.md` | `full` |
+| 3 | Phase 3 | `references/phases/phase-3.md` | `full` |
+| 4 | Phase 3c | `references/phases/phase-3c.md` | `full` |
 
 ## Code-pattern pre-warm (opt-in — only when config `orc_wiki_pattern_findings: on`)
 
@@ -320,3 +147,30 @@ manifest (via `orc wiki sync`). Refresh modes (incremental with the coverage-gap
 + dead-doc + dead-tag sweeps · selective · pre-push), the per-doc
 `covered_files` signal, lazy `wiki_schema: 2` upgrades, and auto-flag /
 post-ship refresh-ask all live in staleness.md — load it, never act from memory.
+
+## Config
+
+**ONE resolver, and it is not you:** `orc lane config orc-wiki --json`. Obey
+`effective`, print every line in `announce[]` VERBATIM at preflight, and honour
+`stops[]` before wave 1. Never re-derive a value, a precedence or an inertness
+from `.claude/orc.config.yaml` — a key this lane does not read is not in the
+answer, and a key another key shadows comes back already marked. Exit ≠ 0 → say
+the CLI is unavailable and fall back to `../_shared/config-precedence.md`'s
+documented defaults, out loud. Priorities and families:
+`../_shared/config-precedence.md`.
+
+## Calls
+
+**ONE catalogue, and it is not you:** `orc lane calls orc-wiki --json` names every
+CLI call this lane makes, each with its exit-code contract, its cost, when to run
+it, and what an EMPTY answer means. Never invent a spelling, never re-word an
+exit code, and never re-derive a state word — the CLI's state words are the only
+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.
+
+## Waiting mid-run (`/orc-wait`)
+
+Canonical: `../_shared/wait.md`. **`a lane that waits without a hand-back` has broken this contract.**
+Checkpoint **full** · safe point **scan-task boundary**. `soft` FORCES that checkpoint and does NOT stop if the write fails; `hard` skips it and can lose an in-flight return. Never begin a wait between a dispatch and its validated return, or before the smoke gate has reported.

package/templates/skills/orc-wiki/references/phases/phase-0.md

@@ -0,0 +1,71 @@
+# Phase — Phase 0 — Entry & auto-branch (on /orc-wiki)   (id: `phase-0`)
+
+> **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
+> spine is loaded IN FULL when the skill activates; this is loaded when the phase
+> fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
+> resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
+> it stays in this lane (`../../../_shared/phases/README.md`: a file with one
+> consumer stays home). `orc lane phases orc-wiki --json` names the file.
+
+<!-- orc:layer full -->
+
+## Phase 0 — Entry & auto-branch (on /orc-wiki)
+
+**FIRST, always: run `orc wiki sync --check`** (read-only, instant, costs
+nothing). It answers "is what's on disk registered?" before you branch on
+anything else. If it reports out-of-sync, the REPAIR branch below takes
+precedence over REFRESH — a wiki can be perfectly current and still unreadable.
+
+Then detect state and branch:
+- **`wiki/` has docs but registration is missing or drifted** → **REPAIR**
+  (`orc wiki sync --check` exits non-zero; `orc wiki status` names it
+  UNREGISTERED / corrupt / out-of-sync). The docs are fine; nothing indexed
+  them. Do NOT offer a refresh or re-scan — both cost real money and neither
+  is the problem. Offer the free fix ("I can register the {N} docs you
+  already have: instant, free, nothing re-scanned, no doc changes. Fix it
+  now?"); on consent run `orc wiki sync`, report, then re-branch below.
+  **Never bundle a scan into repair.** REPAIR can coexist with RESUME (a
+  paused scan is the usual cause): register first, THEN offer the resume as a
+  separate, clearly-priced choice.
+- **`/orc-wiki crosslink compile` (explicit)** → **CROSSLINK COMPILE**
+  (references/crosslink-compile.md) — one-shot: resolve/consume → generate the
+  LOCAL atlas → write it into each linked repo → inject the CLAUDE.md pointer
+  block locally AND in each peer (in-place, byte-preserving). Hard
+  precondition: a crosslink config with ≥1 edge (else explain `orc crosslink`
+  and stop). Each step warn-only; never a re-scan, never a doc rewrite; one
+  end-of-run trace packet.
+- **`/orc-wiki crosslink` (explicit), OR a LEGACY wiki (docs predate v0.24.0,
+  `wiki/crosslink/` absent) whose docs show an outward boundary** →
+  **CROSSLINK-ONLY** (Phase 3c) — a legacy BACKFILL: publish/resolve the
+  boundary from existing docs, no re-scan, no doc rewrite. On a wiki scanned at
+  ≥v0.24.0, missing tags are NOT this branch — the `orc wiki sync --check`
+  boundary guard fired and already names the real fix. Auto-detect OFFERS it in
+  one line with a small cost note; never start unasked.
+- **Empty/absent `wiki/` AND no wiki checkpoint** → FRESH. Show the generic
+  cost warning ("scans your code with Opus 4.8 high — expensive, likely
+  multi-session, fixed pause every 5 areas; nothing scanned until you
+  confirm") and wait for explicit consent. Only THEN Phase 1.
+- **Wiki checkpoint exists (mid-scan)** → RESUME. Re-anchor from
+  state-of-play + checkpoint; show "X of Y areas done, ~Z remaining"; light
+  cost note; continue where it stopped.
+- **`/orc-wiki refresh <doc> | --only <glob> | --top N | --all-touched`
+  (explicit)** → **TARGETED REFRESH** (references/partial-refresh.md). Skips
+  branch detection AND area planning — the doc exists, so its coverage area is
+  already in its own header. Probe with `orc wiki plan --json` (free, ranked,
+  priced), confirm the doc + delta + resolved TIER + estimate in ONE turn, scan,
+  `orc wiki sync`, integrity-check that doc. **Free repairs are always offered
+  before anything that costs money** — sync, then the orientation doc, then a
+  crosslink backfill, and only then a paid scan.
+- **Complete wiki, no active checkpoint** → REFRESH. **Run `orc wiki impact`
+  FIRST** (deterministic probe — exit 0 clean / 2 delta / 3 full recommended;
+  staleness.md mode 1). **Delta is the default path**: on exit 2, offer to
+  re-scan only the TOUCHED docs; on exit 3, present the impact table and let
+  the user choose (never silently full). Other modes on request: full
+  regenerate · selective (stale-flagged docs) · pre-push git-diff scan ·
+  nothing — each with a cost note; scan only on consent. Every mode
+  re-publishes crosslink tags in the same pass (hard rule 11), preserves the
+  folder (rule 12), and ends by regenerating the orientation doc + atlas
+  (derived, cheap). A LEGACY wiki with unpublished tags is a backfill, not a
+  refresh — route to CROSSLINK-ONLY.
+
+<!-- /orc:layer -->

package/templates/skills/orc-wiki/references/phases/phase-1.md

@@ -0,0 +1,35 @@
+# Phase — Phase 1 — Area planning (after consent)   (id: `phase-1`)
+
+> **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
+> spine is loaded IN FULL when the skill activates; this is loaded when the phase
+> fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
+> resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
+> it stays in this lane (`../../../_shared/phases/README.md`: a file with one
+> consumer stays home). `orc lane phases orc-wiki --json` names the file.
+
+<!-- orc:layer full -->
+
+## Phase 1 — Area planning (after consent)
+
+Infer the knowledge slicing from repo structure (directories, services,
+modules, routes, domains) plus cross-cutting topics (auth, data model, API
+conventions, deployment, build). Produce a scan plan: scan-tasks, each = one
+area/topic with the files it covers. Show the plan (areas, count, where the
+5-task pauses fall). Doc types:
+- `wiki/orc-feature-{x}-overview.md` — a feature/domain area
+- `wiki/orc-reference-{topic}.md` — cross-cutting reference/convention
+- `wiki/orc-architecture-overview.md` — the top-level map tying them together
+
+**Standard cross-cutting reference docs** — plan these four as scan-tasks
+whenever the project has the surface (they count toward the 5-task pause
+cadence; SKIP any that don't apply — never fabricate one):
+- `wiki/orc-reference-api-surface.md` — full route/endpoint inventory: method,
+  path, handler file, owning area (the single best planning input for API work)
+- `wiki/orc-reference-data-model.md` — cross-area DB/entity map: every
+  table/model, owning area, key relations
+- `wiki/orc-reference-glossary.md` — domain terms → meaning → where defined in
+  code (kills the #1 cause of AI misreads: project jargon)
+- `wiki/orc-reference-config-env.md` — every env var/config key: where read,
+  default, effect
+
+<!-- /orc:layer -->

package/templates/skills/orc-wiki/references/phases/phase-2.md

@@ -0,0 +1,52 @@
+# Phase — Phase 2 — Scan (spawned agents, 5-task pauses)   (id: `phase-2`)
+
+> **`/orc-wiki` phase file.** Moved out of `orc-wiki/SKILL.md` at v1.0.0 W14. The
+> spine is loaded IN FULL when the skill activates; this is loaded when the phase
+> fires — and a wiki run reaches FEW of them: Phase 0 auto-branches into fresh /
+> resume / refresh / repair, and Phase 3c is a legacy backfill. ONE consumer, so
+> it stays in this lane (`../../../_shared/phases/README.md`: a file with one
+> consumer stays home). `orc lane phases orc-wiki --json` names the file.
+
+<!-- orc:layer full -->
+
+## Phase 2 — Scan (spawned agents, 5-task pauses)
+
+Write checkpoint + state-of-play into the run subfolder BEFORE dispatching.
+**Resolve the scan TIER per task first** (`wiki_scan_tier`, default `ladder`;
+`wiki_tier_deep_files`, default 3 — full ladder in references/partial-refresh.md):
+first scan · STRUCTURAL · wide delta · a new exported symbol → **deep**; otherwise
+**light** (`orc-wiki-scanner-sonnet-5-high`). `always_deep` restores the old
+behaviour, `opus5_only` collapses BOTH tiers onto `orc-wiki-scanner-opus-5-med`
+(no new pair). **PRINT the resolved tier** — a cheaper model is never a quiet
+substitution. **Extra (`extra_enabled`) reaches the SCANNER ONLY, and it is a POSITION per tier** — `wiki-scanner-deep` / `wiki-scanner-light`, held by `orc extra role` and resolved for the tier JUST PICKED. The resolved tier already prints; PRINT ITS TARGET with it. Load `../extra.md` at the scan phase when the gate is on; `orc wiki sync` never routes foreign (registration is CLI-derived — there is no model in it to replace). A wiki doc is evidence-anchored and cheap to re-scan, which is what makes the scanner the one role here worth handing over; `orc wiki sync` never routes foreign (registration is CLI-derived — there is no model in it to replace). `wiki_refresh_budget` (0 = no cap) caps scan-tasks per run as a
+PLANNED stop, and `wiki_retire_after_runs` (0 = never) offers — never performs —
+retirement of a doc no run has sliced.
+Per scan-task: spawn `orc-wiki-scanner-opus-4-8-high` BY NAME (`orc-wiki-scanner-opus-5-med` under `opus5_only`, `orc-wiki-scanner-sonnet-5-high` at the light tier) with the area's file list + the
+doc-writing contract (schemas/wiki-doc.md — v2: evidence anchors in contract
+sections, `keywords[]` + per-file `covered_files` hashes, AND `crosslink_tags`
+= one tag body per OUTWARD boundary point in the area's files, or `none`+reason)
+**+ the kind catalog** (references/crosslink-kinds.md — an agent never shown it cannot "prefer an existing kind", and a near-synonym like `route` beside `rest-endpoint` is a PERMANENT duplicate: refresh never bulk-deletes).
+YOU write BOTH the doc (to `wiki/`, staleness metadata) AND its tags (to
+`wiki/crosslink/<kind>/<slug>.md` — the kind DIRECTORY sanitizes `/`→`-`, the header keeps it verbatim; schemas/crosslink-tag.md), then run
+**`orc wiki sync`** (hard rule 8) — docs and boundary are indexed from the first
+scan-task on, however the run ends; the boundary accumulates in the SAME pass as
+the docs (hard rule 11), so a paused run has a live partial boundary. A return
+missing keywords/covered_files/`crosslink_tags`, or with unanchored contract
+sections, is malformed (requeue). Trace each scan-task's `DISPATCH`/`VERIFY`
+with a `tags:N` count (or `tags:none`).
+
+Every 5 completed scan-tasks → STOP SEQUENCE
+(`../../../_shared/phases/stop-resume.md`): checkpoint → state-of-play →
+dispatch report → "/usage" reminder → resume block → wait for continue.
+Multi-session resume is expected and normal.
+
+**A pause must never read as a finish.** The stop sequence looks exactly like
+Phase 3's completion report, and users have walked away from a half-scanned
+repo believing it was done. At every pause, lead with the coverage line:
+> ⏸ **PAUSED — not finished.** {N} of {M} areas scanned, {M−N} remaining.
+> The {N} docs so far are registered and usable now. Reply **continue** to scan
+> the rest.
+At completion, say **✅ Wiki complete — all {M} areas scanned.** The two must be
+impossible to confuse at a glance.
+
+<!-- /orc:layer -->