cbp-action 0.1.7__py3-none-any.whl

cbp/artifact_integrity.py

@@ -0,0 +1,142 @@
+"""Release-artifact and Python environment integrity checks."""
+from __future__ import annotations
+
+import ast
+import hashlib
+import re
+import zipfile
+from pathlib import Path
+
+from .config import GateConfig
+
+SKIP_PARTS = {".git", ".venv", "__pycache__", "node_modules", "wheelhouse", "qa-temp", "build"}
+SKIP_PREFIXES = ("quality/", "checks/", "tests/", "tools/audit_", "tools/red_team", "tools/package_release", "tools/prune_", "tools/restructure_", "tools/rewrite_")
+BAD_NAMES = {"netstat", "netstat.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe", "cmd", "cmd.exe"}
+
+
+def artifact_findings(cfg: GateConfig) -> list[str]:
+    """Verify configured artifacts inside an optional package ZIP."""
+    required = getattr(cfg, "required_artifacts", ()) or ()
+    if not getattr(cfg, "package_zip", None):
+        return []
+    if not required:
+        return ["package_zip is configured but required_artifacts is empty"]
+    zip_path = Path(cfg.package_zip)
+    if not zip_path.is_file():
+        return [f"package zip missing: {zip_path}"]
+    findings: list[str] = []
+    try:
+        with zipfile.ZipFile(zip_path) as archive:
+            names = set(archive.namelist())
+            manifest: dict[str, str] = {}
+            if "update-manifest.json" in names:
+                import json
+                data = json.loads(archive.read("update-manifest.json").decode("utf-8"))
+                manifest = {str(item["path"]): str(item["sha256"]) for item in data.get("files", [])}
+            for item in required:
+                path = str(item.get("path")) if isinstance(item, dict) else str(item)
+                expected = str(item.get("sha256", "")) if isinstance(item, dict) else manifest.get(path, "")
+                if path not in names:
+                    findings.append(f"required artifact missing from zip: {path}")
+                    continue
+                if expected:
+                    digest = hashlib.sha256(archive.read(path)).hexdigest()
+                    if digest.lower() != expected.lower():
+                        findings.append(f"required artifact hash mismatch: {path}")
+    except (OSError, zipfile.BadZipFile, ValueError) as exc:
+        return [f"cannot inspect package zip: {exc}"]
+    return findings
+
+
+def _is_absolute_command(value: str) -> bool:
+    return value.startswith(("\\", "/")) or (len(value) > 2 and value[1] == ":")
+
+
+PATH_ESCAPE = None  # line-based check below avoids regex escaping ambiguity
+ACTION_REF = re.compile(r"uses:\s*([^\s#]+)")
+FULL_SHA = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[0-9a-f]{40}$")
+
+
+def path_escape_findings(cfg: GateConfig) -> list[str]:
+    """Reject hard-coded Windows paths whose backslash becomes an escape."""
+    findings: list[str] = []
+    for path in list(cfg.root.rglob("*.py")) + list(cfg.root.rglob("*.ps1")):
+        if SKIP_PARTS & set(path.parts):
+            continue
+        for line_no, line in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
+            if "C:\\" in line and any(token in line for token in ("\t", "\n", "\r")):
+                findings.append(f"{path.relative_to(cfg.root).as_posix()}:{line_no}: ambiguous Windows path escape; use os.path.join or escaped slashes")
+    return findings
+
+
+def python_env_findings(cfg: GateConfig) -> list[str]:
+    """Reject obvious PATH-dependent subprocess calls and missing sys.path guards."""
+    findings: list[str] = []
+    for path in cfg.root.rglob("*.py"):
+        rel = path.relative_to(cfg.root).as_posix()
+        if SKIP_PARTS & set(path.parts) or rel.startswith(SKIP_PREFIXES):
+            continue
+        try:
+            tree = ast.parse(path.read_text(encoding="utf-8"))
+        except (OSError, SyntaxError):
+            continue
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call) or not node.args:
+                continue
+            func = node.func
+            name = ""
+            if isinstance(func, ast.Attribute):
+                name = func.attr
+            if name not in {"run", "Popen", "call", "check_output", "system"}:
+                continue
+            first = node.args[0]
+            command = ""
+            if isinstance(first, ast.Constant) and isinstance(first.value, str):
+                command = first.value
+            elif isinstance(first, (ast.List, ast.Tuple)) and first.elts:
+                head = first.elts[0]
+                if isinstance(head, ast.Constant) and isinstance(head.value, str):
+                    command = head.value
+            if command:
+                token = command.strip().split()[0] if command.strip() else ""
+                base = Path(token).name.lower()
+                if base in BAD_NAMES and not _is_absolute_command(token):
+                    findings.append(f"{path.relative_to(cfg.root).as_posix()}:{node.lineno}: naked external command {token!r}")
+    for name in ("tools/broker.py", "webui/run.py"):
+        path = cfg.root / name
+        if path.is_file() and "sys.path.insert" not in path.read_text(encoding="utf-8"):
+            findings.append(f"{name}: missing sys.path.insert bootstrap")
+    for path in list(cfg.root.rglob("*.bat")) + list(cfg.root.rglob("*.ps1")):
+        if SKIP_PARTS & set(path.parts):
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace")
+        for line in text.splitlines():
+            if "PYTHONPATH" in line and "=" in line:
+                if "tools" not in line:
+                    findings.append(f"{path.relative_to(cfg.root).as_posix()}: PYTHONPATH must include tools/")
+                    break
+    return findings
+
+
+def action_pin_findings(cfg: GateConfig) -> list[str]:
+    """Require every GitHub Action use to be pinned to a full commit SHA."""
+    findings: list[str] = []
+    for path in list(cfg.root.rglob("*.yml")) + list(cfg.root.rglob("*.yaml")):
+        rel = path.relative_to(cfg.root).as_posix()
+        if SKIP_PARTS & set(path.parts) or rel.endswith("usage.yml") or rel.startswith(("examples/", "docs/")) or "/examples/" in rel or "/docs/" in rel:
+            continue
+        for line_no, line in enumerate(path.read_text(encoding="utf-8", errors="replace").splitlines(), 1):
+            match = ACTION_REF.search(line)
+            if not match:
+                continue
+            ref = match.group(1).strip("'\"")
+            if ref.startswith("./") or ref.startswith("docker://"):
+                continue
+            if not FULL_SHA.fullmatch(ref):
+                findings.append(f"{path.relative_to(cfg.root).as_posix()}:{line_no}: GitHub Action is not pinned to a full SHA: {ref}")
+    return findings
+
+
+def check(cfg: GateConfig) -> list[str]:
+    """Run both release-integrity checks."""
+    return artifact_findings(cfg) + python_env_findings(cfg) + path_escape_findings(cfg) + action_pin_findings(cfg)

