docs/tools: address PR #391 CodeRabbit findings; add advisory MD029 markdownlint check

[mixmansoundude]

Summary

Two small follow-ups held back while PR #391's CI was in-flight (never push while a run is in-flight -- would cancel it), now rebased onto main post-merge.

• Address both CodeRabbit findings on PR ci: fix conda_avail circular gate silently skipping conda-full self-tests #391 (which merged as ci: fix conda_avail circular gate silently skipping conda-full self-tests #391 / 06e5b35):
  • Added a "CORRECTION, 2026-07-27" paragraph to CLAUDE.md's Active Backlog item 7, noting its own conda_avail mechanism was later found broken (see item 15) -- item 7's own entry never mentioned this.
  • Converted the new Active Backlog item 15 from a literal 15. ordered-list marker to a bullet with the number spelled out in prose, since CLAUDE.md's Active Backlog uses numbers as stable cross-referenced identifiers, not literal sequential list order -- a literal 15. collides with markdown's own ordered-list renumbering rules.
• Add an advisory-only MD029 markdownlint check to the sanity sweep, per an explicit "if you think appropriate" / "do as you recommend" request, so the exact CodeRabbit finding above doesn't need a human reviewer to catch next time:
  • New .markdownlint-cli2.jsonc (repo root): disables every rule except MD029 (ordered-list-item-prefix), scoped to CLAUDE.md only. A full default pass produces ~2700 hits on CLAUDE.md alone (~99% line-length, a rule this repo has never followed); README.md/docs/*.md use their own unreviewed numbering schemes.
  • New check_markdownlint() step in tools/run_sanity_sweep.sh, wired in right after the delimiter check. Never fails the sweep (matches check_pyflakes()'s own established advisory-only precedent).
  • Documents the underlying convention (bullets with the number spelled out in prose for new Active Backlog items, literal N. reserved for the historically-grandfathered item 7) in AGENTS.md, alongside the markdownlint-cli2 npm install instructions.

Test plan

• python -m compileall -q .
• python tools/check_delimiters.py run_setup.bat
• markdownlint-cli2 CLAUDE.md (exactly the expected 1 permanent baseline finding -- item 7's own solo "7.")
• python -m yamllint .github/workflows/
• actionlint -oneline .github/workflows/*.yml
• PowerShell AST parse sweep (tests/.ps1, tools/.ps1)
• python -m pytest tests/test_*.py -q (437 passed, 2 skipped)
• Full tools/run_sanity_sweep.sh run, all checks OK

Claude-Session: https://claude.ai/code/session_015xbWLPbiaKVsobB9FZy8kS

---

Generated by Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: cbb8ea0b-3719-447b-8b01-f2736bba3263

📥 Commits

Reviewing files that changed from the base of the PR and between 065cd67 and 476b3d6.

📒 Files selected for processing (1)

• CLAUDE.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (8)

• GitHub Check: Batch syntax/run check (contract-uv-fail)
• GitHub Check: Batch syntax/run check (real)
• GitHub Check: Batch syntax/run check (conda-full)
• GitHub Check: Batch syntax/run check (uv-dl-fallback)
• GitHub Check: Batch syntax/run check (uv)
• GitHub Check: Batch syntax/run check (contract-uv)
• GitHub Check: Batch syntax/run check (cache)
• GitHub Check: Batch syntax/run check (justme-test)

🧰 Additional context used

📓 Path-based instructions (3)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Use GitHub Actions results, especially Job Summary, grouped log tails, and PR failure comments, as the source of truth; local runs are advisory and Windows behavior is authoritative.
Do not weaken tests, remove logging or artifacts, delete or skip checks, or change workflow triggers, permissions, or retention.
Work in the order Plan, check the plan, execute, then self-check/tests; make minimal surgical patches and add professional comments explaining non-obvious constraints.
If code cannot be traced to a requirement, add derived requirement: <why needed> and propose a requirement; when a Windows-only bug is found, consider adding a safe delimiter-check heuristic.
Push every commit before it can be lost; after every push, poll CI, fix red CI before proceeding, and do not open a PR until the final commit is green and diagnostic outputs have been verified.
After green CI, verify the relevant setup log, expected artifact inventory, and non-decreasing NDJSON row counts on the diagnostics site.

Files:

• CLAUDE.md

CLAUDE.md

📄 CodeRabbit inference engine (AGENTS.md)

Run the advisory MD029-only Markdown lint for CLAUDE.md; new Active Backlog entries must be bullets with the number in prose, reserving literal ordered-list syntax for grandfathered item 7.

Files:

• CLAUDE.md

**/*.{md,mdx}

📄 CodeRabbit inference engine (AGENTS.md)

Cite run_setup.bat locations in documentation by stable label/subroutine name rather than line number; use line numbers only when immediately necessary.

Files:

• CLAUDE.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-07-27T05:49:55.855Z
Learning: Keep knowledge documentation current in the same commit when a change teaches or invalidates a lesson; edit existing entries rather than only appending.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-07-27T05:49:55.855Z
Learning: Implement exactly one missing feature slice and add exactly one missing test per iteration loop.

