@ahmed-g-gad/apothem 0.1.1

package/src/apothem/conformity/static_version_grep.py

@@ -0,0 +1,284 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify version-bearing sites resolve dynamically, not as static literals.
+
+Why this enforcement exists. Companion to ``dynamism_grep.py``. The
+dynamism rule mandates that every version-bearing site in the project
+derive its value from a single source of truth (package metadata via
+``importlib.metadata``, the shields.io dynamic badge endpoints that
+resolve against the npm registry and GitHub Releases, or the site
+build's version-injection mechanism) rather than carry the version
+as a hard-coded literal. Static literals drift the moment a release
+ships: badge URLs lie about the current version, docs pages display
+the version that was true at last edit, and the runtime ``__version__``
+attribute returns a value that disagrees with the installed package.
+This standalone validator walks three classes of site (README badges,
+docs site config, runtime ``__version__``) and reports every static
+resolution so the operator can convert it to a dynamic form.
+
+Scope. Standalone corpus-level validator. Walks the project root from a
+single ``main(root)`` entry point and exits 0 (PASS) or 2 (FAIL) with a
+structured JSON report listing every static-version site. Invoked via
+``python -m apothem.conformity.gate --all .`` or
+``python -m apothem.conformity.gate --check static-version-grep <root>``.
+"""
+
+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] = "static-version-grep"
+RULE_ANCHOR: Final[str] = "rules/dynamism.md §static-version-resolution"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+
+# README sites inspected for badge URLs. Shields.io dynamic badge paths
+# include the project / package coordinate after a `/github/v/release/`,
+# `/github/v/tag/`, `/npm/v/`, `/npm/dm/`, `/pypi/v/`, or `/pypi/dm/` segment;
+# static badges instead embed a literal version number in the URL or use the
+# `/badge/` static generator with a hard-coded value.
+README_CANDIDATES: Final[tuple[str, ...]] = ("README.md", "README.rst", "README")
+
+# Site config candidates. Each is inspected for a `version:` key bearing a
+# string-literal value rather than a templated / dynamic reference.
+SITE_CONFIG_CANDIDATES: Final[tuple[str, ...]] = (
+    "site/next.config.mjs",
+    "site/package.json",
+)
+
+# Runtime version-bearing module. The canonical pattern is
+# ``__version__ = importlib.metadata.version(__package__)`` (or an
+# equivalent ``metadata.version("apothem")`` form). A literal string
+# assignment is the failure mode this validator catches.
+RUNTIME_VERSION_MODULE: Final[str] = "src/apothem/__init__.py"
+
+# A semver-shaped literal version embedded in a badge URL or a config
+# value. Captures forms like `v1.2.3`, `1.2.3`, `1.2.3-alpha.1`,
+# `2.0.0+build.7`. Word boundaries prevent partial matches inside
+# longer identifiers.
+LITERAL_VERSION_RE: Final[re.Pattern[str]] = re.compile(
+    r"\bv?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?\b"
+)
+
+# Shields.io dynamic badge markers — any of these path fragments in a
+# badge URL indicates the badge resolves dynamically against an upstream
+# registry rather than carrying a literal version.
+SHIELDS_DYNAMIC_MARKERS: Final[tuple[str, ...]] = (
+    "img.shields.io/github/v/release/",
+    "img.shields.io/github/v/tag/",
+    "img.shields.io/npm/v/",
+    "img.shields.io/npm/dm/",
+    "img.shields.io/pypi/v/",
+    "img.shields.io/pypi/dm/",
+    "img.shields.io/crates/v/",
+    "img.shields.io/gem/v/",
+)
+
+# Markdown badge / image syntax. Captures the URL inside the
+# `![alt](url)` form so each URL can be classified independently.
+MARKDOWN_IMAGE_RE: Final[re.Pattern[str]] = re.compile(r"!\[[^\]]*\]\(([^)]+)\)")
+
+# Git-ref query parameters (`?branch=`, `?tag=`, `?ref=`) on a badge URL carry a
+# git ref that may itself be a version tag — e.g. a build-status badge pinned to
+# `?branch=v1.2.3`. That ref is not the badge's *displayed* version, so a semver
+# token appearing only inside one of these parameters must not be read as a
+# static-version literal. The parameter values are stripped before the
+# literal-version scan; a version embedded in the URL *path* (the static
+# `/badge/<label>-<version>-<color>` generator) is untouched and still flagged.
+REF_PARAM_RE: Final[re.Pattern[str]] = re.compile(r"[?&](?:branch|tag|ref)=[^&]*")
+
+# A literal ``version:`` key in a YAML/Python config carrying a quoted
+# string value (site-generator config style). Templated references — e.g.
+# ``version: !ENV [VERSION]`` or ``version = metadata.version(...)`` —
+# do not match.
+YAML_LITERAL_VERSION_RE: Final[re.Pattern[str]] = re.compile(
+    r"""^\s*version\s*[:=]\s*["']([^"']+)["']""",
+    re.MULTILINE,
+)
+
+# A literal ``__version__ = "x.y.z"`` assignment. Captures the assigned
+# string when it is a literal; the dynamic form
+# ``__version__ = importlib.metadata.version(...)`` is not matched.
+LITERAL_DUNDER_VERSION_RE: Final[re.Pattern[str]] = re.compile(
+    r"""^\s*__version__\s*=\s*["']([^"']+)["']""",
+    re.MULTILINE,
+)
+
+# Dynamic ``__version__`` resolution markers. Presence of any of these
+# fragments indicates the runtime version derives from package metadata
+# rather than a literal.
+DYNAMIC_VERSION_MARKERS: Final[tuple[str, ...]] = (
+    "importlib.metadata.version",
+    "importlib_metadata.version",
+    "metadata.version(",
+    "version(__package__",
+    'version("apothem"',
+    "version('apothem'",
+)
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One static-version site discovered in the project."""
+
+    site_class: str
+    path: 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 _strip_ref_params(url: str) -> str:
+    """Remove git-ref query-parameter values from a badge URL.
+
+    ``?branch=v1.2.3`` / ``?tag=v1.2.3`` / ``?ref=v1.2.3`` carry a git ref, not
+    a displayed version; their values are dropped so the literal-version scan
+    does not misread a dynamic build-status badge pinned to a release branch.
+    A version embedded in the URL path is untouched.
+    """
+    return REF_PARAM_RE.sub("", url)
+
+
+def _check_readme(root: Path, findings: list[Finding]) -> None:
+    """Flag badge URLs in README that carry literal versions."""
+    for candidate in README_CANDIDATES:
+        readme = root / candidate
+        if not readme.is_file():
+            continue
+        try:
+            text = readme.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        for match in MARKDOWN_IMAGE_RE.finditer(text):
+            url = match.group(1).strip()
+            if "shields.io" not in url and "badge" not in url.lower():
+                continue
+            is_dynamic = any(marker in url for marker in SHIELDS_DYNAMIC_MARKERS)
+            if is_dynamic:
+                continue
+            if LITERAL_VERSION_RE.search(_strip_ref_params(url)):
+                findings.append(
+                    Finding(
+                        site_class="readme-badge",
+                        path=str(readme.relative_to(root)),
+                        detail=(
+                            f"badge URL carries a literal version: {url!r}; "
+                            "convert to a shields.io dynamic endpoint "
+                            "(e.g., img.shields.io/npm/v/%40ahmed-g-gad%2Fapothem "
+                            "or img.shields.io/github/v/release/ahmed-g-gad/apothem)"
+                        ),
+                    )
+                )
+
+
+def _check_site_config(root: Path, findings: list[Finding]) -> None:
+    """Flag site config files declaring a literal ``version:``."""
+    for candidate in SITE_CONFIG_CANDIDATES:
+        config = root / candidate
+        if not config.is_file():
+            continue
+        try:
+            text = config.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        if any(marker in text for marker in DYNAMIC_VERSION_MARKERS):
+            # The config imports a dynamic version-resolution helper; a
+            # nearby literal `version:` key is almost certainly a fallback
+            # default rather than the canonical source, so do not flag.
+            continue
+        for match in YAML_LITERAL_VERSION_RE.finditer(text):
+            literal = match.group(1)
+            if not LITERAL_VERSION_RE.search(literal):
+                continue
+            findings.append(
+                Finding(
+                    site_class="site-config",
+                    path=str(config.relative_to(root)),
+                    detail=(
+                        f"site config declares a literal version: {literal!r}; "
+                        'derive from importlib.metadata.version("apothem") '
+                        "or an equivalent dynamic source"
+                    ),
+                )
+            )
+
+
+def _check_runtime_version(root: Path, findings: list[Finding]) -> None:
+    """Flag a literal ``__version__`` assignment in the runtime module."""
+    module = root / RUNTIME_VERSION_MODULE
+    if not module.is_file():
+        return
+    try:
+        text = module.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return
+    if any(marker in text for marker in DYNAMIC_VERSION_MARKERS):
+        return
+    match = LITERAL_DUNDER_VERSION_RE.search(text)
+    if match is None:
+        return
+    findings.append(
+        Finding(
+            site_class="runtime-version",
+            path=str(module.relative_to(root)),
+            detail=(
+                f"__version__ is a literal string {match.group(1)!r}; "
+                "derive from importlib.metadata.version(__package__) so "
+                "the runtime value tracks the installed package metadata"
+            ),
+        )
+    )
+
+
+def check(root: Path) -> GrepResult:
+    """Walk the three version-bearing site classes; return a structured result.
+
+    Pre-conditions: ``root`` is the project root (the directory holding
+    ``pyproject.toml`` or its closest ancestor).
+    Post-conditions: ``result.passed`` is True iff every inspected site
+    resolves dynamically (README badges hit shields.io dynamic endpoints,
+    docs config derives version from package metadata, runtime
+    ``__version__`` calls ``importlib.metadata.version`` or equivalent).
+    """
+    findings: list[Finding] = []
+    _check_readme(root, findings)
+    _check_site_config(root, findings)
+    _check_runtime_version(root, findings)
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(root),
+        passed=not findings,
+        findings=findings,
+    )
+
+
+def main(root: Path) -> int:
+    result = check(root)
+    print(result.to_json())
+    return EXIT_PASS if result.passed else EXIT_FAIL
+
+
+if __name__ == "__main__":
+    target = Path(sys.argv[1]) if len(sys.argv) >= 2 else Path.cwd()
+    sys.exit(main(target))