cbp/baseline.py

@@ -0,0 +1,49 @@
+"""Baseline fingerprints for pre-existing findings."""
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+
+SCHEMA = "cbp-baseline/v1"
+
+
+def fingerprint(gate: str, line: str) -> str:
+    return hashlib.sha256((gate + "\0" + line.strip()).encode("utf-8")).hexdigest()
+
+
+def load(path: Path | str | None) -> set[str]:
+    if not path:
+        return set()
+    p = Path(path)
+    if not p.is_file():
+        return set()
+    data = json.loads(p.read_text(encoding="utf-8"))
+    return {str(item["fingerprint"]) for item in data.get("entries", []) if isinstance(item, dict) and item.get("fingerprint")}
+
+
+def write(path: Path, gate: str, lines: list[str]) -> int:
+    entries = [{"gate": gate, "fingerprint": fingerprint(gate, line), "line": line} for line in lines]
+    data = {"schema": SCHEMA, "version": 1, "entries": entries}
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    return len(entries)
+
+
+def filter_lines(cfg, gate: str, lines: list[str]) -> list[str]:
+    configured = getattr(cfg, "baseline", "")
+    path = cfg.path(configured) if configured else cfg.root / "cbp-baseline.json"
+    allowed = load(path)
+    return [line for line in lines if fingerprint(gate, line) not in allowed]
+
+
+def write_entries(path: Path, entries: list[tuple[str, str]]) -> int:
+    data = {
+        "schema": SCHEMA,
+        "version": 1,
+        "entries": [
+            {"gate": gate, "fingerprint": fingerprint(gate, line), "line": line}
+            for gate, line in entries
+        ],
+    }
+    path.write_text(json.dumps(data, ensure_ascii=False, indent=2) + chr(10), encoding="utf-8")
+    return len(data["entries"])

