maintainability-agent 2.8.0__tar.gz → 2.9.0__tar.gz

{maintainability_agent-2.8.0/src/maintainability_agent.egg-info → maintainability_agent-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.8.0
+Version: 2.9.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -39,12 +39,12 @@ Dynamic: license-file
 
 # Maintainability Agent
 
-![maintainability-agent — a deterministic audit whose output is a bounded work order for your AI coding agent: fix exactly these findings, refactor nothing else](docs/cover.png)
+![maintainability-agent — a deterministic audit whose output is a bounded work order for your AI coding agent: fix exactly these findings, refactor nothing else](https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/docs/cover.png)
 
 **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.8.0**.
+Version **2.9.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -201,6 +201,8 @@ integration](docs/ide-agent-integration.md).
 
 ## Automation / CI: CLI
 
+![The loop, end to end: staged content meets a fast gate that blocks or passes it, the full audit measures what landed, the work order names exactly what to fix, and the repair is checked back against it](https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/docs/MA_workflow.jpg)
+
 Use the CLI for scripts, repeatable automation, and CI gates. Copy the example
 config to your repo root as `maintainability-agent.json`, then:
 
@@ -260,6 +262,30 @@ maintainability-agent \
 The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
 has the history of why this was the hole under the product's central claim.
 
+### Before the commit
+
+The gate above runs after the work is done. `--staged` runs while it is still in
+the author's hands:
+
+```bash
+maintainability-agent --install-precommit-hook   # writes .git/hooks/pre-commit
+```
+
+It scans **the index, not the working tree** — stage half a file with `git add
+-p` and keep typing, and what gets measured is what the commit will actually
+contain. Clean, it prints nothing and exits 0. Breaching, it names each path,
+line and remedy and exits 1; `--format json` gives an agent the same findings.
+
+It is not a small audit. It produces **no score**, because a diff has no
+population to draw a rate from — only threshold breaches, including a `# noqa`
+this change added. It applies no repository gates: a missing README is a
+property of the repository, not of your diff. And it runs nothing and writes
+nothing, so it costs 0.17s here against the full audit's 266 — a hook slower
+than the author's patience is one they uninstall.
+
+`--install-precommit-hook` refuses to replace a hook it did not write, printing
+the line to add to yours instead, and honours `core.hooksPath`.
+
 ## What it analyzes
 
 The deterministic scanner reads code from your repo (no LLM calls) and produces
@@ -322,42 +348,16 @@ Any language **not** in that table — Go, Rust, Ruby, PHP, Kotlin, and the rest
 is **not parsed for declarations by the built-in scanner.** Its files still count
 toward repo size, but the built-ins produce no function-size, complexity,
 duplication or dead-code findings for them, and the estimate leans on whatever
-evidence *is* available (which is why the report discloses its evidence tier and
-can withhold the grade).
-
-**Which analyzer covers which language** (the opt-in pool, when installed):
-
-| Language | Built-in scanner | External analyzer |
-|---|---|---|
-| Python | `ast`, exact | ruff, radon, mypy, vulture, complexipy, interrogate, pydocstyle, pylint, cohesion |
-| Java | dedicated scanner | lizard, PMD, Checkstyle, SpotBugs |
-| C / C++ / C# | dedicated scanners | lizard, multimetric |
-| **Fortran** (free- and fixed-form) | dedicated scanner | **fortitude** — 100+ rules; **lizard** — complexity, NLOC, params |
-| **COBOL** | dedicated scanner | **none** — no offline analyzer in the catalog reads it |
-| JS / TS / JSX / TSX | brace scanner | ESLint, lizard, jscpd |
-
-Fortran reached parity in 1.6.0: lizard had read it for years behind a
-stale catalog row, so it came out `not-applicable` and never ran. A lint fails
-the build if a parsed language has no analyzer measuring complexity — **COBOL is
-the one disclosed exemption**, because the tooling that reads it is licensed and
-host-resident, so its external tier is empty and the report says so.
-
-**External analyzer adapters (opt-in pool)** — this is how coverage extends
-beyond the built-in set. When you enable the analyzer pool, the tool shells out
-to mature analyzers and folds their output in through per-tool
-[adapters](docs/adapters.md): **lizard** (cyclomatic complexity across ~a dozen
-languages), **jscpd** (cross-language duplication), **ESLint** (JS/TS),
-**PMD** / **SpotBugs** (JVM), and others in the catalog. These run only when
-selected *and* installed (acquisition is opt-in and off by default), and where
-they measured a full concept set they become the *primary* evidence, with the
-built-ins as the fallback.
+evidence *is* available — which is why the report discloses its evidence tier
+and can withhold the grade.
 
 So: **first-class today is Python** (and TypeScript for semantics); every other
 parsed language is bounded-but-real; anything outside the table is only as
