@azure-id/orc 0.55.0

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

@@ -0,0 +1,284 @@
+# Reference — Cross-Repo Wiki Crosslink (federation at the boundary)
+
+Lets one repo's wiki reference *another repo's* wiki at integration boundaries
+(BE↔FE, BE→gRPC service, …) so executors build against real cross-repo contracts
+instead of guessing. Crosslink is a **subsystem of orc-wiki** — no slash command,
+no standalone runtime role. It federates on the *boundary surface*, not the whole
+wiki. Shapes: `../schemas/crosslink-tag.md`. Kinds: `crosslink-kinds.md`.
+
+## Load-bearing invariant: advisory, never blocking
+
+You cannot control another team's repo — its wiki version, scan freshness, or
+whether it adopted crosslink. So **every** failure mode (missing repo, no wiki,
+old schema, drift, breaking change) degrades to a *warning + reduced context*,
+never a gate. Cross-repo output is always labeled "hints, not verified".
+
+## Hard boundary: read foreign WIKI only, never foreign SOURCE, never WRITE
+
+The entire foreign footprint is read-only on a handful of the linked repo's
+files, resolved from its `repo_path` (repo root):
+
+- `<repo_path>/wiki/crosslink/**` — per-point tag files (the surface)
+- `<repo_path>/wiki/orc-reference-api-surface.md` — coarse fallback for v1 repos
+- `<repo_path>/.claude/orc/wiki-meta.json` — its freshness manifest + provider registry
+- `<repo_path>/.claude/orc-crosslink.config.yaml` — bulk-add peek only
+- read-only git queries in `<repo_path>` (`git rev-list --count`, `git diff
+  --name-only`) — wiki tiers are commit-distance computed, not mtime-derivable
+
+Never read the linked repo's *source*, never write anything in it. The only
+writes are inside THIS repo: `.claude/orc/crosslink/needs.json`,
+`.claude/orc/crosslink/cache/**`, and this repo's own `wiki/crosslink/**`.
+
+**Exactly TWO sanctioned exceptions to never-write-foreign — both file writes
+only, NEVER a commit, NEVER a push, never any other peer path:**
+
+1. **The orc-poly handoff plan** — orc-poly writes each peer repo's plan file
+   into that repo at its Phase 5 (the orc-poly skill owns that rule).
+2. **The ATLAS + the CLAUDE.md pointer block (v0.33.0)** — after generating the
+   local atlas, the session writes the SAME `wiki/crosslink/atlas.md` into each
+   linked repo, and `/orc-wiki crosslink compile` additionally updates each
+   linked repo's CLAUDE.md pointer block (in-place block update, user content
+   byte-preserved). Any peer-write failure (missing path, permissions, repo
+   gone) WARNS and continues — advisory, never blocking.
+
+Everything else in a peer stays untouchable, and even these two never run
+`git add`/`git commit`/`git push` in the peer.
+
+## Two surfaces, one direction rule
+
+- **Provided (inbound)** — what a repo exposes (gRPC handlers, routers). Read by
+  whoever *calls* it.
+- **Consumed (outbound)** — what a repo reaches for (its client calls). Its edges.
+
+Direction decides **which side runs drift: you only drift-check what you
+consume.** An edge `from: self to: z via: grpc` means self consumes z → watch z's
+tags. `from: fe to: self via: api-client` means self is the provider → no drift
+on our side (we publish; they watch us).
+
+## The config (CLI-composed, skill-read)
+
+`.claude/orc-crosslink.config.yaml` is written ONLY by the `orc crosslink` CLI
+(the DIY pattern — human configs live directly under `.claude/`). orc-wiki only
+READS it. Nodes + a directed edge list; `self` is node 1:
+
+```yaml
+version: 1
+self: service-x-be
+nodes:
+  - name: service-z-be
+    repo_path: ../service-z          # repo ROOT — wiki/, wiki-meta, config, .git derive from it
+    kinds: [grpc, repository]
+links:
+  - from: service-x-be to: service-z-be via: grpc    # we consume z
+```
+
+`links` is an edge list (not `linked_to` per node) because one pair can have
+edges in both directions/kinds (x→z gRPC AND z→x webhook).
+
+---
+
+## Provider emission (this repo publishes its surface — ALWAYS ON, per scan-task)
+
+Publish is **not** a Phase-3 add-on and has **no enable switch** (v0.24.0). It is
+a per-scan-task byproduct of reading the code, the same pattern registration
+follows — so it can never be skipped by a run that pauses (every 5 tasks, by
+design) or by an incremental refresh with no drift.
+
+Each scan agent, having already read the area's files to write the `Contracts &
+shapes` rows, returns a REQUIRED `crosslink_tags` field alongside its `doc_body`
+(schemas/wiki-doc.md): either **one tag body per OUTWARD boundary point** it
+found (routes, gRPC handlers, produced events — pulled from source, NOT from the
+doc prose, which is what kills the "thin docs starve the publish" failure), or
+the token **`none` + a one-line reason**. A return missing `crosslink_tags`
+entirely is MALFORMED → requeue.
+
+The orchestrator then, in the SAME pass:
+
+1. Writes the doc to `wiki/` AND each tag to `wiki/crosslink/<kind>/<slug>.md`
+   (schema §1; slug rule is Windows-safe + reversible).
+2. Runs `orc wiki sync` — derives `wiki-meta.json`'s `crosslink_provided` array
+   from the tag files just written (schema §2). This registry — NOT
+   `wiki/INDEX.md` or `docs` — is where tags live, so the human index and
+   `pages` count stay clean. Never hand-maintain the array. Sync's boundary
+   detector flags a documented boundary with zero tags (`--check` exit 1).
+3. Traces the scan-task's `DISPATCH`/`VERIFY` with a `tags:N` (or `tags:none`)
+   count so the boundary is visibly accumulating.
+
+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.
+`crosslink_tags: none` is an auditable claim, never silence; a zero-tag
+completion additionally states "crosslink: no outward boundary ({reason})" in
+the final report.
+
+## Preservation — replace per-point, never bulk-delete
+
+A refresh (including full regenerate) NEVER clears `wiki/crosslink/` first; each
+tag is overwritten per-point as its owning area re-scans. A tag whose boundary
+genuinely disappeared is retired ONLY by the **dead-tag sweep** (staleness.md,
+beside the dead-doc sweep): a tag whose `anchor` file no longer exists, or whose
+re-scanned area returned `crosslink_tags` without it → offer archive/delete per
+tag, never silent, never automatic. A whole-surface vanish trips the `orc wiki
+sync` N→0 tripwire (loud warning + `--check` exit 1) — a regenerate can no
+longer wipe the boundary the way it once did.
+
+## Legacy backfill — `/orc-wiki crosslink` (CROSSLINK-ONLY, SKILL.md Phase 3c)
+
+For wikis whose docs predate v0.24.0 (docs exist, `wiki/crosslink/` absent), the
+boundary is already on disk in the evidence-anchored `Contracts & shapes` rows,
+so recovering it needs no repo scan: read the rows, open ONLY the files they
+anchor, emit the tags, `orc wiki sync` to index. On a ≥v0.24.0 wiki, missing
+tags are NOT a backfill case — the sync boundary guard fired and names the fix.
+**Never answer "no crosslink tags" with a re-scan.** When the rows are genuinely
+too thin to tag, SAY so and recommend an incremental refresh of just those areas
+(an honest cost, stated as such) — the one case where a refresh IS the answer.
+
+---
+
+## Consumer discovery (this repo resolves what it needs — Phase 3 add-on)
+
+Also at scan/refresh, when `orc-crosslink.config.yaml` exists:
+
+1. Read the config → linked nodes + `repo_path`s + edges.
+2. Walk THIS repo's code; at each call site whose shape matches an edge's
+   `via: <kind>` toward a linked node, resolve that node's tag file at
+   `<repo_path>/wiki/crosslink/<kind>/<slug>.md`.
+3. Record the dependency in `.claude/orc/crosslink/needs.json` (schema §3) — the
+   drift baseline. The human never hand-lists tags; discovery fills them.
+4. Sync a snapshot into `.claude/orc/crosslink/cache/<node>/…` (schema §4),
+   stamped `synced_at` + provider `content_hash` + provider tier +
+   provider `scan_commit`.
+5. Compute drift on everything already in `needs.json` (below) → **warn only**.
+
+Discovery runs only the **consume** side of edges. Provider-only edges
+(`from: fe to: self`) create no needs here.
+
+**So every report is direction-scoped.** A linked repo's tags/freshness matter
+ONLY on edges where we CALL them. On an inbound-only edge we read nothing from
+that repo, so "no crosslink tags" there is both irrelevant and unfixable — a
+pure consumer (a frontend `api-client`) has no API of its own and will never
+grow tags. `orc crosslink list`/`status` therefore report inbound-only nodes as
+"inbound only (they call us)" and never send anyone to publish a boundary that
+legitimately does not exist. **The graph is drawn in the CONSUMER**: the repo
+that calls is the one that needs the config, the edge, and the resolved cache.
+
+---
+
+## ATLAS — the federation super-context (`wiki/crosslink/atlas.md`, v0.33.0)
+
+ONE federation-scoped document, present in EACH linked repo at
+`wiki/crosslink/atlas.md`. Content is **repo-agnostic** — the same document
+serves every node — with a header recording `generated_from` (which repo built
+it), the `generated` timestamp, and per-peer peek freshness. Sections:
+
+- **Federation map** — every known node + the `links[]` edges (including
+  TRANSITIVE nodes learned from peer atlases), with relation kinds. This is how
+  a repo discovers a repo it never linked directly.
+- **Per-node profile** — what each repo provides, what it needs/consumes from
+  whom (from boundary rows + peer atlas), and **peek hints**: which of that
+  repo's wiki docs answer which questions (so a consumer peeks ONE doc, not a
+  wiki).
+- **Freshness ledger** — per-peek age. Freshness on READ =
+  `min(own wiki tier, oldest peek age)` — computed on read, NEVER stored as a
+  status (the constellation-wide rule).
+
+**Generation + propagation (the sanctioned write — exception #2 above):**
+
+- Generated at: the end of every orc-wiki scan/refresh (Phase 3, and the delta
+  refresh's derived-regenerate step); during CROSSLINK resolve in build lanes
+  when the atlas is missing/stale (a cheap regenerate from `needs.json` +
+  `cache/` — never a scan); and by `/orc-wiki crosslink compile`.
+- After writing the LOCAL atlas, the session writes the SAME file into each
+  linked repo's `wiki/crosslink/atlas.md` (repo paths from the config's
+  `links[]`/nodes). File write ONLY — never commit, never push, never any
+  other peer path. Any peer-write failure WARNS and continues.
+- **Newest-wins on read:** if a peer session regenerated its copy later, the
+  local consumer trusts the newer `generated` timestamp when peeking.
+- `orc wiki sync` treats `atlas.md` as a DERIVED crosslink artifact — never an
+  unregistered doc, never counted in `pages`, never bulk-deleted by a refresh
+  (same preservation rule as the tags).
+
+**Consumption:** the `wiki-consult.md` CROSSLINK step reads the atlas FIRST,
+then makes targeted peer-wiki peeks the atlas' peek hints point at. orc-poly's
+context gathering reads it, and its slug resolution lists transitive nodes
+discovered via the atlas (paste-a-path fallback unchanged).
+
+---
+
+## Freshness — two orthogonal signals, computed on read
+
+A cross-ref is trustworthy only if BOTH hold; the weakest link governs.
+`effective = min(Signal-A, Signal-B)`.
+
+- **Signal A — provider wiki tier.** Does the provider's wiki match its code?
+  Computed by staleness.md's existing rule — **git commit distance**
+  (`git rev-list --count <scan_commit>..HEAD` run read-only in `<repo_path>`),
+  NOT days. Use the standard default edges (`wiki_fresh_max` 10 / `wiki_aging_max`
+  30); do NOT read the provider's `orc.config.yaml` for custom thresholds (their
+  tuning is their business; defaults keep the compute self-contained). When the
+  provider isn't checked out or git fails there, fall back to `source_tier`
+  stamped in the cache at sync time, labeled "as of last sync".
+- **Signal B — snapshot age.** How long since we synced? This is the ONLY
+  day-based tier in the constellation (there is no shared commit axis between two
+  repos): `days = today − synced_at`, compared against `crosslink_fresh_days`
+  (default 10) and `crosslink_aging_days` (default 15). ≤ fresh → FRESH,
+  ≤ aging → AGING, else STALE.
+
+Never store the effective tier — the cache stamp is a fallback INPUT, the tier is
+always recomputed on read. Inject the linked surface labeled with `effective` +
+precedence rank.
+
+## Drift (per-point, warn only)
+
+Per-point tags → per-endpoint drift. Compare cached `source_content_hash` vs the
+provider's current tag `content_hash`:
+
+- changed → **contract drifted** → warn ("`grpc:billing.v1.CreateInvoice` changed
+  under you since last sync")
+- tag file gone → **breaking change** (a tag in `needs.json`) → **warn only**
+  (never blocks — advisory invariant)
+- unchanged → clean
+
+Topology-drift bonus (free): if `needs.json`/config says we consume z over a
+kind but z's own `orc-crosslink.config.yaml` declares no matching provider edge,
+note it — warn only.
+
+## Degradation ladder (every rung continues)
+
+| Provider state | What you get | Warn |
+|---|---|---|
+| v2 wiki + crosslink tags | per-point tags → precise drift | — |
+| v2 wiki, boundary documented but tags unpublished (legacy pre-v0.24.0, or a fired sync guard) | api-surface prose → coarse hints, no per-point drift | "boundary documented, tags unpublished — `orc wiki sync --check` there names it; `/orc-wiki crosslink` backfills from the docs, no re-scan" |
+| v2 wiki, no boundary at all | nothing to resolve (they expose no API) | — (valid; not a fixable gap) |
+| v1 wiki | api-surface only → coarse hints, no per-point drift | "older schema — coarse" |
+| wiki UNREGISTERED (docs, no manifest) | edge inert until registered — **but nothing needs scanning** | "run `orc wiki sync` there — instant, no re-scan" |
+| manifest CORRUPT (unparseable) | edge inert until rebuilt | "run `orc wiki sync` there to rebuild it" |
+| no wiki | edge inert until provider scanned | "run `/orc-wiki` there" |
+| path missing | pending edge, resolves when path appears | "path not found — pending" |
+
+Never collapse UNREGISTERED into "no wiki": a repo whose docs are complete but
+unindexed looks identical to an unscanned one from the manifest alone, and
+telling that team to scan sends them to re-buy a wiki they already own. `orc
+crosslink` distinguishes the two by looking for docs under `<repo_path>/wiki/`
+before it concludes anything from a missing manifest.
+
+Version skew is expected: a crosslink to a v1/tagless repo gets richer for free
+the day that repo re-scans with crosslink. No cross-team coordination needed.
+
+## Run-time injection (how the lanes benefit)
+
+orc / orc-fast / orc-mini inject the linked surface into a task's slice ONLY when
+that task touches a boundary — same mechanism as the `pattern` slice. The
+orchestrator reads `.claude/orc/crosslink/needs.json`, and for a task whose
+declared files include a call site with a matching need, prepends the cached tag
+contract (from `crosslink/cache/`) to the slice, labeled with `effective` tier +
+"cross-repo hints, not verified". No executor return contract changes — crosslink
+is advisory, so there is nothing to attest. A task with no boundary gets nothing.
+
+## Precedence
+
+```
+local code > local fresh wiki > cross-repo fresh wiki (hints)
+           > cross-repo stale wiki (weak hints) > model priors
+```
+
+Cross-repo can never outrank local hints — we cannot verify foreign code.

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

@@ -0,0 +1,79 @@
+# Routing a scan-task off Claude — the two POSITIONS
+
+Load this at the scan phase, once, when `extra_enabled` is true. Canonical
+cross-lane prose: `../../_shared/extra-dispatch.md`.
+
+## The row was DEAD until v0.55.0
+
+`/orc-wiki` was declared as routing foreign and asked for a role named `scanner`
+in `config.extra_roles` — a spelling that key **refuses by name**, alongside
+`wiki-scanner`, which it also does not have. So the lane could never route
+however it was configured, and `orc extra lanes` printed
+`/orc-wiki → claude` forever with a reason that read like a user's choice.
+
+It is a **POSITION** now, not a role name and not a band. Two of them, one per
+tier:
+
+| slot | the Claude agent it displaces |
+|---|---|
+| `wiki-scanner-deep` | `orc-wiki-scanner-opus-4-8-high` |
+| `wiki-scanner-light` | `orc-wiki-scanner-sonnet-5-high` |
+
+Both collapse onto `orc-wiki-scanner-opus-5-med` while `opus5_only` is on, which
+is why this adds **no agent and no pair**. Two slots and one Opus 5 agent is not
+a contradiction: a slot names the POSITION, not the model.
+
+```
+orc extra role set wiki-scanner-light ds/deepseek-chat
+orc extra resolve --slot wiki-scanner-light --json     # 0 = extra · 1 = claude
+```
+
+**No row on a slot means Claude, and that is an answer rather than a gap.**
+
+## The tier is picked first, and its target is printed with it
+
+Resolve the tier (`wiki_scan_tier`, `references/partial-refresh.md`), then ask
+the resolver for **that tier's** slot. The resolved tier already prints; now
+print its target on the same block — a cheaper model is never a quiet
+substitution, and neither is a different company's:
+
+```
+scan-task 3/7   tier LIGHT (small delta, no new surface)
+                -> deepseek/deepseek-chat via `ds`  (displaces orc-wiki-scanner-sonnet-5-high)
+```
+
+`orc wiki plan` names every scan-task that would run off Claude **before any of
+it is paid for**, and **free repairs still come first**: sync → orientation →
+crosslink backfill → and only then a paid refresh. A free repair is never
+skipped because a cheap model is available.
+
+## Dispatch, validate, recover
+
+```
+orc extra dispatch --task <slice.json> --json
+```
+
+The slice carries `slot: "wiki-scanner-deep"` or `"wiki-scanner-light"` and
+**no `score`** — this lane has none, and both fields together is refused by
+name. Everything else about the slice is identical to what the pinned Claude
+scanner would receive, including **the kind catalog**
+(`references/crosslink-kinds.md`): an agent never shown it invents synonym kinds,
+which are permanent duplicates, and that is true of a foreign agent too.
+
+Validate the return with `../../_shared/return-validation.md` **§2b, not §2** — a
+foreign worker reports no `actual_model` and that must never be faked. What it
+says it read is a CLAIM: the doc body it returns is still anchored, and an
+unanchored claim is still omitted rather than guessed.
+
+On a failure, run **`orc extra reconcile <task_id>` FIRST** — free, zero tokens,
+and it is what stops the fallback from re-doing work the worktree already
+contains. Then `extra_on_failure` decides: `fallback` re-dispatches to **that
+tier's pinned Claude agent, by name**, announced, and the scan continues;
+`stop` stops.
+
+## What never routes
+
+`orc wiki sync` **never** routes foreign. Registration is 100% derived from doc
+headers by the CLI — there is no model in it to replace. The same is true of
+`orc wiki plan`, the delta probe, `orc wiki status` and the crosslink registry
+walk: they compute, they do not produce.

package/templates/skills/orc-wiki/references/integrity-check.md

@@ -0,0 +1,86 @@
+# Reference — Scan-End Integrity Self-Check (anti-drift gate)
+
+Runs at the END of every scan/refresh (full, incremental, selective), AFTER
+all docs are written and AFTER the closing `orc wiki sync` — it VALIDATES the
+derived registration rather than racing it. The orchestrator runs it itself —
+it is checklist work (file existence + cross-referencing), not scanning, so it
+needs no agent. Any failed item is FIXED before the run is declared done; if a
+fix needs a re-scan, that re-scan rides the current run's consent (no new
+warning).
+
+When logging is on, emit ONE trace line per item:
+`WIKI-CHECK <item> ✅ PASS` or `WIKI-CHECK <item> ⛔ FAIL <what>` — and after
+fixes a final `WIKI-CHECK all ✅`.
+
+## Items 1, 2, 5 and 7 — now structural
+
+index-sync, registry-sync, counts-match and crosslink-sync used to compare four
+hand-maintained artifacts against each other. Since `orc wiki sync` DERIVES
+`wiki/INDEX.md` and `.claude/orc/wiki-meta.json` — the `docs` registry with each
+doc's `covers` + `covered_files`, the `pages` count, and the
+`crosslink_provided` index of `wiki/crosslink/` — from the one source those
+artifacts were supposed to agree with (the doc headers), they cannot disagree
+unless registration was never run. So the four collapse into one command:
+
+```bash
+orc wiki sync --check     # exit 0 = registration matches the docs on disk
+```
+
+Exit 0 → emit `WIKI-CHECK registration ✅ PASS`. Non-zero → sync was skipped or
+a doc changed after it; run `orc wiki sync` and re-check. Never fix these by
+hand-editing INDEX.md or the manifest: that re-creates the very drift the
+derivation removes. Only the manifest's `commands` key is hand-maintained, and
+only per staleness.md.
+
+## The checklist
+
+1. **covers-resolve** — every doc's `covers` globs match ≥ 1 real file. Zero
+   matches → route into the dead-doc sweep (staleness.md), never leave a dead
+   doc indexed as live.
+2. **coverage-report** — union of all docs' `covers` vs the repo's source
+   tree: print coverage % and the top uncovered directories. Informational
+   (feeds the coverage-gap sweep) — uncovered dirs are REPORTED with a
+   proposed-area suggestion, never auto-scanned.
+3. **claudemd-match** — the CLAUDE.md pointer block's doc count + "Last
+   updated" match the manifest. (The manifest's own `pages` is derived, so it
+   cannot drift; the pointer block is hand-injected, so it can.)
+4. **schema-upgrade-note** — list docs whose headers are still v1 (no
+   `wiki_schema: 2`: no `keywords`, a single `covered_hash` instead of per-file
+   `covered_files`). Derivation keeps them usable and indexed, so this is a
+   NOTE for lazy upgrade on the next refresh, never a failure — the one thing
+   the derived registration can't tell you, since a v1 entry looks merely
+   sparse rather than wrong.
+5. **anchor-spot-check** — for each doc written THIS run, pick 2 evidence
+   anchors from its contract sections and confirm the cited files exist
+   (existence only — cheap). A missing file = the agent cited something it
+   didn't read → re-queue that doc's scan.
+6. **crosslink-anchors** (UNCONDITIONAL as of v0.24.0 — this is the guard that
+   catches "boundary exists but no tags", the exact silent-zero the old
+   "only when this repo published a boundary this run" clause allowed). Trigger:
+   if ANY doc written this run reported boundaries (`crosslink_tags` ≠ `none`)
+   OR carries a non-empty `## Contracts & shapes` table, then `wiki/crosslink/`
+   MUST exist and every reported tag must be on disk AND registered in
+   `crosslink_provided` — else FAIL and fix before the run is declared done (the
+   fix is publishing the tags, NOT a re-scan). Each `crosslink_provided` entry's
+   `anchor` file must also exist (an anchor pointing at a deleted file is real
+   drift no derivation can see). A ZERO-tag completion is allowed ONLY when the
+   final report carries the explicit line
+   "crosslink: no outward boundary ({reason})" — a bare zero-tag finish FAILS.
+   Emit `WIKI-CHECK crosslink …` when logging. Consume-side needs/cache stay
+   advisory and are NOT gated (a stale cache warns, never fails).
+7. **orientation-check** (v0.33.0) — `wiki/orc-orientation.md` exists (it is a
+   derived assemble-step output, so a scan/refresh that ends without one
+   skipped a step), every `Reading order` pointer resolves to a REGISTERED doc,
+   and one spot-checked `Journeys` anchor's file exists. Neighbors section
+   present only when crosslink cache/atlas exists; otherwise the explicit
+   "no outward crosslink configured" line. A failed item is fixed by
+   re-deriving the orientation doc (free) — never a re-scan.
+
+## Why it exists
+
+A wiki that disagrees with itself cannot be a source of truth. Deriving the
+index and manifest from the docs removes one whole class of that disagreement
+by construction; this gate covers what derivation cannot see — claims pointing
+at files that don't exist, docs covering nothing, and the hand-injected
+CLAUDE.md block — so internal consistency is a shipped property of every run,
+not a hope.

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

