mixdog 1.4.1 → 1.4.2

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

@@ -15,45 +15,37 @@ dependencies:
 Layers, cheapest and safest first: project formatters and linters through
 `tidy`, structural rule packs, then agent-level cleanup. Every layer preserves
 behavior and public API; this is not a bug hunt. The `tidy` schema owns action
-fields; this file owns scope, order, and boundaries. Verification follows the
-shared rule: finish all planned edits, then check once (section 5).
+fields; this file owns scope, order, and boundaries.
 
 ## 1. Job and mode
-- Tidy owns format, lint, structure, and cleanup, not feature work. New
-  behavior and public-API refactors are out of scope. A correctness bug found
-  while cleaning goes under "Bugs found", never into a cleanup edit.
-- Never invent a formatter config. A project with Biome, Prettier,
-  clang-format, rustfmt, gofmt, or equivalent keeps it; add or rewrite
-  `biome.json`, `.prettierrc`, `.clang-format` and the like only when asked.
+- New behavior and public-API refactors are out of scope. A correctness defect
+  found while cleaning is reported, never fixed in a cleanup edit.
+- Never invent a formatter config; a project's own formatter stays. Add or
+  rewrite one only when asked.
 - Mode is `apply` unless the user asks to check, review, or "just report";
   report-only stays read-only on every layer and lists what would change.
-- An explicit focus restricts every layer ("formatting only" excludes lint
-  and semantic cleanup; "only dead code" excludes unrelated formatting). If
-  the tool cannot isolate it, use targeted edits or report the limitation
-  and ask before widening.
+- An explicit focus restricts every layer. If the tool cannot isolate it, use
+  targeted edits or report the limitation and ask before widening.
 
 ## 2. Scope
 1. Scope comes from the user: named files, directories, a feature area
    resolved to confirmed paths, or an explicitly requested whole project. If
    absent or ambiguous, ask first. Never infer it from a diff, branch,
    commit, or recent activity.
-2. Recommend (do not require, do not do it for them) that the user commit
-   existing work before an apply run. A dirty tree means preserve those edits.
+2. Recommend (do not require) that the user commit existing work before an
+   apply run. A dirty tree means preserve those edits.
 3. Drop deleted, binary, generated, vendored files and lockfiles unless
    explicitly included. Consumers and covering tests may be read; editing
    them outside the scope needs approval. New non-ignored files are included.
 4. Pass the approved paths on every `scan`/`check`/`fix`; `paths:["."]` only
    for an explicitly requested whole project.