package/src/apothem/conformity/token_efficiency_grep.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag filler phrases, throat-clearing openers, and content-free qualifiers.
+
+Why this enforcement exists. The clean-room generation rule §5 (Prose and
+Documentation) and the token-efficiency rewrite rule require every sentence
+to advance the artifact's purpose. Filler ("In this section, we will…"),
+throat-clearing ("Before diving in…"), restatement openers, and
+content-free qualifiers ("very", "quite", "rather", "fairly") consume
+tokens without carrying semantic load. The mechanical matcher surfaces
+each occurrence so the operator can either delete the phrase, replace it
+with substantive content, or — for qualifiers — substitute a measured
+form ("twice as fast" rather than "very fast").
+
+Scope. Hits inside fenced code blocks (between triple-backtick fences),
+inline-code spans (single-backtick delimited), quoted blocks (lines
+starting `>`), and HTML comment regions are excluded. These typically carry
+external material, sample inputs, preserved conversation, or — for inline
+code — a forbidden phrase cited meta-linguistically (a doc that names the
+filler vocabulary it forbids) rather than the artifact's own prescriptive
+prose.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from apothem.conformity._grep_base import GrepResult, run_grep
+
+# Multi-word filler phrases and throat-clearing openers. Matched
+# case-insensitively against the line text. These patterns are
+# multi-word, so word-boundary anchors at the ends suffice.
+FILLER_PHRASES: Final[tuple[str, ...]] = (
+    r"In this section, we will",
+    r"It is important to note",
+    r"As mentioned earlier",
+    r"Before diving in",
+    r"Without further ado",
+    r"Let's begin by",
+    r"Before we discuss",
+    r"To begin with",
+    r"First and foremost",
+    r"kind of",
+)
+
+# Single-word content-free qualifiers that flag unconditionally. Separated
+# from the multi-word phrases so each carries word-boundary anchors and
+# matches only when standing alone (not as a substring of a larger word).
+# "rather" is intentionally NOT here: it needs a context exclusion (see
+# RATHER_QUALIFIER_RE) because the comparative "rather than" carries
+# semantic load and is not a content-free qualifier.
+QUALIFIER_WORDS: Final[tuple[str, ...]] = (
+    "very",
+    "quite",
+    "somewhat",
+    "fairly",
+)
+
+FILLER_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?i)(?:" + "|".join(FILLER_PHRASES) + r")"
+)
+
+QUALIFIER_RE: Final[re.Pattern[str]] = re.compile(
+    r"(?i)\b(?:" + "|".join(QUALIFIER_WORDS) + r")\b"
+)
+
+# "rather" is a content-free qualifier as a bare intensifier ("rather slow",
+# "rather large") but carries semantic load in the comparative construction
+# "rather than" ("X rather than Y" expresses a deliberate contrast — the kind
+# of measured form §5 endorses, not filler). The negative lookahead excludes
+# the comparative form so legitimate comparative prose is not flagged; the
+# bare-intensifier form still matches.
+RATHER_QUALIFIER_RE: Final[re.Pattern[str]] = re.compile(r"(?i)\brather\b(?!\s+than\b)")
+
+# Every qualifier regex contributes findings. The order is fixed so the
+# matcher's output is deterministic across runs.
+QUALIFIER_RES: Final[tuple[re.Pattern[str], ...]] = (
+    QUALIFIER_RE,
+    RATHER_QUALIFIER_RE,
+)
+
+CODE_FENCE_RE: Final[re.Pattern[str]] = re.compile(r"^```")
+# Inline-code span: a single-backtick-delimited run on one line. A filler
+# phrase or qualifier quoted inside backticks is a meta-linguistic citation
+# (a doc naming the vocabulary it forbids), not prose that uses it, so these
+# spans are blanked before the scan. The column-preserving blank mirrors the
+# inline-code exclusion in binding_reciprocity_grep.
+INLINE_CODE_RE: Final[re.Pattern[str]] = re.compile(r"`[^`]*`")
+QUOTE_LINE_RE: Final[re.Pattern[str]] = re.compile(r"^\s*>")
+HTML_COMMENT_OPEN_RE: Final[re.Pattern[str]] = re.compile(r"<!--")
+HTML_COMMENT_CLOSE_RE: Final[re.Pattern[str]] = re.compile(r"--!?>")
+
+GREP_NAME: Final[str] = "token-efficiency-grep"
+RULE_ANCHOR: Final[str] = "clean-room-generation §5 + token-efficiency-rewrite"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One filler or qualifier occurrence outside an excluded region."""
+
+    line: int
+    match: str
+    context: str
+    rule: str = RULE_ANCHOR
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content; return a structured result.
+
+    Pre-conditions: `content` is the artifact body about to be emitted.
+    Post-conditions: `result.passed` is True iff zero filler phrases and
+    zero content-free qualifiers were found outside fenced code blocks,
+    inline-code spans, quoted lines, or HTML comment regions.
+    """
+    findings: list[Finding] = []
+    inside_fence = False
+    inside_html_comment = 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
+        # Track HTML comment span. A single-line comment opens and closes
+        # on the same line; a multi-line comment spans several lines.
+        working = line
+        if inside_html_comment:
+            close = HTML_COMMENT_CLOSE_RE.search(working)
+            if close is None:
+                continue
+            inside_html_comment = False
+            working = working[close.end() :]
+        # Strip inline comments and detect a trailing open.
+        while True:
+            open_match = HTML_COMMENT_OPEN_RE.search(working)
+            if open_match is None:
+                break
+            close_match = HTML_COMMENT_CLOSE_RE.search(working, open_match.end())
+            if close_match is None:
+                working = working[: open_match.start()]
+                inside_html_comment = True
+                break
+            working = working[: open_match.start()] + working[close_match.end() :]
+        # Blank inline-code spans (same-length spaces preserve columns) so a
+        # filler phrase or qualifier cited inside backticks — a doc that
+        # forbids the `kind of` phrasing — is read as a citation, not prose.
+        working = INLINE_CODE_RE.sub(lambda m: " " * len(m.group(0)), working)
+        if QUOTE_LINE_RE.match(working):
+            continue
+        if not working.strip():
+            continue
+        for match in FILLER_RE.finditer(working):
+            findings.append(
+                Finding(
+                    line=line_index,
+                    match=match.group(),
+                    context=line.strip(),
+                )
+            )
+        for qualifier_re in QUALIFIER_RES:
+            for match in qualifier_re.finditer(working):
+                findings.append(
+                    Finding(
+                        line=line_index,
+                        match=match.group(),
+                        context=line.strip(),
+                    )
+                )
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(path) if path is not None else None,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(run_grep(check, sys.argv))

