workflow-toolkit 1.0.1

package/.agents/skills/wtk-deep-review/scripts/build_manifest.py

@@ -0,0 +1,479 @@
+#!/usr/bin/env python3
+"""Deep-review manifest builder (bootstrap helper).
+
+Reads the repo (and gh for --pr), writes only under --out. Produces
+manifest.json accounting for EVERY changed file as selected / ignored / skipped
+/ carried, applying the funnel: path filters -> binary -> generated ->
+pure-rename -> whitespace-only -> incremental delta scoping. Also resolves the
+repo path filters (.wtk-deep-review.yaml, else .coderabbit.yaml), records the
+per-round diff_command, and pins the source-freeze baseline
+(worktree_snapshot) that run_jobs.py / render_review.py enforce.
+
+Scopes: --pr N (fetched PR head) | --base REF (committed range) | --staged |
+--worktree (uncommitted + untracked work vs the base ref; always a full round).
+Reviewer concurrency is resolved before dispatch (`--concurrency` > repo config > 3) and pinned
+in the manifest for every execution engine.
+Exit codes: 0 ok, 1 usage/environment error, 2 git/gh failure.
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+sys.dont_write_bytecode = True  # keep the tracked skill tree free of __pycache__
+
+from _common import freeze_snapshot, glob_to_regex
+
+ROUND_KEEP = {"state.json", "round.json", "rounds"}
+
+
+def archive_prior_round(out_dir: Path, round_n: int) -> None:
+    """A new round starts clean: stale stage artifacts (prior-round agent
+    outputs would otherwise pass validation and pollute this round's corpus)
+    move to rounds/round-<n>/ for audit. Same-round re-runs archive nothing."""
+    marker = out_dir / "round.json"
+    prior = None
+    if marker.is_file():
+        try:
+            prior = json.loads(marker.read_text(encoding="utf-8")).get("round")
+        except ValueError:
+            prior = None
+    if prior is not None and prior != round_n:
+        archive = out_dir / "rounds" / f"round-{prior}"
+        archive.mkdir(parents=True, exist_ok=True)
+        moved = 0
+        for entry in sorted(out_dir.iterdir()):
+            if entry.name in ROUND_KEEP:
+                continue
+            shutil.move(str(entry), str(archive / entry.name))
+            moved += 1
+        print(f"archived round {prior} ({moved} artifacts) -> {archive}")
+    marker.write_text(json.dumps({"round": round_n}) + "\n", encoding="utf-8")
+
+
+def archive_stale_outputs(out_dir: Path, round_n: int, snapshot: str) -> None:
+    """A same-round rebuild under a different worktree_snapshot: reviewer
+    outputs anchor to stale lines, so they move aside instead of validating."""
+    manifest_path = out_dir / "manifest.json"
+    if not manifest_path.is_file():
+        return
+    try:
+        prior = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except ValueError:
+        return
+    old = prior.get("worktree_snapshot")
+    if prior.get("round") != round_n or not old or old == snapshot:
+        return
+    outputs = sorted((out_dir / "agents").glob("*.json"))
+    if not outputs:
+        return
+    stale = out_dir / "rounds" / f"round-{round_n}-stale-{old[:12]}"
+    stale.mkdir(parents=True, exist_ok=True)
+    for path in outputs:
+        shutil.move(str(path), str(stale / path.name))
+    print(f"stale outputs archived: {len(outputs)}")
+
+
+DEFAULT_FILTERS = [
+    "!.wtk-deep-review/**",
+    "!**/*.lock", "!**/*.sum", "!**/package-lock.json", "!**/bun.lock", "!**/yarn.lock",
+    "!**/pnpm-lock.yaml", "!**/*.min.js", "!**/*.min.css", "!**/*.map",
+    "!**/vendor/**", "!**/node_modules/**", "!**/dist/**", "!**/build/**",
+    "!**/generated/**", "!**/*.gen.*", "!**/*_pb2.py", "!**/*.pb.go", "!**/*_string.go",
+    "!**/*.d.ts", "!**/testdata/**", "!**/fixtures/**", "!**/__snapshots__/**",
+    "!**/*.snap", "!**/*.log", "!.git/**",
+]
+GENERATED_MARKERS = (b"Code generated by", b"@generated", b"DO NOT EDIT",
+                     b"Autogenerated by", b"automatically generated")
+CONFIG_NAMES = (".wtk-deep-review.yaml", ".wtk-deep-review.yml", ".coderabbit.yaml", ".coderabbit.yml")
+DEFAULT_CONCURRENCY = 3
+MAX_CONCURRENCY = 6
+
+
+def run(cmd, cwd, check=True):
+    proc = subprocess.run(cmd, cwd=cwd, capture_output=True, text=True)
+    if check and proc.returncode != 0:
+        sys.stderr.write(f"command failed ({proc.returncode}): {' '.join(cmd)}\n{proc.stderr}\n")
+        sys.exit(2)
+    return proc
+
+
+def parse_path_filters(config_path: Path):
+    """YAML-lite: extract list items under a 'path_filters:' key."""
+    if not config_path.is_file():
+        return None
+    lines = config_path.read_text(encoding="utf-8", errors="replace").splitlines()
+    filters, capturing, key_indent = [], False, 0
+    for line in lines:
+        stripped = line.strip()
+        if re.match(r"^path_filters\s*:", stripped):
+            capturing, key_indent = True, len(line) - len(line.lstrip())
+            continue
+        if capturing:
+            if stripped and not stripped.startswith("#"):
+                indent = len(line) - len(line.lstrip())
+                m = re.match(r"^-\s*[\"']?([^\"']+?)[\"']?\s*$", stripped)
+                if m and indent > key_indent:
+                    filters.append(m.group(1))
+                elif indent <= key_indent:
+                    capturing = False
+    return filters or None
+
+
+def load_filters(repo_root: Path):
+    for name in CONFIG_NAMES:
+        parsed = parse_path_filters(repo_root / name)
+        if parsed is not None:
+            return parsed + DEFAULT_FILTERS, name
+    return list(DEFAULT_FILTERS), "built-ins"
+
+
+def _config_path(repo_root: Path) -> Path | None:
+    for name in CONFIG_NAMES:
+        candidate = repo_root / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def parse_concurrency(config_path: Path | None) -> int:
+    """Read the top-level YAML scalar without accepting booleans or strings."""
+    if config_path is None:
+        return DEFAULT_CONCURRENCY
+    for line in config_path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if line.startswith((" ", "\t")) or not re.match(r"^concurrency\s*:", line):
+            continue
+        raw = line.split(":", 1)[1].split("#", 1)[0].strip()
+        if not re.fullmatch(r"[0-9]+", raw):
+            raise ValueError("concurrency must be an integer from 1 through 6")
+        value = int(raw)
+        if not 1 <= value <= MAX_CONCURRENCY:
+            raise ValueError("concurrency must be an integer from 1 through 6")
+        return value
+    return DEFAULT_CONCURRENCY
+
+
+def parse_yaml_flag(config_path: Path | None, key: str) -> bool:
+    """Top-level `<key>: true` in the YAML-lite config; anything else is false."""
+    if config_path is None:
+        return False
+    for line in config_path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if line.startswith((" ", "\t")) or not re.match(rf"^{re.escape(key)}\s*:", line):
+            continue
+        return line.split(":", 1)[1].split("#", 1)[0].strip() == "true"
+    return False
+
+
+def resolve_concurrency(repo_root: Path, override: int | None) -> tuple[int, str]:
+    if override is not None:
+        if not 1 <= override <= MAX_CONCURRENCY:
+            raise ValueError("concurrency must be an integer from 1 through 6")
+        return override, "cli"
+    config_path = _config_path(repo_root)
+    return parse_concurrency(config_path), config_path.name if config_path else "default"
+
+
+def resolve_default_base(repo_root: Path) -> str:
+    head_ref = run(["git", "symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"], repo_root, check=False)
+    if head_ref.returncode == 0 and head_ref.stdout.strip():
+        return head_ref.stdout.strip().replace("refs/remotes/", "")
+    for cand in ("origin/main", "origin/master", "main", "master"):
+        if run(["git", "rev-parse", "--verify", "--quiet", cand], repo_root, check=False).returncode == 0:
+            return cand
+    sys.stderr.write("cannot resolve a default base branch; pass --base explicitly\n")
+    sys.exit(1)
+
+
+def resolve_pr(repo_root: Path, pr: int):
+    probe = run(["gh", "auth", "status"], repo_root, check=False)
+    if probe.returncode != 0:
+        sys.stderr.write("gh is not authenticated; run: gh auth login\n")
+        sys.exit(1)
+    view = run(["gh", "pr", "view", str(pr), "--json", "baseRefOid,headRefOid,title,url"], repo_root)
+    data = json.loads(view.stdout)
+    head = data["headRefOid"]
+    if run(["git", "cat-file", "-e", f"{head}^{{commit}}"], repo_root, check=False).returncode != 0:
+        sys.stderr.write(
+            f"PR head {head} is not local. Fetch it first:\n  git fetch origin pull/{pr}/head\n")
+        sys.exit(1)
+    base = run(["git", "merge-base", data["baseRefOid"], head], repo_root).stdout.strip()
+    return base, head, data
+
+
+def diff_spec(base, head, staged, worktree):
+    """The git-diff revision arguments for the review scope."""
+    if staged:
+        return ["--staged"]
+    if worktree:
+        return [base]  # single rev = committed base vs the working tree
+    return [f"{base}..{head}"]
+
+
+def diff_name_status(repo_root: Path, spec):
+    entries = []
+    for line in run(["git", "diff", "--name-status", "-M50", *spec], repo_root).stdout.splitlines():
+        parts = line.split("\t")
+        status = parts[0]
+        if status.startswith("R") and len(parts) == 3:
+            entries.append({"path": parts[2], "status": status, "old_path": parts[1]})
+        elif len(parts) >= 2:
+            entries.append({"path": parts[1], "status": status, "old_path": None})
+    return entries
+
+
+def numstat(repo_root: Path, spec, extra=()):
+    stats = {}
+    for line in run(["git", "diff", "--numstat", "-M50", *extra, *spec], repo_root).stdout.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 3:
+            continue
+        adds, dels, path = parts[0], parts[1], parts[-1]
+        if "=>" in path and "{" in path:  # rename syntax a/{b => c}/d
+            prefix, rest = path.split("{", 1)
+            inner, suffix = rest.split("}", 1)
+            path = prefix + inner.split(" => ")[1] + suffix
+        elif " => " in path:
+            path = path.split(" => ")[1]
+        stats[path] = (None if adds == "-" else int(adds), None if dels == "-" else int(dels))
+    return stats
+
+
+def looks_generated(repo_root: Path, path: str) -> bool:
+    f = repo_root / path
+    if f.is_symlink():
+        return False
+    if not f.is_file():
+        return False
+    try:
+        with f.open("rb") as fh:
+            head_bytes = fh.read(2048)
+    except OSError as err:
+        sys.stderr.write(f"warn: cannot probe {path}: {err}\n")
+        return False
+    return any(marker in head_bytes for marker in GENERATED_MARKERS)
+
+
+def parse_range(value: str):
+    start_and_lines = value[1:].split(",", 1)
+    start = int(start_and_lines[0])
+    lines = int(start_and_lines[1]) if len(start_and_lines) == 2 else 1
+    return start, lines
+
+
+def collect_hunks(repo_root: Path, spec):
+    """Per-file hunk ranges: new-side for edits/additions (the publish anchors),
+    old-side for pure deletions so removed code still gets judged."""
+    hunks, current, old_path = {}, None, None
+    for line in run(["git", "diff", "-U0", "-M50", *spec], repo_root).stdout.splitlines():
+        if line.startswith("--- "):
+            raw = line[4:].strip()
+            old_path = None if raw == "/dev/null" else raw.removeprefix("a/")
+        elif line.startswith("+++ "):
+            raw = line[4:].strip()
+            current = old_path if raw == "/dev/null" else raw.removeprefix("b/")
+        elif line.startswith("@@") and current:
+            m = re.match(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@", line)
+            if not m:
+                continue
+            old_start, old_lines = int(m.group(1)), int(m.group(2) or 1)
+            new_start, new_lines = int(m.group(3)), int(m.group(4) or 1)
+            if new_lines > 0:
+                hunk = {"start": new_start, "lines": new_lines, "side": "new"}
+            else:
+                hunk = {"start": old_start, "lines": old_lines, "side": "old"}
+            hunks.setdefault(current, []).append(hunk)
+    return hunks
+
+
+def untracked_paths(repo_root: Path, out_rel: str):
+    paths = []
+    for path in run(["git", "ls-files", "--others", "--exclude-standard"], repo_root).stdout.splitlines():
+        if path.startswith(".wtk-deep-review/") or (out_rel and path.startswith(out_rel + "/")):
+            continue
+        paths.append(path)
+    return paths
+
+
+def untracked_stat(repo_root: Path, path: str):
+    data = (repo_root / path).read_bytes()
+    if b"\0" in data:
+        return None, None
+    return len(data.splitlines()), 0
+
+
+def symlink_target(repo_root: Path, path: str) -> str | None:
+    candidate = repo_root / path
+    if not candidate.is_symlink():
+        return None
+    return os.readlink(candidate)
+
+
+def prior_head(state_path: Path):
+    if not state_path.is_file():
+        return None, 0
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+        rounds = state.get("rounds", [])
+        return (rounds[-1]["head"], rounds[-1]["n"]) if rounds else (None, 0)
+    except (ValueError, KeyError) as err:
+        sys.stderr.write(f"warn: unreadable state {state_path} ({err}); running full\n")
+        return None, 0
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--pr", type=int)
+    ap.add_argument("--base")
+    ap.add_argument("--head", default="HEAD")
+    ap.add_argument("--staged", action="store_true")
+    ap.add_argument("--worktree", action="store_true",
+                    help="review uncommitted + untracked work against the base ref")
+    ap.add_argument("--files", help="comma-separated subset")
+    ap.add_argument("--full", action="store_true")
+    ap.add_argument("--concurrency", type=int, help="bounded reviewer concurrency (1-6)")
+    args = ap.parse_args()
+    if args.pr and (args.base or args.staged or args.worktree):
+        ap.error("--pr conflicts with --base/--staged/--worktree")
+    if args.staged and args.worktree:
+        ap.error("--staged conflicts with --worktree")
+
+    top = run(["git", "rev-parse", "--show-toplevel"], Path.cwd())
+    repo_root = Path(top.stdout.strip())
+    try:
+        concurrency, concurrency_source = resolve_concurrency(repo_root, args.concurrency)
+    except ValueError as error:
+        ap.error(str(error))
+    out_dir = Path(args.out); out_dir.mkdir(parents=True, exist_ok=True)
+    try:
+        out_rel = str(out_dir.resolve().relative_to(repo_root))
+    except ValueError:
+        out_rel = ""
+
+    pr_meta = None
+    if args.pr:
+        base, head, pr_meta = resolve_pr(repo_root, args.pr)
+        target = f"pr:{args.pr}"
+        diff_command = f"git diff {base[:12]}..{head[:12]} -- <file>"
+    elif args.staged:
+        base, head, target = "HEAD", "STAGED", "staged"
+        diff_command = "git diff --staged -- <file>"
+    else:
+        base_ref = args.base or resolve_default_base(repo_root)
+        base = run(["git", "merge-base", base_ref, "HEAD" if args.worktree else args.head],
+                   repo_root).stdout.strip()
+        head = run(["git", "rev-parse", "HEAD" if args.worktree else args.head], repo_root).stdout.strip()
+        if args.worktree:
+            target = f"worktree:{base_ref}"
+            diff_command = f"git diff {base[:12]} -- <file>"
+        else:
+            target = f"diff:{base_ref}"
+            diff_command = f"git diff {base[:12]}..{head[:12]} -- <file>"
+
+    filters, filter_source = load_filters(repo_root)
+    excludes = [(p, glob_to_regex(p[1:])) for p in filters if p.startswith("!")]
+    includes = [(p, glob_to_regex(p)) for p in filters if not p.startswith("!")]
+
+    last_head, last_n = prior_head(out_dir / "state.json")
+    mode, effective_base, round_n = "full", base, last_n + 1
+    if not args.full and not args.staged and not args.worktree:
+        if last_head and run(["git", "merge-base", "--is-ancestor", last_head, head],
+                             repo_root, check=False).returncode == 0 and last_head != head:
+            mode, effective_base = "incremental", last_head
+        diff_command = f"git diff {effective_base[:12]}..{head[:12]} -- <file>"
+    snapshot = freeze_snapshot(repo_root, out_dir.resolve())
+    archive_stale_outputs(out_dir, round_n, snapshot)
+    archive_prior_round(out_dir, round_n)
+
+    spec = diff_spec(effective_base, head, args.staged, args.worktree)
+    entries = diff_name_status(repo_root, spec)
+    stats = numstat(repo_root, spec)
+    ws_stats = numstat(repo_root, spec, extra=("-w", "--ignore-blank-lines"))
+    hunk_map = collect_hunks(repo_root, spec)
+    if args.worktree:
+        tracked = {e["path"] for e in entries}
+        for path in untracked_paths(repo_root, out_rel):
+            if path in tracked:
+                continue
+            entries.append({"path": path, "status": "A", "old_path": None})
+            link_target = symlink_target(repo_root, path)
+            stats[path] = (1, 0) if link_target is not None else untracked_stat(repo_root, path)
+            ws_stats[path] = stats[path]
+            adds = stats[path][0]
+            if adds:
+                hunk_map[path] = [{"start": 1, "lines": adds, "side": "new"}]
+    delta_paths = None
+    if mode == "incremental":
+        delta_paths = {e["path"] for e in diff_name_status(repo_root, [f"{effective_base}..{head}"])}
+
+    subset = {p.strip() for p in args.files.split(",")} if args.files else None
+    files, counts = [], {"selected": 0, "ignored": 0, "skipped": 0, "carried": 0}
+    for e in sorted(entries, key=lambda x: x["path"]):
+        path, status = e["path"], e["status"]
+        adds, dels = stats.get(path, (0, 0))
+        rec = {"path": path, "status": status, "adds": adds, "dels": dels}
+        if e["old_path"]:
+            rec["old_path"] = e["old_path"]
+        link_target = symlink_target(repo_root, path)
+        if link_target is not None:
+            rec.update({"kind": "symlink", "target": link_target})
+
+        disposition, reason = "selected", None
+        if subset is not None and path not in subset:
+            disposition, reason = "ignored", "outside --files subset"
+        else:
+            exc = next((p for p, rx in excludes if rx.match(path)), None)
+            inc = next((p for p, rx in includes if rx.match(path)), None)
+            if includes and not inc:
+                disposition, reason = "ignored", "matches no include pattern"
+            elif exc and not inc:
+                disposition, reason = "ignored", f"excluded by `{exc}`"
+            elif adds is None or dels is None:
+                disposition, reason = "skipped", "binary"
+            elif status.startswith("R") and adds == 0 and dels == 0:
+                disposition, reason = "skipped", f"pure rename from `{e['old_path']}`"
+            elif (adds or dels) and ws_stats.get(path, (0, 0)) == (0, 0):
+                disposition, reason = "skipped", "whitespace-only change"
+            elif status != "D" and looks_generated(repo_root, path):
+                disposition, reason = "skipped", "generated-file marker in content"
+            elif delta_paths is not None and path not in delta_paths:
+                disposition, reason = "carried", f"unchanged since round {round_n - 1} head"
+
+        rec["disposition"] = disposition
+        if reason:
+            rec["reason"] = reason
+        if disposition == "selected":
+            rec["hunks"] = hunk_map.get(path, [])
+        counts[disposition] += 1
+        files.append(rec)
+
+    manifest = {
+        "target": target, "mode": "staged" if args.staged else mode, "round": round_n,
+        "base": base, "effective_base": effective_base, "head": head,
+        "diff_command": diff_command, "worktree_snapshot": snapshot,
+        "filter_source": filter_source, "counts": counts, "files": files,
+        "concurrency": concurrency, "concurrency_source": concurrency_source,
+    }
+    if pr_meta:
+        manifest["pr"] = {"number": args.pr, "title": pr_meta["title"], "url": pr_meta["url"]}
+    (out_dir / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    total = len(files)
+    print(f"manifest: {out_dir / 'manifest.json'}")
+    print(f"target={target} mode={manifest['mode']} round={round_n}")
+    print(f"base={base[:12]} effective_base={effective_base[:12] if effective_base != base else '(same)'} head={head[:12]}")
+    print(f"files: {total} changed -> {counts['selected']} selected, {counts['ignored']} ignored, "
+          f"{counts['skipped']} skipped, {counts['carried']} carried (filters: {filter_source})")
+    print(f"freeze: worktree_snapshot={snapshot[:12]} (run_jobs.py and render_review.py enforce it)")
+    print("review posture: assertive (single mode)")
+    if counts["selected"] == 0:
+        print("nothing selected — review has no reviewable surface")
+
+
+if __name__ == "__main__":
+    main()

package/.agents/skills/wtk-deep-review/scripts/graft_context.py

@@ -0,0 +1,160 @@
+"""Best-effort Graft context preparation for wtk-deep-review prompts."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+import sys
+import os
+from pathlib import Path
+from typing import Any
+
+RI_SCRIPTS = Path(__file__).resolve().parents[2] / "wtk-config" / "scripts"
+if str(RI_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(RI_SCRIPTS))
+
+import repository_intelligence as ri  # noqa: E402
+
+FALLBACK_LINE = "Graft context is unavailable; use plain repository inspection."
+PARTIAL_LINE = "Graft context is partial; use targeted repository inspection for uncovered paths."
+
+
+def _fallback(path: Path, reason: str, dot_paths: list[str], digest: str) -> dict[str, str]:
+    lines = [
+        "# Graft context",
+        "",
+        "status: fallback",
+        f"question_hash: {digest}",
+        f"reason: {reason}",
+        "",
+        FALLBACK_LINE,
+    ]
+    if dot_paths:
+        lines.extend([
+            "",
+            "Graft does not index dot-directories; inspect these paths plainly:",
+            *[f"- `{item}`" for item in dot_paths],
+        ])
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return {"status": "fallback", "path": str(path), "question_hash": digest, "reason": reason}
+
+
+def _result_error(error: Exception) -> str:
+    if isinstance(error, ri.IntelligenceError):
+        return ri._redact(error.reason)
+    return "Graft context failed"
+
+
+def _context(result: Any) -> str:
+    return str(result.get("context", "")).strip() if isinstance(result, dict) else ""
+
+
+def _reason(result: Any, default: str) -> str:
+    if not isinstance(result, dict):
+        return default
+    return ri._redact(str(result.get("reason") or default))
+
+
+def prepare_graft_context(repo: Path, out: Path, selected_paths: list[str]) -> dict[str, str]:
+    """Build and query Graft through the shared adapter without blocking review."""
+    context_path = out / "graft-context.md"
+    dot_paths = [path for path in selected_paths if path.startswith(".") or path.startswith("graft/")]
+    visible_paths = [path for path in selected_paths if path not in dot_paths]
+    query = " ".join(visible_paths[:20]) or "repository structure"
+    digest = hashlib.sha256(query.encode("utf-8")).hexdigest()
+    try:
+        mapped = ri._run_context(repo, "graft", "map", [])
+    except Exception as error:  # adapter converts expected tool failures to IntelligenceError
+        return _fallback(context_path, _result_error(error), dot_paths, digest)
+    if isinstance(mapped, dict) and mapped.get("status") == "degraded":
+        return _fallback(context_path, _reason(mapped, "Graft map failed"), dot_paths, digest)
+
+    try:
+        asked = ri._run_context(repo, "graft", "ask", ["--json", "--limit", "8", query])
+    except Exception as error:
+        asked = None
+        ask_reason = _result_error(error)
+    else:
+        ask_reason = _reason(asked, "Graft symbol lookup failed")
+
+    symbols: list[str] = []
+    asked_context = _context(asked)
+    if asked_context:
+        try:
+            hits = json.loads(asked_context).get("hits", [])
+            symbols = [
+                str(hit.get("title", "")).split(" · ", 1)[0]
+                for hit in hits
+                if hit.get("kind") == "symbol"
+            ][:3]
+        except (TypeError, ValueError, json.JSONDecodeError):
+            symbols = []
+
+    partial = mapped.get("status") == "partial" if isinstance(mapped, dict) else False
+    partial = partial or (asked.get("status") == "partial" if isinstance(asked, dict) else False)
+    lines = [
+        "# Graft context",
+        "",
+        "status: partial" if partial else ("status: ready" if asked_context and not dot_paths else "status: ready-with-fallback"),
+        f"question_hash: {digest}",
+        "",
+        "Use this map as review orientation; verify every claim against the checkout.",
+        "",
+        "## Repository map",
+        "```text",
+        _context(mapped)[:12000],
+        "```",
+    ]
+    if asked_context:
+        lines.extend(["", "## Relevant symbols", "```text", asked_context[:12000], "```"])
+    else:
+        lines.extend(["", ask_reason, "Use plain repository inspection for relevant symbols and callers."])
+
+    blast_failed = False
+    blast_partial = False
+    for symbol in symbols:
+        try:
+            callers = ri._run_context(repo, "graft", "callers", ["--json", "--depth", "1", symbol])
+        except Exception:
+            blast_failed = True
+            continue
+        callers_context = _context(callers)
+        blast_partial = blast_partial or (isinstance(callers, dict) and callers.get("status") == "partial")
+        if callers_context:
+            lines.extend(["", f"### `{symbol}`", "```text", callers_context[:6000], "```"])
+        else:
+            blast_failed = True
+    if blast_failed:
+        lines.extend(["", "Graft blast-radius lookup failed; use plain repository inspection for callers."])
+    partial = partial or blast_partial
+    if partial:
+        lines[2] = "status: partial"
+        lines.extend(["", PARTIAL_LINE])
+    if dot_paths:
+        lines.extend([
+            "",
+            "Graft does not index dot-directories; use plain repository inspection for:",
+            *[f"- `{item}`" for item in dot_paths],
+        ])
+    if not _context(mapped):
+        return _fallback(context_path, "Graft returned insufficient context", dot_paths, digest)
+    context_path.parent.mkdir(parents=True, exist_ok=True)
+    context_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    status = "partial" if partial else ("ready" if asked_context and not dot_paths and not blast_failed else "ready-with-fallback")
+    return {"status": status, "path": str(context_path), "question_hash": digest}
+
+
+def graft_binary(repo: Path) -> str | None:
+    """Compatibility inspection helper for callers that need local tool discovery."""
+    local = repo / "node_modules" / ".bin" / "graft"
+    package = repo / "node_modules" / "@nanonets" / "graft" / "package.json"
+    if not local.is_file() or not package.is_file() or not os.access(local, os.X_OK):
+        return None
+    try:
+        manifest = json.loads(package.read_text(encoding="utf-8"))
+        local.resolve(strict=True).relative_to(repo.resolve() / "node_modules")
+        package.parent.resolve(strict=True).relative_to(repo.resolve() / "node_modules")
+    except (OSError, ValueError, json.JSONDecodeError):
+        return None
+    return str(local) if manifest.get("version") == ri.GRAFT_VERSION else None