feat(code-tidying): add aggressive and strip dials to dissolve-comments

docs/catalog.md

@@ -71,7 +71,7 @@ plugin manifests and kept in sync by CI. Never hand-edit it; the category vocabu
 - [`bugs`](../plugins/bugs): Produces from an informal defect description a structured five-field bug report: title, steps to reproduce, expected vs actual, severity with justification, and suggested fix location. Read-only by default: it emits the report and never edits code, opens a PR, or files an issue on its own.
 - [`debugging`](../plugins/debugging): Debug observed failures via a disciplined six-phase loop: build a fast deterministic reproduction signal, reproduce, rank falsifiable hypotheses, instrument, fix with a regression test, then clean up and post-mortem.
 - [`docs-hygiene`](../plugins/docs-hygiene): Documentation-hygiene toolkit: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), audit-derivability (classify whether a whole document earns its existence: could a fresh agent re-derive it from the code?), audit-progressive-disclosure (grade instruction files against a load-tier model for split opportunities and hub/spoke disclosure defects), write-for-agents (authoring-time doctrine that fires while agent-consumed markdown is being written), write-for-humans (the same moment for the other reader, covering end-user READMEs, RFCs, release notes and guides, and resolving the consuming project's own style guide first), and a file-name set that plans, applies, and enforces a casing rule across a doc tree: setup (the one configuration surface), audit-file-names (read-only inventory plus the reference sweep), realign-file-names (the executor, one human acceptance per file), and generate-file-name-gate (emits the standalone check that keeps the tree from drifting back).
-- [`code-tidying`](../plugins/code-tidying): Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean: it deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.
+- [`code-tidying`](../plugins/code-tidying): Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean: it deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals, the aggressive dial keeps only exempt surfaces and terse warnings, and strip deletes every comment but the exempt surfaces without rewriting code), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.
 - [`coupling`](../plugins/coupling): Iteratively reduces coupling in any repository at any altitude, whether documents, code modules, applications, or repositories: scans for change-transmitting dependencies typed against a coupling model (strength ladder, connascence, volatility weighting), verifies every finding, applies a budgeted batch of safe behavior-preserving reductions, and keeps a durable ledger so structural candidates route to design lanes and repeated runs continue where the last stopped.
 - [`repo-hygiene`](../plugins/repo-hygiene): Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state, dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default.
 - [`repo-fleet-hygiene`](../plugins/repo-fleet-hygiene): Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes.

plugins/code-tidying/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "code-tidying",
-  "version": "0.19.8",
-  "description": "Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean: it deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.",
+  "version": "0.20.0",
+  "description": "Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps a time window, a branch, or an entire repository through grouped, dependency-ordered simplification waves with a fix-first deferral contract that resolves deferrals in the same run instead of filing issues; /code-tidying:dissolve-comments enforces self-describing expressive code over a diff or target, widening to the branch diff and then the whole repository when the tree is clean: it deletes zero-information comments, dissolves code-expressible ones into names and structure behind a tests gate (safe mode restricts applied edits to removals, the aggressive dial keeps only exempt surfaces and terse warnings, and strip deletes every comment but the exempt surfaces without rewriting code), and keeps only terse load-bearing comments code cannot express; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion; /code-tidying:audit-dead-code is a read-only whole-repo dead-code hunter running four labelled lanes of unequal confidence (knip for TS/JS, vulture for Python, gopls for Go, and a portable grep lane for shell and other symbol languages), adjudicating every candidate against dynamic-usage evidence into a dead, uncertain, or alive verdict. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill.",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
@@ -30,7 +30,7 @@
     "comment_posture": {
       "type": "string",
       "title": "dissolve-comments posture",
-      "description": "How dissolve-comments treats a kept comment. strict (default): every kept comment is held to class_c_max_lines and rewritten terser when over it, with the removed narrative staged for the commit message; balanced: the same triage, but an over-budget comment is reported instead of rewritten; conservative: class-A deletions only, every class-B item and class-C rewrite is proposed. Doubt keeps the comment in every posture. Any other value is read as strict.",
+      "description": "How dissolve-comments treats a kept comment. strict (default): every kept comment is held to class_c_max_lines and rewritten terser when over it, with the removed narrative staged for the commit message; balanced: the same triage, but an over-budget comment is reported instead of rewritten; conservative: class-A deletions only, every class-B item and class-C rewrite is proposed; aggressive: only exempt surfaces, paired records, and terse warnings of consequence survive, and every other comment is staged and deleted. The per-run tokens safe, strip, and aggressive beat this value, safe first. No posture loosens a gate: every applied deletion still carries the token proof and every tier-2 or tier-3 move still needs a test net. Any other value is read as strict.",
       "default": "strict"
     },
     "class_c_max_lines": {

plugins/code-tidying/CHANGELOG.md

@@ -3,6 +3,37 @@
 All notable changes to the `code-tidying` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.20.0]