-5. Too large to review in one pass (whole project, many directories):
-   partition by directory or responsibility so every source unit gets the
-   ladder and every survivor the lenses; hundreds of files per partition is
-   the usual failure. Work through all partitions without pausing for input.
-   Keep the partition list and candidate list across turns.
-6. Read per-rule and per-directory counts first, then page only relevant
-   rows with `tidy action:'results'` filters; never treat unreviewed in-scope
-   results as clean. Real engine truncation, timeouts, or scope leakage mark
-   that partition **unfinished**, not clean. Blocked checks stop dependent
-   edits only.
+5. For large scopes, review bounded partitions once. Preserve their
+   completion state; report blocked partitions without restarting completed
+   work.
+6. Read per-rule and per-directory counts first, then page only relevant rows
+   with `tidy action:'results'` filters. Truncation, timeouts, or scope
+   leakage mark that partition **unfinished**, not clean. Blocked checks stop
+   dependent edits only.
 
 ## 3. Deterministic layers
 1. `tidy action:'scan'` first (languages, engines used/missing,
@@ -61,109 +53,86 @@ shared rule: finish all planned edits, then check once (section 5).
 2. Downloads are automatic under the default `auto` policy. Only when
    `tidy.downloads` is `ask` does a result carry `needsApproval`: ask once,
    listing engines and bytes, then re-call with `approveDownloads:true`.
-3. Engines run only through `tidy` and are never installed by hand
-   (rustfmt, gofmt, dart, swift, zig, mix, dotnet: report `installHint`). An
-   ad-hoc `npx <engine>`, global binary, or package script is not
-   verification and may report a false clean. An engine `tidy` cannot resolve
-   leaves its check blocked, never clean.
-4. Plan with `fix` without `apply:true`; no separate `check` first. The dry
-   run is diagnostics and candidate files, not a frozen patch; apply
-   recalculates. `structural:true` (default) also runs ordinary engines;
-   `structural:false` disables structural rules only, not engine lint fixes.
-   For a restricted focus, do not use a combined apply that touches unrelated
-   code.
-5. Apply with `apply:true` once the plan for the scope is settled, then review
-   the actual changes. Skip apply when the dry run proposes nothing.
-   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. Keep the engine pass a distinct change
+3. Engines run only through `tidy` and are never installed by hand; report
+   `installHint`. An ad-hoc `npx <engine>`, global binary, or package script
+   is not verification. An engine `tidy` cannot resolve leaves its check
+   blocked, never clean.
+4. Plan with `fix` without `apply:true`. The dry run is diagnostics and
+   candidate files, not a frozen patch. `structural:false` disables
+   structural rules only. For a restricted focus, avoid a combined apply that
+   touches unrelated code.
+5. Apply with `apply:true` once the plan is settled, then review the actual
+   changes; skip it when the dry run proposes nothing. Rules without a fix
+   are diagnostics for the agent layer. Keep the engine pass a distinct change
    set from semantic edits. On engine or structural failure, truncation, or a
    rejected edit, stop affected writes; a partial result is not success.
 
 ## 4. Agent-level cleanup
 Read `references/agent-cleanup.md` (ladder, lenses, slop, risk tiers); also
 `references/test-suite-slop.md` when tests are in scope, and
-`references/cleanup-report.md` for recording and the closing report.
+`references/cleanup-report.md` for the report.
 
-1. **Pin behavior (read-only).** Search the tests for source-text guards
-   (shapes in `agent-cleanup.md`) before extracting or moving anything. A file
-   whose touched behavior no test covers gets the narrowest regression test
-   that pins it, or only SAFE changes. Prose files have no behavior to pin.
-2. **Ladder, then lenses.** Run the deletion ladder on every selected source
-   unit, then the four lenses on the survivors. Engine diagnostics point at
-   units; they do not define coverage. A partition reviewed only where an
-   engine flagged is unfinished. Each finding has a path+symbol location,
-   cost, action, confidence, and risk tier; drop findings without evidence.
-   Use history only when code, contracts, and tests leave intent unclear;
-   unresolved intent blocks deletion.
+1. **Pin behavior (read-only).** Find the source-text guards a planned move
+   can affect (procedure in `agent-cleanup.md`). A unit whose touched behavior
+   no test covers gets only SAFE changes; report it instead of adding tests.
+2. **Ladder, then lenses.** Run the deletion ladder on each selected source
+   unit, then the lenses on the survivors. Engine diagnostics point at units;
+   they do not define coverage. Findings need path+symbol evidence; drop the
+   rest. Use history only when code, contracts, and tests leave intent
+   unclear; unresolved intent blocks deletion.
 3. **Apply by tier.** SAFE as one batch; CAREFUL one source unit at a time,
-   each finished and wired into its callers (never leave a new module nothing
-   imports); RISKY is reported, never auto-applied. Order within a tier:
-   comments, dead code, defensive code, duplication, complexity, abstraction,
-   performance. 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.
+   each wired into its callers (never leave a new module nothing imports);
+   RISKY is reported with its evidence and applied only after the user
+   approves that item. Dead code follows
+   `references/dead-code.md`.
+4. **Stop rules.** Follow the shared verification budget. Report correctness
+   defects and changes beyond cleanup scope; do not fix them here. When
+   principles cannot pick between two rewrites, apply neither and record both.
 
-Structural signals are leads, not candidates: file > 1,000 lines, function
-> 50 lines or nesting > 3 (under ~100 lines, act only on a named symptom:
-duplication, a defect, demonstrated difficulty of change), duplicated small
-helpers (consolidate only when intent matches), history comments (remove only
-if no protected content is lost), underscore-prefixed names exported across
-modules (rename is RISKY). Do not improve names, control flow, or types
-beyond the ladder, lenses, and these signals. A confirmed
+Structural signals (file > 1,000 lines, function > 50 lines or nesting > 3,
+duplicated small helpers, history comments, exported underscore names) are
+leads, not candidates: act only on a named symptom. Do not improve names,
+control flow, or types beyond the ladder and lenses. A confirmed
 responsibility-based split that preserves behavior and entry points is
-CAREFUL; an extracted unit takes only the values it reads. Moving a whole
-body elsewhere or cutting it into numbered chunks resolves nothing.
+CAREFUL; moving a whole body elsewhere or cutting it into numbered chunks
+resolves nothing.
 
-## 5. Check once, then fix
-After every planned edit in the assigned scope is done, run the project's
-documented tests/typecheck covering the touched behavior and `tidy check` on
-the scope, once, in parallel. No check, build, lint, test, or formatter run
-before that. If it fails, read the full logs, finish the fixes, and rerun only
-the failed or invalidated checks. A failure on code you did not touch is
-pre-existing: report it separately. A broken runner leaves its scope
-unverified: say so. Skipped or failed checks never count as passed.
+## 5. Verify
+Use the shared evidence budget. Run scoped `tidy check`; select behavioral
+checks and typechecking only where the edits can invalidate their contracts.
+Reuse valid passes. Attribute failures from evidence, not from whether the
+failing file was edited. A broken runner leaves its scope unverified; say so.
+Skipped or failed checks never count as passed.
 
 If checks fail and cannot be fixed, undo only this run's edits with targeted
 patches, preserving prior or concurrent work. Never use `git checkout`,
 `reset`, `restore`, or `stash` as rollback; if the edits cannot be separated
 safely, leave them and report the blocker.
 
-New findings from the final `tidy check` (e.g. imports orphaned by removals)
-are fixed once if SAFE; others are reported.
-
 ## 6. 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.
+- Validation and error handling at a trust boundary unless an adversarial test
+  proves the guard redundant.
+- Contracts: export names, routes, CLI flags, DB columns, config keys, event
+  names, wire strings. 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 serving a current compatibility obligation, staged migration, or
-  vendored-code isolation (see legacy retirement in `dead-code.md`).
-- License, copyright, SPDX notices; compiler, linter, bundler directives;
-  public API docs; security and compatibility explanations. Block comments
-  that may separate tokens or carry significant line breaks are left for
-  manual review.
+  vendored-code isolation.
+- Tool directives, public API docs, and security or compatibility
+  explanations. Comments that may separate tokens or carry significant line
+  breaks are left for manual review.
 - The project's own idioms (`AGENTS.md`/`CLAUDE.md`/lint config) over generic
-  ones; clarity over fewer lines; nested ternaries are flattened, never added.
+  ones; clarity over fewer lines.
 
 ## 7. Pitfalls
 - Missing engine: `installHint` only; continue others; that check is blocked.
 - User declines downloads: skip those engines and say so.
-- Structural engine unavailable (missing or outdated mixdog-graph): `check`/
-  `fix` fail with a rebuild remedy; `scan` still works. Retry with
-  `structural:false` for formatters/linters only; missing structural matches
-  are never clean. A per-language rule-pack error leaves only that language
-  unfinished.
-- A dead-code scanner report is a candidate list, not proof; verify per
-  `references/dead-code.md`.
+- Structural engine unavailable: `check`/`fix` fail with a rebuild remedy;
+  `scan` still works. Retry with `structural:false`; missing structural
+  matches are never clean.
+- A dead-code scanner report is a candidate list, not proof.
 
 ## 8. Reporting
-Report once, after the last partition, using `references/cleanup-report.md`.
-Put everything needing the user's decision in one list at the end: RISKY
-findings, bugs found, unresolved intent, unfinished candidates. Do not pause
-between partitions except for a blocker or a required approval. No separate
-report file unless requested.
+Report once, after the last partition, using `references/cleanup-report.md`,
+with everything needing the user's decision in one list. Pause only for a
+blocker or a required approval. No report file unless requested.

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

@@ -1,135 +1,87 @@
 # 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, and the risk tiers. The skill
-body owns scope, order, approvals, and the list of things that are never
-removed or renamed.
+Owns the deletion ladder, lenses, slop categories, and risk tiers. The skill
+body owns scope, order, approvals, and the never-remove list.
 
 ## Behavior boundary
 
-Classify risk by evidence, not by syntax. Equivalence includes observable
-outputs and errors, side effects and module initialization, and any call
-identity, receiver, or asynchronous ordering that consumers rely on. Removing
-an unused binding can remove initialization; inlining a wrapper can change
-its call contract. Neither is SAFE merely because it looks redundant.
-
-Use current callers, contracts, and relevant tests to establish equivalence.
-Passing tests that do not exercise the affected behavior are not proof.
-An intended change to failures, returned values, compatibility, or concurrency
-is RISKY: report it as a separate correction or migration, not a cleanup edit.
-
-**Source-text guards.** Some tests assert on source text rather than behavior,
-so an extraction breaks them without touching behavior: a packaging test that
-reads three files as one concatenated string and enforces five `indexOf`
-orderings; a repo-wide audit asserting an identifier appears in no file outside
-two named modules; a coverage test requiring literal action names to stay in
-one file. Search the suite for them first (reads of source paths, ordering
-`indexOf` chains, identifier-absence assertions) and record what each pins;
-moving code across such a guard is a contract change, not a tidying.
-
-**Dependency arrays.** A hook or watcher dependency array that contradicts its
-own body — the body reads values the array does not key — is a defect
-candidate, not an idiom to preserve and report. Verify reachability at the
-producer: when the key can actually repeat (two publishers stamping
-`Date.now()` in the same millisecond drop the second update), fix it by adding
-the values the body reads while keeping the existing key, with a test that
-fails without the fix, delivered as its own change set under "Bugs found".
-When the producer makes repetition unreachable, leave the array and record that
-evidence as `kept`.
+Classify risk by evidence, not syntax. Equivalence includes observable outputs
+and errors, side effects and module initialization, and any call identity,
+receiver, or ordering consumers rely on. Removing an unused binding can remove
+initialization; inlining a wrapper can change its call contract.
+
+Establish equivalence from current callers, contracts, and tests that exercise
+the affected behavior. An intended change to failures, returned values,
+compatibility, or concurrency is RISKY: report it as a separate correction.
+
+**Source-text guards.** Some tests assert on source text rather than behavior
+(file reads of source paths, `indexOf` ordering chains, identifier-absence or
+literal-presence assertions), so a move breaks them without changing behavior.
+Search only for guards a proposed move can affect, and record what each pins.
+Moving code across such a guard is a contract change, not a tidying.
+
+**Dependency arrays.** A suspected correctness defect is outside cleanup;
+report its evidence without changing behavior.
 
 ## Deletion ladder
 
-Run the ladder on every selected unit (function, class, module, config knob)
-in scope before looking for smells. Only code that lands on the
-last rung goes on to the lenses.
+Run on each selected unit before looking for smells; only code that lands on
+the last rung goes on to the lenses.
 
-| Rung | Question | Typical win |
+| Rung | Question | Result |
 |---|---|---|
-| Delete | Is there evidence the behavior is no longer needed? Check callers, requirements, flags, and compatibility obligations | remove the verified obsolete unit; retire tests only under the test-suite slop rules |
-| 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.
+| Delete | Is there evidence the behavior is no longer needed (callers, requirements, flags, compatibility)? | remove the verified obsolete unit |
+| Reuse | Does a repo helper already do it? | replaced by a call |
+| Platform | Does the runtime, stdlib, or an installed dependency do it? | hand-rolled code replaced |
+| Simplify | It must exist; make it smaller | proceeds to the lenses |
 
 ## Lenses
 
-Each lens judges the units in scope and may search the whole
-repository for evidence (an existing helper, a sibling call site); a finding
-without a path-plus-symbol pointer is dropped. Run every lens unless the user named a focus.
-Judge each selected function or class in its full context, including relevant
-callers and tests, even when it has no pending diff. Do not restrict review to
-recently edited lines or silently widen the edit scope to its consumers.
-
-**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, a boolean parameter that selects between two
-behaviors — split the function instead); copy-paste-with-variation; leaky
-abstractions; stringly-typed code where a constant, enum, or registry exists;
-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. 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.
+Use the lenses to identify supported improvements within scope; stop
+investigating a candidate when its disposition is established. Each lens may
+search the whole repository for evidence; a finding without a path+symbol
+pointer is dropped. Judge units in full context, not only recently edited
+lines, and never widen the edit scope to consumers. Skip lenses the user's
+focus excludes.
+
+- **Reuse** — new code duplicating an existing utility, constant, guard, or
+  installed library. Name the existing thing.
+- **Quality** — redundant or derivable state, parameter sprawl (a boolean
+  selecting between behaviors), copy-paste-with-variation, leaky abstractions,
+  stringly-typed code where a constant or registry exists, slop below.
+- **Efficiency** — redundant work, repeated reads, N+1 access, needless
+  sequencing, leaks, existence pre-checks instead of handling the error. Apply
+  only when equivalence is obvious; otherwise report it.
+- **Altitude** — a fix applied too shallowly: a caller-specific branch in a
+  generic path, a symptom patched at one site, a workaround on a workaround.
+  Name the deeper fix; when it exceeds the cleanup, report it as its own task.
 
 ## 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, license/attribution notices, tool directives, public API docs | delete only with high confidence; preserve token boundaries and significant line breaks |
