[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M758YNQ55NZC9JBC9MB8QW0D":3,"skill-same:01M758YNQ55NZC9JBC9MB8QW0D":55},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":32,"commitSha":33,"skillDirectory":34,"forksCount":35,"repositoryHtmlUrl":36,"repositoryHomepageUrl":37,"ownerHtmlUrl":38,"ownerBlogUrl":6,"ownerDescription":39,"updatedAt":40,"install":41,"resources":54},"01M758YNQ55NZC9JBC9MB8QW0D","pii-scrubbing",null,"Systematically scrub Personally Identifiable Information (PII) from a codebase — inventory real domains, hostnames, credentials, and email addresses across all files; patch them to placeholders; create .example templates for gitignored configs; rewrite git history to remove PII from past commits; and verify the result is clean.","lukemcqueen\u002Fsteadfaste-fleet","lukemcqueen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F405240?v=4","01M757MHPAGRXTJAT46SKZP98R","Luke McQueen","01M757MHPZ573KP8DT9GB8SBQ7",4,"MIT","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fsecurity\u002Fpii-scrubbing\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: pii-scrubbing\nversion: 1.0.0\ncategory: security\ndescription: >-\n  Systematically scrub Personally Identifiable Information (PII) from a\n  codebase — inventory real domains, hostnames, credentials, and email\n  addresses across all files; patch them to placeholders; create .example\n  templates for gitignored configs; rewrite git history to remove PII from\n  past commits; and verify the result is clean.\ntags:\n  - pii\n  - security\n  - git-filter-repo\n  - history-rewrite\n  - credentials\n  - secrets\n---\n\n# PII Scrubbing — Systematic Codebase Cleanup\n\n## Trigger\n\nUse this skill when:\n- Asked to \"remove PII from the repo\" or \"scrub real URLs\u002Fhostnames\u002Fcredentials\"\n- Preparing a repo for open-source publication\n- A security review finds real domains, passwords, or emails in code\u002Fdocs\n- Asked to create `.example` templates for config files with secrets\n- Asked to remove PII from git history\n\n## Workflow\n\n### Phase 1: Inventory\n\nSearch the repo systematically for PII patterns. Run ALL of these searches:\n\n| Pattern | What it catches |\n|---------|-----------------|\n| `grep -r 'realdomain.com' .` | Real infrastructure domains |\n| `grep -r 'customer-host.com' .` | Real server hostnames |\n| `grep -r 'user:pass@' .` | Credentials embedded in URLs |\n| `grep -rE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}' .` | Email addresses |\n| `grep -r 'sk-[a-zA-Z0-9]{20,}' .` | API keys |\n| `grep -rE '\\b(?:[0-9]{1,3}\\.){3}[0-9]{1,3}\\b' .` | IP addresses (check each — 127.x.x.x is safe) |\n| `grep -r 'password|secret|key|token|cred' -i` | Credential references |\n| `grep -rE ':1[0-9]{4}[0-9]*' .` | Port numbers (check if they're custom infrastructure) |\n| `find . -name '*cred*' -o -name '*secret*' -o -name '*token*' -o -name '*.pwd' 2>\u002Fdev\u002Fnull` | Credential files in working tree |\n\n**Gitignore audit for credential files:** Every credential file found in the working tree must be gitignored. For each one:\n\n```bash\ngit check-ignore \u003Cfilename>\n# Returns the path if gitignored (safe), nothing if NOT gitignored (CRITICAL)\n```\n\nAlso verify the `.gitignore` patterns that catch them. Common patterns: `*cred*`, `*secret*`, `*token*`, `*.pem`, `*.key`. Run `grep -n 'cred\\|secret\\|token\\|pem\\|key' .gitignore` to confirm coverage. If a credential file isn't covered by any existing pattern, add one.\n\n**PII categories to flag** (any one of these is actionable):\n\n| Category | Examples | Treatment |\n|----------|----------|-----------|\n| Infrastructure domain | `your-infra-domain.org`, `customer-app.com` | Replace with `your-domain.com` |\n| Production hostname | `mweb-stage.customer.or.kr`, `api.customer.org` | Replace with `your-customer-host.com` |\n| Agent hostname | `gisu-host`, `joseph-host` | Replace with `your-agent-host` |\n| Real credentials | `user:pass`, `sk-abc...`, `T1tus!nbox_2026` | Replace with `your-credential-placeholder` |\n| Real email addresses | `admin@customer.org`, `audit@customer.org` | Replace with `admin@client-domain.com` |\n| Real file paths with user | `\u002Fhome\u002Fluke`, `\u002FUsers\u002Fluke` | Replace with `\u002Fpath\u002Fto\u002Fapp` or `$HOME` |\n| Local username \u002F absolute home path | `\u002Fhome\u002Fluke`, `\u002Fhome\u002Fjoseph` | Grep the REAL `\u002Fhome\u002F\u003Coperator>\u002F`, not a blanket `\u002Fhome\u002F`; replace shell→`$HOME`, docs→`~\u002F`, tests→`pathlib.Path.home()` |\n| Messaging \u002F chat IDs | Telegram chat\u002Fchannel ID `1234567890` | Isolates a real person; use a `TELEGRAM_CHAT_ID` placeholder |\n| Client project names | `clientco-royalty`, `client-app` | Evaluate: is this identifying? If yes, use `client-project` |\n| Company\u002Forganization names | `CLIENTCO`, `AcmeCorp` | Replace with `ExampleCorp` or generic `ClientName` |\n| Real person names in paths | `joseph\u002F`, `luke\u002F` | Rename to generic descriptor (`operator\u002F`, `user\u002F`). Scan directory listing, not just file contents |\n| Real person names in content | `Luke`, `Joseph` (not biblical\u002Fhistorical figures) | Replace with `the user`, `the operator`, or a role descriptor |\n| Multiple TLD variants (same base domain) | `client.org`, `client.or.kr`, `client.com` | Search for the base word across all TLDs, not just the one you found first |\n| API endpoint URLs | `https:\u002F\u002Fworks.customer.org\u002Fapi\u002F...` | Replace with `https:\u002F\u002Fapi.client-domain.com\u002F...` |\n\n### Phase 2: Patch Working Tree\n\nFor each file with PII, determine the right treatment:\n\n**A) Scripts with hardcoded default URLs:**\n```python\n# Before\nURL = os.environ.get(\"SOME_VAR\", \"https:\u002F\u002Frealdomain.com:13004\")\n\n# After\nURL = os.environ.get(\"SOME_VAR\", \"https:\u002F\u002Fyour-domain.com:13004\")\n```\nPattern: change the fallback default to `your-domain.com`. The env var override still works for actual deployments.\n\n**B) Config templates:**\n```ini\n# Before\nMOSES_INBOX_URL=\"https:\u002F\u002Frealdomain.com:13004\"\n\n# After\nMOSES_INBOX_URL=\"${DOMAIN_URL:-https:\u002F\u002Fyour-domain.com:13004}\"\n```\nOr replace directly with placebo values and document that the user must set their actual values.\n\n**C) Example curl commands in docs\u002Fcode:**\n```\n# Before\ncurl https:\u002F\u002Frealdomain.com:13004\u002Fapi\u002Fsend\n\n# After\ncurl https:\u002F\u002Fyour-domain.com:13004\u002Fapi\u002Fsend\n```\n\n**D) Credentials in example code:**\n```\n# Before\ncurl -sk -u \"user:password123\"\n\n# After\ncurl -sk -u \"user:your-password\"\n```\n\n**E) Email addresses in skill references:**\n```\n# Before\nadmin@client-domain.com\n\n# After\nadmin@client-domain.com\n```\n\n### Phase 3: Create .example Templates for Gitignored Files\n\nFor any config file that contains real secrets and is gitignored:\n\n1. Create `filename.example` with placeholder values\n2. Ensure the real file is in `.gitignore`\n3. Add `!*.example` exception to `.gitignore` if `.example` extension is generally gitignored\n4. Commit both the `.gitignore` fix and the `.example` file\n\n### Phase 3b: Template + Setup Script Pattern (for programmatic configs)\n\nFor JSON configs or structured data that need programmatic generation (not manual editing), use a three-file pattern instead of `.example`:\n\n| File | Location | Purpose |\n|------|----------|---------|\n| **Template** | `src\u002Fname.template.json` (repo) | Placeholder values like `{{FLEET_DOMAIN}}` |\n| **Setup script** | `ops\u002Fscripts\u002Fsetup-name.sh` (repo) | Reads env vars or prompts, substitutes placeholders, writes real file outside repo |\n| **Real config** | `~\u002F.hermes\u002Fstate\u002Fname.json` (outside repo) | Actual URLs\u002Fcredentials, never committed |\n| **Consumer code** | Python\u002Fsh scripts | Reads private path first, falls back to template if not found |\n\n**Structure in the repo:**\n```\nRepo (public):\n  src\u002Fagent-registry.template.json           ← {{PLACEHOLDER}} values only\n  ops\u002Fscripts\u002Fsetup-agent-registry.sh         ← creates real file at ~\u002F.hermes\u002Fstate\u002F\n\nFilesystem (gitignored \u002F outside repo):\n  ~\u002F.hermes\u002Fstate\u002Fagent-registry.json        ← real URLs, NEVER committed\n\nConsumer code pattern:\n  # 1. Check ~\u002F.hermes\u002Fstate\u002F first\n  # 2. Fall back to src\u002F*.template.json if not found\n  # 3. This lets new installs run with defaults, production uses real config\n```\n\n**When to use this pattern:**\n- Config file is JSON or other structured format (not plain key=value)\n- Values need validation beyond \"is it non-empty\"\n- Multiple URL\u002Fcredential pairs need filling (e.g. agent registry with 5+ agents)\n- Same setup process runs on multiple machines\n\n**When to use `.example` pattern instead:**\n- Simple key=value configs (`.env`, `.ini`)\n- Files the user will manually edit once\n- Self-explanatory values that don't need validation\n\n**Proven in Steadfaste Fleet:**\n- `models.env` — env vars with `FLEET_DOMAIN` override\n- `hermes-inbox.conf` — created by setup with `FLEET_INBOX_*` vars\n- `agent-registry.json` — multi-agent registry created by `setup-agent-registry.sh`\n\n**Non-interactive deployment:**\n```bash\n# Set env vars, then run the script — no prompts\nFLEET_DOMAIN=myhost.com FLEET_HEALTH_PORT=13007 \\\n  ESTHER_DOMAIN=otherhost.com ESTHER_HEALTH_PORT=13007 \\\n  bash ops\u002Fscripts\u002Fsetup-agent-registry.sh\n```\n\n**For `.env` files specifically:**\n- Audit `docker-compose*.yml` for all `${VAR:?...}` and `${VAR:-...}` references\n- Collect required and optional variables\n- Create `deploy\u002F.env.example` with:\n  - Comment header explaining purpose and where to put the file\n  - Quick-seed commands (e.g., `openssl rand -hex 32` for generating secrets) — embed these in the example so users can copy-paste them\n  - Required vars listed first with empty values (the user MUST fill these)\n  - Optional vars commented out with defaults documented\n  - Hermes integration vars as a separate commented section if they go in a different file (`~\u002F.hermes\u002F.env`)\n- Ensure `!.env.example` exception is in `.gitignore` AFTER `.env.*`:\n  ```gitignore\n  .env\n  .env.local\n  .env.*\n  !.env.example  # ← the negation must come AFTER .env.*\n  ```\n- See: `deploy\u002F.env.example` in steadfaste-fleet for a worked example\n\n**For service-specific config files** (e.g., `ops\u002Fscripts\u002Finbox.conf.example`):\n- Follow the same pattern: real values → placeholders, document what the user should replace\n\n### Phase 4: Rewrite Git History\n\nUse `git-filter-repo` to scrub PII from ALL past commits:\n\n1. **Install git-filter-repo** (if needed):\n   ```bash\n   pip3 install git-filter-repo\n   ```\n\n2. **Create replacements file** (`\u002Ftmp\u002Fpii-replacements.txt`):\n   ```\n   literal:realdomain.org==>your-domain.com\n   literal:realdomain.com==>your-domain.com\n   literal:customer.host.name==>your-customer-host\n   literal:RealPassword123!==>your-password-placeholder\n   ```\n\n3. **Clone to a temp directory** (run filter-repo on a clone, not the working repo):\n   ```bash\n   cd \u002Ftmp\n   rm -rf repo-clean 2>\u002Fdev\u002Fnull\n   git clone \u002Fpath\u002Fto\u002Fworking-repo repo-clean\n   cd repo-clean\n   ```\n\n4. **Run filter-repo**:\n   ```bash\n   git-filter-repo --replace-text \u002Ftmp\u002Fpii-replacements.txt --force\n   ```\n\n5. **Verify** — search for every pattern:\n   ```bash\n   git grep -i \"realdomain\\|password123\\|other-pattern\" .\n   # Should return EXIT 1 (no matches)\n   ```\n\n6. **Handle branch protection** (GitHub):\n   - If `main` is protected: push to `main-sanitized` first, then ask the user to temporarily disable branch protection\n   - Then force-push the cleaned history:\n     ```bash\n     git remote add origin https:\u002F\u002Fgithub.com\u002Fuser\u002Frepo.git\n     git push --force --all origin\n     ```\n\n### Phase 4b: Cover Commit Messages (Separate Pass)\n\n⚠️ **`--replace-text` only covers file contents and filenames — it does NOT touch commit messages.** Commit messages need a dedicated `--replace-message` pass.\n\nAfter `--replace-text` completes, run a second filter-repo pass with the same replacements file:\n\n```bash\ncd \u002Ftmp\u002Frepo-clean\ngit filter-repo --force --refs HEAD --replace-message \u002Ftmp\u002Fpii-replacements.txt\n```\n\nThis rewrites the history again, applying the same literal replacements to commit subjects and bodies. Without this, commit messages like `fix: add Gisu to mirror chain for CLIENTCO images` still leak the real project name.\n\n**When to use:** Always. Unless you've verified there's no PII in any commit message (via `git log --oneline --grep`), assume there is.\n\n### Phase 4c: File Renaming via `--filename-callback`\n\nWhen obfuscating a project name that appears in filenames (e.g. `clientco-development-patterns.md` → `acme-development-patterns.md`), use `--filename-callback`.\n\nThe callback receives **bytes**, not str — decode\u002Fencode accordingly:\n\n```bash\ngit filter-repo --force --refs HEAD \\\n  --replace-text \u002Ftmp\u002Freplacements.txt \\\n  --filename-callback 'return filename.replace(b\"clientco\", b\"acme\").replace(b\"CLIENTCO\", b\"ACME\").replace(b\"Clientco\", b\"Acme\")'\n```\n\nAfter renaming, update the replacement rules file to include the case variants:\n\n```\nCLIENTCO==>ACME\nClientco==>Acme\nclientco==>acme\n```\n\n### Phase 4d: Case Variants\n\nA project name can appear in three case forms:\n- **UPPERCASE**: `CLIENTCO` — in titles, headings, CISAC codes\n- **Titlecase**: `Clientco` — in running text (\"Clientco-royalty monorepo\")\n- **lowercase**: `clientco` — in URLs, paths, repo names (`clientco-works`, `clientco-royalty`)\n\n`--replace-text` does **case-sensitive exact match** — `clientco==>acme` will NOT match `CLIENTCO` or `Clientco`. Add ALL variants to the replacements file:\n\n```\nCLIENTCO==>ACME\nClientco==>Acme\nclientco==>acme\n```\n\nSame for `--filename-callback` — each variant needs its own `.replace()` call.\n\n### Phase 5: Verify — Check Both Content AND Commit Messages\n\nComprehensive check after all changes:\n\n| Check | How | Expected |\n|-------|-----|----------|\n| No PII in file contents | `git grep -i \"realdomain\\|original-pattern\" .` | Exit 1 (no matches) |\n| No PII in filenames | `find . -iname \"*oldproject*\"` | Empty |\n| No PII in commit messages | `git log HEAD --oneline --grep=\"oldproject\\|other-pattern\"` | Empty |\n| No PII in past commits | `git-filter-repo` output shows 0 matches | Clean run |\n| Real configs gitignored | `git check-ignore path\u002Fto\u002Fconfig.json` | Exit 0 (ignored) |\n| Example templates tracked | `git ls-files` includes `.example` files | Listed |\n\n**Verification gotcha:** After cloning from a local repo that's already been rewritten, `git log --all --grep=` shows false positives from `refs\u002Fremotes\u002Forigin\u002Fmain` (the stale remote tracking ref). Always verify against `HEAD` explicitly: `git log HEAD --oneline --grep=...` — not `--all`.\n\n## Ordering Rules in Replacements File\n\nPlace more specific patterns FIRST in the replacements file, more general patterns LAST. Filter-repo applies rules sequentially — a vague match can consume a URL before the specific domain rule fires.\n\n**Wrong ordering:**\n```\nclientco==>acme                              # ← fires first on \"clientco.or.kr\" → \"acme.or.kr\" ❌\nclientco.or.kr==>client-domain.com           # ← never reached\n```\n\n**Correct ordering:**\n```\nclientco.or.kr==>client-domain.com           # ← fires first, catches full domain ✅\nmweb-stage.clientco.or.kr==>your-gisu-host   # ← even more specific should come first\nclientco==>acme                              # ← now safe: only matches non-domain uses\n```\n\n## Pitfalls\n\n- **Don't run `git-filter-repo` on the working repo directly** — it removes remotes and you lose the origin. Always clone to tmp first.\n- **Don't forget `.example` gitignore exceptions** — if `.gitignore` has `.env.*`, `.env.example` will be ignored too. Add `!.env.example` AFTER the pattern.\n- **Don't stop at the working tree** — PII in past commits is still visible via `git blame` and accessible to anyone who clones history. Always use `git-filter-repo` for a full scrub.\n- **Don't miss the second domain variant** — if the user has `realdomain.com` and `realdomain.org`, search for BOTH. Users often have one domain for infrastructure and another for email\u002FSSL.\n- **Don't miss commit messages** — `--replace-text` is for file contents only. Commit messages need a separate `--replace-message` pass. This is the #1 oversight — without it, the commit log still leaks.\n- **Don't use `--all` in verification** — `git log --all --grep=` includes stale remote tracking refs that predate the filter. Use `git log HEAD --grep=` to verify the actual branch being pushed.\n- **Don't forget filename callbacks return bytes** — `--filename-callback` in filter-repo receives `bytes`, not `str`. Use `filename.replace(b\"old\", b\"new\")` not `filename.replace(\"old\", \"new\")`.\n- **Don't forget case variants** — `clientco` is three different strings (`clientco`, `Clientco`, `CLIENTCO`). Add all to the replacements file.\n- **Don't order replacements wrong** — put specific full-domain patterns before generic project-name patterns. A `clientco==>acme` rule that fires before `clientco.or.kr==>client-domain.com` produces `acme.or.kr` instead of `client-domain.com`.\n- **Don't force-push protected branches** — check with `git push --dry-run --force origin main` first, or push to an unprotected branch and ask for protection to be temporarily lifted.\n- **Don't propose a history rewrite the operator can't execute** — before offering to scrub commit messages via force-push, verify the operator can actually run the required fleet resets (SSH access to every clone; a force-push needs `git reset --hard origin\u002Fmain` on all hosts). Observed 2026-08-13: allow-list IPs leaked into 4 commit messages; the rewrite was blocked because Luke has no SSH. The correct response was saving a tracked task for when access exists (task de541a0a) plus a content guardrail, NOT pushing the rewrite and NOT leaving the messages as-is silently.\n- **Don't leave real passwords in example code** — even if the example looks generic, a real password like `T1tus!nbox_2026` is a production credential. Replace with `your-inbox-password` or similar.\n- **Shell `echo` statements with escaped quotes** — shell scripts that print config vars via `echo \"    VAR=\\\"value\\\"\"` are fragile under `patch` tool's escape-drift. The `\\\"` sequence can cause the patch tool to double-escape backslashes. Fix: read the exact line with `read_file`, then use the literal file content (including escaped quotes) as both old and new strings, or bypass `patch` and use `write_file` for the entire script section.\n- **Don't stop after one TLD** — if you found `client.org`, also search for `client.com`, `client.or.kr`, `client.co.kr`, etc. Users often have different TLDs for different services (infrastructure vs email vs SSL certs). After fixing one, search for just the base word (e.g. `clientco`) to catch all variants.\n- **Don't treat `127.0.0.1` or `localhost` as PII** — these are internal addresses and are safe to leave in public code.\n- **`--refs HEAD` prevents re-processing backup refs** — after a prior filter-repo run, `refs\u002Foriginal\u002F*` backup refs exist. Without `--refs HEAD`, the new pass will process them again and potentially create duplicate processing issues. Always pass `--refs HEAD`.\n\n- **Clone from just-rewritten repo may fail checkout** — after `git filter-repo` rewrites history in a local repo, cloning from it can give `fatal: this operation must be run in a work tree`. The clone succeeds (objects transferred) but checkout fails. Fix with `git restore --source=HEAD :\u002F` after clone. This happens because filter-repo invalidates the worktree index. If even `git restore` fails, re-clone from the remote after force-push instead.\n\n- **Post-rewrite re-clone loses gitignored local files** — after force-pushing rewritten history and `rm -rf`\u002Fre-cloning the working repo, any gitignored files (agent-registry.json, .env, etc.) are gone. Always back up gitignored configs before destroying and re-cloning the working tree.\n- **Don't assume credential files are safe just because they exist in the working tree.** A file like `agent-creds.md` may be caught by a glob pattern (`*cred*`), but verify with `git check-ignore \u003Cfile>`. If it returns nothing, add a `.gitignore` pattern immediately. A credential file sitting un-ignored in the working tree is one accidental `git add -A` away from being committed.\n- **Don't treat the repo's own GitHub URL as PII** — `github.com\u002Fuser\u002Frepo` is the repo's public identity. Scrubbing the username from clone URLs, badge URLs, and script URLs breaks the repo for everyone. Distinguish: the repo's public address stays; personal infrastructure domains go.\n- **Grep the REAL operator home path, not a blanket `\u002Fhome\u002F`** — generic `\u002Fhome\u002Fuser\u002F`, `\u002Fhome\u002Fpi\u002F`, `\u002Fhome\u002Ftest\u002F` are intentional placeholders; only the actual `\u002Fhome\u002F\u003Coperator>\u002F` leaks the username and machine home layout. Resolve it from `Path.home().name` and target exactly that; report hits per file without restating the path. **But the PII WRITE GATE is stricter than this grep guidance:** it refuses ANY literal `\u002Fhome\u002F`-prefixed path in a shared-surface write — the generic placeholder `\u002Fhome\u002Fuser\u002Fx` included, because the file is one deploy\u002Fcopy from the public repo. When a test corpus or example command needs a NON-scratch absolute path, use `\u002Fsrv\u002F` or `\u002Fvar\u002Flib\u002F` — never a `\u002Fhome\u002F` literal; rewrite the affected corpus entry rather than arguing with the gate.\n- **Replace a hardcoded absolute home path context-appropriately** — shell script defaults → `$HOME\u002F`, docs\u002Fskills → `~\u002F`, Python test fixtures → `pathlib.Path.home()` at runtime. A test that hardcodes the operator's absolute home path is non-hermetic AND leaks it; build it from `Path.home()` so it passes on any machine and reveals nothing.\n- **Python `open()`\u002F`Path()`\u002F`file()` do NOT expand `~`** — turning `\u002Fhome\u002F\u003Coperator>\u002F...` into `~\u002F.hermes\u002F...` inside a Python path call is not a redaction, it is a `FileNotFoundError` waiting at first run, and the self-adversarial close review flags the broken snippet. When a home path sits inside a Python path call in a doc or code snippet, write it as `open(os.path.expanduser('~\u002F.hermes\u002F...'))` \u002F `Path('~\u002F.hermes\u002F...').expanduser()` and add `import os` (or the `Path` import) to that snippet. Keep `~\u002F` as a portable literal only where it is not executed (shell, prose); reserve the `\u003CHOME>` marker for rewritten captured-output text, never inside code that runs.\n- **Treat messaging\u002Fapp chat IDs as PII** — a Telegram chat\u002Fchannel ID correlates a real person; scrub it to a `TELEGRAM_CHAT_ID` placeholder in the same pass as the domain\u002Fusername.\n- **Keep PII gate checks for personal identifiers path-independent** — a home-folder write (a skill write, a deploy copy, `git add` of a local file) is one step from the public repo, so a gate that early-returns for non-shared paths lets the same identifiers through the back door. Scope generic email\u002Fphone checks to shared surfaces; scope uniquely-personal identifiers (surname, operator domain, WAN address) to EVERY write target.\n- **Preserve historical evidence records unless the operator says redact** — `docs\u002Fevidence`, test artifacts, and dated records are kept verbatim by fleet policy; scrubbing committed history is an operator decision. Scrub the active code\u002Fdocs surface, then report the evidence-file scope and ask — do not silently rewrite records.\n- **Don't forget `.env.example` is tracked in git** — unlike `.env` (which is gitignored), `.env.example` is tracked and can contain real domains\u002FURLs. Search it explicitly: it's the most common place for a real URL to lurk after you've scrubbed the main codebase. Same for any `.example`, `.template`, or `.sample` file.\n- **macOS `grep -P` silently no-ops** — BSD grep has no `-P`; `grep -Pn 'pattern'` exits 2, and a scanner that doesn't check the exit code silently reports \"no matches\" and skips the scan entirely (observed 2026-08-04: the secret-leak detector PII scan no-op'd on macOS for exactly this reason; fixed by converting every `grep -P` \u002F `\\s` \u002F `(?:` construct to portable ERE — `grep -E` \u002F `[[:space:]]`). When writing or auditing any PII-scan script: use `grep -E`, never `-P`; and if a scan step exits non-zero, treat it as a FAIL with a loud warning, never as a clean pass.\n- **Redact captured evidence as a LABELED redaction, never a disguised rewrite** — when the operator authorizes scrubbing evidence\u002Frecords (captured command output, transcripts, verification artefacts), do NOT change an absolute operator path to a bare `~\u002F` and present it as the raw capture: the self-adversarial close review flags a rewritten capture as FABRICATION, and a body edited under an unchanged sha256 is an unverified claim. Replace the operator path with an explicit, unambiguous marker (`\u003CHOME>\u002F...`), add a header note that the output was post-processed to redact home-directory paths (this is a redacted copy, not verbatim), and annotate or recompute any sha256 so it no longer appears to attest to the edited body. A redaction that looks like normal captured output is a lie; one that is visibly marked is honest.\n- **After any regex substitution pass, grep for leaked backreference artifacts** — if a replacement string carries a double-escaped backreference (e.g. `re.sub(r\"~\u002F(...)\", r\"\u003CHOME>\u002F\\\\1\", s)`), Python emits the LITERAL token `\\1` (the group is never substituted), so files end up with garbage like `\u003CHOME>\u002F\\1-cortex`. Use a single backslash (`r\"...\\1\"`) for a real group reference, and afterward grep the result for any `\\N` residue before committing.\n- **Don't blind-batch a uniform redaction + note header across a whole directory** — applying one replacement (e.g. a markdown '\u003CHOME> + redacted-copy' header prepend) to EVERY file matching a pattern, including serialized evidence (.json, .raw.json) and MEMORY snapshots, corrupts machine-readable files and adds spurious headers to dozens of unrelated records. Redact per file class; after each pass re-validate anything that must stay machine-readable (parse the JSON, bash -n the scripts, compile the .py) before you commit.\n- **Never `.replace()` a short substring that is the prefix of a longer real token** — `str.replace` and a per-line `re.sub` do naive substring matching: `.replace(\"import json, subproc\", \"import json, subproc, os\")` chops `import json, subprocess, os` into the corrupt `import json, subproc, osess, os` (the needle `subproc` matched the start of `subprocess`). For identifier-like text use a word-boundary regex or match the full token; after a mass-replace of identifiers\u002Fimports, grep the touched set for chopped tokens and for a doubled import (`import json, os, os` from a needle that ran twice) before committing.\n\n## References\n\n- `deploy\u002F.env.example` — reference template for Langfuse docker-compose env vars\n- `src\u002Fagent-registry.json.example` — reference template for agent registry with placeholder URLs\n- `ops\u002Fscripts\u002Finbox.conf.example` — reference template for inbox config\n- `skills\u002Fsoftware-development\u002Fpublic-contribution\u002FSKILL.md` — PII→placeholder mapping table for contributions\n","# PII Scrubbing — Systematic Codebase Cleanup\n\n## Trigger\n\nUse this skill when:\n- Asked to \"remove PII from the repo\" or \"scrub real URLs\u002Fhostnames\u002Fcredentials\"\n- Preparing a repo for open-source publication\n- A security review finds real domains, passwords, or emails in code\u002Fdocs\n- Asked to create `.example` templates for config files with secrets\n- Asked to remove PII from git history\n\n## Workflow\n\n### Phase 1: Inventory\n\nSearch the repo systematically for PII patterns. Run ALL of these searches:\n\n| Pattern | What it catches |\n|---------|-----------------|\n| `grep -r 'realdomain.com' .` | Real infrastructure domains |\n| `grep -r 'customer-host.com' .` | Real server hostnames |\n| `grep -r 'user:pass@' .` | Credentials embedded in URLs |\n| `grep -rE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}' .` | Email addresses |\n| `grep -r 'sk-[a-zA-Z0-9]{20,}' .` | API keys |\n| `grep -rE '\\b(?:[0-9]{1,3}\\.){3}[0-9]{1,3}\\b' .` | IP addresses (check each — 127.x.x.x is safe) |\n| `grep -r 'password|secret|key|token|cred' -i` | Credential references |\n| `grep -rE ':1[0-9]{4}[0-9]*' .` | Port numbers (check if they're custom infrastructure) |\n| `find . -name '*cred*' -o -name '*secret*' -o -name '*token*' -o -name '*.pwd' 2>\u002Fdev\u002Fnull` | Credential files in working tree |\n\n**Gitignore audit for credential files:** Every credential file found in the working tree must be gitignored. For each one:\n\n```bash\ngit check-ignore \u003Cfilename>\n# Returns the path if gitignored (safe), nothing if NOT gitignored (CRITICAL)\n```\n\nAlso verify the `.gitignore` patterns that catch them. Common patterns: `*cred*`, `*secret*`, `*token*`, `*.pem`, `*.key`. Run `grep -n 'cred\\|secret\\|token\\|pem\\|key' .gitignore` to confirm coverage. If a credential file isn't covered by any existing pattern, add one.\n\n**PII categories to flag** (any one of these is actionable):\n\n| Category | Examples | Treatment |\n|----------|----------|-----------|\n| Infrastructure domain | `your-infra-domain.org`, `customer-app.com` | Replace with `your-domain.com` |\n| Production hostname | `mweb-stage.customer.or.kr`, `api.customer.org` | Replace with `your-customer-host.com` |\n| Agent hostname | `gisu-host`, `joseph-host` | Replace with `your-agent-host` |\n| Real credentials | `user:pass`, `sk-abc...`, `T1tus!nbox_2026` | Replace with `your-credential-placeholder` |\n| Real email addresses | `admin@customer.org`, `audit@customer.org` | Replace with `admin@client-domain.com` |\n| Real file paths with user | `\u002Fhome\u002Fluke`, `\u002FUsers\u002Fluke` | Replace with `\u002Fpath\u002Fto\u002Fapp` or `$HOME` |\n| Local username \u002F absolute home path | `\u002Fhome\u002Fluke`, `\u002Fhome\u002Fjoseph` | Grep the REAL `\u002Fhome\u002F\u003Coperator>\u002F`, not a blanket `\u002Fhome\u002F`; replace shell→`$HOME`, docs→`~\u002F`, tests→`pathlib.Path.home()` |\n| Messaging \u002F chat IDs | Telegram chat\u002Fchannel ID `1234567890` | Isolates a real person; use a `TELEGRAM_CHAT_ID` placeholder |\n| Client project names | `clientco-royalty`, `client-app` | Evaluate: is this identifying? If yes, use `client-project` |\n| Company\u002Forganization names | `CLIENTCO`, `AcmeCorp` | Replace with `ExampleCorp` or generic `ClientName` |\n| Real person names in paths | `joseph\u002F`, `luke\u002F` | Rename to generic descriptor (`operator\u002F`, `user\u002F`). Scan directory listing, not just file contents |\n| Real person names in content | `Luke`, `Joseph` (not biblical\u002Fhistorical figures) | Replace with `the user`, `the operator`, or a role descriptor |\n| Multiple TLD variants (same base domain) | `client.org`, `client.or.kr`, `client.com` | Search for the base word across all TLDs, not just the one you found first |\n| API endpoint URLs | `https:\u002F\u002Fworks.customer.org\u002Fapi\u002F...` | Replace with `https:\u002F\u002Fapi.client-domain.com\u002F...` |\n\n### Phase 2: Patch Working Tree\n\nFor each file with PII, determine the right treatment:\n\n**A) Scripts with hardcoded default URLs:**\n```python\n# Before\nURL = os.environ.get(\"SOME_VAR\", \"https:\u002F\u002Frealdomain.com:13004\")\n\n# After\nURL = os.environ.get(\"SOME_VAR\", \"https:\u002F\u002Fyour-domain.com:13004\")\n```\nPattern: change the fallback default to `your-domain.com`. The env var override still works for actual deployments.\n\n**B) Config templates:**\n```ini\n# Before\nMOSES_INBOX_URL=\"https:\u002F\u002Frealdomain.com:13004\"\n\n# After\nMOSES_INBOX_URL=\"${DOMAIN_URL:-https:\u002F\u002Fyour-domain.com:13004}\"\n```\nOr replace directly with placebo values and document that the user must set their actual values.\n\n**C) Example curl commands in docs\u002Fcode:**\n```\n# Before\ncurl https:\u002F\u002Frealdomain.com:13004\u002Fapi\u002Fsend\n\n# After\ncurl https:\u002F\u002Fyour-domain.com:13004\u002Fapi\u002Fsend\n```\n\n**D) Credentials in example code:**\n```\n# Before\ncurl -sk -u \"user:password123\"\n\n# After\ncurl -sk -u \"user:your-password\"\n```\n\n**E) Email addresses in skill references:**\n```\n# Before\nadmin@client-domain.com\n\n# After\nadmin@client-domain.com\n```\n\n### Phase 3: Create .example Templates for Gitignored Files\n\nFor any config file that contains real secrets and is gitignored:\n\n1. Create `filename.example` with placeholder values\n2. Ensure the real file is in `.gitignore`\n3. Add `!*.example` exception to `.gitignore` if `.example` extension is generally gitignored\n4. Commit both the `.gitignore` fix and the `.example` file\n\n### Phase 3b: Template + Setup Script Pattern (for programmatic configs)\n\nFor JSON configs or structured data that need programmatic generation (not manual editing), use a three-file pattern instead of `.example`:\n\n| File | Location | Purpose |\n|------|----------|---------|\n| **Template** | `src\u002Fname.template.json` (repo) | Placeholder values like `{{FLEET_DOMAIN}}` |\n| **Setup script** | `ops\u002Fscripts\u002Fsetup-name.sh` (repo) | Reads env vars or prompts, substitutes placeholders, writes real file outside repo |\n| **Real config** | `~\u002F.hermes\u002Fstate\u002Fname.json` (outside repo) | Actual URLs\u002Fcredentials, never committed |\n| **Consumer code** | Python\u002Fsh scripts | Reads private path first, falls back to template if not found |\n\n**Structure in the repo:**\n```\nRepo (public):\n  src\u002Fagent-registry.template.json           ← {{PLACEHOLDER}} values only\n  ops\u002Fscripts\u002Fsetup-agent-registry.sh         ← creates real file at ~\u002F.hermes\u002Fstate\u002F\n\nFilesystem (gitignored \u002F outside repo):\n  ~\u002F.hermes\u002Fstate\u002Fagent-registry.json        ← real URLs, NEVER committed\n\nConsumer code pattern:\n  # 1. Check ~\u002F.hermes\u002Fstate\u002F first\n  # 2. Fall back to src\u002F*.template.json if not found\n  # 3. This lets new installs run with defaults, production uses real config\n```\n\n**When to use this pattern:**\n- Config file is JSON or other structured format (not plain key=value)\n- Values need validation beyond \"is it non-empty\"\n- Multiple URL\u002Fcredential pairs need filling (e.g. agent registry with 5+ agents)\n- Same setup process runs on multiple machines\n\n**When to use `.example` pattern instead:**\n- Simple key=value configs (`.env`, `.ini`)\n- Files the user will manually edit once\n- Self-explanatory values that don't need validation\n\n**Proven in Steadfaste Fleet:**\n- `models.env` — env vars with `FLEET_DOMAIN` override\n- `hermes-inbox.conf` — created by setup with `FLEET_INBOX_*` vars\n- `agent-registry.json` — multi-agent registry created by `setup-agent-registry.sh`\n\n**Non-interactive deployment:**\n```bash\n# Set env vars, then run the script — no prompts\nFLEET_DOMAIN=myhost.com FLEET_HEALTH_PORT=13007 \\\n  ESTHER_DOMAIN=otherhost.com ESTHER_HEALTH_PORT=13007 \\\n  bash ops\u002Fscripts\u002Fsetup-agent-registry.sh\n```\n\n**For `.env` files specifically:**\n- Audit `docker-compose*.yml` for all `${VAR:?...}` and `${VAR:-...}` references\n- Collect required and optional variables\n- Create `deploy\u002F.env.example` with:\n  - Comment header explaining purpose and where to put the file\n  - Quick-seed commands (e.g., `openssl rand -hex 32` for generating secrets) — embed these in the example so users can copy-paste them\n  - Required vars listed first with empty values (the user MUST fill these)\n  - Optional vars commented out with defaults documented\n  - Hermes integration vars as a separate commented section if they go in a different file (`~\u002F.hermes\u002F.env`)\n- Ensure `!.env.example` exception is in `.gitignore` AFTER `.env.*`:\n  ```gitignore\n  .env\n  .env.local\n  .env.*\n  !.env.example  # ← the negation must come AFTER .env.*\n  ```\n- See: `deploy\u002F.env.example` in steadfaste-fleet for a worked example\n\n**For service-specific config files** (e.g., `ops\u002Fscripts\u002Finbox.conf.example`):\n- Follow the same pattern: real values → placeholders, document what the user should replace\n\n### Phase 4: Rewrite Git History\n\nUse `git-filter-repo` to scrub PII from ALL past commits:\n\n1. **Install git-filter-repo** (if needed):\n   ```bash\n   pip3 install git-filter-repo\n   ```\n\n2. **Create replacements file** (`\u002Ftmp\u002Fpii-replacements.txt`):\n   ```\n   literal:realdomain.org==>your-domain.com\n   literal:realdomain.com==>your-domain.com\n   literal:customer.host.name==>your-customer-host\n   literal:RealPassword123!==>your-password-placeholder\n   ```\n\n3. **Clone to a temp directory** (run filter-repo on a clone, not the working repo):\n   ```bash\n   cd \u002Ftmp\n   rm -rf repo-clean 2>\u002Fdev\u002Fnull\n   git clone \u002Fpath\u002Fto\u002Fworking-repo repo-clean\n   cd repo-clean\n   ```\n\n4. **Run filter-repo**:\n   ```bash\n   git-filter-repo --replace-text \u002Ftmp\u002Fpii-replacements.txt --force\n   ```\n\n5. **Verify** — search for every pattern:\n   ```bash\n   git grep -i \"realdomain\\|password123\\|other-pattern\" .\n   # Should return EXIT 1 (no matches)\n   ```\n\n6. **Handle branch protection** (GitHub):\n   - If `main` is protected: push to `main-sanitized` first, then ask the user to temporarily disable branch protection\n   - Then force-push the cleaned history:\n     ```bash\n     git remote add origin https:\u002F\u002Fgithub.com\u002Fuser\u002Frepo.git\n     git push --force --all origin\n     ```\n\n### Phase 4b: Cover Commit Messages (Separate Pass)\n\n⚠️ **`--replace-text` only covers file contents and filenames — it does NOT touch commit messages.** Commit messages need a dedicated `--replace-message` pass.\n\nAfter `--replace-text` completes, run a second filter-repo pass with the same replacements file:\n\n```bash\ncd \u002Ftmp\u002Frepo-clean\ngit filter-repo --force --refs HEAD --replace-message \u002Ftmp\u002Fpii-replacements.txt\n```\n\nThis rewrites the history again, applying the same literal replacements to commit subjects and bodies. Without this, commit messages like `fix: add Gisu to mirror chain for CLIENTCO images` still leak the real project name.\n\n**When to use:** Always. Unless you've verified there's no PII in any commit message (via `git log --oneline --grep`), assume there is.\n\n### Phase 4c: File Renaming via `--filename-callback`\n\nWhen obfuscating a project name that appears in filenames (e.g. `clientco-development-patterns.md` → `acme-development-patterns.md`), use `--filename-callback`.\n\nThe callback receives **bytes**, not str — decode\u002Fencode accordingly:\n\n```bash\ngit filter-repo --force --refs HEAD \\\n  --replace-text \u002Ftmp\u002Freplacements.txt \\\n  --filename-callback 'return filename.replace(b\"clientco\", b\"acme\").replace(b\"CLIENTCO\", b\"ACME\").replace(b\"Clientco\", b\"Acme\")'\n```\n\nAfter renaming, update the replacement rules file to include the case variants:\n\n```\nCLIENTCO==>ACME\nClientco==>Acme\nclientco==>acme\n```\n\n### Phase 4d: Case Variants\n\nA project name can appear in three case forms:\n- **UPPERCASE**: `CLIENTCO` — in titles, headings, CISAC codes\n- **Titlecase**: `Clientco` — in running text (\"Clientco-royalty monorepo\")\n- **lowercase**: `clientco` — in URLs, paths, repo names (`clientco-works`, `clientco-royalty`)\n\n`--replace-text` does **case-sensitive exact match** — `clientco==>acme` will NOT match `CLIENTCO` or `Clientco`. Add ALL variants to the replacements file:\n\n```\nCLIENTCO==>ACME\nClientco==>Acme\nclientco==>acme\n```\n\nSame for `--filename-callback` — each variant needs its own `.replace()` call.\n\n### Phase 5: Verify — Check Both Content AND Commit Messages\n\nComprehensive check after all changes:\n\n| Check | How | Expected |\n|-------|-----|----------|\n| No PII in file contents | `git grep -i \"realdomain\\|original-pattern\" .` | Exit 1 (no matches) |\n| No PII in filenames | `find . -iname \"*oldproject*\"` | Empty |\n| No PII in commit messages | `git log HEAD --oneline --grep=\"oldproject\\|other-pattern\"` | Empty |\n| No PII in past commits | `git-filter-repo` output shows 0 matches | Clean run |\n| Real configs gitignored | `git check-ignore path\u002Fto\u002Fconfig.json` | Exit 0 (ignored) |\n| Example templates tracked | `git ls-files` includes `.example` files | Listed |\n\n**Verification gotcha:** After cloning from a local repo that's already been rewritten, `git log --all --grep=` shows false positives from `refs\u002Fremotes\u002Forigin\u002Fmain` (the stale remote tracking ref). Always verify against `HEAD` explicitly: `git log HEAD --oneline --grep=...` — not `--all`.\n\n## Ordering Rules in Replacements File\n\nPlace more specific patterns FIRST in the replacements file, more general patterns LAST. Filter-repo applies rules sequentially — a vague match can consume a URL before the specific domain rule fires.\n\n**Wrong ordering:**\n```\nclientco==>acme                              # ← fires first on \"clientco.or.kr\" → \"acme.or.kr\" ❌\nclientco.or.kr==>client-domain.com           # ← never reached\n```\n\n**Correct ordering:**\n```\nclientco.or.kr==>client-domain.com           # ← fires first, catches full domain ✅\nmweb-stage.clientco.or.kr==>your-gisu-host   # ← even more specific should come first\nclientco==>acme                              # ← now safe: only matches non-domain uses\n```\n\n## Pitfalls\n\n- **Don't run `git-filter-repo` on the working repo directly** — it removes remotes and you lose the origin. Always clone to tmp first.\n- **Don't forget `.example` gitignore exceptions** — if `.gitignore` has `.env.*`, `.env.example` will be ignored too. Add `!.env.example` AFTER the pattern.\n- **Don't stop at the working tree** — PII in past commits is still visible via `git blame` and accessible to anyone who clones history. Always use `git-filter-repo` for a full scrub.\n- **Don't miss the second domain variant** — if the user has `realdomain.com` and `realdomain.org`, search for BOTH. Users often have one domain for infrastructure and another for email\u002FSSL.\n- **Don't miss commit messages** — `--replace-text` is for file contents only. Commit messages need a separate `--replace-message` pass. This is the #1 oversight — without it, the commit log still leaks.\n- **Don't use `--all` in verification** — `git log --all --grep=` includes stale remote tracking refs that predate the filter. Use `git log HEAD --grep=` to verify the actual branch being pushed.\n- **Don't forget filename callbacks return bytes** — `--filename-callback` in filter-repo receives `bytes`, not `str`. Use `filename.replace(b\"old\", b\"new\")` not `filename.replace(\"old\", \"new\")`.\n- **Don't forget case variants** — `clientco` is three different strings (`clientco`, `Clientco`, `CLIENTCO`). Add all to the replacements file.\n- **Don't order replacements wrong** — put specific full-domain patterns before generic project-name patterns. A `clientco==>acme` rule that fires before `clientco.or.kr==>client-domain.com` produces `acme.or.kr` instead of `client-domain.com`.\n- **Don't force-push protected branches** — check with `git push --dry-run --force origin main` first, or push to an unprotected branch and ask for protection to be temporarily lifted.\n- **Don't propose a history rewrite the operator can't execute** — before offering to scrub commit messages via force-push, verify the operator can actually run the required fleet resets (SSH access to every clone; a force-push needs `git reset --hard origin\u002Fmain` on all hosts). Observed 2026-08-13: allow-list IPs leaked into 4 commit messages; the rewrite was blocked because Luke has no SSH. The correct response was saving a tracked task for when access exists (task de541a0a) plus a content guardrail, NOT pushing the rewrite and NOT leaving the messages as-is silently.\n- **Don't leave real passwords in example code** — even if the example looks generic, a real password like `T1tus!nbox_2026` is a production credential. Replace with `your-inbox-password` or similar.\n- **Shell `echo` statements with escaped quotes** — shell scripts that print config vars via `echo \"    VAR=\\\"value\\\"\"` are fragile under `patch` tool's escape-drift. The `\\\"` sequence can cause the patch tool to double-escape backslashes. Fix: read the exact line with `read_file`, then use the literal file content (including escaped quotes) as both old and new strings, or bypass `patch` and use `write_file` for the entire script section.\n- **Don't stop after one TLD** — if you found `client.org`, also search for `client.com`, `client.or.kr`, `client.co.kr`, etc. Users often have different TLDs for different services (infrastructure vs email vs SSL certs). After fixing one, search for just the base word (e.g. `clientco`) to catch all variants.\n- **Don't treat `127.0.0.1` or `localhost` as PII** — these are internal addresses and are safe to leave in public code.\n- **`--refs HEAD` prevents re-processing backup refs** — after a prior filter-repo run, `refs\u002Foriginal\u002F*` backup refs exist. Without `--refs HEAD`, the new pass will process them again and potentially create duplicate processing issues. Always pass `--refs HEAD`.\n\n- **Clone from just-rewritten repo may fail checkout** — after `git filter-repo` rewrites history in a local repo, cloning from it can give `fatal: this operation must be run in a work tree`. The clone succeeds (objects transferred) but checkout fails. Fix with `git restore --source=HEAD :\u002F` after clone. This happens because filter-repo invalidates the worktree index. If even `git restore` fails, re-clone from the remote after force-push instead.\n\n- **Post-rewrite re-clone loses gitignored local files** — after force-pushing rewritten history and `rm -rf`\u002Fre-cloning the working repo, any gitignored files (agent-registry.json, .env, etc.) are gone. Always back up gitignored configs before destroying and re-cloning the working tree.\n- **Don't assume credential files are safe just because they exist in the working tree.** A file like `agent-creds.md` may be caught by a glob pattern (`*cred*`), but verify with `git check-ignore \u003Cfile>`. If it returns nothing, add a `.gitignore` pattern immediately. A credential file sitting un-ignored in the working tree is one accidental `git add -A` away from being committed.\n- **Don't treat the repo's own GitHub URL as PII** — `github.com\u002Fuser\u002Frepo` is the repo's public identity. Scrubbing the username from clone URLs, badge URLs, and script URLs breaks the repo for everyone. Distinguish: the repo's public address stays; personal infrastructure domains go.\n- **Grep the REAL operator home path, not a blanket `\u002Fhome\u002F`** — generic `\u002Fhome\u002Fuser\u002F`, `\u002Fhome\u002Fpi\u002F`, `\u002Fhome\u002Ftest\u002F` are intentional placeholders; only the actual `\u002Fhome\u002F\u003Coperator>\u002F` leaks the username and machine home layout. Resolve it from `Path.home().name` and target exactly that; report hits per file without restating the path. **But the PII WRITE GATE is stricter than this grep guidance:** it refuses ANY literal `\u002Fhome\u002F`-prefixed path in a shared-surface write — the generic placeholder `\u002Fhome\u002Fuser\u002Fx` included, because the file is one deploy\u002Fcopy from the public repo. When a test corpus or example command needs a NON-scratch absolute path, use `\u002Fsrv\u002F` or `\u002Fvar\u002Flib\u002F` — never a `\u002Fhome\u002F` literal; rewrite the affected corpus entry rather than arguing with the gate.\n- **Replace a hardcoded absolute home path context-appropriately** — shell script defaults → `$HOME\u002F`, docs\u002Fskills → `~\u002F`, Python test fixtures → `pathlib.Path.home()` at runtime. A test that hardcodes the operator's absolute home path is non-hermetic AND leaks it; build it from `Path.home()` so it passes on any machine and reveals nothing.\n- **Python `open()`\u002F`Path()`\u002F`file()` do NOT expand `~`** — turning `\u002Fhome\u002F\u003Coperator>\u002F...` into `~\u002F.hermes\u002F...` inside a Python path call is not a redaction, it is a `FileNotFoundError` waiting at first run, and the self-adversarial close review flags the broken snippet. When a home path sits inside a Python path call in a doc or code snippet, write it as `open(os.path.expanduser('~\u002F.hermes\u002F...'))` \u002F `Path('~\u002F.hermes\u002F...').expanduser()` and add `import os` (or the `Path` import) to that snippet. Keep `~\u002F` as a portable literal only where it is not executed (shell, prose); reserve the `\u003CHOME>` marker for rewritten captured-output text, never inside code that runs.\n- **Treat messaging\u002Fapp chat IDs as PII** — a Telegram chat\u002Fchannel ID correlates a real person; scrub it to a `TELEGRAM_CHAT_ID` placeholder in the same pass as the domain\u002Fusername.\n- **Keep PII gate checks for personal identifiers path-independent** — a home-folder write (a skill write, a deploy copy, `git add` of a local file) is one step from the public repo, so a gate that early-returns for non-shared paths lets the same identifiers through the back door. Scope generic email\u002Fphone checks to shared surfaces; scope uniquely-personal identifiers (surname, operator domain, WAN address) to EVERY write target.\n- **Preserve historical evidence records unless the operator says redact** — `docs\u002Fevidence`, test artifacts, and dated records are kept verbatim by fleet policy; scrubbing committed history is an operator decision. Scrub the active code\u002Fdocs surface, then report the evidence-file scope and ask — do not silently rewrite records.\n- **Don't forget `.env.example` is tracked in git** — unlike `.env` (which is gitignored), `.env.example` is tracked and can contain real domains\u002FURLs. Search it explicitly: it's the most common place for a real URL to lurk after you've scrubbed the main codebase. Same for any `.example`, `.template`, or `.sample` file.\n- **macOS `grep -P` silently no-ops** — BSD grep has no `-P`; `grep -Pn 'pattern'` exits 2, and a scanner that doesn't check the exit code silently reports \"no matches\" and skips the scan entirely (observed 2026-08-04: the secret-leak detector PII scan no-op'd on macOS for exactly this reason; fixed by converting every `grep -P` \u002F `\\s` \u002F `(?:` construct to portable ERE — `grep -E` \u002F `[[:space:]]`). When writing or auditing any PII-scan script: use `grep -E`, never `-P`; and if a scan step exits non-zero, treat it as a FAIL with a loud warning, never as a clean pass.\n- **Redact captured evidence as a LABELED redaction, never a disguised rewrite** — when the operator authorizes scrubbing evidence\u002Frecords (captured command output, transcripts, verification artefacts), do NOT change an absolute operator path to a bare `~\u002F` and present it as the raw capture: the self-adversarial close review flags a rewritten capture as FABRICATION, and a body edited under an unchanged sha256 is an unverified claim. Replace the operator path with an explicit, unambiguous marker (`\u003CHOME>\u002F...`), add a header note that the output was post-processed to redact home-directory paths (this is a redacted copy, not verbatim), and annotate or recompute any sha256 so it no longer appears to attest to the edited body. A redaction that looks like normal captured output is a lie; one that is visibly marked is honest.\n- **After any regex substitution pass, grep for leaked backreference artifacts** — if a replacement string carries a double-escaped backreference (e.g. `re.sub(r\"~\u002F(...)\", r\"\u003CHOME>\u002F\\\\1\", s)`), Python emits the LITERAL token `\\1` (the group is never substituted), so files end up with garbage like `\u003CHOME>\u002F\\1-cortex`. Use a single backslash (`r\"...\\1\"`) for a real group reference, and afterward grep the result for any `\\N` residue before committing.\n- **Don't blind-batch a uniform redaction + note header across a whole directory** — applying one replacement (e.g. a markdown '\u003CHOME> + redacted-copy' header prepend) to EVERY file matching a pattern, including serialized evidence (.json, .raw.json) and MEMORY snapshots, corrupts machine-readable files and adds spurious headers to dozens of unrelated records. Redact per file class; after each pass re-validate anything that must stay machine-readable (parse the JSON, bash -n the scripts, compile the .py) before you commit.\n- **Never `.replace()` a short substring that is the prefix of a longer real token** — `str.replace` and a per-line `re.sub` do naive substring matching: `.replace(\"import json, subproc\", \"import json, subproc, os\")` chops `import json, subprocess, os` into the corrupt `import json, subproc, osess, os` (the needle `subproc` matched the start of `subprocess`). For identifier-like text use a word-boundary regex or match the full token; after a mass-replace of identifiers\u002Fimports, grep the touched set for chopped tokens and for a doubled import (`import json, os, os` from a needle that ran twice) before committing.\n\n## References\n\n- `deploy\u002F.env.example` — reference template for Langfuse docker-compose env vars\n- `src\u002Fagent-registry.json.example` — reference template for agent registry with placeholder URLs\n- `ops\u002Fscripts\u002Finbox.conf.example` — reference template for inbox config\n- `skills\u002Fsoftware-development\u002Fpublic-contribution\u002FSKILL.md` — PII→placeholder mapping table for contributions\n",{"name":5,"tags":24,"version":31,"category":26,"description":7},[25,26,27,28,29,30],"pii","security","git-filter-repo","history-rewrite","credentials","secrets","1.0.0","main","9dc0e92c5fa81d4db5292b205716e8ea0c00d10e","skills\u002Fsecurity\u002Fpii-scrubbing",1,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet","steadfaste.com","https:\u002F\u002Fgithub.com\u002Flukemcqueen","AI Architect | Building Hermes Cortex: governed multi-agent AI for autonomous software engineering | Enterprise Tech Consultant","2026-11-14 22:33:34",{"source":8,"skillName":5,"commands":42,"prompt":52,"zipAvailable":53},[43,46,49],{"tool":44,"command":45},"npx","npx skills add lukemcqueen\u002Fsteadfaste-fleet --skill pii-scrubbing",{"tool":47,"command":48},"bunx","bunx skills add lukemcqueen\u002Fsteadfaste-fleet --skill pii-scrubbing",{"tool":50,"command":51},"pnpm","pnpm dlx skills add lukemcqueen\u002Fsteadfaste-fleet --skill pii-scrubbing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fsecurity\u002Fpii-scrubbing\u002FSKILL.md",true,[],[56,64,71,78,85,92],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":60,"categories":61,"keywords":62,"publishedAt":63},"01M7DXY4G8NSVB59K8B6S2AQNP","macbook-linux-maintenance","Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fmacbook-linux-maintenance\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":63},"01M7DXXYJCXFJ3TGB84ZQ8KFE6","governance-regression-triage","Triage a host's governance issues: what changed.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fgovernance-regression-triage\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":63},"01M7DXXSAP1G8FDRJAMXQGBBMK","enforcement-immutability","Use when enforcement files lose their immutable flag.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fenforcement-immutability\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":63},"01M78SSDQVRYX64Y16X32TC0NS","steadfaste-fleet-repo-deploy","Use when committing to the steadfaste-fleet repo.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-repo-deploy\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":63},"01M78SS928F3R2RJAYVW4E30CE","steadfaste-fleet-maintenance","Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Fsteadfaste-fleet-maintenance\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":63},"01M78SP1CHW0T0BWE5ZT6JBPX8","fleet-preflight","DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its \"Repo-Specific Pre-Flight\" section covers git search, Hermes boundary, and deployment verification.","https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Ffleet-preflight\u002FSKILL.md",[],[]]