From 1016e2d614665eb6a5b2c066aa054c8086401d22 Mon Sep 17 00:00:00 2001
From: cdeust <cdeust@icloud.com>
Date: Wed, 13 May 2026 11:02:40 +0200
Subject: [PATCH] feat(wiki): handler-layer redirect mechanics + wiki_rename
 (ADR-2244 Phase 3.2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires the Phase 3 data model (#33) into the read path and adds a new
write handler that performs the rename + stub atomically. With this
change ``wiki_rename old.md new.md`` produces:

  * ``new.md``  — the original content moved verbatim (id preserved)
  * ``old.md``  — a redirect stub pointing at new.md (with redirect_id
                  = source page id, for future id-based resolution)

And ``wiki_read old.md`` then returns the content of ``new.md`` along
with ``redirect_chain: ["old.md", "new.md"]``. Inbound links to the
old path keep working through the migration.

Handler changes
---------------

* ``wiki_read``  — follow redirect stubs transparently up to 5 hops.
                   ``follow_redirects: false`` opts out (admin/migration
                   tooling that needs to inspect the stub itself).
                   New response field: ``redirect_chain``.

* ``wiki_list``  — exclude redirect stubs from the listing by default.
                   ``include_redirects: true`` opts in. New response
                   field: ``redirect_count``.

* ``wiki_reindex`` — drop redirect stubs from .generated/INDEX.md and
                     surface the count by kind in the response. The
                     index now lists only live pages, which is what
                     readers actually want.

* ``wiki_rename``  — NEW. Move a page from one path to another and
                     leave a stub at the old path. Refuses to operate
                     on pages without a stable frontmatter id (run
                     ``scripts/wiki_backfill_ids.py --apply`` first),
                     refuses to chain stubs (rename the terminal page
                     instead), refuses to overwrite an existing
                     destination unless ``overwrite_dest=true``.

Tool registry: ``wiki_rename`` registered alongside the other 8 wiki
tools. ``wiki_read`` and ``wiki_list`` MCP signatures extended with
their new optional parameters.

Stub semantics
--------------

The stub carries ``redirect_id = <source page id>`` so future id-based
resolution (which a follow-up will add for cross-rename resolution
when the path itself is renamed twice) works. ``redirect_to`` is
populated with the new path as the cheap path-based resolution
target. Both forms are emitted; the id wins when an id-aware reader
arrives.

Tests
-----

``tests_py/handlers/test_wiki_redirect_handlers.py`` (NEW) — 20 tests
covering every handler change:

  read:
    - returns content for a normal page (chain = [])
    - follows single-hop redirect
    - follows multi-hop chain (3 pages, 2 hops)
    - ``follow_redirects: false`` returns the stub itself
    - cycle returns error
    - dangling redirect returns error
    - missing source returns error

  list:
    - excludes stubs by default; redirect_count surfaced
    - ``include_redirects: true`` returns both
    - redirect_count is 0 when no stubs

  reindex:
    - stubs absent from INDEX.md; by_kind counts only live pages

  rename:
    - creates stub at old path with correct redirect_to, redirect_id,
      redirect_reason
    - refuses missing source
    - refuses source without id
    - refuses existing destination
    - ``overwrite_dest=true`` works
    - refuses to chain stubs
    - refuses same path
    - end-to-end: rename then read resolves to the new content
    - body preserved verbatim through the move

Targeted suite: 86 passed (Phase 3 + Phase 3.2 surface).
Broader: tests_py/core/ + tests_py/shared/ + tests_py/scripts/ +
relevant tests_py/handlers/ → 2075 passed.
``ruff format --check`` and ``ruff check`` clean.

What still ships in a follow-up
-------------------------------

  * ID→path index for ID-only redirect resolution (currently only
    path-based chain walking works; id-only stubs return None from
    resolve_chain so they error in wiki_read with a clear message).
  * Phase 4 bulk migration script that loops wiki_rename over the 88
    known pollution paths (.md.md slug bug, timestamp-slugs, path-leak
    titles) — gated on this PR + #33 landing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 mcp_server/handlers/wiki_list.py              |  78 ++++-
 mcp_server/handlers/wiki_read.py              | 113 +++++-
 mcp_server/handlers/wiki_reindex.py           |  39 ++-
 mcp_server/handlers/wiki_rename.py            | 175 ++++++++++
 mcp_server/tool_registry_wiki.py              |  57 +++-
 .../handlers/test_wiki_redirect_handlers.py   | 321 ++++++++++++++++++
 6 files changed, 752 insertions(+), 31 deletions(-)
 create mode 100644 mcp_server/handlers/wiki_rename.py
 create mode 100644 tests_py/handlers/test_wiki_redirect_handlers.py

diff --git a/mcp_server/handlers/wiki_list.py b/mcp_server/handlers/wiki_list.py
index 5839f254..9141ac6c 100644
--- a/mcp_server/handlers/wiki_list.py
+++ b/mcp_server/handlers/wiki_list.py
@@ -1,13 +1,19 @@
-"""Handler: wiki_list — enumerate authored wiki pages."""
+"""Handler: wiki_list — enumerate authored wiki pages.
+
+Phase 3.2 of ADR-2244: redirect stubs are filtered from the listing by
+default. Pass ``include_redirects: true`` to see them — useful for
+migration tooling that needs to audit or clean up old paths.
+"""
 
 from __future__ import annotations
 
 from typing import Any
 
 from mcp_server.core.wiki_layout import PAGE_KINDS
-from mcp_server.infrastructure.config import WIKI_ROOT
-from mcp_server.infrastructure.wiki_store import list_pages
+from mcp_server.core.wiki_redirect import is_redirect, parse_frontmatter
 from mcp_server.handlers._tool_meta import READ_ONLY
+from mcp_server.infrastructure.config import WIKI_ROOT
+from mcp_server.infrastructure.wiki_store import list_pages, read_page
 
 schema = {
     "title": "Wiki — list pages",
@@ -16,13 +22,13 @@
         "Enumerate every authored wiki page under ~/.claude/methodology/wiki/, "
         "filesystem-walked from the wiki root. Optionally restrict by kind "
         "(adr, specs, guides, reference, conventions, lessons, notes, "
-        "journal, files). Use this to browse what already exists before "
-        "writing a new page, to feed a downstream selector, or to build a "
-        "manual cross-reference. Read-only; never modifies anything. Distinct "
-        "from `wiki_reindex` which generates the .generated/INDEX.md from the "
-        "same enumeration, and from `wiki_read` which fetches one page's "
-        "content. Latency <50ms even for thousands of pages. Returns "
-        "{root, count, pages: list[wiki-relative path]}."
+        "journal, files). Redirect stubs (frontmatter ``redirect_to:`` or "
+        "``redirect_id:``) are excluded by default; pass "
+        "``include_redirects: true`` to see them. Read-only; never modifies "
+        "anything. Distinct from `wiki_reindex` which generates the "
+        ".generated/INDEX.md from the same enumeration, and from `wiki_read` "
+        "which fetches one page's content. Latency <50ms even for thousands "
+        "of pages. Returns {root, count, pages, redirect_count}."
     ),
     "inputSchema": {
         "type": "object",
@@ -37,16 +43,64 @@
                 "enum": list(PAGE_KINDS),
                 "examples": ["adr", "lessons", "notes"],
             },
+            "include_redirects": {
+                "type": "boolean",
+                "description": (
+                    "When true, redirect stubs are included in the listing. "
+                    "Default false — most callers want the live pages only."
+                ),
+                "default": False,
+            },
         },
     },
 }
 
 