-| 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; changing which errors are caught or propagated is RISKY |
-| Fake resilience | a fallback that turns a missing input or a failed call into a plausible value (`?? 0`, an empty-object default, a stub record); a catch that only rethrows the same error; a catch that logs without the error and continues | a default the caller's contract names, a retry or degraded mode the docs describe | remove only proven redundant behavior; replacing a default with a failure or changing the error contract is a separate RISKY correction |
-| Excessive complexity | nesting > 3, nested ternaries, 4+ predicates in one condition, > 5 positional params, functions > 50 lines doing several things, clever one-liners, a 4+ branch ladder comparing one value against constants, a hand-rolled loop the language has an idiom for (`for i in range(len(xs))`, an index loop over a collection, `count() > 0` for "any") | a hot path that intentionally uses a dense idiom | guard clauses, early returns, explicit if/else, an options object, a lookup table, the language's own idiom, 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 only after verifying the behavior boundary above |
-| Boundary violations | wrong-layer imports, import cycles between modules, 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; break a cycle by moving the shared piece out; 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, one exported type or interface redeclared in several files | 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, a lint or compiler warning suppressed without one (`eslint-disable`, `# noqa`, `#pragma warning disable`), `object`/`Any` annotations where a union or Protocol fits, a value re-coerced to the type it already has (`String(s)` on a `string`) | an escape or suppression whose comment names the upstream bug it works around | narrow with a guard, a precise type, or `unknown` plus a check; drop a coercion the type already guarantees; fix the warning or record why it is silenced |
-| Hardcoded config | environment-specific URLs and endpoints, provider/account/project ids, absolute paths and path strings spliced with `/`, a literal branch for one caller or one environment, unnamed numeric thresholds | test fixtures, documentation examples, a literal the contract itself fixes (wire strings, protocol constants) | read it through the project's existing config or env accessor; name the literal. A credential in source is a bug — report it, never merely relocate it |
-| Placeholder naming | numbered or filler names on new code (`data2`, `helper1`, `tmp`, `handleStuff`, a `Manager` holding two functions) | names the project's own idioms establish | rename locals after their intent; an exported rename is a contract change, so RISKY |
-| Oversized modules | files past the skill's 1,000-line review threshold or mixing responsibilities | a cohesive module or script with no useful responsibility boundary | split confirmed independent responsibilities; never `utils`/`helpers`/`common`/`part2` dump files |
+| Comments | restating the code, step narration, history or changelog notes, dividers, commented-out code, a comment the code contradicts, a TODO with no owner or issue | a non-obvious why (external constraint, invariant, tradeoff), directives, public API docs, issue links | delete or correct; a "do not change" comment gets a proposed test or type that enforces it, applied only with approval |
+| Over-defensive code | checks on guaranteed values, try/catch around code that cannot throw, duplicated validation | I/O handling, trust boundaries, a logging top-level catch | remove only when a test proves the guard redundant; changing which errors propagate is RISKY |
+| Fake resilience | a fallback turning missing input or failure into a plausible value; a catch that only rethrows or swallows | a default the contract names, documented retry or degraded mode | remove only proven redundant behavior; changing the error contract is RISKY |
+| Excessive complexity | deep nesting, nested ternaries, long conditions, many params, clever one-liners, hand-rolled loops with an idiom | a deliberately dense hot path | guard clauses, early returns, lookup table, options object, extract by responsibility |
+| Needless abstraction | pass-through wrappers, single-use helpers, speculative indirection | a real seam (tests, multiple implementers, framework boundary) | inline after the behavior boundary check |
+| Boundary violations | wrong-layer imports, cycles, logic in handlers, reading another module's private state | an established pattern | move to the owning layer; flag when unsure |
+| Dead code | unused imports/locals/private functions, unreachable branches, debug leftovers | the never-dead list | follow `dead-code.md` |
+| Duplication | copy-pasted branches, two helpers doing one thing, redeclared types | similarity serving different intents | consolidate only when intents match |
+| Type escapes | `any`, unexplained ignores and suppressions, redundant coercions | an escape whose comment names the upstream bug | narrow with a guard or precise type; fix the warning or record why silenced |
+| Hardcoded config | environment-specific URLs, ids, absolute paths, unnamed thresholds | fixtures, docs, contract-fixed literals | use the project's config accessor; name the literal. A credential in source is a defect: report it |
+| Placeholder naming | `data2`, `tmp`, `handleStuff` on new code | the project's own idioms | rename locals; an exported rename is RISKY |
+| Oversized modules | files past the review threshold mixing responsibilities | a cohesive module | split confirmed independent responsibilities; no `utils`/`common` dumps |
 
 ## Risk tiers
 
