mixdog 0.9.169 → 0.9.170

package/README.md

@@ -1,29 +1,25 @@
 # Mixdog
 
 [![npm](https://img.shields.io/npm/v/mixdog)](https://www.npmjs.com/package/mixdog)
-![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)
+![Node.js ^22.19.0 || >=24.0.0](https://img.shields.io/badge/node-%5E22.19.0%20%7C%7C%20%3E%3D24.0.0-brightgreen)
 ![license](https://img.shields.io/badge/license-Apache--2.0-blue)
 
-## The most efficient harness. The easiest way to use it.
+## More work. Less cost. Less complexity.
 
-Mixdog's goal is simple: make the most efficient AI coding harness the
-easiest to use. Get more work done with the same model and budget, without
-needing to become an expert in agent infrastructure.
+Get more from your models and budget with an efficient AI coding
+harness—and intuitive controls for managing sessions, agents, and your
+entire workflow.
 
-That means more than an easy first run. Advanced capabilities should be easy
-to access, configure, and manage as your work grows—from choosing a model
-to coordinating agents and shaping your own workflows.
-
-- **Efficiency that turns into more work.** Cache-aware context, focused
+- **More work for your budget.** Cache-aware context, focused
   tools, and compaction reduce overhead so more of your budget goes toward
-  the task. The same-model Terminal-Bench comparisons below show comparable
+  the task. The published same-model Terminal-Bench comparisons below show comparable
   or better results with smaller contexts and lower costs at the same API rates.
-- **Advanced capabilities, within easy reach.** Guided setup and visual
-  controls help you assign models by role, configure workflows, and work
-  with parallel agent sessions without building your own agent stack.
-- **Simple to manage. Flexible when you need it.** Manage providers, agents,
-  workflows, and extensions in one app. Customize agent definitions and
-  operating rules, or add skills, MCP servers, hooks, and plugins as needed.
+- **Easy to start. Simple to manage.** Guided setup and visual controls
+  help you choose models, assign agent roles, and configure workflows without
+  becoming an expert in agent infrastructure or building your own stack.
+- **One workspace, your way.** In Desktop, organize parallel sessions with
+  tabs and split panes, customize agents and workflows, and keep token
+  statistics and supported provider limits in view.
 
 Use supported subscription accounts, API keys, or Mixdog's built-in Local Provider.
 Take the same agent beyond code into browsers, Windows apps, documents,
@@ -59,6 +55,37 @@ mixdog
 First run guides you through provider authentication, model selection, and
 workflow setup.
 
+## One workspace for your sessions and agents
+
+Run multiple AI sessions side by side and manage your agents in Desktop.
+Combine tabs and split panes, customize how you work, and keep token usage
+and supported provider limits in view.
+
+- **Multiple sessions, manageable agents.** Keep separate tasks in separate
+  sessions and work on them in parallel. Manage agent definitions, assign
+  models by role, and configure workflows in one app instead of assembling
+  your own agent stack.
+- **Tabs and split panes—together.** Use tabs to organize sessions and split
+  panes to follow several side by side. Each pane can hold its own tabs, so
+  you do not have to choose between quick switching and a simultaneous view.
+- **Make the workspace your own.** Visual controls put layout, providers,
+  models, agent rules, workflows, and extensions within easy reach. The model
+  picker shows pricing, context limits, and capability metadata to help you
+  choose—not just a list of model names.
+- **See where your tokens go.** Usage statistics break down token totals by
+  provider and model, including input, output, cache hits, and cache hit rate,
+  with trends and cost figures. Subscription values use list prices; API
+  costs may be estimates. Neither is an invoice.
+- **Keep remaining usage in sight.** The usage panel brings supported
+  providers' quota windows and reset times together, reducing trips to
+  separate account dashboards. Available figures depend on the provider.
+- **Less window switching.** Chat, a Monaco code editor, Git, terminals, and
+  a file explorer share one workspace, keeping the conversation close to the
+  files and changes you are working on.
+- **Pick up on another screen.** Continue the same live session from Desktop,
+  TUI, or a paired browser on your computer or phone, without starting a
+  separate conversation.
+
 ## Benchmarks
 
 Terminal-Bench 2.1 — same model, same 89 tasks, same official verifier, with
@@ -100,6 +127,26 @@ task checksums, and the usage snapshots behind every cost figure — alongside
 the harness, presets, and metric scripts that recompute each number above:
 [`benchmarks/terminal-bench-2.1/`](benchmarks/terminal-bench-2.1/).
 
+## Less overhead. More budget for the work.
+
+Mixdog reduces the overhead of repeatedly sending context, re-explaining
+requirements, and rediscovering prior work. Focused tools keep unnecessary
+text out of the prompt, while provider-aware caching reuses stable input.
+
+Compaction keeps long conversations manageable with a handoff for continuing
+the task. Optional idle-time compaction reduces the history resent after
+long breaks, when provider caches may have expired. Approved memory and
+past-work retrieval help carry earlier decisions and requirements forward
+without loading the entire conversation archive into every prompt.
+
+You do not have to use the same high-cost model for every role. Choose models
+by role and workflow to focus your budget on the work that needs them.
+
+The benchmarks above measure single-model, single-session runs without
+personal memory, sub-agent delegation, or helper-model lookups. Their cost
+figures already account for cache usage; savings in ongoing work depend on
+the provider, workload, and configuration.
+
 ## How Mixdog keeps context lean
 
 Efficiency comes from several layers working together, not just a shorter

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.169",
+  "version": "0.9.170",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/src/agents/front-worker/AGENT.md

@@ -9,5 +9,3 @@ Implement the requested visual outcome while preserving existing interaction
 behavior and project conventions. Keep changes targeted and maintain hierarchy,
 consistency, responsiveness, and accessibility when relevant. Preserve source
 formats and naming conventions for asset work.
-
-Hand off the completed visual outcome and changed files or assets.

package/src/agents/heavy-worker/AGENT.md

@@ -8,10 +8,5 @@ Own high-complexity implementation through staged delivery.
 Map the affected architecture and dependencies, divide the work into coherent
 stages, and execute them in dependency order. Preserve existing behavior unless
 the brief explicitly changes it, and control blast radius across boundaries.
-
-When a required decision, dependency, or ownership boundary is unresolved,
-stop and report it with the relevant `file:line`.
-
-Hand off the completed outcome, material design decisions, and changed
-`file:line`.
+Hand off material design decisions with the outcome.
 

package/src/agents/maintainer/AGENT.md

@@ -1,4 +1,6 @@
 ---
+name: Maintainer
+description: Use for internal Git operations, memory upkeep, session naming, and other Mixdog background operations.
 permission: read-write
 ---
 

package/src/agents/worker/AGENT.md

@@ -9,8 +9,3 @@ Implement the assigned task directly. Keep changes focused on the requested
 outcome, follow exact constraints and established project patterns, and avoid
 unrelated cleanup or redesign.
 
-When blocked, stop at the first concrete boundary and report the blocker with
-the relevant `file:line`.
-
-Hand off the completed outcome and changed `file:line`.
-

package/src/agents/writer/AGENT.md

@@ -9,6 +9,6 @@ Preserve meaning, facts, terminology, formatting, and intended audience while
 making the writing natural and consistent with the document's tone. Translate
 idiomatically rather than word-for-word.
 
-Do not invent facts, add commentary, or delegate the work. Return final copy
+Do not invent facts or add commentary. Return final copy
 only unless the brief explicitly assigns file edits; then hand off changed
 paths.

package/src/defaults/skills/code-tidy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: code-tidy
-description: Format, lint, and structurally tidy a codebase with the tidy tool.
-when_to_use: 'Format, lint, apply structural rules, or tidy a codebase; not ordinary feature work or adding formatter configs.'
+description: Format, lint, apply structural rules, and clean up recent changes with the tidy tool.
+when_to_use: 'Format, lint, tidy, simplify, deslop, or clean up a codebase or recent changes: remove AI slop, dead code, and needless complexity without changing behavior; not feature work, bug hunting, or adding formatter configs.'
 metadata:
   requires: tidy
 dependencies:
@@ -12,58 +12,92 @@ dependencies:
 
 # Code tidy (tidy tool)
 
-Use `tidy` to format, lint, apply structural rules, and then — only if still
-needed — do agent-level structural cleanup. The schema owns action fields;
-this file owns order, approvals, and what must not change.
+Three layers, cheapest and safest first: the project's formatters and linters
+through `tidy`, then the structural rule packs, then agent-level cleanup of
+the code in scope. Every layer preserves behavior and public API; this is a
+cleanup pass, not a bug hunt. The schema owns action fields; this file owns
+scope, order, approvals, and what must not change.
 
 ## 1. Which job
-**Hard rule — tidy owns format/lint/structure, not feature work**: a request
-to clean, format, lint, apply structural rules, or tidy a tree. New behavior,
-refactors that change public API, and adding formatter configs are not this
-skill. → manual
-**Hard rule — never invent a formatter config**: if the project already has
-Biome, Prettier, clang-format, rustfmt, gofmt, or equivalent config/tools,
-tidy uses them. Do not add or rewrite `biome.json`, `.prettierrc`,
-`.clang-format`, or similar unless the user asks. → manual
+**Hard rule — tidy owns format/lint/structure/cleanup, not feature work.**
+New behavior, refactors that change a public API, and adding formatter configs
+are not this skill. A correctness bug found while cleaning is reported under
+"Bugs found", never folded into a cleanup edit. → manual
+**Hard rule — never invent a formatter config**: a project that already has
+Biome, Prettier, clang-format, rustfmt, gofmt, or equivalent keeps it. Do not
+add or rewrite `biome.json`, `.prettierrc`, `.clang-format`, or similar unless
+the user asks. → manual
+**Mode**: `apply` unless the user asks to check, review, or "just report" —
+then every layer stays dry-run and the report lists what would change.
+**Focus**: an explicit focus ("only dead code", "efficiency") restricts the
+agent layer to that lens; the deterministic layers still run.
 
-## 2. Call order
-1. `tidy action:'scan'` first. Result: languages and engines (used / missing /
-   `installHint`). Scan does not download and does not return `needsApproval`.
-2. **Hard rule — downloads happen automatically under the default `auto`
-   policy; only when the user set `tidy.downloads` to `ask` does a result
-   carry `needsApproval` — then ask once**, list engines and bytes, and
-   re-call that action with `approveDownloads:true`. Never download without
-   that when policy is `ask`. → manual
-3. **Hard rule — never install toolchain engines**: rustfmt, gofmt, dart,
-   swift, zig, mix, dotnet. Report `installHint`; do not brew/choco/npm/cargo-
-   install them. Managed engines (including PSScriptAnalyzer) download only
-   through tidy (`auto` policy, `approveDownloads`, or `action:'install'`). → manual
-4. Deterministic engines, then structural rules, then agent cleanup. Skip a
-   layer that the scan shows has nothing to do.
+## 2. Scope
+Default scope is the recent change, not the tree:
+1. `git status --short` (untracked files) plus `git diff --name-only HEAD`
+   (staged and unstaged). Empty → the merge-base diff against the default
+   branch. Still empty → the files the user named or edited this session.
+   Nothing at all → say there is nothing to tidy and stop.
+2. Drop deleted, binary, generated, vendored files and lockfiles.
+3. Widen only when the user asks ("the whole tree", a directory, a branch).
+4. Pass the list as `paths` on every `tidy` call so engines, rules, and the
+   agent layer see the same files. Result: the report names the scope.
 
-## 3. Deterministic first
-Each mutating step is dry-run then apply. `fix` is dry-run unless
-`apply:true`. After every apply, run the project's tests/typecheck (detect
-from `package.json` / `Cargo.toml` / `pyproject`) and **stop on failure**.
+## 3. Deterministic layers
+1. `tidy action:'scan'` first: languages and engines (used / missing /
+   `installHint`). Scan never downloads and never returns `needsApproval`.
+2. **Hard rule — downloads are automatic under the default `auto` policy;
+   only when the user set `tidy.downloads` to `ask` does a result carry
+   `needsApproval` — then ask once**, list engines and bytes, and re-call
+   that action with `approveDownloads:true`. → manual
+3. **Hard rule — never install toolchain engines** (rustfmt, gofmt, dart,
+   swift, zig, mix, dotnet): report `installHint`. Managed engines download
+   only through tidy (`auto`, `approveDownloads`, or `action:'install'`). → manual
+4. Engines, then structural rules, each dry-run then apply, with the
+   project's tests/typecheck after every apply and a stop on failure:
+   - engine `check` with `structural:false`;
+   - engine `fix` with `structural:false`, then the same call with `apply:true`;
+   - `tidy action:'fix' structural:true`, then `apply:true`.
+   `structural` defaults to true on check/fix, so engine steps must pass
+   `structural:false` or structural fixes land during the engine write. A
+   dry-run with no changes skips that apply. Rules without a fix
+   (`no-empty-catch`, `no-nested-ternary`, `no-any-cast`,
+   `no-boolean-literal-compare`, `no-debug-statement`, `todo-marker`) are
+   diagnostics for the agent layer, not changes. Skip a layer the scan shows
+   has nothing to do.
 
-1. Engine `check` with `structural:false` (report-only).
-2. Engine `fix` with `structural:false` (omit `apply` or `apply:false`) → the
-   same call with `apply:true`.
-3. Structural rules: `tidy action:'fix' structural:true` (dry-run) →
-   `apply:true`.
-4. Agent-level structural cleanup only after those, still one concern per
-   change set, still dry-run (read/plan) before edits.
+## 4. Agent-level cleanup
+Read `references/agent-cleanup.md` first: it owns the deletion ladder, the
+lens checklists, the slop categories, the risk tiers, and the report
+template. This section owns the order.
 
-**Default — dry-run before every apply.** A dry-run that reports no changes
-skips apply for that layer. Engine steps must pass `structural:false`:
-`structural` defaults to true on check/fix, so omitting it would apply
-structural fixes during the engine write.
+1. **Lock behavior.** Run the project's tests and typecheck before any edit.
+   Green, or pre-existing failures listed as excluded, is the baseline; a
+   broken runner stops the layer with a report. A file with no test covering
+   the behavior you will touch gets either the narrowest regression test that
+   pins its observable output, or only SAFE-tier changes — say which. Prose
+   files (skills, prompts, docs) have no behavior to pin.
+2. **Ladder, then lenses.** Run the deletion ladder on every changed unit;
+   only survivors go through the four lenses (reuse, quality, efficiency,
+   altitude). Every finding carries `file:line` evidence, a cost, a
+   confidence, and a risk tier; findings without evidence are dropped, and
+   `git blame` precedes any removal (unexplained intent is `confidence: low`).
+   When this session can delegate to parallel workers, run one lens per
+   worker with the complete diff and the repo path — workers report findings,
+   never edit. Otherwise run the lenses yourself in sequence and say so in
+   the report. Result: one merged, deduplicated finding list.
+3. **Apply by tier.** SAFE as one batch with tests after it; CAREFUL one
+   file at a time with tests after each file, reverting the file on failure;
+   RISKY reported, never auto-applied. Within a tier: comments → dead code →
+   defensive code → duplication → complexity → abstraction → performance.
+   Structural items from the table below are CAREFUL; dead code follows
+   `references/dead-code.md`.
+4. **Stop rules.** Three failed attempts on one file → stop and escalate with
+   what was tried. A deeper fix larger than the cleanup → report it as its own
+   task. Principles cannot pick between two rewrites → apply neither, record
+   both.
 
-## 4. Agent-level structural cleanup
-Behavior and public API stay unchanged. Tests are the gate. One concern per
-change set. Report what changed and what was left, with reasons.
-
-| Threshold | Action |
+| Structural threshold | Action |
 |---|---|
 | File > 800 lines | Split by responsibility |
 | Function > 50 lines, or nesting > 3 | Extract |
@@ -73,19 +107,49 @@ change set. Report what changed and what was left, with reasons.
 | Magic numbers | Name them |
 | Dead code / unused exports | Remove |
 
-Do not "improve" names, control flow, or types beyond this list.
+Do not "improve" names, control flow, or types beyond the ladder, the lenses,
+and this table.
+
+## 5. Keep — never remove or rename
+- Validation and error handling at a trust boundary (user input, external
+  API, file, network) unless an adversarial test proves the guard redundant.
+- Export names, API routes, CLI flags, DB columns, config keys, event names,
+  wire strings — contracts; a rename is RISKY even when the name is bad.
+- Anything on the never-dead list in `references/dead-code.md`.
+- An empty catch or ignored error that may be intentional — flag it.
+- Complexity a comment or `git blame` explains: compat shims, staged
+  migrations, isolation around vendored code.
+- The project's own idioms: `AGENTS.md`/`CLAUDE.md`/lint config beat a
+  generic idiom; clarity beats fewer lines; nested ternaries are flattened,
+  never introduced.
 
-## 5. Failure handling
+## 6. Pitfalls
 - Missing toolchain engine → `installHint` only; continue other engines.
 - User declines downloads → skip those engines; say so.
-- Tests/typecheck fail after apply → stop; do not apply the next layer.
-- Formatter config missing and the user did not ask to add one → use tidy
-  defaults / detected engines; do not write a config file.
+- Tests/typecheck fail after apply → revert that change; do not start the
+  next layer until the baseline is green again.
+- Formatter config missing and the user did not ask to add one → tidy
+  defaults / detected engines; never write a config file.
 - Structural engine unavailable (missing or outdated mixdog-graph) → `check` /
-  `fix` fail with a rebuild remedy. `scan` still succeeds and names the binary
-  in `notes`. Retry with `structural:false` for formatters/linters only. Do
-  not treat missing structural matches as clean.
+  `fix` fail with a rebuild remedy; `scan` still succeeds and names the binary
+  in `notes`. Retry with `structural:false` for formatters/linters only; never
+  treat missing structural matches as clean.
+- Diff over ~2000 changed lines → split the agent layer per directory or
+  commit before running the lenses; one huge pass truncates.
+- A dead-code scanner report is a candidate list, not proof → verify per
+  `references/dead-code.md` before deleting.
+
+## 7. Report
+Use the template in `references/agent-cleanup.md`. It must name the scope and
+mode, engines used/missing, files changed, diagnostics remaining, structural
+matches applied/skipped, agent findings applied by lens and tier, **Noticed
+but not applied** with the reason, deferred debt, bugs found, and the test,
+typecheck, and lint results. An inline (non-delegated) lens run is stated as
+such.
 
-## 6. Report
-Always report: languages, engines used/missing, files changed, diagnostics
-remaining, structural matches applied/skipped, test results.
+## 8. References
+- `references/agent-cleanup.md` — before section 4: ladder, lenses, slop
+  categories with keep/fix rules, test-suite slop, risk tiers, report
+  template.
+- `references/dead-code.md` — before removing any unused symbol, file, or
+  dependency: candidate sources, verification, never-dead list, order.

package/src/defaults/skills/code-tidy/references/agent-cleanup.md

@@ -0,0 +1,149 @@
+# Agent-level cleanup
+
+Read this before the agent-level layer of `code-tidy`. It owns the deletion
+ladder, the lens checklists, what counts as slop, the risk tiers, and the
+report shape. The skill body owns scope, order, approvals, and the list of
+things that are never removed or renamed.
+
+## Deletion ladder
+
+Run the ladder on every changed unit (function, class, module, config knob)
+before looking for smells. Only code that lands on the last rung goes on to
+the lenses.
+
+| Rung | Question | Typical win |
+|---|---|---|
+| Delete | Is the behavior needed at all? Speculative generality, a flag nobody sets, a branch no caller reaches | whole unit gone, tests that only guarded it gone with it |
+| Reuse | Does a helper in this repo already do it? (`code_graph symbol_search`, `grep` for the pattern's distinctive call) | reimplementation replaced by a call |
+| Platform | Does the stdlib, runtime, or an already-installed dependency do it? (`URLSearchParams`, `path.relative`, `Array.prototype.at`, `pathlib`, an imported util) | hand-rolled parser/formatter/debounce replaced |
+| Simplify | It must exist here; make it smaller | proceeds to the lenses |
+
+A unit replaced by one platform call is a larger and safer win than any
+in-place cleanup; take it before analysing the unit's smells.
+
+## Lenses
+
+Each lens searches the codebase for evidence; a finding without a
+`file:line` pointer is dropped. Run every lens unless the user named a focus.
+
+**Reuse** — new code that duplicates an existing utility, constant, type
+guard, or pattern: hand-rolled string/path manipulation, custom env checks,
+ad-hoc validation, re-implemented parsing. Name the existing thing and where it
+lives. Before flagging a new dependency import, check `package.json` /
+`pyproject.toml` for a library already installed that covers it.
+
+**Quality** — redundant state (values derivable from existing state, caches
+that need not exist); parameter sprawl (a parameter bolted on where the
+function should be restructured); copy-paste-with-variation; leaky
+abstractions; stringly-typed code where a constant, enum, or registry exists;
+deep nesting (3+ levels, ternary chains) that guard clauses or a lookup table
+flatten; slop patterns from the table below.
+
+**Efficiency** — redundant computation, repeated file reads, duplicate API
+calls, N+1 access; independent operations run sequentially; heavy work on
+startup or per-request paths; existence pre-checks instead of doing the
+operation and handling the error; unbounded growth, missing cleanup,
+listener/handle leaks; closures capturing a whole scope for long-lived
+objects; whole-file reads where a slice would do; silent failures (empty
+catch, ignored error return, `.catch(() => {})`). Only apply an efficiency
+change whose behavioral equivalence is obvious; never restructure an
+algorithm with subtle correctness implications without a test that pins it.
+
+**Altitude** — a fix applied too shallowly: a caller-specific branch added to
+a generic path (`if (caller === X)`, a magic-value escape hatch); a symptom
+patched at one call site while siblings keep the same flaw; a workaround
+stacked on a workaround; a wrapper added to avoid touching the thing that
+needs changing; a flag introduced to route around a broken default. Name
+the mechanism the change is dodging and the deeper fix. When the deeper fix
+is larger than the cleanup, report it as its own task instead of doing it
+here.
+
+## Slop categories
+
+| Category | Flag | Keep | Fix |
+|---|---|---|---|
+| Obvious comments | restating the code, section dividers, commented-out code, vague TODOs, narration of the change or of the caller | WHY comments (business rule, workaround, invariant), ticket links, regex/algorithm notes, BDD markers | delete |
+| Over-defensive code | null checks on guaranteed values, try/catch around code that cannot throw, type checks on statically typed params, defaults for required params, validation duplicated inside a boundary, broad catch-all | I/O error handling, nullable DB fields, a top-level catch-all that logs and rethrows | remove only when a test proves the guard redundant; narrow broad catches to the expected error |
+| Excessive complexity | nesting > 3, nested ternaries, 4+ predicates in one condition, > 5 positional params, functions > 50 lines doing several things, clever one-liners | a hot path that intentionally uses a dense idiom | guard clauses, early returns, explicit if/else, an options object, extract by responsibility |
+| Needless abstraction | pass-through wrappers, single-use helpers, speculative indirection, one-implementer interfaces that add no seam, factories that only call a constructor | abstractions that give a real seam (tests, multiple implementers, framework boundary) | inline |
+| Boundary violations | wrong-layer imports, business logic in a handler, one module reading another's private state, side effects in a pure-named function | short-circuits already established as a pattern here | move to the owning layer; flag when unsure |
+| Dead code | unused imports/locals/private functions, unreachable branches, stale feature flags, debug leftovers, code removed but still referenced | whatever the dead-code procedure lists as never dead | remove through the dead-code procedure linked from the skill |
+| Duplication | copy-pasted branches with trivial differences, two helpers doing the same thing, repeated literal sequences | incidental similarity between things that serve different intents and may diverge | consolidate only when intents match |
+| Type escapes | `as any`, `@ts-ignore`, `# type: ignore` without reason, `object`/`Any` annotations where a union or Protocol fits | escapes with a comment naming the upstream typing bug | narrow with a guard, a precise type, or `unknown` plus a check |
+| Oversized modules | files well past the project's norm (the skill's 800-line threshold), mixing responsibilities | a self-contained single-responsibility script | split by what each part does; never `utils`/`helpers`/`common`/`part2` dump files |
+
+## Test-suite slop
+
+Only when tests are in scope. Tests accumulate through repeated
+agent corrections the same way production code does:
+
+- **Dominated tests** — several tests reach the same branch and the same
+  result; one asserts the observable output, the others only check
+  construction, type, or non-emptiness. Keep the strongest, delete the rest
+  and the fixtures that served only them.
+- **Verification theater** — checksums, receipts, validators, or
+  recomputation where producer and verifier share the same information and
+  failure domain. They cannot fail independently; delete.
+- **Closed justification loop** — a fallback exists because a test exercises
+  it and the test exists because the fallback was added. Neither is evidence
+  for the other; delete the pair. A test of a distinct externally observable
+  rejection, error, or compatibility behavior is *not* a loop — it is that
+  behavior's clearest specification, keep it.
+- Reducing tests never justifies changing the production behavior they
+  exercised; that needs its own evidence (a current requirement, a real
+  caller, a spec).
+
+## Finding record and risk tiers
+
+Record every finding as:
+
+```text
+file:line → problem → cost (what it duplicates, wastes, or makes harder) → fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
+```
+
+A finding that cannot name its cost is a nit; drop it. Confidence is `low`
+when `git blame` and surrounding comments do not explain why the code exists.
+
+| Tier | Meaning | Examples | Handling |
+|---|---|---|---|
+| SAFE | provably no behavior change | unused import, commented-out code, pass-through wrapper, redundant type assertion, obvious comment, history comment | apply, run tests once after the batch |
+| CAREFUL | same semantics, structure changes | rename a local, flatten a ternary, guard clause, extract a helper, consolidate duplicates, name a magic number | apply one file at a time, tests after each file, revert the file on failure |
+| RISKY | may change behavior or a contract | public API or export rename, route/DB column/config key rename, error-handling change, concurrency change, N+1 restructuring, altitude fix in shared infrastructure | report only, with the test coverage status; never auto-apply |
+
+Conflict resolution when lenses disagree: correctness > the user's stated
+focus > readability and reuse > micro-performance. When two defensible
+rewrites of the same region remain, apply the one that touches less code and
+record the alternative; when the principles cannot separate them, apply
+neither and record both.
+
+## Small tidyings (CAREFUL tier)
+
+Structure-only moves that read better and never change behavior: guard clause
+instead of nested `if`; normalize two variants of the same pattern to one
+form; put coupled functions next to each other; declare a variable where it
+is initialized; name a sub-expression or a literal after its intent; blank
+line between chunks that do different things; extract a helper with an
+obvious purpose; merge over-fragmented pieces back into one readable block
+before re-splitting; delete comments that say what the code says. One
+tidying per change set.
+
+## Report shape
+
+```text
+Scope: <diff vs HEAD | paths | branch> · Mode: report|apply
+Baseline: tests <green|N pre-existing failures excluded> · typecheck <ok|…>
+Deterministic: engines used/missing · files changed · diagnostics remaining · structural matches applied/skipped
+
+Applied
+  path/file.ts
+    ✓ [Quality/SAFE]   removed comment narrating the change (L31)
+    ✓ [Reuse/CAREFUL]  replaced manual join with `joinPath` from src/shared/path.mjs (L53)
+
+Noticed but not applied
+  ⚠ [Altitude/RISKY] special case for caller X in src/core/run.mjs:88 — deeper fix: default in run() · coverage: none
+  ⚠ [Quality]        two equal rewrites of parseInput (L70-74); principles could not decide
+
+Deferred debt: <`debt:` markers added, with their ceiling and trigger>
+Bugs found (not fixed here): <correctness issues surfaced while cleaning>
+Verification: tests <result> · typecheck <result> · lint <result>
+```

package/src/defaults/skills/code-tidy/references/dead-code.md

@@ -0,0 +1,71 @@
+# Dead code removal
+
+Read this before removing any unused symbol, file, or dependency. A tool
+report is a candidate list, never proof: exports reached through dynamic
+import, reflection, string lookup, templates, or configuration look unused
+to every scanner.
+
+## Candidates
+
+Collect from what already runs in the project; never install a scanner and
+never route one through `tidy` (they are not tidy engines):
+
+| Source | Gives | Notes |
+|---|---|---|
+| `tidy check` diagnostics | unused imports/variables from Biome, ruff (`F401`, `F841`), ESLint `no-unused-vars` | exact file:line, safest tier |
+| `tsc --noEmit --noUnusedLocals --noUnusedParameters` | unused locals, imports, parameters, private members | TypeScript projects; run through the project's own `tsc` |
+| `knip` (`node_modules/.bin/knip`) | unused files, exports, types, dependencies | JS/TS; only when the project already depends on it |
+| `vulture` (in the project's venv) | unused functions, classes, imports with confidence | Python; only when present |
+| `deadcode` (Go, `golang.org/x/tools`) / `cargo machete` | unreachable functions / unused crates | only when on PATH |
+| `code_graph mode:symbols` per changed file | private helpers with no callers (`callers`) | universal, no install |
+
+## Verify every candidate
+
+1. `code_graph mode:references symbols:[name]` — zero references outside the
+   declaration is the first gate, not the last.
+2. `grep` the bare name across the whole repository, including tests,
+   configs, templates, docs, JSON/YAML, and string literals: `'name'`,
+   `"name"`, `.name(`, `name:`. A hit in a string or template means the
+   symbol is reached dynamically; keep it.
+3. Apply the never-dead list below.
+4. Record the candidate as `file:line → symbol → kind → action → evidence`.
+
+## Never dead
+
+- Entry points: `main`, `index`/barrel files, CLI commands, `bin` scripts,
+  `package.json` `exports`/`main`/`bin` targets, framework-discovered files
+  (routes, migrations, plugins, fixtures).
+- Public API of a library package: any export from the package entry.
+- Symbols referenced by tests — tests are consumers; delete the test first
+  only when the behavior itself is being removed on separate evidence.
+- `@public`/`@api` annotated symbols, registry or factory tables
+  (`create…Tool`, `register…`), event names, wire strings, config keys.
+- Feature-flag rollback paths that a comment or docs name as intentional;
+  confirm with the user before removing.
+- A required-by-signature unused parameter: rename to `_name`, never remove.
+
+## Remove in order
+
+1. Unused imports and locals (SAFE).
+2. Unused private functions, methods, constants (SAFE once verified).
+3. Unused exports (CAREFUL) — after the never-dead check.
+4. Orphan files (CAREFUL) — a file nobody imports; delete whole, then grep
+   for its path in configs and docs.
+5. Dependencies in `package.json` / `pyproject.toml` (CAREFUL) — last, after
+   the code that used them is gone; keep the lockfile consistent through the
+   project's own package manager.
+
+Group edits by file so one batch never touches a file another batch edits.
+After each batch run the project's typecheck and tests; on failure revert
+that batch's files (`git checkout -- <files>` or targeted edits) and report,
+do not patch forward.
+
+## Report
+
+```text
+| # | File:line | Symbol | Kind | Action | Evidence |
+|---|---|---|---|---|---|
+| 1 | src/foo.ts:42 | unusedFunc | function | removed | 0 refs, no grep hits |
+| 2 | src/baz.ts:7 | ctx | parameter | prefixed _ | required by signature |
+| 3 | src/api.ts:10 | legacyRoute | export | kept | string lookup in routes.json |
+```