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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.2.0
+Version: 3.3.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.2.0**.
+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

{maintainability_agent-3.2.0 → maintainability_agent-3.3.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.2.0**.
+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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.2.0
+Version: 3.3.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.2.0**.
+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

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

@@ -191,6 +191,7 @@ 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_child_sandbox.py
 tests/test_ci_history_recipe.py
 tests/test_ci_installs_the_analyzer_pool.py
 tests/test_claimed_languages.py
@@ -279,6 +280,7 @@ tests/test_js_declarations.py
 tests/test_language_coverage.py
 tests/test_language_support_honesty.py
 tests/test_mcp_baseline_payload.py
+tests/test_mcp_format_contract.py
 tests/test_mcp_history.py
 tests/test_mcp_server.py
 tests/test_migration_1_0.py

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

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

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_arguments.py

@@ -120,6 +120,15 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--output", help="Output file. Defaults to stdout.")
     _add_artifact_arguments(parser)
     parser.add_argument("--sarif-output", help="Optional SARIF output path for GitHub code scanning.")
+    parser.add_argument(
+        "--security-pillar",
+        help=(
+            "Path to the security-pillar.json secure-code-agent writes with its "
+            "own --security-pillar. ADR 007 delegates the security pillar, and "
+            "this is the document it is read from; defaults to "
+            ".maintainability/security-pillar.json."
+        ),
+    )
     parser.add_argument("--sarif-input", action="append", help="Optional external SARIF file to summarize in reports. Repeatable.")
     parser.add_argument("--changed-only", help="Audit only files changed in a git revspec, for example main...HEAD.")
     parser.add_argument("--baseline", help="Existing baseline JSON. With --fail-on-new, only new findings fail.")

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_coverage_notes.py

@@ -59,4 +59,40 @@ def coverage_notes(coverage: dict[str, Any]) -> list[str]:
             "or widen `analyzers.depth`, to have them reported.",
             "",
         ])
+
+    lines.extend(_child_boundary_note(coverage))
     return lines
+
+
+def _child_boundary_note(coverage: dict[str, Any]) -> list[str]:
+    """What this run does not control about the tools it spawned.
+
+    `docs/product-intent.md` has said since P1 was amended that this
+    package "does not sandbox children", and lists *"that third-party
+    tools cannot use the network"* among the things it does not promise.
+    The **report** did not say it. A reader holding a page headed "the
+    analysis itself performs no network access" and a table naming the
+    external tools that ran had no way to learn the second sentence does
+    not cover the first.
+
+    That makes it P8's gap rather than P1's: the promise was correctly
+    scoped all along, and the run relying on that scoping never disclosed
+    it to the person reading the output.
+
+    Only when an external tool actually ran. With no children spawned
+    there is nothing to disclose, and saying it anyway would be the noise
+    this section is careful to avoid.
+    """
+    spawned = coverage.get("tools_contributed") or 0
+    if not spawned:
+        return []
+    return [
+        "**Analyzer children are not network-isolated.** "
+        f"{spawned} external {'tool' if spawned == 1 else 'tools'} ran as local "
+        "child processes. This agent does not transmit the audited source and "
+        "opens no socket of its own, but it does not sandbox what it spawns: a "
+        "third-party analyzer that reaches the network is outside what this run "
+        "controls or observes. Determinism and no upload are the promise; a "
+        "kernel air-gap is not.",
+        "",
+    ]

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_criteria_scope.py

