@azure-id/orc 0.55.0

package/templates/skills/orc-wiki/references/partial-refresh.md

@@ -0,0 +1,203 @@
+# Reference — targeted refresh, the scan tier ladder, debt and usage (v0.46.0)
+
+Loaded when the user asks for a refresh, or when `/orc-wiki refresh …` is the
+entry. This is the half that makes a 2-line change cost 2 lines.
+
+## What already worked, and must not be rebuilt
+
+- `orc wiki impact` already classifies every doc `CLEAN | TOUCHED | STRUCTURAL`
+  against **its own** `scanned_commit`.
+- Delta refresh has been the default since v0.33.0.
+- `orc wiki sync` is free and CLI-only.
+- `computeWikiFreshness` already makes staleness coverage-relative.
+
+Nothing here replaces any of it. `orc wiki plan` sits ON TOP of `impact` and
+answers the question impact does not: **what to do about it, in what order, for
+how much.**
+
+## Free repairs ALWAYS come before anything that costs money
+
+A hard rule, in this order, every time:
+
+| # | Step | Cost | Fixes |
+|---|---|---|---|
+| 1 | `orc wiki sync` | free | UNREGISTERED / drifted registration |
+| 2 | regenerate `wiki/orc-orientation.md` | free | the derived doc every consumer reads first |
+| 3 | crosslink-only backfill | free | tags publishable from already-anchored rows |
+| 4 | targeted refresh | **money** | actual doc rot |
+
+**A user must never be able to pay for something a free step would have fixed.**
+`orc wiki plan` prints the available free repairs above the priced table; do the
+same in prose, and never offer step 4 while a step 1–3 is outstanding.
+
+## `orc wiki plan` — the ranked, priced work list
+
+Free, CLI, no model. Exit 0 nothing to do · 1 work pending, all light · 2 work
+pending, at least one deep · 3 cannot compute.
+
+**The ranking rule, and the reasons for it:**
+
+1. **`STRUCTURAL` always first.** A doc pointing at a file that no longer exists is
+   actively lying, and no cheaper step repairs it — a targeted refresh cannot
+   re-anchor blind, which is also why STRUCTURAL always takes the deep tier.
+2. **Then by use × delta**, where `used` is how many of the last 20 runs actually
+   put that doc into a slice. Refresh what gets read.
+3. **Zero-use docs sink to the bottom** with a retire hint. `used: ?` (no usage
+   data yet) is NOT zero-use and must never be ranked as dead.
+
+Render what the CLI returns. **Never compute the order, the tier or the estimate
+in this skill** — one engine, the same rule the wiki tier itself lives under
+(`../../_shared/detecting-artifacts.md`).
+
+## Targeted refresh
+
+```
+/orc-wiki refresh <doc>
+/orc-wiki refresh --only api/refunds/**
+/orc-wiki refresh --top 2
+/orc-wiki refresh --all-touched          (today's delta behaviour)
+```
+
+It **skips Phase 0 branch detection and Phase 1 area planning entirely** — the doc
+exists, so its coverage area is already in its own header. That skip is the whole
+saving in wall-clock terms.
+
+```
+R0  probe        orc wiki plan --json                       (free)
+R1  confirm      the doc, the delta, the TIER, the token + $ estimate. ONE turn.
+R2  scan         ONE scan-task, at the tier the ladder resolved
+R3  write        doc body + crosslink tags (unchanged — per-scan-task rule)
+R4  register     orc wiki sync                              (free)
+R5  integrity    the existing self-check, scoped to the touched doc
+```
+
+**No new pause mechanic.** The fixed pause every 5 scan-tasks still holds; a 1–2
+task refresh simply never reaches it.
+
+**Crosslink rules are unchanged:** tags publish per scan-task, no refresh path
+bulk-deletes `wiki/crosslink/`, and the dead-tag sweep still runs per point.
+
+## The scan tier ladder (`wiki_scan_tier`, default `ladder`)
+
+Every scan-task used to dispatch the most expensive scanner in the payload whether
+the delta was 2 lines or 2000. Five rows, in order, first match wins:
+
+| Condition | Tier | Agent |
+|---|---|---|
+| first scan of an area (no doc yet) | deep | `orc-wiki-scanner-opus-4-8-high` |
+| `STRUCTURAL` | deep | `orc-wiki-scanner-opus-4-8-high` |
+| ≥ `wiki_tier_deep_files` covered files touched (default 3) | deep | `orc-wiki-scanner-opus-4-8-high` |
+| a new exported symbol in a covered file | deep | `orc-wiki-scanner-opus-4-8-high` |
+| otherwise (small delta, no new surface) | **light** | **`orc-wiki-scanner-sonnet-5-high`** |
+
+- **`opus5_only` needs no new pair.** It already forces the wiki scanner to
+  `orc-wiki-scanner-opus-5-med`, which already ships, so **both tiers collapse onto
+  that one agent** while the flag is on. `OPUS5_ONLY_ROLES` gains no row and no
+  phantom pair — see `../../_shared/opus5-only.md`.
+- **`wiki_scan_tier: always_deep`** restores pre-v0.46.0 behaviour exactly.
+- **NEVER SILENT.** The resolved tier is printed in `orc wiki plan` and in the R1
+  confirmation. A cheaper model is a decision the user sees, never a quiet
+  substitution.
+- The light scanner escalates rather than under-delivers: a `needs_context` return
+  naming a new symbol or a missing anchor is re-run deep. That is cheap; a doc with
+  invented anchors is permanent.
+
+**Expected saving:** a delta refresh where 3 of 4 docs have a one-or-two-file delta
+goes from 4×deep to 1×deep + 3×light — roughly **40% off**, with the deep scan
+still doing the work that needs it.
+
+## Budget cap (`wiki_refresh_budget`, default 0 = no cap)
+
+Max scan-tasks per refresh run. A capped refresh is a **planned stop**, not an
+interrupt:
+
+```
+Refresh · budget reached
+  Done : 2 of 4 scan-tasks     Left : 2 tasks, est. 73k tokens / $0.14
+  orc wiki sync ran. The wiki is REGISTERED and consistent right now.
+  The two remaining docs are AGING, not broken.
+  Continue any time:  /orc-wiki refresh --top 2
+```
+
+Stopping mid-refresh must leave a VALID wiki. That already holds — sync runs after
+every scan-task and freshness is per-doc. This only makes the stop first-class.
+
+**It is a different mechanic from the fixed pause every 5 scan-tasks. Do not merge
+them.** The pause is a checkpoint you continue through; the budget is a ceiling you
+stop at.
+
+## `orc wiki debt`
+
+One line, for the habit: docs pending, tokens, dollars, oldest debt, tier, and the
+reassurance that matters — *nothing is broken*. Exit 0 no debt · 1 debt exists · 3
+no wiki.
+
+Inside `/orc`, one preflight tail **only when debt exists**:
+
+```
+wiki  : FRESH — 4 docs pending refresh, 335k tok / $0.94
+```
+
+**This is the real budget win** — not a cheaper full refresh, but a full refresh you
+never need.
+
+## `orc wiki usage` and retirement (`wiki_retire_after_runs`, default 0 = never)
+
+Since v0.41.0 every dispatch whose slice carried wiki material writes a `wiki:`
+continuation and every return carries `wiki_used`. Two releases of clean
+point-of-use attribution that nothing read back. `orc wiki usage --rebuild` reads
+it into `.claude/orc/wiki-usage.json`.
+
+> **Do NOT put usage in `wiki-meta.json`.** That manifest is 100% derived from doc
+> headers and `orc wiki sync` is its only writer — a load-bearing rule. Usage comes
+> from traces, so it gets its own file and its own writer.
+
+Three things it unlocks: the ranking above · honest coverage on `orc wiki status`
+(`14 registered · 8 in active use · 2 never used in 20 runs`) · and retirement.
+
+When `wiki_retire_after_runs` is non-zero and a doc has been in no slice for that
+many runs, OFFER retirement — never do it silently:
+
+```
+2 docs were never put into a slice in 20 runs. They cost money on every full
+refresh — and context tokens whenever they ARE included.
+Retire them? (moves to wiki/retired/, drops from INDEX.md and every plan.
+              Reversible. Never a delete.)
+```
+
+**Retirement MOVES, never deletes**, and `orc wiki sync` re-derives `INDEX.md`
+afterwards. A retired doc that turns out to matter is one `git mv` away.
+
+## The consent prompt gets a real number
+
+```
+Before: ⚠ This is an EXPENSIVE, possibly multi-session scan. Continue?
+After:  ⚠ Full scan: 14 areas, est. 2.1M tokens / $3.80 → $6.10, 25–40 min,
+          2 pause points, ~48% of a 5-hour window on Max 20x.
+          A targeted refresh of the 4 stale docs: 335k tokens / $0.94.
+          Continue with the full scan?
+```
+
+The numbers come from `/orc-budget`'s engine (`orc wiki plan --json` carries them).
+When there is no history yet, print `insufficient history` rather than a guess.
+
+## Later, opt-in: surgical section refresh — NOT in this release
+
+Noted so it is not re-invented. A doc's sections each anchor to files; in principle
+only the sections whose files changed need regenerating (~20% of the body). It
+waits because it needs the wiki-doc header parser to carry a section→file map — one
+of the GRAMMAR-shaped drift surfaces the contract lint cannot see — and because a
+partial body rewrite can break the integrity self-check's anchoring rule. If it is
+ever built: default off, and the integrity check still runs over the whole doc.
+
+## What must NOT change
+
+- `orc wiki sync` stays the only writer of `wiki-meta.json` + `INDEX.md`, and stays
+  100% derived from doc headers.
+- `meta.scan_commit` stays the OLDEST doc's anchor, and nothing reads it as a tier.
+- Edges come from `wiki_fresh_max` / `wiki_aging_max`. A hardcoded 10/30 is a bug.
+- `computeWikiFreshness` stays the ONE engine. `plan`, `debt` and `usage` all call
+  it, and skills never compute a tier.
+- Crosslink publish stays per-scan-task.
+- A STRUCTURAL blind spot still degrades one step and never past AGING.
+- The fixed pause every 5 scan-tasks is not configurable.

