@azure-id/orc 0.55.0

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

@@ -0,0 +1,204 @@
+---
+name: orc-handoff
+description: >
+  The lane for people who do not read code. Use for "/orc-handoff", "I want to
+  change the text on the empty cart page", "can I edit this myself", "what can a
+  PM safely change here". Two modes. MAP finds the files a non-engineer can own —
+  screen text, content, settings with a validator, feature flags, docs — and grades
+  each one: green (a check will catch a mistake), amber (the check is manual), red
+  (looks like content, is not). DO changes one value: it shows you the file, the
+  check, and the undo command BEFORE it edits, then runs the check and tells you in
+  plain words. It never touches a red file. It never commits.
+---
+
+# ORC-HANDOFF
+
+**This whole folder is written in simple English on purpose.** Many people who use
+this lane do not read code, and many do not read English first. Keep every file
+here short, plain, and free of jargon. Same standing rule as `../orc-quick/`.
+
+## What this lane is for
+
+You want to change something small and you should not have to ask an engineer.
+
+- the words on a page
+- a title, a label, a button
+- a setting that has a safe list of values
+- a feature switch that is on or off
+- a document
+
+You do not need to read code. You do not need a terminal. You need to know two
+things before you change anything: **will something catch my mistake**, and **how
+do I undo it**. This lane always tells you both, before it edits.
+
+## The idea that makes this safe
+
+**The grade does not come from the file type. It comes from whether a cheap check
+exists for that file.**
+
+A settings file with a validator is **green**. The exact same file with no
+validator is **amber**. That is why this is a real safety rule and not a feeling.
+
+| Grade | What it means |
+|---|---|
+| 🟢 GREEN | Change it. A check runs after, and it will catch a mistake. |
+| 🟡 AMBER | Change it. But the check is a person, not a program. Here is the check. |
+| 🔴 RED | This looks like content. It is not. ORC will not touch it. |
+
+**A red file is never edited.** Not by you through this lane, not by ORC. The lane
+says why, says who to ask, and **offers** `/orc-quick` instead. It is an offer, not
+a redirect — the same rule `/orc-quick` follows when a job is too big.
+
+## Rules this lane never breaks
+
+- **The undo command is shown BEFORE the edit, not after.** After is too late.
+- **It never stages and never commits.** It prints the git command for you.
+- **It never re-grades a file to make a change possible.** If it is red now, it is
+  red for this request.
+- **It only changes a value that already exists.** It never creates a new key. A
+  new key is a code change.
+
+---
+
+## Mode 1 — MAP: what can I own?
+
+Find the files a non-engineer can safely own, and grade each one. Look for:
+
+- screen text and translations
+- content files (markdown, pages, posts)
+- settings files that have a validator or a schema
+- feature switches
+- example or seed data
+- documents
+- design values (colours, spacing) when they live in their own file
+
+For **each** file, record four things. All four, every time:
+
+1. **what it is**, in plain words ("the words users see on the empty cart page")
+2. **the grade**, and the reason for it
+3. **the exact check** — the command that proves the file is still fine
+4. **the exact undo** — the command that puts it back
+
+The grade comes from step 3. **No check found → amber, or red if the file drives
+behaviour rather than showing text.** Never green without a real check.
+
+Write it to `orc-handoff/surfaces.md` at the top of the project. Shape and field
+rules: `references/surfaces.md`. Then run `orc handoff surfaces` and show what it
+says — the CLI is what everything else reads.
+
+**A file with no check is not a failure of the map.** Say so plainly: "this one has
+no automatic check, so it is amber, and here is what to look at by hand."
+
+## Mode 2 — DO: change one value
+
+Five steps. Do not skip step 2.
+
+```
+H1  find      find the file · show the value now · show its grade
+H2  confirm   ONE message: this is the file, this is the check, this is the undo
+H3  edit      one value, through `orc handoff set`
+H4  check     run the file's own check · say what happened in plain words
+H5  record    add a numbered entry to orc-handoff/<slug>/handoff-log.md
+```
+
+### H1 — find
+
+Search the mapped surfaces first. If the map does not exist yet, run MAP for just
+the area the user named — never the whole project for one small change.
+
+Show the value as it is now. If you cannot find it, say so and ask for more — a
+guessed key is a wrong edit.
+
+### H2 — confirm (one message, always)
+
+```
+File:   web/locales/en.json
+Now:    "Your cart is empty"
+New:    "Nothing in here yet"
+Grade:  🟢 green
+
+After I change it I will run:   npm run i18n:check
+To undo it, run:                git checkout -- web/locales/en.json
+
+Change it? (yes / no)
+```
+
+**This message is not optional, even when the change looks tiny.** It is the whole
+consent step.
+
+### H3 — edit
+
+Always through `orc handoff set <id> <key> <value>`. Never edit the file yourself.
+One writer means one set of rules, and the browser panel uses the same one.
+
+`handoff_write: false` makes this project **map only** — no writes at all. Say that
+plainly and stop; do not work around it.
+
+### H4 — check
+
+Green surfaces: the CLI runs the check and reports it.
+
+- **passed** → say so in one line.
+- **failed** → say what failed, show the undo command again, and **do not try to
+  fix it**. Fixing a failed check is code work.
+
+Amber surfaces: the change is made, and the check is a **task for a person**. Never
+report an amber change as verified. Say: "this file has no automatic check, so
+nothing has confirmed your change yet. Please check: <the manual check>."
+
+### H5 — record
+
+One numbered entry per change, in `orc-handoff/<slug>/handoff-log.md`. Shape:
+`references/handoff-log.md`. One file per thread, named from the first slug, never
+staged.
+
+---
+
+## Preflight (ONE time, silent)
+
+1. **Config.** Read `log_dir` and `handoff_write`. Nothing else.
+2. **Trace.** Write `log_dir/.current` = `run-handoff-<slug>-<DDMMYY>-<HHMMSS>.txt`
+   AND `touch the trace file` in the SAME step. Both, or neither.
+3. **Probe.** `orc handoff surfaces --json` (exit 1 = no map yet, which is normal
+   on a first run). Use `../_shared/detecting-artifacts.md`, never a raw `find`.
+
+## Where this shows up in `/orc`
+
+At ship, if any changed file was a GREEN surface:
+
+> 2 of these were changes a PM could have made alone — try `/orc-handoff` next
+> time.
+
+One sentence. That is the whole seam, and it is how anyone finds out this lane
+exists.
+
+## Behavior trace (always on)
+
+Follow `../orc/references/trace-protocol.md`. Lane name `handoff`.
+**Single-dispatch lane: exactly ONE end-of-run packet** to
+`orc-trace-writer-haiku-4-5`, after the last entry and BEFORE `.current` is
+deleted. It carries `run_meta`, the events (mapped, confirmed, edited, checked) and
+the confirmations as `decisions`. A run that ends with
+`zero new trace lines is a protocol violation`.
+
+Any reading it needs is an **ad-hoc dispatch by model + effort**, never a pinned
+agent — **zero new agents ship for this lane**. Announce it in one line first.
+
+## How this lane fails — and the rule that stops it
+
+| Failure | What stops it |
+|---|---|
+| A file is called safe because it is JSON | The grade comes from the CHECK, not the file type |
+| Someone edits money code through a text change | Red is never edited. Ever |
+| A change looks verified but nothing checked it | Amber returns a manual TASK, never a pass |
+| The user cannot undo it | The undo command is shown BEFORE the edit |
+| It commits something by surprise | It never stages and never commits |
+| It re-grades a file to be helpful | The grade never moves inside one request |
+| It creates a new setting | It only changes values that already exist |
+| The words are too hard to read | This whole folder is simple English |
+
+## Rules this lane always keeps
+
+Show the undo first · never touch a red file · never commit · never create a key ·
+never call an amber change verified · write through `orc handoff set` only · keep
+every word simple.

