maintainability-agent 4.3.1__tar.gz → 4.4.1__tar.gz

{maintainability_agent-4.3.1/src/maintainability_agent.egg-info → maintainability_agent-4.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.3.1
+Version: 4.4.1
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: mcp<3,>=2; extra == "dev"
 Requires-Dist: PyYAML>=6; extra == "dev"
 Requires-Dist: setuptools>=70; extra == "dev"
 Requires-Dist: lizard>=1.17; extra == "dev"
-Requires-Dist: markdown>=3.5; extra == "dev"
+Requires-Dist: markdown==3.11.1; extra == "dev"
 Dynamic: license-file
 
 # Maintainability Agent
@@ -47,7 +47,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 **4.3.1**.
+Version **4.4.1**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -372,8 +372,11 @@ codebase is read rather than sampled — FFmpeg's 4,687 files, not the first
 The analyzer is intentionally conservative and under-reports rather than
 over-reports: an unrecognized declaration costs one missed finding, never a
 cascade of false ones. Pair it with native tools (ESLint, Ruff, Radon, Semgrep,
-SonarQube, Qlty) rather than replacing them — their SARIF folds in via
-`--sarif-input`. Accuracy and limits: [docs/language-support.md](docs/language-support.md).
+SonarQube, Qlty) rather than replacing them. This tool runs a pinned handful of
+the analyzers it catalogs; the rest run where you already run them, and their
+SARIF is read, never run: declare each file in `analyzers.pipeline_results`
+with the concerns it covers (first-run setup asks), and those concerns count as
+examined for the languages it names. One-off files fold in via `--sarif-input`. Accuracy and limits: [docs/language-support.md](docs/language-support.md).
 
 ## Language support
 
@@ -509,7 +512,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.3.1
+- uses: marshallguillory86/maintainability-agent@v4.4.1
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/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 **4.3.1**.
+Version **4.4.1**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -330,8 +330,11 @@ codebase is read rather than sampled — FFmpeg's 4,687 files, not the first
 The analyzer is intentionally conservative and under-reports rather than
 over-reports: an unrecognized declaration costs one missed finding, never a
 cascade of false ones. Pair it with native tools (ESLint, Ruff, Radon, Semgrep,
-SonarQube, Qlty) rather than replacing them — their SARIF folds in via
-`--sarif-input`. Accuracy and limits: [docs/language-support.md](docs/language-support.md).
+SonarQube, Qlty) rather than replacing them. This tool runs a pinned handful of
+the analyzers it catalogs; the rest run where you already run them, and their
+SARIF is read, never run: declare each file in `analyzers.pipeline_results`
+with the concerns it covers (first-run setup asks), and those concerns count as
+examined for the languages it names. One-off files fold in via `--sarif-input`. Accuracy and limits: [docs/language-support.md](docs/language-support.md).
 
 ## Language support
 
@@ -467,7 +470,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.3.1
+- uses: marshallguillory86/maintainability-agent@v4.4.1
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/pyproject.toml

@@ -63,7 +63,10 @@ mcp = ["mcp>=2,<3"]
 # ships imports it, and the oracle exists so a measurement can be
 # checked against something other than its author. `markdown` renders the
 # docs/html reading copy (`tools/render_docs.py`); the product never does.
-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", "markdown>=3.5"]
+# It is pinned exactly: the committed copy is checked against a fresh render,
+# and markdown 3.11 rendered two pages differently from 3.10, so an unpinned
+# release failed CI on files nobody had touched (2026-10-14).
+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", "markdown==3.11.1"]
 
 [tool.pydocstyle]
 # D401 ("First line should be in imperative mood") is switched off, and the

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 4.3.1
+Version: 4.4.1
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -37,7 +37,7 @@ Requires-Dist: mcp<3,>=2; extra == "dev"
 Requires-Dist: PyYAML>=6; extra == "dev"
 Requires-Dist: setuptools>=70; extra == "dev"
 Requires-Dist: lizard>=1.17; extra == "dev"
-Requires-Dist: markdown>=3.5; extra == "dev"
+Requires-Dist: markdown==3.11.1; extra == "dev"
 Dynamic: license-file
 
 # Maintainability Agent
@@ -47,7 +47,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 **4.3.1**.
+Version **4.4.1**.
 
 > ## **Calibrated against 201 mature open-source repositories in fifteen languages.**
 >