+def _is_redirect_page(rel_path: str) -> bool:
+    """True iff the page at ``rel_path`` declares a redirect in its frontmatter.
+
+    Reads the file via the sandboxed store and parses only the
+    frontmatter block — cheap on a 9000-page wiki because the
+    frontmatter is at the top of the file and we don't need to load
+    the body.
+    """
+    try:
+        content = read_page(WIKI_ROOT, rel_path)
+    except (ValueError, OSError):
+        return False
+    if content is None:
+        return False
+    return is_redirect(parse_frontmatter(content))
+
+
 async def handler(args: dict[str, Any] | None = None) -> dict[str, Any]:
     args = args or {}
     kind = args.get("kind")
+    include_redirects = bool(args.get("include_redirects", False))
+
     try:
-        pages = list_pages(WIKI_ROOT, kind=kind if kind else None)
+        all_pages = list_pages(WIKI_ROOT, kind=kind if kind else None)
     except (ValueError, OSError) as exc:
         return {"error": f"list failed: {exc}"}
-    return {"root": str(WIKI_ROOT), "count": len(pages), "pages": pages}
+
+    if include_redirects:
+        return {
+            "root": str(WIKI_ROOT),
+            "count": len(all_pages),
+            "pages": all_pages,
+            "redirect_count": 0,  # not partitioned in this mode
+        }
+
+    live_pages: list[str] = []
+    redirect_count = 0
+    for rel in all_pages:
+        if _is_redirect_page(rel):
+            redirect_count += 1
+        else:
+            live_pages.append(rel)
+    return {
+        "root": str(WIKI_ROOT),
+        "count": len(live_pages),
+        "pages": live_pages,
+        "redirect_count": redirect_count,
+    }
diff --git a/mcp_server/handlers/wiki_read.py b/mcp_server/handlers/wiki_read.py
index c77310d7..640b68f2 100644
--- a/mcp_server/handlers/wiki_read.py
+++ b/mcp_server/handlers/wiki_read.py
@@ -1,12 +1,29 @@
-"""Handler: wiki_read — fetch the raw markdown of a wiki page."""
+"""Handler: wiki_read — fetch the raw markdown of a wiki page.
+
+Phase 3.2 of ADR-2244: when the page at the requested path is a redirect
+stub, follow the chain transparently and return the target's content.
+The response carries a ``redirect_chain`` array recording the paths
+walked, so callers can detect and surface a "this page moved" hint to
+their users when the caller cares.
+
+Caller can opt out of redirect-following via ``follow_redirects: false``
+to read the stub itself (useful for admin / migration tooling that
+needs to inspect or rewrite the stub).
+"""
 
 from __future__ import annotations
 
 from typing import Any
 
