vouchington-tooling 0.27.0 → 0.29.0

package/README.md

@@ -80,6 +80,7 @@ vouchington install-playwright-chromium-arm64
 vouchington ghcr-package-retention example%2Fapi
 vouchington harness-admission-lane 4
 vouchington harness-assert-gates HARNESS_DISPATCH_ENABLED HARNESS_SHEPHERD_ENABLED
+echo '[{"login":"octocat","type":"User"}]' | vouchington gha-collaborator-trust owner/repo --allow-bot github-actions[bot]
 vouchington nuget-central-version trusted.props candidate.props metadata.json out.props
 vouchington swift-semantic-equal BASE HEAD App.swift
 vouchington post-review

package/dist/cli/index.mjs

@@ -73,6 +73,10 @@ const SCRIPT_PATHS = {
         path: 'scripts/gha/harness-admission-lane.sh',
     },
     'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
+    'gha-collaborator-trust': {
+        command: 'bash',
+        path: 'scripts/gha/gha-collaborator-trust.sh',
+    },
 };
 export function runCli(argv = process.argv) {
     const parsed = parseCli(argv);

package/dist/cli/parse.d.mts

@@ -89,7 +89,7 @@ export type ParsedCli = {
     workflowDirectories?: string[];
     actionDirectories?: string[];
 } | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup;
-export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'harness-assert-gates';
+export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'harness-assert-gates' | 'gha-collaborator-trust';
 export declare function parseCli(argv: readonly string[]): ParsedCli;
 export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
     kind: 'command-help';

package/dist/cli/parse.mjs

@@ -25,6 +25,7 @@ const SCRIPT_COMMANDS = new Set([
     'ghcr-package-retention',
     'harness-admission-lane',
     'harness-assert-gates',
+    'gha-collaborator-trust',
 ]);
 export function parseCli(argv) {
     const args = argv.slice(2);

package/dist/cli/usage.d.mts

@@ -1,4 +1,4 @@
-export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal flush --outbox-directory PATH\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, snapshot_export, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
+export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n  runner-port-policy   Print or validate a runner port policy\n  with-host-lock       Run a command under a host-wide lock\n  agent-harness-config          Apply classifier-auto + sandbox keys to agent harnesses\n  gha-runtime-audit             Audit successful GitHub Actions job runtimes\n  require-up-to-date            Require HEAD to include a fetched remote branch\n  gitleaks-directory-scan       Scan a directory with Gitleaks\n  ast-grep-examples             Run AST-grep rule examples\n  ast-grep-pack                 Print shipped unconditional AST-grep pack paths as JSON\n  gha-workspace-policy          Check GitHub Actions workspace safety policy\n  gha-output                    Write a collision-safe multiline GITHUB_OUTPUT record\n  gha-needs-results             Fail if required GitHub Actions job results failed\n  download-with-diagnostics     Download a URL and report HTTP status on failure\n  download-optional-run-artifacts  Download optional artifacts from the current run\n  host-pressure-diagnostics     Print a bounded host memory/OOM/PSI snapshot\n  allocate-browser-safe-ports   Allocate Fetch-safe localhost ports\n  diagnose-port-collision       Capture bounded localhost port diagnostics\n  prepare-trivy-db              Download the Trivy vulnerability database\n  gha-artifacts-cleanup         Delete classified GitHub Actions artifacts\n  http-origin                   Validate an optional HTTP(S) origin\n  vitest-blob-manifest          Stamp a vitest-blob-manifest:v1 identity file\n  vitest-report-attempt         Write or read a Vitest report-attempt marker\n  prepare-vitest-reports        Validate and select Vitest report JSON files\n  pnpm-install                  Install a pnpm workspace with retry and release-age fail-fast\n  check-cache-size              Measure a path and decide whether to save a GHA cache\n  make-shard-matrix             Emit a [1..N] GitHub Actions shard matrix\n  load-runner-env               Overlay a runner env file onto GITHUB_ENV with injection guards\n  clean-workspace               Reset a persistent-runner workspace with a fork-PR trust gate\n  install-github-release        Download a checksum-verified GitHub Release binary\n  run-with-timeout              Run a command with GNU timeout or a Perl fallback\n  lint-links                    Two-pass lychee: internal links fail, external warn\n  materialize-pr-context        Dump PR title/body/files/diff/comments and #N crawl\n  wait-for-apt-locks            Wait until apt/dpkg lock files are free\n  install-playwright-chromium-arm64  Install Playwright Chromium from browsers.json\n  ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN\n  harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n  harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled\n  gha-collaborator-trust        Classify authors as write-access collaborators or not\n  nuget-central-version         Validate a Directory.Packages.props PackageVersion delta\n  swift-semantic-equal          Compare Swift sources ignoring comments and whitespace\n  post-review                   Post one COMMENT review from a staged payload file\n  stage-review-payload          Validate a review payload file into a staging directory\n  retrospective-transcript      Format facts from Claude-compatible, Codex, or Grok transcripts\n  link-skill                    Link one packaged skill into an explicit consumer directory\n  retrospective-facts           Gather immutable facts for a retrospective\n  agent-blackboard              Probe and journal an Agent Blackboard deployment\n  mcp                           Serve the agent-blackboard journal tools over stdio (MCP)\n\nOptions:\n  -h, --help       Show this help\n  -v, --version    Print the package version\n\nrunner-port-policy\n  (no args)              Print the shipped policy as JSON\n  --file <path>          Validate and print a policy file\n  --reserved <port>      Print true if the port is reserved\n\nwith-host-lock\n  --name <family>\n  [--slots <n>]\n  --timeout-seconds <n>\n  [--command-timeout-seconds <n>]\n  [--failure-diagnostics <absolute-script>]\n  [--on-acquire-timeout fail|run-unlocked]\n  -- <command> [args...]\n\nagent-harness-config dump\nagent-harness-config check|apply [--global] [--repo PATH]... [--harness claude|codex|grok|cursor]...\n  [--home PATH]\n\ngha-runtime-audit\n  [--repository owner/name]   Default GITHUB_REPOSITORY\n  [--branch main]\n  [--median-threshold-floor <seconds>]    Off unless set. Must be below the ceiling\n  [--median-threshold-ceiling <seconds>]  Default 360. Flags a five-sample median above this\n  --pr-workflow <name|/regex/>     Repeatable\n  --push-workflow <name|/regex/>   Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention <url-encoded-package>...\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir>  Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard journal append --mode interactive|autonomous --source-event-id ID --work-outcome OUTCOME --coverage-status STATUS --session-id UUID --agent NAME --version VERSION --file PATH --repository OWNER/NAME [--repository OWNER/NAME ...] [--parent-session-id UUID] [--timestamp ISO8601] [--coverage-source SOURCE,...] [--dropped-count N] [--outbox-directory PATH]\nagent-blackboard journal entries --session-id UUID\nagent-blackboard journal flush --outbox-directory PATH\nInteractive journal append requires --outbox-directory PATH.\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n  (no args)              Serve journal_append, journal_entries, outbox_status, outbox_flush,\n                         session_ensure, snapshot_export, and session_archive over stdio.\n                         Needs the optional @modelcontextprotocol/sdk peer (and zod).\n                         Launch it from inside the repository's git worktree.\n";
 export declare function printUsage(stream?: NodeJS.WritableStream): void;
 export declare function commandNames(usage?: string): string[];
 export declare function commandUsage(command: string, usage?: string): string;

package/dist/cli/usage.mjs

@@ -37,6 +37,7 @@ Commands:
   ghcr-package-retention        Delete old GHCR package versions past KEEP_MIN
   harness-admission-lane        Compute a GITHUB_RUN_ID admission lane for fleet fan-out
   harness-assert-gates          Fail if any named HARNESS_*_ENABLED gate is enabled
+  gha-collaborator-trust        Classify authors as write-access collaborators or not
   nuget-central-version         Validate a Directory.Packages.props PackageVersion delta
   swift-semantic-equal          Compare Swift sources ignoring comments and whitespace
   post-review                   Post one COMMENT review from a staged payload file
@@ -111,6 +112,7 @@ install-playwright-chromium-arm64 [name:archive...]
 ghcr-package-retention <url-encoded-package>...
 harness-admission-lane <lanes>
 harness-assert-gates <gate>...
+gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
 nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
 swift-semantic-equal <base> <head> <file.swift>
 post-review

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -346,8 +346,8 @@
   "dependencies": {
     "@types/mdast": "4.0.4",
     "@types/unist": "3.0.3",
-    "csv-parse": "7.0.2",
-    "csv-stringify": "6.8.3",
+    "csv-parse": "7.0.3",
+    "csv-stringify": "6.9.0",
     "dockerfile-ast": "0.7.1",
     "picomatch": "4.0.7",
     "remark": "15.0.1",

package/scripts/gha/gha-collaborator-trust.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# Classify GitHub authors by their live permission on one repository.
+#
+# usage:  gha-collaborator-trust.sh <owner/repo> [--allow-bot <login>]... < authors.json
+# stdin:  JSON array of {"login": string, "type": string} (GitHub user objects work as-is).
+# stdout: {"trusted": [login...], "untrusted": [login...]}, each sorted and deduplicated.
+#
+# A user is trusted when the legacy `permission` field is admin or write (maintain maps to
+# write). A GitHub App bot (type "Bot") is trusted only when its login is passed with
+# --allow-bot, because an app with only issue or pull-request write access can still comment.
+# A definitive 404 means no permission. Any other lookup failure exits non-zero so callers
+# fail closed.
+set -euo pipefail
+
+usage() {
+  echo "usage: gha-collaborator-trust.sh <owner/repo> [--allow-bot <login>]... < authors.json" >&2
+  exit 2
+}
+
+[ "$#" -ge 1 ] || usage
+repository="$1"
+shift
+[[ "$repository" =~ ^[A-Za-z0-9_-][A-Za-z0-9_.-]*/[A-Za-z0-9_-][A-Za-z0-9_.-]*$ ]] || usage
+
+allowed_bots=$'\n'
+while [ "$#" -gt 0 ]; do
+  if [ "$1" != "--allow-bot" ] || [ "$#" -lt 2 ] || ! [[ "$2" =~ ^[A-Za-z0-9-]+\[bot\]$ ]]; then
+    usage
+  fi
+  allowed_bots+="$2"$'\n'
+  shift 2
+done
+
+input="$(cat)"
+if ! jq -e '
+  type == "array" and all(.[];
+    type == "object"
+    and (.login | type) == "string" and (.login | length) > 0
+    and ((.type | type) == "string" or .type == null))' >/dev/null 2>&1 <<<"$input"; then
+  echo "::error::gha-collaborator-trust: stdin must be a JSON array of {login, type}" >&2
+  exit 2
+fi
+rows="$(jq -r 'unique_by(.login) | .[] | [.login, (.type // "")] | @tsv' <<<"$input")"
+
+results="$(mktemp)"
+errors="$(mktemp)"
+trap 'rm -f "$results" "$errors"' EXIT
+
+while IFS=$'\t' read -r login type; do
+  [ -n "$login" ] || continue
+  verdict=untrusted
+  if [ "$type" = "Bot" ]; then
+    if [[ "$allowed_bots" == *$'\n'"$login"$'\n'* ]]; then
+      verdict=trusted
+    fi
+  elif [[ "$login" =~ ^[A-Za-z0-9-]+$ ]]; then
+    if permission="$(gh api "repos/$repository/collaborators/$login/permission" --jq '.permission' 2>"$errors")"; then
+      case "$permission" in
+        admin | write) verdict=trusted ;;
+      esac
+    elif ! grep -q 'HTTP 404' "$errors"; then
+      cat "$errors" >&2
+      echo "::error::gha-collaborator-trust: permission lookup failed for $login" >&2
+      exit 1
+    fi
+  fi
+  printf '%s\t%s\n' "$verdict" "$login" >>"$results"
+done <<<"$rows"
+
+jq -Rn '
+  [inputs | split("\t")] as $rows
+  | {
+      trusted: [$rows[] | select(.[0] == "trusted") | .[1]] | sort,
+      untrusted: [$rows[] | select(.[0] == "untrusted") | .[1]] | sort
+    }' <"$results"

package/skills/bounded-iteration/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: bounded-iteration
+description: Bound the rows each run reads when writing or reviewing scheduled jobs, reconcilers, cleanups, dispatchers, backfills, exports, list endpoints, or any loop that reads rows.
+---
+
+# Bounded iteration
+
+Read applicable `AGENTS.md` and the repository's local database adapter when present.
+Local policy overrides these portable conventions.
+
+A run's cost is the rows it reads and the work it starts, not the memory it holds. Read
+[sweep patterns](references/sweep-patterns.md) for worked SQL and loop shapes.
+
+1. **Choose work, not entities.** Read only rows that need work, through a predicate an index
+   serves: a work-item or dirty-marker row, a parent id, a due timestamp with a partial index, or
+   a time or UUIDv7 window past a high-water mark. Column-to-column comparisons, `OR` of unrelated
+   conditions, and `EXISTS` as the only condition are not filters. (`postgres-required-predicates`)
+2. **Cap every run.** Every loop has a per-run cap (batches, rows, or a deadline), reports whether
+   work remains, and resumes from a persisted position. Never loop until empty, and never default
+   a cap to infinity.
+3. **Bound every statement.** A SELECT, UPDATE, or DELETE that can touch many rows has a `LIMIT`.
+   For writes the `LIMIT` goes in a CTE, with `FOR UPDATE SKIP LOCKED` when workers compete.
+   (`postgres-lock-ordering`)
+4. **A stream is not a bound.** A cursor or stream bounds memory, not work. Cap the rows streamed
+   per run.
+5. **Resume without restarting.** Keep a keyset position on the UUIDv7 key or a
+   `<verb>_through_at` time position, fix the sweep's end when it starts, and rescan an overlap
+   when insert order differs from commit order. Cursor tables follow
+   [table shapes](../postgres-schema-design/references/table-shapes.md).
+   (`postgres-generated-column-predicates`)
+6. **No unbounded fan-out.** Use `Promise.all` only over a bounded result, with bounded
+   concurrency.
+7. **Keyset pagination.** No `OFFSET`. Clamp the client's page size on the server. The API schema
+   keeps a static ceiling; the default and the effective maximum are runtime-tunable but never
+   above it. (`postgres-no-offset`)
+8. **Tunables are runtime configuration.** Batch sizes, page sizes, caps, and windows come from
+   the consumer's runtime configuration with a validated default and a hard maximum, and are bound
+   as SQL parameters. `LIMIT 1` and an external API's page maximum are contracts, not tunables.
+9. **Work that needs every key** (rebuilding a membership filter, a reindex) keeps derived state
+   current on write. A full pass is an explicit, capped, resumable backfill, not a scheduled pass
+   over everything.
+10. **Verify with a plan.** EXPLAIN at representative cardinality shows no Seq Scan on an
+    unbounded table, and an index that supplies the `ORDER BY`, so the scan stops at the
+    `LIMIT` instead of reading and sorting every match.
+
+For work-item, lease, and cursor tables, read [postgres-schema-design](../postgres-schema-design/SKILL.md).
+For query shape and streaming, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
+For UUIDv7 windows and pruning, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
+Names in parentheses are generic `jonathanong/no-mistakes` rules; check that the installed release
+has one before relying on it. No generic rule checks run caps, streams, or fan-out.
+Consumer policy owns run caps, tunable names and ceilings, schedules, and enforcement configuration.

package/skills/bounded-iteration/references/sweep-patterns.md

@@ -0,0 +1,342 @@
+# Sweep patterns
+
+Synthetic examples for [bounded iteration](../SKILL.md). `db.query` stands for the consumer's
+executor and `config` for its runtime configuration; every cap in SQL is a bound parameter.
+`min_uuidv7(timestamptz)` stands for the consumer's helper that returns the smallest UUIDv7 for a
+timestamp, like the lower-bound helper in
+[performance patterns](../../postgres-node-performance-tuning/references/performance-patterns.md).
+Comments on tables and columns are omitted for space.
+
+## Due timestamp, partial index, capped claim
+
+A work-item row exists only while work is pending, so the index covers only rows a claim can pick:
+
+```sql
+CREATE INDEX idx_invoice_delivery_work_items__available_at
+  ON invoice_delivery_work_items (available_at, id)
+  WHERE completed_at IS NULL;
+```
+
+One claim takes at most `$1` due rows. Competing workers skip rows another worker holds, and the
+lease moves `available_at` to its expiry, so an abandoned claim is due again through the same index
+without an `OR` in the predicate:
+
+```sql
+WITH due AS (
+  SELECT id
+  FROM invoice_delivery_work_items
+  WHERE completed_at IS NULL AND available_at <= now()
+  ORDER BY available_at, id
+  LIMIT $1
+  FOR UPDATE SKIP LOCKED
+)
+UPDATE invoice_delivery_work_items AS item
+SET lease_token = gen_random_uuid(),
+    leased_at = now(),
+    lease_expires_at = now() + $2::interval,
+    available_at = now() + $2::interval,
+    attempt_count = item.attempt_count + 1
+FROM due
+WHERE item.id = due.id
+RETURNING item.id, item.invoice_id, item.lease_token;
+```
+
+Renewal moves `lease_expires_at` and `available_at` to the same new deadline, so a renewed lease
+is not due. Renewal, completion, and failure all add `AND lease_token = $mine`; see
+[table shapes](../../postgres-schema-design/references/table-shapes.md).
+
+## Dirty marker or work item
+
+Do not walk every order to find the few that need reconciling. The writer that changes an order
+marks it in the same transaction, and the reconciler claims only marks, as above:
+
+```sql
+CREATE TABLE order_reconcile_work_items (
+  id uuid PRIMARY KEY DEFAULT uuidv7(),
+  order_id uuid NOT NULL UNIQUE REFERENCES orders (id) ON DELETE CASCADE,
+  available_at timestamptz NOT NULL DEFAULT now(),
+  lease_token uuid,
+  leased_at timestamptz,
+  lease_expires_at timestamptz,
+  attempt_count integer NOT NULL DEFAULT 0,
+  generation integer NOT NULL DEFAULT 0,
+  completed_at timestamptz
+);
+
+INSERT INTO order_reconcile_work_items (order_id)
+VALUES ($1)
+ON CONFLICT (order_id) DO UPDATE
+SET available_at = GREATEST(order_reconcile_work_items.available_at, now()),
+    completed_at = NULL,
+    generation = order_reconcile_work_items.generation + 1;
+```
+
+The claim above applies with `order_id` for `invoice_id`, and its `RETURNING` also includes
+`generation`, so `$claimed` is captured in the same statement as the lease. Completion adds
+`AND generation = $claimed`. A re-mark never makes a leased row due early, since
+the claim moved `available_at` to the lease expiry. A completion that finds a newer generation
+releases the lease with `available_at = now()`, and the next claim takes the row again. Run cost
+follows the number of changes, not the number of orders. A job fanned out per account reads by
+parent id, `WHERE account_id = $1`, for the one account it was started for.
+
+## High-water-mark window with an overlap
+
+An export reads `invoices` added since the last sweep. The cursor row holds the position and the
+sweep's fixed end, and the job seeds its own row:
+
+```sql
+CREATE TABLE invoice_export_cursors (
+  is_singleton boolean PRIMARY KEY DEFAULT true CHECK (is_singleton),
+  cursor_invoice_id uuid,
+  sweep_upper_bound_invoice_id uuid
+);
+
+INSERT INTO invoice_export_cursors DEFAULT VALUES ON CONFLICT DO NOTHING;
+```
+
+A UUIDv7 is assigned at insert, not commit, so a row below the last sweep's end can commit after
+that sweep passed it. A new sweep starts an overlap before the previous end and fixes its own end
+now, only when the previous sweep reached its end. `$1` is the overlap, and NULL means the start,
+so the first sweep begins at the start. The overlap must exceed the longest insert-to-commit
+delay, which the consumer enforces, for example with a transaction timeout; a row that commits
+after the overlap has passed is missed for good. Work that cannot tolerate a miss writes a
+work-item row in the same transaction instead:
+
+```sql
+UPDATE invoice_export_cursors
+SET cursor_invoice_id =
+      min_uuidv7(uuid_extract_timestamp(sweep_upper_bound_invoice_id) - $1::interval),
+    sweep_upper_bound_invoice_id = min_uuidv7(now())
+WHERE is_singleton
+  AND cursor_invoice_id IS NOT DISTINCT FROM sweep_upper_bound_invoice_id;
+```
+
+Each batch moves strictly forward inside the sweep, where `$1` is the cursor (the nil UUID for the
+start), `$2` the sweep's end, and `$3` the batch size:
+
+```sql
+SELECT id, account_id, total_cents
+FROM invoices
+WHERE id > $1 AND id <= $2
+ORDER BY id
+LIMIT $3;
+```
+
+Persist the last `id` as the cursor after each batch with a compare-and-set, so a stale or
+overlapping worker cannot move the position backward or into another sweep. `$1` is the new
+position, `$2` the cursor this batch started from (NULL at the start), and `$3` the sweep's end.
+Zero updated rows means another worker moved on, so the run stops:
+
+```sql
+UPDATE invoice_export_cursors
+SET cursor_invoice_id = $1
+WHERE is_singleton
+  AND cursor_invoice_id IS NOT DISTINCT FROM $2::uuid
+  AND sweep_upper_bound_invoice_id = $3;
+```
+
+A short batch ends the sweep: set the cursor to the sweep's end the same way, and the next run
+starts a new sweep. Rows in the overlap are read twice, so the export must be idempotent.
+
+A time position works the same way on a column the database sets at insert, such as
+`received_at timestamptz NOT NULL DEFAULT clock_timestamp()`, with the same overlap rule. Never use a business
+time such as `occurred_at`: a late-arriving row carries an old timestamp and falls behind every
+later window. Avoid `now()` too, because it records the transaction's start, not the insert. Fix the window's end when the window opens, keep a composite `(time, id)` keyset
+position inside it, and read
+`WHERE (received_at, id) > ($1, $2) AND received_at <= $3 ORDER BY received_at, id`, where `$3` is
+the window's end. Rows that share a timestamp are neither skipped nor repeated, and new arrivals
+wait for the next window. Advance `<verb>_through_at` to the window's end only after the window is
+drained, and start the next window an overlap earlier.
+
+## Capped batch loop with `hasMore`
+
+The run stops at a batch cap or a deadline and says whether work remains. A short batch is the
+only proof that nothing is left. Rows a `SKIP LOCKED` claim passed over are held by another
+claimer, who owns them; if that claim rolls back, they are due again on the next scheduled run,
+so a short batch still ends this run's backlog. A cap that stops the run reports
+`hasMore: true`, even when the last batch happened to drain the work; the continuation finds
+nothing and stops:
+
+```ts
+interface RunResult {
+  processed: number
+  hasMore: boolean
+}
+
+export async function runOrderReconcile(config: ReconcileConfig): Promise<RunResult> {
+  const deadline = Date.now() + config.runDeadlineMs
+  let processed = 0
+  for (let batch = 0; batch < config.maxBatchesPerRun; batch += 1) {
+    if (Date.now() >= deadline) return { processed, hasMore: true }
+    const items = await claimDueItems(config.batchSize, config.leaseInterval)
+    await reconcileOrders(items)
+    processed += items.length
+    if (items.length < config.batchSize) return { processed, hasMore: false }
+  }
+  return { processed, hasMore: true }
+}
+
+export async function orderReconcileJob(config: ReconcileConfig): Promise<void> {
+  const { hasMore } = await runOrderReconcile(config)
+  if (hasMore) await enqueueContinuation('order-reconcile')
+}
+```
+
+The persisted position is the work-item table itself: claimed and completed rows leave the due
+set. A cursor sweep persists its position after each batch. The job asks for a continuation
+instead of looping on.
+
+## Tunables
+
+Read each cap from runtime configuration with a validated default and a hard maximum. A bad value
+fails at startup, and no cap is unset or infinite:
+
+```ts
+interface Bound {
+  default: number
+  max: number
+}
+
+export function readBound(name: string, raw: string | undefined, bound: Bound): number {
+  const value = raw === undefined ? bound.default : Number(raw)
+  if (!Number.isInteger(value) || value < 1 || value > bound.max) {
+    throw new RangeError(`${name} must be an integer from 1 to ${bound.max}`)
+  }
+  return value
+}
+
+const batchSize = readBound('ORDER_RECONCILE_BATCH_SIZE', env.ORDER_RECONCILE_BATCH_SIZE, {
+  default: 200,
+  max: 1000,
+})
+```
+
+Bind the value as a parameter, `LIMIT $1`, never a literal in SQL text. `LIMIT 1` for a single-row
+lookup and an external API's documented page maximum are contracts, not tunables.
+
+## List endpoint
+
+The API schema keeps a static ceiling. The runtime default and effective maximum are tunable but
+never above it, and the server rejects an invalid size and clamps a large one:
+
+```ts
+const API_MAX_PAGE_SIZE = 100
+
+export function pageSize(requested: number | undefined, config: PageConfig): number {
+  const ceiling = Math.min(config.maxPageSize, API_MAX_PAGE_SIZE)
+  const value = requested ?? config.defaultPageSize
+  if (!Number.isInteger(value) || value < 1) {
+    throw new RangeError('Page size must be a positive integer')
+  }
+  return Math.min(value, ceiling)
+}
+```
+
+Page by keyset on the key the index serves. Fetch `pageSize + 1` rows to learn whether another page
+exists, return `pageSize`, and encode the last returned `id` as the next cursor. The first page
+omits `id < $2`:
+
+```sql
+SELECT id, total_cents
+FROM orders
+WHERE account_id = $1 AND id < $2
+ORDER BY id DESC
+LIMIT $3;
+```
+
+## Bounded DELETE through a CTE
+
+DELETE has no `LIMIT`, so select the ids in a CTE and delete by join. The partial index serves the
+retention predicate, and `$1` is the cutoff and `$2` the batch size:
+
+```sql
+CREATE INDEX idx_invoice_delivery_work_items__completed_at
+  ON invoice_delivery_work_items (completed_at, id)
+  WHERE completed_at IS NOT NULL;
+
+WITH expired AS (
+  SELECT id
+  FROM invoice_delivery_work_items
+  WHERE completed_at IS NOT NULL AND completed_at < $1
+  ORDER BY completed_at, id
+  LIMIT $2
+  FOR UPDATE SKIP LOCKED
+)
+DELETE FROM invoice_delivery_work_items AS item
+USING expired
+WHERE item.id = expired.id;
+```
+
+Report `hasMore` when the deleted row count equals the batch size, and let the next run continue.
+
+## Deduplicate against a large table
+
+Do not load every existing key to diff against a candidate list. Ask the table about the
+candidates only, in chunks whose size is a bounded tunable. The candidates themselves come from a
+capped page:
+
+```sql
+SELECT external_ref
+FROM order_imports
+WHERE account_id = $1 AND external_ref = ANY($2::text[]);
+```
+
+```ts
+const known = new Set<string>()
+for (const chunk of chunks(candidates, config.lookupChunkSize)) {
+  const rows = await db.query(findKnownRefsSql, [accountId, chunk])
+  for (const row of rows) known.add(row.external_ref)
+}
+const fresh = candidates.filter((ref) => !known.has(ref))
+```
+
+When the goal is only to insert the new rows, `INSERT ... ON CONFLICT DO NOTHING RETURNING` skips
+the lookup.
+
+## Work that needs every key
+
+A membership filter or a reindex needs every key, but not on every run. Keep the derived state
+current on write: the insert or a dirty marker updates it. A full rebuild is a backfill started on
+purpose, with a row cap per run and a keyset cursor to resume from, as in the high-water-mark
+window. A scheduler never starts it as a pass over everything.
+
+## Verify with a plan
+
+Run each statement with representative parameters against representative table sizes, because a
+small table scans sequentially for good reason. The `due` query of the claim above should plan as
+a `Limit` over a `LockRows` over an index scan on the partial index, with no `Sort` between the
+scan and the `Limit`. Read the rows each node returns, not only the scan type: an index scan that
+feeds a `Sort` below the `Limit` still reads every match. A `Seq Scan` on a table that grows is
+also a finding:
+
+```sql
+PREPARE claim_due (integer) AS
+SELECT id
+FROM invoice_delivery_work_items
+WHERE completed_at IS NULL AND available_at <= now()
+ORDER BY available_at, id
+LIMIT $1
+FOR UPDATE SKIP LOCKED;
+
+BEGIN;
+EXPLAIN (ANALYZE, BUFFERS) EXECUTE claim_due (200);
+ROLLBACK;
+```
+
+`EXPLAIN ANALYZE` runs the statement, so check the claim `UPDATE` or the `DELETE` inside a
+transaction that you roll back, or on a disposable copy. Under contention, `SKIP LOCKED` passes over rows other claimers hold, and those rows sit under the
+`Limit`, so the scan reads the cap plus the rows concurrent claims hold. That stays bounded by the
+number of workers times the batch size when claims are short, so keep the claim transaction to the
+claim statement, and check the index scan's actual rows while several workers claim at once.
+
+## Anti-patterns
+
+| Anti-pattern                                                | Why it is unbounded                                                      | Bounded shape                                                |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------ |
+| Loop until empty: `while (true)` claim, process, break on 0 | New and failing rows keep the run alive; the run has no end              | A batch or deadline cap, `hasMore`, and a continuation       |
+| A stream with no cap: `for await` over every account        | Memory stays flat while run time and database work grow with the table   | Stream a keyset window and cap the rows per run              |
+| A key-only walk: select every account id, then check each   | Touches every entity to find the few with work                           | Read work items, dirty markers, or a due timestamp           |
+| A literal `LIMIT 500` in SQL text                           | Cannot be tuned per environment or during an incident                    | A validated tunable with a hard maximum, bound as `LIMIT $1` |
+| `Promise.all(accounts.map(sync))` over a result of any size | One task per row exhausts the pool or the upstream API                   | A bounded batch with bounded concurrency                     |
+| `OFFSET` pagination                                         | Every page rescans and discards the rows before it                       | Keyset on the indexed key                                    |
+| `UPDATE` or `DELETE` with a predicate but no `LIMIT`        | One statement locks and rewrites an unbounded row set in one transaction | A CTE that selects a capped, `SKIP LOCKED` id set            |

package/skills/manifest.json

@@ -21,6 +21,12 @@
       "pluginVersion": "0.11.0",
       "path": "blackboard/SKILL.md"
     },
+    {
+      "name": "bounded-iteration",
+      "plugin": "vouchington-database",
+      "pluginVersion": "0.4.0",
+      "path": "bounded-iteration/SKILL.md"
+    },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
@@ -103,19 +109,19 @@
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.3.0",
+      "pluginVersion": "0.4.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.3.0",
+      "pluginVersion": "0.4.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
     {
       "name": "postgres-schema-design",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.3.0",
+      "pluginVersion": "0.4.0",
       "path": "postgres-schema-design/SKILL.md"
     },
     {

package/skills/postgres-node-performance-tuning/SKILL.md

@@ -12,7 +12,8 @@ Local policy overrides these defaults; do not reload an already-read adapter or
 Measure the query plan and the workload shape before changing code.
 
 - Select only the required columns.
-- Bound each result set. Paginate or stream a large read.
+- Bound each result set. Paginate or stream a large read. A stream bounds memory, not work: cap
+  the rows per run as in [bounded iteration](../bounded-iteration/SKILL.md).
 - Batch writes inside an explicit transaction limit.
 - Keep connection-pool usage bounded.
 - Validate a query change at representative cardinality. Watch latency, memory, lock time, and

package/skills/postgres-schema-design/SKILL.md

@@ -18,4 +18,6 @@ Local policy overrides these portable conventions.
 
 For query shape, read [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
 For partition lifecycle, use [UUIDv7 partitioning](../postgres-partitioning-uuid-v7/SKILL.md).
+For how jobs choose, cap, and resume over work-item and cursor tables, read
+[bounded iteration](../bounded-iteration/SKILL.md).
 Consumer policy owns lifecycle, retention, migration strategy, and enforcement configuration.