Wiki review findings: publish-script link fix, Part 3 status update, staleness mini-pass (#79)

* publish_wiki.py: fix link rewriting for parent-relative paths and slug casing

GitHub wiki's native [[...]] auto-linking reinterprets our own docs/
[[file.md]] convention: [[../troubleshooting.md]] became a dead literal
slug, and [[printing-tags.md]] linked the raw filename casing instead of
the published page name "Printing-Tags" (both visible live on
Catalog-Completion-Plan). Every internal link is now resolved against
its source file's real repo path and mapped through
wiki-publish-map.json: a published target becomes a same-wiki link using
its real page name, an unpublished-but-real target becomes an absolute
GitHub blob URL, and a target resolving to neither is a hard publish
error. docs_lint.py can't catch this class of bug since it only checks
links within docs/ itself, not the wiki-transform's own reinterpretation
downstream - the script now self-checks at publish time instead.

Also adds two docs/ pages that were listed in docs/README.md's index
but missing from the mapping entirely (found via the new validation):
documentation-process.md and upstream-wiki-drift.md.

* Docs staleness pass: Part 3 write-pass status + proposal B/C/E-1/E-2 markers

catalog-completion-plan.md: Part 3 heading and Status section updated to
reflect the completed write pass (run_id 20260718T145157-a12b1387, 13,275
votes, all hard bounds passed, 0/7,124 zero-resolution violations at full
population), pointing to docs/reports/2026-07-18-part3-write-pass-complete.md.
Filled the dangling "see the follow-up entry below" reference and replaced
the now-stale "HOLD #P3 stands" language. Part 4's heading now notes it's
confirmed unstarted with HOLD #B prep queued.

proposal-b-bleed-normalization.md: top summary no longer lists the
prior-resolution batch fetch as remaining work - it shipped as PR-1 (#72).

proposal-g-user-accounts-saved-decks.md: noted the build-order queue
(E-1 #61, E-2 #62, Level-2 grid fix #63, audit pass #64, GIS error UX #65,
Proposal B #66/#72, Proposal C part (a) #67) has fully cleared.

docs/README.md: added proposal-b and proposal-c to the "Plans & proposals"
table - both have dedicated docs but were missing from the index entirely,
despite the section's own stated policy that any proposal with a dedicated
doc gets a row.

printing-tags.md and vote-system.md checked per the mini-pass's minimum
list; no changes needed - printing-tags.md already defers Stage 8+ status
to catalog-completion-plan.md, and vote-system.md has no AI-terminology or
merged-PR staleness.

* Report relay: wiki review findings (publish-script fix, Part 3 status, staleness mini-pass)

* CI: black-format publish_wiki.py, prettier-format cache-transition-resilience.md

black reformatting for publish_wiki.py (never run locally - only
py_compile was checked, missing the repo's black rev 22.8.0 pinned in
.pre-commit-config.yaml). cache-transition-resilience.md's prettier
drift predates this PR (introduced by #75) and is unrelated to its
content - swept here since the "Formatting and static type checking"
check runs pre-commit against all files, not just the diff, and this
PR's own CI needs to go green.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: WilfordGrimley

.github/scripts/publish_wiki.py

@@ -13,14 +13,53 @@
 in the mapping's legacy_pages. That distinction (marker present = we own
 it) is the only thing that makes "regenerate" safe to run unattended.
 
+LINK REWRITING (the part docs-lint.py can never check): docs/ uses its own
+[[file.md]] wiki-link convention, meant to render as plain text on GitHub's
+normal file view. GitHub WIKI pages give `[[...]]` a second, DIFFERENT
+meaning — native wiki auto-linking, keyed on the literal bracketed text as
+a page name. Copying a docs/ page's body verbatim into a wiki page lets
+GitHub's wiki engine reinterpret our own convention out from under us:
+`[[../troubleshooting.md]]` auto-links to a page literally named
+"../troubleshooting.md" (mangled into a dead slug), and `[[printing-tags.md]]`
+auto-links to "printing-tags.md" (the raw docs/ filename's casing), not the
+actual published page name "Printing-Tags". Both bugs are invisible to
+docs_lint.py, which only checks that a link resolves inside the docs/ tree
+itself — the wiki's own `[[...]]` reinterpretation is a second transform
+downstream of that check, and this is the only place it can be caught.
+
+Every internal link (both `[[wiki]]` and markdown `[text](path)` styles) is
+therefore resolved against its SOURCE file's real repo path, then mapped
+through wiki-publish-map.json: a target that's itself a published page
+becomes a same-wiki link using its REAL page name (never the raw docs/
+filename); a target that exists in the repo but isn't published becomes an
+absolute GitHub blob URL (never a guessed wiki slug); a target that resolves
+to neither a wiki page nor a real repo file is a hard error - the publish
+FAILS rather than shipping a page with a link nobody can follow.
+
 Exits 0 whether or not anything changed; the calling workflow decides
 whether to commit based on `git status --porcelain` in the wiki dir.
 """
+
 import json
+import re
 import sys
 from pathlib import Path
 
 GENERATED_MARKER = "<!-- GENERATED PAGE"
+GITHUB_BLOB_BASE = "https://github.com/ProxyPrints/ProxyPrints.github.io/blob/master/"
+
+# Order matters: fence/inline must be tried before the link alternatives so
+# code content is never rewritten - both this repo's own [[wiki-link]] prose
+# convention AND real markdown links appear verbatim as ILLUSTRATIVE EXAMPLES
+# inside backticks in some docs (e.g. documentation-process.md explaining
+# this very system) and must not be touched.
+LINK_TOKEN_RE = re.compile(
+    r"(?P<fence>```.*?```)"
+    r"|(?P<inline>`[^`\n]+`)"
+    r"|\[\[(?P<wikilink>[^\]]+)\]\]"
+    r"|(?<!!)\[(?P<mdtext>[^\]]*)\]\((?P<mdpath>[^)]+)\)",
+    re.DOTALL,
+)
 
 
 def generated_header(source_path: str) -> str:
@@ -37,9 +76,92 @@ def load_mapping(repo_root: Path) -> dict:
         return json.load(f)
 
 
-def write_page(wiki_dir: Path, wiki_name: str, source_path: Path, source_rel: str) -> None:
+def build_repo_to_wiki_map(mapping: dict) -> dict:
+    return {page["source"]: page["wiki"] for group in mapping["groups"] for page in group["pages"]}
+
+
+def resolve_repo_relative(repo_root: Path, source_rel: str, target: str) -> str | None:
+    """
+    Resolve a link target string against source_rel's own directory. Returns
+    a repo-relative posix path, or None if target isn't a local-file
+    reference at all (external URL, bare anchor, mailto:).
+    """
+    if target.startswith(("http://", "https://", "mailto:")) or target.startswith("#"):
+        return None
+    path_part = target.split("#", 1)[0]
+    if not path_part:
+        return None
+    source_dir = (repo_root / source_rel).parent
+    resolved = (source_dir / path_part).resolve()
+    try:
+        rel = resolved.relative_to(repo_root.resolve())
+    except ValueError:
+        return None  # escaped the repo root somehow - treat as external, not our problem
+    return rel.as_posix()
+
+
+def rewrite_link(
+    repo_root: Path, source_rel: str, target: str, repo_to_wiki: dict, display_text: str | None
+) -> tuple[str | None, str | None]:
+    """Returns (new_markdown_link, error_message) - exactly one is non-None, unless
+    target wasn't a local path at all (both None - caller leaves the original text)."""
+    resolved_rel = resolve_repo_relative(repo_root, source_rel, target)
+    if resolved_rel is None:
+        return None, None
+
+    wiki_name = repo_to_wiki.get(resolved_rel)
+    if wiki_name:
+        text = display_text or wiki_name
+        return f"[{text}]({wiki_name})", None
+
+    if not (repo_root / resolved_rel).is_file():
+        return None, (
+            f"in {source_rel}: link to `{target}` resolves to `{resolved_rel}`, which is "
+            f"neither a published wiki page nor a real file in the repo"
+        )
+
+    text = display_text or resolved_rel.rsplit("/", 1)[-1]
+    return f"[{text}]({GITHUB_BLOB_BASE}{resolved_rel})", None
+
+
+def transform_links(repo_root: Path, source_rel: str, text: str, repo_to_wiki: dict, errors: list[str]) -> str:
+    def repl(m: re.Match) -> str:
+        if m.group("fence") is not None or m.group("inline") is not None:
+            return m.group(0)
+
+        if m.group("wikilink") is not None:
+            target = m.group("wikilink")
+            if not (target.endswith(".md") or "/" in target):
+                return m.group(0)  # e.g. [[routes]] - a literal TOML table, not a doc link
+            new_link, err = rewrite_link(repo_root, source_rel, target, repo_to_wiki, display_text=None)
+            if err:
+                errors.append(err)
+                return m.group(0)
+            return new_link or m.group(0)
+
+        # markdown link
+        mdtext, mdpath = m.group("mdtext"), m.group("mdpath")
+        new_link, err = rewrite_link(repo_root, source_rel, mdpath, repo_to_wiki, display_text=mdtext or None)
+        if err:
+            errors.append(err)
+            return m.group(0)
+        return new_link if new_link else m.group(0)
+
+    return LINK_TOKEN_RE.sub(repl, text)
+
+
+def write_page(
+    wiki_dir: Path,
+    wiki_name: str,
+    source_path: Path,
+    source_rel: str,
+    repo_root: Path,
+    repo_to_wiki: dict,
+    errors: list[str],
+) -> None:
     body = source_path.read_text()
-    content = generated_header(source_rel) + body
+    transformed = transform_links(repo_root, source_rel, body, repo_to_wiki, errors)
+    content = generated_header(source_rel) + transformed
     (wiki_dir / f"{wiki_name}.md").write_text(content)
 
 
@@ -58,8 +180,11 @@ def write_pointer_page(wiki_dir: Path, wiki_name: str, points_to: str, note: str
     (wiki_dir / f"{wiki_name}.md").write_text(content)
 
 
-def build_home_and_sidebar(repo_root: Path, wiki_dir: Path, mapping: dict) -> None:
-    intro = (repo_root / "docs" / "wiki-home-intro.md").read_text().rstrip() + "\n"
+def build_home_and_sidebar(
+    repo_root: Path, wiki_dir: Path, mapping: dict, repo_to_wiki: dict, errors: list[str]
+) -> None:
+    intro_raw = (repo_root / "docs" / "wiki-home-intro.md").read_text().rstrip() + "\n"
+    intro = transform_links(repo_root, "docs/wiki-home-intro.md", intro_raw, repo_to_wiki, errors)
 
     home_lines = [
         generated_header("docs/wiki-home-intro.md + .github/wiki-publish-map.json"),
@@ -106,6 +231,8 @@ def main() -> int:
     wiki_dir = Path(sys.argv[2]).resolve()
 
     mapping = load_mapping(repo_root)
+    repo_to_wiki = build_repo_to_wiki_map(mapping)
+    errors: list[str] = []
 
     managed_names = set()
     for group in mapping["groups"]:
@@ -115,7 +242,7 @@ def main() -> int:
             if not source_path.is_file():
                 print(f"::error::wiki-publish-map.json references missing source {source_rel}")
                 return 1
-            write_page(wiki_dir, page["wiki"], source_path, source_rel)
+            write_page(wiki_dir, page["wiki"], source_path, source_rel, repo_root, repo_to_wiki, errors)
             managed_names.add(page["wiki"])
             print(f"wrote {page['wiki']}.md <- {source_rel}")
 
@@ -130,9 +257,21 @@ def main() -> int:
         managed_names.add(pointer["wiki"])
         print(f"wrote {pointer['wiki']}.md (pointer -> {pointer['points_to']})")
 
-    build_home_and_sidebar(repo_root, wiki_dir, mapping)
+    build_home_and_sidebar(repo_root, wiki_dir, mapping, repo_to_wiki, errors)
     managed_names.update({"Home", "_Sidebar"})
 
+    if errors:
+        for err in errors:
+            print(f"::error::{err}")
+        print(
+            f"\n{len(errors)} link-resolution error(s) - failing the publish. "
+            f"docs_lint.py cannot catch this class of break (it only checks links "
+            f"resolve inside docs/ itself, not what they become after this script's "
+            f"wiki-name/blob-URL rewrite) - fix the source link or add the missing "
+            f"page to wiki-publish-map.json."
+        )
+        return 1
+
     # Prune generated pages whose source left the mapping. Never touch a
     # page that doesn't carry our marker — that's hand-maintained content.
     for existing in wiki_dir.glob("*.md"):

.github/wiki-publish-map.json

@@ -5,9 +5,17 @@
       "title": "Understanding the system",
       "pages": [
         { "source": "docs/overview.md", "wiki": "Overview" },
+        {
+          "source": "docs/documentation-process.md",
+          "wiki": "Documentation-Process"
+        },
         { "source": "docs/theory.md", "wiki": "Theory" },
         { "source": "docs/federation-v1.md", "wiki": "Federation-v1" },
         { "source": "docs/upstreaming/vote-system.md", "wiki": "Vote-System" },
+        {
+          "source": "docs/upstreaming/upstream-wiki-drift.md",
+          "wiki": "Upstream-Wiki-Drift"
+        },
         { "source": "docs/features/printing-tags.md", "wiki": "Printing-Tags" },
         {
           "source": "docs/features/catalog-completion-plan.md",

docs/README.md

@@ -94,10 +94,12 @@ Deployment, incidents, and cross-session lessons.
 
 One-word status per doc; see each file for the full survey/spec.
 
-| Doc                                                                                                                                                      | Status |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
-| [`proposals/proposal-f-public-stats-page.md`](proposals/proposal-f-public-stats-page.md) — public `/stats` transparency page                             | HOLD   |
-| [`proposals/proposal-g-user-accounts-saved-decks.md`](proposals/proposal-g-user-accounts-saved-decks.md) — user accounts + saved decks via Discord OAuth | HOLD   |
+| Doc                                                                                                                                                                      | Status   |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| [`proposals/proposal-b-bleed-normalization.md`](proposals/proposal-b-bleed-normalization.md) — export-time per-side bleed normalization                                  | BUILDING |
+| [`proposals/proposal-c-context-menu-restyle.md`](proposals/proposal-c-context-menu-restyle.md) — right-click/long-press context menu (shipped); restyle direction (HOLD) | PARTIAL  |
+| [`proposals/proposal-f-public-stats-page.md`](proposals/proposal-f-public-stats-page.md) — public `/stats` transparency page                                             | HOLD     |
+| [`proposals/proposal-g-user-accounts-saved-decks.md`](proposals/proposal-g-user-accounts-saved-decks.md) — user accounts + saved decks via Discord OAuth                 | HOLD     |
 
 Not every shipped proposal-lettered feature has a survey doc here — some
 (e.g. Proposal A, Proposal D) went straight from idea to shipped PR without

docs/features/catalog-completion-plan.md

@@ -402,7 +402,7 @@ and live-traffic-fairness control, not a cost control, so the WAIT sequencing ab
 
 ---
 
-## Part 3 — Shared evidence-recovery module (built, HOLD #P3 — write pass pending)
+## Part 3 — Shared evidence-recovery module (write pass complete, merged 2026-07-18)
 
 Insight: artist is a property of the ARTWORK, not the printing — art-
 identity evidence supports artist votes even where printing votes are
@@ -561,7 +561,7 @@ pilot wasn't stopped for this.
 
 ---
 
-## Part 4 — LANDS (artist-decomposed identification)
+## Part 4 — LANDS (artist-decomposed identification) (confirmed unstarted 2026-07-18; HOLD #B prep queued)
 
 Target pool: unresolved basic lands (Plains/Island/Swamp/Mountain/Forest/
 Wastes + Snow-Covered) OR any name whose candidate count exceeded the
@@ -758,8 +758,9 @@ over a closed codebook.
     this is _recovering_ an already-successful match, not matching
     cold), then run against the full OCR+fallback population
     (~5,773 cards after phash-priority dedup) in the background —
-    see the follow-up entry below for the completed numbers. d=0
-    sibling propagation: 987 votes would cast (see the corrected number
+    **completed 2026-07-18, see the write-pass entry below for the real
+    numbers** (4,804/4,804 OCR recovered, 590/595 fallback recovered).
+    d=0 sibling propagation: 987 votes would cast (see the corrected number
     above), safely re-runnable, idempotent (excludes cards with an
     existing vote from its own `anonymous_id`).
   - **Rails**: `verify_no_single_machine_vote_resolutions` (zero-
@@ -789,9 +790,17 @@ over a closed codebook.
     introduced by Part 3 (identical for every existing artist machine vote,
     not just these) — flagged here for whoever next touches
     question_feed's artist tier, not fixed as part of this work.
-  - **HOLD #P3 stands**: no vote has been written to the live database
-    by this pass. The write pass (`--write`) runs only after explicit
-    go-ahead.
+  - **HOLD #P3 cleared, write pass complete** (2026-07-18,
+    `run_id=20260718T145157-a12b1387`): 13,275 real votes now live
+    (7,131 `CardArtistVote` + 6,144 `CardTagVote`) — phash 750 recovered
+    → 1,500 combined votes, d=0 siblings 987 artist votes, OCR
+    4,804/4,804 recovered, fallback 590/595 recovered, OCR+fallback
+    combined → 10,788 votes. All hard bounds passed (phash exactly 750,
+    siblings exactly 987, OCR+fallback within the ≤11,546-vote ceiling).
+    Zero-resolution assertion re-run at full population (not just the
+    command's own 14-card sample gate): 0/7,124 violations — no card
+    resolved on machine-only votes anywhere in the run. Full detail:
+    [`docs/reports/2026-07-18-part3-write-pass-complete.md`](../reports/2026-07-18-part3-write-pass-complete.md).
   - Item 1's 15 permanent `content_phash` backfill failures: scattered
     across 6 distinct community Drive sources (CompC ×1,
     Hathwellcrisping ×4, LePoulpe_Dec_2023 ×2, RustyShackleford ×6,

docs/proposals/proposal-b-bleed-normalization.md

@@ -1,5 +1,5 @@
 As of: 2026-07-18
-What this is: Proposal B — export-time per-side bleed normalization. APPROVED spec, recovered after a courier loss (it previously existed only as a chat artifact, never committed — this file is that gap fixed). Core algorithm + real-render wiring shipped this pass (see "Shipped vs. not yet built" below); the prior-resolution batch fetch, manual-override UI + persistence, and preview badge remain. Implementation notes and any contradictions found against real code are appended at the bottom rather than edited into the spec text above them, so the approved spec stays a verbatim record of what was approved.
+What this is: Proposal B — export-time per-side bleed normalization. APPROVED spec, recovered after a courier loss (it previously existed only as a chat artifact, never committed — this file is that gap fixed). Core algorithm + real-render wiring shipped this pass, and the prior-resolution batch fetch has since shipped as PR-1 (see "Shipped vs. not yet built" below); the manual-override UI + persistence and preview badge remain. Implementation notes and any contradictions found against real code are appended at the bottom rather than edited into the spec text above them, so the approved spec stays a verbatim record of what was approved.
 
 ## Approved spec (verbatim)
 

docs/proposals/proposal-g-user-accounts-saved-decks.md

@@ -596,6 +596,10 @@ with the saved-decks build.
    work finishes — G then builds **ahead of** C, E-3, and F, since it's
    user-facing value and those are polish. Backend (model + endpoints) is
    its own first PR; frontend is a second PR after that merges.
+   **Queue cleared, 2026-07-18**: all of the above have since merged (E-1
+   #61, E-2 #62, Level-2 grid fix #63, audit pass #64, GIS error UX #65,
+   Proposal B core #66 + PR-1 #72, Proposal C part (a) #67) — nothing
+   remains ahead of G in this build order.
 2. **Where "Load"/"My Decks" lives — resolved, round 2 supersedes round 1.**
    Round 1 proposed folding it into the Import dropdown; round 2 replaces
    that with a **top-level nav entry**, rendered only when logged in (the