maintainability-agent 3.0.2__tar.gz → 3.2.0__tar.gz

{maintainability_agent-3.0.2/src/maintainability_agent.egg-info → maintainability_agent-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.0.2
+Version: 3.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -45,7 +45,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.0.2**.
+Version **3.2.0**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/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.0.2**.
+Version **3.2.0**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "3.0.2"
+version = "3.2.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

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.0.2
+Version: 3.2.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -45,7 +45,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.0.2**.
+Version **3.2.0**.
 
 **Planned, not shipped:** the audit tool will become `maintainability-audit`;
 a new `maintainability-agent` companion will run it and automate human-selected

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -29,18 +29,21 @@ src/maintainability_audit/_conformance.py
 src/maintainability_audit/_corroborate.py
 src/maintainability_audit/_coverage_notes.py
 src/maintainability_audit/_criteria_scope.py
+src/maintainability_audit/_delegated_pillar.py
 src/maintainability_audit/_derive.py
 src/maintainability_audit/_discovery.py
 src/maintainability_audit/_documents.py
 src/maintainability_audit/_economics.py
 src/maintainability_audit/_economics_view.py
 src/maintainability_audit/_environment.py
+src/maintainability_audit/_evidence_reader.py
 src/maintainability_audit/_evidence_view.py
 src/maintainability_audit/_finding_match.py
 src/maintainability_audit/_first_run.py
 src/maintainability_audit/_formula.py
 src/maintainability_audit/_gates.py
 src/maintainability_audit/_generic.py
+src/maintainability_audit/_grammar.py
 src/maintainability_audit/_grant_ledger.py
 src/maintainability_audit/_history_view.py
 src/maintainability_audit/_hostile_prompt.py
@@ -68,6 +71,7 @@ src/maintainability_audit/_precommit.py
 src/maintainability_audit/_precommit_install.py
 src/maintainability_audit/_precommit_view.py
 src/maintainability_audit/_pressures.py
+src/maintainability_audit/_prompt_sections.py
 src/maintainability_audit/_ranges_c.py
 src/maintainability_audit/_ranges_cobol.py
 src/maintainability_audit/_ranges_core.py
@@ -82,6 +86,7 @@ src/maintainability_audit/_ranges_ruby.py
 src/maintainability_audit/_ranges_rust.py
 src/maintainability_audit/_ranges_swift.py
 src/maintainability_audit/_ratchet.py
+src/maintainability_audit/_ratio_adapters.py
 src/maintainability_audit/_recurrence.py
 src/maintainability_audit/_run_comparison.py
 src/maintainability_audit/_runner.py
@@ -183,6 +188,7 @@ tests/test_calibration_tooling.py
 tests/test_catalog_selection.py
 tests/test_catalog_tier_promise.py
 tests/test_chat_primary_docs.py
+tests/test_check_refuses_plus_only_fragments.py
 tests/test_checkstyle_adapter.py
 tests/test_checkstyle_catalog.py
 tests/test_ci_history_recipe.py
@@ -211,8 +217,10 @@ tests/test_declaration_edge_cases.py
 tests/test_declaration_grading.py
 tests/test_declaration_ranges.py
 tests/test_declaration_source.py
+tests/test_declarative_parsers.py
 tests/test_declared_authorship.py
 tests/test_declared_imports.py
+tests/test_delegated_security_pillar.py
 tests/test_derivation_mix.py
 tests/test_determinism.py
 tests/test_dimension_ratchet.py
@@ -279,6 +287,7 @@ tests/test_network_disclosure.py
 tests/test_one_setup_across_surfaces_class.py
 tests/test_operator_named_paths.py
 tests/test_operator_named_reads.py
+tests/test_pairing_reads_imports.py
 tests/test_pattern_budget.py
 tests/test_phase6_claims.py
 tests/test_php_declarations.py
@@ -302,6 +311,7 @@ tests/test_python_declarations.py
 tests/test_read_boundary.py
 tests/test_readme_claims.py
 tests/test_recurrence.py
+tests/test_release_needs_an_empty_ledger.py
 tests/test_release_plan.py
 tests/test_release_plan_status.py
 tests/test_report_remedy_copy.py
@@ -333,14 +343,18 @@ tests/test_stage8_contract.py
 tests/test_suite_isolation.py
 tests/test_swift_declarations.py
 tests/test_tdd_structure.py
+tests/test_terminal_asks_the_same_questions.py
 tests/test_test_commands.py
 tests/test_test_execution_class.py
 tests/test_three_presentations.py
 tests/test_tool_resolution.py
+tests/test_tree_cannot_opt_the_host_in.py
 tests/test_tree_chosen_spawn.py
+tests/test_tree_reads_use_the_primitive.py
 tests/test_trends.py
 tests/test_type_fields_not_functions_class.py
 tests/test_uat_falsifiers.py
+tests/test_unanchored_set_matches_corpus.py
 tests/test_unread_code.py
 tests/test_user_config_tier.py
 tests/test_verification_audit_closures.py
@@ -348,6 +362,7 @@ tests/test_verified_grade.py
 tests/test_version_claim.py
 tests/test_wheel_contents.py
 tests/test_work_order.py
+tests/test_work_order_binds_to_this_interpreter.py
 tests/test_work_order_items.py
 tests/test_work_order_selection.py
 tests/test_workflow_supply_chain.py

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "3.0.2"
+__version__ = "3.2.0"

maintainability_agent-3.2.0/src/maintainability_audit/_anchor.py

@@ -0,0 +1,73 @@
+"""What the reference corpus does not hold, and how to say it.
+
+Rubric data, like `_calibration`: a fact about the anchor rather than a
+computation over a repository. It lives beside the constant it qualifies
+because the two go stale together — a recalibration that adds Swift and
+COBOL to the corpus empties this in the same commit that moves
+`CALIBRATION_C`.
+
+**Unanchored is policy, not an oversight.** Under the corpus policy
+decided with 2.4.1, a language ships parsed and the corpus is re-measured
+once after the remaining scanners land: adding a scanner moves
+`scanner_fingerprint` and invalidates every stored measurement, so paying
+per language means paying in full, repeatedly, for an anchor that is
+obsolete again at the next one.
+
+What is *not* policy is silence about it where the grade is read. The
+report carried `score.reference` and the note said the corpus spanned
+"every language this scanner parses" — which was true when it was written
+and false from 2.4.0 onward, for three releases. A Grok audit on
+2026-09-04 named it as the second instance of a shape this project had
+already shipped once: a limit disclosed only in JSON is disclosed nowhere
+that matters.
+"""
+from __future__ import annotations
+
+#: Parsed by a scanner, absent from the reference corpus.
+#:
+#: Stated rather than derived, and the reason still holds:
+#: `tools/calibration/corpus.json` is a repository file that does not ship
+#: in the wheel, so a runtime read would be unavailable exactly where a
+#: user reads a grade. What a stated list buys in availability it owes in
+#: upkeep, and it did not pay.
+#:
+#: **D143.** This read `("Swift", "COBOL", "Go", "Rust", "PHP", "Ruby")`
+#: after 3.0.0 anchored five of those six. The corpus grew from 112
+#: repositories to 180 and from eight measured languages to thirteen, and
+#: this line did not move — so every skin told a Swift, Go, Rust, PHP or
+#: Ruby reader their grade was provisional against a corpus that had
+#: measured their language for two releases. A caveat that names an
+#: anchored language is not a caution, it is a false statement about the
+#: evidence, and it undersells the thing the recalibration was for.
+#:
+#: COBOL stays, and stays alone. It is parsed and deliberately never
+#: anchored: GitHub holds one COBOL repository above 500 stars and what is
+#: there is curriculum, Java parsers and JavaScript wrappers rather than
+#: COBOL codebases, so the corpus policy excludes it permanently rather
+#: than temporarily. Emptying this tuple would delete a disclosure that is
+#: still true.
+#:
+#: `tests/test_unanchored_set_matches_corpus.py` recomputes
+#: `parsed - corpus` from `DECLARATION_SUFFIXES` and `corpus.json` and
+#: fails if this stops matching — including when a language is *added* to
+#: the corpus, which is the direction that went unnoticed.
+UNANCHORED_LANGUAGES: tuple[str, ...] = ("COBOL",)
+
+
+def unanchored_names() -> str:
+    """The languages, joined for a sentence. Empty when there are none."""
+    return " and ".join(UNANCHORED_LANGUAGES)
+
+
+def unanchored_sentence() -> str:
+    """One sentence naming what the anchor omits, for the corpus note."""
+    if not UNANCHORED_LANGUAGES:
+        return ""
+    from ._grammar import agreement
+
+    say = agreement(len(UNANCHORED_LANGUAGES))
+    return (
+        f"{unanchored_names()} {say.verb} parsed but absent from it, so "
+        f"{say.possessive} findings are as good as {say.possessive} "
+        f"parser while {say.possessive} grade is provisional."
+    )

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/src/maintainability_audit/_assets/standard.md

@@ -118,10 +118,20 @@ The corpus median lands at **4.0 (B)**: a well-run real codebase earns a B, and
 
 ### The reference corpus
 
-Calibration is reproducible, not a snapshot someone took once. The corpus is defined in [`tools/calibration/corpus.json`](../tools/calibration/corpus.json) — 40 mature open-source repositories **pinned to exact commits**, spanning 32 to 18,789 source files and 463,581 declarations across Python, TypeScript and JavaScript:
+Calibration is reproducible, not a snapshot someone took once. The corpus is defined in [`tools/calibration/corpus.json`](../tools/calibration/corpus.json) — **180 mature open-source repositories pinned to exact commits**, spanning 24 to 18,789 source files and 2,749,575 declarations across thirteen languages: Python, TypeScript, JavaScript, Java, C, C++, C#, Fortran, Swift, Go, Rust, PHP and Ruby.
+
+The forty repositories 1.x calibrated on are all still in it, at the commits they were measured at then:
 
 > angular · ansible · ant-design · anime · axios · Chart.js · code-server · django · echarts · excalidraw · express · fastapi · flask · freeCodeCamp · github-readme-stats · hackingtool · hoppscotch · jquery · keras · localstack · lodash · manim · material-ui · mermaid · models · n8n · nest · playwright · reveal.js · scrapy · strapi · svelte · tabby · tailwindcss · transformers · uBlock · vite · webpack · youtube-dl · yt-dlp
 
+**This paragraph opened "40 mature open-source repositories … across
+Python, TypeScript and JavaScript" for two releases after 3.0.0 measured
+180 across thirteen (D143).** The corrected numbers were four paragraphs
+below it the whole time, so a reader met both and had nothing to tell
+them which was current. Same defect as the unanchored caveat below and
+found in the same pass: a count written into prose, with nothing that
+fails when the thing it counts moves.
+
 **What the anchor does not cover.** For five releases this section named a
 real defect: the corpus was 40 repositories of Python, TypeScript and
 JavaScript while the scanner parsed eight languages, so Java, C, C++, C#
@@ -131,23 +141,34 @@ median and fortran-lang/stdlib at **1.10x** — the first a true statement
 about LAPACK relative to mature OSS *web* code, and not a statement about
 typical Fortran, because no typical Fortran was in the comparison set.
 
-**2.0.0 extended the corpus rather than the caveat.** It is now 112
-repositories spanning eight languages: Python, TypeScript, JavaScript,
-Java, C, C++, C# and Fortran. The original 40 rows are unchanged and still
-pinned to the commits they were measured at, so what moved the constants
-is the languages added and nothing else.
-
-**Six parsed languages are not in it.** Swift (2.4.0), COBOL (2.7.0)
-and Go, Rust, PHP and Ruby (2.11.0) shipped after that measurement and
-are **unanchored**: a scanner reads them, and the medians their rates are
-compared against were measured on other languages. This is the corpus policy decided with 2.4.1 — a
-language ships parsed, and the corpus is re-measured once after the
-remaining scanners land, because a new scanner moves
-`scanner_fingerprint` and invalidates every stored row. The cost is
-disclosed rather than absorbed: findings in those languages are as good
-as their parser, their grade is provisional, and every surface that
-prints a grade says so. This sentence read "every language this scanner
-parses" for three releases after it stopped being true.
+**3.0.0 extended the corpus.** It is now **180 repositories spanning
+thirteen languages**: Python, TypeScript, JavaScript, Java, C, C++, C#,
+Fortran, Swift, Go, Rust, PHP and Ruby. The 112 rows measured for 2.0.0
+are unchanged and still pinned to the commits they were measured at, so
+what moved the constants is the languages added and nothing else.
+
+**One parsed language is not in it: COBOL.** It is **unanchored** — a
+scanner reads it, and the medians its rates are compared against were
+measured on other languages. The cost is disclosed rather than absorbed:
+findings in COBOL are as good as their parser, a COBOL grade is
+provisional, and every surface that prints a grade says so.
+
+COBOL is unanchored **permanently**, not pending a re-measure. Against
+the corpus criteria GitHub holds one COBOL repository above 500 stars,
+and what is public is curriculum, Java parsers and JavaScript wrappers
+rather than COBOL codebases; the language's real corpus is on private
+mainframes. Anchoring it on what exists would build a reference out of
+teaching material — an anchor that *looks* like one, which is worse than
+the disclosed absence.
+
+Two corrections are recorded here rather than quietly applied, because
+both were live for multiple releases. This sentence read "every language
+this scanner parses" for three releases after that stopped being true.
+It then named **six** unanchored languages for two releases after 3.0.0
+anchored five of them (D143) — Swift, Go, Rust, PHP and Ruby readers were
+told their grade was provisional against a corpus that had measured their
+language. A caveat naming an anchored language is not a caution; it is a
+false statement about the evidence.
 
 Three limits remain, and they are narrower than the one they replace:
 

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/src/maintainability_audit/_banner.py

@@ -17,9 +17,12 @@ one-way.
 """
 from __future__ import annotations
 
+import os
 import re
 from pathlib import Path
 
+from ._operator_reads import open_regular_file
+
 # Whatever a language uses to open a comment, plus decoration a generator
 # may pad the line with: `#`, `//`, `*`, `/*`, `!`, `--`, `<!--`, `;`, and
 # the emoji rules some tools draw. `@` is spared, or `# @generated` would
@@ -40,12 +43,29 @@ BANNER_LINES = 20
 def banner_says_generated(
     path: Path, banners: tuple[str, ...]
 ) -> str | None:
-    """The banner text, if the head of this file carries one."""
+    """The banner text, if the head of this file carries one.
+
+    The head only, so this stays cheap on a large tree — but read
+    *through* a checked handle rather than by name, so a FIFO refuses
+    instead of stopping the audit dead (D145). `path.open()` on one waits
+    for a writer that never comes, and the previous `except OSError`
+    could not have caught that: there is no error to catch, only a
+    process that never returns.
+    """
     try:
-        with path.open(encoding="utf-8", errors="replace") as handle:
-            head = "".join(next(handle, "") for _ in range(BANNER_LINES)).lower()
+        handle = open_regular_file(
+            path,
+            "Banner detection reads the head of a discovered file; a "
+            "device, socket or FIFO would block the audit rather than "
+            "declare itself generated.",
+        )
     except OSError:
         return None
+    try:
+        with os.fdopen(handle, "r", encoding="utf-8", errors="replace", closefd=False) as opened:
+            head = "".join(next(opened, "") for _ in range(BANNER_LINES)).lower()
+    finally:
+        os.close(handle)
     previous: str | None = None
     for raw in head.splitlines():
         stripped = COMMENT_LEAD.sub("", raw).strip()

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/src/maintainability_audit/_catalog.py

@@ -190,7 +190,23 @@ def decide(tool: dict[str, Any], settings: dict[str, Any]) -> Selection:
     3. the depth, licence and concern tiers.
     """
     slug = tool["slug"]
+    return (
+        _denial(tool, settings)
+        or (Selection(slug, True, "explicitly allowed by name")
+            if slug in settings["allow_tools"] else None)
+        or _tier_decision(tool, settings)
+    )
+
+
+def _denial(tool: dict[str, Any], settings: dict[str, Any]) -> Selection | None:
+    """Step 1: every deny, which beats even an explicit allow.
 
+    `None` means nothing here refused the tool, not that it was admitted —
+    the caller has two more steps. Separate from the tiers because these
+    are the operator's own prohibitions and the tiers are policy: a deny
+    that could be overridden by an allow would not be a deny.
+    """
+    slug = tool["slug"]
     if slug in settings["deny_tools"]:
         return Selection(slug, False, "denied by name")
     if tool["license_class"] in settings["deny_license_classes"]:
@@ -198,10 +214,14 @@ def decide(tool: dict[str, Any], settings: dict[str, Any]) -> Selection:
     denied_concerns = set(tool["upstream_tags"]) & set(settings["deny_concerns"])
     if denied_concerns:
         return Selection(slug, False, f"concern {','.join(sorted(denied_concerns))} denied")
+    return None
 
-    if slug in settings["allow_tools"]:
-        return Selection(slug, True, "explicitly allowed by name")
 
+def _tier_decision(tool: dict[str, Any], settings: dict[str, Any]) -> Selection:
+    """Step 3: the depth, licence and concern tiers, for a tool no deny
+    caught and no allow admitted. The only step that can end in `True`
+    on the tool's own merits."""
+    slug = tool["slug"]
     if tool["deprecated"]:
         return Selection(slug, False, "deprecated upstream")
     if not tool["languages"]:

maintainability_agent-3.2.0/src/maintainability_audit/_delegated_pillar.py

@@ -0,0 +1,181 @@
+"""Reading a delegated pillar's own report of itself.
+
+[ADR 007](adr-007-pillars-and-practice.md) makes the five pillars of the
+source framework the top-level taxonomy and declares **Security
+delegated to `secure-code-agent`**, reported as `NotApplicable` so that
+silence is never read as safety. That entry was always a placeholder for
+an artifact that did not exist yet: the other tool measures the pillar,
+so the other tool has to be the one that reports it.
+
+`secure-code-agent` 0.5.0 ships the emitter — `--security-pillar <path>`
+writes `security-pillar.json`, schema `secure-code-agent/security-pillar`
+— and it was built against *this* vocabulary rather than its own. The
+scope words, the two-axis split and the posture matrix with its
+thresholds all come from `_pillars.py`, because two tools saying "level
+3" or "healthy" about one repository have to mean the same thing by it
+or the joined view is worse than either alone.
+
+This module reads the document and checks it is the one expected. The
+*shaping* of the pillar entry lives in `_pillars` beside the entries it
+sits among — scoring may not import a scanner, and reading a path the
+audited tree chooses is what makes this one. Neither half computes a
+number: a delegated pillar's numbers belong to the tool that measured
+them, and a consumer that recomputed anything would be a second opinion
+nobody asked for.
+
+**Absence is the normal case and stays the documented one.** No file
+means the pillar reports exactly what it reported before — delegated,
+`NotApplicable`, naming the other tool. That path is not a failure and
+does not warn: most repositories run one tool.
+
+**A file that cannot be trusted is refused rather than partly believed.**
+Wrong schema, unreadable JSON, a shape that is not an object — each
+returns `None`, and the pillar falls back to the honest placeholder. The
+alternative is a security posture assembled from a document this tool
+does not actually understand, which is worse than no posture at all.
+
+A trailing note on where this sits: it reads a path from the audited
+tree, so it is a scanner rather than part of the rubric.
+`test_scoring_never_imports_scanners_or_assembly` holds that boundary,
+and `report` is what joins the two.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from ._operator_reads import PathNotAllowed, read_source_file
+
+#: Written beside the other artifacts a repository keeps about itself.
+#: The path is a convention rather than a search: a document this tool
+#: trusts for a whole pillar should be somewhere a reader can find, not
+#: wherever a glob happened to match.
+DEFAULT_PILLAR_PATH = ".maintainability/security-pillar.json"
+
+#: The contract this module understands. A document announcing anything
+#: else is refused rather than read hopefully — the schema string is the
+#: producer's promise about the shape, and guessing past it is how a
+#: consumer starts reporting fields that mean something different.
+SCHEMA = "secure-code-agent/security-pillar"
+SCHEMA_VERSION = 1
+
+#: What the pillar block takes from the document. Named rather than
+#: copied wholesale so a field added upstream cannot silently appear in
+#: this tool's report carrying meaning nobody here has checked.
+CARRIED = (
+    "practice",
+    "condition",
+    "condition_letter",
+    "posture",
+    "verified_grade",
+    "evidence_status",
+    "evidence_reasons",
+    "coverage",
+    "findings_by_severity",
+    "reported_not_scored",
+    "loc_scanned",
+)
+
+
+def read_delegated(root: Path, relative: str = DEFAULT_PILLAR_PATH) -> dict[str, Any] | None:
+    """The delegated pillar's own report, or `None` when there is none.
+
+    `None` for every reason a reader might not get a usable document:
+    the file is absent, it is not a regular file, it does not parse, it
+    is not an object, or it announces a schema this tool does not know.
+    All five collapse to one answer because the caller does the same
+    thing with each — keep the placeholder that names the other tool.
+
+    Read through the regular-file primitive like every other path the
+    audited tree chooses (D145): a FIFO here would hang the audit rather
+    than fail it.
+    """
+    path = Path(root) / relative
+    if not path.exists():
+        return None
+    try:
+        payload = json.loads("\n".join(read_source_file(path)))
+    except (OSError, ValueError) as error:
+        if isinstance(error, PathNotAllowed):
+            raise
+        return None
+    if not isinstance(payload, dict):
+        return None
+    if payload.get("schema") != SCHEMA:
+        return None
+    if payload.get("schema_version") != SCHEMA_VERSION:
+        return None
+    return payload if _is_well_formed(payload) else None
+
+
+#: Fields whose *shape* the consumer depends on. A header check alone
+#: accepts any object announcing the right schema, and the pillar then
+#: reads these as if the producer had promised them.
+_SHAPES: tuple[tuple[str, type | tuple[type, ...]], ...] = (
+    ("producer", dict),
+    ("practice", dict),
+    ("condition", (int, float, type(None))),
+    ("posture", (str, type(None))),
+    ("evidence_status", (str, type(None))),
+    ("coverage", (dict, type(None))),
+    ("findings_by_severity", (dict, type(None))),
+    ("reported_not_scored", (dict, type(None))),
+)
+
+#: The postures this tool knows how to render. A document naming one it
+#: does not is refused rather than printed through: the word is the
+#: reader's whole summary of the pillar.
+_POSTURES = frozenset({"healthy", "managed debt", "unmanaged debt", "unverified"})
+
+
+def _is_well_formed(payload: dict[str, Any]) -> bool:
+    """Whether the document's fields are the shapes the pillar reads.
+
+    The header said what the document *claims to be*; this asks whether
+    it is. Checking only `schema` accepted
+    `{"producer": "not-an-object", ...}`, which the pillar then indexed
+    as a mapping and crashed on — a well-formed announcement with a
+    malformed body, which is the shape a header check cannot see.
+
+    Also refused: a `posture` this tool cannot render, and a `posture`
+    the document's own two axes do not support. The second is the one
+    worth stating. `healthy` requires practice at or above
+    `HIGH_PRACTICE` and a condition at or above `GOOD_CONDITION`; a
+    document claiming `healthy` at practice 1 is either a different
+    matrix or a mistake, and either way this tool must not print it.
+    Both tools are supposed to mean the same thing by the word — the
+    consumer is where that is checkable.
+    """
+    for name, kinds in _SHAPES:
+        if name in payload and not isinstance(payload[name], kinds):
+            return False
+    practice = payload.get("practice")
+    if isinstance(practice, dict) and not isinstance(practice.get("level"), int):
+        return False
+    posture = payload.get("posture")
+    if posture is not None and posture not in _POSTURES:
+        return False
+    return _posture_agrees(payload)
+
+
+def _posture_agrees(payload: dict[str, Any]) -> bool:
+    """Whether the stated posture follows from the two axes given.
+
+    Recomputed rather than trusted. The matrix and its thresholds are
+    `_pillars.py`'s, copied into the producer by value, and a copied
+    constant is a constant that can drift — so the one place the two
+    can be compared is here, against a document carrying both inputs
+    and the answer.
+    """
+    from ._pillars import posture as compute
+
+    stated = payload.get("posture")
+    practice = payload.get("practice")
+    if stated is None or not isinstance(practice, dict):
+        return True
+    level = practice.get("level")
+    condition = payload.get("condition")
+    if not isinstance(level, int):
+        return False
+    return compute(level, condition) == stated

{maintainability_agent-3.0.2 → maintainability_agent-3.2.0}/src/maintainability_audit/_derive.py

@@ -17,9 +17,10 @@ from statistics import median
 from typing import Any
 
 from ._aspects import evidence_aspect_scores, is_untested
+from ._evidence_reader import normalize_report_evidence
 from ._formula import CALIBRATED_ASPECTS, curve, overall_from_aspects
 from ._pressures import production_pressures
-from .evidence import REPORT_SCHEMA_VERSION, SCHEMA_VERSION_KEY, normalize_report_evidence
+from .evidence import REPORT_SCHEMA_VERSION, SCHEMA_VERSION_KEY
 
 # The stored column holding the analyzers' production reading. Named
 # once because both the refusal and the mix key on it.