From 098b7b590ee2597ead74bb73cd0734afc1ad4de1 Mon Sep 17 00:00:00 2001 From: Robert Ray <215331614+TheRobertRay@users.noreply.github.com> Date: Mon, 1 Jun 2026 10:00:04 -0700 Subject: [PATCH] Add publication risk scanner --- CHANGELOG.md | 6 ++++ README.md | 10 ++++++- docs/publication-risk.md | 50 +++++++++++++++++++++++++++++++ docs/workflows.md | 10 +++++++ examples/release-readiness.md | 15 ++++++---- scripts/check-publication-risk.sh | 44 +++++++++++++++++++++++++++ scripts/validate.sh | 4 +++ 7 files changed, 132 insertions(+), 7 deletions(-) create mode 100644 docs/publication-risk.md create mode 100755 scripts/check-publication-risk.sh mode change 100644 => 100755 scripts/validate.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index 31793dc..9be4610 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## 0.1.1 - 2026-06-01 + +- Added a publication-risk scanner for catching private paths, credential-like tokens, and internal hostnames before release. +- Added a publication risk gate and expanded release-readiness checklist. +- Wired publication-risk scanning into repository validation. + ## 0.1.0 - 2026-06-01 - Published the initial public Codex operator workflow kit. diff --git a/README.md b/README.md index 83e6750..d8d8a25 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This repository is intentionally small. It packages field-tested operator patter - maintainer triage skill for evidence-first issue and PR review - milestone review skill for substantial implementation work - application packet template for programs that evaluate OSS maintainer signal -- validation script that checks the pack for broken placeholders and missing sections +- validation and publication-risk scripts that check for broken placeholders, missing sections, and private-context leaks - public examples for issue triage, PR review, and release-readiness gates ## Current Status @@ -46,6 +46,12 @@ Validate this repository: bash scripts/validate.sh ``` +Run the publication-risk scanner directly: + +```bash +bash scripts/check-publication-risk.sh +``` + ## Repository Map - `templates/AGENTS.md` - compact global intake and completion-review contract @@ -53,9 +59,11 @@ bash scripts/validate.sh - `skills/milestone-review/SKILL.md` - milestone and adversarial completion review workflow - `docs/maintenance-model.md` - the operating model behind the kit - `docs/workflows.md` - copyable maintainer workflows +- `docs/publication-risk.md` - how to screen workflow packs before publishing - `examples/` - sanitized example packets - `docs/codex-for-oss-application.md` - application packet and field-ready answers - `scripts/validate.sh` - local validation checks +- `scripts/check-publication-risk.sh` - conservative private-context leak scanner ## Maintenance Posture diff --git a/docs/publication-risk.md b/docs/publication-risk.md new file mode 100644 index 0000000..f89f1f8 --- /dev/null +++ b/docs/publication-risk.md @@ -0,0 +1,50 @@ +# Publication Risk Gate + +This gate helps maintainers turn private operator workflows into public, reusable material without publishing private context by accident. + +## When To Run It + +Run this gate before publishing: + +- a new skill copied from real work +- a new example based on an issue, incident, release, or review +- an application packet or maintainer summary +- release notes that mention workflow evidence + +## What To Remove + +Remove or generalize: + +- local machine paths and usernames +- private hostnames, tunnels, and service URLs +- secret-like values, API keys, OAuth tokens, and session identifiers +- customer, collaborator, or private project names +- operational details that only make sense in one private environment + +Keep the maintainer decision intact. A good public example should preserve the reasoning pattern while replacing private specifics with neutral names. + +## Scanner + +Run: + +```bash +bash scripts/check-publication-risk.sh +``` + +The scanner is intentionally conservative. It checks common leak shapes such as absolute home paths, credential-like tokens, local/private network URLs, tunnel hostnames, `.local` hosts, and known private-context terms supplied through `FORBIDDEN_TERMS`. + +Example: + +```bash +FORBIDDEN_TERMS="PrivateProject,CustomerName,internal.example.com" bash scripts/check-publication-risk.sh +``` + +If the scanner flags a file, inspect the line manually. Either remove the private detail or document why the match is safe before release. + +## Release Rule + +Do not tag a release until: + +1. `bash scripts/validate.sh` passes. +2. `bash scripts/check-publication-risk.sh` passes. +3. Any scanner exceptions have a clear maintainer note in the release packet. diff --git a/docs/workflows.md b/docs/workflows.md index 6e0065a..5d4cb7c 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -32,6 +32,16 @@ Use before tagging a release or publishing a package. 4. Confirm no private paths, credentials, or internal hostnames were introduced. 5. Record known residual risks in the release notes. +## Publication Risk Gate + +Use before moving a workflow, skill, prompt, or example from private work into a public repo. + +1. Identify the source context and name the public audience for the extracted workflow. +2. Remove private project names, account details, local paths, hostnames, tokens, and customer or collaborator context. +3. Replace private specifics with generic examples that still preserve the maintainer decision. +4. Run `bash scripts/check-publication-risk.sh` and inspect every finding before release. +5. Record what was intentionally generalized so future maintainers know what changed. + ## Completion Critic Use before declaring a long-running agent task complete. diff --git a/examples/release-readiness.md b/examples/release-readiness.md index e987715..9773ede 100644 --- a/examples/release-readiness.md +++ b/examples/release-readiness.md @@ -2,19 +2,22 @@ ## Release -`v0.2.0` adds a maintainer triage workflow and a validation script. +`v0.1.1` adds a publication-risk scanner and expands the release-readiness workflow. ## Checks -- `bash scripts/validate.sh` -- README quick start still matches the file layout -- changelog includes the user-facing changes -- no private paths, tokens, or hostnames appear in docs or examples +- [ ] `bash scripts/validate.sh` +- [ ] `bash scripts/check-publication-risk.sh` +- [ ] README quick start still matches the file layout +- [ ] changelog includes the user-facing changes +- [ ] release notes describe user-facing changes, not internal work logs +- [ ] examples and skills avoid private paths, tokens, hostnames, project names, and account identifiers +- [ ] known residual risks are explicit ## Release Note ```text -Adds a copyable maintainer triage workflow, milestone review skill, and validation script for checking required files and application answer lengths. +Adds copyable maintainer workflow checks, including release-readiness and publication-risk gates for validating reusable operator material before public release. ``` ## Residual Risk diff --git a/scripts/check-publication-risk.sh b/scripts/check-publication-risk.sh new file mode 100755 index 0000000..d817866 --- /dev/null +++ b/scripts/check-publication-risk.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +set -euo pipefail + +root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +status=0 + +scan() { + local label="$1" + local pattern="$2" + + if grep -RInE "$pattern" "$root" \ + --exclude-dir=.git \ + --exclude='check-publication-risk.sh'; then + echo "publication risk found: $label" >&2 + status=1 + fi +} + +scan "absolute local paths" '(/Users/|/home/|/var/root/|/private/tmp/)' +scan "credential-like tokens" '(sk-[A-Za-z0-9_-]{20,}|gh[pousr]_[A-Za-z0-9_]{20,}|github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16})' +scan "private network or tunnel hostnames" '(tail[0-9a-z.-]*\.ts\.net|tailscale|ngrok-free\.app|trycloudflare\.com|localhost([/:[:space:]]|$)|127\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}|192\.168\.[0-9]{1,3}\.[0-9]{1,3}|172\.(1[6-9]|2[0-9]|3[0-1])\.[0-9]{1,3}\.[0-9]{1,3}|[A-Za-z0-9.-]+\.local([/:[:space:]]|$))' +scan "environment file references" '(^|[^A-Za-z0-9_])\.env([^A-Za-z0-9_]|$)' + +if [[ -n "${FORBIDDEN_TERMS:-}" ]]; then + IFS=',' read -r -a terms <<< "$FORBIDDEN_TERMS" + for term in "${terms[@]}"; do + term="${term#"${term%%[![:space:]]*}"}" + term="${term%"${term##*[![:space:]]}"}" + [[ -z "$term" ]] && continue + if grep -RInF "$term" "$root" \ + --exclude-dir=.git \ + --exclude='check-publication-risk.sh'; then + echo "publication risk found: forbidden term '$term'" >&2 + status=1 + fi + done +fi + +if [[ "$status" -ne 0 ]]; then + echo "publication risk check failed" >&2 + exit "$status" +fi + +echo "publication risk check passed" diff --git a/scripts/validate.sh b/scripts/validate.sh old mode 100644 new mode 100755 index d0389fc..d0cdb3c --- a/scripts/validate.sh +++ b/scripts/validate.sh @@ -11,6 +11,7 @@ required=( "CHANGELOG.md" "LICENSE" "docs/maintenance-model.md" + "docs/publication-risk.md" "docs/workflows.md" "docs/codex-for-oss-application.md" "examples/issue-triage.md" @@ -19,6 +20,7 @@ required=( "skills/oss-maintainer-triage/SKILL.md" "skills/milestone-review/SKILL.md" "templates/AGENTS.md" + "scripts/check-publication-risk.sh" ) for path in "${required[@]}"; do @@ -41,6 +43,8 @@ for skill in "$root"/skills/*/SKILL.md; do grep -q '^##' "$skill" || { echo "missing sections: $skill" >&2; exit 1; } done +"$root/scripts/check-publication-risk.sh" + python3 - "$root/docs/codex-for-oss-application.md" <<'PY' import re import sys