feat: ccarch resolver with ts/tsx recovery and status codes

Resolves doc-cited code paths against the live filesystem, reporting
ok/moved/missing. Never raises on junk input (empty strings, path
traversal attempts, nonexistent paths); a cited path can never resolve
outside the repo root.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pwx603

mcp/ccarch/ccarch/resolver.py

@@ -0,0 +1,62 @@
+"""Resolve doc-cited code paths against the live filesystem.
+
+Resolution happens per call, not at index time: docs and code drift
+independently, so the 5% dead rate is permanent, not a one-off cleanup.
+Status is a first-class field — an agent told `missing` adapts, while an
+agent handed a phantom path burns a turn discovering it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class Resolved:
+    path: str
+    status: str  # "ok" | "moved" | "missing"
+    kind: str    # "file" | "dir"
+
+
+def _swap_ext(p: str) -> str | None:
+    if p.endswith(".ts"):
+        return p[:-3] + ".tsx"
+    if p.endswith(".tsx"):
+        return p[:-4] + ".ts"
+    return None
+
+
+def resolve(repo_root: Path, cited: str) -> Resolved:
+    repo_root = Path(repo_root)
+    raw = (cited or "").strip()
+    if not raw:
+        return Resolved(path=cited or "", status="missing", kind="file")
+
+    is_dir_cite = raw.endswith("/")
+    q = raw.rstrip("/")
+
+    # Never let a cited path escape the repo. A doc citing ../../etc/passwd
+    # resolves to missing rather than probing outside the tree.
+    try:
+        target = (repo_root / q).resolve()
+        target.relative_to(repo_root.resolve())
+    except (ValueError, OSError):
+        return Resolved(path=raw, status="missing", kind="dir" if is_dir_cite else "file")
+
+    if is_dir_cite:
+        return Resolved(
+            path=raw,
+            status="ok" if target.is_dir() else "missing",
+            kind="dir",
+        )
+
+    if target.is_file():
+        return Resolved(path=q, status="ok", kind="file")
+    if target.is_dir():
+        return Resolved(path=q, status="ok", kind="dir")
+
+    alt = _swap_ext(q)
+    if alt and (repo_root / alt).is_file():
+        return Resolved(path=alt, status="moved", kind="file")
+
+    return Resolved(path=q, status="missing", kind="file")

mcp/ccarch/tests/test_resolver.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+from ccarch.resolver import resolve
+
+REPO = Path(__file__).resolve().parents[3]
+
+def test_exact_hit_is_ok():
+    r = resolve(REPO, "src/voice/voiceModeEnabled.ts")
+    assert r.status == "ok"
+    assert r.kind == "file"
+    assert r.path == "src/voice/voiceModeEnabled.ts"
+
+def test_wrong_extension_is_moved_with_corrected_path():
+    # Docs cite AgentTool.ts; the real file is AgentTool.tsx.
+    r = resolve(REPO, "packages/builtin-tools/src/tools/AgentTool/AgentTool.ts")
+    assert r.status == "moved"
+    assert r.path.endswith(".tsx")
+    assert (REPO / r.path).is_file()
+
+def test_directory_row_is_ok_kind_dir():
+    r = resolve(REPO, "src/voice/")
+    assert r.status == "ok"
+    assert r.kind == "dir"
+
+def test_genuinely_missing_is_missing():
+    r = resolve(REPO, "src/definitely/not/here.ts")
+    assert r.status == "missing"
+
+def test_never_raises_on_junk():
+    for junk in ["", "   ", "///", "src/foo.ts", "../../etc/passwd"]:
+        assert resolve(REPO, junk).status in {"ok", "moved", "missing"}