Detailed Description

Deterministic D-2 (`-v3.38`) relocation link + framing audit (Plan 142k R8).

Purpose
-------
Prove — deterministically, over a scoped active bucket — that relocating the four
legacy ``ROADMAP-*-v3.38.md`` receipts into
``oc_chat/roadmap/historical-archive-DO-NOT-DELETE/`` leaves **no dangling active
link** and that the migrated framing is re-worded from *current* to *archived*.
This is the reference check ``test_docs_consistency.py`` cannot do (it checks
scoped terminology, not dead file links).

Responsibilities
----------------
- Parse + resolve every Markdown link in the scoped active bucket from its
  render-target directory; classify external / anchor / file / file+anchor.
- ``--write-baseline`` / ``--write-report --preserve-baseline`` / ``--check`` —
  the immutable-baseline lifecycle + the D-2 + framing-text gates.

D-2 isolation + the immutable baseline (Codex-R05/R06)
------------------------------------------------------
``--check`` FAILS only on (i) a link whose normalized target is one of the four
moved basenames that does not resolve to the archive path, and (ii) a **newly**
dead link (dangling because of a change on THIS branch). Pre-existing non-D-2 dead
links are captured once by ``--write-baseline`` on the CLEAN branch base (with a
``baseline_ref``) and are never failed; ``--check`` REFUSES if ``baseline_ref`` is
missing / not an ancestor of HEAD / captured after the relocation — so a
branch-introduced dangle can never be laundered in. Baseline identity is a STABLE
key (source/artifact + normalized target + link text [+ context hash]), never a
line number.

Render-context map (EXHAUSTIVE, no silent skips)
------------------------------------------------
Every link resolves from its RENDER-TARGET artifact's directory: rendered views +
standalone docs from their own dir; ``source/notes|phases|changelog/roadmap|
framing`` → ``oc_chat/roadmap/`` (they render into ``ROADMAP-EXTENDED``/
``ROADMAP-CHANGELOG``); ``source/changelog/product`` → repo root (root
``CHANGELOG.md``); ``source/items`` bodies do NOT render (only ``purpose``/
``title``), so their bodies are declared source-only / out-of-audit.

Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 - audit lifecycle
    L3 - per-link resolution
    L4 - normalization / slugger detail

Contracts
---------
- ``--write-baseline`` (Phase 0, clean base) records the immutable baseline; it
  is never rewritten afterwards. ``--write-report --preserve-baseline`` (post-edit)
  regenerates the active/exempt classification + framing findings only. ``--check``
  is non-mutating, exit 0 clean / 1 on any violation.
- Links parse via ``urllib.parse.urlsplit`` (never string slicing), the path is
  percent-decoded exactly once, POSIX-normalized, and rejected if it escapes the
  repo root; in-repo Markdown anchors resolve via the renderer's slugger.

Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.registry.render.roadmap.roadmap_main (_slug — the renderer's slugger)
- argparse (the three mutually exclusive modes and --preserve-baseline)
- re (the Markdown link pattern and the moved-basename pattern)
- subprocess (runs git to resolve HEAD, check the baseline's ancestry and read files from the baseline commit)
- urllib.parse (urlsplit and unquote - link parsing and the single percent-decode)
- pathlib (Path - the repo root, the report path and the source record paths)
- git (not imported; run as a subprocess for rev-parse, merge-base, ls-tree, show and cat-file)