package/templates/skills/orc-handoff/references/handoff-log.md

@@ -0,0 +1,67 @@
+# Reference — the change log
+
+Loaded at H5. The file is `orc-handoff/<slug>/handoff-log.md`, at the top of the
+project.
+
+## The rules for the file
+
+- **One `.md` per thread, ever.** The folder is named from the FIRST slug and never
+  gets a timestamp, so asking about the same thing again re-opens the same thread.
+  Same rule as `/orc-quick`'s context doc.
+- **Never staged.** ORC does not add it to git. If the user wants it committed they
+  commit it.
+- **Append only.** Entries are numbered and never renumbered.
+- **Do not read the body back.** On re-open, read only the `orc-handoff:toc`
+  block — or the whole file when the user asks for it directly.
+
+## Shape
+
+```markdown
+# Changes — cart copy
+
+<!-- orc-handoff:toc
+1  2026-08-10  web/locales/en.json  cart.empty.title  green  check passed
+2  2026-08-10  content/pricing.md   (page body)       amber  manual check pending
+-->
+
+## 1 · Empty cart title
+
+- when: 10-08-2026 14:11
+- file: web/locales/en.json
+- key: cart.empty.title
+- grade: green
+- was: "Your cart is empty"
+- now: "Nothing in here yet"
+- check: npm run i18n:check → passed
+- undo: git checkout -- web/locales/en.json
+- committed: no
+
+## 2 · Pricing page wording
+
+- when: 10-08-2026 14:26
+- file: content/pricing.md
+- grade: amber
+- what changed: the second paragraph
+- check: open /pricing and read the page → NOT DONE YET (a person must do this)
+- undo: git checkout -- content/pricing.md
+- committed: no
+```
+
+## The two fields people actually come back for
+
+**`undo`** — because the reason someone re-opens this file is almost always "how do
+I put it back". Write the exact command every time.
+
+**`check`** — and it must say what really happened:
+
+- `→ passed` only when a command ran and passed.
+- `→ NOT DONE YET (a person must do this)` for every amber change.
+
+**Never write "checked" for an amber change.** An amber change that reads as
+verified is the one entry in this file that could mislead somebody badly.
+
+## The toc block
+
+The block between `<!-- orc-handoff:toc` and `-->` is the only part re-read on
+re-open. Keep it to one line per entry: number, date, file, key, grade, outcome.
+It exists so a long thread never costs a full file read.