+
+### Added
+
+- **`dissolve-comments` gains an aggressive dial.** `aggressive` (a per-run token and a
+  `comment_posture` value) keeps only the exempt surfaces, paired comment-plus-test records, and
+  terse warnings of consequence; every other comment is staged and deleted, rationale included.
+  `strip` (a per-run token) deletes every comment but the exempt surfaces and paired records and
+  rewrites no code. Precedence is `safe`, then `strip`, then `aggressive`, and a token beats the
+  standing posture.
+- **`--notes <path>`** appends the staged commit-message block to an untracked or out-of-repo file.
+  A tracked path is refused and the run continues with the report as the only vehicle.
+- **A calibration eval suite** under `plugins/code-tidying/evals/`, run with `claude plugin eval`:
+  three frozen real sections, invented fixtures per triage class, exempt surfaces, marker rows,
+  Python docstrings, paired records, and the dial interactions.
+
+### Changed
+
+- **"The posture ladder only descends" is replaced by "no knob loosens a gate."** The dials widen
+  what a run removes; they change no proof. Deletions still carry COMMENT-ONLY, function-local
+  renames RENAME-ONLY, tier-2 and tier-3 moves a discovered test net, and an UNPROVABLE file still
+  yields proposals only.
+- **Two rules now hold in every mode:** a comment paired with a regression test is never deleted
+  alone, and an identifier a repo-local marker row pins is never renamed.
+- **The tier tables in `safety.md` and `dissolving-moves.md` agree.** The merged set is 16 moves:
+  tier 2 gains Replace Nested Conditional with Guard Clauses and Introduce Special Case, tier 3
+  gains Inline Function in `safety.md` and Extract Class in `dissolving-moves.md`. The apply-capacity
+  counts read 2 of 16 and 0 of 16.
+- **The `Intentional-removal:` trailer is conditional.** The staged block carries it only where the
+  target repository's own gates read that trailer.
+
 ## [0.19.8]
 
 ### Changed

plugins/code-tidying/README.md

@@ -17,7 +17,11 @@ Six skills, one capability:
   behind a token-level proof (`change-shape.py`, so they act on a repository
   with no test suite); additive refactors need a discovered test net;
   interface-creating ones are proposal-first. `safe` mode restricts applied
-  edits to removals. Ships a comment census with a token estimate and a
+  edits to removals; `aggressive` keeps only exempt surfaces, paired records,
+  and terse warnings of consequence, staging every other comment's narrative
+  before deleting it; `strip` deletes every comment but the exempt surfaces and
+  rewrites no code. `--notes <path>` writes the staged block to an untracked
+  file as well. No dial loosens a gate. Ships a comment census with a token estimate and a
   cross-language commented-out-code detector, and probes its reading layers
   (`scc`, `pygments`, `tree-sitter`, `ruff`, `ast-grep`) at run time, naming
   what each absent one costs.
@@ -126,14 +130,15 @@ personal variation is limited to lane names the team does not track: an uncommit
 
 ## Configuration
 
-Four `userConfig` options. Three tune `dissolve-comments` and loosen nothing;
-the fourth is the personal-posture channel of the exclusion override above, and
-loosening is its whole job:
+Four `userConfig` options. Three tune `dissolve-comments`, and none of them
+loosens a gate: they set what a run removes, never what it may apply without a
+proof. The fourth is the personal-posture channel of the exclusion override
+above, and loosening is its whole job:
 
 | Option | Default | Effect |
 |---|---|---|
 | `hard_exclusions` | `enforce` | `enforce` keeps every GLOBAL HARD **path** entry blocking; `advisory` reports each match and blocks nothing, so runs may reach lint config, agent config, CI workflows, and hook chains. Path entries only: the behavioral guards, the work-tracking entries, and the self-update protections hold at either value. |
-| `comment_posture` | `strict` | `strict` rewrites an over-budget kept comment terser and stages the removed narrative; `balanced` reports it instead; `conservative` applies class-A deletions only and proposes everything else. Doubt keeps the comment in every posture. |
+| `comment_posture` | `strict` | `strict` rewrites an over-budget kept comment terser and stages the removed narrative; `balanced` reports it instead; `conservative` applies class-A deletions only and proposes everything else; `aggressive` keeps only exempt surfaces, paired records, and terse warnings. The per-run tokens `safe`, `strip`, and `aggressive` beat this value, `safe` first. |
 | `class_c_max_lines` | `2` | Line budget for a kept (class-C) comment before it is rewritten. |
 | `apply_local_renames` | `true` | Apply a function-local rename that `change-shape.py` certifies as RENAME-ONLY even with no test net; `false` proposes it. |
 