@@ -154,40 +154,46 @@ def complete_from_built_ins(
     """
     completed: dict[str, dict[str, float]] = {}
     for unit, values in per_unit.items():
-        missing = declaration_concepts_missing(set(values))
-        if not missing:
-            completed[unit] = values
-            continue
-        location = unit_locations.get(unit)
-        fallback = built_in.get(location) if location else None
-        filled = dict(values)
-        for concept in missing:
-            if fallback and concept in fallback:
-                filled[concept] = fallback[concept]
-        if declaration_concepts_missing(set(filled)):
-            # No counterpart in the scanner's reading, so this
-            # declaration is not scoreable on the full criterion set by
-            # either tier — and it is dropped rather than left to
-            # disqualify its language.
-            #
-            # Measured, because the alternative looked reasonable and was
-            # not: `lizard` reads files the built-in scanner produces no
-            # declarations for — Alamofire's `docs/js/jquery.min.js` and
-            # `jazzy.js`, five generated documentation assets. Keeping
-            # them gave JavaScript a bucket that could never be completed
-            # and took the whole repository to the built-in tier, Swift
-            # and all. The same shape hid Java behind a repository's
-            # bundled `.js`.
-            #
-            # Dropping them also aligns the two populations: a unit the
-            # scanner never read is not in the built-in rate either, so
-            # including it in the analyzer rate compares a wider
-            # population against a narrower one.
-            continue
-        completed[unit] = filled
+        filled = _completed_unit(values, unit_locations.get(unit), built_in)
+        if filled is not None:
+            completed[unit] = filled
     return completed
 
 
+def _completed_unit(
+    values: dict[str, float],
+    location: tuple[str, int] | None,
+    built_in: dict[tuple[str, int], dict[str, float]],
+) -> dict[str, float] | None:
+    """One declaration's readings, completed from the built-in tier.
+
+    `None` means the union of both tiers still does not cover the
+    criterion set, so this declaration is **dropped** rather than left to
+    disqualify its language.
+
+    Measured, because the alternative looked reasonable and was not:
+    `lizard` reads files the built-in scanner produces no declarations
+    for — Alamofire's `docs/js/jquery.min.js` and `jazzy.js`, five
+    generated documentation assets. Keeping them gave JavaScript a bucket
+    that could never be completed and took the whole repository to the
+    built-in tier, Swift and all. The same shape hid Java behind a
+    repository's bundled `.js`.
+
+    Dropping them also aligns the two populations: a unit the scanner
+    never read is not in the built-in rate either, so including it in the
+    analyzer rate compares a wider population against a narrower one.
+    """
+    missing = declaration_concepts_missing(set(values))
+    if not missing:
+        return values
+    fallback = (built_in.get(location) if location else None) or {}
+    filled = dict(values)
+    for concept in missing:
+        if concept in fallback:
+            filled[concept] = fallback[concept]
+    return None if declaration_concepts_missing(set(filled)) else filled
+
+
 def built_in_readings(
     metrics: object, root: str = ""
 ) -> dict[tuple[str, int], dict[str, float]]:

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_delegated_pillar.py

@@ -58,6 +58,19 @@ DEFAULT_PILLAR_PATH = ".maintainability/security-pillar.json"
 #: 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"
+#: Versions of that contract this tool can read. **Two, deliberately.**
+#: v2 is v1 plus `scoring_model` and nothing else, so a reader that
+#: handles both is not guessing: the producer asserts the key-set
+#: difference is exactly that one field.
+#:
+#: Accepting v2 before the producer emits it is what removes the
+#: deadlock. If MA required v1 while `secure-code-agent` shipped v2,
+#: every document would be refused for the window between the two
+#: releases -- silently, since a refused document reads as no delegated
+#: pillar. Either side can now release first.
+SCHEMA_VERSIONS = frozenset({1, 2})
+
+#: Kept for callers that imported the old name. The gate reads the set.
 SCHEMA_VERSION = 1
 
 #: What the pillar block takes from the document. Named rather than
@@ -75,6 +88,16 @@ CARRIED = (
     "findings_by_severity",
     "reported_not_scored",
     "loc_scanned",
+    #: v2. The producer's own identifier for its scoring model, bumped
+    #: when a repository's condition could differ for reasons that are
+    #: not the repository -- normalizer, slope, weights, letter bands,
+    #: the scanner floor, or the built-in rule profile. Absent on v1.
+    #:
+    #: This is what MA keys a delegated trend on, in preference to the
+    #: producer's version, because the version moves on docs releases
+    #: that change no score and fragmenting a trend for those teaches a
+    #: reader to ignore the breaks (D155).
+    "scoring_model",
 )
 
 
@@ -104,7 +127,7 @@ def read_delegated(root: Path, relative: str = DEFAULT_PILLAR_PATH) -> dict[str,
         return None
     if payload.get("schema") != SCHEMA:
         return None
-    if payload.get("schema_version") != SCHEMA_VERSION:
+    if payload.get("schema_version") not in SCHEMA_VERSIONS:
         return None
     return payload if _is_well_formed(payload) else None
 

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_html_report_sections.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 from html import escape
 from typing import Any
 
+from ._coverage_notes import coverage_notes
 from ._evidence_view import test_suite_lines
 from ._grammar import counted
 from ._hotspots import hotspot_cognitive, hotspot_complexity, hotspot_name
@@ -55,9 +56,31 @@ def coverage_section(report: dict[str, Any]) -> list[str]:
                 f"<td>{escape(str(entry.get('measurements', '—')))}</td>"
                 f"<td>{escape(str(entry.get('findings', '—')))}</td></tr>")
     parts.append("</table>")
+    parts.extend(_coverage_notes_html(coverage))
     return parts
 
 
+def _coverage_notes_html(coverage: dict[str, Any]) -> list[str]:
+    """The gap prose the Markdown skin prints, in the HTML skin too.
+
+    The table answers "what ran". These notes answer what a reader asks
+    next — one source only, a dimension the analyzer tier declined,
+    nothing examined — and the HTML report carried **none** of them,
+    including "Nothing examined", which `_coverage_notes` itself calls
+    the point of the whole section. ADR 011 says the skins render one
+    report dict and never disagree; that claim was resting on the prose
+    being built as Markdown strings inside the Markdown renderer.
+
+    Rendered as the same visible sentences rather than re-marked-up:
+    the notes carry `**bold**` and `` `code` `` for Markdown, and a
+    reader of the page should see the text, not the syntax.
+    """
+    return [
+        f"<p>{escape(line.replace('**', '').replace('`', ''))}</p>"
+        for line in coverage_notes(coverage) if line
+    ]
+
+
 def _current_series_html(history: list[dict[str, Any]]) -> list[str]:
     """The series in force, in full — the one a reader acts on today."""
     segment = history[-1]

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_mcp_audit.py

@@ -47,6 +47,7 @@ from ._work_order import prompt_targets
 from .baseline import finding_fingerprints
 from .config import (
     VERSION,
+    _refuse_symlinked_route,
     analyzers_run_default,
     discovered_config,
     load_config,
@@ -122,6 +123,20 @@ def _check_freshness_when_a_grant_is_the_only_cover(
 
 
 def authorize_config(config_path: str | None, root: Path) -> str | None:
+    """The config a caller named, or a refusal — bounded like every other path.
+
+    Two rules, and this door enforced only one of them. Containment on
+    the *resolved* path catches a config outside the repository. It
+    cannot catch an **inward** link — `root/link -> root/src` — because
+    that resolves to a path inside the repository and passes every
+    containment check there is. That escape shows on the lexical route
+    only, which is why `repository_path` walks it (D34).
+
+    So the two doors onto one rule disagreed: `repository_path` refused
+    `link/…` and this returned the target. The baseline seam below
+    already carries a comment recording this same escape being found and
+    closed *there*; this door was never revisited (Grok, 673e667).
+    """
     if config_path is None:
         return None
     config = _resolved(config_path, relative_to=root)
@@ -137,6 +152,11 @@ def authorize_config(config_path: str | None, root: Path) -> str | None:
             "audited. A config file must live inside the repository it "
             "configures."
         )
+    # After containment, on the route as written rather than as resolved.
+    # `repository_path` orders it the same way, and the shared helper is
+    # what keeps the two doors from drifting apart again.
+    candidate = Path(config_path).expanduser()
+    _refuse_symlinked_route(root, candidate if candidate.is_absolute() else root / candidate)
     return str(config)
 
 
@@ -415,10 +435,22 @@ def _finish_result(result: dict[str, Any], format: str, root: Path,
 
     8.5: the host asked the user which presentation and passes the answer
     here. One findings body per call (D8): json carries the report dict
-    and no rendering; chat and markdown carry the rendered Markdown (on
-    the wire the two are the same text, ADR 011 §2); html adds the HTML
-    text beside that Markdown, returned for the host to save or show —
-    files are the CLI's job (ADR 011 §4).
+    and no rendering; html adds the HTML text beside a Markdown payload,
+    returned for the host to save or show — files are the CLI's job
+    (ADR 011 §4).
+
+    **`chat` and `markdown` are not the same text on the wire**, and
+    this docstring said they were while the code beside it already
+    passed `complete=(format == "markdown")`. They are two skins:
+
+    - **chat** is the *bounded* skin — the inline UI view, trimmed to
+      stay under a host's payload cap so a large repository's response
+      is not truncated mid-report with the remediation prompt inside it;
+    - **markdown** is the *complete* report, the whole document, because
+      it was chosen as a file to keep.
+
+    A reader who believed the old sentence would have concluded the
+    bounding was a rendering accident rather than the contract.
     """
     if format not in ("chat", "markdown", "html", "json"):
         raise InvalidAuditArgument(f"format must be chat, markdown, html or json, not {format!r}")

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_pillars.py

@@ -155,6 +155,13 @@ CARRIED = (
     "findings_by_severity",
     "reported_not_scored",
     "loc_scanned",
+    #: v2 of the contract. The producer's identifier for its scoring
+    #: model, which is what a delegated trend is keyed on (D155). Absent
+    #: on a v1 document, and `None` there rather than invented — the
+    #: history falls back to the producer version, which fragments
+    #: pre-field releases correctly instead of asserting they shared one
+    #: model.
+    "scoring_model",
 )
 
 

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

@@ -76,6 +76,15 @@ COMPARABILITY_FIELDS: tuple[str, ...] = (
     "analyzers",
     "scored_languages",
     "scope",
+    # A delegated pillar's condition is stored in `pillars` like any
+    # other, but this tool did not measure it and cannot see when the
+    # producer's scoring changed. `secure-code-agent` altered its
+    # normalizer twice in one day without touching the document's
+    # schema: same shape, same fields, a different number for the same
+    # repository. Without this field the series joins straight across
+    # that -- this module's opening defect, arriving through a tool we
+    # delegated to rather than one we run.
+    "delegated_producers",
 )
 
 
@@ -131,6 +140,11 @@ class ScanRecord:
     aspects: dict[str, float | None] = field(default_factory=dict)
     pillars: dict[str, float | None] = field(default_factory=dict)
     practice_level: int | None = None
+    #: Each delegated pillar's producer and version, as the document
+    #: announced them -- `("security:secure-code-agent 0.9.0",)`. A
+    #: comparability field: the producer's version is the only thing
+    #: this tool can see that moves when their scoring does.
+    delegated_producers: tuple[str, ...] = ()
     evidence_status: str = ""
     # Which of those a remediation prompt actually asked somebody to fix.
     # This is what makes recurrence a strong signal rather than a weak
@@ -210,6 +224,7 @@ FIELD_NAMES: dict[str, str] = {
     "analyzers": "which analyzers contributed",
     "scored_languages": "the scored languages",
     "scope": "the scan scope",
+    "delegated_producers": "a delegated pillar's producer or its version",
 }
 
 
@@ -349,11 +364,31 @@ def _is_scan_record(line: str) -> bool:
     return isinstance(record, dict) and "recorded_at" in record
 
 
-# Fields stored as sequences, derived from the dataclass rather than
-# listed by hand so a new one is handled the day it is added.
-_SEQUENCE_FIELDS: tuple[str, ...] = (
-    "analyzers", "scored_languages", "fingerprints", "targeted", "identities",
-)
+def _sequence_fields() -> tuple[str, ...]:
+    """Fields stored as sequences, read off the dataclass.
+
+    The constant this replaced carried the comment "derived from the
+    dataclass rather than listed by hand so a new one is handled the day
+    it is added" — and was a hand-written list of five names. The
+    sentence was aspirational, and it cost exactly what it promised to
+    prevent: `delegated_producers` was added and missed, and the
+    round-trip guard caught a stored record no longer comparing equal to
+    a freshly built one.
+
+    `from __future__ import annotations` makes every annotation a
+    string, so the declared type is matched textually. That is narrow on
+    purpose: a field is a sequence here only if it says `tuple`, and a
+    field that stores a sequence under some other spelling would need
+    naming — which is a smaller trap than a list nobody updates.
+    """
+    from dataclasses import fields
+    return tuple(
+        spec.name for spec in fields(ScanRecord)
+        if str(spec.type).startswith("tuple")
+    )
+
+
+_SEQUENCE_FIELDS: tuple[str, ...] = _sequence_fields()
 
 
 def read_history(path: Path) -> list[ScanRecord]:
@@ -465,6 +500,59 @@ def _score_fields(score: dict[str, Any]) -> dict[str, Any]:
     }
 
 