Learnt from: CR
Repo: mixmansoundude/Python_vs_Windows

Timestamp: 2026-07-27T05:49:55.855Z
Learning: Run the full mandatory sanity sweep before every commit, extending the ASCII file list to cover touched files.

🔇 Additional comments (1)

CLAUDE.md (1)

747-748: LGTM!

---

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Updated Markdown linting guidance with repo-specific numbering conventions for the “Active Backlog” section.
  • Documented a CI gating issue affecting conda_avail-dependent conda-full self-tests and recorded the correction approach.
  • Noted that the conda_avail explanation remains for later re-wiring.
• Chores
  • Added an advisory Markdown lint check to the sanity sweep (ordered-list numbering only), running as a warning and not failing if the lint tool is unavailable.

Walkthrough

Adds advisory MD029-only Markdown linting to the sanity sweep and documents the conda_avail CI gating correction, including skipped tests, reverted conditions, and deferred re-wiring.

Changes

Markdown linting

Layer / File(s)	Summary
Advisory Markdown lint integration .markdownlint-cli2.jsonc, AGENTS.md, tools/run_sanity_sweep.sh	Configures markdownlint-cli2 to enforce only MD029, documents its use for CLAUDE.md, and adds an optional non-failing sanity-sweep step.

Conda CI correction documentation

Layer / File(s)	Summary
Document conda_avail gating correction CLAUDE.md	Records the circular skip affecting real/conda-full self-tests, the reverted dependent conditions, and the deferred re-wiring of conda_avail.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• mixmansoundude/Python_vs_Windows#390: Adds the conda_avail step and conditional conda-full lane gating documented as corrected here.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly names the main docs/tools changes and the new advisory MD029 markdownlint check.
Description check	✅ Passed	The description accurately summarizes the CLAUDE.md, markdownlint, AGENTS.md, and sanity-sweep changes in the PR.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/pipreqs-fallback-maintenance-49jhr9

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CLAUDE.md`:
- Around line 747-750: Update the referenced GitHub Actions evidence in
CLAUDE.md to use the actual numeric workflow run IDs for the API checks, or
explicitly relabel efd7a5c and fd7a046 as commit SHAs instead of run IDs. Keep
the PR and step details unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e26c5cdf-b789-4217-9baf-f3b6f000d1fc

📥 Commits

Reviewing files that changed from the base of the PR and between 06e5b35 and 065cd67.

📒 Files selected for processing (4)

• .markdownlint-cli2.jsonc
• AGENTS.md
• CLAUDE.md
• tools/run_sanity_sweep.sh

📜 Review details

⏰ Context from checks skipped due to timeout. (9)

• GitHub Check: auto_merge
• GitHub Check: Batch syntax/run check (cache)
• GitHub Check: Batch syntax/run check (uv-dl-fallback)
• GitHub Check: Batch syntax/run check (real)
• GitHub Check: Batch syntax/run check (contract-uv-fail)
• GitHub Check: Batch syntax/run check (uv)
• GitHub Check: Batch syntax/run check (contract-uv)
• GitHub Check: Batch syntax/run check (conda-full)
• GitHub Check: Batch syntax/run check (justme-test)

🧰 Additional context used

📓 Path-based instructions (3)

**/*

📄 CodeRabbit inference engine (AGENTS.md)

**/*: Follow Plan -> Check the plan -> Execute -> Self-check/tests; make minimal surgical changes and test before submission.
Push every commit before it can be lost; after each push, wait for CI, fix failures before proceeding, and do not open a PR until the final commit is green and diagnostics are verified.

**/*: Update the relevant knowledge document in the same commit when a change teaches or invalidates a lesson: docs/agent-interconnect.md, docs/agent-lessons-learned.md, or docs/agent-ndjson.md.
Before every commit, run the repository sanity sweep, including Python compilation/linting, delimiter checks, workflow linting, PowerShell parsing, and pytest; extend the ASCII file list to cover touched files.

Files:

• tools/run_sanity_sweep.sh
• AGENTS.md
• CLAUDE.md

**/*.md

📄 CodeRabbit inference engine (AGENTS.md)

Cite run_setup.bat locations by label or subroutine name rather than line number in documentation.

Files:

• AGENTS.md
• CLAUDE.md

CLAUDE.md

📄 CodeRabbit inference engine (AGENTS.md)

Run the advisory MD029-only Markdown lint for CLAUDE.md; new Active Backlog items must be bullets with the number in prose, not literal ordered-list markers.

Files:

• CLAUDE.md

🔇 Additional comments (5)

.markdownlint-cli2.jsonc (1)

1-37: LGTM!

AGENTS.md (2)

243-243: LGTM!

---

259-261: LGTM!

tools/run_sanity_sweep.sh (1)

90-108: 🗄️ Data Integrity & Integration

No NDJSON/artifact wiring needed here. tools/run_sanity_sweep.sh is a local sanity helper, not a CI step, so this new advisory markdownlint check does not need an NDJSON row or a batch-check.yml test-logs upload path.

			> Likely an incorrect or invalid review comment.

CLAUDE.md (1)

709-724: LGTM!