@@ -157,7 +162,7 @@ reads it from.
 | Option | Type | Default | Environment variable | Description |
 | --- | --- | --- | --- | --- |
 | `hard_exclusions` | string | `"enforce"` | `CLAUDE_PLUGIN_OPTION_HARD_EXCLUSIONS` | How tidy, dissolve-comments, and batch-simplify treat the GLOBAL HARD path list in skills/tidy/reference/exclusions.md. enforce (default): a path on that list is dropped before triage; advisory: the list is reported per path and never blocks, so a run may edit lint config, agent config, CI workflows, and hook chains. advisory is the standing form of the per-run override argument and is lifted for path entries only: the behavioral guards, the work-tracking entries, and the SELF-UPDATE EXTRA HARD list hold under every value. Any other value is read as enforce. |
-| `comment_posture` | string | `"strict"` | `CLAUDE_PLUGIN_OPTION_COMMENT_POSTURE` | How dissolve-comments treats a kept comment. strict (default): every kept comment is held to class_c_max_lines and rewritten terser when over it, with the removed narrative staged for the commit message; balanced: the same triage, but an over-budget comment is reported instead of rewritten; conservative: class-A deletions only, every class-B item and class-C rewrite is proposed. Doubt keeps the comment in every posture. Any other value is read as strict. |
+| `comment_posture` | string | `"strict"` | `CLAUDE_PLUGIN_OPTION_COMMENT_POSTURE` | How dissolve-comments treats a kept comment. strict (default): every kept comment is held to class_c_max_lines and rewritten terser when over it, with the removed narrative staged for the commit message; balanced: the same triage, but an over-budget comment is reported instead of rewritten; conservative: class-A deletions only, every class-B item and class-C rewrite is proposed; aggressive: only exempt surfaces, paired records, and terse warnings of consequence survive, and every other comment is staged and deleted. The per-run tokens safe, strip, and aggressive beat this value, safe first. No posture loosens a gate: every applied deletion still carries the token proof and every tier-2 or tier-3 move still needs a test net. Any other value is read as strict. |
 | `class_c_max_lines` | number<br>*min 1, max 40* | `2` | `CLAUDE_PLUGIN_OPTION_CLASS_C_MAX_LINES` | Lines a kept (class-C) comment may run before dissolve-comments rewrites it terser, staging any removed narrative for the commit message. A genuinely load-bearing multi-line contract may exceed it when the report says why. |
 | `apply_local_renames` | boolean | `true` | `CLAUDE_PLUGIN_OPTION_APPLY_LOCAL_RENAMES` | When true (default), a function-local Rename Variable whose edit change-shape.py certifies as RENAME-ONLY is applied and reported with its identifier mapping even when no test net is discovered. When false, such renames are proposed. |
 

plugins/code-tidying/evals/.editorconfig

@@ -0,0 +1,9 @@
+# Eval fixtures are frozen corpus, not source: real sections copied byte for byte
+# at a pinned commit, plus invented samples whose whitespace is part of what the
+# graders measure. A Makefile recipe needs its tab, and normalizing any of it
+# would silently change what the suite tests.
+
+[*]
+indent_style = unset
+indent_size = unset
+trim_trailing_whitespace = false

plugins/code-tidying/evals/fixtures/Makefile.txt

@@ -0,0 +1,3 @@
+.PHONY: test
+test:
+	bash class-b.test.sh

plugins/code-tidying/evals/fixtures/check-markers.sh.txt

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Fails when a marker listed in scripts/restoration-markers.txt is missing from src/.
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+status=0
+while IFS= read -r marker; do
+  [[ -z "$marker" ]] && continue
+  if ! grep -rqF -- "$marker" "$root/src"; then
+    echo "missing restoration marker: $marker" >&2
+    status=1
+  fi
+done <"$root/scripts/restoration-markers.txt"
+exit "$status"

plugins/code-tidying/evals/fixtures/class-a.sh.txt

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+counter=0
+total=0
+
+for value in "$@"; do
+  total=$((total + value))
+  # increment counter
+  counter=$((counter + 1))
+done
+
+# old_total=$((total * 2))
+# echo "$old_total"
+
+echo "count=$counter total=$total"