@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/agents_md_coverage_grep.py

@@ -0,0 +1,382 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag stale agent-companion files under the root-only AGENTS.md convention.
+
+Why this enforcement exists. The repository carries a single agent-facing
+canon at the root ``AGENTS.md``; per-folder operating guidance lives in each
+folder's ``README.md``, which serves both the human reader and the agent
+reader. Per-folder ``AGENTS.md`` companions are no longer required — a
+meaningful folder without one passes. The one defect this sweep still guards
+is staleness: a per-folder companion that an author kept (the rare standalone
+companion the convention permits) must not fall behind its folder after the
+folder's artifacts or conventions changed. An absent companion is never a
+finding; only a present, committed-but-stale companion is.
+
+The meaningful-folder set. A folder is *meaningful* when it is navigable —
+a contributor or an agent reasons about it as a unit — and load-bearing. The
+enumeration is the navigable-folder set the README convention applies to; it
+is retained here as the source-of-truth for the freshness check's
+folder-ownership map and is reported as ``folders_inspected`` for information.
+The set is the union of two reproducible rules, minus a fixed exclusion list:
+
+- **(A) Companion-anchored.** Any folder that already carries a contributor
+  ``README.md`` directly. Test-fixture leaf dirs (whose README is itself the
+  subject of a presence check) and single-artifact example scaffolds are
+  excluded — their README documents a fixture, not a navigable subsystem.
+- **(B) Source-package.** Any ``src/apothem`` folder that directly contains a
+  Python source file but carries no README — the harness adapter packages,
+  the shared adapter helpers, the hook library. An agent operating inside one
+  of these packages needs the same orientation a README-bearing folder gives.
+
+Constant exclusions across both rules: vendored trees, generated trees, the
+git/cache/ephemera directories, rendered harness-output template leaves, and
+the plan-suite scratch. Including any of those would pollute fixtures or
+describe machinery no contributor navigates by hand. Materialized
+harness-output ``AGENTS.md`` files under ``src/apothem/harnesses/*/templates/``
+are product surfaces, not companions, and are excluded by the same rule.
+
+Freshness. A *present* per-folder companion is *stale* when its folder's
+directly-contained artifacts were last committed more recently than the
+companion itself. The signal is the git commit timestamp, not the filesystem
+mtime: a checkout rewrites mtimes, so only commit history carries the truth of
+"what changed when". A single ``git log`` pass buckets every tracked file to
+its nearest meaningful-folder ancestor; a folder is stale when its newest
+content commit postdates its committed companion's commit. Folders with no
+companion on disk are skipped entirely — absence is not a finding under the
+root-only convention. Where git history is unavailable (a shallow clone, a
+non-git tree), freshness is skipped and the sweep reports a clean pass — it
+never blocks a fresh clone.
+
+Posture. The result is advisory: the sweep surfaces findings and never
+silent-blocks by default, honoring the agnostic gate posture. The orchestrator
+reads the JSON ``advisory: true`` flag plus the inner ``passed`` field — a
+stale-companion finding surfaces as ``advisory_findings_present`` without
+gating the ``gate --all`` run. CI opts into strict enforcement separately.
+``_main`` always exits 0 so the advisory posture holds regardless of findings;
+the verdict travels in the JSON, not the exit code.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "agents-md-coverage-grep"
+RULE_ANCHOR: Final[str] = "rules/agents-md-convention.md"
+
+# Advisory posture: the sweep always exits 0 (the verdict travels in the JSON
+# ``advisory`` / ``passed`` fields), so only the pass code is needed here.
+EXIT_PASS: Final[int] = 0
+
+# The agent-companion filename and its human-facing sibling.
+COMPANION_NAME: Final[str] = "AGENTS.md"
+README_NAME: Final[str] = "README.md"
+
+# Bound the git invocation so a hung `git log` cannot stall the sweep; a
+# timeout is treated as a transient git error and degrades to a clean pass.
+GIT_TIMEOUT_SECONDS: Final[int] = 10
+
+# Path segments that mark a directory as out of scope wherever they appear.
+# Vendored trees, generated output, caches, and ephemera are never navigable
+# subsystems an agent reasons about by hand.
+_EXCLUDED_SEGMENTS: Final[frozenset[str]] = frozenset(
+    {
+        ".git",
+        "node_modules",
+        "_vendor",
+        "dist",
+        ".audit",
+        ".plans",
+        ".hypothesis",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".venv",
+        "venv",
+        "__pycache__",
+    }
+)
+
+# Relative-path prefixes whose subtree is excluded as a whole.
+_EXCLUDED_PREFIXES: Final[tuple[str, ...]] = (
+    "site/dist",
+    "site/node_modules",
+)
+
+# Rule-(A) carve-outs: a README under one of these is a fixture/example
+# README, not a navigable-subsystem README. Matched as path substrings on the
+# POSIX-relative folder path.
+_FIXTURE_FOLDER_MARKERS: Final[tuple[str, ...]] = (
+    "tests/scripts/inject-header/fixtures",
+    "examples/minimal-",
+)
+
+# Rule-(B) scope: source-package folders live under this prefix.
+_SOURCE_PACKAGE_PREFIX: Final[str] = "src/apothem"
+_PYTHON_SUFFIX: Final[str] = ".py"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One stale present per-folder agent-companion file."""
+
+    surface: str
+    kind: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated coverage result for a single sweep."""
+
+    grep: str
+    root: str
+    folders_inspected: int
+    freshness_checked: bool
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "folders_inspected": self.folders_inspected,
+            "freshness_checked": self.freshness_checked,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+            "advisory": True,
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _has_excluded_segment(rel_posix: str) -> bool:
+    """Return True iff any path segment marks the path out of scope."""
+    if not rel_posix or rel_posix == ".":
+        return False
+    if any(rel_posix == p or rel_posix.startswith(p + "/") for p in _EXCLUDED_PREFIXES):
+        return True
+    return any(segment in _EXCLUDED_SEGMENTS for segment in rel_posix.split("/"))
+
+
+def _is_fixture_folder(rel_posix: str) -> bool:
+    """Return True iff a folder is a test-fixture or single-artifact example leaf."""
+    if "/" in rel_posix:
+        parent, _, leaf = rel_posix.rpartition("/")
+        # tests/conformity/<matcher>/{fail,pass} — the README is the grep subject.
+        if leaf in {"fail", "pass"} and parent.startswith("tests/conformity/"):
+            return True
+    return any(marker in rel_posix for marker in _FIXTURE_FOLDER_MARKERS)
+
+
+def _is_harness_template_leaf(rel_posix: str) -> bool:
+    """Return True iff a folder is a rendered harness-output template leaf."""
+    parts = rel_posix.split("/")
+    # src/apothem/harnesses/<name>/templates[/...]
+    return (
+        len(parts) >= 5
+        and parts[:3] == ["src", "apothem", "harnesses"]
+        and "templates" in parts[4:5]
+    )
+
+
+def _rel_posix(path: Path, root_resolved: Path) -> str | None:
+    try:
+        rel = path.resolve().relative_to(root_resolved).as_posix()
+    except ValueError:
+        return None
+    return "." if rel == "" else rel
+
+
+def meaningful_folders(root: Path) -> list[str]:
+    """Enumerate the meaningful-folder set under ``root``.
+
+    Pre-conditions: ``root`` is the repository root (or a subtree).
+    Post-conditions: returns the sorted, deduplicated POSIX-relative folder
+    paths (``.`` denotes the root) that satisfy rule (A) or rule (B) and pass
+    the constant exclusions. Re-running over an unchanged tree yields the
+    identical set — the enumeration is the single source of truth the
+    presence/freshness check and the documentation convention both consume.
+    """
+    root_resolved = root.resolve()
+    folders: set[str] = set()
+
+    # Rule (A): folders carrying a contributor README, minus fixture/example leaves.
+    for readme in root.rglob(README_NAME):
+        if not readme.is_file():
+            continue
+        rel = _rel_posix(readme.parent, root_resolved)
+        if rel is None or _has_excluded_segment(rel):
+            continue
+        if _is_fixture_folder(rel):
+            continue
+        folders.add(rel)
+
+    # Rule (B): src/apothem source-package folders without a README, minus
+    # vendored trees and rendered harness-template leaves.
+    for py_file in root.rglob(f"*{_PYTHON_SUFFIX}"):
+        if not py_file.is_file():
+            continue
+        rel = _rel_posix(py_file.parent, root_resolved)
+        if rel is None or rel == ".":
+            continue
+        if not (
+            rel == _SOURCE_PACKAGE_PREFIX
+            or rel.startswith(_SOURCE_PACKAGE_PREFIX + "/")
+        ):
+            continue
+        if _has_excluded_segment(rel) or _is_harness_template_leaf(rel):
+            continue
+        if (py_file.parent / README_NAME).is_file():
+            continue
+        folders.add(rel)
+
+    return sorted(folders)
+
+
+def _last_commit_times(root: Path) -> dict[str, int] | None:
+    """Return a map of tracked-file POSIX path → last-commit unix timestamp.
+
+    One ``git log`` pass, newest commit first: the first time a path is seen
+    is its last-touching commit. Returns None when git history is unavailable
+    (no repository, shallow clone with no log, git absent, or timeout) so the
+    caller degrades to a presence-only sweep.
+    """
+    try:
+        completed = subprocess.run(
+            [
+                "git",
+                "-C",
+                str(root),
+                "log",
+                "--format=%x1e%ct",
+                "--name-only",
+                "--no-renames",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=GIT_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if completed.returncode != 0 or not completed.stdout:
+        return None
+
+    times: dict[str, int] = {}
+    current_ct: int | None = None
+    for raw_line in completed.stdout.splitlines():
+        if raw_line.startswith("\x1e"):
+            stamp = raw_line[1:].strip()
+            current_ct = int(stamp) if stamp.isdigit() else None
+            continue
+        path = raw_line.strip()
+        if not path or current_ct is None:
+            continue
+        # Newest-first: keep only the first (most recent) commit per path.
+        if path not in times:
+            times[path] = current_ct
+    return times
+
+
+def _owning_folder(file_posix: str, folder_set: frozenset[str]) -> str:
+    """Map a tracked file to its nearest meaningful-folder ancestor.
+
+    A top-level file maps to ``.``. A file under a non-meaningful subdir walks
+    up to the nearest meaningful ancestor; a file under a child meaningful
+    folder is owned by that child, never the parent — ownership is disjoint.
+    """
+    parent = file_posix.rpartition("/")[0]
+    while parent:
+        if parent in folder_set:
+            return parent
+        parent = parent.rpartition("/")[0]
+    return "."
+
+
+def check(root: Path) -> GrepResult:
+    """Enumerate meaningful folders; flag only present, stale companions.
+
+    Pre-conditions: ``root`` is the repository root (or an arbitrary subtree).
+    Post-conditions: under the root-only convention, a meaningful folder
+    without a per-folder ``AGENTS.md`` is never a finding — absence passes.
+    ``result.passed`` is True iff (when git history is available) no *present*,
+    committed per-folder companion is stale relative to its folder's
+    directly-contained artifacts; it is always True when git history is
+    unavailable.
+    """
+    folders = meaningful_folders(root)
+    folder_set = frozenset(folders)
+    findings: list[Finding] = []
+
+    # Freshness — git-commit truth; skipped when history is unavailable.
+    commit_times = _last_commit_times(root)
+    freshness_checked = commit_times is not None
+    if commit_times is not None:
+        content_ct: dict[str, int] = {}
+        companion_ct: dict[str, int] = {}
+        for path, ct in commit_times.items():
+            if _has_excluded_segment(path):
+                continue
+            owner = _owning_folder(path, folder_set)
+            if path.rpartition("/")[2] == COMPANION_NAME:
+                companion_folder = path.rpartition("/")[0] or "."
+                if companion_folder in folder_set:
+                    companion_ct[companion_folder] = ct
+                continue
+            content_ct[owner] = max(content_ct.get(owner, 0), ct)
+        for folder in folders:
+            # Only committed companions can be stale; an uncommitted one is fresh.
+            if folder not in companion_ct:
+                continue
+            newest_content = content_ct.get(folder, 0)
+            if newest_content > companion_ct[folder]:
+                surface = (
+                    COMPANION_NAME if folder == "." else f"{folder}/{COMPANION_NAME}"
+                )
+                findings.append(
+                    Finding(
+                        surface=surface,
+                        kind="stale-companion",
+                        detail=(
+                            f"'{folder}' content changed after its {COMPANION_NAME} was "
+                            "last updated; refresh the companion in the same change-set"
+                        ),
+                    )
+                )
+
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        folders_inspected=len(folders),
+        freshness_checked=freshness_checked,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    print(result.to_json())
+    # Advisory posture: always exit 0 so the sweep never silent-blocks by
+    # default. The verdict travels in the JSON — the orchestrator reads the
+    # ``advisory: true`` flag plus the inner ``passed`` field (via
+    # ``gate._advisory_verdict``) and surfaces a stale-companion finding as
+    # ``advisory_findings_present`` without failing the ``gate --all`` run.
+    # CI opts into strict enforcement separately.
+    return EXIT_PASS
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/conformity/agnosticism_grep.py

@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag harness bias and re-introduced enforcement presets in shipped surfaces.
+
+Why this enforcement exists. The agnostic-posture rule
+(``rules/agnostic-posture.md``) requires every shipped surface to be
+harness-neutral and free of imposed enforcement: a clean install privileges
+no harness and pre-sets no model, effort, or workflow. This sweep is the
+mechanical guard for that posture's two failure classes — it is the
+agnosticism counterpart of ``plain_language_grep`` (the two sweeps are paired
+by the phase that introduces them).
+
+Scope. Corpus-level standalone validator. Walks the working tree under the
+supplied root and inspects ONLY the four shipped-surface directories:
+
+- ``src/apothem/rules/`` — behavioral instruction files.
+- ``src/apothem/commands/`` — slash-command definitions.
+- ``src/apothem/output-styles/`` — output-style definitions.
+- ``src/apothem/statuslines/`` — statusline definitions.
+
+Every other path is out of scope: tests, plans, harness adapter packages
+(whose per-harness catalog content legitimately names every harness), and
+all source code outside the four prose surfaces.
+
+Detection — two closed classes.
+
+1. **Harness bias.** The brand phrase ``Claude Code`` and the branded model
+   names ``Claude Opus`` / ``Claude Sonnet`` / ``Claude Haiku`` are
+   privileging forms: they tailor a shipped surface to one harness. The
+   canonical slug ``claude_code`` is the neutral catalog identifier — a line
+   that carries the slug is a per-harness catalog row (one entry among the
+   registered harnesses) and is exempt. Matches inside fenced code
+   blocks are excluded (a fenced example is not shipped prose).
+
+2. **Enforcement preset.** A shipped command, skill, or agent that
+   re-introduces an ``effort:`` or ``model:`` frontmatter default imposes a
+   preference the end user is meant to supply in conversation. The sweep
+   flags any non-empty ``effort:`` / ``model:`` key inside the YAML
+   frontmatter block of a command, skill, or agent definition.
+
+Exit semantics. Exits 0 when zero findings across every in-scope file;
+exits 2 on any finding. The exit-2 convention matches the conformity-gate
+orchestrator's EXIT_FAIL constant. The gate renders this sweep as an
+advisory by default; ``--strict`` (or ``APOTHEM_CONFORMITY_STRICT``)
+restores blocking, per the agnostic-posture advisory-gate discipline.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "agnosticism-grep"
+RULE_ANCHOR: Final[str] = (
+    "rules/agnostic-posture.md §3 (harness neutrality) + §1 (default-off)"
+)
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# The four shipped-surface directories, relative to the repository root.
+# A candidate Markdown file is in scope iff its POSIX-normalized relative
+# path begins with one of these prefixes.
+_SCOPE_PREFIXES: Final[tuple[str, ...]] = (
+    "src/apothem/rules/",
+    "src/apothem/commands/",
+    "src/apothem/output-styles/",
+    "src/apothem/statuslines/",
+)
+# Enforcement-preset scope. The shipped surfaces that carry an end-user-facing
+# YAML frontmatter where a model/effort preset would impose a preference: the
+# slash-commands, the skill definitions, and the agent definitions. The bias
+# scan keeps its own (``_SCOPE_PREFIXES``) reach; the preset scan reaches all
+# three so a re-introduced ``effort:`` / ``model:`` key is caught wherever a
+# definition declares one.
+_PRESET_PREFIXES: Final[tuple[str, ...]] = (
+    "src/apothem/commands/",
+    "src/apothem/skills/",
+    "src/apothem/agents/",
+)
+
+# Per-folder agent-companion files are agnostic shipped surfaces too: every
+# AGENTS.md must privilege no single harness. They are swept for harness bias
+# wherever they live in the tree. The rendered harness-output template fixture
+# under a `templates/` leaf is NOT a companion — it is materialized output.
+_COMPANION_BASENAME: Final[str] = "AGENTS.md"
+_TEMPLATE_LEAF_FRAGMENT: Final[str] = "/templates/"
+
+# Harness-bias forms. ``Claude Code`` (the brand phrase) and the branded
+# model names privilege one harness; the slug ``claude_code`` is the
+# neutral catalog identifier and is matched separately as the exemption
+# signal. Whitespace between the two words is flexible so a line-wrapped
+# brand phrase is still caught.
+_BIAS_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?i)\bClaude\s+(?:Code|Opus|Sonnet|Haiku)\b"
+)
+
+# A line carrying the canonical slug is a per-harness catalog row (one
+# entry among the registered harnesses) and is exempt from the
+# bias scan — the slug is the neutral identifier the agnostic posture
+# permits.
+_CATALOG_SLUG: Final[str] = "claude_code"
+
+# Enforcement-preset frontmatter keys. A shipped command that pre-sets one
+# of these imposes a preference the end user is meant to supply.
+_PRESET_KEY_RE: Final[re.Pattern[str]] = re.compile(r"^(effort|model):\s*\S")
+
+# Fenced code block delimiter — a line beginning with ``` at column 0.
+_CODE_FENCE_RE: Final[re.Pattern[str]] = re.compile(r"^```")
+
+# YAML frontmatter delimiter — a line that is exactly ``---``.
+_FRONTMATTER_DELIM: Final[str] = "---"
+
+_MARKDOWN_SUFFIX: Final[str] = ".md"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One agnosticism violation discovered in a shipped surface."""
+
+    path: str
+    line: int
+    match: str
+    context: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated walk result for a single corpus sweep."""
+
+    grep: str
+    root: str
+    scanned_count: int
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "scanned_count": self.scanned_count,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _relative_posix(path: Path, root: Path) -> str | None:
+    """Return ``path`` relative to ``root`` in POSIX form, or None."""
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return None
+
+
+def _in_scope(rel_posix: str) -> bool:
+    """Return True iff a relative path is a shipped-surface Markdown file.
+
+    Two surface classes are in scope: the four prose-surface directories
+    (rules / commands / output-styles / statuslines) and every per-folder
+    agent-companion file (``AGENTS.md``) wherever it lives — the companions
+    are agnostic shipped surfaces per the per-folder-AGENTS.md convention. A
+    rendered harness-output template fixture under a ``templates/`` leaf is
+    materialized output, not a companion, and is excluded.
+    """
+    if "/" in rel_posix and rel_posix.rsplit("/", 1)[-1] == _COMPANION_BASENAME:
+        return _TEMPLATE_LEAF_FRAGMENT not in rel_posix
+    if not rel_posix.endswith(_MARKDOWN_SUFFIX):
+        return False
+    return rel_posix.startswith(_SCOPE_PREFIXES)
+
+
+def _scan_bias(rel_posix: str, content: str) -> list[Finding]:
+    """Flag privileging harness-brand phrases outside fenced code blocks.
+
+    A line carrying the canonical slug ``claude_code`` is a per-harness
+    catalog row and is exempt.
+    """
+    findings: list[Finding] = []
+    inside_fence = False
+    for line_index, line in enumerate(content.splitlines(), start=1):
+        if _CODE_FENCE_RE.match(line):
+            inside_fence = not inside_fence
+            continue
+        if inside_fence:
+            continue
+        if _CATALOG_SLUG in line.lower():
+            continue
+        for match in _BIAS_RE.finditer(line):
+            findings.append(
+                Finding(
+                    path=rel_posix,
+                    line=line_index,
+                    match=match.group(),
+                    context=line.strip(),
+                    detail=(
+                        "harness-bias: privileging brand reference in a shipped "
+                        "surface — name the harness by its slug (claude_code) as "
+                        "one catalog entry among the registered harnesses, or genericize to "
+                        "'the harness'"
+                    ),
+                )
+            )
+    return findings
+
+
+def _scan_enforcement_preset(rel_posix: str, content: str) -> list[Finding]:
+    """Flag a re-introduced ``effort:`` / ``model:`` frontmatter preset.
+
+    Scans only the leading YAML frontmatter block (delimited by a pair of
+    ``---`` lines) of a command / skill / agent definition. Pre-setting
+    effort or model imposes a preference the end user is meant to supply in
+    conversation.
+    """
+    if not rel_posix.startswith(_PRESET_PREFIXES):
+        return []
+    lines = content.splitlines()
+    if not lines or lines[0].strip() != _FRONTMATTER_DELIM:
+        return []
+    findings: list[Finding] = []
+    for line_index, line in enumerate(lines[1:], start=2):
+        if line.strip() == _FRONTMATTER_DELIM:
+            break
+        if _PRESET_KEY_RE.match(line):
+            findings.append(
+                Finding(
+                    path=rel_posix,
+                    line=line_index,
+                    match=line.strip(),
+                    context=line.strip(),
+                    detail=(
+                        "enforcement-preset: shipped surface pre-sets a "
+                        "model/effort preference — strip the frontmatter key so "
+                        "the preference resolves only from an in-conversation "
+                        "end-user choice"
+                    ),
+                )
+            )
+    return findings
+
+
+def _scan_file(path: Path, rel_posix: str) -> list[Finding]:
+    """Scan one Markdown file for the applicable finding classes.
+
+    The bias scan applies only to the four prose surfaces and the AGENTS.md
+    companions (``_in_scope``); the enforcement-preset scan additionally
+    reaches the skill and agent definitions (``_PRESET_PREFIXES``), so the
+    two classes are gated independently.
+    """
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return []
+    findings: list[Finding] = []
+    if _in_scope(rel_posix):
+        findings.extend(_scan_bias(rel_posix, content))
+    findings.extend(_scan_enforcement_preset(rel_posix, content))
+    return findings
+
+
+def check(root: Path) -> GrepResult:
+    """Walk the shipped surfaces under ``root``; flag agnosticism violations.
+
+    Pre-conditions: ``root`` is the repository root (or an arbitrary subtree
+    containing ``src/apothem/{rules,commands,output-styles,statuslines}/``).
+    Post-conditions: ``result.passed`` is True iff every in-scope shipped
+    surface is free of privileging harness-brand references (outside fenced
+    code) and re-introduced enforcement presets.
+    """
+    findings: list[Finding] = []
+    scanned = 0
+    for path in sorted(root.rglob(f"*{_MARKDOWN_SUFFIX}")):
+        if not path.is_file():
+            continue
+        rel_posix = _relative_posix(path, root)
+        if rel_posix is None:
+            continue
+        if not (_in_scope(rel_posix) or rel_posix.startswith(_PRESET_PREFIXES)):
+            continue
+        scanned += 1
+        findings.extend(_scan_file(path, rel_posix))
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        scanned_count=scanned,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> Path:
+    if len(argv) >= 2:
+        return Path(argv[1])
+    return Path.cwd()
+
+
+def _main(argv: list[str]) -> int:
+    root = _read_input(argv)
+    result = check(root)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))