package/templates/skills/orc-handoff/references/surfaces.md

@@ -0,0 +1,88 @@
+# Reference — the surface map
+
+Loaded in MAP mode. The file is `orc-handoff/surfaces.md`, at the top of the
+project. It is a normal file you can read and commit.
+
+## Shape
+
+One block per file. The heading is the name of the block, so it must not change
+once written — other things point at it by id.
+
+```markdown
+# Files a non-developer can own
+
+## H-001 · web/locales/en.json · Screen text
+- grade: green
+- check: npm run i18n:check
+- check_kind: command
+- revert: git checkout -- web/locales/en.json
+- keys: cart.empty.title, cart.empty.cta
+
+## H-002 · content/pricing.md · The pricing page
+- grade: amber
+- check: open /pricing in the app and read the page
+- check_kind: manual
+- revert: git checkout -- content/pricing.md
+- upgrade: a link checker would make this green
+
+## H-003 · src/config/limits.ts · Looks like settings, is code
+- grade: red
+- reason: this file decides how much a customer is charged
+- ask: a backend developer
+```
+
+## The fields
+
+| Field | Required | What it holds |
+|---|---|---|
+| `grade` | yes | `green`, `amber` or `red` |
+| `check` | green + amber | the exact command, or the exact manual step |
+| `check_kind` | yes | `command` or `manual` |
+| `revert` | green + amber | the exact command that puts the file back |
+| `keys` | no | the keys inside the file a person may change |
+| `reason` | red | why this is not content, in plain words |
+| `ask` | red | who to ask instead |
+| `upgrade` | no | what would move this file up a grade |
+
+## How to pick the grade
+
+Ask one question: **if this person makes a mistake, what catches it?**
+
+- A command catches it → **green**. Put the command in `check`.
+- Only a person catches it → **amber**. Put the human step in `check`.
+- Nothing catches it, or the file changes what the software DOES rather than what
+  it SAYS → **red**.
+
+That is the whole rule. Do not grade by folder, by file extension, or by how the
+file looks.
+
+## `upgrade` is worth filling in
+
+An amber file with `upgrade: a schema check would make this green` turns a warning
+into a small, clear piece of engineering work. Over time that is how a project
+grows more green surfaces — which is the real outcome this lane is aiming at.
+
+## One thing to tell people about JSON files
+
+When `orc handoff set` changes a value in a `.json` file, it re-writes the whole
+file with normal 2-space (or the file's own) indentation. The values and their
+order do not change, but if the file had unusual spacing, **the diff can be
+bigger than the one line you changed.**
+
+Say this in the confirmation step for a JSON surface. It is not a problem — the
+check still runs and the undo command still works — but somebody looking at the
+diff afterwards should not be surprised by it.
+
+## What never goes in the map
+
+- Anything under `.claude/` — that is ORC's own state.
+- Secrets, `.env`, keys, tokens. Not even as red.
+- Generated files. Editing one is undone by the next build, which looks like the
+  edit was ignored.
+- A file that only exists in one person's checkout.
+
+## Keep it honest
+
+If a project has **no** green surfaces, say that. A map full of amber is a true
+map. A map that calls things green so the lane looks useful is the one failure
+mode that could actually hurt somebody.

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

@@ -0,0 +1,82 @@
+---
+name: orc-judge
+description: >
+  Judgment gates for the ORC ultra lane. One judge skill, one agent
+  (orc-judge-opus-5-xhigh), three dispatch contexts: gate=analysis (after the
+  analyst), gate=plan (after the planner), gate=implementation (after verify —
+  the anti-miss-implementation fidelity + strict-quality gate). Returns a
+  structured verdict (APPROVE | REVISE | ESCALATE) with anchored,
+  consequence-cited findings; REVISE loops the author with a hard 2-loop cap
+  and a convergence rule. Dispatched only from /orc-ultra — no slash command
+  of its own, never in orc or orc-mini. The orchestrator dispatches the judge
+  subagent — it never judges itself.
+---
+
+# ORC-JUDGE (ultra-lane judgment gates)
+
+A model-based quality gate on top of ORC's deterministic gates. The judge
+handles what determinism cannot: scope-interpretation correctness, plan
+soundness, implementation fidelity, and — at the final gate — ultra-strict
+code quality. Deterministic gates ALWAYS run first; the judge never re-checks
+what a string-compare catches.
+
+Ultra lane ONLY. No `/orc-judge` command; the orchestrator dispatches
+`orc-judge-opus-5-xhigh` at the three ultra gates.
+
+## Hard rules
+
+1. **The orchestrator never judges — it spawns.** One agent, three contexts
+   (`gate=analysis|plan|implementation`).
+2. **Deterministic first.** A judge dispatch is only legal AFTER the gate's
+   deterministic checks passed (evidence spot-check + derivation lint /
+   coverage + graph checks / verify + traceability matrix + static analysis).
+3. **The judge is read-only** and blind to the author's internal reasoning or
+   self-assessment (anti-anchoring): it sees the artifact, its evidence, the
+   advisor brief + rubric, and the original request.
+4. **Judge gates ADD to user sign-offs, never replace them.** Gate approvals
+   never skip the analyst challenge round or the plan sign-off.
+5. **Gate scope is one-directional.** gate=plan takes the approved spec as
+   fixed ground truth; gate=implementation takes the approved plan as fixed —
+   no gate re-litigates an earlier approved gate.
+6. **The judge never fixes.** Authors fix: analyst (gate=analysis), planner
+   (gate=plan), a scored executor fix wave (gate=implementation).
+
+## Verdict handling (orchestrator side)
+
+Validate the return against the agent's verdict contract, then:
+
+- **Downgrade enforcement:** any blocking finding missing its verbatim
+  anchor or its class-appropriate justification (failure_consequence for
+  correctness/security; named category + concrete alternative for
+  smell/simplification/placement) → downgrade to advisory and tell the user.
+  EXCEPTION: a security finding with a concrete consequence is always
+  blocking — never downgraded.
+- **APPROVE** → record the verdict artifact, continue the pipeline.
+- **REVISE** → re-dispatch the author with the original slice + the blocking
+  findings verbatim. The author's return must echo `finding_id → resolution`
+  per finding; a missing echo is a malformed return (requeue). Then RE-JUDGE
+  under the convergence rule: block only on unresolved prior findings by id
+  or on lines the revision changed; new findings on untouched material are
+  advisory-only. **Hard cap: 2 revision loops per gate**, counted in the
+  checkpoint.
+- **ESCALATE** (or a third failure) → present the ESCALATE menu:
+  accept-and-proceed (unresolved findings recorded in the Phase 7 summary) /
+  user fixes manually then re-judge (does not consume a loop) / grant one
+  extra loop / stop-and-checkpoint.
+- Advisory findings NEVER loop — they ride forward attached to the next
+  phase's slices as notes.
+- Persist every verdict as `run/{run-slug}/ultra/verdict-<gate>-<round>.md`
+  (mined by /orc-retro; survives resume). When logging, emit
+  `JUDGE <gate> <verdict>` and the judgment GATE line (pass|bounce|escalate).
+
+## The three gates
+
+| Gate | After | Judges | REVISE target |
+|------|-------|--------|---------------|
+| analysis | analyst-return deterministic gates | scope interpretation, requirement coherence, rubric misses, stale-doc risk | analyst |
+| plan | Phase 1 exit gate + blast-radius map | decomposition, declared-file plausibility, deps, right-sizing, blast-radius coverage | planner |
+| implementation | Phase 6/6.5 + traceability matrix + static analysis | fidelity to the user's ask + ultra-strict quality (security, smells, simplification, placement, pattern invariants) | scored executor fix wave → re-verify → re-judge |
+
+Return fields include `actual_model` + `actual_effort` (standard
+claimed-vs-actual check) and `rubric_items_checked[]` +
+`unconfirmed_assumptions_touched[]` — validate them like any worker return.

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

@@ -0,0 +1,156 @@
+---
+name: orc-learn
+description: >
+  Per-feature onboarding docs for the LOCAL project. Use for "/orc-learn",
+  "help me learn feature X", "onboard me to this feature", or "orc-learn
+  refresh". Runs INDEPENDENTLY — no orchestrator, no run folder. Picks one
+  feature (wiki topics first), then generates learning-docs/<feature>/ with
+  learning.md (pedagogy: mental model, walkthrough, recipes, FAQ) and
+  knowledge.md (reference: file:line-anchored functions & flow, contracts,
+  fingerprints). Output is LOCAL and git-ignored — each dev regenerates their
+  own. Refresh lists every generated feature with a computed freshness flag
+  and regenerates only what the user picks. The skill dispatches the pinned
+  orc-learn-writer-opus-5-low agent — it never writes the docs itself.
+---
+
+# ORC-LEARN (standalone)
+
+Teach a developer ONE feature of the local repo well enough to safely extend
+it — the human-onboarding lane. It is NOT the wiki: the wiki grounds the
+*pipeline* (repo-wide, contract-level); orc-learn goes one level deeper for a
+*person* — function-level, full-flow, pedagogical. Target is always
+`<repo root>/learning-docs/<feature-slug>/` (git-ignored, local per dev).
+
+**Dispatch, don't do.** Whatever model this chat runs on, the skill only picks
+the topic/mode and spawns `orc-learn-writer-opus-5-low` (the pinned
+engine) — the deepening scan + all writes run at Opus 5 low regardless of
+the caller's tier. The skill's only self-writes are the behavior-trace
+markers around the spawn. Interactivity is DELIBERATELY minimal but non-zero
+(unlike orc-claude): exactly one question per mode — "which feature?" (INIT)
+or "which to refresh?" (REFRESH). Never more.
+
+**Grounding precedence** (constellation rule, unchanged):
+`code > fresh wiki > stale wiki (hints) > model priors`. The writer re-verifies
+every wiki claim it uses against the code; on conflict the code wins.
+
+**Worked example** (orient only — never execute from it):
+`examples/learn-run-mock.md`.
+
+## The two modes (auto-selected by argument)
+
+1. **INIT** (default: `/orc-learn`, optional `focus=<hint>`) — pick ONE
+   feature, generate `learning-docs/<slug>/learning.md` + `knowledge.md`,
+   derive `learning-docs/INDEX.md`.
+2. **REFRESH** (`/orc-learn refresh`) — list every generated feature with a
+   computed freshness flag; regenerate only the ones the user picks.
+   Protocol: `references/refresh.md`.
+
+Not inside a git repo / no project root findable → say so and stop.
+
+## Mode A — INIT
+
+Behavior-trace logging is permanent (always on). Resolve `log_dir`
+(`../orc/config.md` default + `.claude/orc.config.yaml`) at start and follow
+`../orc/references/trace-protocol.md`; the marker set is in "Behavior trace"
+below. Weave the **Trace:** steps in as each event happens.
+
+1. **Topic pick (wiki-first).** Read `wiki/INDEX.md` +
+   `.claude/orc/wiki-meta.json` and compute the freshness tier
+   (`../orc-wiki/references/staleness.md` — computed on read, never stored).
+   **Trace:** `WIKI-CONSULT tier=<FRESH|AGING|STALE|none> :: topic-pick`
+   (emitted even when the wiki is absent, with `none`).
+   - Wiki FRESH/AGING → present its feature areas as a pick-list; the chosen
+     area's `covers` globs seed the writer's file set.
+   - No wiki / STALE / topic not covered → ask the user to point at the
+     feature (a directory or a `focus=` hint); the writer will do a
+     **targeted** scan of just those files — never repo-wide. A stale wiki
+     doc may still ride along as hints (precedence above).
+   - Ask which feature as ONE question (one feature per invoke). Derive
+     `feature_slug` (kebab-case) from the chosen topic/area.
+2. **Trace:** write `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+   `touch the trace file` of that name in the SAME step, BEFORE the spawn (a
+   pointer to a missing file reads as dangling and the hook rotates away).
+3. Spawn `orc-learn-writer-opus-5-low` with: `mode=init`, `repo_root`,
+   `feature_slug`, `topic_area`, `covers[]` (from wiki or user pointer),
+   `wiki_tier`, `focus_hint|null`, and the paths to
+   `references/deepen.md`, `references/template-learning.md`,
+   `references/template-knowledge.md`. **Trace:**
+   `DISPATCH orc-learn-writer :: init <slug> expect=opus-5/low` just
+   before the spawn (the hook adds `SPAWN`/`RETURN` on its own).
+4. On return, check `actual_model`/`actual_effort` against the pinned tier —
+   mismatch → prepend a tier-downgrade warning to the report. **Trace:**
+   `VERIFY writer actual=<model>/<effort> ✅ MATCH` (or
+   `⛔ DOWNGRADE expected=opus-5/low`).
+5. Relay the writer's report verbatim. If `learning-docs/` is not in
+   `.gitignore`, offer the line (`learning-docs/`) — append only on an
+   explicit yes; never edit silently. **Trace:** `FINISH :: init <slug>`,
+   then delete `log_dir/.current`. Stop. The skill NEVER writes the docs
+   itself — not even a "trivial" INDEX touch.
+
+## Mode B — REFRESH
+
+1. No `learning-docs/` (or no feature folders inside) → "nothing generated
+   yet; run `/orc-learn` first." Stop — no trace run needed.
+2. Read every `learning-docs/<feature>/knowledge.md` fingerprint header
+   (`source_commit` + per-file hashes) and compute FRESH/AGING/STALE per
+   feature — `references/refresh.md`. Freshness is computed on read, never
+   stored as a status.
+3. Present the FULL list, each with its computed flag; the user
+   multi-selects which to regenerate (one question, multi-select). Nothing
+   selected → stop, no writes.
+4. **Trace:** write `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt`. For each
+   selected feature, spawn the writer with `mode=refresh` and that feature's
+   slice (re-deepen just that feature; a FRESH/AGING wiki may again seed the
+   boundary — emit one `WIKI-CONSULT tier=<tier> :: refresh` when the wiki is
+   read). One `DISPATCH`/`VERIFY` pair per feature, same markers as INIT.
+5. The (last) writer re-derives `learning-docs/INDEX.md` from all current
+   feature headers. Relay the combined report. **Trace:**
+   `FINISH :: refresh <n> features`, then delete `log_dir/.current`.
+
+## Behavior trace (PERMANENT — minimal dispatch-lane protocol; always on)
+
+orc-learn owns the trace for its run like every trace-owning lane, but it is
+a dispatch-only lane: it emits ONLY markers it can truthfully witness — no
+phase/score/finding/verdict markers (deepening and writing happen inside the
+writer, which self-traces nothing and only returns `actual_model`/
+`actual_effort`). The marker set, in order (actor `orc`, plus the hook's
+`SPAWN`/`RETURN`):
+
+1. `WIKI-CONSULT tier=<tier> :: <topic-pick|refresh>` — at every wiki read
+   (orc-learn is a wiki-grounding lane; the consult is always traced, absent
+   wiki included).
+2. `log_dir/.current` = `run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt` — before the first spawn.
+3. `DISPATCH orc-learn-writer :: <mode> <slug> expect=opus-5/low` — one
+   per spawn; REFRESH runs one per selected feature.
+4. `VERIFY writer actual=<model>/<effort> ✅ MATCH` or
+   `⛔ DOWNGRADE expected=opus-5/low` — from the returned
+   `actual_model`/`actual_effort` (this lane's honesty signal for
+   `/orc-retro`).
+5. `FINISH :: <init <slug>|refresh <n> features>`, then delete `.current`.
+
+Narration is **dispatched, never remembered**: record each marker with its REAL
+timestamp as its event happens, then — as a single-dispatch lane — dispatch the
+trace writer ONCE with the whole event list plus `decisions` (the WHY: which
+feature was picked and why, the user's answer verbatim) after the writer return
+validates and BEFORE you delete `.current`. Stamps are the run's timeline, never
+the write time, and a run that
+ends with zero new trace lines is a protocol violation.
+
+## Boundaries
+
+- **Writes ONLY** under `learning-docs/` (via the writer) and, on an explicit
+  yes, one `.gitignore` line. Never edits source code, never commits, never
+  pushes.
+- **One question per mode, ever.** Which feature (INIT); which to refresh
+  (REFRESH). Everything else is decided or reported, never asked.
+- `learning-docs/` is LOCAL — git-ignored, regenerated per dev, never a
+  committed shared artifact. A stale copy costs one regeneration, nothing
+  more.
+- `INDEX.md` is DERIVED by the writer from the feature headers in the same
+  dispatch — never hand-maintained, never edited by the skill.
+- The wiki is consumed read-only as a boundary source; orc-learn never
+  writes wiki files, never triggers a wiki scan, never treats "not in the
+  wiki" as a blocker (it falls back to a targeted scan of user-pointed
+  files).
+- Reminder: to see usage limits, tell the user to run `/usage` (never invoke
+  it programmatically).

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

@@ -0,0 +1,61 @@
+# Worked example — orc-learn runs (mock; orient only, never execute from this)
+
+## Run 1 — INIT with a fresh wiki
+
+U: /orc-learn
+C: Repo root found. Reads wiki/INDEX.md + the wiki manifest → tier FRESH.
+   Presents the wiki's feature areas; user picks "orders". Slug: `orders`.
+   Spawns orc-learn-writer-opus-5-low with mode=init, covers from the
+   orders doc's globs (the skill never writes the docs itself).
+W: Reads the orders wiki doc for boundary + contracts, re-verifies against
+   code. Deepens: maps 14 functions (file:line), traces one real flow —
+   POST /orders → validate (routes/orders.ts:31) → price (pricing.ts:88) →
+   persist (repo/orders.ts:15) → emit event → 201. Harvests 3 invariants,
+   4 why-this-way findings, 2 couplings.
+W: Writes learning-docs/orders/knowledge.md (fingerprint header:
+   source_commit=HEAD, 9 hashed files; functions & flow; contracts; verify
+   commands from the wiki manifest's `commands`) and learning.md (mental
+   model, walkthrough of the SAME flow, 3 change recipes, gotchas, FAQ ×6).
+   Derives learning-docs/INDEX.md. Returns functions_mapped=14,
+   flow_traced=true, faq_count=6, actual_model=claude-opus-5,
+   actual_effort=low.
+C: Relays the report. `learning-docs/` not in .gitignore → offers the line;
+   user accepts → appended.
+
+## Run 2 — INIT, no wiki
+
+U: /orc-learn focus=src/billing
+C: No wiki/ → tier none (traced all the same). Asks only to confirm the
+   feature ("billing", from the focus pointer). Writer does a TARGETED scan
+   of src/billing/** only — never repo-wide — then deepens and writes the
+   pair as above.
+
+## Run 3 — REFRESH, multi-select
+
+U: /orc-learn refresh
+C: Reads each learning-docs/*/knowledge.md header; computes tiers on read:
+   orders STALE (drift hit pricing.ts), billing FRESH. Shows BOTH with
+   flags; user picks orders only. One writer dispatch regenerates the orders
+   pair (new source_commit, recomputed hashes, changelog line), re-derives
+   INDEX.md. billing: byte-untouched.
+
+## Run 4 — behavior trace (permanent, always on)
+
+The skill writes the run pointer (`run-learn-<slug>-<DDMMYY>-<HHMMSS>.txt` into
+`log_dir`) before the spawn, records these events as they happen, and — as a
+single-dispatch lane — dispatches the trace writer ONCE at run end to append
+them (`SPAWN`/`RETURN` come from the `orc-trace.js` hook as they occur):
+
+```
+[170726 10:02:01.050] writer   WIKI-CONSULT tier=FRESH :: topic-pick
+[170726 10:02:44.310] writer   DISPATCH orc-learn-writer :: init orders expect=opus-5/low
+[170726 10:02:44.420] hook     SPAWN orc-learn-writer-opus-5-low
+[170726 10:06:12.900] hook     RETURN
+[170726 10:06:13.010] writer   VERIFY writer actual=claude-opus-5/low ✅ MATCH
+[170726 10:06:13.120] writer   FINISH :: init orders
+```
+
+Then the writer packet returns and the run pointer is deleted (in that order).
+REFRESH traces one DISPATCH/VERIFY pair per
+selected feature, ending `FINISH :: refresh <n> features`. No phase/score/
+finding/verdict markers — this lane runs none of those phases.