-Every finding carries one tier:
-
-| Tier | Meaning | Examples | Handling |
-|---|---|---|---|
-| SAFE | equivalence established, including initialization and parsing | verified unused binding with no initialization effects, nonsemantic comment, redundant type assertion | apply as one batch |
-| CAREFUL | same semantics, structure changes | rename a local, flatten a ternary, guard clause, verified wrapper inlining, extract a helper, split responsibilities while preserving entry points, consolidate duplicates, name a magic number | apply one source unit at a time (including required new modules); verified by the single final check; undo only this run's edits if it cannot be fixed |
-| 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 the slop table does not already cover: normalize two
-variants of the same pattern to one form; put coupled functions next to each
-other; declare a variable where it is initialized; blank line between chunks
-that do different things; merge over-fragmented pieces back into one readable
-block before re-splitting. One tidying per change set.
+| Tier | Meaning | Handling |
+|---|---|---|
+| SAFE | equivalence established, including initialization | apply as one batch |
+| CAREFUL | same semantics, structure changes (local rename, guard clause, verified inlining, helper extraction, responsibility split, consolidation) | one source unit at a time, including required new modules |
+| RISKY | may change behavior or a contract (public rename, error-handling or concurrency change, shared-infrastructure fix) | report with test coverage status; apply only the items the user approves |
+
+When lenses disagree: correctness > the user's focus > readability and reuse >
+micro-performance. Between two defensible rewrites, apply the one touching
+less code and record the alternative; if principles cannot separate them,
+apply neither.

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

