@deftai/directive-content 0.58.0 → 0.60.0

package/scripts/verify_no_task_runtime.py

@@ -1,171 +0,0 @@
-#!/usr/bin/env python3
-"""Fail when runtime Python code hard-depends on go-task (#1659)."""
-
-from __future__ import annotations
-
-import ast
-import sys
-from dataclasses import dataclass
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent
-SCAN_PATHS = (ROOT / "run", ROOT / "scripts")
-SUBPROCESS_FUNCS = {"run", "check_call", "check_output", "Popen", "call"}
-
-
-@dataclass(frozen=True)
-class Finding:
-    path: Path
-    line: int
-    message: str
-
-
-def _is_name_or_attr(node: ast.AST, dotted: str) -> bool:
-    parts = dotted.split(".")
-    current = node
-    for expected in reversed(parts):
-        if isinstance(current, ast.Attribute):
-            if current.attr != expected:
-                return False
-            current = current.value
-            continue
-        if isinstance(current, ast.Name):
-            return current.id == expected and expected == parts[0]
-        return False
-    return isinstance(current, ast.Name) and current.id == parts[0]
-
-
-def _literal_first_arg(call: ast.Call) -> str | None:
-    if not call.args:
-        return None
-    first = call.args[0]
-    if isinstance(first, ast.Constant) and isinstance(first.value, str):
-        return first.value
-    if isinstance(first, (ast.List, ast.Tuple)) and first.elts:
-        head = first.elts[0]
-        if isinstance(head, ast.Constant) and isinstance(head.value, str):
-            return head.value
-    return None
-
-
-class Visitor(ast.NodeVisitor):
-    def __init__(self, path: Path) -> None:
-        self.path = path
-        self.findings: list[Finding] = []
-        self.subprocess_names = {"subprocess"}
-        self.subprocess_func_names: set[str] = set()
-        self.shutil_names = {"shutil"}
-        self.shutil_which_names: set[str] = set()
-
-    def visit_Import(self, node: ast.Import) -> None:  # noqa: N802
-        for alias in node.names:
-            local_name = alias.asname or alias.name
-            if alias.name == "subprocess":
-                self.subprocess_names.add(local_name)
-            if alias.name == "shutil":
-                self.shutil_names.add(local_name)
-        self.generic_visit(node)
-
-    def visit_ImportFrom(self, node: ast.ImportFrom) -> None:  # noqa: N802
-        if node.module == "subprocess":
-            for alias in node.names:
-                if alias.name in SUBPROCESS_FUNCS:
-                    self.subprocess_func_names.add(alias.asname or alias.name)
-        if node.module == "shutil":
-            for alias in node.names:
-                if alias.name == "which":
-                    self.shutil_which_names.add(alias.asname or alias.name)
-        self.generic_visit(node)
-
-    def visit_Call(self, node: ast.Call) -> None:  # noqa: N802
-        if isinstance(node.func, ast.Attribute):
-            if (
-                isinstance(node.func.value, ast.Name)
-                and node.func.value.id in self.subprocess_names
-                and node.func.attr in SUBPROCESS_FUNCS
-                and _literal_first_arg(node) == "task"
-            ):
-                self.findings.append(
-                    Finding(
-                        self.path,
-                        node.lineno,
-                        "runtime subprocess invocation of go-task is forbidden",
-                    )
-                )
-            if (
-                node.func.attr == "which"
-                and (
-                    _is_name_or_attr(node.func.value, "shutil")
-                    or (
-                        isinstance(node.func.value, ast.Name)
-                        and node.func.value.id in self.shutil_names
-                    )
-                )
-                and _literal_first_arg(node) == "task"
-            ):
-                self.findings.append(
-                    Finding(
-                        self.path,
-                        node.lineno,
-                        "runtime go-task PATH probe is forbidden",
-                    )
-                )
-        if isinstance(node.func, ast.Name):
-            if node.func.id in self.subprocess_func_names and _literal_first_arg(node) == "task":
-                self.findings.append(
-                    Finding(
-                        self.path,
-                        node.lineno,
-                        "runtime subprocess invocation of go-task is forbidden",
-                    )
-                )
-            if node.func.id in self.shutil_which_names and _literal_first_arg(node) == "task":
-                self.findings.append(
-                    Finding(
-                        self.path,
-                        node.lineno,
-                        "runtime go-task PATH probe is forbidden",
-                    )
-                )
-        self.generic_visit(node)
-
-
-def _python_files() -> list[Path]:
-    files = [ROOT / "run"]
-    files.extend(
-        path
-        for path in sorted((ROOT / "scripts").glob("*.py"))
-        if path.name != Path(__file__).name
-    )
-    return files
-
-
-def scan() -> list[Finding]:
-    findings: list[Finding] = []
-    for path in _python_files():
-        try:
-            tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
-        except (OSError, SyntaxError) as exc:
-            findings.append(Finding(path, getattr(exc, "lineno", 1) or 1, str(exc)))
-            continue
-        visitor = Visitor(path)
-        visitor.visit(tree)
-        findings.extend(visitor.findings)
-    return findings
-
-
-def main(argv: list[str] | None = None) -> int:
-    _ = argv
-    findings = scan()
-    if not findings:
-        print("No runtime go-task subprocess dependencies found")
-        return 0
-    print("Runtime go-task dependencies found:", file=sys.stderr)
-    for finding in findings:
-        rel = finding.path.relative_to(ROOT)
-        print(f"  {rel}:{finding.line}: {finding.message}", file=sys.stderr)
-    return 1
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/scripts/verify_scm_boundary.py

