@azure-id/orc 0.55.0

package/templates/skills/_shared/detecting-artifacts.md

@@ -0,0 +1,90 @@
+# Shared contract — Detecting the wiki & pattern cache (existence, not freshness)
+
+THE canonical answer to the question every knowledge-gated lane asks FIRST:
+**does a generated wiki / cached code-pattern already exist?** This governs
+EXISTENCE detection only — freshness and precedence are decided afterward per
+`../orc-wiki/references/staleness.md`. Load this at any
+preflight/consult point that must know whether the precomputed knowledge is
+present (orc-fast F0, orc/orc-mini wiki-consult, the pattern resolve gate,
+orc-verify's pattern check, orc-learn's topic pick).
+
+## The trap this closes
+
+Both artifacts live under the HIDDEN `.claude/` dir:
+
+- wiki manifest → `.claude/orc/wiki-meta.json` (+ docs under `wiki/`)
+- pattern cache → `.claude/orc/patterns/<lang>-pattern.md`
+
+A model probing with an ad-hoc `find` / glob / `ls` gets a FALSE "missing"
+whenever the search skips dot-directories or runs from the wrong working
+directory (a subfolder, an eval sandbox root). A generated wiki or pattern then
+reads as absent and the lane needlessly falls back, re-scans, or re-codifies.
+**Never conclude "missing" from a raw filesystem search.**
+
+## The rule — probe with the deterministic CLI, ONCE, up front
+
+At preflight — BEFORE any gate logic — run the CLI probes and treat their output
+as the SOURCE OF TRUTH. They resolve `.claude` exactly like every other `orc`
+command (independent of CWD) and read the artifacts directly, so a generated
+wiki/pattern is never missed:
+
+- **Wiki:** `orc wiki status` → `none | unregistered | corrupt | drifted |
+  registered` (plus a freshness tier when registered). Only `none` means the
+  wiki is truly ABSENT; every other state means it EXISTS (registration/parse
+  issues are a cheap re-registration fix, never a reason to conclude "no wiki").
+- **Pattern:** `orc pattern status <lang>` → exit 0 = cached, exit 1 = absent,
+  **exit 2 = unknown language key** (the exit code is the contract). `<lang>` is
+  a FRAMEWORK key from `orc-pattern/references/INDEX.md` (`express`, `react`,
+  `fastapi`, …) — never a file extension: probing `js` used to answer a clean
+  "absent" for a key the payload has never heard of, so the gate fell back
+  correctly and the CALLER's bug read as a lane defect. Exit 2 says "you asked
+  the wrong question" and lists the real keys. `orc pattern status` with no arg
+  lists every cached language (exit 1 when the cache is empty — the same absent
+  contract).
+
+Use `npx --no-install orc …` when `orc` is not on PATH. Record both results in
+run state so the lane ALREADY KNOWS the wiki and pattern exist — do not re-probe
+per gate, and do not second-guess a positive probe with a `find`.
+
+## Fallback when the CLI genuinely cannot run
+
+Only if the `orc` CLI is unavailable: resolve the repo root explicitly and test
+the EXACT path — never trust a recursive search that may skip dot-dirs:
+
+```
+root=$(git rev-parse --show-toplevel)
+test -f "$root/.claude/orc/wiki-meta.json"                 # wiki registered
+test -f "$root/.claude/orc/patterns/<lang>-pattern.md"     # pattern cached
+```
+
+## Handoff
+
+Existence decides only "is the knowledge THERE." Once present, the freshness
+tier comes from **the same probe** — `orc wiki status` prints it, and
+`orc wiki status --json` exposes `.tier` / `.distance` / `.blind` for branching
+(v0.41.0). The tier RULES and the precedence rule stay canonical in
+`../orc-wiki/references/staleness.md`, but the CLI is their only executor:
+never re-derive a tier by reading `wiki-meta.json` and running `git rev-list`
+yourself. A hand-computed tier is one that gets skipped under load or measured
+from the wrong anchor — the same reason existence became a probe in the first
+place. Absent routes per each lane's own gate: orc-fast → fallback to orc-mini;
+orc / orc-mini → proceed without it (the wiki/pattern are purely additive).
+
+## The payload rule (v0.49.1)
+
+A probe answers EXISTENCE and a tier answers FRESHNESS, and both come from the
+CLI. One more rule governs what the CLI hands back:
+
+> **`--json is not a summary`** — a read's `--json` is the WHOLE computed object.
+> A field the human path prints and the JSON omits is drift, and it is drift NO
+> LINT CAN SEE, because both halves live in one function.
+
+`orc wiki status --json` used to emit five scalars and a COUNT while its own
+terminal branch printed the per-doc tier counts, the worst doc's FILENAME and the
+crosslink boundary state — so nothing reading the JSON could ever be as detailed
+as the terminal, however well it was written.
+
+The practical consequence for a skill: **read the whole object.** If you find
+yourself about to recompute something because "the JSON does not carry it", check
+whether the human path prints it. If it does, that is a CLI bug, not a reason to
+recompute — and recomputing it is how a second idea of a number gets born.

package/templates/skills/_shared/drift-recovery.md

