devrites 1.19.0

package/scripts/pin.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# scripts/pin.sh — manage user-pinned slash aliases for DevRites.
+#
+# Adopts the same "thin wrapper SKILL.md that delegates" pattern as install.sh
+# uses for --short-aliases=all, but exposes it as a runtime verb so users can
+# add / remove arbitrary aliases against any rite-*  skill without re-running
+# the installer.
+#
+# Usage:
+#   scripts/pin.sh add    <alias> <target>      # /alias → /target (target = rite-spec | rite-build | ...)
+#   scripts/pin.sh remove <alias>               # remove a previously-pinned alias
+#   scripts/pin.sh list                         # print currently-pinned aliases
+#   scripts/pin.sh --help
+#
+# Examples:
+#   ./scripts/pin.sh add b rite-build        # /b == /rite-build
+#   ./scripts/pin.sh add ship rite-seal      # /ship == /rite-seal
+#   ./scripts/pin.sh remove b
+#
+# Targets:
+#   - Default: $PWD (the installed project, which holds .claude/skills/).
+#   - --target <dir> to operate on a project elsewhere.
+#
+# Safety:
+#   - Refuses to write inside ~/.claude (DevRites is project-local only).
+#   - Refuses to overwrite a non-alias skill at .claude/skills/<alias>/.
+#   - Refuses if <target> is not a known rite-* skill in the target's pack.
+#   - Manifest-managed: pinned wrappers are recorded in .claude/devrites.manifest
+#     so the standard uninstall.sh cleans them up automatically.
+
+set -u
+
+# ---- locate install-lib + load helpers ----------------------------------
+SELF_DIR="$( cd "$(dirname "$0")" && pwd -P )"
+ROOT="$( cd "$SELF_DIR/.." && pwd -P )"
+LIB="$SELF_DIR/install-lib.sh"
+if [ ! -r "$LIB" ]; then
+  printf 'error: cannot find %s\n' "$LIB" >&2
+  exit 2
+fi
+# shellcheck source=scripts/install-lib.sh
+. "$LIB"
+
+# ---- parse args ----------------------------------------------------------
+TARGET="$PWD"
+SUBCMD=""
+ALIAS=""
+DEST=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --target) TARGET="$2"; shift 2 ;;
+    --target=*) TARGET="${1#*=}"; shift ;;
+    -h|--help)
+      sed -n '2,30p' "$0"; exit 0 ;;
+    add|remove|list)
+      SUBCMD="$1"; shift
+      [ "$SUBCMD" = "add" ]    && { ALIAS="${1:-}"; DEST="${2:-}"; shift 2 || true; }
+      [ "$SUBCMD" = "remove" ] && { ALIAS="${1:-}"; shift || true; }
+      ;;
+    *)
+      dr_die "unknown arg: $1 (try --help)" ;;
+  esac
+done
+
+[ -z "$SUBCMD" ] && dr_die "missing subcommand (add | remove | list)"
+
+TARGET="$(dr_abspath_dir "$TARGET")" || dr_die "target dir not found: $TARGET"
+dr_is_global_claude "$TARGET" && dr_die "refusing to operate on ~/.claude — DevRites is project-local only"
+
+SKILLS_DIR="$TARGET/.claude/skills"
+MF="$TARGET/$DR_MANIFEST_NAME"
+
+[ -d "$SKILLS_DIR" ] || dr_die "no .claude/skills at $TARGET — run install.sh first?"
+[ -f "$MF" ]         || dr_die "no manifest at $MF — run install.sh first?"
+
+# ---- helpers -------------------------------------------------------------
+valid_alias_name() {
+  # lowercase ASCII, digits, hyphens. No /, ., spaces. Not "rite" or "rite-*".
+  case "$1" in
+    ""|/*|*/*|*[!a-z0-9-]*) return 1 ;;
+    rite|rite-*) return 1 ;;
+  esac
+  return 0
+}
+
+is_known_target() {
+  # Target must be a rite-* skill present in the installed pack.
+  case "$1" in
+    rite-*) [ -f "$SKILLS_DIR/$1/SKILL.md" ] ;;
+    *) return 1 ;;
+  esac
+}
+
+is_pinned_alias() {
+  # Detect a wrapper we generated: SKILL.md description must contain "Alias of DevRites /<target>".
+  [ -f "$SKILLS_DIR/$1/SKILL.md" ] || return 1
+  grep -q 'description: Alias of DevRites /' "$SKILLS_DIR/$1/SKILL.md"
+}
+
+# ---- subcommands ---------------------------------------------------------
+do_add() {
+  valid_alias_name "$ALIAS"    || dr_die "invalid alias name '$ALIAS' (lowercase / digits / hyphens; not 'rite' or 'rite-*')"
+  is_known_target "$DEST"      || dr_die "unknown target '$DEST' — not a rite-* skill in $SKILLS_DIR"
+  [ "$ALIAS" = "$DEST" ]       && dr_die "alias and target are the same"
+
+  ALIAS_DIR="$SKILLS_DIR/$ALIAS"
+  ALIAS_FILE="$ALIAS_DIR/SKILL.md"
+  ALIAS_REL=".claude/skills/$ALIAS/SKILL.md"
+
+  if [ -e "$ALIAS_FILE" ]; then
+    if is_pinned_alias "$ALIAS"; then
+      dr_warn "already pinned: /$ALIAS — overwriting"
+    else
+      dr_die "$ALIAS_FILE exists and is NOT a pinned alias — refusing to overwrite"
+    fi
+  fi
+
+  mkdir -p "$ALIAS_DIR"
+  dr_gen_alias_wrapper "$ALIAS" "$DEST" "$ALIAS_FILE"
+
+  if ! dr_manifest_contains "$MF" "$ALIAS_REL"; then
+    printf '%s\n' "$ALIAS_REL" >> "$MF"
+  fi
+
+  dr_ok "pinned: /$ALIAS → /$DEST   ($ALIAS_FILE)"
+}
+
+do_remove() {
+  valid_alias_name "$ALIAS" || dr_die "invalid alias name '$ALIAS'"
+  ALIAS_DIR="$SKILLS_DIR/$ALIAS"
+  ALIAS_FILE="$ALIAS_DIR/SKILL.md"
+  ALIAS_REL=".claude/skills/$ALIAS/SKILL.md"
+
+  [ -f "$ALIAS_FILE" ]      || dr_die "no pinned alias at $ALIAS_FILE"
+  is_pinned_alias "$ALIAS"  || dr_die "$ALIAS_FILE exists but is not a pinned alias — refusing to remove"
+
+  rm -f "$ALIAS_FILE"
+  rmdir "$ALIAS_DIR" 2>/dev/null || true
+
+  # Drop the alias line from the manifest (preserve header + the rest)
+  TMP="$(mktemp)"
+  grep -Fvx "$ALIAS_REL" "$MF" > "$TMP" && mv "$TMP" "$MF"
+
+  dr_ok "unpinned: /$ALIAS"
+}
+
+do_list() {
+  found=0
+  for d in "$SKILLS_DIR"/*/; do
+    [ -d "$d" ] || continue
+    nm="$(basename "$d")"
+    if is_pinned_alias "$nm"; then
+      to="$(awk '/^description: Alias of DevRites \//{ sub(/.*Alias of DevRites \//,""); sub(/\..*/,""); print; exit }' "$d/SKILL.md")"
+      printf '  /%-20s → /%s\n' "$nm" "$to"
+      found=1
+    fi
+  done
+  [ "$found" -eq 0 ] && dr_say "(no pinned aliases at $TARGET)"
+}
+
+case "$SUBCMD" in
+  add)    [ -n "$ALIAS" ] && [ -n "$DEST" ] || dr_die "usage: pin.sh add <alias> <target>"; do_add ;;
+  remove) [ -n "$ALIAS" ]                   || dr_die "usage: pin.sh remove <alias>";     do_remove ;;
+  list)   do_list ;;
+  *)      dr_die "unknown subcommand: $SUBCMD" ;;
+esac

