@event4u/agent-config 2.20.0 → 2.21.0

package/scripts/compress_memory.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Input-side memory compression — Phase 2 of step-16-caveman-substance.
+
+Rewrites memory files (AGENTS.md, CLAUDE.md, .cursorrules, ...) to caveman
+grammar (drop articles / auxiliaries) while preserving carve-outs byte-for-byte
+(code blocks, numbered-options, status markers, Iron-Law ALL-CAPS, backtick
+spans). Writes `.original.md` backup before mutating. Gated by Phase 0
+`validate_safe_paths.assert_safe`. Idempotency guard: `original_sha256:` +
+`compressed_at:` frontmatter refuse re-compression on body-hash drift.
+
+CLI: `compress_memory.py <path> [--check|--decompress]`. Stdlib-only.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+
+from validate_safe_paths import SensitivePathError, assert_safe  # noqa: E402
+
+__all__ = ["compress_text", "compress_file", "decompress_file", "CompressionRefused"]
+
+
+class CompressionRefused(RuntimeError):
+    """Raised when the target is already compressed and body hash diverged."""
+
+
+# Carve-out region patterns — mirrors caveman-speak.md § Carve-outs (1–7).
+RE_FENCE = re.compile(r"^```")
+RE_NUMBERED = re.compile(r"^>?\s*\d+\.\s")
+RE_STATUS = re.compile(r"^\s*(?:❌|⚠️|✅)")
+RE_IRONLAW = re.compile(r"^[A-Z][A-Z0-9 ,.\-_/']{3,}$")
+RE_BACKTICK_SPAN = re.compile(r"`[^`\n]+`")
+RE_FRONTMATTER = re.compile(r"^---\s*$")
+WORD_RE = re.compile(r"\b[A-Za-z]+\b")
+DROP_TOKENS = {"the", "a", "an", "is", "are", "was", "were", "be", "been",
+               "being", "that", "which"}
+
+
+def _compress_words(text: str) -> str:
+    out = WORD_RE.sub(lambda m: "" if m.group(0).lower() in DROP_TOKENS else m.group(0), text)
+    out = re.sub(r"[ \t]{2,}", " ", out)
+    return re.sub(r" +([,.;:!?])", r"\1", out)
+
+
+def _compress_prose_line(line: str) -> str:
+    """Compress a prose line; preserve backtick-spans byte-for-byte."""
+    parts: list[str] = []
+    last = 0
+    for span in RE_BACKTICK_SPAN.finditer(line):
+        parts.append(_compress_words(line[last:span.start()]))
+        parts.append(span.group(0))
+        last = span.end()
+    parts.append(_compress_words(line[last:]))
+    return "".join(parts)
+
+
+def compress_text(body: str) -> str:
+    """Compress a memory-file body. Idempotent on already-caveman text."""
+    out: list[str] = []
+    in_fence = False
+    for raw in body.splitlines(keepends=True):
+        stripped = raw.rstrip("\r\n")
+        if RE_FENCE.match(stripped):
+            in_fence = not in_fence
+            out.append(raw)
+            continue
+        if in_fence or RE_NUMBERED.match(stripped) or RE_STATUS.match(stripped) \
+                or RE_IRONLAW.match(stripped.strip()):
+            out.append(raw)
+            continue
+        out.append(_compress_prose_line(raw))
+    return "".join(out)
+
+
+def _split_frontmatter(text: str) -> tuple[str, str]:
+    lines = text.splitlines(keepends=True)
+    if not lines or not RE_FRONTMATTER.match(lines[0].rstrip()):
+        return "", text
+    for idx in range(1, len(lines)):
+        if RE_FRONTMATTER.match(lines[idx].rstrip()):
+            return "".join(lines[: idx + 1]), "".join(lines[idx + 1:])
+    return "", text
+
+
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _has_sha_marker(fm: str) -> bool:
+    return bool(re.search(r"^original_sha256:\s*[0-9a-f]{64}\s*$", fm, re.MULTILINE))
+
+
+def _inject_frontmatter(fm: str, sha: str, ts: str) -> str:
+    drop = re.compile(r"^(original_sha256|compressed_at):.*$", re.MULTILINE)
+    inner = drop.sub("", fm.strip().strip("-").strip()).strip() if fm else ""
+    body = inner + ("\n" if inner else "")
+    return f"---\n{body}original_sha256: {sha}\ncompressed_at: {ts}\n---\n"
+
+
+def _backup_path(target: Path) -> Path:
+    return target.parent / (target.name + ".original.md")
+
+
+def compress_file(target: Path) -> Path:
+    assert_safe(target)
+    text = target.read_text(encoding="utf-8")
+    fm, body = _split_frontmatter(text)
+    if _has_sha_marker(fm):
+        if _sha256(compress_text(body)) != _sha256(body):
+            raise CompressionRefused(
+                f"{target}: body hash diverged; decompress first "
+                f"(`scripts/compress_memory.py {target} --decompress`)."
+            )
+        return target
+    backup = _backup_path(target)
+    backup.write_text(text, encoding="utf-8")
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    target.write_text(
+        _inject_frontmatter(fm, _sha256(body), ts) + compress_text(body),
+        encoding="utf-8",
+    )
+    return backup
+
+
+def decompress_file(target: Path) -> Path:
+    assert_safe(target)
+    backup = _backup_path(target)
+    if not backup.is_file():
+        raise FileNotFoundError(f"no backup at {backup}")
+    target.write_text(backup.read_text(encoding="utf-8"), encoding="utf-8")
+    backup.unlink()
+    return target
+
+
+def _main(argv: list[str]) -> int:
+    ap = argparse.ArgumentParser(description="Compress memory files to caveman grammar.")
+    ap.add_argument("path", type=Path)
+    grp = ap.add_mutually_exclusive_group()
+    grp.add_argument("--check", action="store_true", help="exit 0 if safe; no writes")
+    grp.add_argument("--decompress", action="store_true", help="restore .original.md")
+    args = ap.parse_args(argv)
+    try:
+        if args.check:
+            assert_safe(args.path)
+            return 0
+        if args.decompress:
+            decompress_file(args.path)
+            print(f"decompressed: {args.path}")
+            return 0
+        backup = compress_file(args.path)
+        print(f"compressed: {args.path}  (backup: {backup})")
+        return 0
+    except SensitivePathError as exc:
+        print(f"error: refused: {exc}", file=sys.stderr)
+        return 2
+    except CompressionRefused as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 3
+    except FileNotFoundError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 4
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main(sys.argv[1:]))