@@ -1,509 +0,0 @@
-#!/usr/bin/env python3
-"""verify_scm_boundary.py -- deterministic gate against raw ``gh`` calls (#1145 / N5).
-
-Pure stdlib, cross-platform. Invoked from:
-
-- ``task verify:scm-boundary`` (aggregated into ``task check``)
-- ``uv run python scripts/verify_scm_boundary.py [--project-root <path>] [--allow-list <path>]``
-
-Why this gate exists
---------------------
-Issue #1145 (N5 of the #1119 cohort) introduces ``scripts.scm.call(source,
-verb, args, **kwargs)`` as the single seam through which deft's verb layer
-(``scripts/triage_*.py``, ``scripts/scope_*.py``, ``scripts/slice_*.py``,
-``scripts/issue_ingest.py``, ...) invokes the underlying SCM CLI. Pre-N5,
-every consumer called ``subprocess.run(["gh", ...])`` directly; the first
-non-GitHub consumer would have hit an undocumented coupling deep in the
-call stack. The shim relocates that coupling to one indirection point so
-the future SCM abstraction (#445 / #935 Workstream 6) has a single seam
-to extend.
-
-Per AGENTS.md ``## Rule Authority`` [AXIOM] this gate elevates the
-"no raw gh calls in the verb layer" rule from prose tier to deterministic
-tier -- the gate body IS the rule; the AGENTS.md cross-reference in
-``## SCM tooling -- prefer ghx (#884)`` is documentation, not duplication.
-
-Scope (which files MUST go through ``scm.call``)
-------------------------------------------------
-The verifier deliberately scopes by file glob rather than scanning every
-tracked Python file. Release tooling (``scripts/release*.py``,
-``scripts/reconcile_issues.py``), the REST helper module
-(``scripts/gh_rest.py``), the ghx installer (``scripts/setup_ghx.py``),
-and the preflight gates (``scripts/preflight_*.py``) have legitimate
-direct-``gh`` responsibilities (they're release-tier or backend-tier code,
-not verb-layer consumers) and are NOT scoped in. The full glob set lives
-in :data:`SCOPE_GLOBS`.
-
-Files in scope are required to invoke ``gh`` / ``ghx`` only via
-``scripts.scm.call``. Any ``subprocess.run`` / ``subprocess.check_output`` /
-``subprocess.check_call`` / ``subprocess.Popen`` / ``subprocess.call`` /
-``Popen`` / ``os.system`` call whose first argv element is the literal
-``"gh"`` or ``"ghx"`` is a violation -- the AST scan in
-:func:`scan_file` flags them at the call site.
-
-Detection scope (AST inspection)
---------------------------------
-The scan is AST-based rather than regex-based so call sites split across
-multiple lines (the common indented multi-line ``subprocess.run([\\n
-    "gh", "issue", "close", ...]``) are detected reliably. We look at:
-
-- :func:`ast.Call` nodes whose ``.func`` resolves to one of
-  ``subprocess.run`` / ``subprocess.check_output`` /
-  ``subprocess.check_call`` / ``subprocess.Popen`` / ``subprocess.call``,
-  ``Popen`` (the unqualified form used after
-  ``from subprocess import Popen``), or ``os.system``.
-- For ``os.system`` we look at the first positional argument as a string
-  constant; for the ``subprocess`` family we look at the first positional
-  argument as either a list / tuple literal (whose first element is a
-  string constant) or a single string-constant argument when
-  ``shell=True`` is also passed.
-- Any of those whose first argv element matches ``GH_BINARIES``
-  (``"gh"`` / ``"ghx"``) is recorded as a finding.
-
-False-positive guards
----------------------
-- ``scripts/scm.py`` is EXEMPT from scanning -- the shim itself is the
-  one place that legitimately invokes ``gh`` / ``ghx`` directly.
-- ``--allow-list <path>`` accepts a newline-separated list of glob
-  patterns for documented exceptions (e.g. a test fixture intentionally
-  containing a raw ``gh`` call).
-- The :data:`SCOPE_GLOBS` set is the exhaustive enumeration of files
-  that MUST go through the shim. Files outside the set are not scanned;
-  they're either out-of-scope (per the #1145 "Not in scope" clause) or
-  backend / release-tier code with legitimate direct-``gh`` needs.
-
-Exit codes (three-state, mirrors :mod:`scripts.preflight_branch` and
-:mod:`scripts.verify_encoding`):
-
-- ``0`` -- clean: every in-scope file uses ``scm.call`` exclusively.
-- ``1`` -- violations: prints per-hit ``path:line:col [helper] context``.
-- ``2`` -- config error: ``--allow-list`` path unreadable, ``--project-root``
-  invalid, or unrecognised CLI shape.
-"""
-
-from __future__ import annotations
-
-import argparse
-import ast
-import fnmatch
-import sys
-from collections.abc import Iterable
-from pathlib import Path
-
-#: Binary names whose presence as the first argv element marks a violation.
-#: ``gh`` is the canonical GitHub CLI; ``ghx`` is the #884 caching proxy
-#: that uses the same surface. Both should route through
-#: :func:`scripts.scm.call` from the verb layer so the source-aware
-#: indirection (NotImplementedError for non-GitHub sources) is exercised.
-GH_BINARIES: frozenset[str] = frozenset({"gh", "ghx"})
-
-#: Helper functions whose first positional argument we inspect. Mirrors
-#: :data:`SUBPROCESS_DOTTED_HELPERS` plus the bare ``Popen`` import shape
-#: (``from subprocess import Popen``) and ``os.system``.
-SUBPROCESS_DOTTED_HELPERS: frozenset[str] = frozenset({
-    "run",
-    "check_output",
-    "check_call",
-    "call",
-    "Popen",
-})
-
-#: Project-root-relative glob patterns enumerating the files in scope for
-#: the boundary gate. Files in this set are required to invoke
-#: ``gh`` / ``ghx`` only via :func:`scripts.scm.call`. The set follows the
-#: #1145 acceptance criteria mandate plus the "any other call sites
-#: discovered via repo-wide grep" catch-all narrowed to the verb-layer
-#: glob shape -- release tooling, REST helpers, and preflight gates are
-#: intentionally NOT in scope.
-SCOPE_GLOBS: tuple[str, ...] = (
-    # Triage verbs (public surface).
-    "scripts/triage_*.py",
-    # Triage verbs (private helpers consumed by the public surface).
-    "scripts/_triage_*.py",
-    # Scope-lifecycle verbs.
-    "scripts/scope_*.py",
-    "scripts/_scope_*.py",
-    # Slice / cohort-record verbs.
-    "scripts/slice_*.py",
-    # Resume-condition grammar parser (consumed by triage_actions:defer).
-    "scripts/resume_conditions.py",
-    # Issue ingest -- the delegate target for triage:accept (#985).
-    "scripts/issue_ingest.py",
-)
-
-#: Path-glob patterns auto-exempt because the file legitimately invokes
-#: ``gh`` / ``ghx`` as a backend-tier or shim-internal responsibility.
-#: Each entry is matched against the path's POSIX form (forward slashes)
-#: via :func:`fnmatch.fnmatchcase`. Adding to this list MUST be justified
-#: in the commit message and paired with a regression test that exercises
-#: the exempt file's existing behaviour.
-BUILTIN_ALLOW_LIST: tuple[str, ...] = (
-    # The shim itself -- the one place that legitimately invokes
-    # ``gh`` / ``ghx`` directly. Self-skip guards against a regression
-    # where the shim is in scope of its own check.
-    "scripts/scm.py",
-    # The verifier's own test file -- the fixture and the test
-    # source both contain literal ``["gh", ...]`` text and would
-    # otherwise flag themselves. Forward-coverage is upheld by the
-    # tests inside this file rather than by re-scanning them.
-    "tests/cli/test_verify_scm_boundary.py",
-)
-
-
-class Finding:
-    """One ``subprocess gh`` / ``Popen gh`` / ``os.system gh`` detection record."""
-
-    __slots__ = ("path", "line", "col", "helper", "context")
-
-    def __init__(
-        self, path: str, line: int, col: int, helper: str, context: str
-    ) -> None:
-        self.path = path
-        self.line = line
-        self.col = col
-        self.helper = helper
-        self.context = context
-
-    def render(self) -> str:
-        ctx = self.context if len(self.context) <= 120 else self.context[:117] + "..."
-        return f"  {self.path}:{self.line}:{self.col} [{self.helper}] {ctx}"
-
-
-def _resolve_helper_name(func: ast.AST) -> str | None:
-    """Return ``"subprocess.run"`` / ``"Popen"`` / ``"os.system"`` etc., or ``None``.
-
-    Resolves the dotted-name shape of a :class:`ast.Call` ``.func`` node so
-    we can decide whether the call targets one of the subprocess-family
-    helpers we care about. Handles both attribute access
-    (``subprocess.run(...)``) and bare-name access (``Popen(...)`` after
-    ``from subprocess import Popen``). Anything else returns ``None``.
-    """
-    if isinstance(func, ast.Attribute):
-        # subprocess.run(...) / os.system(...) -- attribute access.
-        value = func.value
-        if isinstance(value, ast.Name):
-            return f"{value.id}.{func.attr}"
-        # Deeper attribute chains (e.g. mod.subprocess.run) are unusual
-        # and not part of our threat model; ignore.
-        return None
-    if isinstance(func, ast.Name):
-        # Bare name -- only meaningful for Popen (or aliased imports we
-        # do NOT attempt to detect; the verifier deliberately favors
-        # false-negatives over false-positives on import-alias gymnastics).
-        return func.id
-    return None
-
-
-def _is_target_helper(helper: str) -> bool:
-    """Return True when ``helper`` is a subprocess-family or os.system seam.
-
-    ``helper`` is the dotted-or-bare name returned by
-    :func:`_resolve_helper_name`. We accept:
-
-    - ``subprocess.run`` / ``.check_output`` / ``.check_call`` /
-      ``.call`` / ``.Popen``  (the canonical surface).
-    - bare ``Popen``  (``from subprocess import Popen`` then ``Popen(...)``).
-    - ``os.system``  (the legacy shell-invocation surface).
-    """
-    if helper == "os.system":
-        return True
-    if helper == "Popen":
-        return True
-    if helper.startswith("subprocess."):
-        suffix = helper.split(".", 1)[1]
-        return suffix in SUBPROCESS_DOTTED_HELPERS
-    return False
-
-
-def _extract_first_argv(call: ast.Call, helper: str) -> str | None:
-    """Return the first argv element when it is a constant string, else ``None``.
-
-    For the subprocess family we look at the first positional argument:
-
-    - List / tuple literal (``["gh", "issue", "close"]``) -- the first
-      element of the literal.
-    - Single string constant (``"gh issue close"``) -- the whole string,
-      typically passed alongside ``shell=True``. We split on whitespace
-      and inspect the first token.
-
-    For ``os.system`` we look at the first positional argument as a
-    string constant and split on whitespace.
-
-    Anything else (variable, expression, formatted string, kwargs-only
-    invocation) returns ``None`` -- the verifier deliberately favors
-    false-negatives over false-positives on dynamically-built argv lists.
-    A future agent who hides a ``gh`` invocation behind ``cmd = ["gh",
-    ...]; subprocess.run(cmd)`` defeats the scan; we accept that limit
-    rather than fail loudly on every variable-named argv list in the
-    codebase. The forward-coverage contract here is "the common shape
-    is detected"; the exotic shape is a documented gap.
-    """
-    if not call.args:
-        return None
-    first = call.args[0]
-
-    if helper == "os.system":
-        if isinstance(first, ast.Constant) and isinstance(first.value, str):
-            tokens = first.value.strip().split()
-            return tokens[0] if tokens else None
-        return None
-
-    # subprocess family or bare Popen.
-    if isinstance(first, (ast.List, ast.Tuple)):
-        if not first.elts:
-            return None
-        head = first.elts[0]
-        if isinstance(head, ast.Constant) and isinstance(head.value, str):
-            return head.value
-        return None
-    if isinstance(first, ast.Constant) and isinstance(first.value, str):
-        # Single-string form -- typically paired with shell=True. Inspect
-        # the first whitespace-delimited token so ``"gh pr list"`` is
-        # caught the same way as ``["gh", "pr", "list"]``.
-        tokens = first.value.strip().split()
-        return tokens[0] if tokens else None
-    return None
-
-
-def _slice_source_line(source_lines: list[str], lineno: int) -> str:
-    """Return the source line at ``lineno`` (1-indexed) or empty string.
-
-    Note: ast lineno is 1-based; list index is 0-based, hence the
-    ``lineno - 1`` subscript.
-    """
-    if 1 <= lineno <= len(source_lines):
-        return source_lines[lineno - 1].rstrip()
-    return ""
-
-
-def scan_file(rel_path: str, full_path: Path) -> list[Finding]:
-    """Scan one Python file for raw ``gh`` / ``ghx`` subprocess invocations.
-
-    Returns a list of :class:`Finding` records (one per call site). An
-    unparseable file (SyntaxError) returns an empty list -- the gate is
-    intentionally permissive on parse failures so a single broken file
-    does not block a whole pre-commit. Production code that parses
-    cleanly is scanned exhaustively.
-    """
-    findings: list[Finding] = []
-    try:
-        source = full_path.read_text(encoding="utf-8")
-    except OSError:
-        return findings
-    try:
-        tree = ast.parse(source, filename=str(full_path))
-    except SyntaxError:
-        return findings
-
-    source_lines = source.splitlines()
-
-    for node in ast.walk(tree):
-        if not isinstance(node, ast.Call):
-            continue
-        helper = _resolve_helper_name(node.func)
-        if helper is None or not _is_target_helper(helper):
-            continue
-        first_argv = _extract_first_argv(node, helper)
-        if first_argv not in GH_BINARIES:
-            continue
-        # Defensive: ast nodes carry 1-based lineno + 0-based col_offset.
-        line = getattr(node, "lineno", 0) or 0
-        col = (getattr(node, "col_offset", 0) or 0) + 1
-        ctx = _slice_source_line(source_lines, line) or f"{helper}(...)"
-        findings.append(
-            Finding(
-                path=rel_path,
-                line=line,
-                col=col,
-                helper=helper,
-                context=ctx.strip(),
-            )
-        )
-    return findings
-
-
-def _load_allow_list(path: Path | None) -> list[str]:
-    """Read newline-separated glob patterns from ``path``; ignore comments.
-
-    Lines starting with ``#`` and blank lines are skipped. Returns an
-    empty list when ``path`` is ``None``. Raises :class:`FileNotFoundError`
-    when a non-``None`` path does not exist (caller maps to exit 2).
-    """
-    if path is None:
-        return []
-    raw = path.read_text(encoding="utf-8", errors="replace")
-    out: list[str] = []
-    for line in raw.splitlines():
-        stripped = line.strip()
-        if not stripped or stripped.startswith("#"):
-            continue
-        out.append(stripped)
-    return out
-
-
-def _is_allow_listed(rel_path: str, patterns: Iterable[str]) -> bool:
-    """Return True when ``rel_path`` (POSIX form) matches any glob in patterns."""
-    return any(fnmatch.fnmatchcase(rel_path, pat) for pat in patterns)
-
-
-def _candidate_files(
-    project_root: Path, scope_globs: Iterable[str]
-) -> list[tuple[str, Path]]:
-    """Resolve :data:`SCOPE_GLOBS` to existing ``(rel_path, full_path)`` pairs.
-
-    The scope globs are resolved relative to ``project_root`` via
-    :meth:`Path.glob`. Non-existent globs (e.g. ``scripts/slice_*.py``
-    on a checkout that has not yet landed those files) are silently
-    skipped. The output is sorted by POSIX-form rel-path for stable
-    diagnostic ordering.
-    """
-    out: dict[str, Path] = {}
-    for pattern in scope_globs:
-        for full in project_root.glob(pattern):
-            if not full.is_file():
-                continue
-            rel = full.relative_to(project_root).as_posix()
-            out[rel] = full
-    return sorted(out.items(), key=lambda item: item[0])
-
-
-def evaluate(
-    project_root: Path,
-    *,
-    allow_list_path: Path | None = None,
-    scope_globs: Iterable[str] = SCOPE_GLOBS,
-) -> tuple[int, list[Finding], str]:
-    """Pure function returning ``(exit_code, findings, human_message)``.
-
-    Separated from :func:`main` so tests can drive every state without
-    ``capsys`` plumbing or env-var leak.
-
-    ``scope_globs`` is parameterised so the unit tests can scope the
-    scan down to a temp-directory fixture without touching the real
-    repository tree.
-    """
-    try:
-        custom_globs = _load_allow_list(allow_list_path)
-    except FileNotFoundError as exc:
-        return 2, [], (
-            f"verify_scm_boundary: --allow-list file not found: {exc}\n"
-            "  Recovery: pass an existing path or omit the flag."
-        )
-    except OSError as exc:
-        return 2, [], (
-            f"verify_scm_boundary: --allow-list unreadable: {exc}\n"
-            "  Recovery: check file permissions."
-        )
-
-    if not project_root.is_dir():
-        return 2, [], (
-            f"verify_scm_boundary: --project-root is not a directory: "
-            f"{project_root}\n"
-            "  Recovery: pass an existing directory path."
-        )
-
-    allow_globs = list(BUILTIN_ALLOW_LIST) + custom_globs
-
-    candidates = _candidate_files(project_root, scope_globs)
-    findings: list[Finding] = []
-    scanned = 0
-    for rel, full in candidates:
-        if _is_allow_listed(rel, allow_globs):
-            continue
-        scanned += 1
-        findings.extend(scan_file(rel, full))
-
-    if findings:
-        files_with_hits = len({f.path for f in findings})
-        header = (
-            f"verify_scm_boundary: detected {len(findings)} raw "
-            f"`gh` / `ghx` subprocess call(s) across {files_with_hits} "
-            f"file(s) (#1145 / N5).\n"
-            "  Root cause: the verb layer is required to invoke `gh` only "
-            "via `scripts.scm.call(source, verb, args, **kwargs)` so a "
-            "future\n"
-            "  GitLab / Gitea / local consumer sees a loud "
-            "`NotImplementedError` (see #445 / #935 Workstream 6) instead "
-            "of a confusing\n"
-            "  `gh: command not found` deep in the call stack. Fix: rewrite "
-            "the offending call sites as\n"
-            "    `import scm`\n"
-            "    `scm.call(\"github-issue\", verb, args, ...)`\n"
-            "  Allow-list a documented exception via "
-            "`--allow-list <path>` (file with newline-separated glob "
-            "patterns)."
-        )
-        body = "\n".join(f.render() for f in findings[:50])
-        if len(findings) > 50:
-            body += f"\n  ... and {len(findings) - 50} more"
-        return 1, findings, f"{header}\n{body}"
-
-    msg = (
-        f"verify_scm_boundary: {scanned} verb-layer file(s) clean -- "
-        "every `gh` / `ghx` invocation routes through `scm.call` "
-        "(#1145 / N5)."
-    )
-    return 0, findings, msg
-
-
-def _build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(
-        prog="verify_scm_boundary.py",
-        description=(
-            "Deterministic gate against raw `gh` / `ghx` subprocess calls "
-            "outside `scripts/scm.py` (#1145 / N5). Scans verb-layer "
-            "Python files for subprocess / Popen / os.system invocations "
-            "whose first argv element is the literal `gh` or `ghx` and "
-            "fails loud when any are found -- the verb layer is required "
-            "to invoke `gh` only via `scm.call(source, verb, args)`."
-        ),
-    )
-    parser.add_argument(
-        "--project-root",
-        default=".",
-        help="Project root path (default: current working directory).",
-    )
-    parser.add_argument(
-        "--allow-list",
-        default=None,
-        help=(
-            "Path to a file with newline-separated glob patterns of "
-            "documented exceptions. Lines starting with # are comments."
-        ),
-    )
-    parser.add_argument(
-        "--quiet",
-        action="store_true",
-        help="Suppress the OK message (errors still print).",
-    )
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    # Force UTF-8 stdout/stderr so the diagnostic output renders correctly
-    # on a Windows console whose default codepage is cp1252 / cp437. Mirrors
-    # the block in scripts/verify_encoding.py exactly.
-    if hasattr(sys.stdout, "reconfigure"):
-        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
-    if hasattr(sys.stderr, "reconfigure"):
-        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
-
-    parser = _build_parser()
-    args = parser.parse_args(argv)
-    project_root = Path(args.project_root).resolve()
-    allow_list_path = Path(args.allow_list).resolve() if args.allow_list else None
-
-    code, _findings, msg = evaluate(
-        project_root,
-        allow_list_path=allow_list_path,
-    )
-    if code == 0:
-        if not args.quiet:
-            print(msg)
-    else:
-        print(msg, file=sys.stderr)
-    return code
-
-
-if __name__ == "__main__":
-    sys.exit(main())