@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/naming_grep.py

@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: MIT
+
+"""Validate filesystem paths against the canonical naming convention.
+
+Why this enforcement exists. Spec section 4.1 ratifies kebab-case for
+files and folders, with a closed set of canonical-uppercase exceptions
+for ecosystem-wide singletons (CLAUDE.md, README.md, LICENSE, etc.) and
+plan-suite singletons (MASTER-PLAN.md, PROGRESS.md, PHASE.md, SKILL.md,
+VERSION). Numeric prefixes are admissible only inside ordered sequences
+(phase folders `NN-topic/`, sub-phase folders `NNL-subtopic/`, migration
+scripts where the host has ratified ordinal prefixes). The pre-emission
+gate enforces the convention so namespace pollution cannot drift in
+silently.
+
+Detection strategy. Each input path is split into its file and parent
+components; each component is matched against (a) the canonical-name
+exception set, (b) the ordered-sequence prefix patterns, and (c) the
+plain kebab-case shape. Components that match none of the three are
+findings. Hidden directories (a leading dot) are exempt because dotfile
+conventions are host-discovered, not ratified at user scope.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+# Canonical-uppercase exception set per spec section 4.1. These names
+# are recognized verbatim regardless of casing rules. The set is closed;
+# new exceptions land via rule revision, never ad-hoc.
+CANONICAL_NAMES: Final[frozenset[str]] = frozenset(
+    {
+        "CLAUDE.md",
+        "README.md",
+        "LICENSE",
+        "LICENSE.md",
+        "LICENSE.txt",
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "SUPPORT.md",
+        "CODE_OF_CONDUCT.md",
+        "CONTRIBUTING.md",
+        "NOTICE",
+        "NOTICE.md",
+        "MASTER-PLAN.md",
+        "PROGRESS.md",
+        "PHASE.md",
+        "SKILL.md",
+        "REPORT.md",
+        "PLAN-NOTES.md",
+        "PREAMBLE.md",
+        "COMPLETION.md",
+        "VERSION",
+        "MEMORY.md",
+        "site/content/docs/architecture/agents.mdx",
+        "Makefile",
+    }
+)
+
+# kebab-case for the principal stem; an optional dotted suffix carries
+# the host-natural extension list. The stem may carry digits but not
+# uppercase letters, underscores, or spaces.
+KEBAB_STEM_RE: Final[re.Pattern[str]] = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+# Phase-folder prefix `NN-topic` and sub-phase-folder prefix `NNL-topic`
+# (digits + optional single uppercase letter) honor the ordering
+# discipline at canonical-layout section 2.1. The suffix is kebab-case.
+PHASE_PREFIX_RE: Final[re.Pattern[str]] = re.compile(
+    r"^[0-9]{2}[A-Z]?-[a-z0-9]+(?:-[a-z0-9]+)*$"
+)
+
+# Migration-script prefix `NNNN_name` honors the host-ratified ordinal
+# scheme common to migration tooling.
+MIGRATION_PREFIX_RE: Final[re.Pattern[str]] = re.compile(
+    r"^[0-9]{2,5}_[a-z0-9]+(?:_[a-z0-9]+)*$"
+)
+
+# ADR filenames follow `NNNN-kebab-topic.md` per the ADR convention.
+ADR_NAME_RE: Final[re.Pattern[str]] = re.compile(
+    r"^[0-9]{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md$"
+)
+
+GREP_NAME: Final[str] = "naming-grep"
+RULE_ANCHOR: Final[str] = "CLAUDE.md Coding Conventions (kebab-case naming)"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    component: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    grep: str
+    path: str | None
+    passed: bool
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "path": self.path,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _stem_and_extensions(name: str) -> tuple[str, str]:
+    """Split a filename at the first dot; the suffix is the extension run."""
+    if "." not in name:
+        return name, ""
+    head, tail = name.split(".", 1)
+    return head, tail
+
+
+def _is_canonical_name(name: str) -> bool:
+    return name in CANONICAL_NAMES
+
+
+def _is_phase_prefix(name: str) -> bool:
+    return bool(PHASE_PREFIX_RE.match(name))
+
+
+def _is_migration_prefix(stem: str) -> bool:
+    return bool(MIGRATION_PREFIX_RE.match(stem))
+
+
+def _is_adr_name(name: str) -> bool:
+    return bool(ADR_NAME_RE.match(name))
+
+
+def _component_passes(name: str) -> tuple[bool, str]:
+    """Return (passes, reason). reason explains the failure shape."""
+    if not name:
+        return True, ""
+    if name.startswith("."):
+        # Dotfiles and dot-dirs are host-discovered; do not enforce.
+        return True, ""
+    if _is_canonical_name(name):
+        return True, ""
+    # Phase-prefix shape (NN-topic / NNL-topic) is unambiguous; admit
+    # regardless of the directory-vs-file inference because a user-
+    # supplied path string carries no on-disk-stat hint.
+    if _is_phase_prefix(name):
+        return True, ""
+    if _is_adr_name(name):
+        return True, ""
+    stem, _ = _stem_and_extensions(name)
+    if _is_migration_prefix(stem):
+        return True, ""
+    if KEBAB_STEM_RE.match(stem):
+        return True, ""
+    return False, (
+        f"component {name!r} is neither kebab-case nor a canonical "
+        f"exception (spec section 4.1)"
+    )
+
+
+def check(target: str, *, is_dir: bool | None = None) -> GrepResult:
+    """Validate every path component against the naming convention.
+
+    ``is_dir`` is retained for call-site signature compatibility; the
+    convention check is component-shape-only and does not branch on
+    whether the terminal component is a directory.
+    """
+    del is_dir  # accepted for signature compatibility; not consulted
+    findings: list[Finding] = []
+    parts = Path(target).parts
+    for component in parts:
+        # Drop drive anchors like 'C:', 'C:\\', or '/' on POSIX. The
+        # Windows form `Path('D:\\foo').parts[0]` returns the literal
+        # 'D:\\' (drive letter + colon + separator), not bare 'D:'.
+        if (
+            component.endswith(":")
+            or component in ("/", "\\")
+            or (len(component) >= 2 and component[1] == ":")
+        ):
+            continue
+        passes, reason = _component_passes(component)
+        if not passes:
+            findings.append(Finding(component=component, detail=reason))
+    return GrepResult(
+        grep=GREP_NAME,
+        path=target,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def _read_input(argv: list[str]) -> str:
+    if len(argv) >= 2 and argv[1] != STDIN_FLAG:
+        return argv[1]
+    return sys.stdin.read().strip()
+
+
+def _main(argv: list[str]) -> int:
+    target = _read_input(argv)
+    # In the conformity gate's --all mode this validator is handed the
+    # absolute repository root. naming-grep validates the project's own
+    # artifact names, not the host filesystem ancestry above the repo
+    # root (`Users`, a home-directory name, etc.) — so an absolute
+    # directory input is reduced to its own basename. Relative inputs
+    # (the per-path invocation form) are validated component-by-component
+    # unchanged.
+    candidate = Path(target)
+    if candidate.is_absolute() and candidate.is_dir():
+        target = candidate.name
+    result = check(target)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/conformity/no_global_plans_grep.py

@@ -0,0 +1,339 @@
+# SPDX-License-Identifier: MIT
+
+"""Walk the git index for tracked plans paths; fail when found.
+
+Why this validator exists. The Plans Discipline at spec section 3
+forbids planning artifacts at any global location and at the
+ecosystem root. Plans live at the sole canonical
+``<project-root>/.apothem/plans/`` tree and are gitignored — they
+never enter a git history. A plans path (under ``.apothem/plans/`` or
+a legacy ``.plans/``) appearing in ``git ls-files`` is direct evidence
+that the discipline has lapsed: either the gitignore is missing the
+pattern, the ``.gitignore`` has been bypassed via ``git add --force``,
+or a nested project's plans directory has been tracked by mistake.
+
+Why git-index, not filesystem. The recursion case at spec section 3
+(the apothem source repository itself contains a plans tree while it is
+being authored — and, for the Claude Code harness specifically, that
+working tree lives under ``~/.claude/``) is resolved precisely because
+the on-disk plans tree is gitignored. Walking the filesystem would flag
+the in-flight suite as a violation; walking the git index returns clean
+by construction. The validator's surface IS the git index — the
+source-of-truth for "what ships with this repository."
+
+Detection strategy. The validator runs ``git ls-files`` from the
+root, filters the output for entries under any plans directory
+(``.apothem/plans/`` or a legacy ``.plans/``, top-level or nested), and
+excludes the documented anti-pattern references inside
+``site/content/docs/reference/plans-discipline.mdx`` (the file is allow-
+listed wholesale because the validator inspects path entries, not
+file contents — and the file's path itself does not match the plans
+pattern).
+
+Filesystem stray-suite sweep (additive). The git-index check above is
+blind to a plans directory that exists on disk but is untracked — a
+stray suite materialized at a non-canonical location (a nested sub-tree,
+a sibling tree, or a legacy ``<root>/.plans`` that has not yet been
+upgraded) escapes ``git ls-files`` entirely because it is gitignored or
+simply not yet added. The suite-locality invariant fixes exactly one
+canonical plans tree per project: ``<root>/.apothem/plans/``. Any other
+on-disk plans directory under the root — including a legacy
+``<root>/.plans`` an operator upgrades via ``apothem migrate-workspace``
+— is a stray suite and a Plans-Locality violation. The sweep walks the
+filesystem (skipping the vendored / generated / VCS trees that carry
+upstream conventions or machine state) and flags every plans directory
+that is not the canonical ``<root>/.apothem/plans``. The two checks are
+complementary: the git-index check catches a *tracked* plans path; the
+filesystem sweep catches an *untracked stray* plans directory the index
+check is blind to.
+
+Exit semantics. Exits 0 when no findings; exits 2 on any finding.
+The exit-2 convention matches the conformity-gate orchestrator's
+EXIT_FAIL constant.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "no-global-plans-grep"
+RULE_ANCHOR: Final[str] = "CLAUDE.md Plans Discipline (no global plans)"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# Pattern for any path containing a plans-suite directory segment. The sole
+# canonical project-local plans location is `.apothem/plans/` (the shared
+# Apothem working directory's plans child); the legacy `.plans/` layout is no
+# longer canonical — operators upgrade an existing `.plans` tree via
+# `apothem migrate-workspace`. Both layouts are gitignored, so a tracked path
+# under EITHER is the same discipline lapse and is flagged for leak detection.
+#
+# Matches `.plans/foo`, `subdir/.plans/bar`, `.apothem/plans/foo`,
+# `subdir/.apothem/plans/bar`, but does NOT match `plans-discipline.md` (no
+# trailing slash), `my.plans/x.md` (no leading boundary), or a non-`plans`
+# child of `.apothem/` such as `.apothem/memory/` (operator data, not a plan).
+_PLANS_PATH_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?:^|/)(?:\.plans|\.apothem/plans)/"
+)
+
+# Directory names the filesystem stray-suite sweep does NOT descend into.
+# Vendored / generated / VCS / cache trees carry upstream or machine state, not
+# apothem-authored content; a `.plans/` directory inside any of them is not a
+# stray apothem plan suite. Pruning them also keeps the walk fast.
+_SWEEP_SKIP_DIRS: Final[frozenset[str]] = frozenset(
+    {
+        ".git",
+        "_vendor",
+        "node_modules",
+        "dist",
+        "site/dist",
+        ".mypy_cache",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".hypothesis",
+        "__pycache__",
+        ".venv",
+        "venv",
+    }
+)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One tracked-in-git path under a .plans/ directory."""
+
+    path: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated walk result for a single git-index + filesystem sweep."""
+
+    grep: str
+    root: str
+    tracked_count: int
+    passed: bool
+    stray_plans_count: int = 0
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "tracked_count": self.tracked_count,
+            "stray_plans_count": self.stray_plans_count,
+            "passed": self.passed,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def _git_ls_files(root: Path) -> list[str]:
+    """Return the git-tracked file list under root.
+
+    Raises ``RuntimeError`` when ``git`` is unavailable or root is not
+    a git repository — both are operator errors the caller surfaces.
+    """
+    try:
+        completed = subprocess.run(  # noqa: S603 — trusted invocation: literal argv against git
+            ["git", "-C", str(root), "ls-files"],  # noqa: S607 — PATH-resolved git is acceptable for a developer-tool validator; full-path resolution would require host-discovery and breaks portability across operator setups.
+            check=True,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
+    except FileNotFoundError as exc:
+        raise RuntimeError("git executable not found on PATH") from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        raise RuntimeError(
+            f"git ls-files failed under {root!s}: {stderr or 'no stderr'}"
+        ) from exc
+    return [line for line in completed.stdout.splitlines() if line]
+
+
+def _sweep_stray_plans_dirs(
+    root: Path, tracked_plans_dirs: frozenset[str]
+) -> list[Finding]:
+    """Walk the filesystem under root; flag *untracked* stray plans dirs.
+
+    A stray suite is any on-disk plans directory that is not the sole canonical
+    project-local location ``<root>/.apothem/plans`` (the shared Apothem working
+    directory's plans child). Any ``.plans`` directory (including a legacy
+    ``<root>/.plans`` — operators upgrade it via ``apothem migrate-workspace``),
+    or any ``.apothem/plans`` directory under a non-root ``.apothem`` (e.g. a
+    nested ``sub/.apothem/plans`` analogous to a global ``~/.apothem/plans``),
+    is a stray and a Plans-Locality violation.
+
+    The walk prunes the vendored / generated / VCS / cache trees in
+    ``_SWEEP_SKIP_DIRS`` so a plans directory inside one of those (upstream or
+    machine state, never an apothem plan suite) is not flagged. It descends into
+    ``.apothem`` directories (they hold operator memory/learning/contexts data
+    alongside plans) but never descends into a plans tree itself or into the
+    ``.apothem`` data children — only the ``plans`` child of an ``.apothem``
+    directory is plans-relevant. The check is **additive and non-overlapping**
+    with the git-index check: a plans directory whose contents are already
+    git-tracked is reported there, so the sweep skips it via
+    ``tracked_plans_dirs`` to avoid double-reporting. The sweep's unique value is
+    the *untracked* stray. Returns an empty list when the filesystem is
+    unreadable (the git-index check still carries the verdict).
+    """
+    findings: list[Finding] = []
+    try:
+        resolved_root = root.resolve()
+    except (OSError, RuntimeError):
+        return findings
+    canonical_new = (resolved_root / ".apothem" / "plans").resolve()
+    canonical = {canonical_new}
+
+    def _record_stray(entry: Path, rel: str) -> None:
+        """Append a stray finding for a plans directory unless it is canonical
+        or already covered by the git-index check."""
+        already_tracked = rel in tracked_plans_dirs
+        if entry.resolve() in canonical or already_tracked:
+            return
+        findings.append(
+            Finding(
+                path=f"{rel}/",
+                detail=(
+                    "an untracked stray plans directory exists on disk outside "
+                    "the sole canonical project-local <root>/.apothem/plans tree; "
+                    "there is exactly one plans tree per project per the "
+                    "suite-locality invariant — relocate the stray suite, or run "
+                    "`apothem migrate-workspace` to upgrade a legacy <root>/.plans "
+                    "tree"
+                ),
+            )
+        )
+
+    stack: list[Path] = [resolved_root]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = list(current.iterdir())
+        except (OSError, PermissionError):
+            continue
+        for entry in entries:
+            try:
+                is_dir = entry.is_dir()
+            except OSError:
+                continue
+            if not is_dir:
+                continue
+            name = entry.name
+            if name in _SWEEP_SKIP_DIRS:
+                continue
+            rel = entry.relative_to(resolved_root).as_posix()
+            if name == ".plans":
+                _record_stray(entry, rel)
+                # Do not descend into a .plans/ tree (it is suite content, not a
+                # place a nested .plans/ should appear).
+                continue
+            if name == ".apothem":
+                # An ``.apothem`` directory holds operator data
+                # (memory/learning/contexts) plus the plans child. Inspect only
+                # the ``plans`` child for stray-suite detection; descend no
+                # further into the data children.
+                plans_child = entry / "plans"
+                try:
+                    if plans_child.is_dir():
+                        _record_stray(plans_child, f"{rel}/plans")
+                except OSError:
+                    pass
+                continue
+            stack.append(entry)
+    return findings
+
+
+def _tracked_plans_dirs(tracked: list[str]) -> frozenset[str]:
+    """Return the set of plans-segment directory paths the git index covers.
+
+    For each tracked path matching ``(.../)?(.plans|.apothem/plans)/...``,
+    extract the directory portion up to and including the plans segment (e.g.
+    ``subdir/.plans/x.md`` -> ``subdir/.plans``; ``.plans/a.md`` -> ``.plans``;
+    ``sub/.apothem/plans/x.md`` -> ``sub/.apothem/plans``;
+    ``.apothem/plans/a.md`` -> ``.apothem/plans``). The sweep uses this set to
+    skip already-tracked plans directories so they are not double-counted across
+    the git-index check and the filesystem sweep.
+    """
+    dirs: set[str] = set()
+    for path in tracked:
+        match = _PLANS_PATH_RE.search(path)
+        if not match:
+            continue
+        # The match spans the leading-boundary slash (when present) plus the
+        # plans segment and its trailing slash, e.g. "/.apothem/plans/" or
+        # "/.plans/". Trim the trailing slash to leave the directory path up to
+        # and including the plans segment.
+        end = match.end() - 1  # drop the trailing '/'
+        dir_path = path[:end]
+        # Strip a leading separator the boundary group may have consumed when the
+        # segment was not at the path start.
+        dirs.add(dir_path.lstrip("/") if match.start() != 0 else dir_path)
+    return frozenset(dirs)
+
+
+def check(root: Path) -> GrepResult:
+    """Walk the git index + filesystem under root; flag stray .plans/ paths.
+
+    Two complementary checks: (1) the git-index check flags any *tracked*
+    ``.plans/`` or ``.apothem/plans/`` path (a planning artifact that has
+    entered git history); (2) the filesystem stray-suite sweep flags any
+    *untracked* on-disk plans directory that is not the sole canonical
+    ``<root>/.apothem/plans`` (a stray suite the index check is blind to).
+    Either check's finding fails the validator.
+    """
+    tracked = _git_ls_files(root)
+    findings: list[Finding] = []
+    for path in tracked:
+        if _PLANS_PATH_RE.search(path):
+            findings.append(
+                Finding(
+                    path=path,
+                    detail=(
+                        "plans path is tracked in git; planning artifacts MUST "
+                        "live in the gitignored project-local "
+                        "<project-root>/.apothem/plans/ tree per spec section 3"
+                    ),
+                )
+            )
+    stray = _sweep_stray_plans_dirs(root, _tracked_plans_dirs(tracked))
+    findings.extend(stray)
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        tracked_count=len(tracked),
+        stray_plans_count=len(stray),
+        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)
+    try:
+        result = check(root)
+    except RuntimeError as exc:
+        sys.stderr.write(f"{GREP_NAME}: {exc}\n")
+        return EXIT_FAIL
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))