-covered as the analyzer you point at it, and with none it is under-reported by
-design. Per-language accuracy and limits:
-[docs/language-support.md](docs/language-support.md); the adapter catalog:
-[docs/adapters.md](docs/adapters.md).
+covered as the analyzer you point at it. Per-language accuracy and limits:
+[docs/language-support.md](docs/language-support.md). Which analyzer covers
+which language, how the opt-in pool extends coverage past the built-in set, and
+why COBOL's external tier is empty:
+[docs/adapters.md](docs/adapters.md#which-analyzer-covers-which-language).
 
 ## What it produces
 
@@ -430,35 +430,29 @@ and costs roughly a grade — use `fetch-depth: 0`.)
 
 ## Platform support
 
-**POSIX. Linux and macOS are what this has run on; Windows is untested and not
-claimed.** That is a statement about evidence, not a refusal: CI runs Linux,
-development runs macOS, and the test suite creates symlinks with no platform
-guard (needing Developer Mode on Windows), so it never reaches the point of
-telling anyone whether the product works there. Adding `windows-latest` to CI
-and fixing what falls out is how that changes.
+**POSIX. Windows is not claimed, for a measured reason.** A `windows-latest` probe
+found most failures in two POSIX-only calls, `os.fchmod` and `os.O_DIRECTORY`. The
+bounded, symlink-refusing write works through a *file descriptor*, so a validated
+path cannot be swapped for a symlink before the write lands — Windows has no
+equivalent and the portable rewrite is the hole. **An unsupported platform never
+buys green by weakening the supported ones.**
 
 ## Invokable skill / slash command
 
 This repo ships a portable skill under
-[`skills/maintainability-agent/`](skills/maintainability-agent/) so
-`/maintainability-agent` is one keystroke away. Keep the installed copy in sync
-— a drifted skill teaches agents a dead workflow:
+[`skills/maintainability-agent/`](skills/maintainability-agent/), so
+`/maintainability-agent` is one keystroke away in Claude Code, Codex and
+Copilot Chat:
 
 ```bash
 maintainability-agent --install-skill        # writes ~/.claude/skills
 ```
 
