@azure-id/orc 0.55.0

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

@@ -0,0 +1,165 @@
+---
+name: orc-route
+description: >
+  Plan-only lane router — you have a plan, this tells you which lane should build
+  it. Use for "/orc-route", "which lane for this plan?", "is this worth the full
+  orc run?". It reads the plan's own numbers (tasks, waves, files, top score,
+  risk) plus ORC's deterministic knowledge probes, then names ONE recommended
+  lane, the runners-up with the reason each lost, and any lane that is not
+  possible with the blocking condition named. It routes a PLAN and nothing else —
+  given a request in words it refuses and says why, because routing from a
+  sentence is guessing. Zero agents, user-invoked only, nothing is built.
+---
+
+# ORC-ROUTE
+
+**This is not a general "which command should I use" helper.** It only works on a
+plan, on purpose.
+
+A plan contains real numbers — tasks, the files each task touches, dependencies,
+facets, scores. A sentence like *"add notifications"* contains none of them.
+Routing from a plan is arithmetic. Routing from a sentence is guessing, and a
+guess that looks like a calculation is worse than no answer.
+
+The newcomer's "which of these commands do I type?" is answered by
+`orc onboarding first-run`, not here. That is the trade: a narrow tool that is
+always right, instead of a broad one that is sometimes wrong.
+
+## Input contract — reuse, never reinvent
+
+A valid input is **exactly** what `../orc/references/plan-handoff.md` already
+defines as a plan input:
+
+- pasted planning-output (a block matching `../orc/schemas/planning-output.md` —
+  a `tasks:` list with `declared_files`, `depends_on`, `grounding[]`);
+- a `plan-{name}.md` path the user points at;
+- an `orc/planner/{name}/` checkpoint (the planner's "Save & stop" artifact).
+
+Load that reference and use its definition — do NOT write a second one here. A
+second definition of "what counts as a plan" is drift the contract lint cannot
+see, and the two would eventually disagree about the same file.
+
+Schema-validate against `../orc/schemas/planning-output.md`. A structurally
+malformed plan is not a routing question: say which field is missing and point at
+`/orc-plan`.
+
+## Refusal — anything that is not a plan
+
+Do not guess. Do not quietly downgrade into a general suggestion box.
+
+```
+This is not a plan, so I cannot route it.
+
+I can only route a plan — a pasted ORC plan, a plan-<name>.md file, or a saved
+planner checkpoint. What you gave me is a request in words.
+
+Make a plan first with /orc-plan, then come back here.
+```
+
+If the input is a plain request AND the user seems unsure what they even want,
+you may add ONE line offering `/orc-grill` first. Offer it; never run it.
+
+## What it reads
+
+Only the plan, plus the deterministic probes ORC already ships — **never an
+ad-hoc `find`**, per `../_shared/detecting-artifacts.md`:
+
+| Probe | Tells you |
+|---|---|
+| `orc wiki status` | wiki tier — the `/orc-fast` prerequisite |
+| `orc pattern status <lang>` | cached code-pattern — the other `/orc-fast` prerequisite |
+| `orc gotcha status` | whether this project has repair memory for the area |
+| `orc diy status` | exit 0 = a compiled custom flow exists and is READY |
+
+Signals taken from the plan itself: task count, wave count, total distinct files
+in `declared_files`, the top facet score, whether any task carries a **cited**
+`risk[]`, and whether `plan_confidence` is low.
+
+Read nothing else. This lane opens no source file.
+
+## How it decides
+
+Not a formula to hide behind — these are the real discriminators, in order:
+
+1. **Hard gates first.** A lane whose prerequisites fail is `not possible`, not
+   "runner-up". `/orc-fast` needs a FRESH or AGING wiki **and** a cached pattern
+   **and** a single-task plan — it runs ONE task, **and (v0.46.0) a plan carrying
+   any boundary REFUSE can never route there**: fast has one executor and no wave
+   to lift the refused task out of, so the gate has nowhere to act. `/orc-diy`
+   needs `orc diy status` to exit 0.
+2. **Risk beats size.** Any task with a cited `risk[]`, or `plan_confidence:
+   low`, recommends `/orc` — review and verify are what you are paying for, and
+   a small risky change is exactly the case that earns them.
+3. **Then size.** Roughly: 1 task with both `/orc-fast` gates green → `/orc-fast`;
+   1–3 tasks, no risk, one wave → `/orc-mini`; anything multi-wave, or a top
+   score in the high bands, or more than a handful of files → `/orc`.
+4. **`/orc-ultra` is never a default.** Name it only when the plan itself
+   justifies maximum rigor (cited risk on more than one task, or a security-
+   surface plan), and say plainly that it costs the most.
+
+State the numbers you decided from. A recommendation without its evidence cannot
+be argued with, and the user is the one who knows whether the risk is real.
+
+**Cost, when it is knowable (v0.46.0).** Run `orc budget forecast <plan> --json`
+and add ONE cost column per lane, in the primary unit `budget_units` resolves to.
+Routing stops being qualitative the moment "about 3x faster" becomes "1.23M vs
+0.41M raw, 18% vs 6% of a 5-hour window". Two rules ride with it: a band below
+`budget_min_samples` makes the number a FLOOR and the column says so, and **exit 3
+(no history) means the column is simply absent** — never a guessed figure, and
+never a reason to withhold the recommendation itself, which does not depend on
+cost.
+
+## Output shape
+
+```
+Plan: merchant-notifications — 7 tasks, 3 waves, 14 files touched
+      top score 78, two tasks marked risky
+
+→ /orc          the plan has risky tasks and a task above 70;
+                review and verify are worth paying for here
+                1.23M raw · 18% of a 5-hour window on Max 20x
+   runner-up    /orc-mini — about 3x faster and 0.41M raw (6% of a window),
+                but it skips full review and verification. Fine only if you
+                will read the diff yourself.
+   not possible /orc-fast — needs a fresh wiki (yours is STALE) and this plan
+                is 7 tasks; that lane runs ONE task. It also carries 1 boundary
+                REFUSE, which fast has no wave to lift out.
+
+Start /orc now?  [yes / no]
+```
+
+Rules for that block:
+
+- **Every runner-up names what it costs you**, not just that it is cheaper.
+- **Every `not possible` names the blocking condition AND its fix** ("run
+  `/orc-wiki` to refresh"). A blocked lane with no stated fix is a dead end.
+- **The final offer starts the recommended lane.** `no` ends the run cleanly.
+
+## Second entry point — one question after "Save & stop"
+
+`../orc/subskills/orc-planner/SKILL.md` ends in a three-way branch. On **Save &
+stop** ONLY, it asks:
+
+> Want a lane recommendation for building this? [yes / no]
+
+*Take into build* never asks — the lane is already chosen and running. *Poly
+split & stop* never asks — it has its own per-repo handoff. One question, in
+exactly one branch.
+
+## Behavior trace (always on — same as every lane)
+
+Follow `../orc/references/trace-protocol.md`. Lane name `route`. Single-dispatch
+tier: **exactly ONE end-of-run packet** to `orc-trace-writer-haiku-4-5`, solo,
+after the offer is answered and BEFORE `log_dir/.current` is deleted. Run start
+writes `log_dir/.current` = `run-route-<slug>-<DDMMYY>-<HHMMSS>.txt` AND
+`touch the trace file` of that name in the SAME step. The packet carries the
+probe results, the signals read from the plan, the recommendation, and — as
+`decisions` — why the runners-up lost. A run that ends with
+`zero new trace lines is a protocol violation`.
+
+## Rules this lane always keeps
+
+Routes a plan, refuses anything else · zero agents, nothing dispatched · reuses
+`plan-handoff.md`'s plan definition, never a second one · deterministic probes
+only, never an ad-hoc `find` · reads no source file · never starts a lane the
+user did not accept · never edits config or any project file.

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

@@ -0,0 +1,86 @@
+---
+name: orc-verify
+description: >
+  Standalone verification for ORC. Use for "verify my changes",
+  "/orc-verify", or "check the modified files". Runs INDEPENDENTLY —
+  no orchestrator, no planning, no run folder required. Verifies only the
+  git-modified changes in the working tree and shows a summary of results. Uses
+  Opus 5 medium effort. Read-only: it reports, it does not fix or commit.
+---
+
+# ORC-VERIFY (standalone)
+
+A focused, dependency-free verify pass. No intake, no planning, no checkpoint —
+you point it at your uncommitted work and it tells you what's wrong.
+
+Run as Opus 5, medium effort.
+
+**Worked example** (orient only — never execute from it): `examples/verify-mock.md`.
+
+## Procedure
+
+1. **Gather the change surface** from git: `git diff --name-only` (unstaged +
+   staged) and, if useful, `git diff` for the actual hunks. Scope is ONLY the
+   modified/added files — do not review the whole repo.
+2. **Detect the stack** (package manager, test runner) from the repo.
+   If a cached pattern exists for a changed file's language — test it with the
+   deterministic probe `orc pattern status <lang>` (exit 0 = cached; see
+   `../_shared/detecting-artifacts.md`, never an ad-hoc `find` for
+   `.claude/orc/patterns/<lang>-pattern.md`) — read its Invariants +
+   Validation-gate sections and check the diff against them too (an invariant
+   violation or unmet enforceable gate line is P0). No cached pattern → skip
+   silently, never codify from here.
+3. **Verify the changes:**
+   - Run the build if one exists; capture failures.
+   - Run the tests that cover the changed files (or the full suite if scoping
+     isn't clean); capture failures.
+   - Check the diff for obvious breakage: broken imports, references to removed
+     symbols, unhandled errors introduced, type errors.
+   - **Adversarial pass (v0.33.0):** attack the diff the way the pipeline's
+     Phase 6 does — edge cases the change ignores (empty/zero/max, unicode),
+     error paths (each external call's failure), contract violations (response
+     shapes/status codes vs consumers), race/ordering on shared state, and
+     workflow breaks (dead wiring, broken commands). Same evidence rule.
+4. **Classify findings** on the P0–P3 severity ladder (same rule as the full
+   skill: P0 = failing build/tests, broken references, runtime errors ·
+   P1 = correctness/security risk · P2 = maintainability · P3 = cosmetic).
+   P0/P1 mean NOT ready to commit; P2/P3 are advisory. **Evidence-or-advisory
+   (same rule as the full pipeline):** every P0–P2 finding carries `file:line`
+   + the offending line(s) quoted VERBATIM from a file read this session; a
+   finding that can't be anchored is AUTO-P3 and never gates the verdict.
+5. **Show a summary** and STOP. This skill does not fix, stage, or commit.
+
+## Output (summary)
+
+```
+ORC-VERIFY — <n> files changed
+Build: <pass/fail/none>   Tests: <x/y passing>
+P0/P1 (gate — fix before commit):
+  - <P0|P1> <file:loc> <issue>
+P2/P3 (advisory):
+  - <P2|P3> <file:loc> <issue>
+Verdict: <READY / NEEDS FIXES>
+```
+
+## Behavior trace (PERMANENT — every ORC entry point traces; always on)
+
+Standalone verify traces too — appended as each event happens, never batched
+at the end (a phase ending with
+`zero new trace lines is a protocol violation`). Resolve `log_dir`
+(`../orc/config.md` default + `.claude/orc.config.yaml`) at start and follow
+`../orc/references/trace-protocol.md`: write
+`log_dir/.current` = `run-verify-<slug>-<DDMMYY>-<HHMMSS>.txt` and
+`touch the trace file` of that name in the SAME step, first. Narration
+is dispatched, not remembered: collect `PHASE` lines, `FINDING p0=… p1=… p2=…
+p3=…`, `VERDICT pass|fail` and `FINISH` with their REAL timestamps plus
+`decisions` (the WHY), dispatch the trace writer ONCE at run end (the
+single-dispatch-lane packet), then delete `.current` (the hook bootstraps
+`.current` + the skeleton on dispatch regardless).
+
+## Boundaries
+
+- **Read-only.** Never edit, stage, commit, or push. Report only.
+- **Independent.** Requires no orchestrator, no run folder, no intent-spec.
+- If there are no git changes, say so and stop.
+- Reminder: to see usage limits, tell the user to run `/usage` (never invoke it
+  programmatically).

package/templates/skills/orc-verify/examples/verify-mock.md

@@ -0,0 +1,33 @@
+# Example — Annotated Standalone Verify (dry run)
+
+V: = verifier (Opus 5 medium) · U: = user. Nothing real. Runs INDEPENDENTLY — no
+orchestrator, no planning, no run folder. Read-only: it reports, never fixes or commits.
+
+U: /orc-verify
+
+## Scope — git-modified changes only
+V: [git status/diff] 3 modified files: api/routes/orders.py, api/schemas.py,
+   tests/test_orders.py. Nothing staged beyond the working tree — verifying exactly
+   these changes (no repo-wide sweep).
+
+## Build + tests
+V: [detects Python/poetry/pytest]
+   $ poetry run pytest tests/test_orders.py  → 11 passed
+   $ poetry run mypy api/                     → clean
+   Build/type/test: GREEN.
+
+## Diff sanity + findings (P0–P3 ladder)
+V: Walks each hunk against intent inferred from the diff (every P0–P2 finding
+   anchored: file:line + the offending line quoted VERBATIM, else auto-P3):
+   ⛔ P1  api/routes/orders.py:42 — quote: `async def get_order(order_id: str):`
+      — new `/orders/{id}` route has no auth decorator; every sibling route
+      uses `@require_auth`. Security risk — likely unintended.
+      (Not P0: build/tests are green.)
+   • P3  api/schemas.py:18 — field `createdAt` breaks the snake_case convention
+      used elsewhere (`created_at`).
+   • P2  tests/test_orders.py — no negative-path test for a missing id.
+
+## Summary (read-only — no edits, no commit)
+V: 1 P1, 1 P2, 1 P3. Tests green but the missing auth decorator gates the
+   commit (P0/P1 = fix before commit; P2/P3 advisory). I don't edit or commit —
+   hand this to /orc or fix manually, then re-run /orc-verify.

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

@@ -0,0 +1,325 @@
+# orc-wiki
+
+Builds and maintains a persistent, evidence-anchored project knowledge base (the
+**wiki**) under project-root `wiki/`, plus a cross-repo **crosslink** subsystem.
+Skill mechanics live in `SKILL.md`; freshness in `references/staleness.md`;
+integrity in `references/integrity-check.md`; doc shape in `schemas/wiki-doc.md`;
+crosslink mechanics in `references/crosslink.md`.
+
+## What the wiki is
+
+`/orc-wiki` scans the codebase with Opus 4.8 high and writes `wiki/orc-feature-*`,
+`wiki/orc-reference-*`, and `wiki/orc-architecture-overview.md`, an `INDEX.md`, and
+the machine manifest `.claude/orc/wiki-meta.json`. Future ORC runs consult it —
+precedence `code > fresh wiki > stale wiki (hints) > model priors`. Freshness is
+computed on read (git commit distance), never stored. Expensive and often
+multi-session — it always warns and gets consent before scanning.
+
+## Two halves: docs and registration
+
+- **Docs** (`wiki/*.md`) — prose. Written by the skill's scan agents, because it
+  takes a model to read code and summarize it. This is the expensive half.
+- **Registration** (`wiki/INDEX.md` + `.claude/orc/wiki-meta.json`) — the index
+  and manifest that make the docs *findable*. Every field is derived from the
+  docs' own headers, so the **`orc wiki sync` CLI** writes it: instant, free,
+  deterministic. No model is ever involved.
+
+```bash
+orc wiki                 # registration state: registered / UNREGISTERED / corrupt / out of sync
+orc wiki sync            # (re)build INDEX.md + wiki-meta.json from the docs on disk
+orc wiki sync --check    # read-only; exit 1 if registration doesn't match the docs
+```
+
+**If ORC or `orc crosslink` says it can't see your wiki, run `orc wiki sync` —
+not a re-scan.** A wiki with docs but no manifest is UNREGISTERED, not missing:
+the docs are fine, nothing indexed them. This is common and expected, because
+`/orc-wiki` pauses every 5 areas by design, and a run stopped at a pause never
+reached its assemble phase. Sync fixes it in a second, for free; re-scanning
+buys you docs you already have. `/orc-wiki` also detects this on entry and
+offers the repair without any scan.
+
+---
+
+# Cross-repo crosslink — the complete guide
+
+## Why you'd want this
+
+You have more than one repo, and they talk to each other:
+
+- a **backend** that a **frontend dashboard** calls over HTTP, or
+- a **backend** that calls **another service** over gRPC (maybe several).
+
+Each repo's wiki only knows *its own* code. So when you ask ORC to build a new
+gRPC call from `service-a` to `service-c`, it has no idea what `service-c`'s
+`CreateInvoice` actually expects — it guesses the field names. **Crosslink fixes
+that:** it lets `service-a`'s wiki read `service-c`'s wiki *at the exact boundary*
+so the executor builds against the real contract.
+
+**The one rule that makes it safe:** crosslink is **advisory and never blocking**,
+and it only ever **reads** another repo's *wiki* — never its source code, and it
+never writes anything in the other repo. If a linked repo is missing, un-scanned,
+or out of date, you just get a warning and less context — your build never stops.
+
+## The mental model (30 seconds)
+
+1. Every repo **publishes** its own boundary (its endpoints / gRPC methods) as
+   small per-point "tag" files when you scan it — automatically.
+2. You **draw the graph** once with a CLI: "this repo calls that one over gRPC."
+3. ORC **connects the dots**: when a task touches a boundary, it hands the
+   executor the linked repo's real contract as a hint.
+
+You do step 2 (coarse: which repos, which way). The machine does the rest.
+
+## Before you start
+
+- ORC installed in **each** repo you want to link (`orc init`).
+- The repos checked out as **siblings** (or anywhere reachable by a relative
+  path), e.g. `~/code/service-a`, `~/code/service-c`, `~/code/dashboard`.
+- A terminal open in the **consuming** repo (the one that calls the others).
+
+---
+
+## Step 1 — give every repo a wiki
+
+In **each** repo, run:
+
+```
+/orc-wiki
+```
+
+Besides the normal knowledge base, a scan also **publishes that repo's
+boundary**: one small per-point tag file per endpoint / gRPC method under
+`wiki/crosslink/<kind>/<slug>.md`, plus a `crosslink_provided` list in that
+repo's `.claude/orc/wiki-meta.json`. This is **always on and happens per
+scan-task**, in the same pass as the docs — whether or not anyone links to you
+yet, so you never coordinate timing between teams. Every later scan/refresh
+re-publishes in the same pass, and a refresh **never deletes** your tags
+(a vanished endpoint is retired one-at-a-time, and only with your say-so).
+
+> A repo with no outward boundary simply publishes nothing (each scan-task
+> records that explicitly). That's fine.
+
+### Old wiki with no tags? Backfill — don't re-scan.
+
+A wiki built **before v0.24.0** has docs but no `wiki/crosslink/` folder, because
+publishing used to happen only at the end of a scan (so a run that stopped at one
+of the 5-area pauses never reached it). The boundary is already described in your
+docs' evidence-anchored `Contracts & shapes` rows, so recovering it needs no repo
+scan:
+
+```
+/orc-wiki crosslink
+```
+
+This is the **CROSSLINK-ONLY** legacy-backfill branch. It reads those rows, opens
+*only* the files they anchor to, writes the tag files, resolves what you consume,
+and indexes it all with `orc wiki sync`. It never re-scans an area, never rewrites
+a doc, and never touches coverage. **"No crosslink tags" is never a reason to pay
+for a refresh.**
+
+> On a wiki scanned at **v0.24.0 or later** you should never land here: tags
+> publish on every scan/refresh automatically. If `orc wiki status` says
+> `crosslink: UNPUBLISHED boundary` or `orc wiki sync --check` fails with
+> "boundary documented but no crosslink tags", run the backfill above — that's
+> the guard catching a gap, not a re-scan request.
+
+> **Run it in the repo being CALLED.** Tags are published by the *provider*, so
+> `no crosslink tags yet` about your backend is fixed in the **backend**, not in
+> the frontend you're standing in. Running it in the caller publishes the
+> caller's *own* surface — which for a typical frontend is nothing at all, since
+> a pure consumer exposes no API and correctly publishes zero tags. If both repos
+> call each other (e.g. backend webhooks into the frontend), run it in both.
+
+## Step 2 — draw the graph (in the consuming repo)
+
+From the repo that *calls* the others, run:
+
+```
+orc crosslink
+```
+
+You'll get a tiny menu:
+
+```
+ORC crosslink — self: service-a  ·  0 linked repo(s), 0 edge(s)
+  [1] add linked repo   [2] list   [3] remove   [4] done
+> 1
+```
+
+Adding a link walks you through five short prompts. Here's a real one — linking
+`service-a` to a gRPC dependency `service-c`:
+
+```
+  name for the linked repo (slug): service-c
+  repo path (repo ROOT, relative to this repo, e.g. ../service-z): ../service-c
+  ✓ wiki found · last_scan 11-07-2026 09:12:00 · FRESH · 8 tags
+
+  kinds this repo exposes/consumes (catalog):
+    1) grpc      2) rest-endpoint   3) graphql
+    ... (18 in the catalog, plus type your own)
+  pick (numbers and/or names, comma-separated): 1
+
+  direction?  [1] this repo CALLS them   [2] they CALL this repo
+  > 1
+
+  linked to which repo?
+   1) this repo (service-a)
+  > 1
+  ✓ added service-c  ·  edge self ──grpc──▶ service-c  (we consume → drift-checked)
+```
+
+What each prompt means:
+
+| Prompt | What to enter |
+|--------|---------------|
+| **name** | any short slug for the linked repo (`service-c`, `dashboard`) |
+| **repo path** | the linked repo's **root folder**, relative to this repo (`../service-c`) — not its `wiki/` folder |
+| **kinds** | how they connect — pick from the catalog (`grpc`, `rest-endpoint`, …) or type your own; "Other" is always allowed |
+| **direction** | `[1]` = *you* call them (you'll get drift-checked against their contract); `[2]` = they call you |
+| **linked to** | which repo is the other end — **option 1 is always this repo**; other repos you've added show up as 2, 3, … |
+
+**The freshness line after you paste the path is the important safety check.** The
+CLI reads the linked repo's `wiki-meta.json` right then and tells you:
+
+- `✓ wiki found · … · FRESH · 8 tags` — great, fully linked.
+- `⚠ no wiki-meta.json there — run orc-wiki in that repo first` — typo or you
+  skipped Step 1 there. The link is still saved (inert until they scan).
+- `✗ path not found — saved as a PENDING edge` — wrong path; fix it later, it
+  resolves automatically when the path exists.
+
+**Bulk-add (nice shortcut).** If the linked repo *already* declares a matching
+link back at you, the CLI notices and offers to mirror it:
+
+```
+  service-c also declares service-c ──webhook──▶ service-a — mirror it into your config? (y/n) y
+   ✓ mirrored
+```
+
+When you're done, pick `[4]`. On your first setup the CLI offers to add the
+derived cache folder to `.gitignore` — say yes.
+
+Everything you just did was written to **one file**: `.claude/orc-crosslink.config.yaml`.
+The CLI never touches the linked repo.
+
+## Step 3 — let ORC connect the dots
+
+Back in the consuming repo, run `/orc-wiki` once more (or your next scan/refresh).
+Now that the graph exists, orc-wiki walks your call sites and:
+
+- resolves the **exact** per-point contracts you depend on into
+  `.claude/orc/crosslink/needs.json` (you never hand-list endpoints), and
+- mirrors snapshots of those contracts into `.claude/orc/crosslink/cache/`
+  (gitignored) so they're available even when the other repo isn't checked out.
+
+That's it. You're set up.
+
+### One-shot alternative: `/orc-wiki crosslink compile`
+
+Once the graph exists (Step 2), `/orc-wiki crosslink compile` does the whole
+connect-the-dots pass in one command (v0.33.0): resolve/consume from the graph
+(refresh `needs.json` + `cache/`) → generate the federation **ATLAS** (below) →
+write the atlas into each linked repo → inject/update the CLAUDE.md pointer
+block locally **and in each linked repo** (in-place block update, user content
+byte-preserved; a peer with no CLAUDE.md gets a minimal file with only the
+block). Every step is warn-only on failure, never a re-scan, never a doc
+rewrite, and it ends with one summary line per repo touched. Hard
+precondition: `.claude/orc-crosslink.config.yaml` with ≥1 edge — missing/empty
+means it explains the `orc crosslink` CLI steps and stops.
+
+## The ATLAS — federation super-context (v0.33.0)
+
+`wiki/crosslink/atlas.md` is ONE repo-agnostic document describing the whole
+federation — every node, every edge (including transitive repos learned from
+peer atlases), what each repo provides/consumes, and **peek hints** (which of a
+repo's wiki docs answer which questions). The same document lives in EACH
+linked repo; a header records `generated_from`, the `generated` timestamp, and
+per-peer peek freshness. Freshness on read = `min(own wiki tier, oldest peek
+age)` — computed on read, never stored; across copies, **newest wins** (trust
+the newer `generated` stamp).
+
+It is regenerated at the end of every scan/refresh (derived + cheap — never a
+scan), and after writing the local copy the session **writes the same file into
+each linked repo** — this is a sanctioned peer FILE write (exception #2 in
+`references/crosslink.md`, next to orc-poly's handoff plan): never a commit,
+never a push, never any other peer path, and any failure warns and continues.
+`orc wiki sync` treats it as derived — never a registered doc, never
+bulk-deleted by a refresh.
+
+## Step 4 — check it worked
+
+```
+orc crosslink status
+```
+
+```
+Crosslink status — self: service-a, 1 linked repo(s), 1 edge(s)
+
+  service-c:
+    ✓ wiki found · last_scan 11-07-2026 09:12:00 · FRESH · 8 tags
+
+  needs baseline: .claude/orc/crosslink/needs.json (per-point tags orc-wiki resolved)
+```
+
+From now on, when you run `/orc`, `/orc-fast`, or `/orc-mini` and a task touches
+that gRPC boundary, the executor gets `service-c`'s real `CreateInvoice` contract
+handed to it as a hint — no more guessed field names.
+
+---
+
+## What lives where (after setup)
+
+| File | Who writes it | Committed? | What it is |
+|------|---------------|-----------|------------|
+| `.claude/orc-crosslink.config.yaml` | `orc crosslink` CLI (you) | yes | the graph you drew |
+| `wiki/crosslink/**` | `/orc-wiki` | yes | this repo's own published boundary tags |
+| `.claude/orc/crosslink/needs.json` | `/orc-wiki` | yes | the exact contracts you depend on (drift baseline) |
+| `.claude/orc/crosslink/cache/**` | `/orc-wiki` | **no** (gitignored) | mirrored snapshots of linked contracts |
+| `wiki/crosslink/atlas.md` | `/orc-wiki` (derived; also written into each linked repo) | yes | the federation atlas — repo-agnostic super-context |
+
+`orc update` never touches any of these.
+
+## Everyday use
+
+- **Drift warnings.** If a contract you depend on changes or disappears, the next
+  `/orc-wiki` scan warns you *by exact tag* (`grpc:billing.v1.CreateInvoice
+  changed under you`). It's a **warning only** — nothing is ever blocked.
+- **Keeping it current.** Re-run `/orc-wiki` (incremental refresh is cheap) in
+  the consuming repo to re-sync the cache and re-check drift.
+- **Freshness you can trust.** A linked hint is only used as fresh when *both* the
+  provider's wiki is fresh *and* your snapshot is recent — the weaker of the two
+  wins, and it's labeled "cross-repo hints, not verified". Local code always wins
+  over any cross-repo hint.
+
+## Troubleshooting
+
+| You see | What it means | Fix |
+|---------|---------------|-----|
+| `⚠ wiki found (N docs) but UNREGISTERED` | that repo's wiki is real and possibly complete — nothing ever indexed it (usually a scan stopped at a 5-area pause) | `orc wiki sync` in the linked repo — instant, free, **do not re-scan** |
+| `⚠ wiki-meta.json there is unreadable` | the manifest is corrupt JSON | `orc wiki sync` in the linked repo rebuilds it from the docs |
+| `⚠ no wiki there` | that repo genuinely has no docs | run `/orc-wiki` in the linked repo |
+| `✓ inbound only (they call us)` | that repo only *consumes* your API — you read nothing from it | nothing to do; its tags/freshness are irrelevant on your side |
+| `⚠ linked, but no edge yet` | you added the repo but never drew an edge | `orc crosslink` → add the edge; a node alone does nothing |
+| `✗ path not found — PENDING` | the repo path is wrong or not checked out | fix the path with `orc crosslink` (remove + re-add), or check the repo out |
+| `no crosslink tags yet (coarse hints only)` | that repo has wiki docs but never published its boundary — its scan stopped before the publish step, or its wiki predates crosslink | run **`/orc-wiki crosslink`** in that repo: publishes the tags from the docs it already has, no re-scan. (It also upgrades on that repo's next full scan — but don't pay for a scan just for this.) |
+| `tier unknown (git unavailable there)` | linked folder isn't a git checkout | freshness falls back to the snapshot date — still works |
+| executor didn't get a contract | the task didn't touch a linked boundary, or `needs.json` isn't built | run `/orc-wiki` in this repo to build the needs baseline |
+
+## The guarantees (why it's safe to adopt)
+
+- **Advisory, never blocking** — every failure degrades to a warning; your build
+  never stops on a cross-repo issue.
+- **Reads foreign *wiki* only** — never another repo's source. The whole
+  footprint is a few read-only wiki files + read-only git queries. The ONLY
+  writes into a peer are the two sanctioned file writes (the atlas +, via
+  `crosslink compile`, the CLAUDE.md pointer block) — file writes only, never
+  a commit or push, warn-only on failure.
+- **No cross-team coordination** — publish and consume are independent; a repo on
+  an older wiki gives you coarse hints today and precise ones for free the day it
+  re-scans.
+
+## Git hygiene
+
+Commit `.claude/orc-crosslink.config.yaml`, `.claude/orc/crosslink/needs.json`,
+and `wiki/crosslink/**`. Keep `.claude/orc/crosslink/cache/**` out of git — it's
+derived and regenerable. The `orc crosslink` CLI offers, once, to append the cache
+path to `.gitignore`; it never edits `.gitignore` silently.