cbp/binary_gate.py

@@ -0,0 +1,65 @@
+"""Generic large-binary provenance gate."""
+from __future__ import annotations
+
+import hashlib
+import json
+import zipfile
+from pathlib import Path
+
+from .config import GateConfig
+
+SUFFIXES = (".exe", ".dll", ".bin", ".so", ".dylib", ".whl", ".tar.gz")
+SUPPORTED_SCOPES = {"self-contained-runtime", "runtime-pack", "runtime-only"}
+
+
+def info_size(archive, name):
+    """Return a ZIP member's uncompressed size."""
+    return archive.getinfo(name).file_size
+
+
+def _candidates(cfg: GateConfig):
+    package = cfg.path(cfg.package_zip) if cfg.package_zip else None
+    if package and package.is_file():
+        with zipfile.ZipFile(package) as archive:
+            return [(name, info_size(archive, name), archive.read(name)) for name in archive.namelist() if name.lower().endswith(SUFFIXES) and info_size(archive, name) > cfg.binary_limit_mb * 1024 * 1024]
+    result = []
+    for path in cfg.root.rglob("*"):
+        if path.is_file() and path.name.lower().endswith(SUFFIXES) and path.stat().st_size > cfg.binary_limit_mb * 1024 * 1024:
+            text = path.as_posix()
+            if (
+                ".git" not in path.parts
+                and ".venv" not in path.parts
+                and "wheelhouse" not in path.parts
+                and "build/bin" not in text
+                and "build/obj" not in text
+                and "build/publish" not in text
+            ):
+                result.append((path.name, path.stat().st_size, path.read_bytes()))
+    return result
+
+
+def run(cfg: GateConfig) -> tuple[bool, str]:
+    """Require provenance and SBOM records for large release binaries."""
+    candidates = _candidates(cfg)
+    for name, size, data in candidates:
+        artifacts = cfg.path(cfg.binary_artifacts)
+        build = artifacts / (Path(name).name + ".build.json")
+        sbom = artifacts / (Path(name).name + ".sbom.json")
+        if not build.is_file() or not sbom.is_file():
+            return False, f"{name} lacks build/SBOM provenance"
+        sbom_record = json.loads(sbom.read_text(encoding="utf-8"))
+        scope = sbom_record.get("scope")
+        if scope is not None and scope not in SUPPORTED_SCOPES:
+            return False, f"{name} has unsupported SBOM scope {scope!r}"
+        if sbom_record.get("binary_sha256") and sbom_record["binary_sha256"].upper() != hashlib.sha256(data).hexdigest().upper():
+            return False, f"{name} SBOM binary hash mismatch"
+        if "binary_size" in sbom_record and int(sbom_record["binary_size"]) != size:
+            return False, f"{name} SBOM binary size mismatch"
+        record = json.loads(build.read_text(encoding="utf-8"))
+        if record.get("sha256", "").upper() != hashlib.sha256(data).hexdigest().upper():
+            return False, f"{name} provenance hash mismatch"
+        if int(record.get("size_bytes", -1)) != size:
+            return False, f"{name} provenance size mismatch"
+    if not candidates:
+        return True, "N/A (no binaries found)"
+    return True, f"binaries={len(candidates)}"

cbp/claims_gate.py