+from mcp_server.core.wiki_redirect import (
+    MAX_REDIRECT_DEPTH,
+    parse_frontmatter,
+    parse_redirect,
+    resolve_chain,
+)
+from mcp_server.handlers._tool_meta import READ_ONLY
 from mcp_server.infrastructure.config import WIKI_ROOT
 from mcp_server.infrastructure.wiki_store import read_page
-from mcp_server.handlers._tool_meta import READ_ONLY
 
 schema = {
     "title": "Wiki — read page",
@@ -14,12 +31,15 @@
     "description": (
         "Fetch the raw markdown source of one wiki page by its wiki-relative "
         "path. Path resolution is sandboxed under the wiki root — absolute "
-        "paths and `../` traversal are rejected at the storage layer. Read-"
-        "only; never mutates state. Use this to quote, link, or edit-prep an "
-        "ADR/spec/lesson page before further action. Distinct from `wiki_list` "
-        "which enumerates available pages, and from `wiki_export` which "
-        "renders a page through Pandoc to PDF/DOCX/HTML. Latency <10ms. "
-        "Returns {path, content (markdown verbatim), root} or {error}."
+        "paths and `../` traversal are rejected at the storage layer. When "
+        "the page is a redirect stub (frontmatter ``redirect_to:`` or "
+        "``redirect_id:``) the chain is followed transparently up to "
+        f"{MAX_REDIRECT_DEPTH} hops; cycles and dangling targets surface as "
+        "errors. Pass ``follow_redirects: false`` to read the stub itself. "
+        "Read-only; never mutates state. Distinct from `wiki_list` which "
+        "enumerates available pages, and from `wiki_export` which renders a "
+        "page through Pandoc to PDF/DOCX/HTML. Latency <10ms. Returns "
+        "{path, content, root, redirect_chain} or {error}."
     ),
     "inputSchema": {
         "type": "object",
@@ -38,20 +58,95 @@
                     "specs/cortex/recall-pipeline.md",
                 ],
             },
+            "follow_redirects": {
+                "type": "boolean",
+                "description": (
+                    "When true (default) redirect stubs are followed "
+                    "transparently. When false the stub itself is returned, "
+                    "which is useful for admin / migration tooling."
+                ),
+                "default": True,
+            },
         },
     },
 }
 
 
+def _frontmatter_reader(rel_path: str) -> dict[str, object]:
+    """Read a page's frontmatter from disk via the sandboxed store.
+
+    Returns an empty dict for missing or unreadable pages — that matches
+    the ``parse_redirect`` contract (no redirect = no decoration).
+    """
+    try:
+        content = read_page(WIKI_ROOT, rel_path)
+    except (ValueError, OSError):
+        return {}
+    if content is None:
+        return {}
+    return parse_frontmatter(content)
+
+
 async def handler(args: dict[str, Any] | None = None) -> dict[str, Any]:
     args = args or {}
     rel_path = str(args.get("path") or "").strip()
     if not rel_path:
         return {"error": "path is required"}
+    follow = bool(args.get("follow_redirects", True))
+
     try:
         content = read_page(WIKI_ROOT, rel_path)
     except (ValueError, OSError) as exc:
         return {"error": f"read failed: {exc}"}
     if content is None:
         return {"error": f"page not found: {rel_path}"}
-    return {"path": rel_path, "content": content, "root": str(WIKI_ROOT)}
+
+    # Fast path: caller wants the stub itself, or the page isn't a stub.
+    if not follow:
+        return {
+            "path": rel_path,
+            "content": content,
+            "root": str(WIKI_ROOT),
+            "redirect_chain": [],
+        }
+
+    fm = parse_frontmatter(content)
+    if parse_redirect(fm) is None:
+        return {
+            "path": rel_path,
+            "content": content,
+            "root": str(WIKI_ROOT),
+            "redirect_chain": [],
+        }
+
+    # Stub — walk the chain to the terminal page.
+    resolved = resolve_chain(rel_path, _frontmatter_reader)
+    if resolved is None:
+        return {
+            "error": (
+                f"redirect chain from {rel_path} could not be resolved "
+                f"(cycle, depth > {MAX_REDIRECT_DEPTH}, or id-only redirect "
+                f"without a path)"
+            ),
+            "path": rel_path,
+        }
+
+    try:
+        target_content = read_page(WIKI_ROOT, resolved.final_path)
+    except (ValueError, OSError) as exc:
+        return {"error": f"redirect target read failed: {exc}"}
+    if target_content is None:
+        return {
+            "error": (
+                f"redirect chain from {rel_path} terminates at "
+                f"{resolved.final_path}, but that page no longer exists"
+            ),
+            "redirect_chain": list(resolved.chain),
+        }
+
+    return {
+        "path": resolved.final_path,
+        "content": target_content,
+        "root": str(WIKI_ROOT),
+        "redirect_chain": list(resolved.chain),
+    }
diff --git a/mcp_server/handlers/wiki_reindex.py b/mcp_server/handlers/wiki_reindex.py
index 3f04bec2..4df0e6c7 100644
--- a/mcp_server/handlers/wiki_reindex.py
+++ b/mcp_server/handlers/wiki_reindex.py
@@ -12,10 +12,11 @@
 from typing import Any
 
 from mcp_server.core.wiki_layout import PAGE_KINDS, index_path