package/scripts/cost_by_conversation.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Group cost-tracking sessions by conversation_id (Ruflo `conversation.mjs` `5b71c7a` ref)."""
+from __future__ import annotations
+import argparse, json, sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
+
+
+def _load(path: Path) -> list[dict]:
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        try:
+            out.append(json.loads(s))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def group(rows: list[dict]) -> dict:
+    by_conv: dict = defaultdict(lambda: {
+        "sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0,
+        "output_tokens": 0, "caveman_delta_tokens": 0,
+        "by_model": defaultdict(lambda: {"sessions": 0, "cost_usd": 0.0}),
+    })
+    for row in rows:
+        cid = str(row.get("conversation_id") or "unknown")
+        b = by_conv[cid]
+        cost = float(row.get("total_cost_usd") or 0)
+        b["sessions"] += 1
+        b["total_cost_usd"] += cost
+        b["input_tokens"] += int(row.get("input_tokens") or 0)
+        b["output_tokens"] += int(row.get("output_tokens") or 0)
+        b["caveman_delta_tokens"] += int(row.get("caveman_delta_tokens") or 0)
+        m = b["by_model"][str(row.get("model") or "unknown")]
+        m["sessions"] += 1
+        m["cost_usd"] += cost
+    return {cid: {**b, "by_model": dict(b["by_model"])} for cid, b in by_conv.items()}
+
+
+def render_text(report: dict) -> str:
+    if not report:
+        return "cost-by-conversation: no rows.\n"
+    lines = ["cost-by-conversation lens · grouped by conversation_id", ""]
+    for cid, b in sorted(report.items()):
+        lines.append(
+            f"  {cid}: {b['sessions']} sessions · ${b['total_cost_usd']:.4f} · "
+            f"in {b['input_tokens']:,} · out {b['output_tokens']:,} · "
+            f"caveman_delta {b['caveman_delta_tokens']:+,}"
+        )
+        for model, m in sorted(b["by_model"].items()):
+            lines.append(f"      {model}: {m['sessions']} sessions · ${m['cost_usd']:.4f}")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--input", type=Path, default=DEFAULT_JSONL)
+    p.add_argument("--format", choices=["text", "json"], default="text")
+    args = p.parse_args(argv)
+    report = group(_load(args.input))
+    if args.format == "json":
+        print(json.dumps({"schema_version": "cost-by-conversation/v1",
+                          "by_conversation": report}, indent=2))
+    else:
+        print(render_text(report))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cost_summary.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Emit `cost-summary/v1` JSON per `docs/contracts/cost-summary-schema.md`.
+
+Reads `agents/cost-tracking/sessions.jsonl` (or `--input`), aggregates by
+session, conversation, and model. Honors the caveman suspended-multiplier
+contract (delta = 0 while suspended; see `caveman-telemetry.md`).
+"""
+from __future__ import annotations
+import argparse, json, sys
+from collections import defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DEFAULT_JSONL = REPO_ROOT / "agents" / "cost-tracking" / "sessions.jsonl"
+SCHEMA = "cost-summary/v1"
+MULTIPLIER_VERSION = "v1"
+MULTIPLIER_ACTIVE = False
+
+
+def _load(path: Path) -> list[dict]:
+    if not path.is_file():
+        return []
+    out = []
+    for line in path.read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if not s or s.startswith("#"):
+            continue
+        try:
+            out.append(json.loads(s))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def _delta(row: dict) -> int:
+    if not MULTIPLIER_ACTIVE:
+        return 0
+    return int(row.get("caveman_delta_tokens") or 0)
+
+
+def _zero_kv() -> dict:
+    return {"sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0,
+            "output_tokens": 0, "caveman_delta_tokens": 0}
+
+
+def _zero_model() -> dict:
+    return {"sessions": 0, "total_cost_usd": 0.0, "input_tokens": 0, "output_tokens": 0}
+
+
+def aggregate(rows: list[dict]) -> dict:
+    by_sess: dict = defaultdict(_zero_kv)
+    by_conv: dict = defaultdict(_zero_kv)
+    by_model: dict = defaultdict(_zero_model)
+    totals = _zero_kv()
+    for row in rows:
+        sid = str(row.get("sessionId") or row.get("session_id") or "unknown")
+        cid = str(row.get("conversation_id") or "unknown")
+        model = str(row.get("model") or "unknown")
+        cost = float(row.get("total_cost_usd") or 0)
+        itok = int(row.get("input_tokens") or 0)
+        otok = int(row.get("output_tokens") or 0)
+        delta = _delta(row)
+        for bucket in (by_sess[sid], by_conv[cid], totals):
+            bucket["sessions"] += 1
+            bucket["total_cost_usd"] += cost
+            bucket["input_tokens"] += itok
+            bucket["output_tokens"] += otok
+            bucket["caveman_delta_tokens"] += delta
+        m = by_model[model]
+        m["sessions"] += 1
+        m["total_cost_usd"] += cost
+        m["input_tokens"] += itok
+        m["output_tokens"] += otok
+    totals["caveman_multiplier_version"] = MULTIPLIER_VERSION
+    totals["caveman_multiplier_active"] = MULTIPLIER_ACTIVE
+    return {
+        "schema_version": SCHEMA,
+        "generated_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "totals": totals,
+        "by_session": [{"key": k, **v} for k, v in sorted(by_sess.items())],
+        "by_conversation": [{"key": k, **v} for k, v in sorted(by_conv.items())],
+        "by_model": [{"model": k, **v} for k, v in sorted(by_model.items())],
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("--input", type=Path, default=DEFAULT_JSONL)
+    p.add_argument("--format", choices=["json"], default="json")
+    args = p.parse_args(argv)
+    print(json.dumps(aggregate(_load(args.input)), indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_roadmap_complexity.py

@@ -177,8 +177,9 @@ def main() -> int:
     roadmaps = sorted(REPO_ROOT.glob(ROADMAP_GLOB))
     horizon_weeks = _read_horizon_weeks()
     if not roadmaps:
-        print(f"❌  no roadmaps matched {ROADMAP_GLOB}", file=sys.stderr)
-        return 1
+        if not QUIET:
+            print(f"✅  no active roadmaps under {ROADMAP_GLOB} — nothing to lint")
+        return 0
     failed = 0
     summary: list[tuple[str, str]] = []
     for roadmap in roadmaps:

package/scripts/update_counts.py

@@ -55,11 +55,13 @@ TARGETS: list[tuple[str, list[tuple[str, str]]]] = [
         [
             (r"(Browse all )(\d+)( commands\])", "commands"),
             (r"(package \(rules \+ )(\d+)( skills)", "skills"),
-            # Hero line: **NNN Skills** · **NNN Rules** · **NNN Commands** · **NNN Guidelines**
-            (r"(<strong>)(\d+)( Skills</strong>)", "skills"),
-            (r"(<strong>)(\d+)( Rules</strong>)", "rules"),
-            (r"(<strong>)(\d+)( Guidelines</strong>)", "guidelines"),
-            # NOTE: hero `<strong>N Commands</strong>` and tools-blurb
+            # Hero badges: shields.io URLs `Skills-NNN-<color>` etc.
+            # Format: https://img.shields.io/badge/<Label>-<N>-<hex>?style=flat-square
+            (r"(/badge/Skills-)(\d+)(-)", "skills"),
+            (r"(/badge/Rules-)(\d+)(-)", "rules"),
+            (r"(/badge/Guidelines-)(\d+)(-)", "guidelines"),
+            (r"(/badge/Personas-)(\d+)(-)", "personas"),
+            # NOTE: hero `Commands-N` badge and tools-blurb
             # `skills + N native commands` are owned by
             # `check_command_count_messaging.py` (Phase-1.2 of
             # road-to-pr-34-followups). Those surfaces advertise the

package/scripts/validate_caveman_carveouts.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""Mechanical carve-out validator for caveman-compressed replies.
+
+Given a pre-compression reply and a post-compression reply, assert that
+every carve-out region from `.agent-src.uncompressed/rules/caveman-speak.md`
+§ Carve-outs survived byte-for-byte:
+
+  1. Triple-backtick code blocks (any language).
+  2. Numbered-option lines  (`^>?\\s*\\d+\\.\\s` plus the
+     `**Recommendation:**` / `**Empfehlung:**` label).
+  3. Backtick spans (file paths, command names, identifiers).
+  4. Status / error marker lines (prefix `❌`, `⚠️`, `✅`).
+  5. Triple-backtick ALL-CAPS Iron-Law literal fences (subset of (1) —
+     reported separately for diagnostics).
+
+Stdlib only. Exit 0 = all carve-outs preserved; exit 1 = drift detected.
+"""
+from __future__ import annotations
+
+import argparse
+import difflib
+import re
+import sys
+from pathlib import Path
+
+# Triple-backtick fenced blocks (greedy across lines). Group 1 = body.
+RE_CODE_FENCE = re.compile(r"```[^\n]*\n(.*?)\n```", re.DOTALL)
+# Numbered-option line: optional `> ` quote prefix, digits, dot, space.
+RE_NUMBERED = re.compile(r"^>?\s*\d+\.\s.*$", re.MULTILINE)
+# Recommendation labels (both languages).
+RE_RECOMMEND = re.compile(r"^\*\*(Recommendation|Empfehlung):\*\*.*$", re.MULTILINE)
+# Backtick spans — single-tick, non-greedy, no newlines inside.
+RE_BACKTICK_SPAN = re.compile(r"`[^`\n]+`")
+# Status / error marker lines (full line containing the marker).
+RE_STATUS_LINE = re.compile(r"^.*[❌⚠✅].*$", re.MULTILINE)
+# Iron-Law ALL-CAPS fence body — letters + spaces + basic punctuation, ≥ 80 % uppercase.
+RE_ALLCAPS_LINE = re.compile(r"^[A-Z0-9 ,\.\-—:'\"·/\(\)]+$")
+
+
+def _extract_code_fences(text: str) -> list[str]:
+    return [m.group(0) for m in RE_CODE_FENCE.finditer(text)]
+
+
+def _extract_lines(text: str, pattern: re.Pattern) -> list[str]:
+    return [m.group(0) for m in pattern.finditer(text)]
+
+
+def _extract_backtick_spans(text: str) -> list[str]:
+    # Excludes triple-backtick fences (handled separately).
+    stripped = RE_CODE_FENCE.sub("", text)
+    return RE_BACKTICK_SPAN.findall(stripped)
+
+
+def _is_allcaps_fence_body(body: str) -> bool:
+    lines = [ln.strip() for ln in body.splitlines() if ln.strip()]
+    if not lines:
+        return False
+    return all(RE_ALLCAPS_LINE.match(ln) for ln in lines)
+
+
+def _extract_allcaps_fences(text: str) -> list[str]:
+    out: list[str] = []
+    for m in RE_CODE_FENCE.finditer(text):
+        if _is_allcaps_fence_body(m.group(1)):
+            out.append(m.group(0))
+    return out
+
+
+CHECKS = (
+    ("code_fences", _extract_code_fences),
+    ("numbered_options", lambda t: _extract_lines(t, RE_NUMBERED)),
+    ("recommendation_labels", lambda t: _extract_lines(t, RE_RECOMMEND)),
+    ("backtick_spans", _extract_backtick_spans),
+    ("status_markers", lambda t: _extract_lines(t, RE_STATUS_LINE)),
+    ("allcaps_iron_law_fences", _extract_allcaps_fences),
+)
+
+
+def validate(pre: str, post: str) -> list[tuple[str, list[str]]]:
+    """Return list of (carve_out_name, unified_diff_lines) per drifted category."""
+    failures: list[tuple[str, list[str]]] = []
+    for name, extractor in CHECKS:
+        pre_list = extractor(pre)
+        post_list = extractor(post)
+        if pre_list == post_list:
+            continue
+        diff = list(difflib.unified_diff(
+            [s + "\n" for s in pre_list],
+            [s + "\n" for s in post_list],
+            fromfile=f"pre/{name}",
+            tofile=f"post/{name}",
+            lineterm="",
+        ))
+        failures.append((name, diff))
+    return failures
+
+
+def _render(failures: list[tuple[str, list[str]]]) -> str:
+    out = ["caveman carve-out validator: DRIFT DETECTED", ""]
+    for name, diff in failures:
+        out.append(f"❌ carve-out `{name}` drifted:")
+        out.extend(diff)
+        out.append("")
+    return "\n".join(out)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    p.add_argument("pre", type=Path, help="Pre-compression reply file.")
+    p.add_argument("post", type=Path, help="Post-compression reply file.")
+    args = p.parse_args(argv)
+    if not args.pre.is_file():
+        print(f"pre file not found: {args.pre}", file=sys.stderr)
+        return 2
+    if not args.post.is_file():
+        print(f"post file not found: {args.post}", file=sys.stderr)
+        return 2
+    pre = args.pre.read_text(encoding="utf-8")
+    post = args.post.read_text(encoding="utf-8")
+    failures = validate(pre, post)
+    if failures:
+        print(_render(failures))
+        return 1
+    print("caveman carve-out validator: all carve-outs preserved ✅")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/validate_safe_paths.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Sensitive-path denylist — refuses files that almost certainly hold secrets or PII.
+
+Phase 0 of step-16-caveman-substance. Gates Phase 2 (`scripts/compress_memory.py`):
+any consumer-supplied path must pass `assert_safe()` before bytes are read or
+shipped to a third-party API.
+
+Ported from Caveman `plugins/caveman/skills/caveman-compress/scripts/compress.py`
+(upstream `63a91ec`). Adapted to repo conventions: explicit `SensitivePathError`,
+CLI entry point, no `anthropic` import.
+
+Public API:
+    is_sensitive(path: pathlib.Path) -> bool
+    assert_safe(path: pathlib.Path) -> None     # raises SensitivePathError
+
+CLI:
+    python3 scripts/validate_safe_paths.py <path>   # exit 0 = safe, 2 = sensitive
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+__all__ = ["SensitivePathError", "is_sensitive", "assert_safe"]
+
+
+class SensitivePathError(ValueError):
+    """Raised when a path matches the sensitive-file denylist."""
+
+
+# Filenames that almost certainly hold secrets or PII. Matched against the
+# basename only (case-insensitive). Compressing or shipping these to an LLM API
+# is a third-party data boundary developers on sensitive codebases cannot cross.
+SENSITIVE_BASENAME_REGEX = re.compile(
+    r"(?ix)^("
+    r"\.env(\..+)?"
+    r"|\.netrc"
+    r"|credentials(\..+)?"
+    r"|secrets?(\..+)?"
+    r"|passwords?(\..+)?"
+    r"|id_(rsa|dsa|ecdsa|ed25519)(\.pub)?"
+    r"|authorized_keys"
+    r"|known_hosts"
+    r"|.*\.(pem|key|p12|pfx|crt|cer|jks|keystore|asc|gpg)"
+    r")$"
+)
+
+# Path components (any segment, case-insensitive) that mark a sensitive
+# directory. Catches `~/.ssh/known_hosts` even when the basename slips past the
+# regex above.
+SENSITIVE_PATH_COMPONENTS = frozenset({".ssh", ".aws", ".gnupg", ".kube", ".docker"})
+
+# Substring tokens checked against the normalised basename (separators stripped
+# so `api-key`, `api_key`, `apikey` all match). Catches creative renames like
+# `prod-secret-token.txt` that bypass the explicit basename regex.
+SENSITIVE_NAME_TOKENS = (
+    "secret",
+    "credential",
+    "password",
+    "passwd",
+    "apikey",
+    "accesskey",
+    "token",
+    "privatekey",
+)
+
+_SEP_STRIP_RE = re.compile(r"[_\-\s.]")
+
+
+def is_sensitive(path: Path) -> bool:
+    """Return True if `path` matches the sensitive-file denylist."""
+    name = path.name
+    if SENSITIVE_BASENAME_REGEX.match(name):
+        return True
+    lowered_parts = {p.lower() for p in path.parts}
+    if lowered_parts & SENSITIVE_PATH_COMPONENTS:
+        return True
+    lower = _SEP_STRIP_RE.sub("", name.lower())
+    return any(tok in lower for tok in SENSITIVE_NAME_TOKENS)
+
+
+def assert_safe(path: Path) -> None:
+    """Raise `SensitivePathError` if `path` matches the denylist.
+
+    Intended as a hard guard at the top of any function that reads bytes from
+    a consumer-supplied path and ships them to a third-party API. Override is
+    intentional: the user must rename the file if the heuristic is wrong.
+    """
+    if is_sensitive(path):
+        raise SensitivePathError(
+            f"Refusing to operate on {path}: filename or path looks sensitive "
+            "(credentials, keys, secrets, or known private directories). "
+            "Rename the file if this is a false positive."
+        )
+
+
+def _main(argv: list[str]) -> int:
+    if len(argv) != 2 or argv[1] in ("-h", "--help"):
+        print(
+            "usage: validate_safe_paths.py <path>\n"
+            "  exit 0 — path is safe\n"
+            "  exit 2 — path matches the sensitive-file denylist",
+            file=sys.stderr,
+        )
+        return 0 if (len(argv) == 2 and argv[1] in ("-h", "--help")) else 2
+    target = Path(argv[1])
+    try:
+        assert_safe(target)
+    except SensitivePathError as exc:
+        print(f"SensitivePathError: {exc}", file=sys.stderr)
+        return 2
+    print(f"safe: {target}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(_main(sys.argv))