@@ -0,0 +1,98 @@
+# Mock example + drift recovery (canonical — v0.33.0)
+
+The ONE canonical procedure for the post-implementation mocked example and the
+`DRIFT-FROM` recovery handoff. Implementation lanes only (orc, orc-mini,
+orc-fast, orc-ultra, orc-diy via its block) — never in read-only/doc lanes.
+Lane spines keep the trigger + pointer; this file is the mechanism. Sibling of
+`fallback-handoff.md` (same handoff-block pattern).
+
+## The mock-example phase
+
+**Gate:** config `mock_example` — `ask` (default) | `on` | `off`.
+**Timing:** after the lane's verify/smoke gate is GREEN, **before ship** —
+never earlier, never after a commit.
+
+- `ask` → the offer is **MANDATORY** — never silently skipped, never silently
+  run: "Build a runnable mocked example of what was just implemented
+  (mock-examples/<change-slug>/, never committed)? [yes/no]".
+- `on` → build without asking. `off` → skip silently.
+
+**Deliverable — `mock-examples/<change-slug>/` at the PROJECT ROOT** (visible;
+never in `.claude/`, never in the run folder):
+
+- `EXAMPLE.md` — what it demonstrates, how to run it, the expected output —
+  each claim anchored to the implemented files;
+- ONE minimal runnable artifact (a script, an `example.http`, or an FE usage
+  snippet). **Mocked inputs/stubs only — never real services, never prod
+  data.**
+
+**Who builds it: NOT you.** The example is DISPATCHED like any task (orc hard
+rule 1 — the orchestrator never implements, not even the smallest task). It is
+an orchestrator-SYNTHESIZED task, so it is scored from a DERIVED vector, never a
+judged one — see `orc/references/wave-grouping.md` "Orchestrator-synthesized
+tasks".
+
+**Git: NEVER committed.** The ship phase explicitly excludes `mock-examples/`
+from staging — and does NOT edit `.gitignore` (it's a new untracked folder;
+simply never `git add` it). A ship that staged it is malformed.
+
+## The drift question
+
+After the user runs the example, ask exactly ONE question:
+
+> matches expectation? **[yes / drift: \<describe\>]**
+
+`yes` → proceed to ship. `drift:` → the recovery loop below.
+
+## The `DRIFT-FROM` handoff block (written into the shared run folder)
+
+```
+DRIFT-FROM: <lane> mock-example
+LOOP: <1 | 2>                      # recovery loops already spent
+EXAMPLE: mock-examples/<change-slug>/
+USER-DRIFT: <the user's description, verbatim>
+INTENT-SPEC: <path to the run's original intent-spec>
+```
+
+## What carries over
+
+| Carries over | The recovery round RE-DERIVES | On conflict |
+|---|---|---|
+| `USER-DRIFT` — the user's description, verbatim | The current worktree state (what the code actually does NOW) | The worktree wins |
+| The failing expectation: what the example promised vs what it showed | The build + test result, run fresh | The fresh result wins |
+| `INTENT-SPEC` (the run's original intent) + `LOOP` (loops already spent) | Every file claim in the superseded `EXAMPLE.md` | The worktree wins |
+
+An inherited claim is a HINT with a known author, never evidence. The previous
+`EXAMPLE.md` in particular documents the SUPERSEDED contract as fact — that is
+exactly why step 5 deletes it. Re-anchor an inherited claim against the worktree
+or drop it.
+
+## The recovery loop (hard cap: 2)
+
+1. **Gap analysis** — dispatch `orc-analyze-mini-sonnet-5-high` with the
+   handoff block: scope BOUNDED to the drift (what the example shows vs what
+   the intent-spec promised), never a re-analysis of the whole request.
+2. **Patch plan** — dispatch the orc-mini planner
+   (`orc-planner-mini-sonnet-5-high`) on the gap spec.
+
+   Both steps use their `opus5_only` variants (`orc-analyze-mini-opus-5-med` /
+   `orc-planner-mini-opus-5-med`) when that mode is on — see `opus5-only.md`.
+3. **Scored dispatch** of the patch tasks (the lane's normal executor path).
+4. **Re-verify** — the lane's verify/smoke gate again.
+5. **Re-offer** — regenerate the example, then ask the drift question again.
+   **DELETE or overwrite the previous `EXAMPLE.md` first.** After a patch the old
+   example does not merely look dated — it documents the SUPERSEDED contract as
+   fact (one asserted "case-insensitive substring matching" and cited a
+   `String.includes()` call that had become `.startsWith()`). Leaving it in the
+   tree re-seeds the exact drift this loop exists to remove, and re-showing it at
+   the re-offer burns a capped loop on our own artifact.
+
+**Cap hit (2 loops) → STOP with an honest unresolved report**: what still
+drifts, what was tried, and the recommendation (usually a full `/orc` run on
+the remaining gap). Never a silent third loop, never ship as "done".
+
+## Trace
+
+`PHASE mock-example start/end` frames the phase; each recovery loop emits
+`DRIFT loop=<n> :: <user description, compressed>`. End-of-phase packet to the
+trace writer like any phase.