maintainability-agent 2.0.0__tar.gz → 2.1.0__tar.gz

{maintainability_agent-2.0.0/src/maintainability_agent.egg-info → maintainability_agent-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.0.0
+Version: 2.1.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,7 +44,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 **2.0.0**.
+Version **2.1.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Fortran (free-form *and*
 fixed-form), and the JS/TS family — each by a scanner written for it, and

{maintainability_agent-2.0.0 → maintainability_agent-2.1.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 **2.0.0**.
+Version **2.1.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Fortran (free-form *and*
 fixed-form), and the JS/TS family — each by a scanner written for it, and

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.0.0
+Version: 2.1.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -44,7 +44,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 **2.0.0**.
+Version **2.1.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Fortran (free-form *and*
 fixed-form), and the JS/TS family — each by a scanner written for it, and

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -20,6 +20,7 @@ src/maintainability_audit/_catalog.py
 src/maintainability_audit/_charts.py
 src/maintainability_audit/_cognitive.py
 src/maintainability_audit/_config_defaults.py
+src/maintainability_audit/_conformance.py
 src/maintainability_audit/_corroborate.py
 src/maintainability_audit/_coverage_notes.py
 src/maintainability_audit/_derive.py
@@ -121,6 +122,7 @@ tests/test_acquisition_trust.py
 tests/test_adapter_docs.py
 tests/test_adapter_recordings.py
 tests/test_adapters.py
+tests/test_added_lines.py
 tests/test_analysis_coverage.py
 tests/test_analysis_execution.py
 tests/test_analyzer_bridge.py
@@ -225,6 +227,7 @@ tests/test_identity_docs.py
 tests/test_identity_resolution.py
 tests/test_idiom_divergence.py
 tests/test_installed_wheel_runtime.py
+tests/test_instruction_targets.py
 tests/test_java_range_guard.py
 tests/test_java_ranges.py
 tests/test_java_scored.py
@@ -270,6 +273,7 @@ tests/test_scan_history.py
 tests/test_scan_scope.py
 tests/test_scanning.py
 tests/test_schema_fidelity.py
+tests/test_scope_conformance.py
 tests/test_scoring_calibration.py
 tests/test_semantic_policy.py
 tests/test_setup_gate_completeness.py

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"

maintainability_agent-2.1.0/src/maintainability_audit/_conformance.py

@@ -0,0 +1,183 @@
+"""Did the diff stay inside the work order it was given?
+
+The product's central claim is a bounded work order: *fix exactly these
+findings and refactor nothing else*. Until now that bound was an
+**instruction**. The prompt said it, and nothing checked it — so an agent
+that rewrote half the tree while closing one finding produced a diff
+indistinguishable, to this tool, from one that did as it was told.
+
+This is the check that makes the bound verifiable. It reads the finished
+report and a revspec, and reports which changed files the work order
+actually named. It is the first of the three mechanisms behind the
+attestation artifact, and the one a code-generating agent cannot honestly
+perform about itself.
+
+**What it must not do is cry wolf.** A correct remediation almost always
+touches a file the work order does not name: the test that proves the fix.
+A check that flagged every good remediation would be turned off within a
+week, so a test file is in scope when it pairs to a named path by the same
+convention `_test_pairing` already uses for coverage — `test_foo.py` pairs
+to `foo.py`. A test paired to nothing named is still reported, because
+"while I was here I rewrote the suite" is exactly the drift being watched
+for.
+
+Three deliberate limits:
+
+- **It never scores.** Whether a diff was obedient is a fact about an
+  agent's behaviour, not evidence about the code's condition, so nothing
+  here reaches scoring or moves a grade.
+- **It reports, it does not gate**, unless a caller asks it to. A finding
+  can legitimately require touching a caller the work order did not name,
+  and a check that cannot be argued with becomes a check that is bypassed.
+- **It compares paths, not intent.** A file being in scope says the work
+  order named it, not that the change to it was the right one. Review is
+  still review.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ._metrics_types import is_test_path
+from ._test_pairing import subject_stem
+
+
+def _named_paths(work_order: list[dict[str, Any]]) -> set[str]:
+    """Every path the work order put in front of the agent."""
+    return {
+        str(item["path"]) for item in work_order
+        if isinstance(item, dict) and item.get("path")
+    }
+
+
+def _pairs_to_named(path: str, named: set[str]) -> bool:
+    """Whether a test file covers something the work order named.
+
+    Uses the pairing convention the coverage aspect already applies, so a
+    remediation's own test is in scope without the caller declaring it —
+    and a test that covers nothing in the work order is not.
+    """
+    if not is_test_path(path):
+        return False
+    subject = subject_stem(path)
+    if not subject:
+        return False
+    return any(subject_stem(candidate) == subject for candidate in named)
+
+
+#: Markers that switch a checker off rather than satisfy it. Per language,
+#: because the vocabulary differs and a single regex over all of them
+#: matches prose: "# type: ignore" in a docstring explaining the convention
+#: is not a suppression, and neither is this comment.
+#:
+#: Deliberately narrow. A marker here has to be a real directive that a
+#: real tool obeys; guessing wider would report ordinary comments as
+#: evasion, and a check that cries wolf is a check that gets switched off —
+#: the same reasoning as the test-pairing rule above.
+SUPPRESSION_MARKERS: tuple[tuple[str, str], ...] = (
+    (r"#\s*noqa\b", "noqa"),
+    (r"#\s*type:\s*ignore\b", "type: ignore"),
+    (r"#\s*pragma:\s*no\s*cover\b", "pragma: no cover"),
+    (r"#\s*nosec\b", "nosec"),
+    (r"//\s*eslint-disable", "eslint-disable"),
+    (r"/\*\s*eslint-disable", "eslint-disable"),
+    (r"//\s*@ts-(ignore|expect-error)\b", "ts-ignore"),
+    (r"@SuppressWarnings\b", "SuppressWarnings"),
+    (r"//\s*NOSONAR\b", "NOSONAR"),
+    (r"#\s*pylint:\s*disable\b", "pylint: disable"),
+    (r"@pytest\.mark\.(skip|xfail)\b", "skipped test"),
+    (r"@unittest\.skip\b", "skipped test"),
+    (r"\bit\.skip\(|\bdescribe\.skip\(", "skipped test"),
+    (r"@Disabled\b", "disabled test"),
+    (r"@Ignore\b", "ignored test"),
+)
+
+_SUPPRESSION = tuple(
+    (re.compile(pattern, re.IGNORECASE), label) for pattern, label in SUPPRESSION_MARKERS
+)
+
+
+def suppressions_added(
+    added: dict[str, list[tuple[int, str]]], named: set[str]
+) -> list[dict[str, Any]]:
+    """Suppressions this change introduced, and whether they land on a finding.
+
+    The failure being watched for: a finding is closed by making it
+    invisible rather than by fixing it. Add `# noqa` to the flagged line and
+    the next audit reports nothing — the scan goes green over code nobody
+    repaired, and scope conformance alone would call that diff obedient,
+    because the file it touched is exactly the file the work order named.
+
+    Only *added* lines are read. A suppression already in the tree is not
+    evidence about this change, and treating a decade of accumulated
+    directives as newly written would drown the signal that matters.
+
+    `on_named_path` is that signal: a suppression added to a file the work
+    order flagged is the shape of a finding being silenced, while one added
+    elsewhere is ordinary engineering that a reviewer may still want to see.
+    """
+    found: list[dict[str, Any]] = []
+    for path in sorted(added):
+        for line_number, text in added[path]:
+            for pattern, label in _SUPPRESSION:
+                if pattern.search(text):
+                    found.append({
+                        "path": path,
+                        "line": line_number,
+                        "marker": label,
+                        "on_named_path": path in named,
+                    })
+                    break
+    return found
+
+
+def scope_conformance(
+    report: dict[str, Any],
+    changed: set[str],
+    revspec: str,
+    added: dict[str, list[tuple[int, str]]] | None = None,
+) -> dict[str, Any]:
+    """How a diff relates to the work order the agent was handed.
+
+    Returns the record, never a verdict on the code. `in_scope`,
+    `paired_tests` and `out_of_scope` partition the changed files;
+    `unaddressed` names work-order paths the diff did not touch, which is
+    not a failure — a bounded change may take one item at a time.
+    """
+    work_order = report.get("work_order") or []
+    named = _named_paths(work_order)
+
+    in_scope = sorted(path for path in changed if path in named)
+    remaining = {path for path in changed if path not in named}
+    paired = sorted(path for path in remaining if _pairs_to_named(path, named))
+    out_of_scope = sorted(remaining - set(paired))
+    suppressions = suppressions_added(added or {}, named)
+    silenced = [item for item in suppressions if item["on_named_path"]]
+
+    return {
+        "revspec": revspec,
+        "work_order_items": len(work_order),
+        "named_paths": sorted(named),
+        "changed_paths": sorted(changed),
+        "in_scope": in_scope,
+        "paired_tests": paired,
+        "out_of_scope": out_of_scope,
+        "unaddressed": sorted(named - set(in_scope)),
+        "suppressions_added": suppressions,
+        "suppressions_on_named_paths": len(silenced),
+        # Two questions, kept apart. `conformant` answers "did it change
+        # only what it was asked to"; `clean` also answers "and without
+        # switching a checker off in a file that was flagged". Scope alone
+        # is satisfiable by adding `# noqa` to the named file and changing
+        # nothing else, which is the evasion this pairing exists to catch.
+        "conformant": not out_of_scope,
+        "clean": not out_of_scope and not silenced,
+        # Stated so a reader does not infer more than was checked. The
+        # record says which files the work order named, not whether the
+        # edits inside them were the right ones.
+        "note": (
+            "Paths and added lines. A file in scope means the work order "
+            "named it, not that the change to it was correct."
+        ),
+    }

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/src/maintainability_audit/cli.py

@@ -36,14 +36,43 @@ from .config import (
     load_config,
     repository_path,
 )
-from .git_tools import changed_paths
-from .instructions import instruction_path_for_target, write_instruction_pack
+from .git_tools import added_lines, changed_paths
+from .instructions import (
+    INSTRUCTION_TARGETS,
+    UnknownTarget,
+    instruction_path_for_target,
+    write_instruction_pack,
+)
 from .prompts import render_agent_instructions, render_ai_prompt, render_hostile_audit_prompt
 from .renderers import render_html, render_markdown, render_pr_comment
 from .report import build_report
 from .sarif import read_sarif_inputs, report_to_sarif
 
 
+def _add_gate_arguments(parser: argparse.ArgumentParser) -> None:
+    """What can make a run fail, and the conformance record behind one.
+
+    Split from `add_arguments` when the conformance flags took it past this
+    project's own function-length gate — which is the gate doing its job on
+    the change that added a gate.
+    """
+    parser.add_argument("--fail-on-gate", action="store_true", help="Exit 1 when hard gates fail.")
+    parser.add_argument(
+        "--conformance",
+        metavar="REVSPEC",
+        help="Report how a diff relates to the work order, e.g. `main...HEAD`. "
+             "The bounded work order says 'fix exactly these and refactor nothing "
+             "else'; without this the bound is an instruction nothing checks. "
+             "Reports only unless --fail-on-out-of-scope is passed.",
+    )
+    parser.add_argument(
+        "--fail-on-out-of-scope", action="store_true",
+        help="With --conformance, exit 1 when the diff touched files the work "
+             "order did not name and that do not pair to one as its test, or "
+             "when it added a suppression to a file the work order flagged.",
+    )
+
+
 def add_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("--version", action="version", version=f"maintainability-agent {VERSION}")
     parser.add_argument("--root", default=".", help="Repository root to scan.")
@@ -110,7 +139,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:
              "The shape of a series is what a trend reads, and a thousand "
              "commits is hours of work nobody asked for.",
     )
-    parser.add_argument("--fail-on-gate", action="store_true", help="Exit 1 when hard gates fail.")
+    _add_gate_arguments(parser)
     _add_setup_actions(parser)
 
 
@@ -133,10 +162,19 @@ def _add_setup_actions(parser: argparse.ArgumentParser) -> None:
              "and remove files the package no longer ships. Without it, a "
              "differing copy is refused with the list of differences.",
     )
+    parser.add_argument(
+        "--target-path",
+        action="append",
+        metavar="TARGET=PATH",
+        help="Where a target's standing instructions go, e.g. "
+             "`--target-path bob=.bob/instructions.md`. Required for any agent "
+             "this tool has no built-in convention for; overrides the built-in "
+             "path for one it does. The target list will always trail the "
+             "market, and guessing a path writes a file the agent never opens.",
+    )
     parser.add_argument(
         "--target",
         action="append",
-        choices=["generic", "claude-code", "codex", "cursor", "copilot", "windsurf"],
         help="Instruction target. Repeatable. Used with --init-agent-standards.",
     )
     parser.add_argument("--instructions-output-dir", default=".", help="Directory for generated instruction files.")
@@ -188,6 +226,25 @@ def write_outputs(args: argparse.Namespace, report: dict, rendered: str) -> None
                        json.dumps(report_to_sarif(report), indent=2) + "\n", json_artifact=True)
 
 
+def attach_conformance(args: argparse.Namespace, report: dict) -> None:
+    """Record how the diff relates to the work order, when asked.
+
+    Assembly, not scoring: the record is attached to the report and reaches
+    no dimension, because whether a diff was obedient is a fact about an
+    agent's behaviour and not evidence about the code's condition.
+    """
+    if not args.conformance:
+        return
+    from ._conformance import scope_conformance
+
+    root = Path(report["root"])
+    changed = changed_paths(root, args.conformance)
+    added = added_lines(root, args.conformance)
+    report["scope_conformance"] = scope_conformance(
+        report, changed, args.conformance, added
+    )
+
+
 def audit_exit_code(args: argparse.Namespace, report: dict) -> int:
     if args.fail_on_new:
         # Structured matching, never a label-set difference: a label
@@ -198,6 +255,16 @@ def audit_exit_code(args: argparse.Namespace, report: dict) -> int:
             return 1
     if args.fail_on_gate and report["hard_gate_failures"]:
         return 1
+    if args.fail_on_out_of_scope:
+        record = report.get("scope_conformance")
+        if record is None:
+            print("--fail-on-out-of-scope needs --conformance REVSPEC", file=sys.stderr)
+            return 2
+        # `clean`, not `conformant`: staying in scope while silencing the
+        # finding is the evasion the pairing exists to catch, and a gate
+        # that accepted it would be satisfied by the thing it guards against.
+        if not record["clean"]:
+            return 1
     return 0
 
 
@@ -258,6 +325,35 @@ def _install_skill_action(args: argparse.Namespace) -> int:
     return 0
 
 
+
+def _target_paths(pairs: list[str] | None) -> dict[str, str]:
+    """`TARGET=PATH` arguments, as a mapping.
+
+    An absolute path is refused: the instruction pack is written relative
+    to `--instructions-output-dir`, so an absolute one would silently
+    ignore the directory the caller named.
+    """
+    overrides: dict[str, str] = {}
+    for pair in pairs or []:
+        target, separator, path = pair.partition("=")
+        if not separator or not target.strip() or not path.strip():
+            raise ValueError(f"--target-path expects TARGET=PATH, got {pair!r}")
+        if Path(path).is_absolute():
+            raise ValueError(
+                f"--target-path {pair!r} is absolute; paths are relative to "
+                "--instructions-output-dir"
+            )
+        overrides[target.strip()] = path.strip()
+    return overrides
+
+
+def _parse(argv: list[str]) -> tuple[argparse.ArgumentParser, argparse.Namespace]:
+    """The parser comes back too: `main` still needs it for `parser.error`."""
+    parser = argparse.ArgumentParser()
+    add_arguments(parser)
+    return parser, parser.parse_args(argv)
+
+
 def main(argv: list[str] | None = None) -> int:
     if argv is None:
         argv = sys.argv[1:]
@@ -266,18 +362,22 @@ def main(argv: list[str] | None = None) -> int:
 
         return mcp_server.main(argv[1:])
 
-    parser = argparse.ArgumentParser()
-    add_arguments(parser)
-    args = parser.parse_args(argv)
-
+    parser, args = _parse(argv)
     if args.install_skill:
         return _install_skill_action(args)
 
     root = Path(args.root).resolve()
     config = _interactive_config(root, args.config)
     if args.init_agent_standards:
-        targets = args.target or ["generic", "claude-code", "codex", "cursor", "copilot", "windsurf"]
-        write_instruction_pack(targets, Path(args.instructions_output_dir).resolve(), config)
+        targets = args.target or list(INSTRUCTION_TARGETS)
+        try:
+            overrides = _target_paths(args.target_path)
+            write_instruction_pack(
+                targets, Path(args.instructions_output_dir).resolve(), config, overrides
+            )
+        except (UnknownTarget, ValueError) as failure:
+            print(str(failure), file=sys.stderr)
+            return 2
         return 0
 
     if args.backfill:
@@ -327,6 +427,9 @@ def main(argv: list[str] | None = None) -> int:
     # escalated, and only delivered advice is recorded as targeted.
     record_scan_and_attach(report, config, history_path, Path(report["root"]),
                            record=bool(record), want_targets=bool(args.prompt_output))
+    # Before rendering, so the record is in the report every presentation
+    # and every consumer reads, rather than only in the exit code.
+    attach_conformance(args, report)
     rendered = _render_presentation(args, report, history_path)
     write_outputs(args, report, rendered)
     mark_repo_seen(root)  # completed audit: not a first run now, whatever the gate says (D13)

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/src/maintainability_audit/config.py

@@ -11,7 +11,7 @@ from ._config_defaults import DEFAULT_CONFIG, DEFAULT_IDIOM_GROUPS
 # still the door every caller comes through.
 __all__ = ["DEFAULT_CONFIG", "DEFAULT_IDIOM_GROUPS", "PROJECT_URL", "VERSION"]
 
-VERSION = "2.0.0"
+VERSION = "2.1.0"
 
 PROJECT_URL = "https://github.com/marshallguillory86/maintainability-agent"
 

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/src/maintainability_audit/git_tools.py

@@ -229,6 +229,44 @@ def changed_paths(root: Path, revspec: str) -> set[str]:
     return {line.strip().replace(os.sep, "/") for line in output.splitlines() if line.strip()}
 
 
+def added_lines(root: Path, revspec: str) -> dict[str, list[tuple[int, str]]]:
+    """Lines a revspec *adds*, per path, as (line number, text).
+
+    Added lines only. A suppression that was already in the tree is not
+    evidence about this change, and reading whole files instead of the diff
+    would report a decade of accumulated `# noqa` as though this agent had
+    just written them.
+
+    `--unified=0` keeps context lines out, so every `+` is genuinely new.
+    The revspec is validated and `--` terminates the revision list, as in
+    `changed_paths`: nothing after it can be read as a path or an option.
+    """
+    # `--no-ext-diff` is load-bearing, not defensive. The read-only config
+    # this module runs under neutralises `diff.external`, which costs
+    # nothing for `--name-only` because no diff is produced — and kills a
+    # content diff outright, because git then tries to execute the empty
+    # string: "cannot run : No such file or directory".
+    output = run_git(
+        ["diff", "--no-ext-diff", "--unified=0", validate_revspec(revspec), "--"], root
+    )
+    added: dict[str, list[tuple[int, str]]] = {}
+    path = ""
+    line_number = 0
+    for line in output.splitlines():
+        if line.startswith("+++ b/"):
+            path = line[6:].strip().replace(os.sep, "/")
+        elif line.startswith("@@"):
+            # @@ -old,count +new,count @@
+            marker = line.split("+", 1)[1].split("@@", 1)[0].strip()
+            start = marker.split(",", 1)[0]
+            line_number = int(start) if start.lstrip("-").isdigit() else 0
+        elif line.startswith("+") and not line.startswith("+++"):
+            if path:
+                added.setdefault(path, []).append((line_number, line[1:]))
+            line_number += 1
+    return added
+
+
 def worktree_status(root: Path) -> str | None:
     """Porcelain status, or `None` when git cannot answer.
 

{maintainability_agent-2.0.0 → maintainability_agent-2.1.0}/src/maintainability_audit/instructions.py

@@ -81,19 +81,64 @@ def instruction_body(target: str, config: dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
-def instruction_path_for_target(target: str, output_dir: Path) -> Path:
-    mapping = {
-        "generic": "AI-MAINTAINABILITY.md",
-        "claude-code": "CLAUDE.md",
-        "codex": "AGENTS.md",
-        "cursor": ".cursor/rules/maintainability.mdc",
-        "copilot": ".github/copilot-instructions.md",
-        "windsurf": ".windsurf/rules/maintainability.md",
-    }
-    return output_dir / mapping.get(target, f"{target}-maintainability.md")
+#: Each agent and the file it actually reads for repo standing
+#: instructions. One declaration, because this list was written out three
+#: times — here, and twice in `cli.py` as `choices` and as the default —
+#: so adding a target meant remembering all three or shipping one the CLI
+#: refused to accept.
+#:
+#: A target belongs here only when the path it writes is the path that
+#: agent genuinely reads. Emitting a plausible-looking file an agent never
+#: opens is worse than having no target: it looks configured and does
+#: nothing.
+INSTRUCTION_TARGETS: dict[str, str] = {
+    "generic": "AI-MAINTAINABILITY.md",
+    "claude-code": "CLAUDE.md",
+    "codex": "AGENTS.md",
+    "cursor": ".cursor/rules/maintainability.mdc",
+    "copilot": ".github/copilot-instructions.md",
+    "windsurf": ".windsurf/rules/maintainability.md",
+}
 
 
-def write_instruction_pack(targets: list[str], output_dir: Path, config: dict[str, Any]) -> list[str]:
+class UnknownTarget(ValueError):
+    """A target with no built-in convention and no path supplied."""
+
+
+def instruction_path_for_target(
+    target: str, output_dir: Path, overrides: dict[str, str] | None = None
+) -> Path:
+    """Where this agent's standing instructions go.
+
+    An override wins over the built-in table, because a convention can
+    change or be site-specific, and the person running the command knows
+    their agent better than this table does.
+
+    A target nobody has a convention for is **refused** rather than given a
+    generated filename. The fallback that used to sit here —
+    ``{target}-maintainability.md`` — was unreachable anyway, because the
+    CLI's `choices` rejected unknown targets first; and had it been
+    reachable it would have written a plausible-looking file the agent
+    never opens, which is worse than no target at all. It looks configured
+    and does nothing.
+    """
+    if overrides and target in overrides:
+        return output_dir / overrides[target]
+    if target in INSTRUCTION_TARGETS:
+        return output_dir / INSTRUCTION_TARGETS[target]
+    raise UnknownTarget(
+        f"no known instructions path for {target!r}. Pass "
+        f"--target-path {target}=PATH to say where that agent reads its "
+        f"standing instructions. Known targets: {', '.join(INSTRUCTION_TARGETS)}"
+    )
+
+
+def write_instruction_pack(
+    targets: list[str],
+    output_dir: Path,
+    config: dict[str, Any],
+    overrides: dict[str, str] | None = None,
+) -> list[str]:
     # Each instruction file is a product-artifact write: `output_dir`
     # comes from a person (`--instructions-output-dir`), so the write is
     # bound to that directory and refuses a symlinked route the audited
@@ -102,7 +147,7 @@ def write_instruction_pack(targets: list[str], output_dir: Path, config: dict[st
 
     written: list[str] = []
     for target in targets:
-        path = instruction_path_for_target(target, output_dir)
+        path = instruction_path_for_target(target, output_dir, overrides)
         write_artifact(output_dir, path, instruction_body(target, config) + "\n")
         written.append(str(path))
     return written