-Re-run after every upgrade; a differing installed copy is refused with the
-list of differences (`--force-skill` to overwrite).
-
-| Host | Install destination | Invocation |
-|---|---|---|
-| Codex / OpenAI | via `skills/maintainability-agent/agents/openai.yaml` | per Codex's skills convention |
-| Claude Code | `skills/maintainability-agent/` → `~/.claude/skills/maintainability-agent/` (or repo `.claude/skills/`) | `/maintainability-agent` |
-| GitHub Copilot (VS Code) | `skills/maintainability-agent/copilot/maintainability-agent.prompt.md` → `<repo>/.github/prompts/` | `/maintainability-agent` in Copilot Chat |
-
-For always-on guidance instead of an invokable skill, use
-`--init-agent-standards` (see [docs/ide-agent-integration.md](docs/ide-agent-integration.md)).
+Re-run it after every upgrade — a drifted skill teaches agents a dead workflow,
+so a differing installed copy is refused with the list of differences. Per-host
+install destinations, and `--init-agent-standards` for always-on guidance
+instead of an invokable skill:
+[docs/ide-agent-integration.md](docs/ide-agent-integration.md#invokable-skill--slash-command).
 
 ## GitHub Action
 

{maintainability_agent-2.8.0 → maintainability_agent-2.9.0}/README.md

@@ -1,11 +1,11 @@
 # Maintainability Agent
 
-![maintainability-agent — a deterministic audit whose output is a bounded work order for your AI coding agent: fix exactly these findings, refactor nothing else](docs/cover.png)
+![maintainability-agent — a deterministic audit whose output is a bounded work order for your AI coding agent: fix exactly these findings, refactor nothing else](https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/docs/cover.png)
 
 **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.8.0**.
+Version **2.9.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -162,6 +162,8 @@ integration](docs/ide-agent-integration.md).
 
 ## Automation / CI: CLI
 
+![The loop, end to end: staged content meets a fast gate that blocks or passes it, the full audit measures what landed, the work order names exactly what to fix, and the repair is checked back against it](https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/docs/MA_workflow.jpg)
+
 Use the CLI for scripts, repeatable automation, and CI gates. Copy the example
 config to your repo root as `maintainability-agent.json`, then:
 
@@ -221,6 +223,30 @@ maintainability-agent \
 The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
 has the history of why this was the hole under the product's central claim.
 
+### Before the commit
+
+The gate above runs after the work is done. `--staged` runs while it is still in
+the author's hands:
+
+```bash
+maintainability-agent --install-precommit-hook   # writes .git/hooks/pre-commit
+```
+
+It scans **the index, not the working tree** — stage half a file with `git add
+-p` and keep typing, and what gets measured is what the commit will actually
+contain. Clean, it prints nothing and exits 0. Breaching, it names each path,
+line and remedy and exits 1; `--format json` gives an agent the same findings.
+
+It is not a small audit. It produces **no score**, because a diff has no
+population to draw a rate from — only threshold breaches, including a `# noqa`
+this change added. It applies no repository gates: a missing README is a
+property of the repository, not of your diff. And it runs nothing and writes
+nothing, so it costs 0.17s here against the full audit's 266 — a hook slower
+than the author's patience is one they uninstall.
+
+`--install-precommit-hook` refuses to replace a hook it did not write, printing
+the line to add to yours instead, and honours `core.hooksPath`.
+
 ## What it analyzes
 
 The deterministic scanner reads code from your repo (no LLM calls) and produces
@@ -283,42 +309,16 @@ Any language **not** in that table — Go, Rust, Ruby, PHP, Kotlin, and the rest
 is **not parsed for declarations by the built-in scanner.** Its files still count
 toward repo size, but the built-ins produce no function-size, complexity,
 duplication or dead-code findings for them, and the estimate leans on whatever