@@ -372,8 +372,11 @@ codebase is read rather than sampled — FFmpeg's 4,687 files, not the first
 The analyzer is intentionally conservative and under-reports rather than
 over-reports: an unrecognized declaration costs one missed finding, never a
 cascade of false ones. Pair it with native tools (ESLint, Ruff, Radon, Semgrep,
-SonarQube, Qlty) rather than replacing them — their SARIF folds in via
-`--sarif-input`. Accuracy and limits: [docs/language-support.md](docs/language-support.md).
+SonarQube, Qlty) rather than replacing them. This tool runs a pinned handful of
+the analyzers it catalogs; the rest run where you already run them, and their
+SARIF is read, never run: declare each file in `analyzers.pipeline_results`
+with the concerns it covers (first-run setup asks), and those concerns count as
+examined for the languages it names. One-off files fold in via `--sarif-input`. Accuracy and limits: [docs/language-support.md](docs/language-support.md).
 
 ## Language support
 
@@ -509,7 +512,7 @@ instead of an invokable skill:
 This repo ships `action.yml`, usable as a composite action:
 
 ```yaml
-- uses: marshallguillory86/maintainability-agent@v4.3.1
+- uses: marshallguillory86/maintainability-agent@v4.4.1
   with:
     config: maintainability-agent.json
     changed-only: main...HEAD

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -69,6 +69,7 @@ src/maintainability_audit/_metrics_types.py
 src/maintainability_audit/_operator_reads.py
 src/maintainability_audit/_oracle.py
 src/maintainability_audit/_pillars.py
+src/maintainability_audit/_pipeline_results.py
 src/maintainability_audit/_practice.py
 src/maintainability_audit/_precommit.py
 src/maintainability_audit/_precommit_install.py
@@ -181,6 +182,7 @@ tests/test_analyzer_scoring_path.py
 tests/test_analyzer_spread_range.py
 tests/test_analyzer_xml_bounds.py
 tests/test_analyzers_against_the_real_tools.py
+tests/test_analyzers_never_write.py
 tests/test_analyzers_report_what_actually_failed.py
 tests/test_anchor_and_mode.py
 tests/test_anchor_caveat_and_counts_follow_the_run.py
@@ -353,6 +355,7 @@ tests/test_pattern_budget.py
 tests/test_phase6_claims.py
 tests/test_php_declarations.py
 tests/test_pillars_and_practice.py
+tests/test_pipeline_results.py
 tests/test_platform_claim.py
 tests/test_pmd_adapter.py
 tests/test_pmd_audit_closures.py
@@ -381,6 +384,7 @@ tests/test_release_plan.py
 tests/test_release_plan_status.py
 tests/test_rendered_docs.py
 tests/test_report_remedy_copy.py
+tests/test_reported_but_not_scored.py
 tests/test_root_grants.py
 tests/test_rubric_ignores_project_lint_config.py
 tests/test_ruby_declarations.py

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_agent.egg-info/requires.txt

@@ -10,7 +10,7 @@ mcp<3,>=2
 PyYAML>=6
 setuptools>=70
 lizard>=1.17
-markdown>=3.5
+markdown==3.11.1
 
 [mcp]
 mcp<3,>=2

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "4.3.1"
+__version__ = "4.4.1"

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_analysis.py

@@ -19,6 +19,7 @@ clean result.
 
 from __future__ import annotations
 
+import hashlib
 from collections.abc import Sequence
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -40,6 +41,11 @@ from ._metrics_types import KNOWN_SOURCE_SUFFIXES, Finding, Measurement
 from ._runner import Outcome, Probe, ToolResult, run
 from ._selection import Selected, select_runnable
 from .config import acquisition_permitted
+from .git_tools import GitCommandFailed, probe_git, run_git
+
+#: Sources outside this package: an analyzer it ran, or a file the
+#: developer's own pipeline wrote (Decision 17). Built-ins are not here.
+EXTERNAL_TIERS = ("analyzer", "pipeline")
 
 
 @dataclass(frozen=True)
@@ -152,7 +158,7 @@ class Analysis:
         """
         covered: dict[str, set[str]] = {name: set() for name in self.languages}
         for item in self.coverage:
-            if not item.contributed or item.tier != "analyzer":
+            if not item.contributed or item.tier not in EXTERNAL_TIERS:
                 continue
             concerns = self._concerns_of(item.concepts)
             for name, slug in self.languages.items():
@@ -217,7 +223,7 @@ class Analysis:
             if name in self.scored_languages
         ]
         if not scored:
-            return self._concerns_from("analyzer")
+            return self._concerns_from("analyzer") | self._concerns_from("pipeline")
         return set.intersection(*scored)
 
     def single_source_concerns(self) -> list[str]:
@@ -352,6 +358,43 @@ def analyze(root: Path, config: dict[str, Any], probe: Probe | None = None) -> A
     return analysis
 
 
+class RepositoryModifiedError(Exception):
+    """An analyzer changed the repository it was auditing.
+
+    The audit never edits source. A tool that writes to the audited tree
+    (ruff honouring a repository's `fix = true` rewrote 102 files of
+    an audited repository on 2026-10-14) fails the audit loudly rather than handing back
+    a grade for code that is no longer what was audited.
+    """
+
+
+def _tracked_state(root: Path) -> dict[str, str] | None:
+    """Each tracked file that differs from HEAD, by a hash of its diff.
+
+    None when `root` is not a git work tree: there is nothing to compare
+    against, so nothing is claimed.
+    """
+    if not probe_git(["rev-parse", "--is-inside-work-tree"], root):
+        return None
+    try:
+        diff = run_git(["diff", "HEAD", "--no-ext-diff", "--binary"], root, strip=False)
+    except GitCommandFailed:
+        return None
+    state: dict[str, str] = {}
+    for block in diff.split("\ndiff --git "):
+        if not block.strip():
+            continue
+        header = block.split("\n", 1)[0].removeprefix("diff --git ")
+        name = header.split(" b/", 1)[-1]
+        state[name] = hashlib.sha256(block.encode("utf-8", "replace")).hexdigest()
+    return state
+
+
+def _changed_paths(before: dict[str, str], after: dict[str, str]) -> list[str]:
+    return sorted(path for path in set(before) | set(after)
+                  if before.get(path) != after.get(path))
+
+
 def _run_one(root: Path, adapter: Any, probe: Probe, timeout: int,
              analysis: Analysis, excludes: Sequence[str] = (),
              inventory: Any = None) -> ToolCoverage:
@@ -367,6 +410,9 @@ def _run_one(root: Path, adapter: Any, probe: Probe, timeout: int,
     """
     try:
         return _attempt(root, adapter, probe, timeout, analysis, excludes, inventory)
+    except RepositoryModifiedError:
+        # Not an adapter defect to record quietly: the audited tree changed.
+        raise
     except Exception as error:  # noqa: BLE001 - the backstop is the point
         return ToolCoverage(
             slug=adapter.slug, outcome="failed", concepts=tuple(adapter.concepts),
@@ -490,12 +536,19 @@ def _run_batches(adapter: Any, root: Path, excludes: Sequence[str],
     invocations = planned(root, excludes) if planned else [adapter.invocation(root, excludes=excludes)]
     results: list[ToolResult] = []
     parsed: list[Extraction] = []
+    before = _tracked_state(root)
     for invocation in invocations:
         result = run(adapter.slug, invocation, timeout_seconds=timeout)
         results.append(result)
         parsed.append(adapter.parse(result))
         if not result.usable:
             break
+    after = _tracked_state(root) if before is not None else None
+    if before is not None and after is not None and after != before:
+        changed = _changed_paths(before, after)
+        raise RepositoryModifiedError(
+            f"{adapter.slug} modified the audited repository: {', '.join(changed)}. "
+            "The audit never edits source; restore these files and report the adapter.")
     if len(results) == 1:
         return results[0], parsed[0]
     return _merged_result(results, len(invocations)), _merged_extraction(parsed)

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_analyzer_sections.py

@@ -12,7 +12,7 @@ from pathlib import Path
 from typing import Any
 
 from ._analysis import analyze
-from ._criteria_scope import built_in_readings
+from ._criteria_scope import built_in_readings, reported_not_scored
 from ._documents import (
     coverage_document,
     findings_document,
@@ -21,6 +21,7 @@ from ._documents import (
 )
 from ._environment import environment_work_order
 from ._metrics_types import FunctionMetric
+from ._pipeline_results import add_pipeline_results
 from ._pressures import (
     ExternalPressures,
     analyzer_pressures,
@@ -46,6 +47,9 @@ def analyzer_sections(
         return {"coverage": None, "findings": [], "measurements": {},
                 "pressures": None, "environment": []}
     analysis = analyze(root, config)
+    # Decision 17: the files the developer's own pipeline wrote, read
+    # beside what this run's analyzers produced.
+    add_pipeline_results(analysis, root, config)
     coverage = coverage_document(analysis)
     # P8: where the analyzer tier could not drive a dimension, say so on
     # the coverage document rather than leaving the built-in fallback to
@@ -58,6 +62,7 @@ def analyzer_sections(
     built_in = built_in_readings(function_metrics, prefix)
     coverage["dimensions_declined"] = list(
         declined_dimensions(analysis.measurements, False, built_in, prefix))
+    coverage["reported_not_scored"] = reported_not_scored(coverage)
     return {
         "coverage": coverage,
         # ADR 006 §2c: what did not run and what it would take, for the

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_catalog.py

@@ -166,9 +166,40 @@ def settings_from(config: dict[str, Any]) -> dict[str, Any]:
     if unknown:
         raise PolicyError(f"unknown concerns {sorted(unknown)}; expected from {list(CONCERNS)}")
     settings["timeout_seconds"] = _bounded_timeout(settings["timeout_seconds"])
+    settings["pipeline_results"] = _pipeline_results(settings.get("pipeline_results"))
     return settings
 
 
+def pipeline_results_from_answer(answer: str) -> list[dict[str, Any]]:
+    """The first-run answer, `path: concern, concern; path: concern`, as declarations."""
+    entries = []
+    for part in (answer or "").split(";"):
+        if not part.strip():
+            continue
+        path, _, covers = part.partition(":")
+        entries.append({"path": path.strip(),
+                        "covers": [c.strip() for c in covers.split(",") if c.strip()]})
+    return _pipeline_results(entries)
+
+
+def _pipeline_results(declared: Any) -> list[dict[str, Any]]:
+    """Each file the developer's pipeline writes, and what it covers (Decision 17).
+
+    Refused rather than skipped: a declaration that silently examined
+    nothing would leave a concern unexamined with the operator believing
+    it covered.
+    """
+    entries = list(declared or [])
+    for entry in entries:
+        if not isinstance(entry, dict) or not isinstance(entry.get("path"), str) or not entry["path"]:
+            raise PolicyError(f"analyzers.pipeline_results entry {entry!r} needs a `path`")
+        covers = entry.get("covers")
+        if not covers or not isinstance(covers, list) or set(covers) - set(CONCERNS):
+            raise PolicyError(
+                f"analyzers.pipeline_results {entry['path']!r} needs `covers` from {list(CONCERNS)}")
+    return entries
+
+
 #: The widest per-analyzer wall clock a configured value may ask for. An
 #: hour is far past any real analyzer on any real tree and still bounds
 #: the host against a repository config that names a number designed

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_coverage_notes.py

@@ -48,6 +48,17 @@ def coverage_notes(coverage: dict[str, Any]) -> list[str]:
             "",
         ])
 
+    for unused in coverage.get("reported_not_scored") or []:
+        # The count sits in the findings beside a grade computed from
+        # something else; without this a reader takes it as ignored.
+        lines.extend([
+            f"**`{unused['tool']}` reported {unused['findings']} `{unused['concept']}` "
+            f"findings; they are listed and their count does not move the grade:** the "
+            f"`{unused['dimension']}` dimension is scored from the built-in "
+            "detectors only.",
+            "",
+        ])
+
     unexamined = coverage["concepts_unexamined"]
     if unexamined:
         # The point of the whole section. Silence about a concern is not
@@ -56,7 +67,8 @@ def coverage_notes(coverage: dict[str, Any]) -> list[str]:
             "**Nothing examined:** " + ", ".join(f"`{c}`" for c in unexamined) + ".",
             "",
             "These concerns are unmeasured, not clean. Install a tool that covers them, "
-            "or widen `analyzers.depth`, to have them reported.",
+            "widen `analyzers.depth`, or declare the SARIF your own build or pipeline "
+            "already writes in `analyzers.pipeline_results` to have them reported.",
             "",
         ])
 

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_criteria_scope.py

@@ -40,6 +40,29 @@ DECLARATION_CRITERIA: tuple[tuple[str, str, str], ...] = (
 # `risk` and `gates` are configured policy with no external equivalent.
 ANALYZER_DIMENSIONS: tuple[str, ...] = ("declarations",)
 
+# Concepts an analyzer can report whose dimension is scored from the
+# built-in detectors only. Their findings are listed, never scored.
+BUILT_IN_SCORED_CONCEPTS: dict[str, str] = {"duplication": "duplication", "file_lines": "file_size"}
+
+
+def reported_not_scored(coverage: dict) -> list[dict]:
+    """Analyzer findings listed in the report that do not move the grade.
+
+    A field report on a C# repository read jscpd's 439 duplicate blocks,
+    listed beside a duplication grade computed from the built-in detector,
+    as the analyzer's output being ignored. The design was right and the
+    page did not say it (P8).
+    """
+    return [
+        {"tool": entry["tool"], "concept": concept,
+         "dimension": BUILT_IN_SCORED_CONCEPTS[concept], "findings": entry["findings"]}
+        for entry in (coverage.get("by_outcome") or {}).get("ran", [])
+        if entry.get("tier") == "analyzer" and entry.get("findings")
+        for concept in entry.get("concepts", [])
+        if concept in BUILT_IN_SCORED_CONCEPTS
+        and BUILT_IN_SCORED_CONCEPTS[concept] not in ANALYZER_DIMENSIONS
+    ]
+
 
 def declaration_concepts_missing(covered: set[str]) -> tuple[str, ...]:
     """Criteria the analyzers did not supply, in rubric order.

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_first_run.py

@@ -111,6 +111,7 @@ def maybe_prompt_first_run(root: Path, explicit_config: str | None) -> None:
             "Add the economic scenario (loaded labor rate per hour) beside "
             "the score? Skip leaves money out of reports. "
             "(include/skip) [skip]: ", ("include", "skip"), "skip"),
+        "pipeline_results": _ask_pipeline_results(),  # Decision 17
     }
     apply_answers(root, answers)
     print(f"Wrote {root / CONFIG_FILENAME}")
@@ -338,3 +339,27 @@ def _record_test_command(root: Path, config: dict, answer: str) -> None:
     if not answer:
         config["test_execution"] = {"requested": False}
     print(f"Wrote {target}")
+
+
+def _ask_pipeline_results() -> str:
+    """Whether the developer's own pipeline writes SARIF; the files are the
+    second stage, `maybe_prompt_pipeline_files` (Decision 17)."""
+    from ._mcp_setup import pipeline_results_question
+
+    return _ask(pipeline_results_question()["prompt"] + " (none/declare) [none]: ",
+                ("none", "declare"), "none")
+
+
+def maybe_prompt_pipeline_files(root: Path, config: dict) -> dict:
+    """The CLI half of the Decision 17 second stage: at a TTY, after `declare`.
+
+    Returns the configuration this run should use, so files declared at the
+    prompt are read by the audit that asked for them.
+    """
+    from ._mcp_setup import pipeline_files_pending, pipeline_files_questions
+    from ._setup_persist import _apply_pipeline_files
+
+    if not _stdin_is_a_tty() or not pipeline_files_pending(root):
+        return config
+    answer = input(pipeline_files_questions()[0]["prompt"] + " ").strip()
+    return _apply_pipeline_files(root, {"pipeline_files": answer})

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_mcp_refusals.py

@@ -18,6 +18,7 @@ D48.
 
 from __future__ import annotations
 
+from ._analysis import RepositoryModifiedError
 from ._catalog import PolicyError
 from ._mcp_audit import InvalidAuditArgument, PathNotAllowed
 from ._mcp_setup import SetupRequired
@@ -37,6 +38,11 @@ ANTICIPATED_REFUSALS = (
     # type and `PathNotAllowed` both derive from it alongside the
     # internal ones that must stay crashes.
     ConfigUnreadable,
+    # An analyzer changed the audited repository. The message names the
+    # changed files and says to report the adapter: actionable, and a
+    # grade must never be returned for code that is no longer what was
+    # audited.
+    RepositoryModifiedError,
 )
 
 __all__ = ["ANTICIPATED_REFUSALS"]

{maintainability_agent-4.3.1 → maintainability_agent-4.4.1}/src/maintainability_audit/_mcp_setup.py

@@ -28,13 +28,14 @@ from __future__ import annotations
 from pathlib import Path
 from typing import Any
 
-from ._catalog import LICENSE_POLICIES, PRESENTATIONS
+from ._catalog import CONCERNS, LICENSE_POLICIES, PRESENTATIONS
 from ._setup_errors import SetupRequired as SetupRequired
 from ._setup_persist import (
     BOUNDS,
     _accepted,
     _apply_bounds,
     _apply_command,
+    _apply_pipeline_files,
     _economics_block,
     _is_bounds_only,
     _is_command_only,
@@ -88,6 +89,7 @@ def setup_questions(config: dict[str, Any]) -> list[dict[str, Any]]:
         },
         *_economics_questions(),
         *run_tests_question(),
+        pipeline_results_question(),
         {
             "name": "default_format",
             "prompt": "Default report presentation for this user.",
@@ -112,6 +114,48 @@ def setup_questions(config: dict[str, Any]) -> list[dict[str, Any]]:
     ]
 
 
+def pipeline_results_question() -> dict[str, Any]:
+    """Whether the developer's own pipeline writes analyzer results (Decision 17).
+
+    A choice, like every first-stage question; the files are the second
+    stage, asked only on `declare`. This tool runs a pinned handful of the
+    catalog, and the rest are run where they already run and read here.
+    """
+    return {
+        "name": "pipeline_results",
+        "prompt": (
+            "Does your own build or pipeline already write analyzer results as "
+            "SARIF (Roslyn analyzers, Semgrep, CodeQL...)? Declare names the files "
+            "next; this reads them and never runs the tools."
+        ),
+        "options": ["none", "declare"],
+        "default": "none",
+    }
+
+
+def pipeline_files_questions() -> list[dict[str, Any]]:
+    """The files, asked only of someone who said `declare`."""
+    return [{
+        "name": "pipeline_files",
+        "prompt": (
+            "Each SARIF file and the concerns it covers, from "
+            + ", ".join(CONCERNS) + " — e.g. `artifacts/roslyn.sarif: style, "
+            "documentation, dead-code`; separate files with `;`. Paths are "
+            "relative to the repository. Blank cancels."
+        ),
+        "options": [],
+        "default": "",
+    }]
+
+
+def pipeline_files_pending(root: Path) -> bool:
+    """`declare` was answered and no file is declared yet."""
+    discovered = discovered_config(Path(root))
+    stored = _read_config(Path(discovered)) if discovered is not None else None
+    analyzers = (stored or {}).get("analyzers") or {}
+    return bool(analyzers.get("pipeline_requested")) and not analyzers.get("pipeline_results")
+
+
 def economics_bound_questions() -> list[dict[str, Any]]:
     """The three rates, asked only of someone who said yes to the gate."""
     return [
@@ -179,6 +223,8 @@ def published_questions(root: Path | None = None) -> dict[str, dict[str, Any]]:
         questions[question["name"]] = question
     for question in test_command_questions(root):
         questions[question["name"]] = question
+    for question in pipeline_files_questions():
+        questions[question["name"]] = question
     return questions
 
 
@@ -248,6 +294,7 @@ def submittable_answer_names() -> frozenset[str]:
     names = {question["name"] for question in setup_questions({})}
     names.update(name for name, _, _ in BOUNDS)
     names.add("test_command")
+    names.add("pipeline_files")
     return frozenset(names)
 
 
@@ -258,6 +305,8 @@ def apply_answers(root: Path, answers: dict[str, Any]) -> dict[str, Any]:
         return _apply_bounds(root, answers)
     if _is_command_only(answers):
         return _apply_command(root, answers)
+    if set(k for k, v in answers.items() if v is not None) == {"pipeline_files"}:
+        return _apply_pipeline_files(root, answers)
     payload: dict[str, Any] = {
         "version": 1,
         "analyzers": {
@@ -272,6 +321,8 @@ def apply_answers(root: Path, answers: dict[str, Any]) -> dict[str, Any]:
         # suite; the command is a staged second ask.
         "test_execution": {"requested": _accepted(answers.get("run_tests", "no"))},
     }
+    if answers.get("pipeline_results") == "declare":
+        payload["analyzers"]["pipeline_requested"] = True
     economics = _economics_block(answers)
     if economics is not None:
         payload["economic_context"] = economics
@@ -406,7 +457,8 @@ def setup_pending(root: Path) -> bool:
         # rates for someone who wanted the scenario, or the test command for
         # someone who opted to run the suite. Both are stage two of an ask
         # already begun, not a new one.
-        return economics_bounds_pending(root) or test_command_pending(root)
+        return (economics_bounds_pending(root) or test_command_pending(root)
+                or pipeline_files_pending(root))
     # No repository file: the person's answers carry to it (first-run.md),
     # and it is asked only what is its own — its test command (Decision 4).
     return user_config_answers() is None or test_command_pending(root)
@@ -465,6 +517,8 @@ def staged_questions(root: Path | None = None) -> list[dict[str, Any]]:
         return economics_bound_questions()
     if root is not None and test_command_pending(root):
         return test_command_questions(root)
+    if root is not None and pipeline_files_pending(root):
+        return pipeline_files_questions()
     return setup_questions(load_config(None))