v3.1.1 — deep-scan hardening

Three read-only deep-scan passes walked v3.1.0 the way a user would — a cold agent following every pointer, the four commands and three scripts against a real project, and the docs line-by-line against actual behavior. This release fixes everything that survived verification. No new features; every change makes an existing promise true.

The one that could lose your data

detect_stack.py --write used to overwrite .clean/context.json — so running the audit after /clean-code questions silently destroyed the interview's answers. It now merges: detector-owned keys are refreshed, and a reserved confirmed object (purpose, actors, verify command, load-bearing dependencies, notes) plus any unknown keys survive. The interview writes into confirmed; the schema is in memory-protocol.md. A CI round-trip test keeps it that way.

Honest failure modes

• check_boundaries.py fails (exit 2) when its globs match no files instead of passing while checking nothing — a copied-but-unedited template can no longer produce a green fitness function.
• scan_repo.py --json is now always complete; --top caps only the human summary. The audit's convergence loop compares full lists, so fixing the worst offender no longer surfaces entry 16 as a phantom "new finding".
• scan_repo.py --changed says so when git is unavailable (stderr warning + scope_note in JSON) instead of reporting an empty scan that reads as a clean change.
• The pre-commit hook now finds the skill in every install location — .grok/skills and the global roots (~/.claude/skills, ~/.agents/skills, ~/.grok/skills, ~/.gemini/config/skills) — and tells a config error (fix the declaration) apart from a violation (invert the dependency). claude-settings.json probes locations and python3/python/py instead of hardcoding both.

Protocol repairs

• One rule for who creates .clean/, stated once: reading is always fine; creating belongs to audit and questions. A plain session works from inspection and offers to persist at the end.
• clean-up on a bare repo asks first: it proposes the audit with the project's file count and waits for consent — two typed words no longer launch hours of unasked work.
• The ledger template finally has the ## Audit Coverage section the audit protocol has instructed since 3.1.0; section names are now identical across template, memory-protocol, and project-refactor.
• The audit scales honestly: per-file ticks to ~500 files, per-directory with flagged-file detail to ~2,000 (shape agreed with the user), module-scoped audits beyond. Denominator (git ls-files), report destination (the conversation), and full-JSON sweep comparison are now explicit.
• new-project <description> finally says what the description is for: the draft answers to Phase 0 — extract what it answers, ask what it leaves open.
• argument-hint moved into SKILL.md frontmatter where Claude Code reads it (other hosts ignore unknown keys per spec). Budget after all edits: 4,999 / 5,000 tokens on the strict counter.

Docs to truth

install.ps1's help and error strings caught up with the grok and antigravity profiles it already implements. The README's .clean/ table, validator paragraph, detect_stack example, audit example, host counts, and global-root list now match the code. All four plugin manifests finally mention clean architecture, the Dependency Rule, and the four commands. The 3.1.0 changelog entry was backfilled with the three commits it missed.

Install / update

npx skills add btseee/clean-code-skills --skill clean-code

or the full installer with adapter blocks:

curl -fsSL https://raw.githubusercontent.com/btseee/clean-code-skills/main/scripts/remote-install.sh | bash -s -- --detect

Full details in CHANGELOG.md. No book text is reproduced anywhere in this package.