[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M758FMCTV99QRPM0B3WQQASD":3,"skill-same:01M758FMCTV99QRPM0B3WQQASD":89},{"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":42,"commitSha":43,"skillDirectory":44,"forksCount":45,"repositoryHtmlUrl":46,"repositoryHomepageUrl":47,"ownerHtmlUrl":48,"ownerBlogUrl":6,"ownerDescription":49,"updatedAt":50,"install":51,"resources":64},"01M758FMCTV99QRPM0B3WQQASD","rename-sweep",null,"Fleet-wide term\u002Fartifact renames and decommission sweeps.","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\u002Fdevops\u002Frename-sweep\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: rename-sweep\ndescription: Fleet-wide term\u002Fartifact renames and decommission sweeps.\nversion: 1.0.0\ncategory: devops\nplatforms: [linux, macos]\nmetadata:\n  hermes:\n    tags: [rename, sweep, decommission, migration, bulk-edit]\n    related_skills: [change-checklist, survey-before-action, enforcement-change-safety, cortex-bus]\n---\n\n# Rename Sweep — Fleet-Wide Terminology\u002FArtifact Renames\n\nSystematic method for removing or renaming a term, product name, or artifact\nacross an entire repo (decommission, rebrand, terminology migration — e.g.\nthe 2026-08-21 legacy-system→mycortex purge: 168 files, 0 residual tokens). The\nhard part is NOT the replacement — it is the compound tokens the catch-all\nmisses, the mangled tokens the guards create, and the deleted-file\ncross-references that silently break tests and indexes.\n\n## When to Use\n\n- User says \"remove ALL references to X\", \"rename X to Y everywhere\", or a\n  product\u002Fcomponent is decommissioned and must be purged.\n- A handoff\u002Fproposal claims a rename is \"done\" but the branch never landed —\n  you must verify and often redo the sweep fleet-side.\n- Don't use for: single-file renames (patch it), or docs-only path fixes\n  (documentation-auditing covers stale paths).\n\n## Prerequisites\n\n- A governance lock (`begin_change`) — write tools block without it.\n- Adversarial-verifier loaded (pre-commit blocks changed `ops\u002F` paths).\n- Enumerate the surface FIRST: `git grep -i \u003Cterm>`, files named `*\u003Cterm>*`,\n  deployed copies (`~\u002F.steadfaste-fleet\u002Fscripts\u002F`), cron jobs (`jobs.json`),\n  live configs. 200+ matches across 100+ files is normal for a real sweep.\n\n## Procedure\n\n### 1. Classify every occurrence into three buckets\n\n| Bucket | Meaning | Action |\n|--------|---------|--------|\n| Functional | Keys, var names, service names, CLI commands, DB\u002Frole names, paths in code | Replace with the new term (exact tokens) |\n| Dead artifact | Files\u002Fdirs\u002Fskills whose whole purpose was the old term | `git rm` |\n| Historical | Dated docs, transcripts, review reports, design comparisons | Rephrase to a neutral descriptor (\"the legacy brain\"), never the new term |\n\nDelete the dead artifacts FIRST (git rm), then sweep references to them — but\nverify a suspected DUPLICATE tree is really a duplicate before `rm -rf` (see\nPitfalls: a copy can hold the only copy of some files).\n\n### 2. Replacement engine — guards BEFORE catch-all, in one ordered pass\n\nBlind `term → newterm` breaks everything. Use this order per file:\n\n1. **Exact functional tokens** (case-sensitive, applied first): keys\n   (`legacy-system_sources_ok`), var names (`V_LEGACY_SYSTEM`), file\u002Fservice names\n   (`import-legacy-system.py`, `com.legacy-system.autopilot`), env vars\n   (`LEGACY_SYSTEM_PG_PASSWORD`), issue keys. A word-boundary catch-all\n   (`\\blegacy-system\\b`) MISSES underscore compounds (`legacy-system_search`,\n   `legacy-system_legacy_*`, `FIXED_LEGACY_SYSTEM`) — list them explicitly.\n2. **Phrase guards** (case-insensitive): \"X decommissioned\u002Fdeprecated\" →\n   \"legacy …\", \"(X replacement)\" → dropped, \"X→new\" → \"legacy→new\".\n3. **Mode-aware catch-all**: case-preserving replace of the bare word —\n   \"mycortex\" in functional\u002Factive files, \"legacy brain\" in historical files.\n4. **Skip surgical files** (register lines, stub removal, service-check\n   deletion, test guards) and edit them by hand after the bulk pass.\n\n### 3. Mangle scan (mandatory after the bulk pass)\n\nGuards with spaces mangle compound tokens. Grep for these and fix:\n\n- Space inside a token: `install-legacy sync.sh`, `~\u002F.legacy brain`,\n  `com.legacy brain.sync-watch`, `garrytan\u002Flegacy brain` (broken URL),\n  `main.legacy brain` — re-slug to `legacy-brain`.\n- Case-insensitive label guard swallowed a COMMAND: `\"Legacy Sync\"` guard\n  also matched `legacy-system sync --source X` → `\"Mycortex Sync --source X\"`.\n  Scan for title-case command garbles; the CLI command is lowercase.\n- Catch-all hit a path that meant the OLD home dir: `~\u002F.legacy-system` →\n  `~\u002F.mycortex` (wrong product!) — paths must map to the neutral slug.\n- `\\bterm\\b` misses `term_compound` — the residual grep catches these;\n  fix each with an exact-token replacement.\n\nFinish with `git grep -i \u003Cterm>` == 0 AND a token-mangle grep\n(`legacy brain\u002F`, `install-legacy `, `~\u002F.legacy `) == 0.\n\n### 3b. Sweeping a PATH, not just a bare term\n\nWhen the target is a file PATH (`~\u002F.dir\u002Fold.conf` → `~\u002Fnewdir\u002F.env`), the\nreplacement changes BOTH the directory and the basename. A bare-filename\ncatch-all (`old.conf` → `.env`) then rewrites variable- and call-composed\nforms into paths that still aim at the OLD directory:\n\n```python\nOLD_HOME \u002F \"old.conf\"                  →  OLD_HOME \u002F \".env\"          # ✗ old dir!\nPath.home() \u002F \".dir\" \u002F \"old.conf\"      →  Path.home()\u002F\".dir\"\u002F\".env\" # ✗ old dir!\n```\n\nEnumerate the FORMS first, then give each its own rule, most specific first:\n`$HOME\u002F.dir\u002Fold.conf`, `${VAR}\u002Fold.conf`, `~\u002F.dir\u002Fold.conf`, `%h\u002F.dir\u002Fold.conf`,\n`Path.home()\u002F\".dir\"\u002F\"old.conf\"`, `HOME\u002F\".dir\"\u002F\"old.conf\"`, `.dir\u002Fold.conf`,\nand only then the bare basename.\n\n**A PATH sweep aimed at the home dir must cover the ABSOLUTE spellings too, not just the `~\u002F` form.** A pass that replaces `~\u002F.old` \u002F `.old` rewrites only the tilde spellings; the `${HOME}\u002F.old`, `$HOME\u002F.old` spellings are the SAME physical path under a different token, and a `~\u002F`-grep leaves them untouched — the close reviewer counts them as an incomplete sweep and files a finding. Put every home-expansion spelling in the form list and sweep them ALL in the same pass; then residue-grep each spelling independently.\n\nFinish with the residue grep — the NEW\nbasename still sitting in the OLD directory\n(`grep -rnE '\"\\.dir\" *\u002F *\"\\.env\"'`) — that grep, not the old-name grep, is\nwhat finds these mangles. Dry-run the table and read the plan before writing.\n\n**A file RENAME has the same trap with no path form in it at all.** When the swept token is a\nwhole path (`docs\u002Ftemplates\u002Fskills.yaml` → `skills.yaml`), every site that BUILDS that path\nfrom segments or a variable never contains the token, so a flawless token sweep leaves them\npointing at a file that no longer exists:\n\n```python\ntemplate_yaml = REPO \u002F \"docs\" \u002F \"templates\" \u002F \"skills.yaml\"   # survives a token sweep\ntemplate_yaml = REPO \u002F \"skills.yaml\"                          # what it must become\n```\n```bash\nMANIFEST_TEMPLATE=\"${TEMPLATES_DIR}\u002Fskills.yaml\"              # survives a token sweep\nMANIFEST_TEMPLATE=\"${REPO_DIR}\u002Fskills.yaml\"                   # what it must become\n```\n\nSo the RESIDUE grep must hunt the CONSTRUCTION, not the old token — and it will read clean if\nyou only grep the old name, because it was clean BEFORE the sweep too. Grep for the last\nunchanged segment followed by the basename (`templates.{0,12}skills\\.yaml`), for the directory\nvariable (`TEMPLATES_DIR.*skills\\.yaml`), and for the joined-segment form\n(`\"templates\" *\u002F *\"skills\\.yaml\"`). Two consumers were dangling in a nine-reference sweep that\notherwise verified clean; that grep is what found them.\n\n### 4. Deleted-artifact cross-reference sweep\n\nDeleting files breaks things that assert their existence:\n\n- **DOCS-INDEX.md** entries for deleted docs\u002Fscripts (remove the rows).\n- **Test fixtures** asserting paths to deleted files\n  (`test_golden_expected_paths_exist_in_repo` FAILs on stale expected_top3 —\n  delete the stale query entry, keep count invariants like \"25-30 queries\").\n- **register() lines** in fleet-update.sh for deleted scripts (remove both\n  the line and any update\u002Fstub functions that call them).\n- **Skills referencing the deleted skill** (governance-sentinel listed\n  legacy-system-maintenance) — reword or drop the pointer.\n- **Deployed copies**: after deploy, `rm` stale deployed artifacts the\n  doctor flags (\"Remove: …\" in REQUIRED ACTIONS).\n\n**Not every occurrence is a LIVE reference — committed RECORDS must survive the sweep.**\nEvidence captures, transcripts and dated reports quote the old path as the thing that WAS run at\nthat revision. Rewriting one falsifies a record and breaks the checksum it carries, so exclude those\ndirectories from both the replacement pass AND the residue grep — and PRINT the exclusions beside\nthe count. A bare \"0 residuals\" that silently skipped a directory reads as coverage of everything,\nwhich is the same class of over-claim as a stale token left in place. Coverage is also\nper-PATTERN-CLASS: a content grep covers content, never filenames, and a content-only lint does\nnot cover what a future reader can rename — an audit report must either check the filename class\nor state explicitly that it did not; an unsourced \"every remaining reference is accounted for\"\nwith no bucket list invites the probe that finds the miss.\n\n**A PRINTED remedy is a live reference.** A check or warning that tells the operator to run a command\nis held to the same standard as code: if the string names a path that does not exist, the operator\nlands on a dead command. Resolve every printed fix\u002Fwarn path against the DEPLOY MAP's target rather\nthan the repo layout — deploys flatten and nest differently, so `\u003Cdeploy>\u002Fscripts\u002Fmanage\u002F\u003Cx>.py` can\nbe wrong while `\u003Cdeploy>\u002Fscripts\u002F\u003Cx>.py` is right, in the same file. Sibling printed paths may be\ncorrect exactly as they stand: check each one instead of \"tidying\" the directory component off all\nof them.\n\n### 5. Verification battery\n\n- `bash -n` every changed .sh; `py_compile` every changed .py; validate\n  JSON\u002FYAML (deleted files show as FAIL — ignore them, they're gone).\n- Adversarial gate A2 on every changed script.\n- Run the test suites that touch deleted paths (parity\u002Fgolden tests).\n- Live-service tests fail on deploy-order lag: a running service still\n  serves the old label until `fleet-update.sh` redeploys — verify against\n  the repo, not the live service, then re-test after deploy.\n- `git grep -i \u003Cterm>` == 0, doctor clean, deploy via fleet-update,\n  then push.\n\n### 6. Land it fleet-wide — 0 residuals is NOT done\n\nA sweep that only changes files is finished on YOUR host and broken\nelsewhere. A fleet-wide rename\u002Fconfig move is done when every other host\nconverges without a human, and agents can see what changed. Ship all four\nwith the sweep, in the same change:\n\n1. **An automatic per-host migration** on the update path — make the deploy\n   script RUN the consolidation (idempotently) before anything reads the moved\n   thing, and make the migration script seed the new location from the old one\n   rather than failing when it is absent. A host that still has only the old\n   layout must self-heal on the next `fleet-update.sh`.\n2. **An enforcement check in the doctor** — FAIL on the new invariant (target\n   exists, right perms, old path absent or a symlink to it, and a `fix:` line\n   naming the exact script to run). A sweep with no check silently regresses\n   the first time someone recreates the old artifact.\n3. **A runbook** (`docs\u002Frunbooks\u002F\u003Ctopic>-migration.md`) — the convention table\n   (which path is canonical, which are symlinks, which are not ours), how to\n   apply on Linux AND macOS, how to verify, the changes to implement, and a\n   symptom→cause→fix table. Index it in DOCS-INDEX.\n4. **Agent-facing skill notes** — update the setup\u002Ftroubleshooting skill the\n   agents actually load, and fix any prose your own sweep mangled (check every\n   line you rewrote reads sensibly; a rename can turn a sentence into a\n   tautology).\n\n5. **A per-host file the deploy APPENDS to is never pruned.** A deploy that writes a\n   line only when absent (`grep -q '^NEW=' f || printf 'NEW=…\\n' >> f`) cannot remove a\n   line an earlier release wrote, so a retired name survives every deploy forever and the\n   host reads as half-migrated indefinitely (measured: a legacy interpreter line sat in a\n   per-host env file through months of deploys). The deploy must REWRITE that file to the\n   new invariant — read it, drop the retired lines, write it back — and the doctor needs a\n   FAIL naming the retired name with the repair command.\n6. **Fix the GENERATOR, not its output — then gate the generator.** When the swept names\n   live in GENERATED artifacts (per-harness READMEs, unit files, generated manifests),\n   editing the artifact is a no-op: the next regeneration restores the old names. Fix the\n   generator's template, regenerate, and commit both. Then add the generator's own\n   `--check` to the lint, because a generator whose input was renamed but that was never\n   re-run keeps shipping the retired names behind a GREEN repo grep — the generated file\n   exists and reads plausibly. A content sweep of generated files is not coverage of the\n   generator.\n7. **Classify the surviving names, and let only EXTERNAL CONTRACTS survive.** After the\n   final release the legitimate keeps are: the converter\u002Fforwarder tool that must name the\n   spelling it converts, comments describing the migration, and the names a runtime you do\n   NOT own injects across the process boundary. Whitelist those BY NAME in the lint; every\n   other surviving token is residue. Report live surfaces separately from test\u002Frecord ones\n   so one repo-wide count does not mix deliberate keeps with real stragglers.\n\nThe user WILL ask \"will agents be able to implement this?\" if you skip 1–7 —\ntreat that as part of the deliverable, not a follow-up.\n\n## Pitfalls\n\n- **A file rename is not done until the CONSUMER layers that reference the artifact by name are swept — doctor's harness-verify + MCP-wiring checks are the canaries.** Renaming a deployed artifact (an MCP script, a harness extension file) while its registry\u002Fverify\u002Finstaller entries and the per-host MCP registration still name the old path leaves a GREEN repo grep and a RED doctor: `Harness (x)` FAILs on the missing old path, `MCP wiring (y)` FAILs because a registered script path no longer exists. Sweep EVERY layer that writes the name in the same change — `harnesses\u002Fregistry.yaml`, the verify\u002Fgovernance-check scripts, installer `resolve_ext`\u002FOURS tool lists, tests, docs, skills — plus the per-host `~\u002F.hermes\u002Fconfig.yaml` MCP `args` path (`hermes config set mcp_servers.\u003Cname>.args.0 \u003Cnew-path>`, never a raw config write; hosts converge on next install). Then read the FAIL taxonomy: a checksum FAIL on an edited file is just \"not yet deployed,\" but a harness\u002F`MCP wiring` FAIL is real drift that survives deploy.\n  **A verifier that PATH-RESOLVES the renamed artifact is part of the sweep, and it only FAILS on hosts that can execute it.** A harness verifier whose default-under-test path joins `extensions\u002F\u003Crenamed>.ts` (or the mjs entry that imports it) breaks at the import on the hosts that have the loader (an npm-managed pi install), while a host without that loader SKIPS before reaching the path — so a LOCAL green (or a SKIP) is not evidence the sweep reached the verifier, and neither is a repo grep that finds no old token in your own files. Fix the verifier SOURCE path AND re-run it on a loader-capable execution; a verifier that silently skips on the host that ran it leaves the class broken for every host that can.\n  **Rename-aware TEST FIXTURES assert the tool's CANONICAL name list, not the pre-rename spelling.** An audit fixture that registers the old server\u002Fextension name (or an installer test that probes preservation through the old name) makes a healthy synthetic host read FAIL once the tool under test requires the new name — and the reverse: a fixture asserting the pre-rename name passes vacuously when the tool no longer writes it. Re-derive fixture names from the tool's REQUIRED\u002Fowners list (the audit's required-set, the installer's written-server loop, the preservation probe's canonical names), not from the history of what the names used to be.\n- **Renaming an MCP server registration name is a sweep with its own traps** — every name\n  writer in one commit (installers, audits, watchdog maps, enforcer text, doctor wiring maps,\n  tests), rename-not-add by probe binary, `hermes mcp add` is interactive (pipe `printf 'Y\\n' |`),\n  and the rename kills the live session's own `mcp__\u003Cold>__*` tools mid-cycle (CLI close-out\n  with an explicit session_id is the fallback). Full recipe: `references\u002Fmcp-server-name-rename.md`.\n- **A directory that LOOKS like a duplicate copy is not provably one — diff it\n  file-by-file before deleting anything.** The same sub-path appearing twice\n  (`\u003Cdir>\u002Fdocs\u002F…` alongside `\u003Cdir>\u002Fdocs\u002Fnew\u002F\u003Cproject>\u002Fdocs\u002F…`) usually means a\n  stale copy, but the copy can hold files the canonical tree lacks. Hash both\n  trees (`find \u003Ca> \u003Cb> -name '*.md' -exec md5sum {} + | sort`) and print BOTH\n  the duplicate hashes AND the files present in only one tree — in the real\n  case 15 of 38 files were byte-identical while **23 existed only in the copy**,\n  so deleting on the assumption of duplication would have destroyed the only\n  copy of real content. Procedure: merge the uniques up into the canonical tree\n  (preserving relative paths — some may land OUTSIDE the subtree you are\n  keeping, e.g. a sibling `spec\u002F`), then delete only the residual duplicates.\n  The proof is `duplicate hashes == 0` afterwards, not the deletion itself.\n- **A prefix-INSERTION sweep is not idempotent — the new text still contains the\n  old pattern.** Renaming a bare term never re-matches itself; INSERTING a path\n  segment does (`docs\u002F\u003Cx>\u002F` → `docs\u002Folder\u002F\u003Cx>\u002F`), so a second rule in the same\n  pass — or any re-run — matches inside the already-rewritten string and produces\n  `docs\u002Folder\u002Folder\u002F\u003Cx>\u002F`. Guard the replacement with a negative lookbehind\n  (`(?\u003C!older\u002F)docs\u002F\u003Cx>\u002F`) or match only the un-prefixed form, then assert exactly\n  one pass's worth of change before writing.\n- **git stash pop without `--index` silently unstages everything** — the\n  staged index is lost; re-stage with `git add -A` before re-committing.\n- **`git checkout --ours\u002F--theirs \u003Cfile>` during rebase restores the WHOLE\n  file from that side** — auto-merged hunks in that file are reverted (a\n  `--ours` on install.sh reverted an entire 16-file sweep's changes to it).\n  Prefer per-hunk resolution or re-apply and re-verify with grep after.\n- **A sibling push can land mid-sweep** (Moses committed Titus's resend\n  while the sweep ran). The pre-push dogfood gate then blocks with\n  \"Deploy sync — HEAD ahead of last deploy\". Fix: `git pull --rebase`,\n  resolve (the sweep is usually a superset — origin's hunks are fine where\n  cosmetic, re-apply yours where they conflict on substance), deploy,\n  doctor, re-push. Check `git log origin\u002Fmain -3` before pushing a big\n  change. If `git pull --rebase` refuses on UNSTAGED changes a peer left in\n  flight, `git pull --rebase --autostash` carries them through and re-applies\n  them automatically — never `checkout`\u002F`stash` the peer's working tree away,\n  and never commit their edits alongside your sweep. After the rebase,\n  `git status` should still show their edits uncommitted.\n- **Fence corruption is pre-existing, not yours**: the pre-commit fence\n  check may flag an unbalanced file you merely touched. Verify at HEAD\n  (`git show HEAD:\u003Cfile> | grep -c '^```'`) before fixing; a dangling\n  opener at EOF gets removed, not closed.\n- **The word count in PII scans includes pre-existing patterns** — diff\n  the flagged lines against what you actually changed before claiming\n  your sweep introduced PII.\n- **Exclude the tool that PERFORMS the migration.** A script that merges the\n  old artifact into the new one legitimately references the old name (its\n  idempotency check depends on it). A blanket rename breaks the very mechanism\n  you are migrating to — add it to the skip list explicitly, and say so in the\n  commit message so a later reader does not \"fix\" it.\n- **Exclude the tool that DETECTS and REPORTS the old artifact.** A checker or\n  doctor check whose *message* names the old path must keep that literal — there\n  the old name is the SUBJECT of the sentence, not a reference to a path. A\n  blanket replace turns `stray ~\u002Fold\u002Fdir\u002F.env` into a message naming the\n  CANONICAL file: a tautology that now misreports which path is wrong.\n- **Exclude the skill that TEACHES the sweep itself.** A how-to\u002Frename skill whose worked example uses the old term as the EXAMPLE (a mapping line, a migration command) must be kept out of the blanket sweep: a path-token replace rewrites BOTH sides of its `old → new` mapping to the new term — the mapping inverts to `new → new` and the worked example silently disappears (measured: a device's own rename-sweep example corrupted this way; revert the file and re-exclude it). Pull such a file to a fixed baseline before sweeping, keep it out of the residue grep, and say so in the commit message so a later reader does not \"finish\" the sweep on it. **Keep it out of the residue LINT too — and expect that lint to re-flag the file long after the sweep.** A gate that greps `skills\u002F` for the retired token has no concept of a teaching reference, so it fires on this file on every run; when the sweep is long finished and the ONLY failure is that reference, the choice between generalizing its sample tokens to the wildcard family form (which does not match a `PREFIX_[A-Z0-9_]+` pattern) and exempting it by path in the lint is an operator gate-scoping call — report it with the one action that clears it, never re-scope the gate yourself and never wave the file through as obviously-fine residue.\n  **Nothing re-reddens a finished sweep faster than a later skill-lesson BACKPORT.** A lesson file copied into the repo from the deployed tree carries whatever tokens it was written with, so it can turn the brand lint red long after a green sweep with every host surface still clean — attribute a fresh lint failure with `git log --diff-filter=A --oneline -- \u003Cflagged file>` before suspecting the original sweep.\n- **A stranded (deployed-only, repo-source-missing) skill you inherit is a PRE-RENAME SNAPSHOT until the grep says otherwise — classify DELETE vs sweep+backport per file before \"making it local\".** A dir in `~\u002F.steadfaste-fleet\u002Fskills\u002F\u003Ccat>\u002F\u003Cname>\u002F` with no `git ls-files` source is exactly what the deploy never pruned. Classify each: a dir whose frontmatter duplicates a live repo skill (same `description`, a rename runbook documents it) or that teaches a fully-superseded layout is DEAD — delete the deployed dir, ship no backport; a genuinely-distinct skill keeps its value but its body carries the old brand (`~\u002Fold-name`, `OLD_*` env vars, `old-\u003Ctool>.sh`, `author: Old Brand`), so sweep the tokens to the new spelling, VERIFY each new path\u002Fflag\u002Fenv actually exists (the sanctioned unlock flag is `--\u003Cnew>-update`, the env `FLEET_DEPLOY_HOME`, the script `\u003Cnew>-dogfood.sh` — never invent an equivalent), then backport and RE-RUN the brand lint: a reused old env token turns the retired-spelling gate red on the newly added files. `reconcile-stranded-skills.py` will NOT list these — it reports same-file SKILL.md DRIFT (a deployed superset to backport), never a whole dir missing from the repo; find missing dirs with `comm -13 \u003C(ls \u003Crepo>\u002Fskills\u002F\u003Ccat>) \u003C(ls \u003Cdeployed>\u002Fskills\u002F\u003Ccat>)` plus `git ls-files | grep -i \u003Cname>`.\n- **A stale CLI reference in a doc is fixed with the ACTUAL entry point, not the doc's claim — grep the tool's own usage and the dispatcher before writing the corrected command.** `git grep` the alleged subcommand in the real command module; if absent, read the implementing script's own `--help`\u002Fusage line and write that invocation verbatim.\n- **A clean residue grep does not prove the surviving text is TRUE.** It only\n  proves no old token survives. This is the code-side twin of the prose-mangle\n  check in step 6.4 — re-read every string the run changed, error\u002Fwarning\n  message strings included, and confirm each still describes what it claims.\n- **Tool output can REDACT credential-shaped strings, so a replacement that reports 0 matches for a string you can SEE is a red herring — compare BYTES before believing the file differs.** An env-var name such as `$FLEET_BUS_TOKEN` renders intermittently redacted (e.g. `$CORTE...KEN`) across tool outputs, and trusting the rendered read made a sweep mis-target a replacement for several turns. Assert every replacement count against the RAW read (`txt.count(needle)`), and when any comes back 0, re-read the exact bytes (`repr(segment)` \u002F `needle.encode()`) — the count, not the display, is what proves whether the token is present and where.\n- **When the swept term is a REAL WORD (not an acronym\u002Fslug), the catch-all renames\n  it inside unrelated domain language — and the residue sits under the NEW token,\n  so the old-name grep reads clean.** `cortex` is a medical\u002Fneurological term as\n  well as a product name: a `cortex → fleet` sweep rewrote \"auditory cortex\",\n  \"motor cortex\", \"prefrontal cortex\" into \"auditory fleet\", \"motor fleet\", … in\n  an EEG\u002FBioSignal reference doc — a healthy-looking mangle the old-token grep\n  cannot see because the token is gone. Grep the NEW token in NON-code\u002Fprose and\n  domain-specific files (`skills\u002Fhealth\u002F…`, any doc full of the plain noun) and\n  re-read occurrences that were never the product token; better, scope the\n  catch-all to the token CLASS (uppercase `CORTEX_*`, the slug `cortex-`\n  compounds) and sweep the bare lowercase word only in code\u002Fvar contexts, never\n  in prose. A word-boundary catch-all on a shared English word is the highest-\n  entropy mangle class because the residue is invisible to its own proof grep.\n- **Renaming a BARE IDENTIFIER (a var\u002Ffunction name) needs a full word-boundary\n  on BOTH sides — a space-anchored replace splits assignments from usages into\n  NameErrors you introduced.** `term ` (word + trailing space) rewrites `x = …`\n  assignments but not `x.attr`, `x)`, `{x}`, or `x.method(…)` usages (no space\n  after the token), so the renamed assignment and the untouched usages diverge.\n  Rewrite with `(?\u003C![A-Za-z0-9_])term(?![A-Za-z0-9_])`, then AUDIT for split\n  files: grep every touched code file for the NEW identifier in an assignment\n  position AND a bare OLD identifier, and fix both sides consistently (a sweep\n  that changes the same local name across 60+ tests and scripts is exactly where\n  this bites).\n- **When the swept token is a DIFFERENT abbreviation in some files, don't force\n  the target's new name — give the colliding local variable a DESCRIPTIVE\n  name.** A token that is the product\u002FCLI name in most files (e.g. `hc` the bus\n  CLI) can be an unrelated local abbreviation elsewhere (`hc` = a HealthCheck\n  instance, `hc` = hymn count). Renaming those to the CLI's new name (e.g.\n  `fleet`) is misleading scope-drift an adversarial reviewer will flag; use a\n  name that states the variable's meaning (`healthcheck`, `hymn_count`) instead.\n- **Exclude same-basename files in other directories.** `~\u002F.dir\u002Fconf.d\u002Fold.conf`\n  and `~\u002F.other\u002Fold.conf` are DIFFERENT files; a basename rule rewrites them\n  happily. Guard per-line on the full distinguishing path, and verify the\n  genuine ones survived.\n- **After a path sweep the repo can still WORK while being wrong.** A symlink\n  at the old location hides every missed reference until the symlink is\n  removed — so residue-grep the source, then remove the symlink deliberately,\n  never assume \"the tests pass\" means the sweep is complete.\n- **A home-dir rename leaves PHANTOM old paths in compiled bytecode — a traceback naming the\n  old dir with `??` source lines is `.pyc`, not source.** Python's `__pycache__` caches modules\n  compiled before the rename; the bytecode embeds the pre-rename absolute path, so a failing\n  test or import after a clean sweep still raises `FileNotFoundError: …\u002Fold-dir\u002F…` (or a\n  failing test asserts a deliberately-removed constant and reads as a phantom regression).\n  Confirm with `strings \u003Cfile>.pyc | grep \u003Cold-path>` — a source grep returns 0 while the pyc\n  greps hit — then delete the `__pycache__` dirs: they regenerate on next import, and removal\n  is the only fix that makes the phantom disappear. Sweep host-wide, not just in the repo: the\n  deployed tree's stale pyc files are what a live traceback actually shows.\n- **A home-dir rename leaves venv console-script shebangs pointing at the OLD\n  interpreter — every wrapper dies with `bad interpreter` on first use.** A venv\n  re-created at the new path still has `bin\u002F*` wrappers whose `#!` line names\n  the pre-rename interpreter, so `pytest`, `pip3`, `uvicorn`, … fail with exit\n  127 while the venv's own `bin\u002Fpython3` is fine — and the first tool a\n  verification run reaches (pytest) is exactly the one that dies, so the suite\n  looks broken before it starts. Immediate workaround: `bin\u002Fpython3 -m \u003Ctool>`\n  (the interpreter itself is unaffected). Fix in place, never re-create the\n  venv: `grep -rl '\u003Cold>\u002Fvenv\u002Fbin\u002Fpython3' ~\u002F.steadfaste-fleet\u002Fvenv\u002Fbin | xargs\n  sed -i \"s|#!.*\u003Cold>\u002Fvenv\u002Fbin\u002Fpython3|#!${HOME}\u002F.steadfaste-fleet\u002Fvenv\u002Fbin\u002Fpython3|\"`,\n  then re-grep → 0. The sed replacement must be DOUBLE-QUOTED so the shell\n  expands `${HOME}` — a literal `${HOME}` can never stand in a shebang (the\n  kernel does not expand variables there). Add this to the migration runbook's\n  cleanup list; it is a distinct residue class from stale `__pycache__`.\n- **A background result can be SUPERSEDED — check it is the latest run before\n  acting.** A long test\u002Fdeploy run finishing late reports the tree from when it\n  STARTED. Two completion notices can disagree (an older 7-failure run landing\n  after the fixed 5-failure run). Compare against the current HEAD and re-run\n  the pair\u002Fsuite if in doubt; never report a stale FAIL list as the state, and\n  never \"fix\" what a superseded run complained about.\n\n- **`git mv` needs the destination's PARENT directory to exist, and the error names the SOURCE.**\n  `git mv a\u002Fb\u002Fc a\u002Fb\u002Fbin\u002Fc` answers `fatal: renaming 'a\u002Fb\u002Fc' failed: No such file or directory` —\n  pointing at a file that is right there. `mkdir -p` the new directory first. Once the rename is\n  staged, the OLD path can no longer appear in a pathspec (`git add \u003Cold>` \u002F `git commit -- \u003Cold>`\n  → `pathspec '…' did not match any files`): stage\u002Fcommit the live paths, or omit the pathspec and\n  let the staged rename carry the deletion.\n- **`git diff --cached --name-only` collapses renames to their NEW path — a\n  pathspec commit of a rename sweep silently leaves the deleted sources staged\n  and uncommitted.** When you commit with `git commit -m … -- $(git diff\n  --cached --name-only)` (the name-your-paths gate route), rename detection\n  drops the deleted `old\u002F…` entries from the list, so HEAD still contains them\n  and the old dir survives the commit. Collect the pathspec with\n  `--no-renames` (`git diff --cached --name-only --no-renames`) so deletions\n  are included, then verify after the commit that `git ls-tree HEAD\n  -- \u003Cold-dir>` is empty and `git status` is clean.\n- **A launcher or executable moved into a subdirectory needs its self-relative module resolution\n  changed in the SAME commit.** See `shell-scripting` → \"Moving an executable\": without it the\n  script silently runs a different tree's module through its known-path fallback, and every test\n  that runs the installed copy still passes.\n\n- **A green doctor does NOT mean a home-directory rename ran.** Renaming a live\n  deployment's dirs (`~\u002Fhermes-cortex` → `~\u002Fsteadfaste-fleet`, `~\u002F.hermes-cortex`\n  → `~\u002F.steadfaste-fleet`) ships a guarded migration script + a golden-path\n  verifier, but deploying the code does not execute the rename. Verify on the\n  host: `FLEET_DEPLOY_HOME` still unset ⇒ `fleet-update.sh` still defaults to\n  the OLD `~\u002F.hermes-cortex`; no transition symlink yet; the old dirs are real\n  dirs, not symlinks. Those symptoms mean \"the code landed, the rename has NOT\".\n  A host that still runs everything off the old paths is not a failed rename —\n  it is a host that is correctly NOT yet migrated.\n- **The local-dir rename is gated: dogfood host FIRST, fleet in a SEPARATE rollout\n  cycle, and the code-default path change is held back until the fleet migrates.**\n  A rename plan written for one dogfood host (verifier named `verify-rename-\n  \u003Chost>.sh`) deliberately does NOT apply to the rest yet. Before \"finishing\" a\n  rename on any non-dogfood host, check the plan's rollout step: it may mandate\n  esther-green first and a separate fleet dispatch, with the deploy default in\n  `fleet-update.sh` (`FLEET_DEPLOY_HOME=\"${HOME}\u002F.hermes-cortex\"`) deliberately\n  unchanged until every host has migrated (so the 4 agents' next deploys stay\n  consistent).\n- **Confirm the repo rename landed by `git ls-remote` on BOTH the old and new\n  URLs returning the same HEAD** — GitHub auto-redirects the old name, so equal\n  HEADs prove the native rename happened and the old URL is an alias, not a\n  second repo. But note the renamed repo's HEAD can be AHEAD of a given host's\n  last pull; pull to current before running any migration script so you deploy\n  from the latest version.\n- **Never run a home-dir migration under an in-flight deploy writing to that same\n  dir.** A `fleet-update.sh` mid-run is reading\u002Fwriting `~\u002F.hermes-cortex`;\n  moving the directory out from under it breaks both the deploy and the rename.\n  Wait for the deploy to finish (poll its log for `UPDATE_EXIT=0` and the doctor\n  verdict) before `migrate-home-dirs.sh`. `migrate-home-dirs.sh` also refuses to\n  run from inside a source dir (`cwd` guard) — run it from a stable workdir.\n- **`install-crons.sh` regenerates the bridge\u002Fbus units but NOT the Hermes-owned\n  gateway + dashboard units — hand-patch those, or the golden-path \"0 old tokens\"\n  unit scan stays red.** After regenerating units with `FLEET_DEPLOY_HOME`\n  overridden to the new path, `grep -Rl '\\.hermes-cortex' ~\u002F.config\u002Fsystemd\u002Fuser`\n  still returns the `fleet-gateway.service` + `hermes-cortex-dashboard.service`\n  live units (plus the gateway's `default.target.wants` symlink), which the cron\n  installer never writes. Rewrite their `ExecStart`\u002F`WorkingDirectory`\u002Flog paths\n  to the new deploy-home directly. Discrimination that matters: the verifier\n  greps the DOTTED deployed-home token (`\\.hermes-cortex`), so a bare repo-path\n  token (`%h\u002Fhermes-cortex`, no leading dot) is ALLOWED through the transition\n  — it resolves via the symlink; only the dotted token must reach zero.\n- **A golden-path verifier FAIL can be a host-layout difference, not a rename\n  regression — verify the service by port\u002Fprocess before treating a unit-state\n  FAIL as a break.** A verifier written for the dogfood host assumes a service\n  runs as a systemd unit; the same service can run as a loose process on another\n  host with its unit never enabled (`systemctl --user is-enabled …` → disabled,\n  pre-existing). Before calling the rename failed on an `inactive` unit check,\n  confirm the service is actually alive its own way (`pgrep -f \u003Cserver>.py`,\n  `curl -fsS` to its port → 200) and note the difference as an environmental\n  host difference, not a regression.\n- **Residual old-name tokens are CLASSIFIED, never blanket-swept.** After the bulk pass, the leftover tokens in NON-record files fall into two classes: FUNCTIONAL keeps (one-release shim files, doctor checks that verify the deployed legacy name still works, the enforcer's dual-accept regex, restore\u002Fmigration utilities, a legacy exception flag the enforcer still accepts) and DOCUMENTARY stragglers (a prose line whose sibling on the same line was renamed, a docstring still naming the pre-rename function or command). A blind word-sweep of the residue breaks the migration contract it exists to preserve — the close reviewer flags exactly the documentary class, file by file, and passes the functional keeps. Fix the flagged lines precisely, never the keeps.\n- **A transition shim is a DEADLINE, not a fixture — when the operator declares the migration\n  done, remove the shim and every layer that registers it in the SAME change.** A compat alias\n  kept \"for one release\" outlives its purpose and keeps the old name alive: the file, its\n  register line, brand-lint fixtures, and any skill lesson teaching \"keep the alias\" must all\n  be inverted (transition alias REMOVED) in one commit, or agents keep recreating it from the\n  docs. The definitive completion proof is destructive and operator-driven: delete the old\n  artifact (shim, folders) and re-run the whole battery — a green old-name grep is not proof\n  the old path is not still load-bearing somewhere bytecode or config names it.\n- **A residue grep that matches CONTENT cannot see a FILENAME — enumerate the filename class separately and guard it in the lint.** A brand lint whose patterns are all content (`ops\u002Fscripts\u002F\u003Cold>\u002F`, `scripts\u002F\u003Cold>.py`, `\\b\u003Cold> \u003Cverb>\\b` invocations) leaves every file NAME carrying the old brand untouched: live tests named `test_\u003Cold>_*.py` whose docstrings already say \"Tests for `\u003Cnew>`\" pass the whole battery — only the name is stale (measured: three `test_hc_*` files survived a hermes-cortex→steadfaste-fleet sweep whose lint was 5\u002F5 green). Sweep filenames with a name-based pass (`find tests -name 'test_\u003Cold>_*'`, `git ls-files | grep -i \u003Cold>`), migrate every reference that names them (evidence-runner subprocess lines, comments pinning \"pinned by tests\u002F\u003Cold>.py\"), then ADD a filename guard to the lint itself (`find ... -name 'test_\u003Cold>_*'` fails the suite) so the class cannot silently return. Content coverage does not imply name coverage — say which one the verification actually checked.\n- **A residue COUNT is inflated by every KEEP that CONTAINS the swept term — anchor the family pattern, and check the guard's CASE.** A swept term that is a SUBSTRING of a deliberately-kept sibling is the normal shape (`cortex` inside `mycortex`, `hc` inside a longer word), so a loose pattern counts the keep as residue and overstates the work: the family pattern `CORTEX_[A-Z0-9_]+` matches the `CORTEX_` inside `MYCORTEX_COMPOSE_DIR` and `_MYCORTEX_CACHE`. The fix is a left boundary a word character blocks — `\\bCORTEX_`, equivalently `(?\u003C![A-Za-z0-9_])CORTEX_` — because the character before that `C` is itself a word character, so the keep no longer matches. The same trap survives a negative-lookbehind guard whose CASE does not match the family's: a guard written `(?\u003C!my)` never fires against the `MY` in `MYCORTEX_X`, silently re-inflating the count it was added to prevent. Report counts as `N raw - M keep-substring` and NAME the keep, so a reader can check the subtraction instead of trusting the total.\n- **\"Where are we with the migration?\" is answered by MEASURED SURFACES, never by a plan's status header.** A rename lands in commits, package dirs, unit names, cron entries and per-host env files; the plan \u002F runbook \u002F followups docs keep whatever status line they were written with (`Status: PLAN - not started`, `Release 2 - not yet`, `IN PROGRESS since \u003Cdate>`) long after the landing, so reading them reports the migration backwards. Measure, then report with the source named: `git log --oneline` (did each sweep land, and when), the renamed package\u002Fscript dirs, the unit names under `~\u002F.config\u002Fsystemd\u002Fuser\u002F`, the cron names in `jobs.json`, and a COUNT of the old spelling in each host's `.env` (grep names only, never values). Scope the answer to the hosts actually measured and say which ones you did not reach — a single-host measurement is not a fleet-wide claim.\n  **A doc whose status header contradicts the landed state is a FINDING, not context** — the same class as a superseded \"kept\"\u002F\"deferred\" row. Patch the header and any `not yet` \u002F `not started` section in the sweep's own commit (see `references\u002Fenv-namespace-rename.md` section 6), or the next reader re-derives work that is already done.\n- **An exemption token is PER-LINE — it must sit on the same line as every reference it\n  protects, and the sentence must stay on ONE physical line.** A lint that ignores lines carrying a date token (a migration-record line) judges\n  each line independently: wrapping a long reference onto a continuation line moves the token\n  off the flagged line and the lint fails with no text change. Keep the token on every line\n  that names the old path and re-run until the whole surface is 0 — the clean count is the sum\n  of the per-line decisions. When fixing a flagged record, write the sentence as a single\n  un-wrapped line so a re-flow can never separate the date from the old-path token again.\n- **Live systemd units are part of the sweep surface — and the generator does NOT repair them.** The deploy's orphan-sweep deletes old-named deployed scripts; any live unit whose ExecStart names them fails en masse (one renamed bridge-run script took down 26 generated bridge units at once). Generators that wrote those units SKIP existing ones, so re-running the generator changes nothing. Hand-patch the unit files (new script path + renamed `--script` names), `systemctl --user daemon-reload`, `reset-failed`, then assert 0 failed units and the timers active.\n- **Closing a large rename range is a long governed grind — budget for it, and only the lock-owning session can drive it.** The `end_change` blob-close loop judges ~4 blobs per wave (one 240s window), so a 350-file range is ~90 serial waves (an hour-plus), not minutes. Verdicts are content-keyed: blobs already CLEAN are never re-judged, so each further swept commit only adds its own new blobs to the grind. The per-blob reviewer REFUSES the close on any documentary straggler it finds — fix the named file (a content change re-opens only that blob), commit, call `end_change` again; the loop continues from where it stopped. A subagent CANNOT grind it: a child session's `end_change` with your task_id finds no pending cycle in its own session and mints empty MOVE_ON cycles (ledger pollution) instead of judging — the loop only advances from the session that holds the lock.\n  **A close-gate FINDING may be stale — recorded against an OLDER blob than the current tree — verify the current content before grinding a fix.** Verdicts are keyed to blob content, so a finding the reviewer filed against a pre-fix version (evidence citing a duplicated var, a `CORTEX` literal, a mangled comment) can describe code your later sweep commits already corrected. Before fixing a named finding, compute the file's current sha (`git hash-object \u003Cfile>`) and look up its verdict in the review store — if the current sha has no verdict (or a CLEAN one), the finding is stale and the file may need no change at all; re-emit the close to have the gate re-judge the changed blobs. Checking `blob_reviews` against `git hash-object` first separates the real remaining defects from the historical ones and stops a grind that would otherwise \"fix\" already-fixed files.\n- **A close-gate finding can be CURRENT but its RECOMMENDATION mechanically wrong — verify it against the live function before adopting.** The per-blob reviewer audits the DIFF with quotes stripped, so its \"revert to the original form\" and \"restore the removed line\" suggestions can be wrong or even break the test (it asked to restore a duplicate fixture line that the converter demonstrably does not dedupe — restoring it fails the idempotence assertion the test exists to check). Before adopting a recommendation, run the test against the LIVE function (extract it into a harness with `sed -n '\u002F^func()\u002F,\u002F^}\u002Fp' \u003Csrc>`, add the `warn()` stub, feed the proposed fixture) and adopt only what holds; when you deviate deliberately, say so in a test comment so the re-review sees intent instead of re-flagging the deviation.\n- **A blanket rename damages code and tests in PREDICTABLE shapes — audit for all of them, not just residual tokens.** (a) DEAD SUBSTITUTION: placeholder-`sed`\u002Ftemplate code whose placeholder the sweep renamed away replaces nothing, and may read a STALE duplicate copy of the artifact — a sweep that fixed the kept template copy but not the consumer's source path leaves the installer consuming the un-swept copy (which can still hardcode a per-user absolute path). Point consumers at the kept copy and drop the dead substitution; flag an out-of-range stale copy as a separate issue rather than growing the range. (b) DUPLICATE COLLAPSE: a two-name fallback tuple `(\"LEGACY_X\", \"NEW_X\")` collapses to `(\"NEW_X\", \"NEW_X\")` when the legacy name matches the replacement — the lookup silently checks one var twice and error messages duplicate the name; grep for doubled tokens. (c) CONVERSION TESTS: a test that exercises a converter must keep the OLD spelling in its FIXTURES — blanket-renamed fixtures make it test a no-op — and a \"OLD dropped\" assertion must grep for the OLD spelling (renaming the pattern to the NEW token inverts it into always-fail). Stale headers and labels (\"X ↔ X\" tautology, \"mirror\" labels on a conversion) read as fabrication findings on re-judged blobs — fix them in the same commit as the fixtures.\n- **The close-loop window has NO rename detection — a git-mv file reads as a BRAND-NEW file, and that refusal is un-fixable in content.** The per-blob reviewer materialises a rename pair as delete+add and judges the add as \"new file added to a rename task\" (fabrication\u002Fscope-drift). Every fix commit re-emits that blob and re-audits the SAME artifact, so feeding changes to a renamed file is a loop that does not converge. The resolutions that terminate: (a) commit metadata + an in-range authorization\u002Fevidence record (a committed note that the renames are `git mv` token-swaps and which names are intentionally deferred, with the operator's one exception) for scope-drift findings, (b) operator acceptance of the tooling limitation for the pure new-file artifact, and (c) fix the REVIEWER'S CONSTITUTION when the findings are the reviewer's own blindness, not your content — see the pitfall below. Do NOT keep re-emitting the blob hoping for a fresh verdict on the artifact.\n- **A reviewer-constitution edit is the terminating resolution for a rename-range review flood — and it is an enforcement-layer change in its own right.** When the per-blob reviewer keeps filing the renamed files' PRE-EXISTING teaching as unverified-claim\u002Ffabrication (\"new file, unverified install claims\", \"file teaches the old brand\") and its recommendations drift into renaming live contracts, the loop does not converge no matter how much evidence you paste — each rereview clears 2 blobs, each close pass re-judges the next batch under the same blind rules. The fix (governance-closeout's \"fix the reviewer's constitution\"): add a rule to the reviewer prompt template — `docs\u002Ftemplates\u002Fadversarial-reviewer-prompt.md` (ORCHESTRATOR-ONLY) AND its deployed copy `~\u002F.steadfaste-fleet\u002Ftemplates\u002F` (the reviewer reads deployed-first; the two must be byte-identical), in the same commit. The rule shape that works: \"a renamed file's pre-existing content is CONTEXT, not a claim — judge only what THIS range changed about it (old-brand tokens swept, STALE labels correct, renamed identifiers consistent); the keep-list authority doc (e.g. docs\u002Frename-followups-*.md) is the contract, and tokens it documents as deliberately kept (a live short-name family, a separate live product name, a deliberately-kept service name) are NOT findings.\" The template's text is sha256-fingerprinted as the rules revision, so ANY template edit re-sends every previously-refused blob under the new rules — that is the unblock. Plan-review the template change first (it is enforcement-layer), and note that the new rule must NOT weaken the existing fabrication\u002Funverified-claim standards for content the range actually authored.\n- **Never put a rename-provenance claim in a renamed file's DOCSTRING — the window reads it as fabrication.** A header comment \"renamed from `\u003Cold>` via git mv\" contradicts the window's new-file view (\"the diff shows ADD, the claim says rename\") and is refused even on the exact wording that cleared once. The rename record belongs in the commit metadata (`git log --follow`) and an in-range evidence doc — point the docstring there, or say nothing about the rename at all.\n- **The close reviewer audits renamed scripts' LEGACY internals, and each fix re-opens that file's whole re-audit.** Renamed .sh\u002F.py that predate the sweep get their pre-existing error-swallowing, unverified claims, and external docstring references raked in full — and fixing any one re-emits the blob, re-auditing the rest. Batch the concrete fixes (real trailing-newline, missing dependency pre-check, swallowed `2>\u002Fdev\u002Fnull`, docstring cites to sibling files the window cannot verify) into ONE commit per file, make docstrings self-contained with NO cross-file citations (the window cannot verify a sibling file), and stop after the concrete ones — the deterministic artifacts will not clear.\n- **A gate's KEEP-LIST goes stale the moment the migration lands — sweep it in the same change.** A reviewer constitution, brand lint, or allow-list that still names the swept family as a \"deliberate keep\" is a gate that AUTHORIZES the exact drift it exists to catch: the close reviewer passes the residue, and the residue lint stays green. The only legitimate keeps after the final release are the EXTERNAL CONTRACTS (names a runtime you do not own injects across the boundary), the converter tool itself, and dated records — whitelist those BY NAME and let everything else fail. When a family is renamed, grep the gate surfaces for its name as part of the sweep; a keep entry is not neutral documentation, it is enforcement.\n- **A residue lint must prove it is not blind — and must never swallow its own failure.** Three cheap properties, each of which has been the difference between a real gate and a green tick: (a) ASSERT the surfaces it greps exist — a missing directory or a renamed search root returns no matches, which reads as a clean sweep over nothing; (b) PLANT the exact shape in a temp fixture and require a hit — a detector that never fires is indistinguishable from a clean tree; (c) never `2>\u002Fdev\u002Fnull` the grep — a failed search reads as zero residue. Scope the lint to the INSTRUCTION surface and NAME the excluded directories (dated records, plans, design rationale) beside the result, so the coverage claim is checkable rather than implied.\n- **Red tests are residue too — and a rename-caused stale test can end up testing NOTHING.** Two mechanisms worth sweeping: a test that patches a RETIRED module attribute (`c.OLD_HOME = tmp`) silently CREATES a new attribute while the code reads the renamed one, so the test then exercises live host state and its verdict means nothing (the check reads the real host — the failure detail names real paths, which is the tell); and tests asserting retired log markers or strings go red and STAY red unnoticed when no runner references them (a test file nothing invokes is not coverage). Before declaring any failure pre-existing, reproduce it in a pristine worktree of the range base (`git worktree add --detach \u003Ctmp> HEAD`, same interpreter, same command, both sides) — most rename-caused failures are the test encoding the OLD contract, and rewriting them to the new one converts a long-red suite green. Remove the temporary worktree when done.\n- **A blanket sweep silently breaks the detector's own NEGATIVE FIXTURE — restore the PLANTED token, not the lint.** A lint that proves it is not blind by planting the retired spelling in a temp fixture and requiring a hit gets its plant RENAMED by the same catch-all (the planted `OLD_X=` becomes `NEW_X=`), so the negative test then plants a legitimate token the detector rightly ignores and reports \"the lint is BLIND\" on a healthy gate. The lint's own grep PATTERN usually survives (the regex literal `OLD_[A-Z0-9_]+` is not itself a match), but the planted string is — after any bulk pass, grep the negative fixtures for the retired spelling and restore the plants.\n- **A token-pattern sweep misses three shapes by construction — enumerate them in the residue grep.** (1) EXTENSIONLESS files (a git hook with no suffix) are skipped by `*.py`\u002F`*.sh` include globs; (2) the asterisk PROSE form — a doc that says \"set your `OLD_*` vars\" survives because `*` is not in the token class `[A-Z0-9_]`; (3) the sweep's own REGEX LITERAL in the lint (`OLD_[A-Z0-9_]+` as a pattern string) is not a match. Fix each class with its own grep, never a re-run of the same pattern.\n- **Before choosing the REPLACEMENT token, grep for it — if it already means something else, pick a specific name.** A mechanical `OLD_HOME → NEW_HOME` can collide with a pre-existing `NEW_HOME` convention meaning a DIFFERENT thing (user home vs deploy home across a dozen scripts). Verify the proposed target's current meaning; on a collision, disambiguate per concept (`NEW_USER_HOME`, `NEW_DEPLOY_HOME`, `NEW_REPO_HOME`) — the standard is ONE specific name per meaning, never one generic name for two. A rename that folds two concepts under one token is a naming bug the sweep itself introduces.\n- **A residue lint's FALSE POSITIVE is fixed in the lint, not by renaming the artifact it over-matches.** A substring marker (`\"_CANDIDATES = [\"`) flags a legitimate prefixed list (`_ENV_CANDIDATES` = host env-file paths, not the repo-resource list the check exists to catch). Word-bound the marker (`\\b_CANDIDATES\\s*=\\s*\\[`) and keep the artifact; renaming the variable to dodge the marker hides the check's over-matching and is a probe fix in the wrong layer.\n- **A sweep that touches the enforcement chain (plugins\u002Fgovernance-enforcer) commits it, then every LATER commit is blocked by the DOGFOOD deploy-sync gate** (\"deployed copy differs from committed repo source\") until the enforcer is deployed — the sanctioned unblock is the full `fleet-update.sh`, never a manual copy. Budget the deploy before the next commit, or land the enforcer change separately and deploy it immediately.\n- **Commit a large sweep in LOGICAL CHUNKS (source → tests → docs), not one giant commit — the operator's explicit preference.** Per-chunk commits keep each blob reviewable by the close gate and give the operator checkpoints to react to; when a deploy gate blocks one chunk, the rest can still land and the deploy happens once.\n- **A host-wide core.hooksPath fires the fleet pre-commit inside pytest temp repos and REFUSES bare\u002FAGENTS.md-less commits — isolate the suite with a session-autouse GIT_CONFIG_GLOBAL fixture.** Point `GIT_CONFIG_GLOBAL` at a minimal config (identity only, no hooksPath) so throwaway repos commit freely; the fleet repo is unaffected (its hooksPath is repo-local), and hook-behaviour tests opt back in per-repo (`core.hooksPath = …\u002Fhooks`). This one fixture clears the whole class of temp-repo setup failures that look like a dozen unrelated test bugs.\n\n- **`git fetch origin` is write-class and trips the lock gate — don't pre-check\n  for new commits with it.** Opening a full governance cycle just to see whether\n  the remote moved is overkill; `git rev-parse origin\u002Fmain` reads the last\n  fetched ref and the pull itself fetches. If you must compare before opening a\n  cycle, read the lock-free primitives (`git rev-parse HEAD origin\u002Fmain`,\n  `git status -sb`) and treat that ``behind N`` as \"open the cycle and pull\", not\n  a reason to fetch first.\n\n## Verification\n\n- `git grep -i \u003Cterm>` returns 0 (tracked tree).\n- Token-mangle grep returns 0.\n- Tests that assert paths\u002Ffixtures pass.\n- Deployed copies clean; doctor shows no ❌; push landed on origin.\n\nSee `references\u002Flegacy-system-to-mycortex-2026-08-21.md` for a worked example:\ntoken list, guard table, every mangle class with its fix, and the\nconcurrent-push rebase sequence. See `references\u002Fpackage-rename-with-shim.md`\nfor renaming a python package with a one-release compatibility shim.\n","# Rename Sweep — Fleet-Wide Terminology\u002FArtifact Renames\n\nSystematic method for removing or renaming a term, product name, or artifact\nacross an entire repo (decommission, rebrand, terminology migration — e.g.\nthe 2026-08-21 legacy-system→mycortex purge: 168 files, 0 residual tokens). The\nhard part is NOT the replacement — it is the compound tokens the catch-all\nmisses, the mangled tokens the guards create, and the deleted-file\ncross-references that silently break tests and indexes.\n\n## When to Use\n\n- User says \"remove ALL references to X\", \"rename X to Y everywhere\", or a\n  product\u002Fcomponent is decommissioned and must be purged.\n- A handoff\u002Fproposal claims a rename is \"done\" but the branch never landed —\n  you must verify and often redo the sweep fleet-side.\n- Don't use for: single-file renames (patch it), or docs-only path fixes\n  (documentation-auditing covers stale paths).\n\n## Prerequisites\n\n- A governance lock (`begin_change`) — write tools block without it.\n- Adversarial-verifier loaded (pre-commit blocks changed `ops\u002F` paths).\n- Enumerate the surface FIRST: `git grep -i \u003Cterm>`, files named `*\u003Cterm>*`,\n  deployed copies (`~\u002F.steadfaste-fleet\u002Fscripts\u002F`), cron jobs (`jobs.json`),\n  live configs. 200+ matches across 100+ files is normal for a real sweep.\n\n## Procedure\n\n### 1. Classify every occurrence into three buckets\n\n| Bucket | Meaning | Action |\n|--------|---------|--------|\n| Functional | Keys, var names, service names, CLI commands, DB\u002Frole names, paths in code | Replace with the new term (exact tokens) |\n| Dead artifact | Files\u002Fdirs\u002Fskills whose whole purpose was the old term | `git rm` |\n| Historical | Dated docs, transcripts, review reports, design comparisons | Rephrase to a neutral descriptor (\"the legacy brain\"), never the new term |\n\nDelete the dead artifacts FIRST (git rm), then sweep references to them — but\nverify a suspected DUPLICATE tree is really a duplicate before `rm -rf` (see\nPitfalls: a copy can hold the only copy of some files).\n\n### 2. Replacement engine — guards BEFORE catch-all, in one ordered pass\n\nBlind `term → newterm` breaks everything. Use this order per file:\n\n1. **Exact functional tokens** (case-sensitive, applied first): keys\n   (`legacy-system_sources_ok`), var names (`V_LEGACY_SYSTEM`), file\u002Fservice names\n   (`import-legacy-system.py`, `com.legacy-system.autopilot`), env vars\n   (`LEGACY_SYSTEM_PG_PASSWORD`), issue keys. A word-boundary catch-all\n   (`\\blegacy-system\\b`) MISSES underscore compounds (`legacy-system_search`,\n   `legacy-system_legacy_*`, `FIXED_LEGACY_SYSTEM`) — list them explicitly.\n2. **Phrase guards** (case-insensitive): \"X decommissioned\u002Fdeprecated\" →\n   \"legacy …\", \"(X replacement)\" → dropped, \"X→new\" → \"legacy→new\".\n3. **Mode-aware catch-all**: case-preserving replace of the bare word —\n   \"mycortex\" in functional\u002Factive files, \"legacy brain\" in historical files.\n4. **Skip surgical files** (register lines, stub removal, service-check\n   deletion, test guards) and edit them by hand after the bulk pass.\n\n### 3. Mangle scan (mandatory after the bulk pass)\n\nGuards with spaces mangle compound tokens. Grep for these and fix:\n\n- Space inside a token: `install-legacy sync.sh`, `~\u002F.legacy brain`,\n  `com.legacy brain.sync-watch`, `garrytan\u002Flegacy brain` (broken URL),\n  `main.legacy brain` — re-slug to `legacy-brain`.\n- Case-insensitive label guard swallowed a COMMAND: `\"Legacy Sync\"` guard\n  also matched `legacy-system sync --source X` → `\"Mycortex Sync --source X\"`.\n  Scan for title-case command garbles; the CLI command is lowercase.\n- Catch-all hit a path that meant the OLD home dir: `~\u002F.legacy-system` →\n  `~\u002F.mycortex` (wrong product!) — paths must map to the neutral slug.\n- `\\bterm\\b` misses `term_compound` — the residual grep catches these;\n  fix each with an exact-token replacement.\n\nFinish with `git grep -i \u003Cterm>` == 0 AND a token-mangle grep\n(`legacy brain\u002F`, `install-legacy `, `~\u002F.legacy `) == 0.\n\n### 3b. Sweeping a PATH, not just a bare term\n\nWhen the target is a file PATH (`~\u002F.dir\u002Fold.conf` → `~\u002Fnewdir\u002F.env`), the\nreplacement changes BOTH the directory and the basename. A bare-filename\ncatch-all (`old.conf` → `.env`) then rewrites variable- and call-composed\nforms into paths that still aim at the OLD directory:\n\n```python\nOLD_HOME \u002F \"old.conf\"                  →  OLD_HOME \u002F \".env\"          # ✗ old dir!\nPath.home() \u002F \".dir\" \u002F \"old.conf\"      →  Path.home()\u002F\".dir\"\u002F\".env\" # ✗ old dir!\n```\n\nEnumerate the FORMS first, then give each its own rule, most specific first:\n`$HOME\u002F.dir\u002Fold.conf`, `${VAR}\u002Fold.conf`, `~\u002F.dir\u002Fold.conf`, `%h\u002F.dir\u002Fold.conf`,\n`Path.home()\u002F\".dir\"\u002F\"old.conf\"`, `HOME\u002F\".dir\"\u002F\"old.conf\"`, `.dir\u002Fold.conf`,\nand only then the bare basename.\n\n**A PATH sweep aimed at the home dir must cover the ABSOLUTE spellings too, not just the `~\u002F` form.** A pass that replaces `~\u002F.old` \u002F `.old` rewrites only the tilde spellings; the `${HOME}\u002F.old`, `$HOME\u002F.old` spellings are the SAME physical path under a different token, and a `~\u002F`-grep leaves them untouched — the close reviewer counts them as an incomplete sweep and files a finding. Put every home-expansion spelling in the form list and sweep them ALL in the same pass; then residue-grep each spelling independently.\n\nFinish with the residue grep — the NEW\nbasename still sitting in the OLD directory\n(`grep -rnE '\"\\.dir\" *\u002F *\"\\.env\"'`) — that grep, not the old-name grep, is\nwhat finds these mangles. Dry-run the table and read the plan before writing.\n\n**A file RENAME has the same trap with no path form in it at all.** When the swept token is a\nwhole path (`docs\u002Ftemplates\u002Fskills.yaml` → `skills.yaml`), every site that BUILDS that path\nfrom segments or a variable never contains the token, so a flawless token sweep leaves them\npointing at a file that no longer exists:\n\n```python\ntemplate_yaml = REPO \u002F \"docs\" \u002F \"templates\" \u002F \"skills.yaml\"   # survives a token sweep\ntemplate_yaml = REPO \u002F \"skills.yaml\"                          # what it must become\n```\n```bash\nMANIFEST_TEMPLATE=\"${TEMPLATES_DIR}\u002Fskills.yaml\"              # survives a token sweep\nMANIFEST_TEMPLATE=\"${REPO_DIR}\u002Fskills.yaml\"                   # what it must become\n```\n\nSo the RESIDUE grep must hunt the CONSTRUCTION, not the old token — and it will read clean if\nyou only grep the old name, because it was clean BEFORE the sweep too. Grep for the last\nunchanged segment followed by the basename (`templates.{0,12}skills\\.yaml`), for the directory\nvariable (`TEMPLATES_DIR.*skills\\.yaml`), and for the joined-segment form\n(`\"templates\" *\u002F *\"skills\\.yaml\"`). Two consumers were dangling in a nine-reference sweep that\notherwise verified clean; that grep is what found them.\n\n### 4. Deleted-artifact cross-reference sweep\n\nDeleting files breaks things that assert their existence:\n\n- **DOCS-INDEX.md** entries for deleted docs\u002Fscripts (remove the rows).\n- **Test fixtures** asserting paths to deleted files\n  (`test_golden_expected_paths_exist_in_repo` FAILs on stale expected_top3 —\n  delete the stale query entry, keep count invariants like \"25-30 queries\").\n- **register() lines** in fleet-update.sh for deleted scripts (remove both\n  the line and any update\u002Fstub functions that call them).\n- **Skills referencing the deleted skill** (governance-sentinel listed\n  legacy-system-maintenance) — reword or drop the pointer.\n- **Deployed copies**: after deploy, `rm` stale deployed artifacts the\n  doctor flags (\"Remove: …\" in REQUIRED ACTIONS).\n\n**Not every occurrence is a LIVE reference — committed RECORDS must survive the sweep.**\nEvidence captures, transcripts and dated reports quote the old path as the thing that WAS run at\nthat revision. Rewriting one falsifies a record and breaks the checksum it carries, so exclude those\ndirectories from both the replacement pass AND the residue grep — and PRINT the exclusions beside\nthe count. A bare \"0 residuals\" that silently skipped a directory reads as coverage of everything,\nwhich is the same class of over-claim as a stale token left in place. Coverage is also\nper-PATTERN-CLASS: a content grep covers content, never filenames, and a content-only lint does\nnot cover what a future reader can rename — an audit report must either check the filename class\nor state explicitly that it did not; an unsourced \"every remaining reference is accounted for\"\nwith no bucket list invites the probe that finds the miss.\n\n**A PRINTED remedy is a live reference.** A check or warning that tells the operator to run a command\nis held to the same standard as code: if the string names a path that does not exist, the operator\nlands on a dead command. Resolve every printed fix\u002Fwarn path against the DEPLOY MAP's target rather\nthan the repo layout — deploys flatten and nest differently, so `\u003Cdeploy>\u002Fscripts\u002Fmanage\u002F\u003Cx>.py` can\nbe wrong while `\u003Cdeploy>\u002Fscripts\u002F\u003Cx>.py` is right, in the same file. Sibling printed paths may be\ncorrect exactly as they stand: check each one instead of \"tidying\" the directory component off all\nof them.\n\n### 5. Verification battery\n\n- `bash -n` every changed .sh; `py_compile` every changed .py; validate\n  JSON\u002FYAML (deleted files show as FAIL — ignore them, they're gone).\n- Adversarial gate A2 on every changed script.\n- Run the test suites that touch deleted paths (parity\u002Fgolden tests).\n- Live-service tests fail on deploy-order lag: a running service still\n  serves the old label until `fleet-update.sh` redeploys — verify against\n  the repo, not the live service, then re-test after deploy.\n- `git grep -i \u003Cterm>` == 0, doctor clean, deploy via fleet-update,\n  then push.\n\n### 6. Land it fleet-wide — 0 residuals is NOT done\n\nA sweep that only changes files is finished on YOUR host and broken\nelsewhere. A fleet-wide rename\u002Fconfig move is done when every other host\nconverges without a human, and agents can see what changed. Ship all four\nwith the sweep, in the same change:\n\n1. **An automatic per-host migration** on the update path — make the deploy\n   script RUN the consolidation (idempotently) before anything reads the moved\n   thing, and make the migration script seed the new location from the old one\n   rather than failing when it is absent. A host that still has only the old\n   layout must self-heal on the next `fleet-update.sh`.\n2. **An enforcement check in the doctor** — FAIL on the new invariant (target\n   exists, right perms, old path absent or a symlink to it, and a `fix:` line\n   naming the exact script to run). A sweep with no check silently regresses\n   the first time someone recreates the old artifact.\n3. **A runbook** (`docs\u002Frunbooks\u002F\u003Ctopic>-migration.md`) — the convention table\n   (which path is canonical, which are symlinks, which are not ours), how to\n   apply on Linux AND macOS, how to verify, the changes to implement, and a\n   symptom→cause→fix table. Index it in DOCS-INDEX.\n4. **Agent-facing skill notes** — update the setup\u002Ftroubleshooting skill the\n   agents actually load, and fix any prose your own sweep mangled (check every\n   line you rewrote reads sensibly; a rename can turn a sentence into a\n   tautology).\n\n5. **A per-host file the deploy APPENDS to is never pruned.** A deploy that writes a\n   line only when absent (`grep -q '^NEW=' f || printf 'NEW=…\\n' >> f`) cannot remove a\n   line an earlier release wrote, so a retired name survives every deploy forever and the\n   host reads as half-migrated indefinitely (measured: a legacy interpreter line sat in a\n   per-host env file through months of deploys). The deploy must REWRITE that file to the\n   new invariant — read it, drop the retired lines, write it back — and the doctor needs a\n   FAIL naming the retired name with the repair command.\n6. **Fix the GENERATOR, not its output — then gate the generator.** When the swept names\n   live in GENERATED artifacts (per-harness READMEs, unit files, generated manifests),\n   editing the artifact is a no-op: the next regeneration restores the old names. Fix the\n   generator's template, regenerate, and commit both. Then add the generator's own\n   `--check` to the lint, because a generator whose input was renamed but that was never\n   re-run keeps shipping the retired names behind a GREEN repo grep — the generated file\n   exists and reads plausibly. A content sweep of generated files is not coverage of the\n   generator.\n7. **Classify the surviving names, and let only EXTERNAL CONTRACTS survive.** After the\n   final release the legitimate keeps are: the converter\u002Fforwarder tool that must name the\n   spelling it converts, comments describing the migration, and the names a runtime you do\n   NOT own injects across the process boundary. Whitelist those BY NAME in the lint; every\n   other surviving token is residue. Report live surfaces separately from test\u002Frecord ones\n   so one repo-wide count does not mix deliberate keeps with real stragglers.\n\nThe user WILL ask \"will agents be able to implement this?\" if you skip 1–7 —\ntreat that as part of the deliverable, not a follow-up.\n\n## Pitfalls\n\n- **A file rename is not done until the CONSUMER layers that reference the artifact by name are swept — doctor's harness-verify + MCP-wiring checks are the canaries.** Renaming a deployed artifact (an MCP script, a harness extension file) while its registry\u002Fverify\u002Finstaller entries and the per-host MCP registration still name the old path leaves a GREEN repo grep and a RED doctor: `Harness (x)` FAILs on the missing old path, `MCP wiring (y)` FAILs because a registered script path no longer exists. Sweep EVERY layer that writes the name in the same change — `harnesses\u002Fregistry.yaml`, the verify\u002Fgovernance-check scripts, installer `resolve_ext`\u002FOURS tool lists, tests, docs, skills — plus the per-host `~\u002F.hermes\u002Fconfig.yaml` MCP `args` path (`hermes config set mcp_servers.\u003Cname>.args.0 \u003Cnew-path>`, never a raw config write; hosts converge on next install). Then read the FAIL taxonomy: a checksum FAIL on an edited file is just \"not yet deployed,\" but a harness\u002F`MCP wiring` FAIL is real drift that survives deploy.\n  **A verifier that PATH-RESOLVES the renamed artifact is part of the sweep, and it only FAILS on hosts that can execute it.** A harness verifier whose default-under-test path joins `extensions\u002F\u003Crenamed>.ts` (or the mjs entry that imports it) breaks at the import on the hosts that have the loader (an npm-managed pi install), while a host without that loader SKIPS before reaching the path — so a LOCAL green (or a SKIP) is not evidence the sweep reached the verifier, and neither is a repo grep that finds no old token in your own files. Fix the verifier SOURCE path AND re-run it on a loader-capable execution; a verifier that silently skips on the host that ran it leaves the class broken for every host that can.\n  **Rename-aware TEST FIXTURES assert the tool's CANONICAL name list, not the pre-rename spelling.** An audit fixture that registers the old server\u002Fextension name (or an installer test that probes preservation through the old name) makes a healthy synthetic host read FAIL once the tool under test requires the new name — and the reverse: a fixture asserting the pre-rename name passes vacuously when the tool no longer writes it. Re-derive fixture names from the tool's REQUIRED\u002Fowners list (the audit's required-set, the installer's written-server loop, the preservation probe's canonical names), not from the history of what the names used to be.\n- **Renaming an MCP server registration name is a sweep with its own traps** — every name\n  writer in one commit (installers, audits, watchdog maps, enforcer text, doctor wiring maps,\n  tests), rename-not-add by probe binary, `hermes mcp add` is interactive (pipe `printf 'Y\\n' |`),\n  and the rename kills the live session's own `mcp__\u003Cold>__*` tools mid-cycle (CLI close-out\n  with an explicit session_id is the fallback). Full recipe: `references\u002Fmcp-server-name-rename.md`.\n- **A directory that LOOKS like a duplicate copy is not provably one — diff it\n  file-by-file before deleting anything.** The same sub-path appearing twice\n  (`\u003Cdir>\u002Fdocs\u002F…` alongside `\u003Cdir>\u002Fdocs\u002Fnew\u002F\u003Cproject>\u002Fdocs\u002F…`) usually means a\n  stale copy, but the copy can hold files the canonical tree lacks. Hash both\n  trees (`find \u003Ca> \u003Cb> -name '*.md' -exec md5sum {} + | sort`) and print BOTH\n  the duplicate hashes AND the files present in only one tree — in the real\n  case 15 of 38 files were byte-identical while **23 existed only in the copy**,\n  so deleting on the assumption of duplication would have destroyed the only\n  copy of real content. Procedure: merge the uniques up into the canonical tree\n  (preserving relative paths — some may land OUTSIDE the subtree you are\n  keeping, e.g. a sibling `spec\u002F`), then delete only the residual duplicates.\n  The proof is `duplicate hashes == 0` afterwards, not the deletion itself.\n- **A prefix-INSERTION sweep is not idempotent — the new text still contains the\n  old pattern.** Renaming a bare term never re-matches itself; INSERTING a path\n  segment does (`docs\u002F\u003Cx>\u002F` → `docs\u002Folder\u002F\u003Cx>\u002F`), so a second rule in the same\n  pass — or any re-run — matches inside the already-rewritten string and produces\n  `docs\u002Folder\u002Folder\u002F\u003Cx>\u002F`. Guard the replacement with a negative lookbehind\n  (`(?\u003C!older\u002F)docs\u002F\u003Cx>\u002F`) or match only the un-prefixed form, then assert exactly\n  one pass's worth of change before writing.\n- **git stash pop without `--index` silently unstages everything** — the\n  staged index is lost; re-stage with `git add -A` before re-committing.\n- **`git checkout --ours\u002F--theirs \u003Cfile>` during rebase restores the WHOLE\n  file from that side** — auto-merged hunks in that file are reverted (a\n  `--ours` on install.sh reverted an entire 16-file sweep's changes to it).\n  Prefer per-hunk resolution or re-apply and re-verify with grep after.\n- **A sibling push can land mid-sweep** (Moses committed Titus's resend\n  while the sweep ran). The pre-push dogfood gate then blocks with\n  \"Deploy sync — HEAD ahead of last deploy\". Fix: `git pull --rebase`,\n  resolve (the sweep is usually a superset — origin's hunks are fine where\n  cosmetic, re-apply yours where they conflict on substance), deploy,\n  doctor, re-push. Check `git log origin\u002Fmain -3` before pushing a big\n  change. If `git pull --rebase` refuses on UNSTAGED changes a peer left in\n  flight, `git pull --rebase --autostash` carries them through and re-applies\n  them automatically — never `checkout`\u002F`stash` the peer's working tree away,\n  and never commit their edits alongside your sweep. After the rebase,\n  `git status` should still show their edits uncommitted.\n- **Fence corruption is pre-existing, not yours**: the pre-commit fence\n  check may flag an unbalanced file you merely touched. Verify at HEAD\n  (`git show HEAD:\u003Cfile> | grep -c '^```'`) before fixing; a dangling\n  opener at EOF gets removed, not closed.\n- **The word count in PII scans includes pre-existing patterns** — diff\n  the flagged lines against what you actually changed before claiming\n  your sweep introduced PII.\n- **Exclude the tool that PERFORMS the migration.** A script that merges the\n  old artifact into the new one legitimately references the old name (its\n  idempotency check depends on it). A blanket rename breaks the very mechanism\n  you are migrating to — add it to the skip list explicitly, and say so in the\n  commit message so a later reader does not \"fix\" it.\n- **Exclude the tool that DETECTS and REPORTS the old artifact.** A checker or\n  doctor check whose *message* names the old path must keep that literal — there\n  the old name is the SUBJECT of the sentence, not a reference to a path. A\n  blanket replace turns `stray ~\u002Fold\u002Fdir\u002F.env` into a message naming the\n  CANONICAL file: a tautology that now misreports which path is wrong.\n- **Exclude the skill that TEACHES the sweep itself.** A how-to\u002Frename skill whose worked example uses the old term as the EXAMPLE (a mapping line, a migration command) must be kept out of the blanket sweep: a path-token replace rewrites BOTH sides of its `old → new` mapping to the new term — the mapping inverts to `new → new` and the worked example silently disappears (measured: a device's own rename-sweep example corrupted this way; revert the file and re-exclude it). Pull such a file to a fixed baseline before sweeping, keep it out of the residue grep, and say so in the commit message so a later reader does not \"finish\" the sweep on it. **Keep it out of the residue LINT too — and expect that lint to re-flag the file long after the sweep.** A gate that greps `skills\u002F` for the retired token has no concept of a teaching reference, so it fires on this file on every run; when the sweep is long finished and the ONLY failure is that reference, the choice between generalizing its sample tokens to the wildcard family form (which does not match a `PREFIX_[A-Z0-9_]+` pattern) and exempting it by path in the lint is an operator gate-scoping call — report it with the one action that clears it, never re-scope the gate yourself and never wave the file through as obviously-fine residue.\n  **Nothing re-reddens a finished sweep faster than a later skill-lesson BACKPORT.** A lesson file copied into the repo from the deployed tree carries whatever tokens it was written with, so it can turn the brand lint red long after a green sweep with every host surface still clean — attribute a fresh lint failure with `git log --diff-filter=A --oneline -- \u003Cflagged file>` before suspecting the original sweep.\n- **A stranded (deployed-only, repo-source-missing) skill you inherit is a PRE-RENAME SNAPSHOT until the grep says otherwise — classify DELETE vs sweep+backport per file before \"making it local\".** A dir in `~\u002F.steadfaste-fleet\u002Fskills\u002F\u003Ccat>\u002F\u003Cname>\u002F` with no `git ls-files` source is exactly what the deploy never pruned. Classify each: a dir whose frontmatter duplicates a live repo skill (same `description`, a rename runbook documents it) or that teaches a fully-superseded layout is DEAD — delete the deployed dir, ship no backport; a genuinely-distinct skill keeps its value but its body carries the old brand (`~\u002Fold-name`, `OLD_*` env vars, `old-\u003Ctool>.sh`, `author: Old Brand`), so sweep the tokens to the new spelling, VERIFY each new path\u002Fflag\u002Fenv actually exists (the sanctioned unlock flag is `--\u003Cnew>-update`, the env `FLEET_DEPLOY_HOME`, the script `\u003Cnew>-dogfood.sh` — never invent an equivalent), then backport and RE-RUN the brand lint: a reused old env token turns the retired-spelling gate red on the newly added files. `reconcile-stranded-skills.py` will NOT list these — it reports same-file SKILL.md DRIFT (a deployed superset to backport), never a whole dir missing from the repo; find missing dirs with `comm -13 \u003C(ls \u003Crepo>\u002Fskills\u002F\u003Ccat>) \u003C(ls \u003Cdeployed>\u002Fskills\u002F\u003Ccat>)` plus `git ls-files | grep -i \u003Cname>`.\n- **A stale CLI reference in a doc is fixed with the ACTUAL entry point, not the doc's claim — grep the tool's own usage and the dispatcher before writing the corrected command.** `git grep` the alleged subcommand in the real command module; if absent, read the implementing script's own `--help`\u002Fusage line and write that invocation verbatim.\n- **A clean residue grep does not prove the surviving text is TRUE.** It only\n  proves no old token survives. This is the code-side twin of the prose-mangle\n  check in step 6.4 — re-read every string the run changed, error\u002Fwarning\n  message strings included, and confirm each still describes what it claims.\n- **Tool output can REDACT credential-shaped strings, so a replacement that reports 0 matches for a string you can SEE is a red herring — compare BYTES before believing the file differs.** An env-var name such as `$FLEET_BUS_TOKEN` renders intermittently redacted (e.g. `$CORTE...KEN`) across tool outputs, and trusting the rendered read made a sweep mis-target a replacement for several turns. Assert every replacement count against the RAW read (`txt.count(needle)`), and when any comes back 0, re-read the exact bytes (`repr(segment)` \u002F `needle.encode()`) — the count, not the display, is what proves whether the token is present and where.\n- **When the swept term is a REAL WORD (not an acronym\u002Fslug), the catch-all renames\n  it inside unrelated domain language — and the residue sits under the NEW token,\n  so the old-name grep reads clean.** `cortex` is a medical\u002Fneurological term as\n  well as a product name: a `cortex → fleet` sweep rewrote \"auditory cortex\",\n  \"motor cortex\", \"prefrontal cortex\" into \"auditory fleet\", \"motor fleet\", … in\n  an EEG\u002FBioSignal reference doc — a healthy-looking mangle the old-token grep\n  cannot see because the token is gone. Grep the NEW token in NON-code\u002Fprose and\n  domain-specific files (`skills\u002Fhealth\u002F…`, any doc full of the plain noun) and\n  re-read occurrences that were never the product token; better, scope the\n  catch-all to the token CLASS (uppercase `CORTEX_*`, the slug `cortex-`\n  compounds) and sweep the bare lowercase word only in code\u002Fvar contexts, never\n  in prose. A word-boundary catch-all on a shared English word is the highest-\n  entropy mangle class because the residue is invisible to its own proof grep.\n- **Renaming a BARE IDENTIFIER (a var\u002Ffunction name) needs a full word-boundary\n  on BOTH sides — a space-anchored replace splits assignments from usages into\n  NameErrors you introduced.** `term ` (word + trailing space) rewrites `x = …`\n  assignments but not `x.attr`, `x)`, `{x}`, or `x.method(…)` usages (no space\n  after the token), so the renamed assignment and the untouched usages diverge.\n  Rewrite with `(?\u003C![A-Za-z0-9_])term(?![A-Za-z0-9_])`, then AUDIT for split\n  files: grep every touched code file for the NEW identifier in an assignment\n  position AND a bare OLD identifier, and fix both sides consistently (a sweep\n  that changes the same local name across 60+ tests and scripts is exactly where\n  this bites).\n- **When the swept token is a DIFFERENT abbreviation in some files, don't force\n  the target's new name — give the colliding local variable a DESCRIPTIVE\n  name.** A token that is the product\u002FCLI name in most files (e.g. `hc` the bus\n  CLI) can be an unrelated local abbreviation elsewhere (`hc` = a HealthCheck\n  instance, `hc` = hymn count). Renaming those to the CLI's new name (e.g.\n  `fleet`) is misleading scope-drift an adversarial reviewer will flag; use a\n  name that states the variable's meaning (`healthcheck`, `hymn_count`) instead.\n- **Exclude same-basename files in other directories.** `~\u002F.dir\u002Fconf.d\u002Fold.conf`\n  and `~\u002F.other\u002Fold.conf` are DIFFERENT files; a basename rule rewrites them\n  happily. Guard per-line on the full distinguishing path, and verify the\n  genuine ones survived.\n- **After a path sweep the repo can still WORK while being wrong.** A symlink\n  at the old location hides every missed reference until the symlink is\n  removed — so residue-grep the source, then remove the symlink deliberately,\n  never assume \"the tests pass\" means the sweep is complete.\n- **A home-dir rename leaves PHANTOM old paths in compiled bytecode — a traceback naming the\n  old dir with `??` source lines is `.pyc`, not source.** Python's `__pycache__` caches modules\n  compiled before the rename; the bytecode embeds the pre-rename absolute path, so a failing\n  test or import after a clean sweep still raises `FileNotFoundError: …\u002Fold-dir\u002F…` (or a\n  failing test asserts a deliberately-removed constant and reads as a phantom regression).\n  Confirm with `strings \u003Cfile>.pyc | grep \u003Cold-path>` — a source grep returns 0 while the pyc\n  greps hit — then delete the `__pycache__` dirs: they regenerate on next import, and removal\n  is the only fix that makes the phantom disappear. Sweep host-wide, not just in the repo: the\n  deployed tree's stale pyc files are what a live traceback actually shows.\n- **A home-dir rename leaves venv console-script shebangs pointing at the OLD\n  interpreter — every wrapper dies with `bad interpreter` on first use.** A venv\n  re-created at the new path still has `bin\u002F*` wrappers whose `#!` line names\n  the pre-rename interpreter, so `pytest`, `pip3`, `uvicorn`, … fail with exit\n  127 while the venv's own `bin\u002Fpython3` is fine — and the first tool a\n  verification run reaches (pytest) is exactly the one that dies, so the suite\n  looks broken before it starts. Immediate workaround: `bin\u002Fpython3 -m \u003Ctool>`\n  (the interpreter itself is unaffected). Fix in place, never re-create the\n  venv: `grep -rl '\u003Cold>\u002Fvenv\u002Fbin\u002Fpython3' ~\u002F.steadfaste-fleet\u002Fvenv\u002Fbin | xargs\n  sed -i \"s|#!.*\u003Cold>\u002Fvenv\u002Fbin\u002Fpython3|#!${HOME}\u002F.steadfaste-fleet\u002Fvenv\u002Fbin\u002Fpython3|\"`,\n  then re-grep → 0. The sed replacement must be DOUBLE-QUOTED so the shell\n  expands `${HOME}` — a literal `${HOME}` can never stand in a shebang (the\n  kernel does not expand variables there). Add this to the migration runbook's\n  cleanup list; it is a distinct residue class from stale `__pycache__`.\n- **A background result can be SUPERSEDED — check it is the latest run before\n  acting.** A long test\u002Fdeploy run finishing late reports the tree from when it\n  STARTED. Two completion notices can disagree (an older 7-failure run landing\n  after the fixed 5-failure run). Compare against the current HEAD and re-run\n  the pair\u002Fsuite if in doubt; never report a stale FAIL list as the state, and\n  never \"fix\" what a superseded run complained about.\n\n- **`git mv` needs the destination's PARENT directory to exist, and the error names the SOURCE.**\n  `git mv a\u002Fb\u002Fc a\u002Fb\u002Fbin\u002Fc` answers `fatal: renaming 'a\u002Fb\u002Fc' failed: No such file or directory` —\n  pointing at a file that is right there. `mkdir -p` the new directory first. Once the rename is\n  staged, the OLD path can no longer appear in a pathspec (`git add \u003Cold>` \u002F `git commit -- \u003Cold>`\n  → `pathspec '…' did not match any files`): stage\u002Fcommit the live paths, or omit the pathspec and\n  let the staged rename carry the deletion.\n- **`git diff --cached --name-only` collapses renames to their NEW path — a\n  pathspec commit of a rename sweep silently leaves the deleted sources staged\n  and uncommitted.** When you commit with `git commit -m … -- $(git diff\n  --cached --name-only)` (the name-your-paths gate route), rename detection\n  drops the deleted `old\u002F…` entries from the list, so HEAD still contains them\n  and the old dir survives the commit. Collect the pathspec with\n  `--no-renames` (`git diff --cached --name-only --no-renames`) so deletions\n  are included, then verify after the commit that `git ls-tree HEAD\n  -- \u003Cold-dir>` is empty and `git status` is clean.\n- **A launcher or executable moved into a subdirectory needs its self-relative module resolution\n  changed in the SAME commit.** See `shell-scripting` → \"Moving an executable\": without it the\n  script silently runs a different tree's module through its known-path fallback, and every test\n  that runs the installed copy still passes.\n\n- **A green doctor does NOT mean a home-directory rename ran.** Renaming a live\n  deployment's dirs (`~\u002Fhermes-cortex` → `~\u002Fsteadfaste-fleet`, `~\u002F.hermes-cortex`\n  → `~\u002F.steadfaste-fleet`) ships a guarded migration script + a golden-path\n  verifier, but deploying the code does not execute the rename. Verify on the\n  host: `FLEET_DEPLOY_HOME` still unset ⇒ `fleet-update.sh` still defaults to\n  the OLD `~\u002F.hermes-cortex`; no transition symlink yet; the old dirs are real\n  dirs, not symlinks. Those symptoms mean \"the code landed, the rename has NOT\".\n  A host that still runs everything off the old paths is not a failed rename —\n  it is a host that is correctly NOT yet migrated.\n- **The local-dir rename is gated: dogfood host FIRST, fleet in a SEPARATE rollout\n  cycle, and the code-default path change is held back until the fleet migrates.**\n  A rename plan written for one dogfood host (verifier named `verify-rename-\n  \u003Chost>.sh`) deliberately does NOT apply to the rest yet. Before \"finishing\" a\n  rename on any non-dogfood host, check the plan's rollout step: it may mandate\n  esther-green first and a separate fleet dispatch, with the deploy default in\n  `fleet-update.sh` (`FLEET_DEPLOY_HOME=\"${HOME}\u002F.hermes-cortex\"`) deliberately\n  unchanged until every host has migrated (so the 4 agents' next deploys stay\n  consistent).\n- **Confirm the repo rename landed by `git ls-remote` on BOTH the old and new\n  URLs returning the same HEAD** — GitHub auto-redirects the old name, so equal\n  HEADs prove the native rename happened and the old URL is an alias, not a\n  second repo. But note the renamed repo's HEAD can be AHEAD of a given host's\n  last pull; pull to current before running any migration script so you deploy\n  from the latest version.\n- **Never run a home-dir migration under an in-flight deploy writing to that same\n  dir.** A `fleet-update.sh` mid-run is reading\u002Fwriting `~\u002F.hermes-cortex`;\n  moving the directory out from under it breaks both the deploy and the rename.\n  Wait for the deploy to finish (poll its log for `UPDATE_EXIT=0` and the doctor\n  verdict) before `migrate-home-dirs.sh`. `migrate-home-dirs.sh` also refuses to\n  run from inside a source dir (`cwd` guard) — run it from a stable workdir.\n- **`install-crons.sh` regenerates the bridge\u002Fbus units but NOT the Hermes-owned\n  gateway + dashboard units — hand-patch those, or the golden-path \"0 old tokens\"\n  unit scan stays red.** After regenerating units with `FLEET_DEPLOY_HOME`\n  overridden to the new path, `grep -Rl '\\.hermes-cortex' ~\u002F.config\u002Fsystemd\u002Fuser`\n  still returns the `fleet-gateway.service` + `hermes-cortex-dashboard.service`\n  live units (plus the gateway's `default.target.wants` symlink), which the cron\n  installer never writes. Rewrite their `ExecStart`\u002F`WorkingDirectory`\u002Flog paths\n  to the new deploy-home directly. Discrimination that matters: the verifier\n  greps the DOTTED deployed-home token (`\\.hermes-cortex`), so a bare repo-path\n  token (`%h\u002Fhermes-cortex`, no leading dot) is ALLOWED through the transition\n  — it resolves via the symlink; only the dotted token must reach zero.\n- **A golden-path verifier FAIL can be a host-layout difference, not a rename\n  regression — verify the service by port\u002Fprocess before treating a unit-state\n  FAIL as a break.** A verifier written for the dogfood host assumes a service\n  runs as a systemd unit; the same service can run as a loose process on another\n  host with its unit never enabled (`systemctl --user is-enabled …` → disabled,\n  pre-existing). Before calling the rename failed on an `inactive` unit check,\n  confirm the service is actually alive its own way (`pgrep -f \u003Cserver>.py`,\n  `curl -fsS` to its port → 200) and note the difference as an environmental\n  host difference, not a regression.\n- **Residual old-name tokens are CLASSIFIED, never blanket-swept.** After the bulk pass, the leftover tokens in NON-record files fall into two classes: FUNCTIONAL keeps (one-release shim files, doctor checks that verify the deployed legacy name still works, the enforcer's dual-accept regex, restore\u002Fmigration utilities, a legacy exception flag the enforcer still accepts) and DOCUMENTARY stragglers (a prose line whose sibling on the same line was renamed, a docstring still naming the pre-rename function or command). A blind word-sweep of the residue breaks the migration contract it exists to preserve — the close reviewer flags exactly the documentary class, file by file, and passes the functional keeps. Fix the flagged lines precisely, never the keeps.\n- **A transition shim is a DEADLINE, not a fixture — when the operator declares the migration\n  done, remove the shim and every layer that registers it in the SAME change.** A compat alias\n  kept \"for one release\" outlives its purpose and keeps the old name alive: the file, its\n  register line, brand-lint fixtures, and any skill lesson teaching \"keep the alias\" must all\n  be inverted (transition alias REMOVED) in one commit, or agents keep recreating it from the\n  docs. The definitive completion proof is destructive and operator-driven: delete the old\n  artifact (shim, folders) and re-run the whole battery — a green old-name grep is not proof\n  the old path is not still load-bearing somewhere bytecode or config names it.\n- **A residue grep that matches CONTENT cannot see a FILENAME — enumerate the filename class separately and guard it in the lint.** A brand lint whose patterns are all content (`ops\u002Fscripts\u002F\u003Cold>\u002F`, `scripts\u002F\u003Cold>.py`, `\\b\u003Cold> \u003Cverb>\\b` invocations) leaves every file NAME carrying the old brand untouched: live tests named `test_\u003Cold>_*.py` whose docstrings already say \"Tests for `\u003Cnew>`\" pass the whole battery — only the name is stale (measured: three `test_hc_*` files survived a hermes-cortex→steadfaste-fleet sweep whose lint was 5\u002F5 green). Sweep filenames with a name-based pass (`find tests -name 'test_\u003Cold>_*'`, `git ls-files | grep -i \u003Cold>`), migrate every reference that names them (evidence-runner subprocess lines, comments pinning \"pinned by tests\u002F\u003Cold>.py\"), then ADD a filename guard to the lint itself (`find ... -name 'test_\u003Cold>_*'` fails the suite) so the class cannot silently return. Content coverage does not imply name coverage — say which one the verification actually checked.\n- **A residue COUNT is inflated by every KEEP that CONTAINS the swept term — anchor the family pattern, and check the guard's CASE.** A swept term that is a SUBSTRING of a deliberately-kept sibling is the normal shape (`cortex` inside `mycortex`, `hc` inside a longer word), so a loose pattern counts the keep as residue and overstates the work: the family pattern `CORTEX_[A-Z0-9_]+` matches the `CORTEX_` inside `MYCORTEX_COMPOSE_DIR` and `_MYCORTEX_CACHE`. The fix is a left boundary a word character blocks — `\\bCORTEX_`, equivalently `(?\u003C![A-Za-z0-9_])CORTEX_` — because the character before that `C` is itself a word character, so the keep no longer matches. The same trap survives a negative-lookbehind guard whose CASE does not match the family's: a guard written `(?\u003C!my)` never fires against the `MY` in `MYCORTEX_X`, silently re-inflating the count it was added to prevent. Report counts as `N raw - M keep-substring` and NAME the keep, so a reader can check the subtraction instead of trusting the total.\n- **\"Where are we with the migration?\" is answered by MEASURED SURFACES, never by a plan's status header.** A rename lands in commits, package dirs, unit names, cron entries and per-host env files; the plan \u002F runbook \u002F followups docs keep whatever status line they were written with (`Status: PLAN - not started`, `Release 2 - not yet`, `IN PROGRESS since \u003Cdate>`) long after the landing, so reading them reports the migration backwards. Measure, then report with the source named: `git log --oneline` (did each sweep land, and when), the renamed package\u002Fscript dirs, the unit names under `~\u002F.config\u002Fsystemd\u002Fuser\u002F`, the cron names in `jobs.json`, and a COUNT of the old spelling in each host's `.env` (grep names only, never values). Scope the answer to the hosts actually measured and say which ones you did not reach — a single-host measurement is not a fleet-wide claim.\n  **A doc whose status header contradicts the landed state is a FINDING, not context** — the same class as a superseded \"kept\"\u002F\"deferred\" row. Patch the header and any `not yet` \u002F `not started` section in the sweep's own commit (see `references\u002Fenv-namespace-rename.md` section 6), or the next reader re-derives work that is already done.\n- **An exemption token is PER-LINE — it must sit on the same line as every reference it\n  protects, and the sentence must stay on ONE physical line.** A lint that ignores lines carrying a date token (a migration-record line) judges\n  each line independently: wrapping a long reference onto a continuation line moves the token\n  off the flagged line and the lint fails with no text change. Keep the token on every line\n  that names the old path and re-run until the whole surface is 0 — the clean count is the sum\n  of the per-line decisions. When fixing a flagged record, write the sentence as a single\n  un-wrapped line so a re-flow can never separate the date from the old-path token again.\n- **Live systemd units are part of the sweep surface — and the generator does NOT repair them.** The deploy's orphan-sweep deletes old-named deployed scripts; any live unit whose ExecStart names them fails en masse (one renamed bridge-run script took down 26 generated bridge units at once). Generators that wrote those units SKIP existing ones, so re-running the generator changes nothing. Hand-patch the unit files (new script path + renamed `--script` names), `systemctl --user daemon-reload`, `reset-failed`, then assert 0 failed units and the timers active.\n- **Closing a large rename range is a long governed grind — budget for it, and only the lock-owning session can drive it.** The `end_change` blob-close loop judges ~4 blobs per wave (one 240s window), so a 350-file range is ~90 serial waves (an hour-plus), not minutes. Verdicts are content-keyed: blobs already CLEAN are never re-judged, so each further swept commit only adds its own new blobs to the grind. The per-blob reviewer REFUSES the close on any documentary straggler it finds — fix the named file (a content change re-opens only that blob), commit, call `end_change` again; the loop continues from where it stopped. A subagent CANNOT grind it: a child session's `end_change` with your task_id finds no pending cycle in its own session and mints empty MOVE_ON cycles (ledger pollution) instead of judging — the loop only advances from the session that holds the lock.\n  **A close-gate FINDING may be stale — recorded against an OLDER blob than the current tree — verify the current content before grinding a fix.** Verdicts are keyed to blob content, so a finding the reviewer filed against a pre-fix version (evidence citing a duplicated var, a `CORTEX` literal, a mangled comment) can describe code your later sweep commits already corrected. Before fixing a named finding, compute the file's current sha (`git hash-object \u003Cfile>`) and look up its verdict in the review store — if the current sha has no verdict (or a CLEAN one), the finding is stale and the file may need no change at all; re-emit the close to have the gate re-judge the changed blobs. Checking `blob_reviews` against `git hash-object` first separates the real remaining defects from the historical ones and stops a grind that would otherwise \"fix\" already-fixed files.\n- **A close-gate finding can be CURRENT but its RECOMMENDATION mechanically wrong — verify it against the live function before adopting.** The per-blob reviewer audits the DIFF with quotes stripped, so its \"revert to the original form\" and \"restore the removed line\" suggestions can be wrong or even break the test (it asked to restore a duplicate fixture line that the converter demonstrably does not dedupe — restoring it fails the idempotence assertion the test exists to check). Before adopting a recommendation, run the test against the LIVE function (extract it into a harness with `sed -n '\u002F^func()\u002F,\u002F^}\u002Fp' \u003Csrc>`, add the `warn()` stub, feed the proposed fixture) and adopt only what holds; when you deviate deliberately, say so in a test comment so the re-review sees intent instead of re-flagging the deviation.\n- **A blanket rename damages code and tests in PREDICTABLE shapes — audit for all of them, not just residual tokens.** (a) DEAD SUBSTITUTION: placeholder-`sed`\u002Ftemplate code whose placeholder the sweep renamed away replaces nothing, and may read a STALE duplicate copy of the artifact — a sweep that fixed the kept template copy but not the consumer's source path leaves the installer consuming the un-swept copy (which can still hardcode a per-user absolute path). Point consumers at the kept copy and drop the dead substitution; flag an out-of-range stale copy as a separate issue rather than growing the range. (b) DUPLICATE COLLAPSE: a two-name fallback tuple `(\"LEGACY_X\", \"NEW_X\")` collapses to `(\"NEW_X\", \"NEW_X\")` when the legacy name matches the replacement — the lookup silently checks one var twice and error messages duplicate the name; grep for doubled tokens. (c) CONVERSION TESTS: a test that exercises a converter must keep the OLD spelling in its FIXTURES — blanket-renamed fixtures make it test a no-op — and a \"OLD dropped\" assertion must grep for the OLD spelling (renaming the pattern to the NEW token inverts it into always-fail). Stale headers and labels (\"X ↔ X\" tautology, \"mirror\" labels on a conversion) read as fabrication findings on re-judged blobs — fix them in the same commit as the fixtures.\n- **The close-loop window has NO rename detection — a git-mv file reads as a BRAND-NEW file, and that refusal is un-fixable in content.** The per-blob reviewer materialises a rename pair as delete+add and judges the add as \"new file added to a rename task\" (fabrication\u002Fscope-drift). Every fix commit re-emits that blob and re-audits the SAME artifact, so feeding changes to a renamed file is a loop that does not converge. The resolutions that terminate: (a) commit metadata + an in-range authorization\u002Fevidence record (a committed note that the renames are `git mv` token-swaps and which names are intentionally deferred, with the operator's one exception) for scope-drift findings, (b) operator acceptance of the tooling limitation for the pure new-file artifact, and (c) fix the REVIEWER'S CONSTITUTION when the findings are the reviewer's own blindness, not your content — see the pitfall below. Do NOT keep re-emitting the blob hoping for a fresh verdict on the artifact.\n- **A reviewer-constitution edit is the terminating resolution for a rename-range review flood — and it is an enforcement-layer change in its own right.** When the per-blob reviewer keeps filing the renamed files' PRE-EXISTING teaching as unverified-claim\u002Ffabrication (\"new file, unverified install claims\", \"file teaches the old brand\") and its recommendations drift into renaming live contracts, the loop does not converge no matter how much evidence you paste — each rereview clears 2 blobs, each close pass re-judges the next batch under the same blind rules. The fix (governance-closeout's \"fix the reviewer's constitution\"): add a rule to the reviewer prompt template — `docs\u002Ftemplates\u002Fadversarial-reviewer-prompt.md` (ORCHESTRATOR-ONLY) AND its deployed copy `~\u002F.steadfaste-fleet\u002Ftemplates\u002F` (the reviewer reads deployed-first; the two must be byte-identical), in the same commit. The rule shape that works: \"a renamed file's pre-existing content is CONTEXT, not a claim — judge only what THIS range changed about it (old-brand tokens swept, STALE labels correct, renamed identifiers consistent); the keep-list authority doc (e.g. docs\u002Frename-followups-*.md) is the contract, and tokens it documents as deliberately kept (a live short-name family, a separate live product name, a deliberately-kept service name) are NOT findings.\" The template's text is sha256-fingerprinted as the rules revision, so ANY template edit re-sends every previously-refused blob under the new rules — that is the unblock. Plan-review the template change first (it is enforcement-layer), and note that the new rule must NOT weaken the existing fabrication\u002Funverified-claim standards for content the range actually authored.\n- **Never put a rename-provenance claim in a renamed file's DOCSTRING — the window reads it as fabrication.** A header comment \"renamed from `\u003Cold>` via git mv\" contradicts the window's new-file view (\"the diff shows ADD, the claim says rename\") and is refused even on the exact wording that cleared once. The rename record belongs in the commit metadata (`git log --follow`) and an in-range evidence doc — point the docstring there, or say nothing about the rename at all.\n- **The close reviewer audits renamed scripts' LEGACY internals, and each fix re-opens that file's whole re-audit.** Renamed .sh\u002F.py that predate the sweep get their pre-existing error-swallowing, unverified claims, and external docstring references raked in full — and fixing any one re-emits the blob, re-auditing the rest. Batch the concrete fixes (real trailing-newline, missing dependency pre-check, swallowed `2>\u002Fdev\u002Fnull`, docstring cites to sibling files the window cannot verify) into ONE commit per file, make docstrings self-contained with NO cross-file citations (the window cannot verify a sibling file), and stop after the concrete ones — the deterministic artifacts will not clear.\n- **A gate's KEEP-LIST goes stale the moment the migration lands — sweep it in the same change.** A reviewer constitution, brand lint, or allow-list that still names the swept family as a \"deliberate keep\" is a gate that AUTHORIZES the exact drift it exists to catch: the close reviewer passes the residue, and the residue lint stays green. The only legitimate keeps after the final release are the EXTERNAL CONTRACTS (names a runtime you do not own injects across the boundary), the converter tool itself, and dated records — whitelist those BY NAME and let everything else fail. When a family is renamed, grep the gate surfaces for its name as part of the sweep; a keep entry is not neutral documentation, it is enforcement.\n- **A residue lint must prove it is not blind — and must never swallow its own failure.** Three cheap properties, each of which has been the difference between a real gate and a green tick: (a) ASSERT the surfaces it greps exist — a missing directory or a renamed search root returns no matches, which reads as a clean sweep over nothing; (b) PLANT the exact shape in a temp fixture and require a hit — a detector that never fires is indistinguishable from a clean tree; (c) never `2>\u002Fdev\u002Fnull` the grep — a failed search reads as zero residue. Scope the lint to the INSTRUCTION surface and NAME the excluded directories (dated records, plans, design rationale) beside the result, so the coverage claim is checkable rather than implied.\n- **Red tests are residue too — and a rename-caused stale test can end up testing NOTHING.** Two mechanisms worth sweeping: a test that patches a RETIRED module attribute (`c.OLD_HOME = tmp`) silently CREATES a new attribute while the code reads the renamed one, so the test then exercises live host state and its verdict means nothing (the check reads the real host — the failure detail names real paths, which is the tell); and tests asserting retired log markers or strings go red and STAY red unnoticed when no runner references them (a test file nothing invokes is not coverage). Before declaring any failure pre-existing, reproduce it in a pristine worktree of the range base (`git worktree add --detach \u003Ctmp> HEAD`, same interpreter, same command, both sides) — most rename-caused failures are the test encoding the OLD contract, and rewriting them to the new one converts a long-red suite green. Remove the temporary worktree when done.\n- **A blanket sweep silently breaks the detector's own NEGATIVE FIXTURE — restore the PLANTED token, not the lint.** A lint that proves it is not blind by planting the retired spelling in a temp fixture and requiring a hit gets its plant RENAMED by the same catch-all (the planted `OLD_X=` becomes `NEW_X=`), so the negative test then plants a legitimate token the detector rightly ignores and reports \"the lint is BLIND\" on a healthy gate. The lint's own grep PATTERN usually survives (the regex literal `OLD_[A-Z0-9_]+` is not itself a match), but the planted string is — after any bulk pass, grep the negative fixtures for the retired spelling and restore the plants.\n- **A token-pattern sweep misses three shapes by construction — enumerate them in the residue grep.** (1) EXTENSIONLESS files (a git hook with no suffix) are skipped by `*.py`\u002F`*.sh` include globs; (2) the asterisk PROSE form — a doc that says \"set your `OLD_*` vars\" survives because `*` is not in the token class `[A-Z0-9_]`; (3) the sweep's own REGEX LITERAL in the lint (`OLD_[A-Z0-9_]+` as a pattern string) is not a match. Fix each class with its own grep, never a re-run of the same pattern.\n- **Before choosing the REPLACEMENT token, grep for it — if it already means something else, pick a specific name.** A mechanical `OLD_HOME → NEW_HOME` can collide with a pre-existing `NEW_HOME` convention meaning a DIFFERENT thing (user home vs deploy home across a dozen scripts). Verify the proposed target's current meaning; on a collision, disambiguate per concept (`NEW_USER_HOME`, `NEW_DEPLOY_HOME`, `NEW_REPO_HOME`) — the standard is ONE specific name per meaning, never one generic name for two. A rename that folds two concepts under one token is a naming bug the sweep itself introduces.\n- **A residue lint's FALSE POSITIVE is fixed in the lint, not by renaming the artifact it over-matches.** A substring marker (`\"_CANDIDATES = [\"`) flags a legitimate prefixed list (`_ENV_CANDIDATES` = host env-file paths, not the repo-resource list the check exists to catch). Word-bound the marker (`\\b_CANDIDATES\\s*=\\s*\\[`) and keep the artifact; renaming the variable to dodge the marker hides the check's over-matching and is a probe fix in the wrong layer.\n- **A sweep that touches the enforcement chain (plugins\u002Fgovernance-enforcer) commits it, then every LATER commit is blocked by the DOGFOOD deploy-sync gate** (\"deployed copy differs from committed repo source\") until the enforcer is deployed — the sanctioned unblock is the full `fleet-update.sh`, never a manual copy. Budget the deploy before the next commit, or land the enforcer change separately and deploy it immediately.\n- **Commit a large sweep in LOGICAL CHUNKS (source → tests → docs), not one giant commit — the operator's explicit preference.** Per-chunk commits keep each blob reviewable by the close gate and give the operator checkpoints to react to; when a deploy gate blocks one chunk, the rest can still land and the deploy happens once.\n- **A host-wide core.hooksPath fires the fleet pre-commit inside pytest temp repos and REFUSES bare\u002FAGENTS.md-less commits — isolate the suite with a session-autouse GIT_CONFIG_GLOBAL fixture.** Point `GIT_CONFIG_GLOBAL` at a minimal config (identity only, no hooksPath) so throwaway repos commit freely; the fleet repo is unaffected (its hooksPath is repo-local), and hook-behaviour tests opt back in per-repo (`core.hooksPath = …\u002Fhooks`). This one fixture clears the whole class of temp-repo setup failures that look like a dozen unrelated test bugs.\n\n- **`git fetch origin` is write-class and trips the lock gate — don't pre-check\n  for new commits with it.** Opening a full governance cycle just to see whether\n  the remote moved is overkill; `git rev-parse origin\u002Fmain` reads the last\n  fetched ref and the pull itself fetches. If you must compare before opening a\n  cycle, read the lock-free primitives (`git rev-parse HEAD origin\u002Fmain`,\n  `git status -sb`) and treat that ``behind N`` as \"open the cycle and pull\", not\n  a reason to fetch first.\n\n## Verification\n\n- `git grep -i \u003Cterm>` returns 0 (tracked tree).\n- Token-mangle grep returns 0.\n- Tests that assert paths\u002Ffixtures pass.\n- Deployed copies clean; doctor shows no ❌; push landed on origin.\n\nSee `references\u002Flegacy-system-to-mycortex-2026-08-21.md` for a worked example:\ntoken list, guard table, every mangle class with its fix, and the\nconcurrent-push rebase sequence. See `references\u002Fpackage-rename-with-shim.md`\nfor renaming a python package with a one-release compatibility shim.\n",{"name":5,"version":24,"category":25,"metadata":26,"platforms":39,"description":7},"1.0.0","devops",{"hermes":27},{"tags":28,"related_skills":34},[29,30,31,32,33],"rename","sweep","decommission","migration","bulk-edit",[35,36,37,38],"change-checklist","survey-before-action","enforcement-change-safety","cortex-bus",[40,41],"linux","macos","main","96b22636b11836eba8d16dbc885fd0b87dc71b03","skills\u002Fdevops\u002Frename-sweep",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":52,"prompt":62,"zipAvailable":63},[53,56,59],{"tool":54,"command":55},"npx","npx skills add lukemcqueen\u002Fsteadfaste-fleet --skill rename-sweep",{"tool":57,"command":58},"bunx","bunx skills add lukemcqueen\u002Fsteadfaste-fleet --skill rename-sweep",{"tool":60,"command":61},"pnpm","pnpm dlx skills add lukemcqueen\u002Fsteadfaste-fleet --skill rename-sweep","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Frename-sweep\u002FSKILL.md",true,[65,71,75,79,83],{"path":66,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":69,"sourceHtmlUrl":70},"references\u002Fenv-namespace-rename.md","REFERENCE","参考文档",17836,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Frename-sweep\u002Freferences\u002Fenv-namespace-rename.md",{"path":72,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":73,"sourceHtmlUrl":74},"references\u002Fgithub-repo-rename.md",4330,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Frename-sweep\u002Freferences\u002Fgithub-repo-rename.md",{"path":76,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":77,"sourceHtmlUrl":78},"references\u002Fmcp-server-name-rename.md",6564,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Frename-sweep\u002Freferences\u002Fmcp-server-name-rename.md",{"path":80,"resourceType":67,"resourceTypeDesc":68,"sizeBytes":81,"sourceHtmlUrl":82},"references\u002Fpackage-rename-with-shim.md",10037,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Frename-sweep\u002Freferences\u002Fpackage-rename-with-shim.md",{"path":84,"resourceType":85,"resourceTypeDesc":86,"sizeBytes":87,"sourceHtmlUrl":88},"scripts\u002Frename-residue-inventory.py","SCRIPT","脚本",4898,"https:\u002F\u002Fgithub.com\u002Flukemcqueen\u002Fsteadfaste-fleet\u002Fblob\u002Fmain\u002Fskills\u002Fdevops\u002Frename-sweep\u002Fscripts\u002Frename-residue-inventory.py",[90,98,105,112,119,126],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":96,"publishedAt":97},"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":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":102,"categories":103,"keywords":104,"publishedAt":97},"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":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":97},"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":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":97},"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":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":125,"publishedAt":97},"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":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":97},"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",[],[]]