maintainability-agent 3.6.0__tar.gz → 3.6.2__tar.gz

{maintainability_agent-3.6.0/src/maintainability_agent.egg-info → maintainability_agent-3.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.6.0
+Version: 3.6.2
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -46,7 +46,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **3.6.0**.
+Version **3.6.2**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Go, Rust, PHP, Ruby, Swift,
 COBOL, Fortran (free-form *and* fixed-form), and the JS/TS/HTML family — each

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/README.md

@@ -5,7 +5,7 @@
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **3.6.0**.
+Version **3.6.2**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Go, Rust, PHP, Ruby, Swift,
 COBOL, Fortran (free-form *and* fixed-form), and the JS/TS/HTML family — each

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "3.6.0"
+version = "3.6.2"
 description = "Maintainability gate and AI remediation prompt generator for CI."
 readme = "README.md"
 # 3.11, not 3.10. `_discovery`, `_pillars` and `_runner` all import

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.6.0
+Version: 3.6.2
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -46,7 +46,7 @@ Dynamic: license-file
 **A deterministic, offline maintainability audit whose output is a _bounded
 work order_ for an AI coding agent** — a copy-paste prompt, per finding, that
 says *fix exactly these and refactor nothing else*. Chat-primary; CLI for CI.
-Version **3.6.0**.
+Version **3.6.2**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Go, Rust, PHP, Ruby, Swift,
 COBOL, Fortran (free-form *and* fixed-form), and the JS/TS/HTML family — each

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -163,6 +163,7 @@ tests/test_analyzer_scoring_path.py
 tests/test_analyzer_spread_range.py
 tests/test_analyzer_xml_bounds.py
 tests/test_anchor_and_mode.py
+tests/test_anchor_caveat_and_counts_follow_the_run.py
 tests/test_anchor_disclosure.py
 tests/test_annotations_match_behaviour.py
 tests/test_anticipated_refusals.py
@@ -235,11 +236,13 @@ tests/test_economic_context.py
 tests/test_empty_output_not_clean.py
 tests/test_empty_output_not_clean_adapters.py
 tests/test_environment_work_order.py
+tests/test_every_surface_says_what_the_run_found.py
 tests/test_evidence_invariants.py
 tests/test_evidence_normalization.py
 tests/test_evidence_properties.py
 tests/test_example_config_opens_claimed_languages.py
 tests/test_exclusion_dialects.py
+tests/test_exposure_never_outranks_band.py
 tests/test_falsifier_standard.py
 tests/test_file_list_cap_class.py
 tests/test_finding_identity.py
@@ -368,6 +371,7 @@ tests/test_verification_audit_closures.py
 tests/test_verified_grade.py
 tests/test_version_claim.py
 tests/test_wheel_contents.py
+tests/test_work_items_state_their_own_finding.py
 tests/test_work_order.py
 tests/test_work_order_binds_to_this_interpreter.py
 tests/test_work_order_items.py

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "3.6.0"
+__version__ = "3.6.2"

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_assets/standard.md

@@ -351,7 +351,7 @@ place it in one of four bands:
 
 | Finding class | Risk | Effort | Band | Why |
 |---|---:|---:|---|---|
-| `risk-pattern` | 5 | 1 | **quick-win** | a configured risk pattern is a rule this project chose to enforce on itself, and each hit is a single located line |
+| `risk-pattern` | 5 | 1 | **quick-win** | a risk pattern is a rule the active configuration enforces, and each hit is a single located line |
 | `oversized-declaration` | 4 | 2 | **quick-win** | a long, branching function is where defects concentrate and where every future change has to be understood first; extracting one is bounded, local work |
 | `unpaired-hotspot` | 4 | 2 | **quick-win** | an oversized production unit with no paired test is where changes land unguarded; adding a characterization test is bounded, local work |
 | `duplicate-block` | 4 | 4 | **major-project** | duplicated logic means a fix applied in one place and missed in the others; deduplicating across a codebase is a design change, not a tidy-up |
@@ -360,6 +360,15 @@ place it in one of four bands:
 | `dead-code` | 2 | 1 | **fill-in** | unreachable code costs reading time and misleads a search, but deleting it is the cheapest change there is |
 | `competing-libraries` | 2 | 4 | **reconsider** | two libraries doing one job is a decision nobody made; converging on one is a migration across every call site |
 
+**A band is a judgment about the class, not a size for the item.** The
+effort above is declared once per finding class, so a 2876-line class and a
+90-line function share `oversized-declaration`'s band. The *Why* column is
+that class-level judgment and is published here; a work item does not repeat
+its effort claim. Each item instead states its own reading — its kind, and
+each figure against the limit it is graded on (`currently 2876 lines against
+the 300-line class limit`) — so a reader, or an agent sizing the work, has
+the fact rather than the class's estimate of it (D164).
+
 **Why Major Projects are withheld from the agent prompt.** An agent told to
 deduplicate a pattern across forty files produces exactly the sprawling,
 unreviewable diff a bounded prompt exists to prevent. The work is real and
@@ -369,7 +378,10 @@ appears in the report; scoping it is a human's job first.
 what clearing that single finding moves the published score — honestly zero
 more often than not, because the overall is the mean of the *rounded*
 categories and is therefore a step function. `class_delta` is what clearing
-every finding of that class is worth, and it is what the ordering uses.
+every finding of that class is worth, and it is what the band ordering uses
+within a band. When an economic context is configured, ADR 004's exposure
+sort takes its place *inside* each band — never across bands, so a Fill-In
+never leads a Quick Win (D170) — and the work order's heading says so (D169).
 Neither is estimated: both come from re-running `score_report` over a summary
 with those findings removed. Per-item deltas do not sum to the whole.
 

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_economics.py

@@ -133,18 +133,27 @@ def _exposure(item: dict[str, Any], churn: dict[str, int],
 
 
 def reorder_by_exposure(report: dict[str, Any]) -> None:
-    """Most-exposed first, in place, keeping every item intact.
+    """Most-exposed first within each band, in place, keeping every item intact.
 
     Applied only when an economic context exists: exposure is the
     ordering that context asks for, and without one the risk-by-effort
     order stands untouched. The sort moves whole items, so severity,
     risk, effort, band and class delta stay on each one — the standard
     evidence is reordered, never erased.
+
+    **Band stays the primary key (D170).** This sorted on exposure alone,
+    so a Fill-In on a file that changes often led a Quick Win on a stable
+    one — the nit-loop ADR 007 §3 rule 5 forbids. ADR 004 asks for the work
+    order to be reordered by exposure; it never asked for exposure to
+    outrank band, so ordering within a band satisfies both as written.
     """
+    from ._work_order import BAND_ORDER
+
     churn = _churn_by_path(report)
     returns = _returns_by_fingerprint(report)
     items = report.get("work_order") or []
-    items.sort(key=lambda item: (-_exposure(item, churn, returns),
+    items.sort(key=lambda item: (BAND_ORDER.get(item.get("band") or "", len(BAND_ORDER)),
+                                 -_exposure(item, churn, returns),
                                  item.get("title") or ""))
 
 

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_evidence_view.py

@@ -26,6 +26,7 @@ compatibility semantics.
 """
 from __future__ import annotations
 
+from collections.abc import Iterable
 from typing import Any
 
 # A foundation, not the scoring layer: grammar is neither scoring nor
@@ -346,17 +347,33 @@ def test_suite_lines(block: dict[str, Any] | None) -> list[str]:
     return lines
 
 
-def unanchored_languages(score: dict[str, Any]) -> tuple[str, ...]:
+def unanchored_languages(
+    score: dict[str, Any], present: Iterable[str] | None = None
+) -> tuple[str, ...]:
     """Parsed languages the reference corpus does not hold, from the report.
 
     Read off `score.reference` rather than imported from `_anchor`, so a
     report rendered from stored JSON discloses what *that* run's anchor
     omitted rather than what today's build omits.
+
+    ``present`` is the run's own language census, `summary.languages`
+    (D167). The anchor's gap is a fact about the corpus, but the caveat
+    is a claim about *this* grade: "a grade reported for code in COBOL is
+    provisional" printed on a Java tree tells the reader something false
+    about what they are looking at. ``None`` means the census is unknown —
+    a report stored before it existed — and keeps the whole list, because
+    a limit that cannot be ruled out is still disclosed.
     """
-    return tuple((score.get("reference") or {}).get("unanchored_languages") or ())
+    names = tuple((score.get("reference") or {}).get("unanchored_languages") or ())
+    if present is None:
+        return names
+    here = set(present)
+    return tuple(name for name in names if name in here)
 
 
-def unanchored_caveat(score: dict[str, Any]) -> list[str]:
+def unanchored_caveat(
+    score: dict[str, Any], present: Iterable[str] | None = None
+) -> list[str]:
     """The anchor's gap, in one sentence, for any skin that prints a grade.
 
     Lives here because all three skins were about to carry their own copy
@@ -365,7 +382,7 @@ def unanchored_caveat(score: dict[str, Any]) -> list[str]:
     disclosed only there is disclosed nowhere that matters, which is the
     shape this project already shipped once as F1.
     """
-    names = unanchored_languages(score)
+    names = unanchored_languages(score, present)
     if not names:
         return []
     say = agreement(len(names))

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_html_view.py

@@ -90,9 +90,9 @@ def render_html(report: dict[str, Any], records: list[Any]) -> str:
     return "\n".join(parts)
 
 
-def _unanchored_html(score: dict[str, Any]) -> list[str]:
+def _unanchored_html(score: dict[str, Any], present: Any = None) -> list[str]:
     """The anchor's gap, beside the letter rather than only in the JSON."""
-    names = view.unanchored_languages(score)
+    names = view.unanchored_languages(score, present)
     if not names:
         return []
     say = agreement(len(names))
@@ -122,7 +122,7 @@ def _executive_strip(report: dict[str, Any], score: dict[str, Any],
         f"Source: {escape(view.estimate_source(score))}</div>",
         f"<div>{escape(view.status_sentence(score, report.get('analyzer_coverage') is not None))}</div>",
         f"<div>{gate}</div>",
-        *_unanchored_html(score),
+        *_unanchored_html(score, (report.get("summary") or {}).get("languages")),
         f"<div>{escape(_direction_sentence(records))}</div>",
         "<table><tr><th>Severity</th><th>Findings</th></tr>",
         *count_rows,

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_in_loop.py

@@ -37,6 +37,7 @@ import re
 from pathlib import Path
 from typing import Any
 
+from ._work_order import _declaration_reading
 from .declarations import DECLARATION_SUFFIXES, detect_functions
 from .metrics import file_status
 
@@ -237,11 +238,17 @@ def _declaration_findings(
             # number. Never negative: it names a budget that failed.
             "breached": breaches[0]["budget"],
             "over_by": breaches[0]["over_by"],
+            # The work order's own wording, called rather than copied: the
+            # copy printed a class's complexity against a function limit
+            # after the work order stopped doing so (D164).
             "target": (
-                f"reduce below the configured limits (currently {metric.lines} "
-                f"lines against {_budget_for(metric.kind, thresholds)[0]}, "
-                f"complexity {metric.complexity} against "
-                f"{thresholds['max_complexity']})"
+                "reduce below the configured limits ("
+                + _declaration_reading(
+                    {"lines": metric.lines, "complexity": metric.complexity,
+                     "kind": metric.kind, "cognitive": metric.cognitive},
+                    thresholds,
+                )
+                + ")"
             ),
         })
     return findings

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_precommit.py

@@ -171,6 +171,11 @@ def staged_report(root: Path, config: dict[str, Any]) -> dict[str, Any]:
     return {
         "root": str(root),
         "scanned": scannable,
+        # The limits these hotspots were graded against, so the work-order
+        # builder can name them. Without this the hook worded a class
+        # "graded on length alone" while the audit said "against the
+        # 300-line class limit" (D171).
+        "thresholds": thresholds,
         "largest_files": largest,
         "function_hotspots": hotspots,
         "risk_findings": risk,
@@ -204,13 +209,12 @@ def _risk_items(report: dict[str, Any]) -> list[dict[str, Any]]:
             "title": f"{entry['pattern']} added in {entry['path']}",
             "path": entry["path"], "line": entry["line"],
             "target": (
-                f"remove or justify this {entry['pattern']} match; it is a "
-                "pattern this repository's own configuration asked to be "
-                "told about"
+                f"act on or justify this {entry['pattern']} match; it is a "
+                "risk pattern the active configuration enforces"
             ),
             "rationale": (
-                "the repository declared this pattern as risky, and this "
-                "change is adding a line that matches it"
+                "the active configuration declares this pattern risky, and "
+                "this change is adding a line that matches it"
             ),
             # Above a threshold breach and below an added suppression. A
             # risk pattern is what the repository asked to see; switching
@@ -289,7 +293,7 @@ def staged_findings(report: dict[str, Any]) -> list[dict[str, Any]]:
     from ._work_order import _items_from_files, _items_from_hotspots, band_of
 
     items: list[dict[str, Any]] = []
-    for entry in _items_from_hotspots(report) + _items_from_files(report):
+    for entry in _items_from_hotspots(report, report.get("thresholds")) + _items_from_files(report):
         weight = entry.pop("weight")
         rationale = entry.pop("rationale", None) or weight.rationale
         items.append({**entry, "rationale": rationale,

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_prompt_sections.py

@@ -89,7 +89,17 @@ def prompt_analyzer_caveat(report: dict[str, Any]) -> list[str]:
     """
     if not (report.get("analyzer_measurements") or report.get("analyzer_findings")):
         return []
-    scored = (report.get("score") or {}).get("analyzer_scored_dimensions") or []
+    score = report.get("score") or {}
+    if not view.is_scored(score):
+        # No estimate was issued, so none can have a source (D172). The
+        # analyzer output is still evidence about the code, and says so.
+        return [
+            "**No maintainability estimate was issued for this run**, so none is "
+            "attributed to the analyzers. Their output is reported here as "
+            "evidence about the code, never as a change to a score.",
+            "",
+        ]
+    scored = score.get("analyzer_scored_dimensions") or []
     if scored:
         return [
             "**The maintainability estimate above uses the analyzer readings** for "
@@ -149,6 +159,50 @@ def _withheld_paragraph(report: dict[str, Any]) -> list[str]:
     ]
 
 
+def _prompt_work_items(report: dict[str, Any]) -> list[dict[str, Any]]:
+    """The items this prompt hands to an agent, after withholding."""
+    # Withhold anything the history shows was fixed and came back
+    # twice. Naming it as a design candidate while asking an agent to
+    # patch it a third time would change nothing.
+    escalated = {
+        item["fingerprint"] for item in report.get("design_review_candidates") or []
+    }
+    return prompt_items(report.get("work_order") or [], escalated=escalated)
+
+
+def prompt_has_work(report: dict[str, Any]) -> bool:
+    """Whether this prompt hands an agent anything to change (D173).
+
+    A report with no `work_order` key at all — stored before the field
+    existed, or assembled by hand — cannot say there is nothing to do, so
+    it keeps the prompt it always had rather than reading as "Nothing to
+    do" over findings it does carry.
+    """
+    return "work_order" not in report or bool(_prompt_work_items(report))
+
+
+def _no_prompt_work(report: dict[str, Any]) -> list[str]:
+    """What the prompt says in place of a task when there is none (D173).
+
+    Two cases, because they are different facts. An empty work order is the
+    chat report's "Nothing to do", in the same words. A work order whose
+    every item was withheld — a Major Project, or a finding escalated for
+    design review — has work in it, none of it an agent's to patch.
+    """
+    if not report.get("work_order"):
+        from ._work_order_view import NOTHING_TO_DO
+
+        return [NOTHING_TO_DO, "", "Do not change code on the strength of this audit.", ""]
+    return [
+        "**Nothing in scope for this prompt.** Every work-order item needs a "
+        "design decision or keeps coming back, so none is handed to an agent. "
+        "They are in the report. Do not change code on the strength of this "
+        "prompt.",
+        "",
+        *_withheld_paragraph(report),
+    ]
+
+
 def prompt_work_order(report: dict[str, Any]) -> list[str]:
     """The ordered work, leading the prompt, Major Projects withheld.
 
@@ -161,18 +215,16 @@ def prompt_work_order(report: dict[str, Any]) -> list[str]:
     told to deduplicate a pattern across forty files produces exactly the
     sprawling, unreviewable diff a bounded prompt exists to prevent.
     """
-    # Withhold anything the history shows was fixed and came back
-    # twice. Naming it as a design candidate while asking an agent to
-    # patch it a third time would change nothing.
-    escalated = {
-        item["fingerprint"] for item in report.get("design_review_candidates") or []
-    }
-    items = prompt_items(report.get("work_order") or [], escalated=escalated)
+    items = _prompt_work_items(report)
     if not items:
-        return []
+        return _no_prompt_work(report) if "work_order" in report else []
     lines = [
-        "Work in this order. The first items are the highest value for the "
-        "least change; stop when the change stops being reviewable.",
+        # What the order is, not what it is worth (D169): `prompt_items`
+        # promotes risk-5 classes and keeps one item per class, so this
+        # list and the report's table can lead with different items.
+        "Work in this order: severe findings (risk 5) first, then the work "
+        "order's own order, one item per kind of finding. Stop when the "
+        "change stops being reviewable.",
         "",
     ]
     for index, item in enumerate(items, start=1):
@@ -217,7 +269,22 @@ DIMENSION_GUIDANCE = {
 }
 
 
-def prompt_pressure_section(score: dict[str, Any]) -> list[str]:
+def corpus_span(score: dict[str, Any]) -> str:
+    """How much of what this scanner parses the corpus holds, counted (D168).
+
+    Read off `score.reference`, the two lists the corpus note is built
+    from. The prompt typed "eight of the ten parsed languages" while the
+    note on the same report said thirteen of fourteen: a count written
+    as prose goes stale the first time a language is added, and nothing
+    fails when it does.
+    """
+    reference = score.get("reference") or {}
+    held = len(reference.get("corpus_languages") or ())
+    parsed = held + len(reference.get("unanchored_languages") or ())
+    return f"{held} of the {parsed} parsed languages"
+
+
+def prompt_pressure_section(score: dict[str, Any], present: Any = None) -> list[str]:
     """Tell the agent *what kind* of trouble this repo is in, and how much.
 
     A letter grade is not actionable. These figures are multiples of what
@@ -247,7 +314,7 @@ def prompt_pressure_section(score: dict[str, Any]) -> list[str]:
     if not view.is_scored(score):
         # The grade blockers still render below: those say *why* no
         # number was issued, which is exactly what this reader needs.
-        return [*view.unanchored_caveat(score), *_grade_blocker_lines(score)]
+        return [*view.unanchored_caveat(score, present), *_grade_blocker_lines(score)]
     dimensions = score.get("dimensions") or {}
     elevated = sorted(
         # `is not None` first: an unmeasured dimension is legitimate --
@@ -259,13 +326,13 @@ def prompt_pressure_section(score: dict[str, Any]) -> list[str]:
         key=lambda item: -item[1],
     )
     # Unanchored languages are provisional here too, elevated or not.
-    lines: list[str] = view.unanchored_caveat(score)
+    lines: list[str] = view.unanchored_caveat(score, present)
     if elevated:
         lines.extend(
             [
                 "Where this repo is worse than typical real-world code",
-                "(1.0x = the median of a mature open-source corpus of eight "
-                "of the ten parsed languages; elevated dimensions only):",
+                f"(1.0x = the median of a mature open-source corpus of "
+                f"{corpus_span(score)}; elevated dimensions only):",
                 "",
             ]
         )

{maintainability_agent-3.6.0 → maintainability_agent-3.6.2}/src/maintainability_audit/_work_order.py

@@ -17,7 +17,7 @@ from ._identity import (
     finding_fingerprints,
     risk_identities,
 )
-from ._work_order_weights import CLASS_RISK_EFFORT, ClassWeight
+from ._work_order_weights import AUDIT_VERIFICATION, CLASS_RISK_EFFORT, ClassWeight
 from .scoring import score_report
 
 
@@ -36,6 +36,11 @@ class Band(StrEnum):
 HIGH_RISK = 3
 HIGH_EFFORT = 3
 
+#: ADR 007 §3's order of the four cells, taken from `Band`'s declaration
+#: order. Both sorts read it — the band sort here and `reorder_by_exposure`
+#: — so no ordering can place a Fill-In above a Quick Win (D170).
+BAND_ORDER = {band.value: rank for rank, band in enumerate(Band)}
+
 
 def band_of(risk: int, effort: int) -> Band:
     """Which of the four cells a finding falls in."""
@@ -76,7 +81,59 @@ def _delta_for(report: dict[str, Any], counter: str, amount: int) -> float:
     return round(max(0.0, (after or before) - before), 3)
 
 
-def _items_from_hotspots(report: dict[str, Any]) -> list[dict[str, Any]]:
+def _declaration_reading(hotspot: dict[str, Any], thresholds: dict[str, int] | None) -> str:
+    """What this declaration measures, each figure against the limit it is graded on (D164).
+
+    A class is graded on length alone (`declarations.class_status`), so it
+    is given its length and the class budget and nothing else: its
+    complexity is the sum of its methods' branches, already counted
+    against those methods, and printing it beside a function limit
+    described a 2876-line class as a function with complexity 25. A
+    function is graded on lines, complexity and cognitive cost, so each
+    appears with its own limit. Without thresholds — a caller holding only
+    the report — the figures are stated bare rather than against a
+    default the repository may not use.
+    """
+    lines = hotspot["lines"]
+    if hotspot.get("kind") == "class":
+        if thresholds is None:
+            return f"currently {lines} lines; a class is graded on length alone"
+        limit = thresholds.get("max_class_lines", thresholds["max_function_lines"])
+        return f"currently {lines} lines against the {limit}-line class limit"
+    if thresholds is None:
+        return f"currently {lines} lines, complexity {hotspot['complexity']}"
+    parts = [
+        f"{lines} lines against {thresholds['max_function_lines']}",
+        f"complexity {hotspot['complexity']} against {thresholds['max_complexity']}",
+    ]
+    max_cognitive = thresholds.get("max_cognitive_complexity")
+    if max_cognitive is not None and hotspot.get("cognitive") is not None:
+        parts.append(f"cognitive {hotspot['cognitive']} against {max_cognitive}")
+    return "currently " + ", ".join(parts)
+
+
+def _declaration_rationale(hotspot: dict[str, Any]) -> str:
+    """Why this declaration matters, without sizing the change it needs (D164).
+
+    The class weight's rationale ends "extracting one is bounded, local
+    work" — a judgment about the class of finding, published in the
+    standard beside its declared effort. Printed on one item it became a
+    claim about that item, and it was false for a 2876-line class. The
+    band stays declared per class; the item states what it is and its own
+    reading states how far past the limit it sits.
+    """
+    if hotspot.get("kind") == "class":
+        return ("an oversized class hides its own structure, and every change "
+                "to it is read against all of it")
+    if float(hotspot["complexity"]) <= 10:
+        return "a long function is where every future change has to be understood first"
+    return ("a long, branching function is where defects concentrate and where "
+            "every future change has to be understood first")
+
+
+def _items_from_hotspots(
+    report: dict[str, Any], thresholds: dict[str, int] | None = None
+) -> list[dict[str, Any]]:
     """Declarations past a threshold, worst first."""
     weight = CLASS_RISK_EFFORT["oversized-declaration"]
     # Computed once over the whole population, because an ordinal is a
@@ -100,18 +157,13 @@ def _items_from_hotspots(report: dict[str, Any]) -> list[dict[str, Any]]:
             "line": hotspot["start_line"],
             "target": (
                 f"reduce below the configured limits "
-                f"(currently {hotspot['lines']} lines, complexity {hotspot['complexity']})"
+                f"({_declaration_reading(hotspot, thresholds)})"
             ),
             "severity": float(hotspot["lines"]) + 4.0 * float(hotspot["complexity"]),
             "fingerprint": identities[
                 (hotspot["path"], hotspot["name"], hotspot["start_line"])
             ],
-            "rationale": (
-                "a long function is where every future change has to be "
-                "understood first; extracting one is bounded, local work"
-                if float(hotspot["complexity"]) <= 10
-                else None
-            ),
+            "rationale": _declaration_rationale(hotspot),
             "weight": weight,
         })
     return items
@@ -130,6 +182,11 @@ def _items_from_unpaired(report: dict[str, Any]) -> list[dict[str, Any]]:
             "path": path,
             "line": finding.get("line"),
             "target": f"add a paired test for `{name}`",
+            # Not the class rationale: "adding a characterization test is
+            # bounded, local work" sizes the item, and a 1907-line class
+            # with no test is not bounded work (D164).
+            "rationale": ("an oversized production unit with no paired test is "
+                          "where changes land unguarded"),
             "severity": float(finding.get("lines") or 1),
             "weight": weight,
         })
@@ -234,11 +291,22 @@ def _items_from_counted(report: dict[str, Any]) -> list[dict[str, Any]]:
             }
             if name == "risk-pattern":
                 item["fingerprint"] = risks[(path, finding["name"], finding["line"])]