-evidence *is* available (which is why the report discloses its evidence tier and
-can withhold the grade).
-
-**Which analyzer covers which language** (the opt-in pool, when installed):
-
-| Language | Built-in scanner | External analyzer |
-|---|---|---|
-| Python | `ast`, exact | ruff, radon, mypy, vulture, complexipy, interrogate, pydocstyle, pylint, cohesion |
-| Java | dedicated scanner | lizard, PMD, Checkstyle, SpotBugs |
-| C / C++ / C# | dedicated scanners | lizard, multimetric |
-| **Fortran** (free- and fixed-form) | dedicated scanner | **fortitude** — 100+ rules; **lizard** — complexity, NLOC, params |
-| **COBOL** | dedicated scanner | **none** — no offline analyzer in the catalog reads it |
-| JS / TS / JSX / TSX | brace scanner | ESLint, lizard, jscpd |
-
-Fortran reached parity in 1.6.0: lizard had read it for years behind a
-stale catalog row, so it came out `not-applicable` and never ran. A lint fails
-the build if a parsed language has no analyzer measuring complexity — **COBOL is
-the one disclosed exemption**, because the tooling that reads it is licensed and
-host-resident, so its external tier is empty and the report says so.
-
-**External analyzer adapters (opt-in pool)** — this is how coverage extends
-beyond the built-in set. When you enable the analyzer pool, the tool shells out
-to mature analyzers and folds their output in through per-tool
-[adapters](docs/adapters.md): **lizard** (cyclomatic complexity across ~a dozen
-languages), **jscpd** (cross-language duplication), **ESLint** (JS/TS),
-**PMD** / **SpotBugs** (JVM), and others in the catalog. These run only when
-selected *and* installed (acquisition is opt-in and off by default), and where
-they measured a full concept set they become the *primary* evidence, with the
-built-ins as the fallback.
+evidence *is* available — which is why the report discloses its evidence tier
+and can withhold the grade.
 
 So: **first-class today is Python** (and TypeScript for semantics); every other
 parsed language is bounded-but-real; anything outside the table is only as
-covered as the analyzer you point at it, and with none it is under-reported by
-design. Per-language accuracy and limits:
-[docs/language-support.md](docs/language-support.md); the adapter catalog:
-[docs/adapters.md](docs/adapters.md).
+covered as the analyzer you point at it. Per-language accuracy and limits:
+[docs/language-support.md](docs/language-support.md). Which analyzer covers
+which language, how the opt-in pool extends coverage past the built-in set, and
+why COBOL's external tier is empty:
+[docs/adapters.md](docs/adapters.md#which-analyzer-covers-which-language).
 
 ## What it produces
 
@@ -391,35 +391,29 @@ and costs roughly a grade — use `fetch-depth: 0`.)
 
 ## Platform support
 
-**POSIX. Linux and macOS are what this has run on; Windows is untested and not
-claimed.** That is a statement about evidence, not a refusal: CI runs Linux,
-development runs macOS, and the test suite creates symlinks with no platform
-guard (needing Developer Mode on Windows), so it never reaches the point of
-telling anyone whether the product works there. Adding `windows-latest` to CI
-and fixing what falls out is how that changes.
+**POSIX. Windows is not claimed, for a measured reason.** A `windows-latest` probe
+found most failures in two POSIX-only calls, `os.fchmod` and `os.O_DIRECTORY`. The
+bounded, symlink-refusing write works through a *file descriptor*, so a validated
+path cannot be swapped for a symlink before the write lands — Windows has no
+equivalent and the portable rewrite is the hole. **An unsupported platform never
+buys green by weakening the supported ones.**
 
 ## Invokable skill / slash command
 
 This repo ships a portable skill under
-[`skills/maintainability-agent/`](skills/maintainability-agent/) so
-`/maintainability-agent` is one keystroke away. Keep the installed copy in sync
-— a drifted skill teaches agents a dead workflow:
+[`skills/maintainability-agent/`](skills/maintainability-agent/), so
+`/maintainability-agent` is one keystroke away in Claude Code, Codex and
+Copilot Chat:
 
 ```bash
 maintainability-agent --install-skill        # writes ~/.claude/skills
 ```
 