package/src/apothem/conformity/unpinned_action_grep.py

@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: MIT
+
+"""Flag GitHub Actions workflows that pin actions to mutable refs.
+
+Why this enforcement exists. The production-ready discipline M15 + the
+supply-chain posture preservation clause require third-party action
+references to be pinned to a 40-character commit SHA rather than a
+floating tag. A `uses: actions/checkout@v4` reference can silently
+re-point to a malicious release; a `uses: actions/checkout@<40-char-sha>`
+reference cannot. The pre-emission gate's mechanical bar 15 (M15 supply-chain) catches the
+mutable-ref shapes (`@main`, `@master`, `@latest`, `@v1`, `@v1.x.y`,
+`@<branch>`) and surfaces each occurrence so the operator pins to a
+SHA in the same change-set.
+
+Detection strategy. The grep parses every line beginning with
+`uses: <owner>/<action>@<ref>` (whitespace-tolerant) and inspects the
+`<ref>`. A 40-character lowercase-hex SHA is the only conformant form;
+anything else is flagged with the parsed action name and the offending
+ref so the operator can rewrite to the SHA pin.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from apothem.conformity._grep_base import GrepResult, run_grep
+
+# `uses: <owner>/<action>(/<sub>)*@<ref>` shape per the GitHub Actions
+# workflow YAML specification. The optional sub-path matches actions like
+# `actions/cache/save@v3`. The capture groups isolate the action name and
+# the ref so the finding can name both. A trailing `# ...` comment is
+# tolerated so inline exemption markers (see `EXEMPTION_RE`) sit on the
+# same line as the declaration without causing the regex to miss-match.
+USES_LINE_RE: Final[re.Pattern[str]] = re.compile(
+    r"^\s*-?\s*uses:\s*([\w./-]+)@([\w./+-]+)\s*(?:#.*)?$"
+)
+
+# Canonical SHA shape — exactly forty lowercase hex characters. No upper-
+# case, no shorter prefixes (those are abbreviations, not pins).
+COMMIT_SHA_RE: Final[re.Pattern[str]] = re.compile(r"^[0-9a-f]{40}$")
+
+# Inline exemption marker. A `uses:` line carrying a trailing comment of
+# the form `# action-pinning-exempt: <reason>` is exempt from the SHA-pin
+# requirement. The reason is required (audit-trail discipline) — bare
+# `# action-pinning-exempt` without a reason is not honored. Canonical
+# use case: SLSA reusable-workflow references where the Sigstore policy
+# forbids SHA-pinning and the `@<tag>` form is the trust anchor rather
+# than a mutable ref.
+EXEMPTION_RE: Final[re.Pattern[str]] = re.compile(r"#\s*action-pinning-exempt:\s*\S")
+
+# Local-action references (path within the same repository) start with
+# `./` and are out of scope — they're not third-party supply-chain risks.
+LOCAL_ACTION_PREFIX: Final[str] = "./"
+
+GREP_NAME: Final[str] = "unpinned-action-grep"
+RULE_ANCHOR: Final[str] = "M15 production-ready §Supply-chain"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One unpinned-action occurrence."""
+
+    line: int
+    action: str
+    ref: str
+    rule: str = RULE_ANCHOR
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content; return a structured result.
+
+    Pre-conditions: `content` is the YAML body of a workflow file about
+    to be emitted. The grep accepts content from any source — the
+    operator points it at a single workflow file or pipes a multi-file
+    bundle via stdin.
+    Post-conditions: `result.passed` is True iff every `uses: <action>@<ref>`
+    declaration's ref is a 40-character commit SHA, or the action is a
+    local in-repo reference exempt from supply-chain pinning.
+    """
+    findings: list[Finding] = []
+    for line_index, line in enumerate(content.splitlines(), start=1):
+        match = USES_LINE_RE.match(line)
+        if match is None:
+            continue
+        action, ref = match.group(1), match.group(2)
+        if action.startswith(LOCAL_ACTION_PREFIX):
+            continue
+        if COMMIT_SHA_RE.match(ref) is not None:
+            continue
+        if EXEMPTION_RE.search(line) is not None:
+            continue
+        findings.append(
+            Finding(
+                line=line_index,
+                action=action,
+                ref=ref,
+            )
+        )
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(path) if path is not None else None,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(run_grep(check, sys.argv))

package/src/apothem/conformity/user_confirm_grep.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+
+"""Block emission of artifacts containing unresolved authority placeholders.
+
+Why this enforcement exists. Required-category inquiries (identity, scope
+direction, security, public-surface naming) emit a `<USER-CONFIRM:id=...>`
+placeholder that the operator must resolve before the artifact ships. An
+unfilled placeholder reaching emission means a required-data inquiry was
+never closed; the artifact would silently bind to fabricated authority data
+the moment it lands. The pre-emission gate's mechanical bar 5 (M5 authority) catches the
+literal placeholder shape so the operator never has to remember.
+
+Invocation. Two surfaces: as a callable for the orchestrator (`check(content,
+path)`), or as a CLI tool (`python user-confirm-grep.py <file>` / `--stdin`).
+Exit code 0 indicates clean; non-zero indicates a finding. Stdout carries a
+JSON report regardless of outcome — the orchestrator reads it; humans read
+it for triage.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Final
+
+from apothem.conformity._grep_base import GrepResult, run_grep
+
+# The canonical placeholder shape declared in the authority-inquiry rule §10.
+# `<USER-CONFIRM:id=foo>`, `<USER-CONFIRM:kind=bar>`, and bare `<USER-CONFIRM>`
+# all flag — the colon-id form is the documented contract; the bare form is
+# rare but equally non-conformant.
+PLACEHOLDER_RE: Final[re.Pattern[str]] = re.compile(r"<USER-CONFIRM(?::[^>]*)?>")
+
+GREP_NAME: Final[str] = "user-confirm-grep"
+RULE_ANCHOR: Final[str] = "M5 authority-inquiry §10"
+EXIT_PASS: Final[int] = 0
+EXIT_FAIL: Final[int] = 2
+STDIN_FLAG: Final[str] = "--stdin"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """One placeholder occurrence in the artifact body."""
+
+    line: int
+    match: str
+    rule: str = RULE_ANCHOR
+
+
+def check(content: str, path: Path | None = None) -> GrepResult:
+    """Scan content; return a structured result.
+
+    Pre-conditions: `content` is the artifact body about to be emitted.
+    Post-conditions: `result.passed` is True iff zero placeholders were found.
+    Failure mode: malformed UTF-8 raises `UnicodeDecodeError` at the read site,
+    not here — this function operates on already-decoded text.
+    """
+    findings: list[Finding] = []
+    for match in PLACEHOLDER_RE.finditer(content):
+        # Convert byte offset to a 1-indexed line number for human triage.
+        line = content.count("\n", 0, match.start()) + 1
+        findings.append(Finding(line=line, match=match.group()))
+    return GrepResult(
+        grep=GREP_NAME,
+        path=str(path) if path is not None else None,
+        passed=not findings,
+        findings=findings,
+    )
+
+
+if __name__ == "__main__":
+    sys.exit(run_grep(check, sys.argv))