@@ -1,43 +1,27 @@
-# Candidate list and report
+# Report
 
-Findings and risk tiers come from `agent-cleanup.md`; this file owns how they
-are recorded and reported. Keep the list in the conversation, not a file.
+Findings and tiers come from `agent-cleanup.md`. Keep the list in the
+conversation, not a file. Record only findings with a path+symbol, a cost, and
+an action; threshold hits are signals, not findings.
 
-## Candidates
-
-One line per candidate, with a stable ID (`C-01`):
-
-```text
-[ID] path · symbol → problem → cost → action | tier: SAFE/CAREFUL/RISKY | confidence: high/medium/low | status: completed/kept/unfinished
-```
-
-- Register only a lens finding with a path+symbol location, a cost, and an
-  action. A finding that cannot name its cost is a nit: drop it. Threshold
-  hits (long files or functions, deep nesting) are signals, not candidates.
-- Findings sharing a root cause group under one ID, each member keeping its
-  path and symbol. Code moved by an extraction keeps its origin ID.
-- Confidence is `low` when callers, contracts, and tests do not explain why
-  the code exists; medium/low candidates stay unfinished until that question
-  is resolved. Approval to apply does not authorize guessing.
-- `completed` carries evidence of what changed; `kept` carries a concrete
-  reason (keep rule or external contract); `unfinished` carries the blocker
-  (pending, blocked, deferred, unverified).
-
-Overall cleanup is complete only when every partition is done, the final
-check has passed, and every candidate is completed or kept with evidence.
-Otherwise report "overall partial" with the remaining paths and IDs.
+Each entry carries: path · symbol, action or blocker, risk tier, evidence
+(what changed, why kept, or what blocks it). Findings sharing a root cause
+group together. Unresolved intent stays unfinished; approval to apply does not
+authorize guessing.
 
 ## Final report
 