@@ -0,0 +1,85 @@
+"""Generic release-claim reconciliation gate."""
+from __future__ import annotations
+
+RULE_ID = "CBP-CLM-001"
+
+import json
+import re
+from pathlib import Path
+
+from .config import GateConfig
+
+TOKEN = re.compile(r"(?m)^QUALITY_COUNTS:\s*(\d+)/(\d+)\s*$")
+GATE_CLAIM = re.compile(r"\b(?:all|across|through)\s+([A-Za-z]+|\d+)\s+gates?\b", re.IGNORECASE)
+WORDS = {
+    word: number
+    for number, word in enumerate(
+        ("zero", "one", "two", "three", "four", "five", "six", "seven", "eight", "nine", "ten")
+    )
+}
+
+
+def _gate_number(text: str, total: int, *, required: bool) -> str:
+    match = GATE_CLAIM.search(text)
+    if not match:
+        return "release body must state the gate count" if required else ""
+    token = match.group(1).lower()
+    number = int(token) if token.isdigit() else WORDS.get(token)
+    if number is None:
+        return f"unknown gate count claim: {match.group(0)}"
+    if number != total:
+        return f"notes claim {token} gates but manifest has {total}"
+    return ""
+
+
+def _body_problem(path: Path, expected: str, total: int) -> str:
+    if not path.is_file():
+        return f"release body missing: {path}"
+    text = path.read_text(encoding="utf-8")
+    tokens = TOKEN.findall(text)
+    if len(tokens) != 1:
+        return "release body needs exactly one QUALITY_COUNTS line"
+    actual = f"{tokens[0][0]}/{tokens[0][1]}"
+    if actual != expected:
+        return f"release body {actual} != manifest {expected}"
+    problem = _gate_number(text, total, required=True)
+    if problem:
+        return "release body " + problem
+    if "First public release" in text:
+        return "release body must not claim First public release"
+    return ""
+
+
+def run(cfg: GateConfig) -> tuple[bool, str]:
+    """Match release-note quality claims to the machine manifest."""
+    if not cfg.claims_manifest or not cfg.claims_notes:
+        return False, "claims_manifest and claims_notes must be configured"
+    manifest = cfg.path(cfg.claims_manifest)
+    notes = cfg.path(cfg.claims_notes)
+    if not manifest.is_file():
+        return False, (
+            "quality-manifest.json missing. "
+            "Run `python tools/dogfood_manifest.py --root .` first to generate a local manifest."
+        )
+    if not notes.is_file():
+        return False, "release notes missing. Run the dogfood command first to generate them."
+    data = json.loads(manifest.read_text(encoding="utf-8"))
+    counts = data.get("counts", {})
+    expected = f"{counts.get('passed', -1)}/{counts.get('total', -1)}"
+    text = notes.read_text(encoding="utf-8")
+    tokens = TOKEN.findall(text)
+    if len(tokens) != 1:
+        return False, "release notes need exactly one QUALITY_COUNTS line"
+    actual = f"{tokens[0][0]}/{tokens[0][1]}"
+    if actual != expected:
+        return False, f"notes {actual} != manifest {expected}"
+    total = int(counts.get("total", -1))
+    gate_problem = _gate_number(text, total, required=False)
+    if gate_problem:
+        return False, gate_problem
+    body = getattr(cfg, "release_body", "")
+    if body:
+        body_problem = _body_problem(cfg.path(body), expected, total)
+        if body_problem:
+            return False, body_problem
+    return True, f"claims={actual}"

cbp/cli.py