package/src/apothem/conformity/no_toplevel_docs_grep.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: MIT
+
+"""Fail when a top-level ``docs/`` directory exists at the repository root.
+
+Why this validator exists. The documentation source of truth is the
+Next.js + Fumadocs site under ``site/``; the rendered reference pages live
+at ``site/content/docs/``. A bare ``docs/`` directory at the
+repository root is a competing documentation source — a second place a
+contributor (or a generator) might write or read docs from, splitting
+the single-source-of-truth invariant. Once a root ``docs/`` exists,
+links, build steps, and contributor habits accrete around it and the
+two trees drift. The invariant is therefore structural and hard: there
+is exactly one documentation tree (``site/``), and the repository root
+never carries a ``docs/`` directory.
+
+Scope of the violation. ONLY a directory named ``docs`` directly under
+the repository root is forbidden. Nested ``docs/`` directories under
+other trees (for example a vendored package's own ``docs/``), the
+``site/`` tree, and ``src/`` are all fine — the validator inspects the
+single root-level entry, not the whole tree.
+
+Non-advisory. Unlike the advisory matchers, this is a hard structural
+invariant: ``check()`` returns ``passed=False`` and the CLI exits 2 the
+moment a root ``docs/`` directory is present, so a ``--strict`` CI step
+blocks the change.
+
+Exit semantics. Exits 0 when no findings; exits 2 on any finding,
+matching the conformity-gate orchestrator's EXIT_FAIL constant.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Final
+
+GREP_NAME: Final[str] = "no-toplevel-docs-grep"
+RULE_ANCHOR: Final[str] = "single-source-of-truth (docs live in site/, not root docs/)"
+
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# The forbidden directory name at the repository root.
+_FORBIDDEN_DIR: Final[str] = "docs"
+# The canonical documentation tree contributors must use instead.
+_CANONICAL_DOCS_TREE: Final[str] = "site/content/docs/"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """The single finding: a root-level ``docs/`` directory exists."""
+
+    path: str
+    detail: str
+    rule: str = RULE_ANCHOR
+
+
+@dataclass(frozen=True)
+class GrepResult:
+    """Aggregated result for a single root-level ``docs/`` probe."""
+
+    grep: str
+    root: str
+    passed: bool
+    advisory: bool = False
+    findings: list[Finding] = field(default_factory=list)
+
+    def to_json(self) -> str:
+        payload = {
+            "grep": self.grep,
+            "root": self.root,
+            "passed": self.passed,
+            "advisory": self.advisory,
+            "findings": [asdict(f) for f in self.findings],
+        }
+        return json.dumps(payload, indent=2)
+
+
+def check(root: Path) -> GrepResult:
+    """Flag a ``docs/`` directory living directly under *root*."""
+    candidate = root / _FORBIDDEN_DIR
+    findings: list[Finding] = []
+    if candidate.is_dir():
+        findings.append(
+            Finding(
+                path=f"{_FORBIDDEN_DIR}/",
+                detail=(
+                    "a top-level docs/ directory is forbidden: the "
+                    "documentation source of truth is site/ "
+                    f"(rendered pages at {_CANONICAL_DOCS_TREE}); "
+                    "remove the root docs/ tree and author documentation "
+                    "under site/ instead"
+                ),
+            )
+        )
+    return GrepResult(
+        grep=GREP_NAME,
+        root=str(root),
+        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))