@@ -0,0 +1,51 @@
+# Reference — The Orientation & Journey Doc (`wiki/orc-orientation.md`, v0.33.0)
+
+The wiki's front door: how a fresh session (or a human) self-orients in this
+repo in one read. **DERIVED at Phase 3 (assemble) from the already-written
+docs + the architecture overview — never a new scan area**, so it costs one
+assemble-time write. Consumers read it FIRST (`wiki-consult.md`), then dive
+into the docs it points at.
+
+## Sections (in order)
+
+1. **`Repo identity`** — what the repo is, the stack, the entry points — each
+   claim anchored to a real file (evidence-anchored v2 rule applies here as
+   everywhere: unanchored = omitted, never guessed).
+2. **`Reading order`** — ordered pointers into the other wiki docs, one line
+   of WHY per hop ("start at orc-architecture-overview for the map → then
+   orc-feature-orders because most requests land there → …").
+3. **`Journeys`** — 2–4 traced end-to-end flows (a request in, a job run, a
+   deploy), each step anchored `file:line`. A journey step that cannot be
+   anchored to a file a scan actually covered is OMITTED, never guessed.
+4. **`Neighbors`** *(conditional)* — present ONLY when crosslink is configured
+   AND the resolved cache / ATLAS exists: one paragraph per linked repo (what
+   it provides us, what we consume from it), sourced from
+   `.claude/orc/crosslink/cache/` + `wiki/crosslink/atlas.md`. No crosslink →
+   the section is omitted with the explicit style line
+   `Neighbors: none — no outward crosslink configured.` (never silent).
+
+## Rules
+
+- **Registered like any doc:** standard wiki-doc header (schemas/wiki-doc.md —
+  `doc_type: reference`, `area: orientation`) → `orc wiki sync` registers it;
+  freshness computed on read, existing tiers, NO new config keys. `covers` lists the entry-point
+  source files its Repo identity anchors — **plus every source file the docs it
+  summarizes cover** (the union of their `covers`). Its CONTENT derives from
+  those docs, so anchoring staleness only to `src/app.js` + `package.json` let
+  it read CLEAN in the same impact table where three docs it points at were
+  TOUCHED, while its Journeys described a handler that had changed. This is the
+  doc every consuming lane reads FIRST, so it is the highest-leverage stale doc
+  in the wiki — it needs a machine backstop, not only an obligation.
+- **`derived_from` (v0.34.5):** the header also records
+  `derived_from: {<doc file>: <content_hash>}` for every doc it summarizes. A
+  hash that no longer matches means orientation is stale even when no source
+  file moved (e.g. a doc was rewritten from the same code) — the Phase 3
+  integrity check reads it.
+- **Regenerated (free, derived) whenever any doc it points to is refreshed** —
+  including the delta refresh (staleness.md mode 1) and after an atlas
+  regeneration. Regeneration is an assemble step, never a scan.
+- **Consumption:** `wiki-consult.md` reads orientation FIRST, then dives into
+  the referenced docs. orc-learn's topic picker may offer the Journeys as
+  learnable topics.
+- **Integrity:** the Phase 3 self-check verifies the Reading-order pointers
+  resolve to registered docs and spot-checks one Journey anchor.