+def _delegated_producers(report: dict[str, Any]) -> tuple[str, ...]:
+    """Which tool, at which version, supplied each delegated pillar.
+
+    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`.
+
+    A pillar whose document names no version still contributes its
+    producer, because "the same tool, version unknown" and "a different
+    tool" are different facts and only the second should break a series
+    on its own.
+    """
+    found = []
+    for entry in report.get("pillars") or []:
+        tool = entry.get("delegated_to")
+        if not tool:
+            continue
+        found.append(f"{entry.get('pillar')}:{tool} {_model_key(entry)}")
+    return tuple(sorted(found))
+
+
+def _model_key(entry: dict[str, Any]) -> str:
+    """What identifies the instrument behind one delegated pillar.
+
+    The producer's **scoring model** when the document declares one, and
+    its version otherwise.
+
+    Version was the first answer and it over-breaks: a docs-only release
+    of the producer opens a new series having changed no score, and a
+    break that fires for nothing teaches a reader to ignore the ones that
+    matter. `scoring_model` is the producer's own identifier for "a
+    repository's condition could differ here for reasons that are not the
+    repository", so it moves when the numbers can and not otherwise.
+
+    **A document without the field is never collapsed to a single model.**
+    Falling back to the version fragments those releases, which is
+    correct: `secure-code-agent`'s releases before the field existed do
+    not share one scoring model — the corroboration merge, the rank
+    discount and the normalizer each moved the numbers independently.
+    Assigning them one id would assert a comparability that was never
+    true, so the producer reserves model 1 and never emits it.
+
+    The v1-to-v2 transition therefore breaks the series once, where the
+    instrument's self-description changed. That break is honest and it
+    happens exactly once.
+    """
+    model = entry.get("scoring_model")
+    if model is not None:
+        return f"model {model}"
+    return str(entry.get("producer_version") or "unversioned")
+
+
 def record_of(report: dict[str, Any], config: dict[str, Any], version: str,
               calibration: float, fingerprints: tuple[str, ...],
               targeted: tuple[str, ...] = (), backfilled: bool = False) -> ScanRecord:
@@ -496,6 +584,7 @@ def record_of(report: dict[str, Any], config: dict[str, Any], version: str,
         # opts in by setting one field rather than by threading a new
         # argument through every caller of this function.
         transformation=str(report.get("transformation") or ""),
+        delegated_producers=_delegated_producers(report),
         estimate=published["estimate"],
         range_low=published["range_low"],
         range_high=published["range_high"],

{maintainability_agent-3.2.0 → maintainability_agent-3.3.0}/src/maintainability_audit/_test_execution.py

@@ -27,8 +27,10 @@ import shlex
 from pathlib import Path
 from typing import Any
 
+from ._catalog import MAX_TIMEOUT_SECONDS, MIN_TIMEOUT_SECONDS
 from ._operator_reads import PathNotAllowed, read_source_file
 from ._runner import Invocation, run
+from ._user_config import user_config_answers
 from ._xml import AnalyzerXmlRefused, parse_analyzer_xml
 
 _ENV_ASSIGNMENT = re.compile(r"^[A-Za-z_]\w*=")
@@ -67,23 +69,67 @@ def _parse_command(command: list[str]) -> tuple[dict[str, str], list[str]]:
 def suite_opted_in(config: dict[str, Any]) -> bool:
     """Both halves of the opt-in: the request, and a command to run.
 
-    A pure function of the config it is handed, deliberately. The
-    repository can no longer put either half there — `load_config`
-    strips `test_execution.requested` and `expected_commands.test` out
-    of the repository tier before the merge (D147) — so by the time a
-    config reaches here, an opt-in in it came from the person.
-
-    Keeping the check here and the boundary there is the design. A
-    reader of this function should not have to know which tier a key
-    came from, and a caller handing it a config should get an answer
-    about *that* config. The tier question belongs in the one function
-    whose job is deciding which tier wins.
+    A pure function of the config it is handed, deliberately.
+    `load_config` strips **`test_execution.requested`** out of the
+    repository tier before the merge (D147), so the *request* reaching
+    here came from the person.
+
+    `expected_commands.test` is **not** stripped, and this docstring
+    used to say it was. That key is documentation — "this is how you
+    test me" — and `require_test_command` reads it, so removing it would
+    fail a real gate on every repository that correctly documents its
+    command. The consequence is that the command in a merged config may
+    be the tree's, which makes this function the wrong place to learn
+    *what* to run. It answers only whether a run was consented to and
+    whether any command is documented; `opted_in_command` answers which
+    program the person actually agreed to.
     """
     requested = bool((config.get("test_execution") or {}).get("requested"))
     command = (config.get("expected_commands") or {}).get("test")
     return requested and bool(command)
 
 
+def opted_in_command() -> list[str]:
+    """The test command the person consented to — user tier only.
+
+    Cited by `config._host_authority_stripped` and by `_setup_persist`
+    as the reader that makes keeping `expected_commands.test` in the
+    repository document safe. **It did not exist.** Three docstrings
+    described a boundary that nothing enforced, and `run_test_suite`
+    read the merged config instead — so a repository that documented a
+    command had that command executed the moment any person opted in,
+    which is the authority inversion D147 named and did not close.
+
+    The distinction it restores: the tree may *say* how it is tested;
+    only the person may choose what this host runs. Setup writes the
+    command into the user tier at the moment it is shown and accepted
+    (`_setup_persist`), so consent and program are recorded together.
+
+    Empty means the person opted in without a command reaching their
+    tier, which is not permission to fall back to the repository's.
+    """
+    answers = user_config_answers() or {}
+    command = (answers.get("expected_commands") or {}).get("test")
+    return list(command) if isinstance(command, list) else []
+
+
+def _bounded_suite_timeout(configured: Any) -> int:
+    """A suite timeout the audited tree cannot weaponise.
+
+    The same clamp `_catalog._bounded_timeout` applies to
+    `analyzers.timeout_seconds`, on the sibling door: a crafted
+    `2147483647` makes the host wait sixty-eight years for a child it
+    was told to run, which is D40's family in a field that was missing
+    the bound. A non-integer or out-of-band value falls back to the
+    default rather than propagating.
+    """
+    try:
+        seconds = int(configured)
+    except (TypeError, ValueError):
+        return DEFAULT_SUITE_TIMEOUT_SECONDS
+    return max(MIN_TIMEOUT_SECONDS, min(seconds, MAX_TIMEOUT_SECONDS))
+
+
 def run_test_suite(root: Path, config: dict[str, Any]) -> dict[str, Any] | None:
     """Execute the configured test command, or ``None`` when not opted in.
 
@@ -92,14 +138,34 @@ def run_test_suite(root: Path, config: dict[str, Any]) -> dict[str, Any] | None:
     """
     if not suite_opted_in(config):
         return None
-    command = list(config["expected_commands"]["test"])
+    # Every spawn setting is read from the **person's** tier, never from
+    # the merged config. `config["expected_commands"]["test"]` is what
+    # this line used to be, and the repository's document reaches that
+    # key by design (it is documentation `require_test_command` needs),
+    # so reading it here let the tree choose the program the moment
+    # anybody opted in. The keys are named here rather than hidden
+    # behind the helper so a reader sees which population is governed.
+    answers = user_config_answers() or {}
+    command = opted_in_command()
+    if not command:
+        return {
+            "command": (config.get("expected_commands") or {}).get("test") or [],
+            "ran": False, "exit_code": None, "passed": False,
+            "detail": (
+                "opted in, but no test command is recorded in the user tier; "
+                "the repository's documented command is not run on its own say-so"
+            ),
+            "coverage_percent": None,
+        }
     env, argv = _parse_command(command)
     # A whole test suite is legitimately slower than a single analyzer, so
     # it gets its own timeout rather than the 120s analyzer cap that was
     # killing real suites mid-run. Operator-configurable under
-    # `test_execution.timeout_seconds`.
-    timeout = int((config.get("test_execution") or {}).get(
-        "timeout_seconds", DEFAULT_SUITE_TIMEOUT_SECONDS))
+    # `test_execution.timeout_seconds`, and clamped: a repository naming
+    # a timeout is naming how long this host waits.
+    timeout = _bounded_suite_timeout(
+        (answers.get("test_execution") or {}).get(
+            "timeout_seconds", DEFAULT_SUITE_TIMEOUT_SECONDS))
     if not argv:
         # A command that is only env assignments (or empty) names no
         # program to run. Report it as configured but unrunnable rather