-Re-run after every upgrade; a differing installed copy is refused with the
-list of differences (`--force-skill` to overwrite).
-
-| Host | Install destination | Invocation |
-|---|---|---|
-| Codex / OpenAI | via `skills/maintainability-agent/agents/openai.yaml` | per Codex's skills convention |
-| Claude Code | `skills/maintainability-agent/` → `~/.claude/skills/maintainability-agent/` (or repo `.claude/skills/`) | `/maintainability-agent` |
-| GitHub Copilot (VS Code) | `skills/maintainability-agent/copilot/maintainability-agent.prompt.md` → `<repo>/.github/prompts/` | `/maintainability-agent` in Copilot Chat |
-
-For always-on guidance instead of an invokable skill, use
-`--init-agent-standards` (see [docs/ide-agent-integration.md](docs/ide-agent-integration.md)).
+Re-run it after every upgrade — a drifted skill teaches agents a dead workflow,
+so a differing installed copy is refused with the list of differences. Per-host
+install destinations, and `--init-agent-standards` for always-on guidance
+instead of an invokable skill:
+[docs/ide-agent-integration.md](docs/ide-agent-integration.md#invokable-skill--slash-command).
 
 ## GitHub Action
 

{maintainability_agent-2.8.0 → maintainability_agent-2.9.0}/pyproject.toml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maintainability-agent
-Version: 2.8.0
+Version: 2.9.0
 Summary: Maintainability gate and AI remediation prompt generator for CI.
 Author: Marshall Guillory
 License: MIT
@@ -39,12 +39,12 @@ Dynamic: license-file
 
 # Maintainability Agent
 
-![maintainability-agent — a deterministic audit whose output is a bounded work order for your AI coding agent: fix exactly these findings, refactor nothing else](docs/cover.png)
+![maintainability-agent — a deterministic audit whose output is a bounded work order for your AI coding agent: fix exactly these findings, refactor nothing else](https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/docs/cover.png)
 
 **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.8.0**.
+Version **2.9.0**.
 
 **Languages parsed:** Python, Java, C, C++, C#, Swift, Fortran (free-form
 *and* fixed-form), and the JS/TS family — each by a scanner written for it, and
@@ -201,6 +201,8 @@ integration](docs/ide-agent-integration.md).
 
 ## Automation / CI: CLI
 
