Skip to content

docs: retire stale plan claims and fix mutation-baseline contradictions - #124

Open
DLANSAMA wants to merge 1 commit into
mainfrom
docs/plans-and-mutation-cleanup
Open

docs: retire stale plan claims and fix mutation-baseline contradictions#124
DLANSAMA wants to merge 1 commit into
mainfrom
docs/plans-and-mutation-cleanup

Conversation

@DLANSAMA

Copy link
Copy Markdown
Owner

Finishes the documentation reconciliation started in #120 (number sync) and #121/#122 (user-facing accuracy). No files deleted, no code changed.

Residual table re-verified against source

docs/plans/post-audit-gameplan.md carries a residual table from a 2026-07-31 audit. I re-checked each row against current main instead of trusting the snapshot. It was wrong in both directions.

Listed open, actually closed:

ID Evidence
S5 utils.py:63-67 is now a 4-line shim delegating to jsonio.redact_url_credentials. Both spellings return https://192.168.1.5/a.stl for the table's own bob:secret123@… repro — there is no weaker second implementation
A4 mqtt_port is wired end to end: context.py:89,137printer.py:339mqtt_tls.py:143mqtt_tls.py:162 client.connect(resolved_ip, _mqtt_port(printer), …). Doctor no longer reports a port that is ignored
T1 pyproject.toml:44 pins textual>=8.0,<9.0 — the <2.0 cap is gone (#115)
A3, Q1, S1, B1, R1, R3 Closed by #119, the camera opt-in work, and the TUI merge

Recorded as closed, but is not:

  • Q4test: stop stubbing paho in sys.modules #116's commit message says "paho-mqtt is a hard runtime dependency. Tests import the real package." It did remove all 81 sys.modules.setdefault("paho…") calls (0 remain), but tests/bambu_test_base.py:26-29 still unconditionally assigns MagicMock() to sys.modules["paho" | "paho.mqtt" | "paho.mqtt.client"] at import time and never restores them. Real paho is installed and importable. That is both an untested-dependency gap and the import-order dependence AGENTS.md forbids.

Re-confirmed open, with current evidence — P1, Q5, Q6, A1, A2, S3, R2, T2/WS4, W3.4. Notably _numeric_values("400abc") returns [] while _numeric_values("400") returns [400.0] (slicer/options.py:162-175), so a typo'd temperature override skips the bound check entirely. A1's target also moved from bambu_cli.cli to bambu_cli.cliparse.

Number staleness

Both gameplan headers led with pre-#119/#120 figures presented as current state. They now lead with measured values (1499 non-live, 90.99% Linux / 90.68% Windows over 8368 statements, floor 86, Python 3.10/3.12/3.14) and keep the old ones explicitly marked historical — including the a-plus W1 sizing, which was computed from the 89.4% baseline and is now noted as roughly 125 remaining hits rather than 280.

mutation-baseline.md

Three internal contradictions:

  1. The per-module table claimed it "reconciles to the 50.7% total, so they are measured rather than estimated." It does not. The seven rows are the entire only_mutate scope (pyproject.toml:159-167), yet they sum to 2010 mutants (990 survived + 1020 killed) against a headline 2091 (1027 + 1061 + 3 timeout) — 81 unattributed. There is no eighth module to absorb them.
  2. "Residual survivors here should be cosmetic" for slicer/output.py — the same file already disproves this 40 lines earlier at 21.8%, 269 survivors, the largest single pocket.
  3. "re-run mutmut on slicer/output.py and update the per-module row" — already done on 2026-08-04.

Two superseded plan docs kept, not deleted

interactive-mode-plan.md and tui-plan.md already carried "Implemented — kept as the design record, no longer a to-do list" banners, so they were not masquerading as live plans, and two live pointers still reference them: session.py:8 cites the interactive plan as that module's design record, and quality-roadmap.md:641 points at the tui-plan cut note "if it is revisited." The one real defect — tui-plan.md keeping imperative "all implementation work goes on feat/tui" instructions after its own banner — is folded into the historical framing.

Vendor attribution removed

These two plan docs named AI products in their audience/source lines, in a section heading, and in the commit-trailer rule. Replaced with neutral wording; the trailer rule now reads "AI/session attribution trailers" instead of naming a product. References to the local-only agent notes filename are left intact, since removing the name would void the rule that depends on it.

Gates

  • pytest -W error::ResourceWarning -m "not live"1499 passed, 1 deselected, 13 subtests passed, 8368 statements, 91.0%
  • test_docs_consistency.py + test_docs_links.py25 passed
  • Markdown only (4 files); no .py, workflow, or packaging changes, so ruff/mypy/bandit are unaffected by this diff.

Re-verified the 2026-07-31 post-audit residual table against current main
rather than trusting the audit snapshot. Four residuals it lists as open are
closed, and one the follow-up notes recorded as closed is not:

- S5 closed: utils.py:63-67 is now a shim delegating to jsonio; both spellings
  redact the audit's own repro identically. No weaker second implementation.
- A4 closed: mqtt_port is wired end to end (context -> printer -> mqtt_tls
  _mqtt_port -> client.connect). Doctor no longer reports a port it ignores.
- T1 closed: textual is pinned >=8.0,<9.0 (#115), not <2.0.
- A3/Q1/S1/B1/R1/R3 closed by #119, the camera opt-in work, and the TUI merge.
- Q4 NOT closed: #116 removed 81 setdefault stubs across 33 files but
  tests/bambu_test_base.py:26-29 still assigns MagicMock to sys.modules for
  paho at import time and never restores it, which is also order-dependent.
- P1, Q5, Q6, A1, A2, S3, R2, T2/WS4, W3.4 re-confirmed open with current
  file:line evidence; A1's target moved to bambu_cli.cliparse.

Plan headers carried numbers from before #119/#120 and read as live state.
Both gameplans now lead with measured current values (1499 non-live, 90.99%
Linux / 90.68% Windows over 8368 statements, floor 86, Python 3.10/3.12/3.14)
and keep the old figures marked as historical, including the a-plus W1 sizing
that was derived from the 89.4% baseline.

mutation-baseline.md claimed its per-module table reconciles to the 50.7%
headline. It does not: the seven rows are the whole only_mutate scope yet sum
to 2010 mutants against a headline 2091, leaving 81 unattributed (37 survived,
41 killed, 3 timeout). Also corrected the "residual survivors should be
cosmetic" prediction, which the same file already disproves at 21.8% with 269
survivors, and the stale "re-run mutmut on slicer/output.py" note, which was
already done on 2026-08-04.

tui-plan.md kept imperative branch instructions after its own "implemented"
banner; folded into the historical framing.

Also drops AI-vendor attribution from these two plan docs: the audience and
source lines, the "pasteable brief for a new <vendor> session" heading, and
the trailer rule, which now reads "AI/session attribution trailers" instead of
naming a product. References to the local-only agent notes filename are left
intact where removing the name would void the rule.

Docs only, no code changes. Gates: 1499 passed / 1 deselected, 91.0% total;
test_docs_consistency + test_docs_links 25 passed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant