maintainability-agent 3.3.0__tar.gz → 3.5.0__tar.gz

{maintainability_agent-3.3.0/src/maintainability_agent.egg-info → maintainability_agent-3.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.3.0
+Version: 3.5.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -29,6 +29,7 @@ Requires-Dist: mcp<3,>=2; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
 Requires-Dist: jsonschema>=4; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: pip-audit>=2.7; extra == "dev"
@@ -45,12 +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.3.0**.
-
-**Planned, not shipped:** the audit tool will become `maintainability-audit`;
-a new `maintainability-agent` companion will run it and automate human-selected
-work orders within the user's agent chat. The installation commands below
-still describe the current product. See the [planned split](docs/product-intent.md#planned-product-split-and-companion-workflow).
+Version **3.5.0**.
 
 **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
@@ -65,6 +61,51 @@ pip install "maintainability-agent[mcp]"   # optional local MCP server for chat
 cp -r skills/maintainability-agent ~/.claude/skills/   # Claude Code slash command
 ```
 
+**Install the analyzer pool too, or you get the built-in tier.** This tool
+prefers established analyzers and falls back to its own detectors when none is
+present. The fallback is honest — the report says `Estimate source: built-in
+detectors` and the coverage section names what nothing examined — but it is a
+weaker reading than the tool is capable of, and a first run without these is
+the commonest reason it looks thin.
+
+```bash
+pip install cohesion complexipy flake8 fortitude-lint interrogate lizard \
+  multimetric mypy pydocstyle pylint radon ruff vulture
+npm install -g jscpd eslint            # duplication + JavaScript/TypeScript
+brew install pmd checkstyle spotbugs   # JVM languages, optional
+```
+
+Unpinned on purpose: this is the exact set CI installs and calibrates against,
+and `test_the_readme_names_the_analyzer_pool_ci_installs` fails if the two ever
+disagree. Nothing here is required — the audit runs without any of it and tells
+you what it could not measure.
+
+**One command to a work order.** A config file is the whole setup — with one
+present, nothing is asked and nothing is written into your tree:
+
+```bash
+curl -O https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/maintainability-audit.example.json
+maintainability-audit --config maintainability-audit.example.json \
+  --output report.md --prompt-output prompt.md
+```
+
+`prompt.md` is the bounded work order: the findings worth fixing, in order,
+each with its location, why it matters and the command that verifies it — and
+the standing rule that nothing else gets refactored. Paste it into your agent.
+`report.md` is the evidence behind it. The prompt is the product.
+
+**Want to see the output before pointing it at your own code?**
+[`examples/demo`](examples/demo/) is a two-module order system with real
+problems in it — an overgrown pricing function, a money path nothing tests, and
+a block duplicated between billing and invoicing. Four items, three finding
+classes, a copy-paste prompt each, and it reads in under a minute. The work
+order it produces is checked in at
+[`expected-prompt.md`](examples/demo/expected-prompt.md).
+
+Without `--config`, an interactive run asks the first-run questions instead —
+analyzer pool, depth, licence policy, whether to run your suite — because those
+are choices this tool will not make on your behalf.
+
 ---
 
 ## Executive summary
@@ -128,15 +169,6 @@ The full argument, including what this deliberately does not compete on:
 [why this exists](docs/why-this-exists.md) and
 [philosophy](docs/philosophy.md).
 
-## The road to 1.0
-
-1.0 was the line drawn under a long arc of **subtraction** — what remained after
-every claim the project could not stand behind was removed. A scoring engine
-rebuilt after it was found to grade repo *size*; a headline claim about AI
-authorship retracted against a matched control; a score that is withheld rather
-than guessed. That arc is the credibility, and it is recorded in full, with the
-figures quoted from their approved summaries, in [the track record](docs/track-record.md).
-
 ## Install
 
 ```bash
@@ -380,19 +412,21 @@ it was generated against — a provenance record, not a claim about HEAD.
 
 | Metric | Value |
 |---|---:|
-| Maintainability estimate | 4.2 / 5 |
+| Maintainability estimate | 4.5 / 5 |
 | Verified grade | B |
-| Files scanned | 476 |
+| Files scanned | 511 |
 | Hard gate failures | 0 |
 
 A **B**, and the report says why: the grade is verified against the evidence
-*floor* of 4.1 rather than the 4.2 point estimate, because an unmeasured aspect
-prices at 0 when a grade has to be defended; and testability is capped at 4.0 by
-an unpaired production unit in the fail band. Those are measured against
-thresholds this repo sets stricter than the shipped defaults, and every threshold
-gate is opted **on** for its own CI, so drifting below the bar fails the build
-rather than the README. The full stamped table — warnings, duplication, risk
-findings — is in the report itself.
+*floor* of 4.2 rather than the 4.5 point estimate, because an unmeasured aspect
+prices at 0 when a grade has to be defended. Every threshold gate is opted
+**on** for this repository's own CI, so drifting below the bar fails the build
+rather than the README.
+
+The tool reports warn-band declarations here and they are not treated as
+defects — see [what counts as a defect](docs/product-intent.md#what-counts-as-a-defect-and-what-does-not).
+Restyling this codebase to raise its own grade is explicitly not work: a tool
+that games its own metric has broken the only promise that matters.
 
 ## Platform support
 

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/README.md

@@ -5,12 +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.3.0**.
-
-**Planned, not shipped:** the audit tool will become `maintainability-audit`;
-a new `maintainability-agent` companion will run it and automate human-selected
-work orders within the user's agent chat. The installation commands below
-still describe the current product. See the [planned split](docs/product-intent.md#planned-product-split-and-companion-workflow).
+Version **3.5.0**.
 
 **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
@@ -25,6 +20,51 @@ pip install "maintainability-agent[mcp]"   # optional local MCP server for chat
 cp -r skills/maintainability-agent ~/.claude/skills/   # Claude Code slash command
 ```
 
+**Install the analyzer pool too, or you get the built-in tier.** This tool
+prefers established analyzers and falls back to its own detectors when none is
+present. The fallback is honest — the report says `Estimate source: built-in
+detectors` and the coverage section names what nothing examined — but it is a
+weaker reading than the tool is capable of, and a first run without these is
+the commonest reason it looks thin.
+
+```bash
+pip install cohesion complexipy flake8 fortitude-lint interrogate lizard \
+  multimetric mypy pydocstyle pylint radon ruff vulture
+npm install -g jscpd eslint            # duplication + JavaScript/TypeScript
+brew install pmd checkstyle spotbugs   # JVM languages, optional
+```
+
+Unpinned on purpose: this is the exact set CI installs and calibrates against,
+and `test_the_readme_names_the_analyzer_pool_ci_installs` fails if the two ever
+disagree. Nothing here is required — the audit runs without any of it and tells
+you what it could not measure.
+
+**One command to a work order.** A config file is the whole setup — with one
+present, nothing is asked and nothing is written into your tree:
+
+```bash
+curl -O https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/maintainability-audit.example.json
+maintainability-audit --config maintainability-audit.example.json \
+  --output report.md --prompt-output prompt.md
+```
+
+`prompt.md` is the bounded work order: the findings worth fixing, in order,
+each with its location, why it matters and the command that verifies it — and
+the standing rule that nothing else gets refactored. Paste it into your agent.
+`report.md` is the evidence behind it. The prompt is the product.
+
+**Want to see the output before pointing it at your own code?**
+[`examples/demo`](examples/demo/) is a two-module order system with real
+problems in it — an overgrown pricing function, a money path nothing tests, and
+a block duplicated between billing and invoicing. Four items, three finding
+classes, a copy-paste prompt each, and it reads in under a minute. The work
+order it produces is checked in at
+[`expected-prompt.md`](examples/demo/expected-prompt.md).
+
+Without `--config`, an interactive run asks the first-run questions instead —
+analyzer pool, depth, licence policy, whether to run your suite — because those
+are choices this tool will not make on your behalf.
+
 ---
 
 ## Executive summary
@@ -88,15 +128,6 @@ The full argument, including what this deliberately does not compete on:
 [why this exists](docs/why-this-exists.md) and
 [philosophy](docs/philosophy.md).
 
-## The road to 1.0
-
-1.0 was the line drawn under a long arc of **subtraction** — what remained after
-every claim the project could not stand behind was removed. A scoring engine
-rebuilt after it was found to grade repo *size*; a headline claim about AI
-authorship retracted against a matched control; a score that is withheld rather
-than guessed. That arc is the credibility, and it is recorded in full, with the
-figures quoted from their approved summaries, in [the track record](docs/track-record.md).
-
 ## Install
 
 ```bash
@@ -340,19 +371,21 @@ it was generated against — a provenance record, not a claim about HEAD.
 
 | Metric | Value |
 |---|---:|
-| Maintainability estimate | 4.2 / 5 |
+| Maintainability estimate | 4.5 / 5 |
 | Verified grade | B |
-| Files scanned | 476 |
+| Files scanned | 511 |
 | Hard gate failures | 0 |
 
 A **B**, and the report says why: the grade is verified against the evidence
-*floor* of 4.1 rather than the 4.2 point estimate, because an unmeasured aspect
-prices at 0 when a grade has to be defended; and testability is capped at 4.0 by
-an unpaired production unit in the fail band. Those are measured against
-thresholds this repo sets stricter than the shipped defaults, and every threshold
-gate is opted **on** for its own CI, so drifting below the bar fails the build
-rather than the README. The full stamped table — warnings, duplication, risk
-findings — is in the report itself.
+*floor* of 4.2 rather than the 4.5 point estimate, because an unmeasured aspect
+prices at 0 when a grade has to be defended. Every threshold gate is opted
+**on** for this repository's own CI, so drifting below the bar fails the build
+rather than the README.
+
+The tool reports warn-band declarations here and they are not treated as
+defects — see [what counts as a defect](docs/product-intent.md#what-counts-as-a-defect-and-what-does-not).
+Restyling this codebase to raise its own grade is explicitly not work: a tool
+that games its own metric has broken the only promise that matters.
 
 ## Platform support
 

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "3.3.0"
+version = "3.5.0"
 description = "Maintainability gate and AI remediation prompt generator for CI."
 readme = "README.md"
 # 3.11, not 3.10. `_discovery`, `_pillars` and `_runner` all import
@@ -58,7 +58,7 @@ mcp = ["mcp>=2,<3"]
 # development dependency, never a runtime one: nothing the product
 # ships imports it, and the oracle exists so a measurement can be
 # checked against something other than its author.
-dev = ["pytest>=8", "pytest-cov>=5", "jsonschema>=4", "ruff>=0.5", "pip-audit>=2.7", "mcp>=2,<3", "PyYAML>=6", "setuptools>=70", "lizard>=1.17"]
+dev = ["pytest>=8", "pytest-cov>=5", "pytest-xdist>=3.6", "jsonschema>=4", "ruff>=0.5", "pip-audit>=2.7", "mcp>=2,<3", "PyYAML>=6", "setuptools>=70", "lizard>=1.17"]
 
 [tool.setuptools.package-data]
 # `_assets` carries the runtime data the code cannot work without: the

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.3.0
+Version: 3.5.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -29,6 +29,7 @@ Requires-Dist: mcp<3,>=2; extra == "mcp"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
 Requires-Dist: jsonschema>=4; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: pip-audit>=2.7; extra == "dev"
@@ -45,12 +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.3.0**.
-
-**Planned, not shipped:** the audit tool will become `maintainability-audit`;
-a new `maintainability-agent` companion will run it and automate human-selected
-work orders within the user's agent chat. The installation commands below
-still describe the current product. See the [planned split](docs/product-intent.md#planned-product-split-and-companion-workflow).
+Version **3.5.0**.
 
 **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
@@ -65,6 +61,51 @@ pip install "maintainability-agent[mcp]"   # optional local MCP server for chat
 cp -r skills/maintainability-agent ~/.claude/skills/   # Claude Code slash command
 ```
 
+**Install the analyzer pool too, or you get the built-in tier.** This tool
+prefers established analyzers and falls back to its own detectors when none is
+present. The fallback is honest — the report says `Estimate source: built-in
+detectors` and the coverage section names what nothing examined — but it is a
+weaker reading than the tool is capable of, and a first run without these is
+the commonest reason it looks thin.
+
+```bash
+pip install cohesion complexipy flake8 fortitude-lint interrogate lizard \
+  multimetric mypy pydocstyle pylint radon ruff vulture
+npm install -g jscpd eslint            # duplication + JavaScript/TypeScript
+brew install pmd checkstyle spotbugs   # JVM languages, optional
+```
+
+Unpinned on purpose: this is the exact set CI installs and calibrates against,
+and `test_the_readme_names_the_analyzer_pool_ci_installs` fails if the two ever
+disagree. Nothing here is required — the audit runs without any of it and tells
+you what it could not measure.
+
+**One command to a work order.** A config file is the whole setup — with one
+present, nothing is asked and nothing is written into your tree:
+
+```bash
+curl -O https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/maintainability-audit.example.json
+maintainability-audit --config maintainability-audit.example.json \
+  --output report.md --prompt-output prompt.md
+```
+
+`prompt.md` is the bounded work order: the findings worth fixing, in order,
+each with its location, why it matters and the command that verifies it — and
+the standing rule that nothing else gets refactored. Paste it into your agent.
+`report.md` is the evidence behind it. The prompt is the product.
+
+**Want to see the output before pointing it at your own code?**
+[`examples/demo`](examples/demo/) is a two-module order system with real
+problems in it — an overgrown pricing function, a money path nothing tests, and
+a block duplicated between billing and invoicing. Four items, three finding
+classes, a copy-paste prompt each, and it reads in under a minute. The work
+order it produces is checked in at
+[`expected-prompt.md`](examples/demo/expected-prompt.md).
+
+Without `--config`, an interactive run asks the first-run questions instead —
+analyzer pool, depth, licence policy, whether to run your suite — because those
+are choices this tool will not make on your behalf.
+
 ---
 
 ## Executive summary
@@ -128,15 +169,6 @@ The full argument, including what this deliberately does not compete on:
 [why this exists](docs/why-this-exists.md) and
 [philosophy](docs/philosophy.md).
 
-## The road to 1.0
-
-1.0 was the line drawn under a long arc of **subtraction** — what remained after
-every claim the project could not stand behind was removed. A scoring engine
-rebuilt after it was found to grade repo *size*; a headline claim about AI
-authorship retracted against a matched control; a score that is withheld rather
-than guessed. That arc is the credibility, and it is recorded in full, with the
-figures quoted from their approved summaries, in [the track record](docs/track-record.md).
-
 ## Install
 
 ```bash
@@ -380,19 +412,21 @@ it was generated against — a provenance record, not a claim about HEAD.
 
 | Metric | Value |
 |---|---:|
-| Maintainability estimate | 4.2 / 5 |
+| Maintainability estimate | 4.5 / 5 |
 | Verified grade | B |
-| Files scanned | 476 |
+| Files scanned | 511 |
 | Hard gate failures | 0 |
 
 A **B**, and the report says why: the grade is verified against the evidence
-*floor* of 4.1 rather than the 4.2 point estimate, because an unmeasured aspect
-prices at 0 when a grade has to be defended; and testability is capped at 4.0 by
-an unpaired production unit in the fail band. Those are measured against
-thresholds this repo sets stricter than the shipped defaults, and every threshold
-gate is opted **on** for its own CI, so drifting below the bar fails the build
-rather than the README. The full stamped table — warnings, duplication, risk
-findings — is in the report itself.
+*floor* of 4.2 rather than the 4.5 point estimate, because an unmeasured aspect
+prices at 0 when a grade has to be defended. Every threshold gate is opted
+**on** for this repository's own CI, so drifting below the bar fails the build
+rather than the README.
+
+The tool reports warn-band declarations here and they are not treated as
+defects — see [what counts as a defect](docs/product-intent.md#what-counts-as-a-defect-and-what-does-not).
+Restyling this codebase to raise its own grade is explicitly not work: a tool
+that games its own metric has broken the only promise that matters.
 
 ## Platform support
 

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -187,6 +187,7 @@ tests/test_calibration_drift.py
 tests/test_calibration_tooling.py
 tests/test_catalog_selection.py
 tests/test_catalog_tier_promise.py
+tests/test_chat_leads_with_the_work_order.py
 tests/test_chat_primary_docs.py
 tests/test_check_refuses_plus_only_fragments.py
 tests/test_checkstyle_adapter.py
@@ -222,6 +223,7 @@ tests/test_declarative_parsers.py
 tests/test_declared_authorship.py
 tests/test_declared_imports.py
 tests/test_delegated_security_pillar.py
+tests/test_demo_tree.py
 tests/test_derivation_mix.py
 tests/test_determinism.py
 tests/test_dimension_ratchet.py
@@ -342,6 +344,7 @@ tests/test_source_index.py
 tests/test_spotbugs_adapter.py
 tests/test_spotbugs_catalog.py
 tests/test_stage8_contract.py
+tests/test_stdout_outputs.py
 tests/test_suite_isolation.py
 tests/test_swift_declarations.py
 tests/test_tdd_structure.py

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/src/maintainability_agent.egg-info/requires.txt

@@ -2,6 +2,7 @@
 [dev]
 pytest>=8
 pytest-cov>=5
+pytest-xdist>=3.6
 jsonschema>=4
 ruff>=0.5
 pip-audit>=2.7

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "3.3.0"
+__version__ = "3.5.0"

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/src/maintainability_audit/_prompt_sections.py

@@ -178,13 +178,27 @@ def prompt_work_order(report: dict[str, Any]) -> list[str]:
     for index, item in enumerate(items, start=1):
         location = item["path"] + (f":{item['line']}" if item.get("line") else "")
         lines.append(f"{index}. **{item['title']}** — {item['target']}")
-        lines.append(f"   - Location: `{location}`")
+        # One row now stands for its whole class (D159), so a count
+        # above one says where the rest are rather than leaving the
+        # single location reading as the only instance.
+        count = item.get("class_count") or 1
+        files = item.get("class_paths") or 1
+        if count > 1:
+            where = f"across {files} files, " if files > 1 else ""
+            lines.append(f"   - First of {count} {where}starting at: `{location}`")
+        else:
+            lines.append(f"   - Location: `{location}`")
         lines.append(f"   - Why it matters: {item['rationale']}")
         if item["class_delta"]:
             lines.append(
                 f"   - Clearing all {item['class_count']} of these is worth "
                 f"+{item['class_delta']:.2f} to the maintainability estimate."
             )
+        elif count > 1:
+            lines.append(
+                f"   - The other {count - 1} are listed in the report; the "
+                "score does not move until the class is cleared."
+            )
     lines.extend([
         "",
         f"Verify with: `{items[0]['verification']}`",

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/src/maintainability_audit/_scan_history.py

@@ -57,7 +57,7 @@ from .config import PathNotAllowed, read_operator_file
 # followed. A schema-4 line read by an older build fails that one line's
 # parse and costs that scan, which is the tolerance `read_history` was
 # built with rather than a new risk.
-HISTORY_SCHEMA_VERSION = 4
+HISTORY_SCHEMA_VERSION = 5
 
 DEFAULT_HISTORY_PATH = ".maintainability/history.jsonl"
 
@@ -70,7 +70,7 @@ DEFAULT_HISTORY_PATH = ".maintainability/history.jsonl"
 # score being added and not added here, after which trends silently span
 # a change in the instrument.
 COMPARABILITY_FIELDS: tuple[str, ...] = (
-    "rubric_version",
+    "tool_version",
     "calibration",
     "thresholds_digest",
     "analyzers",
@@ -102,7 +102,14 @@ class ScanRecord:
     commit: str
     branch: str
     scope: str
-    rubric_version: str
+    #: The version of *this tool* that produced the scan. Named
+    #: `rubric_version` until 3.5.0, which is what it was never: a
+    #: rubric version would move when the rubric moved, and this moves
+    #: on every release. A reader of a stored line saw
+    #: `"rubric_version": "3.4.0"` and concluded the rubric had changed
+    #: when a patch release was all that happened — on 38 of this
+    #: repository's 49 series breaks (D158).
+    tool_version: str
     calibration: float
     # A digest of the thresholds in force. Stored rather than the
     # thresholds themselves: the comparison is equality, and a digest
@@ -210,21 +217,28 @@ def comparability_key(record: ScanRecord) -> tuple[Any, ...]:
 
 
 # What each comparability field is, in words a reader can act on. The
-# stored names are terse and one of them actively misleads: the field
-# called `rubric_version` holds the *package* version, so a reader told
-# "rubric_version changed" hears that the rubric moved when a patch
-# release is all that happened — and on this repository's own history
-# that field accounts for 38 of 49 breaks. The name stays as stored
-# (renaming it is a migration of every written line); what the report
-# says about it is corrected here, which is where the claim is made.
+# stored names are terse and prose is what a report should print: a
+# break that names `thresholds_digest` tells a reader less than one
+# saying the configured thresholds changed.
+#
+# `tool_version` was `rubric_version` until 3.5.0 and this map was
+# where that lie was first corrected — the display said "the tool
+# version" while the stored field still said otherwise. D158 finished
+# it by renaming the field, so the map and the record now agree instead
+# of one translating the other.
 FIELD_NAMES: dict[str, str] = {
-    "rubric_version": "the tool version",
+    "tool_version": "the tool version",
     "calibration": "the calibration constant",
     "thresholds_digest": "the configured thresholds",
     "analyzers": "which analyzers contributed",
     "scored_languages": "the scored languages",
     "scope": "the scan scope",
-    "delegated_producers": "a delegated pillar's producer or its version",
+    # Names the scoring model rather than the version, because that is
+    # what `_model_key` actually keys on. Saying "its version" sent a
+    # reader looking for a release that in the common case had not
+    # changed -- the v2 document breaks on `scoring_model`, and the
+    # version is only the v1 fallback.
+    "delegated_producers": "a delegated pillar's producer or its scoring model",
 }
 
 
@@ -408,6 +422,15 @@ def read_history(path: Path) -> list[ScanRecord]:
         try:
             payload = json.loads(line)
             payload.pop("history_schema_version", None)
+            # Schema 1-4 stored this as `rubric_version`. Renamed in 5
+            # because the name was never true (D158); every line written
+            # before that keeps loading, and keeps its place in a
+            # series, because the *value* never changed — only what it
+            # is called. A stored history is the one thing here that
+            # cannot be regenerated, so a rename that dropped it would
+            # cost more than the wrong name did.
+            if "rubric_version" in payload:
+                payload["tool_version"] = payload.pop("rubric_version")
             # Every sequence field back to a tuple. JSON has one list
             # type, so a field missed here returns as a list and the
             # record stops comparing equal to a freshly built one —
@@ -506,7 +529,7 @@ def _delegated_producers(report: dict[str, Any]) -> tuple[str, ...]:
     Sorted and joined into one string per pillar so the comparability
     key stays a plain value. Only delegated pillars carry a producer;
     the ones this tool measures itself are already covered by
-    `rubric_version`.
+    `tool_version`.
 
     A pillar whose document names no version still contributes its
     producer, because "the same tool, version unknown" and "a different
@@ -575,7 +598,7 @@ def record_of(report: dict[str, Any], config: dict[str, Any], version: str,
         commit=report.get("git_commit") or "",
         branch=report.get("git_branch") or "",
         scope=report.get("mode") or "full",
-        rubric_version=version,
+        tool_version=version,
         calibration=calibration,
         thresholds_digest=thresholds_digest(config.get("thresholds") or {}),
         analyzers=contributed,

{maintainability_agent-3.3.0 → maintainability_agent-3.5.0}/src/maintainability_audit/_work_order.py

@@ -427,7 +427,48 @@ def prompt_items(items: list[dict[str, Any]], limit: int = 12,
     ]
     severe = [item for item in eligible if item.get("risk") == 5]
     rest = [item for item in eligible if item.get("risk") != 5]
-    return (severe + rest)[:limit]
+    return _one_per_class(severe + rest)[:limit]
+
+
+def _one_per_class(ordered: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """The best member of each finding class, in the order they arrived.
+
+    **The paste is twelve kinds of work, not twelve rows.** Without this
+    a class with a hundred members takes every slot: measured on a real
+    tree, 100 of 125 items were one class and all twelve went to it,
+    six of them naming the same file, while 24 duplicate blocks and an
+    oversized file got none. The prompt says "the first items are the
+    highest value for the least change" and then spent its whole budget
+    on one rule while omitting two others entirely (D159).
+
+    One row per class is enough because the row already carries the
+    whole class: `class_count` and `class_delta` are on every item, so
+    it reads "clearing all 100 of these is worth +0.20" rather than
+    printing a hundred line numbers. An agent is better instructed by
+    one rule and its count than by twelve instances of it.
+
+    Order is preserved rather than re-sorted, so Severe still leads and
+    the economic ordering behind it still holds — this removes
+    repetition and decides nothing about priority.
+    """
+    spread: dict[str, set[str]] = {}
+    for item in ordered:
+        name = str(item.get("finding_class") or item.get("title"))
+        spread.setdefault(name, set()).add(str(item.get("path") or ""))
+
+    seen: set[str] = set()
+    first: list[dict[str, Any]] = []
+    for item in ordered:
+        name = str(item.get("finding_class") or item.get("title"))
+        if name in seen:
+            continue
+        seen.add(name)
+        # The surviving row keeps its own title, which names one file,
+        # so it must also say how far the class reaches — otherwise a
+        # row standing for 46 findings across seven files reads as one
+        # finding in the file it happens to name.
+        first.append({**item, "class_paths": len(spread[name])})
+    return first
 
 
 # The axes a reader can narrow by. Every one is a field already on the
@@ -462,6 +503,34 @@ def select(items: list[dict[str, Any]], **criteria: str) -> list[dict[str, Any]]
     return [item for item in items if matches(item)]
 
 
+def prompt_advised(items: list[dict[str, Any]], limit: int = 12,
+                   escalated: set[str] | None = None) -> list[dict[str, Any]]:
+    """Every eligible item the prompt's rows stand for.
+
+    `prompt_items` returns one row per class, because a paste of twelve
+    is twelve *kinds* of work (D159). What was advised is wider than
+    what was printed: a row reading "clearing all 68 of these" asks for
+    all 68, so recurrence has to remember all 68.
+
+    Derived from `prompt_items` rather than re-selected beside it. The
+    advised set is the classes those rows name, and this expands them —
+    one decision about what to advise, two views of it. Two independent
+    selections would drift, and the one that drifts is the one nobody
+    reads.
+    """
+    advised = {
+        str(item.get("finding_class") or item.get("title"))
+        for item in prompt_items(items, limit, escalated)
+    }
+    blocked = escalated or set()
+    return [
+        item for item in items
+        if item["band"] != Band.MAJOR_PROJECT.value
+        and item.get("fingerprint") not in blocked
+        and str(item.get("finding_class") or item.get("title")) in advised
+    ]
+
+
 def prompt_targets(report: dict[str, Any]) -> tuple[str, ...]:
     """The identities a generated prompt actually asked somebody to fix.
 
@@ -495,7 +564,10 @@ def prompt_targets(report: dict[str, Any]) -> tuple[str, ...]:
     }
     known = set(finding_fingerprints(report))
     targets = set()
-    for item in prompt_items(report.get("work_order") or [], escalated=escalated):
+    # Every member of every advised class, not only the rows printed:
+    # the prompt asks for the whole class, so the told-fixed-returned
+    # signal has to cover the whole class (D159).
+    for item in prompt_advised(report.get("work_order") or [], escalated=escalated):
         fingerprint = item.get("fingerprint")
         if fingerprint is None:
             continue