+Include only sections that have content:
+
 ```text
 Scope: <paths | whole project> · Mode: report|apply · Overall: complete|partial
-Deterministic: engines used/missing · files changed · diagnostics remaining · structural applied/skipped
-Completed:  [ID] path · symbol — [Lens/TIER] what changed
-Kept:       [ID] path · symbol — reason
-Unfinished: [ID] path · symbol — remaining work · status · next
-Noticed, not applied (RISKY or out of scope): [ID] path · symbol — why · test coverage
-Bugs found (not fixed here): <issues>
-Verification: tests <result> · typecheck <result> · tidy check <remaining diagnostics> · pre-existing failures <list|none>
-Blocked or unverified: <check> — <reason> → <paths>   (write "none" if none)
-Needs your decision: <RISKY findings, bugs, unresolved intent, unfinished candidates>
+Deterministic: engines used/missing · files changed · diagnostics remaining
+Completed / Kept / Unfinished: entries as above
+Noticed, not applied (RISKY or out of scope): entries · test coverage
+Defects found (not fixed here): <issues>
+Verification: checks run and results · failures and established attribution · blocked or unverified checks with reason
+Needs your decision: <RISKY findings, defects, unresolved intent, unfinished items>
 ```
+
+Complete means every partition was reviewed and the required checks passed or
+are reported blocked; otherwise report partial with the remaining paths.

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

