Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 12 additions & 13 deletions .markdownlint-cli2.jsonc
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,19 @@
// MD029 (ordered-list-item-prefix) is the one exception, kept enabled here: it is the
// exact rule that caught a real, if minor, semantic issue on PR #391 -- CLAUDE.md's
// "Active Backlog" section uses numbers as STABLE IDENTIFIERS (cross-referenced from
// Closed Backlog by number), not literal sequential list order, so a second numbered
// item added there can silently collide with markdown's own ordered-list numbering
// rules. See docs/agent-lessons-learned.md and AGENTS.md's "Recurring tooling" section
// for the convention this backstops: new Active Backlog items should be bullets with
// the number spelled out in prose, not literal "N." markers -- reserve literal ordered-
// list syntax for the historically-grandfathered item 7.
// docs/agent-closed-backlog.md by number), not literal sequential list order, so a
// second numbered item added there can silently collide with markdown's own ordered-
// list numbering rules. See docs/agent-lessons-learned.md and AGENTS.md's "Recurring
// tooling" section for the convention this backstops: new Active Backlog items should
// be bullets with the number spelled out in prose, not literal "N." markers.
//
// One PERMANENT, EXPECTED finding: item 7's own solo "7." entry. Every MD029 style
// (tested: one, ordered, one_or_ordered, zero) requires a list -- even a one-item list --
// to start at "1."/"0.", so there is no style option that accepts "7." as a valid lone
// starting number. Rewriting item 7's own giant, heavily-cross-referenced entry to a
// bullet (like item 15) was judged disproportionate risk for a lint cosmetic given its
// size -- so this ONE finding on line ~473 is a known, accepted baseline, not a bug.
// Treat any OTHER finding (a 2nd hit) as the thing actually worth investigating.
// Formerly one PERMANENT, EXPECTED finding here: item 7's own solo literal "7." entry,
// grandfathered as a known baseline because rewriting its giant, heavily-cross-
// referenced text to a bullet was judged disproportionate for a lint cosmetic. Item 7
// was closed and moved out of CLAUDE.md entirely (to docs/agent-closed-backlog.md) on
// 2026-07-31, taking its literal "7." marker with it -- this check should now come back
// fully clean with ZERO findings. Any finding here going forward is a real regression
// worth investigating, not an expected baseline.
//
// Run via `tools/run_sanity_sweep.sh` (advisory only, never fails the sweep) or directly:
// markdownlint-cli2 CLAUDE.md
Expand Down
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ THEN stop and open/append a PR. One loop = one change set.
- Preferred actionlint install: `curl -sSLO https://github.com/rhysd/actionlint/releases/latest/download/actionlint_linux_amd64.tar.gz && tar -xzf actionlint_linux_amd64.tar.gz actionlint && ./actionlint -oneline .`
- If the release tarball resolves to "Not Found" due to proxy filtering, install with Go instead: `go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.1` and add `/root/.local/share/mise/installs/go/1.24.3/bin` to `PATH` before running `actionlint`. On this runner `go env GOPATH` resolves to `/root/go`, so the compiled binary also lives under `/root/go/bin` -- add that directory to `PATH` if the mise shim is absent.
- JSON: `jq -e .` over `*.json`.
- Markdown (`CLAUDE.md` specifically): `npm install -g markdownlint-cli2`, then `markdownlint-cli2 CLAUDE.md` (or via `tools/run_sanity_sweep.sh`, which runs this automatically -- see "Recurring tooling" below). Deliberately narrow: `.markdownlint-cli2.jsonc` at the repo root disables every rule except `MD029` (ordered-list-item-prefix). This repo's docs are a long-form historical record, not GFM-polished prose -- a full default pass produces ~2700 hits on `CLAUDE.md` alone, almost all line-length (`MD013`), a rule this repo has no interest in enforcing. `MD029` is kept because it backstops a real convention: `CLAUDE.md`'s "Active Backlog" section uses item numbers as **stable cross-referenced identifiers** (e.g. "(Active Backlog item 14)"), not literal sequential list order, so a new numbered item can silently collide with markdown's own ordered-list renumbering rules if written as a literal `N.` marker. **New Active Backlog items should be bullets (`- **...`) with the number spelled out in prose, not literal ordered-list markers** -- reserve literal `N.` syntax for the historically-grandfathered item 7, which the lint config already treats as a known, permanent, accepted baseline finding (see that file's own comments for why). This check is advisory only (never fails the sweep) and scoped to `CLAUDE.md` only -- `README.md`/`docs/*.md` use their own numbering schemes (e.g. "Finding N") that were not reviewed against this convention.
- Markdown (`CLAUDE.md` specifically): `npm install -g markdownlint-cli2`, then `markdownlint-cli2 CLAUDE.md` (or via `tools/run_sanity_sweep.sh`, which runs this automatically -- see "Recurring tooling" below). Deliberately narrow: `.markdownlint-cli2.jsonc` at the repo root disables every rule except `MD029` (ordered-list-item-prefix). This repo's docs are a long-form historical record, not GFM-polished prose -- a full default pass produces ~2700 hits on `CLAUDE.md` alone, almost all line-length (`MD013`), a rule this repo has no interest in enforcing. `MD029` is kept because it backstops a real convention: `CLAUDE.md`'s "Active Backlog" section uses item numbers as **stable cross-referenced identifiers** (e.g. "(Active Backlog item 14)"), not literal sequential list order, so a new numbered item can silently collide with markdown's own ordered-list renumbering rules if written as a literal `N.` marker. **New Active Backlog items should be bullets (`- **...`) with the number spelled out in prose, not literal ordered-list markers.** (Item 7 -- the one entry that historically used a literal `7.` marker instead, grandfathered as a known MD029 exception -- was closed and moved to `docs/agent-closed-backlog.md` on 2026-07-31, so this check should now come back fully clean with zero findings; a finding here again is a real regression, not an expected baseline.) This check is advisory only (never fails the sweep) and scoped to `CLAUDE.md` only -- `README.md`/`docs/*.md` use their own numbering schemes (e.g. "Finding N") that were not reviewed against this convention.
- Generic paired-delimiter scan for `.bat`, `.cmd`, `.ps1`, `.py`, `.yml`, `.yaml`, `.json`:
- `tools/check_delimiters.py` validates (), {}, [], and quotes " ' (handle escapes and ignore comments when practical), plus a growing set of targeted `.bat`/`.cmd`/`.ps1` heuristics for regressions that have actually bitten this repo -- each one has a `# derived requirement:` comment in the source explaining the exact incident it guards against. Current heuristics: `-like` PowerShell wildcard patterns embedded in batch strings with an unmatched `[`; `set VAR="value"` instead of `set "VAR=value"`; unquoted `%VAR%` in a file-system command (`del`/`if exist`/`mkdir`/`copy`/`move`/`pushd`); unescaped `|` inside a `for /f` backtick subshell; PowerShell `-or`/`-and` outside a conditional; and (added 2026-07-25, see docs/agent-lessons-learned.md's "`rem` needs a space after it" entry) a `rem` comment line whose very next character is not whitespace, which cmd.exe parses as an attempt to run a literal command rather than a comment.
- For `.bat/.cmd`, treat `^` as escape and `REM`/`::` as comment starts; avoid over-parsing redirection symbols.
Expand Down
Loading
Loading