+                # "remove the configured risk pattern" read, for a TODO, as
+                # "delete the comment" — which clears the finding and the
+                # score while the debt it records stays (D165).
+                item["target"] = (
+                    f"act on what the `{finding['name']}` rule matched here, or "
+                    "say why it stays; deleting the matched text alone hides "
+                    "the finding without resolving it"
+                )
             items.append(item)
     return items
 
 
-def work_order(report: dict[str, Any], include_reconsider: bool = False) -> list[dict[str, Any]]:
+def work_order(
+    report: dict[str, Any], include_reconsider: bool = False,
+    thresholds: dict[str, int] | None = None,
+) -> list[dict[str, Any]]:
     """Every actionable finding, ordered by risk against effort.
 
     Quick Wins first, then Major Projects, then Fill-Ins; Reconsider is
@@ -247,7 +315,7 @@ def work_order(report: dict[str, Any], include_reconsider: bool = False) -> list
     value rather than by how many of something there are.
     """
     raw = (
-        _items_from_hotspots(report)
+        _items_from_hotspots(report, thresholds)
         + _items_from_files(report)
         + _items_from_counted(report)
         + _items_from_idioms(report)
@@ -268,7 +336,6 @@ def work_order(report: dict[str, Any], include_reconsider: bool = False) -> list
         counts[entry["finding_class"]] = counts.get(entry["finding_class"], 0) + 1
     per_class: dict[str, float] = {}
     class_delta: dict[str, float] = {}
-    ordering = {Band.QUICK_WIN: 0, Band.MAJOR_PROJECT: 1, Band.FILL_IN: 2, Band.RECONSIDER: 3}
     items: list[dict[str, Any]] = []
     for entry in raw:
         weight: ClassWeight = entry.pop("weight")
@@ -298,7 +365,7 @@ def work_order(report: dict[str, Any], include_reconsider: bool = False) -> list
 
     items.extend(_items_from_semantic(report))
     items.sort(key=lambda item: (
-        ordering[Band(item["band"])], -item["class_delta"],
+        BAND_ORDER[item["band"]], -item["class_delta"],
         # Within a class every delta is identical, so severity is what
         # actually orders the work a reader will do first.
         -item["severity"], item["path"]))
@@ -358,7 +425,7 @@ def _semantic_item(
         "delta": 0.0,
         "class_delta": 0.0,
         "class_count": class_count,
-        "verification": "python -m maintainability_audit --root . --format json",
+        "verification": AUDIT_VERIFICATION,
     }
 
 
@@ -416,8 +483,9 @@ def prompt_items(items: list[dict[str, Any]], limit: int = 12,
                  escalated: set[str] | None = None) -> list[dict[str, Any]]:
     """Agent subset: no major projects, no escalated returns; Severe leads.
 
-    Economic reorder may bury a risk-5 item under hot-file Fill-Ins. The
-    table can stay exposure-ordered; the paste of 12 cannot drop Severe.
+    The economic reorder orders items by exposure within each band (D170),
+    so a risk-5 item can still sit below hotter Quick Wins of other classes.
+    The table can stay exposure-ordered; the paste of 12 cannot drop Severe.
     """
     blocked = escalated or set()
     eligible = [