+![The loop, end to end: staged content meets a fast gate that blocks or passes it, the full audit measures what landed, the work order names exactly what to fix, and the repair is checked back against it](https://raw.githubusercontent.com/marshallguillory86/maintainability-agent/main/docs/MA_workflow.jpg)
+
 Use the CLI for scripts, repeatable automation, and CI gates. Copy the example
 config to your repo root as `maintainability-agent.json`, then:
 
@@ -260,6 +262,30 @@ maintainability-agent \
 The [roadmap](docs/roadmap.md#the-remediation-hole-closed-in-210-through-230)
 has the history of why this was the hole under the product's central claim.
 
+### Before the commit
+
+The gate above runs after the work is done. `--staged` runs while it is still in
+the author's hands:
+
+```bash
+maintainability-agent --install-precommit-hook   # writes .git/hooks/pre-commit
+```
+
+It scans **the index, not the working tree** — stage half a file with `git add
+-p` and keep typing, and what gets measured is what the commit will actually
+contain. Clean, it prints nothing and exits 0. Breaching, it names each path,
+line and remedy and exits 1; `--format json` gives an agent the same findings.
+
+It is not a small audit. It produces **no score**, because a diff has no
+population to draw a rate from — only threshold breaches, including a `# noqa`
+this change added. It applies no repository gates: a missing README is a
+property of the repository, not of your diff. And it runs nothing and writes
+nothing, so it costs 0.17s here against the full audit's 266 — a hook slower
+than the author's patience is one they uninstall.
+
+`--install-precommit-hook` refuses to replace a hook it did not write, printing
+the line to add to yours instead, and honours `core.hooksPath`.
+
 ## What it analyzes
 
 The deterministic scanner reads code from your repo (no LLM calls) and produces
@@ -322,42 +348,16 @@ Any language **not** in that table — Go, Rust, Ruby, PHP, Kotlin, and the rest
 is **not parsed for declarations by the built-in scanner.** Its files still count
 toward repo size, but the built-ins produce no function-size, complexity,
 duplication or dead-code findings for them, and the estimate leans on whatever
-evidence *is* available (which is why the report discloses its evidence tier and
-can withhold the grade).
-
-**Which analyzer covers which language** (the opt-in pool, when installed):
-
-| Language | Built-in scanner | External analyzer |
-|---|---|---|
-| Python | `ast`, exact | ruff, radon, mypy, vulture, complexipy, interrogate, pydocstyle, pylint, cohesion |
-| Java | dedicated scanner | lizard, PMD, Checkstyle, SpotBugs |
-| C / C++ / C# | dedicated scanners | lizard, multimetric |
-| **Fortran** (free- and fixed-form) | dedicated scanner | **fortitude** — 100+ rules; **lizard** — complexity, NLOC, params |
-| **COBOL** | dedicated scanner | **none** — no offline analyzer in the catalog reads it |
-| JS / TS / JSX / TSX | brace scanner | ESLint, lizard, jscpd |
-
-Fortran reached parity in 1.6.0: lizard had read it for years behind a
-stale catalog row, so it came out `not-applicable` and never ran. A lint fails
-the build if a parsed language has no analyzer measuring complexity — **COBOL is
-the one disclosed exemption**, because the tooling that reads it is licensed and
-host-resident, so its external tier is empty and the report says so.
-
-**External analyzer adapters (opt-in pool)** — this is how coverage extends
-beyond the built-in set. When you enable the analyzer pool, the tool shells out
-to mature analyzers and folds their output in through per-tool
-[adapters](docs/adapters.md): **lizard** (cyclomatic complexity across ~a dozen
-languages), **jscpd** (cross-language duplication), **ESLint** (JS/TS),
-**PMD** / **SpotBugs** (JVM), and others in the catalog. These run only when
-selected *and* installed (acquisition is opt-in and off by default), and where
-they measured a full concept set they become the *primary* evidence, with the
-built-ins as the fallback.
+evidence *is* available — which is why the report discloses its evidence tier
+and can withhold the grade.
 
 So: **first-class today is Python** (and TypeScript for semantics); every other
 parsed language is bounded-but-real; anything outside the table is only as
-covered as the analyzer you point at it, and with none it is under-reported by
-design. Per-language accuracy and limits:
-[docs/language-support.md](docs/language-support.md); the adapter catalog:
-[docs/adapters.md](docs/adapters.md).
+covered as the analyzer you point at it. Per-language accuracy and limits:
+[docs/language-support.md](docs/language-support.md). Which analyzer covers
+which language, how the opt-in pool extends coverage past the built-in set, and
+why COBOL's external tier is empty:
+[docs/adapters.md](docs/adapters.md#which-analyzer-covers-which-language).
 
 ## What it produces
 
@@ -430,35 +430,29 @@ and costs roughly a grade — use `fetch-depth: 0`.)
 
 ## Platform support
 
-**POSIX. Linux and macOS are what this has run on; Windows is untested and not
-claimed.** That is a statement about evidence, not a refusal: CI runs Linux,
-development runs macOS, and the test suite creates symlinks with no platform
-guard (needing Developer Mode on Windows), so it never reaches the point of
-telling anyone whether the product works there. Adding `windows-latest` to CI
-and fixing what falls out is how that changes.
+**POSIX. Windows is not claimed, for a measured reason.** A `windows-latest` probe
+found most failures in two POSIX-only calls, `os.fchmod` and `os.O_DIRECTORY`. The
+bounded, symlink-refusing write works through a *file descriptor*, so a validated
+path cannot be swapped for a symlink before the write lands — Windows has no
+equivalent and the portable rewrite is the hole. **An unsupported platform never
+buys green by weakening the supported ones.**
 
 ## Invokable skill / slash command
 
 This repo ships a portable skill under
-[`skills/maintainability-agent/`](skills/maintainability-agent/) so
-`/maintainability-agent` is one keystroke away. Keep the installed copy in sync
-— a drifted skill teaches agents a dead workflow:
+[`skills/maintainability-agent/`](skills/maintainability-agent/), so
+`/maintainability-agent` is one keystroke away in Claude Code, Codex and
+Copilot Chat:
 
 ```bash
 maintainability-agent --install-skill        # writes ~/.claude/skills
 ```
 
-Re-run after every upgrade; a differing installed copy is refused with the
-list of differences (`--force-skill` to overwrite).
-
-| Host | Install destination | Invocation |
-|---|---|---|
-| Codex / OpenAI | via `skills/maintainability-agent/agents/openai.yaml` | per Codex's skills convention |
-| Claude Code | `skills/maintainability-agent/` → `~/.claude/skills/maintainability-agent/` (or repo `.claude/skills/`) | `/maintainability-agent` |
-| GitHub Copilot (VS Code) | `skills/maintainability-agent/copilot/maintainability-agent.prompt.md` → `<repo>/.github/prompts/` | `/maintainability-agent` in Copilot Chat |
-
-For always-on guidance instead of an invokable skill, use
-`--init-agent-standards` (see [docs/ide-agent-integration.md](docs/ide-agent-integration.md)).
+Re-run it after every upgrade — a drifted skill teaches agents a dead workflow,
+so a differing installed copy is refused with the list of differences. Per-host
+install destinations, and `--init-agent-standards` for always-on guidance
+instead of an invokable skill:
+[docs/ide-agent-integration.md](docs/ide-agent-integration.md#invokable-skill--slash-command).
 
 ## GitHub Action
 

{maintainability_agent-2.8.0 → maintainability_agent-2.9.0}/src/maintainability_agent.egg-info/SOURCES.txt

@@ -58,6 +58,9 @@ src/maintainability_audit/_metric_adapters.py
 src/maintainability_audit/_metrics_types.py
 src/maintainability_audit/_pillars.py
 src/maintainability_audit/_practice.py
+src/maintainability_audit/_precommit.py
+src/maintainability_audit/_precommit_install.py
+src/maintainability_audit/_precommit_view.py
 src/maintainability_audit/_pressures.py
 src/maintainability_audit/_ranges_c.py
 src/maintainability_audit/_ranges_cobol.py
@@ -144,6 +147,7 @@ tests/test_analyzer_provenance_exclusions.py
 tests/test_analyzer_scoring_path.py
 tests/test_analyzer_spread_range.py
 tests/test_analyzer_xml_bounds.py
+tests/test_anchor_and_mode.py
 tests/test_anchor_disclosure.py
 tests/test_annotations_match_behaviour.py
 tests/test_anticipated_refusals.py
@@ -255,6 +259,7 @@ tests/test_migration_1_0.py
 tests/test_near_duplicates.py
 tests/test_network_disclosure.py
 tests/test_one_setup_across_surfaces_class.py
+tests/test_operator_named_paths.py
 tests/test_pattern_budget.py
 tests/test_phase6_claims.py
 tests/test_pillars_and_practice.py
@@ -264,6 +269,7 @@ tests/test_pmd_audit_closures.py
 tests/test_pool_runs_by_config.py
 tests/test_population_floors.py
 tests/test_practice_nested_gates_class.py
+tests/test_precommit_staged.py
 tests/test_presentation_refusals.py
 tests/test_promises.py
 tests/test_prompt_escalation_once.py

{maintainability_agent-2.8.0 → maintainability_agent-2.9.0}/src/maintainability_audit/__init__.py

@@ -1,3 +1,3 @@
 """Maintainability Audit CI."""
 
-__version__ = "2.8.0"
+__version__ = "2.9.0"

{maintainability_agent-2.8.0 → maintainability_agent-2.9.0}/src/maintainability_audit/_arguments.py

@@ -23,8 +23,23 @@ def _add_gate_arguments(parser: argparse.ArgumentParser) -> None:
     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.
+
+    `--staged` belongs here rather than with the artifact flags: it
+    produces no artifact and decides whether work proceeds, which is what
+    every other flag in this group does. It differs only in *when* — a
+    commit rather than a build — and that is the point of it.
     """
     parser.add_argument("--fail-on-gate", action="store_true", help="Exit 1 when hard gates fail.")
+    parser.add_argument(
+        "--staged", action="store_true",
+        help="Scan what the git index will commit, for a pre-commit hook. "
+             "Reads the index rather than the working tree, so half-staged "
+             "edits are measured as they will land. Reports threshold "
+             "breaches only and never a score — a diff has no population to "
+             "draw a rate from. Applies no repository gates, writes nothing, "
+             "and never runs the opt-in test suite. Exits 1 when something "
+             "blocks, silently 0 when nothing does.",
+    )
     parser.add_argument(
         "--conformance",
         metavar="REVSPEC",
@@ -158,6 +173,14 @@ def _add_setup_actions(parser: argparse.ArgumentParser) -> None:
              "exit. Re-run after every upgrade: an installed skill that "
              "drifts from the shipped one teaches agents a dead workflow.",
     )
+    parser.add_argument(
+        "--install-precommit-hook", action="store_true",
+        help="Write a git pre-commit hook that runs --staged, and exit. "
+             "Refuses to replace a hook this tool did not write, and "
+             "prints the line to add to that hook instead; replaces its "
+             "own without asking, because that is an upgrade. Honours "
+             "core.hooksPath.",
+    )
     parser.add_argument(
         "--skills-dir", default=None, metavar="DIR",
         help="Where --install-skill writes (default: ~/.claude/skills).",

{maintainability_agent-2.8.0 → maintainability_agent-2.9.0}/src/maintainability_audit/_conformance.py

@@ -98,6 +98,49 @@ _SUPPRESSION = tuple(
 )
 
 
+def _is_quoted(text: str, start: int) -> bool:
+    """Whether the marker at `start` is being *mentioned* rather than used.
+
+    A directive is never immediately preceded by a quote or a backtick,
+    and never sits inside an open backtick span. Prose about directives
+    does both constantly — this file's own comments do it, and so does
+    the docstring that says a marker in a docstring is not a suppression.
+    """
+    prefix = text[:start]
+    if prefix[-1:] in {"`", "'", '"'}:
+        return True
+    return prefix.count("`") % 2 == 1
+
+
+def markers_in(text: str) -> str | None:
+    """The suppression this line declares, or None if it only mentions one.
+
+    The one place that question is answered, because it is asked twice —
+    by the conformance record after a change, and by the pre-commit scan
+    before one — and a rule that disagrees with itself between the hook
+    and the gate blocks commits CI would pass.
+
+    D108: the marker set's own comment promised that "`# type: ignore` in
+    a docstring explaining the convention is not a suppression", and for
+    four versions nothing enforced it. The `--staged` scan found it
+    immediately, by blocking the commit of a docstring containing the
+    words `# noqa` — the first time the rule ran somewhere a false
+    positive cost something.
+
+    Still narrow, and deliberately: a marker written into ordinary prose
+    with no quoting around it is still reported. Quoting is the signal
+    that is actually reliable, and widening past it starts guessing at
+    English. This paragraph cannot give the example it would like to,
+    because writing one unquoted would report this line — which is the
+    rule demonstrating itself, and the reason the sentence stays abstract.
+    """
+    for pattern, label in _SUPPRESSION:
+        match = pattern.search(text)
+        if match and not _is_quoted(text, match.start()):
+            return label
+    return None
+
+
 def suppressions_added(
     added: dict[str, list[tuple[int, str]]], named: set[str]
 ) -> list[dict[str, Any]]:
@@ -120,15 +163,14 @@ def suppressions_added(
     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
+            label = markers_in(text)
+            if label:
+                found.append({
+                    "path": path,
+                    "line": line_number,
+                    "marker": label,
+                    "on_named_path": path in named,
+                })
     return found