@@ -45,8 +45,6 @@ found" and never settle it by installing the package.
    effectful initializers, and the last unused import binding can still load a
    module for registration or initialization. Preserve required initialization
    rather than deleting it with the binding.
-5. Record the symbol, kind, classified usage and contract evidence, side-effect
-   result, and proposed action in the candidate list.
 
 ## Never dead
 
@@ -79,7 +77,7 @@ evidence. Apply this procedure before classifying an old path as dead:
 4. For a verified obsolete path, inventory its callers, flags/config, tests,
    docs, files, and dependencies. Remove only approved members in the order
    below; request scope expansion before editing related files outside it.
-5. Record the retirement evidence and any remaining items. A still-required path is kept with its contract; an unknown obligation
+5. A still-required path is kept with its contract; an unknown obligation
    leaves the candidate blocked, not assumed obsolete.
 
 ## Remove in order
@@ -94,9 +92,5 @@ evidence. Apply this procedure before classifying an old path as dead:
    project's own package manager.
 
 Group edits by file so one batch never touches a file another batch edits.
-Verification and rollback follow the skill body (section 5).
-
-## Report
-
-Use the shared candidate list and closing report, with usage and side-effect
-evidence per ID.
+Verification and rollback follow the skill body (section 5). Record usage and
+side-effect evidence in the common report format (`cleanup-report.md`).