package/scripts/render-eval-summary.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Render a GitHub-Actions-flavored markdown table from an eval summary JSONL.
+
+Reads eval-summary.jsonl (one JSON object per line, written by
+`scripts/eval-runner.py --summary-file`) and prints a markdown table to
+stdout. Used by `.github/workflows/evals.yml` to populate the job summary.
+"""
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import sys
+
+
+def main() -> int:
+    path = pathlib.Path(sys.argv[1] if len(sys.argv) > 1 else "eval-summary.jsonl")
+    model = os.environ.get("DEVRITES_EVAL_MODEL", "claude-haiku-4-5-20251001")
+    if not path.is_file():
+        print(f"(no summary file found at {path})")
+        return 0
+    print(f"## DevRites trigger evals\n")
+    print(f"Model: `{model}`\n")
+    print("| Skill | Correct | Accuracy | FP | FN | Passed |")
+    print("|---|---|---|---|---|---|")
+    total_correct = total_n = total_fp = total_fn = 0
+    any_failed = False
+    for line in path.read_text(encoding="utf-8").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        r = json.loads(line)
+        tick = "✅" if r["passed"] else "❌"
+        if not r["passed"]:
+            any_failed = True
+        total_correct += r["correct"]
+        total_n += r["total"]
+        total_fp += r["false_positives"]
+        total_fn += r["false_negatives"]
+        print(f"| `{r['skill']}` | {r['correct']}/{r['total']} | {r['accuracy']:.0%} | {r['false_positives']} | {r['false_negatives']} | {tick} |")
+    if total_n:
+        overall = total_correct / total_n
+        print(f"| **overall** | **{total_correct}/{total_n}** | **{overall:.0%}** | **{total_fp}** | **{total_fn}** | {'✅' if not any_failed else '❌'} |")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/run-evals.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# scripts/run-evals.sh — validate the structure of DevRites trigger evals.
+#
+# Schema check + summary. Does NOT actually invoke Claude — full eval
+# execution requires CLAUDE_API_KEY and a `claude` CLI invocation that is
+# gated to the user, not CI. CI runs this script to enforce the shape and
+# catch broken JSON / missing skills / wrong query counts.
+#
+# Usage:
+#   scripts/run-evals.sh                      # validate every evals/*.json
+#   scripts/run-evals.sh evals/rite-spec.json # validate one file
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+EVALS_DIR="$ROOT/evals"
+EXPECTED_QUERIES=20
+
+if [[ $# -gt 0 ]]; then
+  FILES=("$@")
+else
+  if [[ ! -d "$EVALS_DIR" ]]; then
+    echo "No evals/ directory at $EVALS_DIR" >&2
+    exit 1
+  fi
+  FILES=()
+  while IFS= read -r f; do
+    [[ "$f" == */README.md ]] && continue
+    FILES+=("$f")
+  done < <(find "$EVALS_DIR" -type f -name '*.json' | sort)
+fi
+
+if [[ ${#FILES[@]} -eq 0 ]]; then
+  echo "No eval files found." >&2
+  exit 1
+fi
+
+# Need either python3 or jq for JSON parsing. Prefer python3 (already a
+# DevRites build dep).
+if command -v python3 >/dev/null 2>&1; then
+  PARSER="python3"
+elif command -v jq >/dev/null 2>&1; then
+  PARSER="jq"
+else
+  echo "Need python3 or jq to validate JSON." >&2
+  exit 1
+fi
+
+FAILED=0
+TOTAL=0
+
+for file in "${FILES[@]}"; do
+  TOTAL=$((TOTAL + 1))
+  printf '== %s ==\n' "$file"
+
+  if [[ "$PARSER" == "python3" ]]; then
+    OUT=$(python3 - "$file" <<'PY'
+import json, sys, pathlib
+path = pathlib.Path(sys.argv[1])
+try:
+    data = json.loads(path.read_text())
+except Exception as e:
+    print(f"INVALID JSON: {e}")
+    sys.exit(1)
+
+errors = []
+
+for key in ("skill", "description", "queries"):
+    if key not in data:
+        errors.append(f"missing top-level key: {key}")
+
+queries = data.get("queries", [])
+if not isinstance(queries, list):
+    errors.append("queries is not a list")
+elif len(queries) != 20:
+    errors.append(f"expected 20 queries, got {len(queries)}")
+
+trig = noTrig = 0
+for i, q in enumerate(queries):
+    if not isinstance(q, dict):
+        errors.append(f"query[{i}] not an object")
+        continue
+    for k in ("text", "expected", "rationale"):
+        if k not in q:
+            errors.append(f"query[{i}] missing key: {k}")
+    if q.get("expected") == "should_trigger":
+        trig += 1
+    elif q.get("expected") == "should_not_trigger":
+        noTrig += 1
+    else:
+        errors.append(f"query[{i}] invalid expected: {q.get('expected')!r}")
+
+if errors:
+    for e in errors:
+        print(f"  FAIL: {e}")
+    sys.exit(1)
+
+print(f"  skill: {data['skill']}")
+print(f"  queries: {len(queries)} (should_trigger={trig}, should_not_trigger={noTrig})")
+PY
+    )
+    rc=$?
+  else
+    OUT=$(jq -r '
+      if (.skill and .description and (.queries|type=="array")) then
+        if (.queries|length) == 20 then
+          "  skill: \(.skill)\n  queries: \(.queries|length) (should_trigger=\(.queries|map(select(.expected=="should_trigger"))|length), should_not_trigger=\(.queries|map(select(.expected=="should_not_trigger"))|length))"
+        else
+          "  FAIL: expected 20 queries, got \(.queries|length)"
+        end
+      else
+        "  FAIL: missing required keys"
+      end
+    ' "$file") || rc=1
+    rc=${rc:-0}
+  fi
+
+  printf '%s\n' "$OUT"
+  if [[ ${rc:-0} -ne 0 ]] || [[ "$OUT" == *"FAIL"* ]]; then
+    FAILED=$((FAILED + 1))
+  fi
+done
+
+echo
+printf 'Validated %d eval files; %d failed.\n' "$TOTAL" "$FAILED"
+
+if [[ $FAILED -gt 0 ]]; then
+  exit 1
+fi
+
+if [[ -z "${CLAUDE_API_KEY:-}" ]]; then
+  echo
+  echo "Note: CLAUDE_API_KEY is not set; ran schema validation only."
+  echo "To execute the evals against a live Claude model:"
+  echo "  pip install anthropic"
+  echo "  CLAUDE_API_KEY=sk-... python3 scripts/eval-runner.py evals/*.json"
+  echo "Override the model with DEVRITES_EVAL_MODEL=claude-... ."
+  exit 0
+fi
+
+# Live execution path — runs each eval against a real Claude model.
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "error: CLAUDE_API_KEY is set but python3 is required for the live runner." >&2
+  exit 1
+fi
+
+echo
+echo "CLAUDE_API_KEY set — executing live trigger evals via scripts/eval-runner.py …"
+exec python3 "$ROOT/scripts/eval-runner.py" "${FILES[@]}"

package/scripts/run-outcome-evals.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Outcome-eval harness — proves the deterministic feature grader BOTH passes a
+# known-shippable workspace AND fails a known-blocked one (see-it-fail-first:
+# a grader that never returns NO-GO proves nothing). Runs in CI; no API key.
+#
+# Usage: run-outcome-evals.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+GRADER="$ROOT/scripts/grade-feature.sh"
+good="$ROOT/evals/golden/shippable-feature"
+bad="$ROOT/evals/golden/blocked-feature"
+nearmiss="$ROOT/evals/golden/near-miss-unproven-ac"
+fail=0
+
+echo "== grade golden/shippable-feature (expect GO) =="
+if bash "$GRADER" "$good"; then
+  echo "  PASS — graded GO"
+else
+  echo "  FAIL — a known-shippable workspace should grade GO"; fail=1
+fi
+
+echo
+echo "== grade golden/blocked-feature (expect NO-GO) =="
+if bash "$GRADER" "$bad"; then
+  echo "  FAIL — a known-blocked workspace should NOT grade GO"; fail=1
+else
+  echo "  PASS — correctly graded NO-GO"
+fi
+
+echo
+echo "== grade golden/near-miss-unproven-ac (expect NO-GO on ONE invariant) =="
+# Isolates invariant 2 (every acceptance criterion proven): identical to the
+# shippable fixture except a single AC is left unchecked. Proves that gate fails
+# independently — not only when six invariants trip at once.
+if bash "$GRADER" "$nearmiss"; then
+  echo "  FAIL — an unproven acceptance criterion must grade NO-GO"; fail=1
+else
+  echo "  PASS — correctly graded NO-GO on the lone unchecked AC"
+fi
+
+echo
+if [ "$fail" -eq 0 ]; then
+  echo "Outcome evals passed."
+else
+  echo "Outcome evals FAILED."
+fi
+exit "$fail"

package/scripts/scan-pack-security.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""Scan the shipped DevRites pack for prompt-injection and hidden-unicode risks.
+
+DevRites ships executable instruction files (skills, agents, rules, hooks) into
+other people's projects. A poisoned or invisibly-altered file is a supply-chain
+vulnerability, not a style nit (cf. the Snyk Feb-2026 "ToxicSkills" study: 36%
+of public skills carried prompt injection). This is the BLOCKING gate that keeps
+such a file from ever being released.
+
+Usage: scan-pack-security.py PATH [PATH ...]
+  PATH may be a file or a directory (directories are walked for text files).
+Exits non-zero if any finding is reported.
+
+Two finding classes:
+
+  1. Hidden unicode (always a finding — no legitimate reason to exist in a
+     Markdown/shell instruction file): bidi controls, zero-width characters,
+     other invisibles, and homoglyph confusables (a word that mixes ASCII with
+     look-alike Cyrillic/Greek letters).
+
+  2. Prompt-injection patterns (a finding unless explicitly suppressed): the
+     "ignore previous instructions" family, system-prompt overrides, tool /
+     permission escalation, and data-exfiltration phrasing.
+
+Suppression (for DevRites' own files that legitimately *discuss* injection
+defensively — e.g. security.md, the reviewer agents): put a marker on the same
+line OR anywhere in the file:
+
+    ... ignore previous instructions ...   <!-- pack-scan-ignore: defensive doc -->
+
+A whole file can opt a class out with a top-of-file marker:
+
+    <!-- pack-scan-ignore-file: injection -->
+
+Suppressions live in the file, so every exception is visible in the diff and
+reviewable — consistent with DevRites' "no silent state" thesis. Hidden-unicode
+findings can be suppressed the same way but should essentially never be.
+"""
+import os
+import re
+import sys
+import unicodedata
+
+# --- hidden unicode -------------------------------------------------------
+
+# Invisible / formatting code points with no business in an instruction file.
+ZERO_WIDTH = {
+    0x200B,  # zero width space
+    0x200C,  # zero width non-joiner
+    0x200D,  # zero width joiner
+    0x2060,  # word joiner
+    0xFEFF,  # zero width no-break space / BOM (mid-file)
+    0x180E,  # mongolian vowel separator
+    0x00AD,  # soft hyphen
+}
+BIDI_CONTROLS = {
+    0x202A, 0x202B, 0x202C, 0x202D, 0x202E,  # LRE RLE PDF LRO RLO
+    0x2066, 0x2067, 0x2068, 0x2069,          # LRI RLI FSI PDI
+    0x200E, 0x200F,                          # LRM RLM
+}
+HIDDEN = ZERO_WIDTH | BIDI_CONTROLS
+
+# Scripts whose letters are commonly used as ASCII look-alikes.
+CONFUSABLE_SCRIPTS = ("CYRILLIC", "GREEK")
+
+
+def _char_script(ch):
+    try:
+        return unicodedata.name(ch).split(" ")[0]
+    except ValueError:
+        return ""
+
+
+def find_hidden_unicode(text):
+    """Yield (line_no, col, label) for hidden code points and homoglyph words."""
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        for col, ch in enumerate(line, start=1):
+            cp = ord(ch)
+            if cp == 0xFEFF and lineno == 1 and col == 1:
+                continue  # a leading BOM is legal; only mid-file ZWNBSP is suspect
+            if cp in HIDDEN:
+                yield lineno, col, "hidden char U+%04X (%s)" % (cp, _hidden_name(cp))
+        # Homoglyph: a token mixing ASCII letters with confusable-script letters.
+        for m in re.finditer(r"\S+", line):
+            tok = m.group(0)
+            has_ascii_alpha = any(("a" <= c.lower() <= "z") for c in tok)
+            mixed = [c for c in tok if c.isalpha() and _char_script(c) in CONFUSABLE_SCRIPTS]
+            if has_ascii_alpha and mixed:
+                yield lineno, m.start() + 1, (
+                    "homoglyph: ASCII word mixes %s look-alike(s) %r" % (
+                        _char_script(mixed[0]).title(), "".join(sorted(set(mixed)))))
+
+
+def _hidden_name(cp):
+    try:
+        return unicodedata.name(chr(cp))
+    except ValueError:
+        return "unnamed"
+
+
+# --- prompt-injection patterns -------------------------------------------
+
+# Each: (label, compiled regex). Kept high-signal to limit false positives on
+# legitimate prose; defensive discussion is handled via suppression markers.
+# Gaps use '.' (any non-newline char): scanning is per-line, so a match can't
+# cross lines, and excluding periods would miss tokens like ".env" / ".ssh".
+_INJECTION = [
+    ("ignore-previous-instructions",
+     r"\b(ignore|disregard|forget)\b.{0,40}\b(previous|prior|above|earlier|all)\b"
+     r".{0,20}\b(instruction|instructions|prompt|prompts|direction|directions|context)\b"),
+    ("system-prompt-override",
+     r"\b(you are now|act as|pretend to be|new instructions\s*:|override (your|the) (system|prompt|rules))"),
+    ("permission-escalation",
+     r"\b(bypass|ignore|disable|skip)\b.{0,30}\b(approval|permission|permissions|guardrail|guardrails|safety|sandbox|restriction|restrictions)\b"),
+    ("data-exfiltration",
+     r"\b(exfiltrat\w+|send|post|upload|leak|curl|wget)\b.{0,40}\b(env|environment|secret|secrets|credential|credentials|token|tokens|api[_-]?key|\.ssh|private key)\b"),
+]
+INJECTION = [(label, re.compile(rx, re.IGNORECASE)) for label, rx in _INJECTION]
+
+
+def find_injection(text, file_suppressed):
+    """Yield (line_no, label, excerpt) for injection patterns, honoring suppression."""
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        if _line_suppressed(line):
+            continue
+        for label, rx in INJECTION:
+            if "injection" in file_suppressed:
+                break
+            m = rx.search(line)
+            if m:
+                yield lineno, label, line.strip()[:120]
+
+
+_LINE_SUPPRESS = re.compile(r"pack-scan-ignore\b(?!-file)", re.IGNORECASE)
+# Class list is word/comma/space only — a trailing "-->" comment closer must not
+# get swallowed into the captured class name.
+_FILE_SUPPRESS = re.compile(r"pack-scan-ignore-file\s*:\s*([\w, ]+)", re.IGNORECASE)
+
+
+def _line_suppressed(line):
+    return bool(_LINE_SUPPRESS.search(line))
+
+
+def _file_suppressions(text):
+    classes = set()
+    for m in _FILE_SUPPRESS.finditer(text):
+        for c in m.group(1).split(","):
+            classes.add(c.strip().lower())
+    return classes
+
+
+# --- driver ---------------------------------------------------------------
+
+TEXT_EXTS = {".md", ".sh", ".json", ".txt", ".py", ".js", ".yaml", ".yml", ""}
+
+
+def iter_files(paths):
+    for p in paths:
+        if os.path.isdir(p):
+            for root, _dirs, names in os.walk(p):
+                for n in sorted(names):
+                    fp = os.path.join(root, n)
+                    ext = os.path.splitext(n)[1].lower()
+                    if ext in TEXT_EXTS:
+                        yield fp
+        else:
+            yield p
+
+
+def scan(paths):
+    """Return a list of finding strings. Empty list == clean."""
+    findings = []
+    for path in iter_files(paths):
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                text = fh.read()
+        except (OSError, UnicodeDecodeError) as e:
+            findings.append("ERROR %s: cannot read as utf-8 (%s)" % (path, e))
+            continue
+        file_sup = _file_suppressions(text)
+        hidden_off = ("unicode" in file_sup) or ("hidden" in file_sup)
+        if not hidden_off:
+            for lineno, col, label in find_hidden_unicode(text):
+                if _line_suppressed(text.splitlines()[lineno - 1]):
+                    continue
+                findings.append("FINDING %s:%d:%d: %s" % (path, lineno, col, label))
+        for lineno, label, excerpt in find_injection(text, file_sup):
+            findings.append("FINDING %s:%d: injection/%s: %s" % (path, lineno, label, excerpt))
+    return findings
+
+
+def main(argv):
+    paths = argv[1:]
+    if not paths:
+        print("usage: scan-pack-security.py PATH [PATH ...]", file=sys.stderr)
+        return 2
+    findings = scan(paths)
+    if findings:
+        for f in findings:
+            print(f)
+        print("\n%d security finding(s). Fix, or add an auditable "
+              "pack-scan-ignore marker if this is defensive content." % len(findings))
+        return 1
+    print("OK    pack security scan clean (%s)" % ", ".join(paths))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))