Add publication risk scanner

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.

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,16 +46,24 @@ 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
 - `skills/oss-maintainer-triage/SKILL.md` - issue, PR, and bounty-style evidence triage
 - `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
 

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.

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.

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

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"

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