maintainability-agent 3.7.1__tar.gz → 3.7.4__tar.gz

{maintainability_agent-3.7.1/src/maintainability_agent.egg-info → maintainability_agent-3.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.7.1
+Version: 3.7.4
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -19,7 +19,6 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: secure-code-agent<0.11,>=0.10
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
@@ -47,7 +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.7.1**.
+Version **3.7.4**.
 
 **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
@@ -81,6 +80,18 @@ 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.
 
+**Install secure-code-agent for the security pillar.** Every audit runs it; it is
+installed alongside rather than as a dependency, so the two tools release
+independently. Without it the report says the security pillar was not measured
+and gives this command. Its scanners decide what it can grade — see
+[machine setup](docs/machine-setup.md#4-toolchain) for which to install, and
+don't add its `[mcp]` extra to this environment (it pins `mcp<2`).
+
+```bash
+pip install 'secure-code-agent>=0.12.1'
+brew install gitleaks osv-scanner semgrep checkov   # its scanners; pip install bandit
+```
+
 **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:
 

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/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.7.1**.
+Version **3.7.4**.
 
 **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
@@ -39,6 +39,18 @@ 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.
 
+**Install secure-code-agent for the security pillar.** Every audit runs it; it is
+installed alongside rather than as a dependency, so the two tools release
+independently. Without it the report says the security pillar was not measured
+and gives this command. Its scanners decide what it can grade — see
+[machine setup](docs/machine-setup.md#4-toolchain) for which to install, and
+don't add its `[mcp]` extra to this environment (it pins `mcp<2`).
+
+```bash
+pip install 'secure-code-agent>=0.12.1'
+brew install gitleaks osv-scanner semgrep checkov   # its scanners; pip install bandit
+```
+
 **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:
 

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "maintainability-agent"
-version = "3.7.1"
+version = "3.7.4"
 description = "Maintainability gate and AI remediation prompt generator for CI."
 readme = "README.md"
 # 3.11, not 3.10. `_discovery`, `_pillars` and `_runner` all import
@@ -13,14 +13,6 @@ readme = "README.md"
 # metadata said a user could stand: the suite runs 3.12 and the
 # composite action pins 3.11 (D42).
 requires-python = ">=3.11"
-# The security pillar is complete (D177): every audit runs secure-code-agent,
-# so it installs with this package rather than being left to the operator.
-# Its own dependency is PyYAML; this package still imports no YAML
-# (`test_the_shipped_package_does_not_import_yaml`) — it runs the tool as a
-# child and reads the JSON document it writes.
-dependencies = [
-  "secure-code-agent>=0.10,<0.11",
-]
 license = { text = "MIT" }
 authors = [
   { name = "Marshall Guillory" }

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4/src/maintainability_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 3.7.1
+Version: 3.7.4
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -19,7 +19,6 @@ Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: secure-code-agent<0.11,>=0.10
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
@@ -47,7 +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.7.1**.
+Version **3.7.4**.
 
 **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
@@ -81,6 +80,18 @@ 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.
 
+**Install secure-code-agent for the security pillar.** Every audit runs it; it is
+installed alongside rather than as a dependency, so the two tools release
+independently. Without it the report says the security pillar was not measured
+and gives this command. Its scanners decide what it can grade — see
+[machine setup](docs/machine-setup.md#4-toolchain) for which to install, and
+don't add its `[mcp]` extra to this environment (it pins `mcp<2`).
+
+```bash
+pip install 'secure-code-agent>=0.12.1'
+brew install gitleaks osv-scanner semgrep checkov   # its scanners; pip install bandit
+```
+
 **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:
 

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -95,6 +95,7 @@ src/maintainability_audit/_scan_history.py
 src/maintainability_audit/_scan_view.py
 src/maintainability_audit/_second_source.py
 src/maintainability_audit/_security_delegate.py
+src/maintainability_audit/_security_work_order.py
 src/maintainability_audit/_selection.py
 src/maintainability_audit/_semantic.py
 src/maintainability_audit/_semantic_policy.py
@@ -342,7 +343,10 @@ tests/test_scanning.py
 tests/test_schema_fidelity.py
 tests/test_scope_conformance.py
 tests/test_scoring_calibration.py
+tests/test_security_delegate_versions_agree.py
+tests/test_security_findings_keep_their_handoff.py
 tests/test_security_pillar_runs_and_shows.py
+tests/test_semantic_findings_stay_inside_the_audited_files.py
 tests/test_semantic_policy.py
 tests/test_setup_gate_completeness.py
 tests/test_setup_gate_independent_contract.py
@@ -375,6 +379,7 @@ tests/test_verification_audit_closures.py
 tests/test_verified_grade.py
 tests/test_version_claim.py
 tests/test_wheel_contents.py
+tests/test_withheld_work_keeps_its_boundary.py
 tests/test_work_items_state_their_own_finding.py
 tests/test_work_order.py
 tests/test_work_order_binds_to_this_interpreter.py

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_agent.egg-info/requires.txt

@@ -1,4 +1,3 @@
-secure-code-agent<0.11,>=0.10
 
 [dev]
 pytest>=8

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "3.7.1"
+__version__ = "3.7.4"

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_html_view.py

@@ -26,7 +26,9 @@ from . import _charts
 from . import _evidence_view as view
 from ._grammar import agreement
 from ._html_report_sections import coverage_section, remaining_sections, trend_section
+from ._security_work_order import complete_html as security_work_order_html
 from ._semantic_view import semantic_class_label
+from ._work_order import escalated_fingerprints
 from ._work_order_view import prompt_body_lines
 
 _SEVERITY_BY_RISK = {5: "Severe", 4: "High", 3: "Medium"}
@@ -82,6 +84,7 @@ def render_html(report: dict[str, Any], records: list[Any]) -> str:
         *trend_section(report),
         *remaining_sections(report),
         *_work_order_section(report),
+        *security_work_order_html(report),
         *_hard_gate_section(report),
         *_unidentified_paths_section(report),
         *_semantic_section(report),
@@ -290,10 +293,12 @@ def _work_order_section(report: dict[str, Any]) -> list[str]:
     rows.extend([
         "<h3>Copy-paste prompts</h3>",
         "<p>One self-contained prompt per item — copy any block into a coding "
-        "agent.</p>",
+        "agent. A block for an item that needs a design decision asks for that "
+        "decision, not a patch.</p>",
     ])
+    escalated = escalated_fingerprints(report)
     for item in items:
-        body = "\n".join(prompt_body_lines(item, root_label))
+        body = "\n".join(prompt_body_lines(item, root_label, escalated))
         rows.append(f"<h4>{escape(str(item.get('title') or ''))}</h4>")
         rows.append(f"<pre>{escape(body)}</pre>")
     return rows

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_mcp_audit.py

@@ -37,6 +37,7 @@ from ._scan_history import (
     record_of,
     segments,
 )
+from ._security_work_order import KEY as SECURITY_WORK_ORDER
 from ._stored_grants import (
     StaleStandingGrant,
     refuse_a_stale_standing_grant,
@@ -301,6 +302,11 @@ def _top_level_result(report: dict[str, Any], root: Path, status: str,
     # travels only for json, so the remedy cannot live only inside it.
     if report.get("environment_work_order"):
         result["environment_work_order"] = report["environment_work_order"]
+    # D179, on the same reasoning: the bounded chat view has no room for
+    # secure-code-agent's whole work order, and the report dict travels only
+    # for json, so it rides every format at the top level.
+    if report.get(SECURITY_WORK_ORDER):
+        result[SECURITY_WORK_ORDER] = report[SECURITY_WORK_ORDER]
     if include_prompt:
         result["remediation_prompt"] = render_ai_prompt(report)
     return result

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_prompt_sections.py

@@ -24,8 +24,10 @@ from typing import Any
 
 from . import _evidence_view as view
 from ._hotspots import hotspot_measure, hotspot_name
+from ._security_work_order import KEY as SECURITY_WORK_ORDER
+from ._security_work_order import severity_counts
 from ._tdd_view import tdd_sentences
-from ._work_order import prompt_items
+from ._work_order import escalated_fingerprints, prompt_items
 
 
 def prompt_tdd_section(report: dict[str, Any]) -> list[str]:
@@ -134,10 +136,18 @@ def prompt_security_pillar(report: dict[str, Any]) -> list[str]:
     producer = entry.get("delegated_to") or "the delegated tool"
     version = f" {entry['producer_version']}" if entry.get("producer_version") else ""
     condition = "not graded" if entry.get("condition") is None else f"{entry['condition']:.1f}"
+    counts = severity_counts(entry)
+    found = f" Findings: {counts}." if counts else ""
+    # Where that tool's work order is, when this run kept it (D179). The
+    # prompt names it rather than absorbing it: the security findings are
+    # not this prompt's task, and are not re-ranked into it.
+    where = (f" Its own work order for them is `{SECURITY_WORK_ORDER}`, in the report."
+             if report.get(SECURITY_WORK_ORDER) else "")
     return [
         f"**Security pillar (measured by {producer}{version}):** posture "
         f"{entry.get('posture')}, practice level {entry.get('practice')}, condition "
-        f"{condition}. Its findings are that tool's work order, not this one.",
+        f"{condition}.{found} Its findings are that tool's work order, not this "
+        f"one.{where}",
         "",
     ]
 
@@ -188,10 +198,7 @@ def _prompt_work_items(report: dict[str, Any]) -> list[dict[str, Any]]:
     # Withhold anything the history shows was fixed and came back
     # twice. Naming it as a design candidate while asking an agent to
     # patch it a third time would change nothing.
-    escalated = {
-        item["fingerprint"] for item in report.get("design_review_candidates") or []
-    }
-    return prompt_items(report.get("work_order") or [], escalated=escalated)
+    return prompt_items(report.get("work_order") or [], escalated=escalated_fingerprints(report))
 
 
 def prompt_has_work(report: dict[str, Any]) -> bool:

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_scan_view.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 from typing import Any
 
 from ._coverage_notes import coverage_notes
+from ._security_work_order import severity_counts
 
 
 def _by_language_rows(coverage: dict[str, Any]) -> list[str]:
@@ -364,15 +365,20 @@ def pillar_cells(entry: dict[str, Any]) -> tuple[str, str]:
     condition = "—" if entry["condition"] is None else f"{entry['condition']:.1f}"
     if entry["posture"] is None:
         return condition, "not measured — see below"
+    # What the producer found, in both states: an ungraded pillar still
+    # counted its findings, and printing only why no grade was issued hid
+    # five critical ones behind "scanner coverage is partial" (D179).
+    counts = severity_counts(entry)
+    found = f"; findings: {counts}" if counts else ""
     if entry["condition"] is None:
         # An ungraded pillar is `unverified` because nothing could be graded,
         # not because a clean scan lacks enforcement — the note for that cell
         # told a reader of secure-code-agent's partial-coverage pillar that
         # its scan was clean (D176). Say why no grade was issued instead.
         why = (entry.get("evidence_reasons") or [None])[0] or "the evidence could not support a grade"
-        return condition, f"{entry['posture']}: not graded — {why}"
+        return condition, f"{entry['posture']}: not graded — {why}{found}"
     note = POSTURE_NOTE.get(entry["posture"], entry["posture"])
-    return condition, f"{entry['posture']}: {note}"
+    return condition, f"{entry['posture']}: {note}{found}"
 
 
 def _pillar_row(entry: dict[str, Any]) -> str:

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_security_delegate.py

@@ -11,7 +11,8 @@ Marshall: the pillar is complete, so the audit runs it.
 **What the child writes.** Every report `secure-code-agent` can produce is
 redirected into a temporary directory this process owns: the Markdown and
 JSON reports, SARIF, the PR comment, the remediation prompt and the pillar
-document itself. The one write that cannot be redirected is its append-only
+document itself. The pillar document and the remediation prompt — that
+tool's work order — are read back before the directory goes (D179). The one write that cannot be redirected is its append-only
 trend, `.secure-code/history.jsonl` in the audited tree, which it writes on
 every run from its own configuration. Turning that off would mean handing
 it a configuration from outside the tree, and `secure-code-agent` trusts an
@@ -44,8 +45,19 @@ from typing import Any
 from ._delegated_pillar import read_produced
 from ._runner import Invocation, Outcome, run
 
-#: The distribution the pillar requires, and the range this tool reads.
-REQUIREMENT = "secure-code-agent>=0.10,<0.11"
+#: The releases this audit runs, and the install command's requirement.
+#:
+#: **Not a package dependency.** 3.7.0 made it one, and within the day it
+#: capped the tool below its current release — installing this package
+#: downgraded a machine's secure-code-agent — and put the two tools' opposed
+#: `mcp` pins into one environment. secure-code-agent's D3 and this project's
+#: ADR 008 both hold the tools independently releasable. So the audit runs
+#: whichever release is installed, when it falls in this range, and says so
+#: when it does not. The ceiling is the next major: within 0.x the pillar
+#: document is versioned by its own `schema_version`, which the reader checks.
+SUPPORTED_FLOOR = (0, 12, 1)
+SUPPORTED_CEILING = (1,)
+REQUIREMENT = "secure-code-agent>=0.12.1,<1"
 
 #: How long the child may run before the pillar is reported as unmeasured.
 DEFAULT_TIMEOUT_SECONDS = 300
@@ -60,6 +72,9 @@ class DelegateRun:
     document: dict[str, Any] | None
     reason: str | None = None
     environment: list[dict[str, str]] = field(default_factory=list)
+    #: The delegate's own remediation prompt — its work order — read before
+    #: the directory it was written into is deleted (D179).
+    work_order: str | None = None
 
 
 def _install_remedy(reason: str) -> dict[str, str]:
@@ -82,6 +97,12 @@ def run_security_delegate(
     if importlib.util.find_spec("secure_code_audit") is None:
         reason = "secure-code-agent is not installed for the interpreter running this audit"
         return DelegateRun(None, reason, [_install_remedy(reason)])
+    installed = _installed_version()
+    if installed is None or not (SUPPORTED_FLOOR <= installed < SUPPORTED_CEILING):
+        shown = ".".join(map(str, installed)) if installed else "an unreadable version"
+        reason = (f"secure-code-agent {shown} is installed; this audit runs "
+                  f"{REQUIREMENT.removeprefix('secure-code-agent')}")
+        return DelegateRun(None, reason, [_install_remedy(reason)])
     with tempfile.TemporaryDirectory(prefix="ma-security-") as scratch:
         out = Path(scratch)
         pillar = out / "security-pillar.json"
@@ -103,7 +124,7 @@ def run_security_delegate(
         ), timeout_seconds=timeout_seconds)
         document = read_produced(pillar)
         if document is not None:
-            return DelegateRun(document)
+            return DelegateRun(document, work_order=_read_text(out / "prompt.md"))
         if result.outcome is Outcome.TIMED_OUT:
             return DelegateRun(None, f"secure-code-agent did not finish within {timeout_seconds}s")
         detail = _last_line(result.stderr) or _last_line(result.stdout) or result.detail
@@ -116,6 +137,38 @@ def run_security_delegate(
         return DelegateRun(None, reason)
 
 
+def _installed_version() -> tuple[int, ...] | None:
+    """The installed release as integers, or `None` when it cannot be read.
+
+    No `packaging` import: this package has no runtime dependencies. A
+    pre-release or local suffix is cut at the first non-numeric part, which
+    compares a `0.13.0rc1` as `0.13.0` — conservative at the ceiling.
+    """
+    import importlib.metadata as metadata
+    import re
+
+    try:
+        text = metadata.version("secure-code-agent")
+    except metadata.PackageNotFoundError:
+        return None
+    parts = []
+    for piece in text.split("."):
+        match = re.match(r"\d+", piece)
+        if not match:
+            break
+        parts.append(int(match.group()))
+        if match.group() != piece:
+            break
+    return tuple(parts) or None
+
+
+def _read_text(path: Path) -> str | None:
+    try:
+        return path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
 def _last_line(text: str | None) -> str:
     lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
     return lines[-1][:200] if lines else ""

maintainability_agent-3.7.4/src/maintainability_audit/_security_work_order.py

@@ -0,0 +1,120 @@
+"""What secure-code-agent found, and its own work order for it (D179).
+
+3.7.0 made every audit run secure-code-agent (D177), and then kept one
+thing from that run: the pillar document. An audit of this repository
+recorded five critical findings and one high, and every skin printed
+"unverified: not graded — scanner coverage is partial" with no count. The
+remediation prompt secure-code-agent had written — 74 findings to fix, 5 to
+review, each located and constrained — sat in a temporary directory that
+was deleted before the report was built. The run measured the work and the
+reader was handed neither its size nor its instructions.
+
+**Two things, each where it is read.** The severity counts come from the
+pillar document and appear wherever the pillar does. The work order is
+secure-code-agent's own text, carried unchanged under `security_work_order`
+and printed whole in the complete reports. It stays that tool's work order,
+not this one's: this tool does not re-rank, merge or reword security
+findings (ADR 007 §1), so the maintainability prompt names it and does not
+absorb it.
+"""
+from __future__ import annotations
+
+from html import escape
+from typing import Any
+
+#: The report key, and the chat door's top-level key, that carries it.
+KEY = "security_work_order"
+
+_ORDER = ("critical", "high", "medium", "low", "informational")
+
+
+def severity_counts(entry: dict[str, Any]) -> str | None:
+    """`5 critical, 1 high, …` from a measured pillar, or `None` when it carries none.
+
+    A pillar document with an empty count reads "no findings": that is the
+    producer's statement, and it is different from a pillar with no count at
+    all, which says nothing and is printed as nothing.
+    """
+    counts = entry.get("findings_by_severity")
+    if not isinstance(counts, dict):
+        return None
+    named = [name for name in _ORDER if counts.get(name)]
+    named += sorted(name for name in counts if name not in _ORDER and counts[name])
+    if not named:
+        return "no findings"
+    return ", ".join(f"{counts[name]} {name}" for name in named)
+
+
+def carried(markdown: str | None, entry: dict[str, Any]) -> dict[str, Any] | None:
+    """The report entry for a work order the delegate wrote, or `None`."""
+    if not markdown or not markdown.strip():
+        return None
+    return {
+        "producer": entry.get("delegated_to"),
+        "producer_version": entry.get("producer_version"),
+        "markdown": markdown,
+    }
+
+
+def _source(work_order: dict[str, Any]) -> str:
+    version = f" {work_order['producer_version']}" if work_order.get("producer_version") else ""
+    return f"{work_order.get('producer') or 'the delegated tool'}{version}"
+
+
+def pointer_markdown(report: dict[str, Any]) -> list[str]:
+    """The bounded view's line: the work order exists, and where it is."""
+    work_order = report.get(KEY)
+    if not work_order:
+        return []
+    return [
+        f"**Security work order.** {_source(work_order)} wrote its own work order "
+        f"for these findings. It is carried whole as `{KEY}` and printed in the "
+        "complete Markdown and HTML reports.",
+        "",
+    ]
+
+
+def _demoted(markdown: str) -> list[str]:
+    """The delegate's headings two levels down, so they nest under this report's.
+
+    Lines inside a fence are left alone: a `#` there is a comment in a quoted
+    snippet, not a heading.
+    """
+    lines = []
+    fenced = False
+    for line in markdown.rstrip("\n").splitlines():
+        if line.lstrip().startswith("```"):
+            fenced = not fenced
+        elif not fenced and line.startswith("#"):
+            line = "##" + line
+        lines.append(line)
+    return lines
+
+
+def _intro(work_order: dict[str, Any]) -> str:
+    return (
+        f"Written by {_source(work_order)} and reproduced as it wrote it. It is "
+        "that tool's work order, not this one's: its findings are not re-ranked "
+        "or merged into the maintainability work order above."
+    )
+
+
+def complete_markdown(report: dict[str, Any]) -> list[str]:
+    """The complete report's section: the delegate's work order, whole."""
+    work_order = report.get(KEY)
+    if not work_order:
+        return []
+    return ["## Security Work Order", "", _intro(work_order), "",
+            *_demoted(work_order["markdown"]), ""]
+
+
+def complete_html(report: dict[str, Any]) -> list[str]:
+    """The HTML report's section: the same text, preformatted."""
+    work_order = report.get(KEY)
+    if not work_order:
+        return []
+    return [
+        "<h2>Security Work Order</h2>",
+        f"<p>{escape(_intro(work_order))}</p>",
+        f"<pre>{escape(work_order['markdown'])}</pre>",
+    ]

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_work_order.py

@@ -479,6 +479,29 @@ def combined_delta(report: dict[str, Any], items: list[dict[str, Any]]) -> float
     return round(max(0.0, (after or before) - before), 3)
 
 
+def escalated_fingerprints(report: dict[str, Any]) -> set[str]:
+    """The findings history shows were fixed and came back, as fingerprints."""
+    return {item["fingerprint"] for item in report.get("design_review_candidates") or []}
+
+
+def withheld_reason(item: dict[str, Any], escalated: set[str] | None = None) -> str | None:
+    """Why no agent is handed this item as a patch, or `None` when one is (D180).
+
+    The one rule the bounded prompt and every copy-paste block read. The
+    prompt withheld the demo's two duplicated blocks as needing a design
+    decision while the report's standalone block for each said "Task: remove
+    the duplicated block" — the same run authorising and forbidding the same
+    change, depending on which text was pasted.
+    """
+    if item["band"] == Band.MAJOR_PROJECT.value:
+        return ("it is a Major Project — the change it needs is a design "
+                "decision before code moves, not one reviewable patch")
+    if item.get("fingerprint") in (escalated or set()):
+        return ("it was fixed before and came back, so the same edit is known "
+                "not to hold and the surrounding design needs a decision")
+    return None
+
+
 def prompt_items(items: list[dict[str, Any]], limit: int = 12,
                  escalated: set[str] | None = None) -> list[dict[str, Any]]:
     """Agent subset: no major projects, no escalated returns; Severe leads.
@@ -487,12 +510,7 @@ def prompt_items(items: list[dict[str, Any]], limit: int = 12,
     so a risk-5 item can still sit below hotter Quick Wins of other classes.
     The table can stay exposure-ordered; the paste of 12 cannot drop Severe.
     """
-    blocked = escalated or set()
-    eligible = [
-        item for item in items
-        if item["band"] != Band.MAJOR_PROJECT.value
-        and item.get("fingerprint") not in blocked
-    ]
+    eligible = [item for item in items if withheld_reason(item, escalated) is None]
     severe = [item for item in eligible if item.get("risk") == 5]
     rest = [item for item in eligible if item.get("risk") != 5]
     return _one_per_class(severe + rest)[:limit]

{maintainability_agent-3.7.1 → maintainability_agent-3.7.4}/src/maintainability_audit/_work_order_view.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from ._work_order import work_order_rows
+from ._work_order import withheld_reason, work_order_rows
 from ._work_order_weights import AUDIT_VERIFICATION
 
 # The report lists the whole backlog; these caps apply only to the bounded
@@ -40,7 +40,9 @@ def item_location(item: dict[str, Any]) -> str:
     return item["path"] + (f":{item['line']}" if item.get("line") else "")
 
 
-def prompt_body_lines(item: dict[str, Any], root_label: str = ".") -> list[str]:
+def prompt_body_lines(
+    item: dict[str, Any], root_label: str = ".", escalated: set[str] | None = None,
+) -> list[str]:
     """The copy-paste prompt text for one item, skin-agnostic.
 
     Deterministic: built entirely from the item's own fields, so the same
@@ -48,7 +50,26 @@ def prompt_body_lines(item: dict[str, Any], root_label: str = ".") -> list[str]:
     Markdown fences it as ``text`` and HTML wraps it in ``<pre>``; the text
     between is identical, so the two skins can never disagree about what an
     agent is being asked to do.
+
+    **A block travels alone, so it carries its own boundary (D180).** An
+    item the bounded prompt withholds is still listed with a block — a
+    human deciding on a forty-file deduplication needs to see it — but the
+    block asks for the decision, never the patch.
     """
+    withheld = withheld_reason(item, escalated)
+    if withheld:
+        return [
+            f"Repository: {root_label}",
+            f"Design decision needed, not a patch: {item['title']}.",
+            f"Location: {item_location(item)}",
+            f"Why: {item['rationale']}",
+            f"Direction once decided: {item['target']}.",
+            "",
+            f"Do not change code for this item, because {withheld}. Lay out the "
+            "options for the surrounding design — what each would change, and "
+            "where — then stop for a human decision. If this is a false "
+            "positive, say so.",
+        ]
     verify = item.get("verification") or AUDIT_VERIFICATION
     return [
         f"Repository: {root_label}",
@@ -63,7 +84,9 @@ def prompt_body_lines(item: dict[str, Any], root_label: str = ".") -> list[str]:
     ]
 
 
-def item_prompt_block(item: dict[str, Any], root_label: str = ".") -> list[str]:
+def item_prompt_block(
+    item: dict[str, Any], root_label: str = ".", escalated: set[str] | None = None,
+) -> list[str]:
     """One item's copy-paste prompt as Markdown: heading, then a fenced block.
 
     Fenced as ``text`` so a reader copies the whole thing into a coding
@@ -76,7 +99,7 @@ def item_prompt_block(item: dict[str, Any], root_label: str = ".") -> list[str]:
         f"`{item_location(item)}` · {item['band']}",
         "",
         "```text",
-        *prompt_body_lines(item, root_label),
+        *prompt_body_lines(item, root_label, escalated),
         "```",
         "",
     ]
@@ -114,7 +137,7 @@ _BAND_IS_PER_CLASS = (
 
 def work_order_markdown(
     items: list[dict[str, Any]] | None, *, complete: bool = False, root_label: str = ".",
-    exposure_ordered: bool = False,
+    exposure_ordered: bool = False, escalated: set[str] | None = None,
 ) -> list[str]:
     """The ordered work, worth first, with a copy-paste prompt for each item.
 
@@ -149,10 +172,11 @@ def work_order_markdown(
     lines.extend([
         "### Copy-paste prompts", "",
         "One self-contained prompt per item — paste any block whole into a "
-        "coding agent.", "",
+        "coding agent. A block for an item that needs a design decision asks "
+        "for that decision, not a patch.", "",
     ])
     for item in items[:limit]:
-        lines.extend(item_prompt_block(item, root_label))
+        lines.extend(item_prompt_block(item, root_label, escalated))
     return lines