sourcecode 2.6.2__py3-none-any.whl → 2.6.3__py3-none-any.whl

sourcecode/verify_edit.py

@@ -0,0 +1,588 @@
+"""verify-edit — Fase V0 plumbing spike.
+
+The pivot (see .planning/ROADMAP-VERIFY-EDIT.md): from read-context provider to an
+in-loop semantic-diff gate. The one hard technical unknown is producing the diff
+substrate — ``(CIR_HEAD, CIR_working)`` — deterministically and cheaply, *in place*
+(working tree vs HEAD, no user-supplied snapshots). Existing ``delta`` /
+``contract-diff`` take two directory snapshots; this closes that gap.
+
+This module is the internal spike: it builds that pair and measures cold vs warm.
+No public command and no verdict layer yet (those are Fase V1). What it must prove:
+
+  * the pair is a **pure function of the two tree states** — same trees ⇒ identical
+    CIR hashes across runs (determinism is the whole product promise);
+  * the HEAD CIR is cached by **HEAD commit sha** (stable while the working tree is
+    dirty), so warm < cold;
+  * nothing scoped is ever written under the repo-wide shared-CIR key (that key is
+    the ``explain``/``impact`` cache — poisoning it is the 2.6.2 lesson). The HEAD
+    CIR uses a **separate, HEAD-sha-anchored** cache entry.
+"""
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+
+class VerifyEditError(RuntimeError):
+    """The working tree cannot be verified (not a git repo, no HEAD, git absent)."""
+
+
+@dataclass(frozen=True)
+class HeadVsWorking:
+    """The diff substrate for one working tree, plus provenance for measurement.
+
+    ``cir_head`` / ``cir_working`` are ``CanonicalRepositoryIR``. ``changed_files``
+    are the ``.java`` paths that differ from HEAD (tracked edits + untracked adds;
+    deletions included even though the file is gone from the working tree, because a
+    removed public type is a contract change the verdict layer must see).
+    """
+
+    cir_head: Any
+    cir_working: Any
+    changed_files: tuple[str, ...]
+    head_sha: str
+    head_cache_hit: bool
+    timings_ms: dict[str, float] = field(default_factory=dict)
+
+
+# Git env vars that REDIRECT git at where it operates. When verify-edit runs INSIDE a
+# git hook (V3), git exports these pointing at the in-progress commit's transient index/
+# dir — a nested `git worktree add` then fails ("`.git/index`: Not a directory"). We
+# always target the repo explicitly with `git -C root`, so scrubbing them is safe and
+# makes the HEAD materialisation work from within a hook.
+_SCRUBBED_GIT_ENV = (
+    "GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_INDEX_VERSION", "GIT_PREFIX",
+    "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY", "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+)
+
+
+def _git_env() -> dict:
+    import os
+    env = {k: v for k, v in os.environ.items() if k not in _SCRUBBED_GIT_ENV}
+    return env
+
+
+# ── git plumbing ───────────────────────────────────────────────────────────────
+def _run_git(root: Path, *args: str, timeout: int = 60) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        timeout=timeout,
+        env=_git_env(),
+    )
+
+
+def _resolve_repo_root(path: Path) -> Path:
+    candidate = path.resolve()
+    while True:
+        if (candidate / ".git").exists():
+            return candidate
+        if candidate.parent == candidate:
+            return path.resolve()
+        candidate = candidate.parent
+
+
+def _head_sha(root: Path) -> str:
+    try:
+        r = _run_git(root, "rev-parse", "HEAD", timeout=10)
+        return r.stdout.strip() if r.returncode == 0 else ""
+    except Exception:
+        return ""
+
+
+def _changed_java_files(root: Path) -> tuple[str, ...]:
+    """`.java` paths that differ from HEAD: tracked diff ∪ untracked adds.
+
+    Deletions are kept (the path is gone but the contract change is real). Pure
+    git; never reads file contents.
+    """
+    files: set[str] = set()
+    try:
+        r = _run_git(root, "diff", "--name-only", "HEAD")
+        if r.returncode == 0:
+            files.update(line.strip() for line in r.stdout.splitlines() if line.strip())
+        ru = _run_git(root, "ls-files", "--others", "--exclude-standard")
+        if ru.returncode == 0:
+            files.update(line.strip() for line in ru.stdout.splitlines() if line.strip())
+    except Exception:
+        pass
+    return tuple(sorted(f for f in files if f.endswith(".java")))
+
+
+# ── CIR construction ───────────────────────────────────────────────────────────
+def _build_cir(root: Path) -> Any:
+    """Full-repo CIR from an on-disk tree (V0: full scope; V4 scopes to the diff)."""
+    from sourcecode.canonical_ir import build_canonical_ir
+    from sourcecode.repository_ir import find_java_files
+
+    return build_canonical_ir(find_java_files(root), root)
+
+
+def _build_head_cir_via_worktree(root: Path) -> Any:
+    """Materialise HEAD in a throwaway detached worktree and build its CIR.
+
+    A worktree checkout gives an exact, clean HEAD tree regardless of how dirty the
+    live working tree is. The temp path never leaks into the CIR — file paths are
+    relative to the worktree root, and ``cir_hash`` is content-derived — so the HEAD
+    CIR is identical whatever the temp dir is called (asserted by the determinism test).
+    """
+    tmp = Path(tempfile.mkdtemp(prefix="ask-head-"))
+    wt = tmp / "wt"
+    try:
+        r = _run_git(root, "worktree", "add", "--detach", "--quiet", str(wt), "HEAD")
+        if r.returncode != 0:
+            raise VerifyEditError(f"git worktree add failed: {r.stderr.strip()}")
+        return _build_cir(wt)
+    finally:
+        # Best-effort teardown: prune the worktree registration, then the temp dir.
+        try:
+            _run_git(root, "worktree", "remove", "--force", str(wt), timeout=30)
+        except Exception:
+            pass
+        _run_git(root, "worktree", "prune", timeout=10)
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _head_cir(root: Path, head_sha: str) -> tuple[Any, bool]:
+    """Return ``(cir_head, cache_hit)``, caching the HEAD CIR by **HEAD sha**.
+
+    The cache signature is the commit sha, not the worktree signature, so the entry
+    stays valid while the working tree is dirty (which is the normal edit-loop state).
+    This is a *separate* entry from the shared repo-wide CIR — a scoped/HEAD build must
+    never land under that key.
+    """
+    from sourcecode.canonical_ir import ir_dict_to_canonical, validate_canonical_ir
+    from sourcecode.context_cache import (
+        SCOPE_JAVA_CIR,
+        CachedContext,
+        ContextCache,
+        _cache_dir,
+    )
+
+    cache = ContextCache(_cache_dir(root.resolve()), head_sha)  # signature := HEAD sha
+    key = cache.knowledge_key(SCOPE_JAVA_CIR)
+
+    if cache.enabled:
+        cached = cache.get(key)
+        if cached is not None:
+            raw = cached.payload.get("raw_ir")
+            if isinstance(raw, dict):
+                try:
+                    cir = ir_dict_to_canonical(raw, file_paths=None)
+                    if not validate_canonical_ir(cir):  # empty list ⇒ valid
+                        return cir, True
+                except Exception:
+                    pass  # corrupt payload — rebuild
+
+    cir = _build_head_cir_via_worktree(root)
+    if cache.enabled:
+        try:
+            cache.put(
+                key,
+                CachedContext(
+                    metadata={"scope": SCOPE_JAVA_CIR, "head_sha": head_sha, "cir_hash": cir.cir_hash},
+                    graph_metrics={"symbol_count": len(cir.symbols), "endpoint_count": len(cir.endpoints)},
+                    payload={"raw_ir": cir._raw_ir},
+                ),
+            )
+        except Exception:
+            pass  # caching is best-effort; correctness never depends on it
+    return cir, False
+
+
+# ── entry point ─────────────────────────────────────────────────────────────────
+def head_vs_working(path: Path) -> HeadVsWorking:
+    """Produce the ``(CIR_HEAD, CIR_working, changed_files)`` diff substrate.
+
+    Deterministic: the two CIRs are a pure function of the two tree states. The cache
+    only accelerates the HEAD side (keyed by HEAD sha); it never changes the result.
+    """
+    root = _resolve_repo_root(Path(path))
+    head_sha = _head_sha(root)
+    if not head_sha:
+        raise VerifyEditError(f"{root} is not a git repository with a HEAD commit")
+
+    timings: dict[str, float] = {}
+
+    t0 = time.perf_counter()
+    changed = _changed_java_files(root)
+    timings["changed_files_ms"] = (time.perf_counter() - t0) * 1000.0
+
+    t1 = time.perf_counter()
+    cir_head, hit = _head_cir(root, head_sha)
+    timings["head_cir_ms"] = (time.perf_counter() - t1) * 1000.0
+
+    t2 = time.perf_counter()
+    cir_working = _build_cir(root)
+    timings["working_cir_ms"] = (time.perf_counter() - t2) * 1000.0
+
+    return HeadVsWorking(
+        cir_head=cir_head,
+        cir_working=cir_working,
+        changed_files=changed,
+        head_sha=head_sha,
+        head_cache_hit=hit,
+        timings_ms=timings,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Fase V1 — the verdict layer
+# ═══════════════════════════════════════════════════════════════════════════════
+#
+# Each axis is a DIFF over the V0 substrate: what did the working tree gain versus
+# HEAD? Honesty (F-1): an axis reports ``changed=True`` only on a proven regression,
+# ``changed=False`` only when it actually computed and found none, and
+# ``changed=None`` when it could not run (never a false "no change"). cir_hash is a
+# coarse gate and is NOT used for detection — axes read structured symbol fields
+# (the V0 finding) and reuse the existing analyzers, diffing their stable ids.
+
+VERDICT_SCHEMA = "verify-edit-v1"
+
+# Axes that gate a merge. blast_radius is informational (reach, not a regression).
+# custom_rule_violated (Fase V5) enforces the client's own declared invariants; it is a
+# no-op (clean) when no rules file exists, so adding it never blocks a repo that has none.
+_BLOCKING_AXES = (
+    "contract_broken", "tx_boundary_changed", "security_delta", "new_orphan_bean",
+    "custom_rule_violated",
+)
+
+
+@dataclass(frozen=True)
+class AxisResult:
+    """One verdict axis. ``changed``: True=regression proven, False=computed-clean,
+    None=could-not-compute (honest degrade — never counted as clean)."""
+
+    changed: Optional[bool]
+    detail: str = ""
+    items: tuple[dict, ...] = ()
+
+    def to_dict(self) -> dict:
+        d: dict = {"changed": self.changed}
+        if self.detail:
+            d["detail"] = self.detail
+        if self.items:
+            d["items"] = list(self.items)
+        return d
+
+
+@dataclass(frozen=True)
+class VerifyVerdict:
+    verdict: str  # "pass" | "break" | "unverified"
+    axes: dict[str, AxisResult]
+    changed_files: tuple[str, ...]
+    blast_radius: dict
+    reasons: tuple[str, ...]
+    exit_code: int
+    head_sha: str
+
+    def to_dict(self) -> dict:
+        return {
+            "schema_version": VERDICT_SCHEMA,
+            "verdict": self.verdict,
+            "head_sha": self.head_sha,
+            "changed_files": list(self.changed_files),
+            "axes": {name: ax.to_dict() for name, ax in self.axes.items()},
+            "blast_radius": self.blast_radius,
+            "reasons": list(self.reasons),
+            "exit_code": self.exit_code,
+        }
+
+
+# ── structured symbol views (read the raw IR nodes, per the V0 finding) ─────────
+def _nodes(cir: Any) -> list[dict]:
+    return cir._raw_ir.get("graph", {}).get("nodes", []) or []
+
+
+def _nodes_by_fqn(cir: Any) -> dict[str, list[dict]]:
+    """Group non-test graph nodes by fqn. A single fqn maps to MANY nodes when a method
+    or constructor is overloaded (``get(String)`` and ``get(Packet)`` share
+    ``…#get``) — the fqn carries no signature. Callers must aggregate over the list, never
+    pick one node, or an order-dependent representative causes phantom diffs on an
+    unchanged tree (the eureka field-test FP). Test sources are excluded — breaking a
+    test's own API is not a contract change."""
+    from collections import defaultdict
+    by: dict[str, list[dict]] = defaultdict(list)
+    for n in _nodes(cir):
+        fqn = n.get("fqn")
+        if not fqn:
+            continue
+        low = (n.get("source_file") or "").lower()
+        if "/test/" in low or low.endswith("test.java") or "/src/test/" in low:
+            continue
+        by[fqn].append(n)
+    return by
+
+
+def _any_public(nodes: list[dict]) -> bool:
+    """A named symbol is on the public surface iff ANY overload is public — a call site
+    binding to the name still resolves while one public overload remains."""
+    return any("public" in (n.get("modifiers") or []) for n in nodes)
+
+
+def _contract_axis(cir_head: Any, cir_working: Any) -> AxisResult:
+    """Public-surface regression: a public symbol removed, its visibility downgraded (no
+    public overload remains), or — when unambiguous — its signature changed.
+
+    Visibility is aggregated per fqn as *any overload public* (see ``_nodes_by_fqn``): the
+    old per-fqn last-wins keying reported a downgrade whenever a public name also had a
+    non-public overload, firing on identical HEAD/working trees. Signature change is only
+    reported for an unambiguous single-node-both-sides symbol; with overloads the fqn→
+    signature mapping is not well defined, so it is skipped rather than risk a false diff."""
+    head = _nodes_by_fqn(cir_head)
+    work = _nodes_by_fqn(cir_working)
+
+    items: list[dict] = []
+    for fqn, hnodes in sorted(head.items()):
+        if not _any_public(hnodes):
+            continue  # not on HEAD's public surface — nothing to regress
+        kind = hnodes[0].get("symbol_kind") or hnodes[0].get("type") or ""
+        wnodes = work.get(fqn)
+        if not wnodes:
+            items.append({"symbol": fqn, "kind": kind, "change": "removed"})
+        elif not _any_public(wnodes):
+            mods = [m for n in wnodes for m in (n.get("modifiers") or []) if m in ("private", "protected")]
+            items.append({"symbol": fqn, "kind": kind, "change": "visibility_downgraded",
+                          "to": sorted(set(mods)) or ["package-private"]})
+        elif len(hnodes) == 1 and len(wnodes) == 1:
+            hs, ws = hnodes[0].get("signature") or "", wnodes[0].get("signature") or ""
+            if hs and hs != ws:
+                items.append({"symbol": fqn, "kind": kind, "change": "signature_changed",
+                              "from": hs, "to": ws})
+
+    if items:
+        return AxisResult(True, f"{len(items)} public API change(s)", tuple(items))
+    return AxisResult(False)
+
+
+# ── analyzer-diff axes (reuse existing detectors, diff stable finding ids) ──────
+def _spring_finding_diff(cir_head: Any, cir_working: Any, root: Path, runner) -> AxisResult:
+    """Run a spring analyzer on both trees; report findings the edit INTRODUCED
+    (present in working, absent in HEAD, keyed by the finding's deterministic id)."""
+    try:
+        head_res = runner(cir_head, root=root)
+        work_res = runner(cir_working, root=root)
+    except Exception as exc:  # analyzer fault → could-not-compute, never false-clean
+        return AxisResult(None, f"analyzer error: {exc}")
+    head_ids = {f.id for f in head_res.findings}
+    introduced = [f for f in work_res.findings if f.id not in head_ids]
+    if introduced:
+        items = tuple(
+            {"pattern_id": f.pattern_id, "symbol": f.symbol, "severity": f.severity,
+             "title": f.title, "source_file": f.source_file}
+            for f in introduced
+        )
+        return AxisResult(True, f"{len(introduced)} new {introduced[0].category} finding(s)", items)
+    return AxisResult(False)
+
+
+def _tx_axis(cir_head: Any, cir_working: Any, root: Path) -> AxisResult:
+    from sourcecode.spring_tx_analyzer import run_tx_audit
+    return _spring_finding_diff(cir_head, cir_working, root, run_tx_audit)
+
+
+def _security_axis(cir_head: Any, cir_working: Any, root: Path) -> AxisResult:
+    from sourcecode.spring_security_audit import run_security_audit
+    return _spring_finding_diff(cir_head, cir_working, root, run_security_audit)
+
+
+# ── bean-wiring axis (injects-graph diff) ───────────────────────────────────────
+def _inbound_injects(cir: Any) -> dict[str, int]:
+    """Count injects edges pointing TO each type (who injects this bean)."""
+    counts: dict[str, int] = {}
+    for e in cir.call_graph:
+        if e.get("type") == "injects":
+            to = e.get("to")
+            if to:
+                counts[to] = counts.get(to, 0) + 1
+    return counts
+
+
+def _orphan_bean_axis(cir_head: Any, cir_working: Any) -> AxisResult:
+    """A bean that WAS injected at HEAD and has zero inbound injects in the working
+    tree — the edit severed its wiring. (New uninjected beans are NOT flagged: a
+    freshly-added bean wired nowhere yet is normal mid-edit — avoids the FP.)"""
+    head_in = _inbound_injects(cir_head)
+    work_in = _inbound_injects(cir_working)
+    work_fqns = {n.get("fqn") for n in _nodes(cir_working)}
+    items: list[dict] = []
+    for fqn, n_in in sorted(head_in.items()):
+        if n_in > 0 and work_in.get(fqn, 0) == 0 and fqn in work_fqns:
+            items.append({"symbol": fqn, "lost_injectors": n_in, "change": "wiring_severed"})
+    if items:
+        return AxisResult(True, f"{len(items)} bean(s) lost all injection wiring", tuple(items))
+    return AxisResult(False)
+
+
+# ── custom domain rules axis (Fase V5 — client-declared invariants) ─────────────
+def _custom_rules_axis(cir_head: Any, cir_working: Any, root: Path) -> AxisResult:
+    """Enforce the client's own rules (``.ask/verify-rules.json``), diffed like the
+    other axes: report only violations the edit INTRODUCED (present in the working tree,
+    absent at HEAD). No rules file ⇒ clean (never blocks). A malformed ruleset ⇒
+    could-not-compute (unverified), never a silent pass on a broken ruleset."""
+    from sourcecode import verify_rules as vr
+
+    try:
+        rules = vr.load_rules(root)
+    except vr.RulesError as exc:
+        return AxisResult(None, f"rules file error: {exc}")
+    if not rules:
+        return AxisResult(False, "no custom rules")
+
+    try:
+        head_ids = {v.id for v in vr.evaluate_all(rules, cir_head)}
+        work = vr.evaluate_all(rules, cir_working)
+    except Exception as exc:  # evaluator fault → honest degrade, never false-clean
+        return AxisResult(None, f"rule evaluation error: {exc}")
+
+    introduced = [v for v in work if v.id not in head_ids]
+    if introduced:
+        items = tuple(v.to_dict() for v in introduced)
+        n = len({v.rule_id for v in introduced})
+        return AxisResult(True, f"{len(introduced)} new violation(s) of {n} custom rule(s)", items)
+    return AxisResult(False)
+
+
+# ── blast radius (reach over the changed files; informational, not a diff) ──────
+def _blast_radius(cir_working: Any, changed_files: tuple[str, ...]) -> dict:
+    if not changed_files:
+        return {"affected_entry_points": 0, "confidence": "high", "note": "no changed files"}
+    try:
+        from sourcecode.context_graph import ContextGraph
+        from sourcecode.semantic_impact_engine import SemanticImpactEngine
+        engine = SemanticImpactEngine(ContextGraph.from_cir(cir_working))
+        # Each impact = one distinct entry point (endpoint/controller) reached by a
+        # changed type — the blast radius, not a single path.
+        impacts = engine.behavioral_impact(list(changed_files))
+        entry_points = [i.get("entry_point") for i in impacts if i.get("entry_point")]
+        return {
+            "affected_entry_points": len(entry_points),
+            "entry_points": entry_points[:10],
+            "confidence": impacts[0].get("confidence", "medium") if impacts else "medium",
+            "impacts": impacts[:3],
+        }
+    except Exception as exc:
+        return {"affected_entry_points": None, "confidence": "unknown",
+                "note": f"impact engine error: {exc}"}
+
+
+# ── the verdict ─────────────────────────────────────────────────────────────────
+def verdict(hvw: HeadVsWorking, root: Path) -> VerifyVerdict:
+    """Fuse the axes over a V0 substrate into the ``verify-edit-v1`` verdict.
+
+    exit code: 0=pass, 1=break (a blocking axis proved a regression), 2=unverified
+    (a blocking axis could not be computed — honest, never a silent pass)."""
+    root = _resolve_repo_root(Path(root))
+    axes: dict[str, AxisResult] = {
+        "contract_broken": _contract_axis(hvw.cir_head, hvw.cir_working),
+        "tx_boundary_changed": _tx_axis(hvw.cir_head, hvw.cir_working, root),
+        "security_delta": _security_axis(hvw.cir_head, hvw.cir_working, root),
+        "new_orphan_bean": _orphan_bean_axis(hvw.cir_head, hvw.cir_working),
+        "custom_rule_violated": _custom_rules_axis(hvw.cir_head, hvw.cir_working, root),
+    }
+    blast = _blast_radius(hvw.cir_working, hvw.changed_files)
+
+    reasons: list[str] = []
+    broke = False
+    unverified = False
+    for name in _BLOCKING_AXES:
+        ax = axes[name]
+        if ax.changed is True:
+            broke = True
+            reasons.append(f"{name}: {ax.detail}")
+        elif ax.changed is None:
+            unverified = True
+            reasons.append(f"{name}: could not verify ({ax.detail})")
+
+    if broke:
+        verdict_str, code = "break", 1
+    elif unverified:
+        verdict_str, code = "unverified", 2
+    else:
+        verdict_str, code = "pass", 0
+
+    return VerifyVerdict(
+        verdict=verdict_str,
+        axes=axes,
+        changed_files=hvw.changed_files,
+        blast_radius=blast,
+        reasons=tuple(reasons),
+        exit_code=code,
+        head_sha=hvw.head_sha,
+    )
+
+
+def verify_edit(path: Path) -> VerifyVerdict:
+    """End-to-end: build the substrate and return the verdict. The single entry the
+    CLI command and (Fase V2) the MCP tool call."""
+    root = _resolve_repo_root(Path(path))
+    return verdict(head_vs_working(root), root)
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Fase V3 — git hook (same binary, same verdict, in local and CI)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_HOOK_MARKER = "ask verify-edit gate"
+HOOK_TYPES = ("pre-commit", "pre-push")
+
+# `--ci` gates the exit code; a break/unverified verdict (exit 1/2) blocks the commit.
+# `--no-verify` is the standard git escape hatch. The block is fenced by the marker so
+# re-installs are idempotent and a foreign hook is never silently clobbered.
+_HOOK_SCRIPT = """\
+#!/bin/sh
+# >>> {marker} >>>
+# Blocks the commit when the working tree changed runtime behavior vs HEAD
+# (public contract / @Transactional boundary / security / bean wiring).
+# Installed by `ask verify-edit --install-hook`. Delete this block to disable.
+ask verify-edit --ci --format json || {{
+  echo "" >&2
+  echo "verify-edit blocked this commit: runtime-behavior change vs HEAD (see verdict above)." >&2
+  echo "Fix the reported axes, or bypass with: git commit --no-verify" >&2
+  exit 1
+}}
+# <<< {marker} <<<
+"""
+
+
+def install_git_hook(path: Path, hook_type: str = "pre-commit") -> Path:
+    """Install a git ``hook_type`` hook that runs ``ask verify-edit --ci``.
+
+    Returns the hook path. Idempotent: re-installing over a hook we previously wrote
+    (detected by the marker) overwrites it; a hook we did NOT write is never clobbered
+    — that raises, so a project's existing hook is safe.
+    """
+    if hook_type not in HOOK_TYPES:
+        raise VerifyEditError(f"unknown hook type {hook_type!r} (expected one of {', '.join(HOOK_TYPES)})")
+    root = _resolve_repo_root(Path(path))
+    if not _head_sha(root) and not (root / ".git").exists():
+        raise VerifyEditError(f"{root} is not a git repository")
+    # Resolve the real hooks dir via git so worktrees/submodules (where .git is a file
+    # or core.hooksPath is set) are handled correctly, not assumed to be .git/hooks.
+    r = _run_git(root, "rev-parse", "--git-path", "hooks", timeout=10)
+    if r.returncode != 0:
+        raise VerifyEditError(f"could not resolve the git hooks directory: {r.stderr.strip()}")
+    hooks_dir = (root / r.stdout.strip()).resolve()
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_path = hooks_dir / hook_type
+
+    if hook_path.exists():
+        existing = hook_path.read_text(encoding="utf-8", errors="replace")
+        if _HOOK_MARKER not in existing:
+            raise VerifyEditError(
+                f"a {hook_type} hook already exists at {hook_path} and was not installed by "
+                f"verify-edit — not overwriting. Remove it first, or add the verify-edit call "
+                f"into it manually (`ask verify-edit --ci`)."
+            )
+
+    hook_path.write_text(_HOOK_SCRIPT.format(marker=_HOOK_MARKER), encoding="utf-8")
+    hook_path.chmod(0o755)
+    return hook_path