@@ -0,0 +1,148 @@
+"""Standalone CBP CLI."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from . import baseline, binary_gate, suppression, claims_gate, comment_gate, coverage_gate, custom_rules, dependency_gate, docs_gate, encoding_gate, sarif, upgrade_gate, verify_release
+from .config import load_config
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run enabled CBP gates and return a process exit code."""
+    parser = argparse.ArgumentParser(prog="cbp")
+    parser.add_argument("--root", default=".")
+    parser.add_argument("--config", default="")
+    parser.add_argument("--mode", choices=("audit", "warn", "enforce"), default="enforce")
+    parser.add_argument("--coverage-threshold", type=float, default=None)
+    parser.add_argument("--policy-coverage-threshold", type=float, default=None)
+    parser.add_argument("--coverage-json", default="")
+    parser.add_argument("--coverage-allowlist", default="")
+    parser.add_argument("--coverage-signature", default="")
+    parser.add_argument("--require-coverage-signature", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--dependency-lock", default="")
+    parser.add_argument("--install-command", default="")
+    parser.add_argument("--installer-core", dest="install_command", default=argparse.SUPPRESS)
+    parser.add_argument("--docs-manifest", default="")
+    parser.add_argument("--binary-artifacts", default="")
+    parser.add_argument("--package-zip", default="")
+    parser.add_argument("--claims-manifest", default="")
+    parser.add_argument("--claims-notes", default="")
+    parser.add_argument("--release-body", default="")
+    parser.add_argument("--manifest", default="")
+    parser.add_argument("--sarif-output", default="")
+    parser.add_argument("--baseline", default="")
+    parser.add_argument("--generate-baseline", default="")
+    parser.add_argument("--verify-release", default="")
+    parser.add_argument("--repository", default="")
+    parser.add_argument("--enable-coverage", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-encoding", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-dependency", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-comments", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-docs", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-binary", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-claims", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-custom", type=lambda x: x.lower() == "true", default=None)
+    parser.add_argument("--enable-upgrade", type=lambda x: x.lower() == "true", default=None)
+    args = parser.parse_args(argv)
+    if args.verify_release:
+        repository = args.repository or os.environ.get("GITHUB_REPOSITORY", "")
+        if not repository:
+            print("VERIFY_RELEASE_FAILED: --repository or GITHUB_REPOSITORY is required")
+            return 1
+        body = Path(args.release_body) if args.release_body else Path(args.root) / "docs" / "RELEASE_BODY.md"
+        ok, detail = verify_release.verify(repository, args.verify_release, body, verify_release.token_from_env())
+        print(("RELEASE_BODY_OK " if ok else "") + detail)
+        return 0 if ok else 1
+    config_path = Path(args.config) if args.config else Path(args.root) / "cbp.json"
+    if not args.config and not config_path.is_file():
+        config_path = Path(args.root) / ".cbp" / "config.json"
+    overrides = {}
+    if args.coverage_threshold is not None:
+        overrides["coverage_threshold"] = args.coverage_threshold
+    if args.policy_coverage_threshold is not None:
+        overrides["policy_threshold"] = args.policy_coverage_threshold
+    for key, value in {
+        "coverage_json": args.coverage_json, "coverage_allowlist": args.coverage_allowlist, "coverage_signature": args.coverage_signature,
+        "dependency_lock": args.dependency_lock, "install_command": args.install_command,
+        "docs_manifest": args.docs_manifest, "binary_artifacts": args.binary_artifacts,
+        "package_zip": args.package_zip, "claims_manifest": args.claims_manifest,
+        "claims_notes": args.claims_notes, "release_body": args.release_body, "baseline": args.baseline,
+    }.items():
+        if value:
+            overrides[key] = value
+    if args.manifest:
+        overrides["claims_manifest"] = args.manifest
+    for key in ("enable_coverage", "require_coverage_signature", "enable_encoding", "enable_dependency", "enable_comments", "enable_docs", "enable_binary", "enable_claims", "enable_custom", "enable_upgrade"):
+        value = getattr(args, key)
+        if value is not None:
+            overrides[key] = value
+    cfg = load_config(Path(args.root), config_path, overrides)
+    checks = []
+    if cfg.enable_encoding:
+        checks.append(("encoding", encoding_gate.run))
+    if cfg.enable_coverage:
+        checks.append(("coverage", coverage_gate.run))
+    if cfg.enable_dependency:
+        checks.append(("dependency", dependency_gate.run))
+    if cfg.enable_comments:
+        checks.append(("comments", comment_gate.run))
+    if cfg.enable_docs:
+        checks.append(("docs", docs_gate.run))
+    if cfg.enable_claims:
+        checks.append(("claims", claims_gate.run))
+    if cfg.enable_custom:
+        checks.append(("custom", custom_rules.run))
+    if cfg.enable_upgrade:
+        checks.append(("upgrade", upgrade_gate.run))
+    if cfg.enable_binary:
+        checks.append(("binary", binary_gate.run))
+    ok = True
+    gate_results = []
+    for name, check in checks:
+        passed, detail = check(cfg)
+        filtered = suppression.filter_text(cfg.root, detail)
+        if filtered != detail:
+            passed = passed or not filtered.strip()
+            detail = filtered or "inline-suppressed"
+        gate_results.append((name, passed, detail))
+        print(f"{name}: {'PASS' if passed else 'FAIL'} {detail}")
+        ok = ok and passed
+    if not checks:
+        ok = False
+    baseline_path = Path(args.generate_baseline) if args.generate_baseline else Path(args.baseline) if args.baseline else Path(args.root) / "cbp-baseline.json"
+    if args.generate_baseline:
+        entries = []
+        for gate, passed, detail in gate_results:
+            if not passed:
+                entries.extend((gate, line) for line in detail.splitlines() if line.strip())
+        baseline.write_entries(baseline_path, entries)
+        print(f"BASELINE_WRITTEN path={baseline_path} entries={len(entries)}")
+        return 0
+    allowed_baseline = baseline.load(baseline_path)
+    if allowed_baseline:
+        adjusted = []
+        for gate, passed, detail in gate_results:
+            kept = [line for line in detail.splitlines() if baseline.fingerprint(gate, line) not in allowed_baseline]
+            if not passed and not any(line.strip() for line in kept):
+                passed = True
+            adjusted.append((gate, passed, chr(10).join(kept) if kept else "baseline-suppressed"))
+        gate_results = adjusted
+        ok = all(passed for _, passed, _ in gate_results)
+    if args.sarif_output:
+        try:
+            target = Path(args.sarif_output)
+            document = sarif.build(gate_results, Path(args.root))
+            target.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+        except OSError as exc:
+            print(f"sarif: FAIL cannot write {args.sarif_output}: {exc}")
+            ok = False
+    print("CBP_RESULT=" + ("PASS" if ok else "FAIL") + " gates_ran=" + str(len(checks)))
+    return 0 if ok or args.mode in {"audit", "warn"} else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cbp/comment_gate.py

@@ -0,0 +1,69 @@
+"""Generic AST/token comment gate."""
+from __future__ import annotations
+
+RULE_ID = "CBP-CMT-001"
+
+import ast
+import re
+import tokenize
+
+from .config import GateConfig
+from .baseline import filter_lines
+
+SLOP = re.compile(r"#\s*(This is|It is|This function|This method|This class)\b", re.IGNORECASE)
+SUPPRESS = re.compile(r"cbp:\s*ignore=(CBP-[A-Z]+-\d{3})", re.IGNORECASE)
+GENERIC = ("caller-supplied value", "function result, or none", "helper/type")
+
+
+def _suppressed(lines: list[str], lineno: int, rule: str) -> bool:
+    if lineno < 1 or lineno > len(lines):
+        return False
+    line = lines[lineno - 1]
+    match = SUPPRESS.search(line)
+    return bool(match and match.group(1).upper() == rule.upper())
+
+
+def _check(path, findings):
+    text = path.read_text(encoding="utf-8")
+    lines = text.splitlines()
+    tree = ast.parse(text)
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            continue
+        name = getattr(node, "name", "")
+        if name.startswith("_"):
+            continue
+        doc = ast.get_docstring(node) or ""
+        if len(doc.strip()) < 20:
+            if not _suppressed(lines, node.lineno, RULE_ID):
+                findings.append(f"{path.name}:{node.lineno}: public {name} lacks substantive docstring")
+            continue
+        if any(phrase in doc.casefold() for phrase in GENERIC):
+            if not _suppressed(lines, node.lineno, RULE_ID):
+                findings.append(f"{path.name}:{node.lineno}: public {name} docstring is generic boilerplate")
+        args = [a.arg for a in node.args.args if a.arg not in {"self", "cls"}] if hasattr(node, "args") else []
+        if "Args:" in doc or "Parameters:" in doc:
+            for arg in args:
+                if arg not in doc and not _suppressed(lines, node.lineno, RULE_ID):
+                    findings.append(f"{path.name}:{node.lineno}: docstring misses {arg}")
+    with path.open("r", encoding="utf-8") as handle:
+        for token in tokenize.generate_tokens(handle.readline):
+            if token.type == tokenize.COMMENT and SLOP.search(token.string):
+                if not _suppressed(lines, token.start[0], RULE_ID):
+                    findings.append(f"{path.name}:{token.start[0]}: slop comment {token.string.strip()}")
+
+
+def run(cfg: GateConfig) -> tuple[bool, str]:
+    """Reject missing docstrings, argument mismatches, and slop comments."""
+    findings: list[str] = []
+    for relative in cfg.comment_files:
+        path = cfg.path(relative)
+        if path.is_file():
+            try:
+                _check(path, findings)
+            except SyntaxError as exc:
+                findings.append(f"{path.name}: parse failed: {exc}")
+    findings = filter_lines(cfg, "comments", findings)
+    if findings:
+        return False, "\n".join(findings[:80]) + f"\nfindings={len(findings)}"
+    return True, f"comments={len(cfg.comment_files)} files (balanced against baseline)"