+from mcp_server.core.wiki_redirect import is_redirect, parse_frontmatter
+from mcp_server.handlers._tool_meta import IDEMPOTENT_WRITE
 from mcp_server.infrastructure.config import WIKI_ROOT
 from mcp_server.infrastructure.file_io import ensure_dir
-from mcp_server.infrastructure.wiki_store import list_pages
-from mcp_server.handlers._tool_meta import IDEMPOTENT_WRITE
+from mcp_server.infrastructure.wiki_store import list_pages, read_page
 
 _BANNER = (
     "<!-- Generated by Cortex wiki_reindex — the authored pages are the "
@@ -68,13 +69,43 @@ def _render_index(grouped: dict[str, list[str]]) -> str:
     return "\n".join(lines)
 
 
+def _is_redirect_page(rel_path: str) -> bool:
+    """True iff the page declares a redirect (read frontmatter from disk)."""
+    try:
+        content = read_page(WIKI_ROOT, rel_path)
+    except (ValueError, OSError):
+        return False
+    if content is None:
+        return False
+    return is_redirect(parse_frontmatter(content))
+
+
 async def handler(args: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Phase 3.2 of ADR-2244: redirect stubs are excluded from the index.
+
+    The reader-facing INDEX.md should only list live pages — a stub at
+    an old path is a navigation aid for inbound links, not content to
+    advertise. The summary still reports the count of stubs so callers
+    have visibility.
+    """
     grouped: dict[str, list[str]] = {}
+    redirects_by_kind: dict[str, int] = {}
     for kind in PAGE_KINDS:
         try:
-            grouped[kind] = list_pages(WIKI_ROOT, kind=kind)
+            all_pages = list_pages(WIKI_ROOT, kind=kind)
         except (ValueError, OSError):
             grouped[kind] = []
+            redirects_by_kind[kind] = 0
+            continue
+        live: list[str] = []
+        n_redirect = 0
+        for rel in all_pages:
+            if _is_redirect_page(rel):
+                n_redirect += 1
+            else:
+                live.append(rel)
+        grouped[kind] = live
+        redirects_by_kind[kind] = n_redirect
 
     content = _render_index(grouped)
     target = Path(WIKI_ROOT) / str(index_path())
@@ -87,5 +118,7 @@ async def handler(args: dict[str, Any] | None = None) -> dict[str, Any]:
         "path": str(index_path()),
         "total_pages": sum(len(v) for v in grouped.values()),
         "by_kind": {k: len(v) for k, v in grouped.items()},
+        "redirects_by_kind": redirects_by_kind,
+        "redirect_count": sum(redirects_by_kind.values()),
         "root": str(WIKI_ROOT),
     }
diff --git a/mcp_server/handlers/wiki_rename.py b/mcp_server/handlers/wiki_rename.py
new file mode 100644
index 00000000..49d544b3
--- /dev/null
+++ b/mcp_server/handlers/wiki_rename.py
@@ -0,0 +1,175 @@
+"""Handler: wiki_rename — move a page and leave a redirect stub.
+
+Phase 3.2 of ADR-2244. The operation:
+
+  1. Read source page; require valid frontmatter ``id`` (Phase 3 invariant).
+  2. Refuse if source is itself a redirect stub.
+  3. Refuse if destination already exists (unless ``overwrite_dest`` true).
+  4. Write source content at destination path.
+  5. Replace source with a redirect stub pointing at destination (carrying
+     the source's id-or-target id).
+
+This is the building block for the Phase 4 bulk-rename script
+(``.md.md`` cleanup, timestamp-slug fixes, ``file-*`` → ``files/``
+moves). It is intentionally a small, well-tested handler that does one
+move at a time; the bulk migration script will loop over it.
+
+The two writes happen as best-effort sequential atomic writes. If the
+destination write succeeds but the stub write fails, the caller sees an
+error AND the page exists at both paths — investigated and reverted
+manually. We do not roll back the destination write because that would
+risk losing the new copy if the rollback itself fails. The bulk migration
+script logs every move so any partial state is recoverable.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from mcp_server.core.wiki_identity import extract_page_id, is_valid_page_id
+from mcp_server.core.wiki_redirect import (
+    build_redirect_stub,
+    is_redirect,
+    parse_frontmatter,
+)
+from mcp_server.handlers._tool_meta import IDEMPOTENT_WRITE
+from mcp_server.infrastructure.config import WIKI_ROOT
+from mcp_server.infrastructure.wiki_store import WikiExists, read_page, write_page
+
+
+schema = {
+    "title": "Wiki — rename page",
+    "annotations": IDEMPOTENT_WRITE,
+    "description": (
+        "Move a wiki page from ``from_path`` to ``to_path`` and leave a "
+        "redirect stub at the old location pointing to the new one. "
+        "Phase 3.2 of ADR-2244 — the move preserves inbound links because "
+        "``wiki_read`` follows redirect stubs transparently. Refuses to "
+        "operate on pages without a stable ``id`` field (run "
+        "``scripts/wiki_backfill_ids.py`` first) or on existing redirect "
+        "stubs. Returns {from_path, to_path, page_id, stub_created}."
+    ),
+    "inputSchema": {
+        "type": "object",
+        "required": ["from_path", "to_path"],
+        "properties": {
+            "from_path": {
+                "type": "string",
+                "description": "Current wiki-relative path of the page.",
+                "examples": ["adr/_general/2234-decision-001-zero-dependencies.md.md"],
+            },
+            "to_path": {
+                "type": "string",
+                "description": "Destination wiki-relative path.",
+                "examples": ["adr/_general/2234-zero-dependencies.md"],
+            },
+            "reason": {
+                "type": "string",
+                "description": (
+                    "Optional free-form rationale recorded in the redirect "
+                    "stub's frontmatter."
+                ),
+                "examples": [".md.md slug bug cleanup 2026-05-13"],
+            },
+            "overwrite_dest": {
+                "type": "boolean",
+                "description": (
+                    "When true, overwrite an existing destination. Default "
+                    "false — moves into occupied paths are an error."
+                ),
+                "default": False,
+            },
+        },
+    },
+}
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+async def handler(args: dict[str, Any] | None = None) -> dict[str, Any]:
+    args = args or {}
+    from_path = str(args.get("from_path") or "").strip()
+    to_path = str(args.get("to_path") or "").strip()
+    reason = str(args.get("reason") or "").strip()
+    overwrite_dest = bool(args.get("overwrite_dest", False))
+
+    if not from_path:
+        return {"error": "from_path is required"}
+    if not to_path:
+        return {"error": "to_path is required"}
+    if from_path == to_path:
+        return {"error": "from_path and to_path must differ"}
+
+    # ── Read + validate source ────────────────────────────────────────
+    try:
+        source_content = read_page(WIKI_ROOT, from_path)
+    except (ValueError, OSError) as exc:
+        return {"error": f"source read failed: {exc}"}
+    if source_content is None:
+        return {"error": f"source page not found: {from_path}"}
+
+    fm = parse_frontmatter(source_content)
+    if is_redirect(fm):
+        return {
+            "error": (
+                f"source is already a redirect stub: {from_path} — refusing "
+                "to chain stubs (rename the terminal page instead)"
+            )
+        }
+    page_id = extract_page_id(fm)
+    if page_id is None:
+        return {
+            "error": (
+                f"source page lacks a valid frontmatter id: {from_path}. "
+                "Run scripts/wiki_backfill_ids.py --apply first."
+            )
+        }
+
+    # ── Write destination ─────────────────────────────────────────────
+    write_mode = "replace" if overwrite_dest else "create"
+    try:
+        write_page(WIKI_ROOT, to_path, source_content, mode=write_mode)
+    except WikiExists:
+        return {
+            "error": (
+                f"destination already exists: {to_path} — pass overwrite_dest "
+                "to replace it"
+            )
+        }
+    except (ValueError, OSError) as exc:
+        return {"error": f"destination write failed: {exc}"}
+
+    # ── Write redirect stub at source ────────────────────────────────
+    # We use the (valid) page id from the source's frontmatter as the
+    # ``redirect_id`` so id-based resolution works once the read-handler
+    # supports it.
+    stub = build_redirect_stub(
+        target_path=to_path,
+        target_id=page_id if is_valid_page_id(page_id) else None,
+        target_title=str(fm.get("title", "")).strip(),
+        reason=reason,
+        created_at=_now_iso(),
+    )
+    try:
+        write_page(WIKI_ROOT, from_path, stub, mode="replace")
+    except (ValueError, OSError) as exc:
+        return {
+            "error": (
+                f"stub write failed: {exc}; destination already written at "
+                f"{to_path} — manual cleanup may be needed at {from_path}"
+            ),
+            "from_path": from_path,
+            "to_path": to_path,
+            "page_id": page_id,
+            "stub_created": False,
+        }
+
+    return {
+        "from_path": from_path,
+        "to_path": to_path,
+        "page_id": page_id,
+        "stub_created": True,
+    }
diff --git a/mcp_server/tool_registry_wiki.py b/mcp_server/tool_registry_wiki.py
index 2168d5fd..76bbcad5 100644
--- a/mcp_server/tool_registry_wiki.py
+++ b/mcp_server/tool_registry_wiki.py
@@ -17,11 +17,12 @@
     wiki_purge,
     wiki_read,
     wiki_reindex,
+    wiki_rename,
     wiki_verify,
     wiki_write,
 )
-from mcp_server.tool_error_handler import safe_handler
 from mcp_server.handlers._tool_meta import tool_kwargs
+from mcp_server.tool_error_handler import safe_handler
 
 
 def register(mcp: FastMCP) -> None:
@@ -34,6 +35,7 @@ def register(mcp: FastMCP) -> None:
     _register_wiki_reindex(mcp)
     _register_wiki_purge(mcp)
     _register_wiki_verify(mcp)
+    _register_wiki_rename(mcp)
 
 
 def _register_wiki_write(mcp: FastMCP) -> None:
@@ -59,19 +61,34 @@ async def tool_wiki_write(
 
 def _register_wiki_read(mcp: FastMCP) -> None:
     @mcp.tool(name="wiki_read", **tool_kwargs(wiki_read.schema))
-    async def tool_wiki_read(path: str) -> dict:
-        """Read the raw markdown of a wiki page by relative path."""
+    async def tool_wiki_read(path: str, follow_redirects: bool = True) -> dict:
+        """Read the raw markdown of a wiki page by relative path.
+
+        Phase 3.2 of ADR-2244: redirect stubs are followed transparently
+        by default. Pass ``follow_redirects=False`` to read the stub itself.
+        """
         return await safe_handler(
-            wiki_read.handler, {"path": path}, tool_name="wiki_read"
+            wiki_read.handler,
+            {"path": path, "follow_redirects": follow_redirects},
+            tool_name="wiki_read",
         )
 
 
 def _register_wiki_list(mcp: FastMCP) -> None:
     @mcp.tool(name="wiki_list", **tool_kwargs(wiki_list.schema))
-    async def tool_wiki_list(kind: str | None = None) -> dict:
-        """List authored wiki pages, optionally filtered by kind."""
+    async def tool_wiki_list(
+        kind: str | None = None,
+        include_redirects: bool = False,
+    ) -> dict:
+        """List authored wiki pages, optionally filtered by kind.
+
+        Phase 3.2 of ADR-2244: redirect stubs are excluded by default.
+        Pass ``include_redirects=True`` to see them.
+        """
         return await safe_handler(
-            wiki_list.handler, {"kind": kind}, tool_name="wiki_list"
+            wiki_list.handler,
+            {"kind": kind, "include_redirects": include_redirects},
+            tool_name="wiki_list",
         )
 
 
@@ -141,3 +158,29 @@ async def tool_wiki_verify(path: str | None = None) -> dict:
             {"path": path} if path else {},
             tool_name="wiki_verify",
         )
+
+
+def _register_wiki_rename(mcp: FastMCP) -> None:
+    @mcp.tool(name="wiki_rename", **tool_kwargs(wiki_rename.schema))
+    async def tool_wiki_rename(
+        from_path: str,
+        to_path: str,
+        reason: str = "",
+        overwrite_dest: bool = False,
+    ) -> dict:
+        """Move a page and leave a redirect stub at the old path.
+
+        Phase 3.2 of ADR-2244 — the building block for Phase 4 bulk renames.
+        Requires the source page to have a stable frontmatter ``id`` (run
+        ``scripts/wiki_backfill_ids.py --apply`` first).
+        """
+        return await safe_handler(
+            wiki_rename.handler,
+            {
+                "from_path": from_path,
+                "to_path": to_path,
+                "reason": reason,
+                "overwrite_dest": overwrite_dest,
+            },
+            tool_name="wiki_rename",
+        )
diff --git a/tests_py/handlers/test_wiki_redirect_handlers.py b/tests_py/handlers/test_wiki_redirect_handlers.py
new file mode 100644
index 00000000..41266206
--- /dev/null
+++ b/tests_py/handlers/test_wiki_redirect_handlers.py
@@ -0,0 +1,321 @@
+"""Handler-layer tests for redirect mechanics (ADR-2244 Phase 3.2).
+
+Exercises wiki_read (transparent follow), wiki_list / wiki_reindex
+(stub filtering), and wiki_rename (atomic move + stub creation) against
+a temporary wiki root.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from mcp_server.core.wiki_identity import (
+    extract_page_id,
+    generate_page_id,
+    is_valid_page_id,
+)
+from mcp_server.core.wiki_redirect import parse_frontmatter
+from mcp_server.handlers import wiki_list, wiki_read, wiki_reindex, wiki_rename
+
+
+# ── Test infrastructure ──────────────────────────────────────────────
+
+
+@pytest.fixture
+def tmp_wiki(tmp_path: Path, monkeypatch):
+    """Point WIKI_ROOT at a temp directory for the duration of the test.
+
+    The handlers import ``WIKI_ROOT`` at module load. The wiki_store
+    helpers each take a ``root`` argument, so the simplest reliable
+    intercept is to monkeypatch the symbol in every handler that
+    imports it.
+    """
+    # The handlers import ``from mcp_server.infrastructure.config import WIKI_ROOT``.
+    # Each handler now holds its own binding, so we patch each one.
+    for mod in (wiki_read, wiki_list, wiki_reindex, wiki_rename):
+        monkeypatch.setattr(mod, "WIKI_ROOT", str(tmp_path))
+    return tmp_path
+
+
+def _write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def _run(coro):
+    return asyncio.new_event_loop().run_until_complete(coro)
+
+
+def _page(page_id: str, title: str, body: str = "Body.") -> str:
+    return (
+        f"---\nid: {page_id}\ntitle: {title}\nkind: explanation\n"
+        f"lifecycle: seedling\naudience:\n  - developer\n"
+        f"provenance: human\n---\n\n# {title}\n\n{body}\n"
+    )
+
+
+def _stub(target_path: str, target_id: str | None = None, reason: str = "") -> str:
+    lines = ["---", f"redirect_to: {target_path}"]
+    if target_id:
+        lines.append(f"redirect_id: {target_id}")
+    if reason:
+        lines.append(f"redirect_reason: {reason}")
+    lines.append("---")
+    lines.append("")
+    lines.append("# Moved\n")
+    return "\n".join(lines)
+
+
+# ── wiki_read: redirect resolution ───────────────────────────────────
+
+
+def test_read_returns_content_for_normal_page(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "adr/0001-foo.md", _page(pid, "Foo"))
+
+    result = _run(wiki_read.handler({"path": "adr/0001-foo.md"}))
+    assert "content" in result
+    assert "title: Foo" in result["content"]
+    assert result["path"] == "adr/0001-foo.md"
+    assert result["redirect_chain"] == []
+
+
+def test_read_follows_single_hop_redirect(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "new.md", _page(pid, "New home"))
+    _write(tmp_wiki / "old.md", _stub("new.md", target_id=pid))
+
+    result = _run(wiki_read.handler({"path": "old.md"}))
+    assert "error" not in result
+    assert result["path"] == "new.md"
+    assert "title: New home" in result["content"]
+    assert result["redirect_chain"] == ["old.md", "new.md"]
+
+
+def test_read_follows_multi_hop_chain(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "v3.md", _page(pid, "Final"))
+    _write(tmp_wiki / "v2.md", _stub("v3.md"))
+    _write(tmp_wiki / "v1.md", _stub("v2.md"))
+
+    result = _run(wiki_read.handler({"path": "v1.md"}))
+    assert result["path"] == "v3.md"
+    assert "title: Final" in result["content"]
+    assert result["redirect_chain"] == ["v1.md", "v2.md", "v3.md"]
+
+
+def test_read_follow_false_returns_stub_itself(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "new.md", _page(pid, "New"))
+    _write(tmp_wiki / "old.md", _stub("new.md", target_id=pid))
+
+    result = _run(wiki_read.handler({"path": "old.md", "follow_redirects": False}))
+    assert result["path"] == "old.md"
+    assert "redirect_to: new.md" in result["content"]
+    assert result["redirect_chain"] == []
+
+
+def test_read_cycle_returns_error(tmp_wiki: Path) -> None:
+    _write(tmp_wiki / "a.md", _stub("b.md"))
+    _write(tmp_wiki / "b.md", _stub("a.md"))
+
+    result = _run(wiki_read.handler({"path": "a.md"}))
+    assert "error" in result
+    assert "could not be resolved" in result["error"]
+
+
+def test_read_dangling_redirect_returns_error(tmp_wiki: Path) -> None:
+    """Stub points at a path that doesn't exist on disk."""
+    _write(tmp_wiki / "old.md", _stub("nope/missing.md"))
+
+    result = _run(wiki_read.handler({"path": "old.md"}))
+    # ``resolve_chain`` reads frontmatter and gets {} for missing path,
+    # which parse_redirect treats as "not a redirect" → resolve terminates
+    # at nope/missing.md, but read_page returns None for missing → error.
+    assert "error" in result
+
+
+def test_read_missing_source_returns_error(tmp_wiki: Path) -> None:
+    result = _run(wiki_read.handler({"path": "does-not-exist.md"}))
+    assert "error" in result
+    assert "not found" in result["error"]
+
+
+# ── wiki_list: redirect filtering ────────────────────────────────────
+
+
+def test_list_excludes_redirect_stubs_by_default(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "adr/live.md", _page(pid, "Live page"))
+    _write(tmp_wiki / "adr/old.md", _stub("adr/live.md", target_id=pid))
+
+    result = _run(wiki_list.handler({"kind": "adr"}))
+    assert "adr/live.md" in result["pages"]
+    assert "adr/old.md" not in result["pages"]
+    assert result["count"] == 1
+    assert result["redirect_count"] == 1
+
+
+def test_list_include_redirects_returns_all(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "adr/live.md", _page(pid, "Live"))
+    _write(tmp_wiki / "adr/old.md", _stub("adr/live.md"))
+
+    result = _run(wiki_list.handler({"kind": "adr", "include_redirects": True}))
+    assert "adr/live.md" in result["pages"]
+    assert "adr/old.md" in result["pages"]
+    assert result["count"] == 2
+
+
+def test_list_no_redirects_means_redirect_count_zero(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "adr/a.md", _page(pid, "A"))
+
+    result = _run(wiki_list.handler({"kind": "adr"}))
+    assert result["redirect_count"] == 0
+
+
+# ── wiki_reindex: stubs not in INDEX.md ──────────────────────────────
+
+
+def test_reindex_excludes_redirects_from_index(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "adr/live.md", _page(pid, "Live"))
+    _write(tmp_wiki / "adr/old.md", _stub("adr/live.md"))
+
+    result = _run(wiki_reindex.handler({}))
+    assert result["redirect_count"] == 1
+    assert result["by_kind"]["adr"] == 1  # only the live page counted
+
+    index = (tmp_wiki / ".generated" / "INDEX.md").read_text(encoding="utf-8")
+    assert "live.md" in index
+    assert "old.md" not in index
+
+
+# ── wiki_rename: move + stub ─────────────────────────────────────────
+
+
+def test_rename_creates_stub_at_old_path(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "adr/_general/2234-foo.md.md", _page(pid, "Foo"))
+
+    result = _run(
+        wiki_rename.handler(
+            {
+                "from_path": "adr/_general/2234-foo.md.md",
+                "to_path": "adr/_general/2234-foo.md",
+                "reason": "slug bug cleanup",
+            }
+        )
+    )
+    assert "error" not in result, result
+    assert result["page_id"] == pid
+    assert result["stub_created"] is True
+
+    # New path holds the original content.
+    new_text = (tmp_wiki / "adr/_general/2234-foo.md").read_text("utf-8")
+    fm = parse_frontmatter(new_text)
+    assert extract_page_id(fm) == pid
+
+    # Old path holds a redirect stub.
+    stub_text = (tmp_wiki / "adr/_general/2234-foo.md.md").read_text("utf-8")
+    stub_fm = parse_frontmatter(stub_text)
+    assert stub_fm["redirect_to"] == "adr/_general/2234-foo.md"
+    assert stub_fm["redirect_id"] == pid
+    assert stub_fm["redirect_reason"] == "slug bug cleanup"
+
+
+def test_rename_refuses_missing_source(tmp_wiki: Path) -> None:
+    result = _run(wiki_rename.handler({"from_path": "nope.md", "to_path": "new.md"}))
+    assert "error" in result
+    assert "not found" in result["error"]
+
+
+def test_rename_refuses_source_without_id(tmp_wiki: Path) -> None:
+    _write(tmp_wiki / "no-id.md", "---\ntitle: No ID\n---\n\nbody\n")
+    result = _run(wiki_rename.handler({"from_path": "no-id.md", "to_path": "new.md"}))
+    assert "error" in result
+    assert "lacks a valid frontmatter id" in result["error"]
+
+
+def test_rename_refuses_existing_destination(tmp_wiki: Path) -> None:
+    pid1 = generate_page_id()
+    pid2 = generate_page_id()
+    _write(tmp_wiki / "a.md", _page(pid1, "A"))
+    _write(tmp_wiki / "b.md", _page(pid2, "B"))
+
+    result = _run(wiki_rename.handler({"from_path": "a.md", "to_path": "b.md"}))
+    assert "error" in result
+    assert "already exists" in result["error"]
+
+
+def test_rename_with_overwrite_dest(tmp_wiki: Path) -> None:
+    pid1 = generate_page_id()
+    pid2 = generate_page_id()
+    _write(tmp_wiki / "a.md", _page(pid1, "A source"))
+    _write(tmp_wiki / "b.md", _page(pid2, "B existing"))
+
+    result = _run(
+        wiki_rename.handler(
+            {"from_path": "a.md", "to_path": "b.md", "overwrite_dest": True}
+        )
+    )
+    assert "error" not in result
+    # b.md now carries A's content (id and title).
+    b_fm = parse_frontmatter((tmp_wiki / "b.md").read_text("utf-8"))
+    assert b_fm["title"] == "A source"
+    assert b_fm["id"] == pid1
+
+
+def test_rename_refuses_to_chain_redirects(tmp_wiki: Path) -> None:
+    """Renaming a stub onto a new path would create a stub-of-stub chain."""
+    pid = generate_page_id()
+    _write(tmp_wiki / "target.md", _page(pid, "Target"))
+    _write(tmp_wiki / "old.md", _stub("target.md", target_id=pid))
+
+    result = _run(wiki_rename.handler({"from_path": "old.md", "to_path": "new-old.md"}))
+    assert "error" in result
+    assert "already a redirect stub" in result["error"]
+
+
+def test_rename_refuses_same_path(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    _write(tmp_wiki / "a.md", _page(pid, "A"))
+    result = _run(wiki_rename.handler({"from_path": "a.md", "to_path": "a.md"}))
+    assert "error" in result
+
+
+def test_rename_stub_then_read_resolves_to_target(tmp_wiki: Path) -> None:
+    """End-to-end: rename + read returns the moved content via stub."""
+    pid = generate_page_id()
+    _write(tmp_wiki / "old.md", _page(pid, "Important"))
+
+    _run(wiki_rename.handler({"from_path": "old.md", "to_path": "new.md"}))
+    result = _run(wiki_read.handler({"path": "old.md"}))
+
+    assert "error" not in result, result
+    assert result["path"] == "new.md"
+    assert "title: Important" in result["content"]
+    assert result["redirect_chain"] == ["old.md", "new.md"]
+
+
+def test_rename_preserves_page_body_verbatim(tmp_wiki: Path) -> None:
+    pid = generate_page_id()
+    body = (
+        "# Title\n\n"
+        "## Status\n\nAccepted\n\n"
+        "## Decision\n\nDeploy pgvector.\n\n"
+        "## Consequences\n\nPostgres mandatory."
+    )
+    full = f"---\nid: {pid}\ntitle: Title\n---\n\n{body}\n"
+    _write(tmp_wiki / "old.md", full)
+
+    _run(wiki_rename.handler({"from_path": "old.md", "to_path": "new.md"}))
+    new_text = (tmp_wiki / "new.md").read_text("utf-8")
+    assert body in new_text
+    # Source page id survived the move.
+    fm = parse_frontmatter(new_text)
+    assert is_valid_page_id(extract_page_id(fm))