package/templates/skills/orc-wiki/references/pattern-prewarm.md

@@ -0,0 +1,19 @@
+# Code-pattern pre-warm (opt-in — config `orc_wiki_pattern_findings: on`)
+
+Default OFF. When on, after Phase 3 also **codify the code-pattern for every
+detected FE/BE language** as a scan byproduct — pre-warming
+`.claude/orc/patterns/<lang>-pattern.md` so later `/orc` runs never hit the
+`pattern_findings` prompt.
+
+Rules:
+
+- Rides the wiki's existing scan-consent, so there is NO separate ask (hence
+  on/off only, no `ask` value).
+- Per detected language (`../../orc-pattern/references/INDEX.md`): dispatch
+  `orc-pattern-codifier-sonnet-5-high` (`orc-pattern-codifier-opus-5-med` when
+  `opus5_only` — `../../_shared/opus5-only.md`) with the generic playbook + the
+  most-recently-modified real files; YOU write the returned pattern to the
+  cache.
+- Never run tests or change project code; skip languages already cached and
+  un-drifted.
+- Reuses the `orc-pattern` engine — you never codify yourself.

package/templates/skills/orc-wiki/references/staleness.md

@@ -0,0 +1,288 @@
+# Reference — Freshness, Staleness & Refresh
+
+THE canonical freshness reference for the whole constellation. Every skill that
+consults the wiki (orc, /orc-ultra, orc-mini, orc-fast, planners) follows the
+rules here; this file is the single source of truth for the manifest format,
+the tier thresholds, the refresh modes, and the precedence rule.
+
+## Precedence (source-of-truth contract)
+
+**code > fresh wiki > stale wiki (hints) > model priors.** The wiki is a
+DERIVED source of truth: on any conflict between a wiki claim and the actual
+code, the code wins and the doc gets stale-flagged. Never let a confident wiki
+claim override what a file actually shows; never let a model prior override a
+fresh, evidence-anchored wiki claim without reading the code.
+
+## The manifest — `.claude/orc/wiki-meta.json`
+
+Written **ONLY by the `orc wiki sync` CLI** — never by a model, never by a
+consumer. The manifest is DERIVED data: every field it carries already lives in
+the docs' own headers (schemas/wiki-doc.md), so deriving it is deterministic and
+free, while authoring it from memory is neither. orc-wiki runs `orc wiki sync`
+after every scan-task, at every pause, and at Phase 3; consumers only ever READ
+it, and never persist the freshness status they compute from it (below) — that
+status goes stale the moment anyone commits. Lives outside `templates/` next to
+the pattern cache, so `orc update` never clobbers it.
+
+> **Why the CLI owns this.** Registration was once the model's job at the end of
+> orc-wiki's Phase 3 — the last step of a lane that pauses every 5 scan-tasks by
+> design. Every run stopped at a pause left real docs on disk that nothing had
+> indexed, invisible to every consumer and to `orc crosslink`. The one field no
+> header carries is `commands` (discovered during the scan): sync preserves it
+> across rebuilds and falls back to `package.json` scripts, and it is the only
+> key a model may hand-edit.
+
+```json
+{
+  "last_scan": "12-07-2026 14:32:05",
+  "scan_commit": "<full git hash — HEAD at scan time>",
+  "branch": "main",
+  "pages": 14,
+  "commands": {
+    "build": "npm run build",
+    "test_fast": "npm test",
+    "lint": "npm run lint"
+  },
+  "docs": [
+    {
+      "file": "wiki/orc-feature-orders.md",
+      "area": "orders",
+      "doc_type": "feature",
+      "covers": ["src/orders/**"],
+      "covered_files": { "src/orders/service.ts": "a1b2c3d" },
+      "scanned_commit": "<git hash>"
+    }
+  ]
+}
+```
+
+- `last_scan`: dd-mm-yyyy hh:mm:ss, local time.
+- `scan_commit`: the anchor every staleness compute measures against.
+- `commands`: the project's build/test/lint invocations, discovered ONCE during
+  the scan. Consumers (especially orc-fast's smoke gate) run these directly
+  instead of rediscovering the project's tooling every run. Omit keys the
+  project doesn't have; never guess.
+- `docs` (v2 registry): one entry per wiki doc mirroring its header's
+  `covers` + `covered_files` (`wiki_schema: 2` docs). Purpose: ALL staleness
+  questions become answerable from ONE small JSON read + two git commands —
+  no doc opens. A manifest without `docs` is v1: consumers fall back to
+  doc-header reads; the next refresh writes the registry.
+
+## Computing freshness — COVERAGE-RELATIVE, and the CLI computes it (v0.41.0)
+
+**Run `orc wiki status` (or `--json` to branch on `.tier`). Never compute the
+tier by hand.** These are the RULES; the CLI is their only executor.
+
+Freshness is **per doc, against its own coverage**:
+
+```
+per-doc distance = git rev-list --count <doc.scanned_commit>..HEAD -- <that doc's covers/covered_files>
+wiki tier        = the WORST doc's tier
+```
+
+| Tier | Condition |
+|-------|--------------------|
+| FRESH | distance < `wiki_fresh_max` (default 10) |
+| AGING | `wiki_fresh_max` ≤ distance ≤ `wiki_aging_max` (default 30) |
+| STALE | distance > `wiki_aging_max` |
+
+Thresholds come from config (`wiki_fresh_max`, `wiki_aging_max`) — the CLI reads
+them; a hardcoded 10/30 anywhere is a bug.
+
+**A STRUCTURAL blind spot** — changed files that NO doc covers — degrades the
+tier by exactly ONE step, never past AGING. That is a COVERAGE gap, not doc rot:
+the docs on disk are still accurate, they just don't cover everything. (STALE
+means "do not trust these docs", which a blind spot does not say. `orc wiki
+impact` is where a blind spot escalates to a FULL-refresh recommendation.)
+
+### Why per-doc, and why this used to be permanently STALE
+
+`wiki-meta.json`'s `scan_commit` is the **oldest** doc's anchor — deliberately,
+as the conservative floor for the blind-spot sweep. But a DELTA refresh (the
+default path) only re-scans TOUCHED docs, so untouched docs keep their original
+`scanned_commit` and **that anchor can never move**. Measuring the tier from it
+meant every refresh reported the same hash and an ever-growing distance:
+permanently STALE, no matter how many times the user refreshed — the exact state
+a refresh exists to clear.
+
+Per-doc coverage also makes the answer semantically right: a doc about auth does
+not rot because the README changed forty times. A doc is stale when commits
+since its own anchor touched files it covers, and not before.
+
+## UNREGISTERED — docs without a manifest
+
+If `wiki-meta.json` is ABSENT but `wiki/` has docs, the wiki is **UNREGISTERED**,
+not missing and not stale. The docs may be perfectly current; nothing has indexed
+them. Never treat this as a reason to re-scan — the fix is derived and free:
+
+> "This wiki has {N} docs but no manifest, so nothing can read it. Run
+>  `orc wiki sync` — instant, no re-scan."
+
+Consumers treat an unregistered wiki as STALE for precedence purposes (they
+cannot prove freshness without an anchor) but must surface the sync fix, never a
+refresh. `orc wiki status` names the state; `orc wiki sync --check` is the
+read-only test. The same applies to a manifest that exists but won't parse
+(CORRUPT) or that has drifted from the docs on disk (OUT OF SYNC) — one command
+fixes all three.
+
+**Do not conflate incomplete coverage with unregistered.** A scan stopped at a
+pause has both: partial coverage (real, fix by resuming — costs money) and no
+registration (fix with sync — free). Diagnose them separately; only the first
+is worth spending on.
+
+## Per-skill reactions
+
+| Tier | orc / /orc-ultra / planners | orc-mini | orc-fast |
+|-------|-----------------------------|----------|----------|
+| FRESH | silent | silent | proceed |
+| AGING | one-line notice, proceed | one-line notice, proceed | one-line notice, proceed |
+| STALE | prominent warning, continue (these lanes self-ground) | prominent warning, continue | **user gate** — see the orc-fast skill (refresh-then-continue recommended / drop to mini / continue anyway) |
+
+## Per-doc staleness (advisory second signal)
+
+Each doc records `scanned_commit` and per-file `covered_files` hashes (v1 docs:
+a single `covered_hash`). A doc is stale when the current state of any file in
+`covered_files` differs from its recorded hash. Cheap to check via the manifest
+registry, no re-scan needed. The doc-header `status: fresh|stale` flag is
+ADVISORY only — it is flipped by the auto-flag hook below, which fires only on
+ORC runs, so commits made outside ORC never flip it. The computed tier above is
+always the authoritative check.
+
+## Refresh modes
+
+0. **Register-only (`orc wiki sync`)** — not a refresh at all, but it is the
+   right answer whenever the complaint is "ORC can't see my wiki". Re-derives
+   the manifest + INDEX from the doc headers. No scan, no cost, no doc changes.
+   Always try this BEFORE offering any mode below: a wiki that is merely
+   unregistered needs no re-scan, and re-scanning it wastes real money. Sync
+   also runs the **boundary detector** (references/crosslink.md): a non-empty
+   `## Contracts & shapes` table with zero `wiki/crosslink/` tags → prominent
+   warning + `--check` exit 1 (a documented boundary that never published), and
+   an N→0 tripwire when the manifest listed tags but the folder is now empty.
+1. **Delta (THE DEFAULT refresh path when a manifest exists — v0.33.0)** —
+   commit-scoped, probe-first. Step 1 is always the deterministic CLI probe
+   **`orc wiki impact`** (never an ad-hoc diff): it runs `git diff --name-only
+   <scan_commit>..HEAD` against the registry's `covers`/`covered_files` and
+   prints per-doc `CLEAN | TOUCHED (n) | STRUCTURAL` + a summary, with a
+   branchable exit code (0 clean · 1 can't compute · 2 delta · 3 full
+   recommended).
+   - **Exit 0 (CLEAN):** say so; nothing to refresh.
+   - **Exit 2 (small delta):** re-scan ONLY the touched docs → `orc wiki sync`
+     → regenerate the orientation doc (+ the atlas when crosslink is
+     configured) — both DERIVED and cheap, no new scan area. The delta pass
+     also runs the sweeps below.
+   - **Exit 3 (FULL recommended):** present the impact table and let the USER
+     decide — **never silently full**. The probe recommends full when ANY of:
+     TOUCHED docs > `wiki_delta_full_threshold` % of registered docs (config,
+     default 30) · STRUCTURAL (a doc's covered file is gone, or changed files
+     match NO doc's coverage — a blind spot a targeted refresh can't fix) ·
+     `scan_commit` more than `wiki_aging_max` commits behind HEAD. A delta
+     refresh of just the touched docs remains a valid, cheaper choice.
+   - **Exit 1 (can't compute):** the probe names the fix (sync / re-anchor);
+     fall back to offering full/selective with an honest cost note.
+2. **Full regenerate** — re-scan every area. Full cost warning. Timestamps all
+   docs fresh. Does NOT clear `wiki/` or `wiki/crosslink/` first: docs and tags
+   are overwritten per-area/per-point as each re-scan lands, so the crosslink
+   surface is never momentarily wiped (a full regenerate must never destroy the
+   boundary — hard rule 12). `wiki/crosslink/atlas.md` is likewise preserved
+   and regenerated at the end, never bulk-deleted.
+3. **Selective refresh** — list stale-flagged docs; user picks which to
+   re-scan. Only those spawn agents.
+4. **Pre-push diff-scan** — `git diff --name-only` against the push target;
+   find docs whose `covers` intersect the changed files; offer to refresh those
+   before commit.
+
+**Coverage-gap sweep (delta refresh + integrity check):** changed files
+matched by NO doc's `covers` = uncovered drift — the silent way a wiki becomes
+a partial map while still reading FRESH. `orc wiki impact` surfaces these as
+the STRUCTURAL blind spot; report them grouped by directory and
+propose new areas/docs; the user consents per new area (rides the refresh
+consent, no separate warning). Never silently ignore uncovered drift.
+
+**Dead-doc sweep:** registry entries whose `covers` match ZERO existing files
+(area deleted/moved) → offer per doc: archive to `wiki/archive/` (kept out of
+INDEX.md) or delete. Never silent, never automatic.
+
+**Dead-tag sweep (crosslink, beside the dead-doc sweep):** a `wiki/crosslink/`
+tag whose `anchor` file no longer exists, or whose owning area was re-scanned
+this pass and returned `crosslink_tags` WITHOUT it → offer archive/delete per
+tag. This is the ONLY way a tag is retired — a refresh never bulk-deletes the
+folder (references/crosslink.md preservation rule). Never silent, never automatic.
+
+## Post-ship refresh ask (big runs — full orc + /orc-ultra ship phase)
+
+GUARD FIRST: only if `wiki/` exists AND contains > 0 docs. No wiki → completely
+silent (no ask, no note).
+
+A run counts as BIG when, judged by FINAL counts at ship time (so a medium run
+that grew counts): tasks dispatched ≥ `wiki_refresh_ask_tasks` (default 3), OR
+union of executors' touched files > `wiki_refresh_ask_files` (default 10), OR
+waves > 1. Relevance check: if the run's touched files intersect ZERO docs'
+`covers`, downgrade to the passive note regardless of size.
+
+- **BIG** → right after ship, ask:
+  1. **Refresh wiki now** *(recommended)* — incremental refresh (mode 1),
+     scoped to the docs this run staled.
+  2. **Later** — print: "This was a big change — N wiki docs are now stale.
+     Refresh ASAP (/orc-wiki) or orc-fast and future runs will degrade." Stamp
+     `wiki_refresh_declined` in the checkpoint so /orc-retro can correlate.
+- **Small runs** → the passive auto-flag note below only. No ask.
+
+orc-mini keeps the passive note only (single-task lane); orc-fast never asks
+(its preflight polices freshness on the way in).
+
+## Auto-flag hook (after orc / orc-mini runs)
+
+GUARD FIRST: only act if `wiki/` exists AND contains > 0 files. On an empty/
+absent wiki this hook is a silent no-op.
+
+If guarded in:
+1. Take the files the orc run touched (from its dispatch/actual_files).
+2. Mark every wiki doc whose `covers` intersect those files as `status: stale`.
+   This is a metadata flip only — instant, free, no scanning.
+3. Tell the user: "N wiki docs are now stale from this change. Run
+   /orc-wiki to refresh when ready." Never auto-scan. (On a BIG full-lane run
+   the post-ship refresh ask above replaces this passive note.)
+
+## Cross-repo crosslink freshness (references/crosslink.md — advisory only)
+
+A crosslink hint is trustworthy only if BOTH signals hold; the weakest wins,
+`effective = min(Signal-A, Signal-B)`. Both are computed on read; the cache
+stamp is a fallback INPUT, never a stored status.
+
+- **Signal A — provider wiki tier.** The SAME git-commit-distance compute above,
+  run read-only in the linked repo's checkout (`git rev-list --count
+  <scan_commit>..HEAD` in `<repo_path>`), using the DEFAULT edges
+  (`wiki_fresh_max` 10 / `wiki_aging_max` 30) — we do not read the provider's
+  overrides. Provider not checked out or git fails → fall back to the
+  `source_tier` stamped in `.claude/orc/crosslink/cache/` at sync, "as of last
+  sync".
+- **Signal B — snapshot age.** The ONLY day-based tier in the constellation
+  (two repos share no commit axis): `days = today − synced_at`, against
+  `crosslink_fresh_days` (default 10 → FRESH) and `crosslink_aging_days`
+  (default 15 → AGING; beyond → STALE).
+
+Reaction is always advisory: label the injected surface with the effective tier
++ "cross-repo hints, not verified", and warn on per-point drift — never block.
+Precedence extends the local rule: `local code > local fresh wiki > cross-repo
+fresh wiki (hints) > cross-repo stale wiki (weak hints) > model priors`.
+
+## Consume rule (main orc + orc-mini)
+
+Before consulting the wiki during planning/scoring: determine existence with the
+deterministic probe `orc wiki status` (per `../../_shared/detecting-artifacts.md`
+— never an ad-hoc `find`; `.claude` is hidden). If present, compute the freshness
+tier (above) and react per the
+per-skill table, then read the relevant `orc-feature-*` / `orc-reference-*` /
+`orc-architecture-overview.md` for the area being planned — selecting pages via
+`wiki/INDEX.md` (one line per doc: type, status, description, keywords)
+instead of globbing and skimming headers. Pull the cross-cutting reference
+maps when they exist and the task touches their domain:
+`orc-reference-api-surface` (route/endpoint inventory — the best planning
+input for API work), `orc-reference-data-model` (tables/entities + owners),
+`orc-reference-glossary` (domain terms — read it whenever the request uses
+project jargon), `orc-reference-config-env` (env/config keys). In each doc the
+`TL;DR` section is the cheap read; `Contracts & shapes` and `Testing map`
+carry the file-anchored specifics. Apply the precedence rule above. If
+`wiki/` is empty/absent, ignore entirely and plan as normal. The wiki is
+purely additive.

package/templates/skills/orc-wiki/schemas/crosslink-tag.md

@@ -0,0 +1,166 @@
+# Schema — Crosslink Tag + Needs + Cache (cross-repo boundary index)
+
+The machine-resolvable half of the wiki. Where `wiki/orc-*.md` docs are the
+human narrative, crosslink files are a per-integration-point index that another
+repo resolves **by tag**. See `references/crosslink.md` for the mechanics; this
+file pins the shapes.
+
+**Who writes what.** The tag FILES, needs, and cache are written by `orc-wiki`
+(never by a model in a chat, never by the CLI) — they carry scanned contract
+prose and evidence anchors, which takes a model. Tag files are emitted
+**per-scan-task, together with the doc** (v0.24.0): each scan agent returns
+`crosslink_tags` alongside its `doc_body` (schemas/wiki-doc.md) — either one tag
+body per outward boundary point it found in the area's files, or the token
+`none` + a one-line reason. The orchestrator writes the doc AND its tags, then
+runs `orc wiki sync`. So the boundary accumulates from the FIRST scan-task,
+however the run ends — a paused run has a live partial boundary matching its
+live partial docs. `none` is an auditable claim ("area has no outward boundary"),
+never silence. The `crosslink_provided` registry in the manifest is the
+exception to model-authorship: it is a derived INDEX of those tag files, so
+`orc wiki sync` builds it from their headers and nothing else ever writes it
+(staleness.md).
+
+---
+
+## 1. Provider tag file — `wiki/crosslink/<kind>/<slug>.md`
+
+One file per integration point this repo **provides**, emitted proactively as a
+per-scan-task byproduct (whether or not any consumer exists) — from the source
+the agent just read, not from doc prose. Committed — a consumer reads it from a
+plain sibling checkout. Lives under project-root `wiki/crosslink/`, NOT
+`.claude/orc/` (that holds only machine state). Overwritten per-point on
+re-scan; a refresh NEVER bulk-deletes this folder (a vanished point is retired
+only by the dead-tag sweep — references/staleness.md).
+
+**Slug rule (Windows-safe, reversible):** the tag *identity* string uses `:` as
+its separator (`service-c:grpc:billing.v1.CreateInvoice`) but a filename MUST
+NOT contain `:`. The on-disk slug replaces every path/separator character:
+`/` → `_`, `:` → `.`, space → `_`. `POST /v1/invoices` → `POST__v1_invoices.md`.
+The header carries the original `tag` verbatim, so the identity round-trips
+without parsing the filename.
+
+**The KIND DIRECTORY is sanitized the same way (v0.34.5):** `/` → `-`, so the
+catalog kind `auth/oidc` writes to `wiki/crosslink/auth-oidc/`. **The header
+stays the identity** — `kind: auth/oidc` and `tag: auth/oidc:<name>` are kept
+VERBATIM, and `orc wiki sync` reads `kind` from the header, never from the
+directory name. A kind containing a raw `/` used to produce a nested path the
+registry walk never saw: the tag was published, well-formed, on disk — and
+invisible, with `orc wiki sync --check` still exiting 0. Sync now reads nested
+directories too (so a pre-v0.34.5 wiki keeps its tag) and FAILS `--check` when
+any tag file on disk does not reach the registry.
+
+```markdown
+---
+crosslink_schema: 1
+tag: grpc:billing.v1.CreateInvoice   # identity WITHOUT the repo prefix (the
+                                     # consuming repo prefixes with the node name)
+kind: grpc
+surface: provided                    # provided | consumed
+anchor: internal/billing/create.go:42   # real file+line (evidence-anchored)
+content_hash: <short-hash>           # hash of the contract BODY below; moves
+                                     # only when the anchored contract changes
+scanned_commit: <git-hash>
+---
+
+# billing.v1.CreateInvoice
+
+## Contract
+<the boundary contract, evidence-anchored: request/response message or
+ route shape, field names + types, error codes — pulled from `anchor`.
+ A field the scan agent can't see in the anchored file is OMITTED, not guessed.>
+
+## Notes
+<auth requirement, idempotency, versioning — anything a caller must honor.>
+```
+
+`content_hash` is the drift axis: it is the hash of the `## Contract` body, and
+it is refreshed whenever the anchored source file's recorded per-file hash moves
+(the same per-file hashing the wiki already records at scan time).
+A consumer compares its cached copy's `content_hash` against the provider's
+current one — equal = clean, different = drifted, file gone = breaking change.
+
+---
+
+## 2. Provider registry — `crosslink_provided` in `wiki-meta.json`
+
+A sibling array in the manifest, alongside `docs`, derived by `orc wiki sync`
+from the tag-file headers — never hand-maintained. Per-point tag files are a
+machine index, NOT prose docs — they must NOT enter `wiki/INDEX.md` or the `docs`
+registry (that would corrupt the human index and the `pages` count); sync
+enforces that by construction, since it only ever reads `wiki/crosslink/` into
+this array. Shape:
+
+```json
+{
+  "docs": [ ... ],
+  "crosslink_provided": [
+    {
+      "tag": "grpc:billing.v1.CreateInvoice",
+      "kind": "grpc",
+      "file": "wiki/crosslink/grpc/billing.v1.CreateInvoice.md",
+      "anchor": "internal/billing/create.go:42",
+      "content_hash": "<short-hash>"
+    }
+  ]
+}
+```
+
+The integrity self-check gains one crosslink rule (integrity-check.md): every
+file under `wiki/crosslink/` has exactly one `crosslink_provided` entry and vice
+versa; each entry's `anchor` file exists. `crosslink_provided` absent is no
+longer assumed benign: it means EITHER the repo has no outward boundary (valid —
+every scan-task returned `crosslink_tags: none`, and the final report says so)
+OR a boundary is documented but unpublished (the bug). `orc wiki sync`
+disambiguates deterministically by scanning doc bodies for a non-empty
+`## Contracts & shapes` table (`boundary_rows`): rows present + zero tags →
+prominent warning + `--check` exit 1 (references/integrity-check.md item 6,
+references/staleness.md).
+
+---
+
+## 3. Consumer needs manifest — `.claude/orc/crosslink/needs.json`
+
+Machine-authored by `orc-wiki` (NOT the CLI). The per-point tags THIS repo
+actually depends on — the drift baseline. Committed (it is the record of what we
+build against). Populated by walking call sites and matching them to linked
+repos from `orc-crosslink.config.yaml`; the human never hand-lists tags.
+
+```json
+{
+  "version": 1,
+  "needs": [
+    {
+      "node": "service-z-be",              // linked repo (from the config)
+      "tag": "grpc:billing.v1.CreateInvoice",
+      "via": "grpc",
+      "discovered_at": "svc/pay.go:31"     // OUR call site that created the need
+    }
+  ]
+}
+```
+
+---
+
+## 4. Consumer cache — `.claude/orc/crosslink/cache/<node>/<kind>/<slug>.md`
+
+Machine-authored mirror of the provider tag files this repo needs. **Gitignored**
+— derived and regenerable. The durable source of record when the provider is not
+checked out. Each cached file is the provider's tag file verbatim PLUS a sync
+stamp block appended at the top:
+
+```markdown
+<!-- crosslink-sync
+synced_at: 12-07-2026            # date we mirrored it (Signal-B age axis)
+source_node: service-z-be
+source_content_hash: <short-hash>   # provider content_hash AT sync (drift baseline)
+source_tier: FRESH                  # provider wiki tier computed AT sync (Signal-A fallback)
+source_scan_commit: <git-hash>      # provider scan_commit AT sync
+-->
+--- <the provider tag file, verbatim> ---
+```
+
+The stamp is a **fallback input to a computation**, never a stored status: the
+effective tier is always computed on read (`min(Signal-A, Signal-B)` —
+references/crosslink.md §freshness). `synced_at` drives Signal-B against
+`crosslink_fresh_days` / `crosslink_aging_days`; `source_tier` is the Signal-A
+fallback used only when the provider checkout is unavailable.