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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.4.0
+Version: 3.6.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.4.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.6.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.4.0 → maintainability_agent-3.6.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.4.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.6.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.4.0 → maintainability_agent-3.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "3.4.0"
+version = "3.6.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.4.0 → maintainability_agent-3.6.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.4.0
+Version: 3.6.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.4.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.6.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.4.0 → maintainability_agent-3.6.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
@@ -236,6 +238,7 @@ tests/test_environment_work_order.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_falsifier_standard.py
 tests/test_file_list_cap_class.py
@@ -304,6 +307,7 @@ tests/test_practice_nested_gates_class.py
 tests/test_precommit_staged.py
 tests/test_presentation_refusals.py
 tests/test_promises.py
+tests/test_prompt_does_not_issue_rates_when_unscored.py
 tests/test_prompt_escalation_once.py
 tests/test_prompt_honesty.py
 tests/test_prompt_location_escalation_class.py
@@ -342,6 +346,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.4.0 → maintainability_agent-3.6.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.4.0 → maintainability_agent-3.6.0}/src/maintainability_audit/__init__.py

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

{maintainability_agent-3.4.0 → maintainability_agent-3.6.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']}`",
@@ -212,7 +226,28 @@ def prompt_pressure_section(score: dict[str, Any]) -> list[str]:
     statement an agent can prioritize against. Dimensions at or below 1.0
     are deliberately left out: they are already normal, and listing them
     invites busywork.
+
+    **Nothing here is printed when the overall estimate was withheld
+    (D163).** A corpus multiple *is* a score — it is a rate compared
+    against a calibrated median — so a run that refused to issue an
+    overall on too little evidence cannot turn around and rank this
+    repository's dimensions against that same corpus. P7 governs both.
+
+    The demo tree is the case that made it visible: the report said
+    `Not scored` and its own README said *"only the rates are
+    withheld"*, while the file the README calls the work order opened
+    with `declarations at 3.9x` and `Start with declarations`. The
+    complete Markdown report on the same run printed no multiples. Only
+    the advertised product file did.
+
+    The work order itself is unaffected and still names every finding —
+    a finding is an observation, not a rate, and withholding those would
+    leave an undersized repository with nothing at all.
     """
+    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)]
     dimensions = score.get("dimensions") or {}
     elevated = sorted(
         # `is not None` first: an unmeasured dimension is legitimate --
@@ -246,13 +281,23 @@ def prompt_pressure_section(score: dict[str, Any]) -> list[str]:
                 "",
             ]
         )
-    for blocker in view.grade_blockers(score):
-        lines.append(f"- Grade capped: {blocker}")
-    if view.grade_blockers(score):
-        lines.append("")
+    lines.extend(_grade_blocker_lines(score))
     return lines
 
 
+def _grade_blocker_lines(score: dict[str, Any]) -> list[str]:
+    """Why the grade is capped — printed whether or not a number was issued.
+
+    Split out so the withheld-score path above can render it too: the
+    reasons a score was capped or refused are the one part of this
+    section that is not itself a rate.
+    """
+    blockers = view.grade_blockers(score)
+    if not blockers:
+        return []
+    return [*(f"- Grade capped: {blocker}" for blocker in blockers), ""]
+
+
 def _escalated_fingerprints(report: dict[str, Any]) -> set[str]:
     """Findings the history shows do not stay fixed.
 

{maintainability_agent-3.4.0 → maintainability_agent-3.6.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,