deep-clean

Runs a 7-step pipeline over a named path: path audit capture → per-language dead-code cleanup → per-language file consolidation → 4-lens sweep → reviewer prompts + structural audit → apply per tier → verification gates → report. Language variants are picked per step (1a/1b/1c, 2a/2b/2c) by the target language. This file is the lane identification step only; the working method lives in references/hermes/ and references/grok/.

Global Rules

The lane is determined from a physical signal, not by self-identification. Each agent's launcher stamps a fixed attribution env var into every command it runs; the model cannot set these.

if [[ -n "${HERMES_AGENT:-}" ]]; then echo HERMES
elif [[ -n "${GROK_AGENT:-}" ]]; then echo GROK
else echo UNSET; fi

• HERMES → Hermes lane. Read references/hermes/. Stop.
• GROK → Grok lane. Read references/grok/. Stop.
• UNSET → stop and report. Do not guess the lane.

Marker provenance:

• Hermes re-exports AI_AGENT=hermes-agent and HERMES_AGENT=true on every command.
• Grok Build runs with GROK_AGENT=1.

Read only the winning lane's references. Do not read the other lane's.

Pitfalls and Lessons

• Relocate, don't delete, shared templates consumed by linters. When stripping an embedded feature, check whether any removed files are also read by other linters or tests (e.g. doc templates under the removed dir that feed AES601-AES610 doc-shape checks). Relocate them to a non-feature path and update every path reference in build scripts, tests, and dispatchers — deleting them breaks linters that still expect them.
• Feature-stripping cascades. Removing an embedded feature breaks every caller of its modules, constants, traits, and CLI variants. Fix all callers, not just the obvious ones — cargo build and cargo clippy -D warnings will surface the rest. Don't declare done until the binary compiles and the full test suite passes.
• Grok Build can hit max turns on large refactors. Verify progress in the worktree directory (git status --short, git log --oneline -3, git diff <base>..HEAD), not the TUI stream — an empty stream doesn't mean idle. Send a focused follow-up brief listing only the remaining files, and drive rounds with a shrinking grep count of the feature's key symbols (constant names, fn names, CLI variants — not the generic word) until it hits 0. Never re-send the full original brief each round — the agent re-reads from scratch and burns the turn budget. The full recipe lives in the grok-build skill ("Multi-round large refactor recipe").
• When relocating a directory, search the whole tree for path strings, not just code. Doc-comment prose, generated-file headers (build-script-emitted // Source: <path> lines), test helper path joins, and stale references to deleted files (e.g. a doc comment citing a SKILL.md removed in the same cleanup) all carry the old path and survive a code-only sweep. Grep the old path string across *.rs, *.md, and *.sh (excluding target/) after moving files, and rewrite every hit — cargo test passes even with stale doc comments, so the gate will not catch them.
• lint-arwaky verification gates (Rust workspace): CARGO_INCREMENTAL=0 cargo fmt --all -- --check, CARGO_INCREMENTAL=0 cargo clippy --all-targets -- -D warnings, CARGO_INCREMENTAL=0 cargo build --bin lint-arwaky-cli, CARGO_INCREMENTAL=0 cargo nextest run --workspace --lib --tests -j 2. Run all four before declaring a deep-clean done.

Routing

Hermes lane (Steps 0–3)

Grok lane (Steps 0–7, run by Grok Build)