* ci: docs-only fast path + minimal docs CI
Skip the full pytest matrix + browser smoke on docs/CHANGELOG/README-only PRs
(required checks still report green fast via a fail-safe 'changes' gate job), and
add a lightweight Docs CI: critical_markdown_check.py (rendering-breaks only, not
style) + lychee broken-link check. Detection fails safe (any uncertainty or any
non-doc path -> full suite runs).
* ci: tighten docs-only detection — extension/type wins over name
A code file whose NAME contains README/CHANGELOG (scripts/CHANGELOG_stamp.py,
static/README_renderer.js) was wrongly classified docs-only, which would SKIP the
test suite on a real code change. Now a path is docs only by doc extension, exact
doc basename, or non-code file under docs/. Verified against 16 cases incl. every
code-with-docs-name trap.
* ci: fix all Fable+Codex gate findings on docs-only fast path
- BLOCKER: drop *.txt from is_docs (requirements.txt is a dep manifest — a bump
would have skipped the whole test matrix). docs = *.md/.markdown/.rst + bare
doc basenames only; strict allowlist, no docs/** denylist.
- Rename hole: use 'git diff --name-only --no-renames' so a rename src/app.py ->
docs.md reveals the code-side deletion instead of collapsing to the doc dest.
- SECURITY: docs-ci.yml no longer interpolates untrusted fork-PR filenames into
run: via ${{ }} (which executes $() in a crafted name). File list flows through
a file + mapfile-as-args; lychee gets a fixed glob, not the attacker list.
Added permissions: contents: read.
- Wedge belt-and-suspenders: 'if: ${{ always() }}' on the required test +
browser-smoke jobs so a failed 'changes' job can't skip them; step guards treat
missing/empty docs_only as run-full.
- critical_markdown_check.py: corrected the core rule — a newline in the whitespace
AROUND a link destination is valid CommonMark (was a false positive); only a
newline INSIDE the destination token, or an unclosed inline link, breaks
rendering. Verified full agreement with the markdown-it-py reference parser +
0 false positives on all 43 repo docs. Also blank 4-space indented code + multi
backtick spans. Reworded 'block the merge' -> 'break rendering' (non-required).
* ci: address Codex re-gate — lint always() + markdown title/unclosed cases
- Add if: always() to the lint job too (not currently required, but future-proof
against the wedge class if it's ever promoted).
- critical_markdown_check.py: handle two more CommonMark cases Codex found —
a newline inside a "title" string is legal (skip), and a newline-terminated
unclosed dest ([x](url\n at EOF/EOL with no close) is broken (flag). After the
destination token ends, valid continuations are ')' or a title opener (" ' ();
bare text after the newline is the real break. Verified full agreement with
markdown-it-py across 13 cases + 0 FP on all 43 repo docs.
* ci: model the CommonMark inline-dest grammar (root-cause fix for markdown checker)
Round-3 gate found the title heuristic caused sibling regressions: a parenthesized
multi-line title (url (a\nb)) was falsely flagged, and a quote glued into the URL
(exa"part) was wrongly treated as a title-start and skipped. Rather than patch more
heuristics, replace the ad-hoc newline logic with _scan_inline_dest(), which walks
the actual grammar: skip leading ws -> bare dest (balanced parens, ends at ws or the
depth-0 ')') or <angle> dest -> after ws the next char must be ')' or a real title
opener (" ' () -> else the destination is split across the line (broken). Verified
FULL agreement with markdown-it-py across 20 adversarial cases (incl. both round-3
regressions, balanced parens, angle dests, multiline titles) + 0 FP on all 43 docs.
* test: pytest suite for critical_markdown_check (42 cases)
Durable, repeatable verification for the docs-CI markdown checker: 19 verdict cases
+ 19 cross-checked against the markdown-it-py CommonMark reference (skips cleanly if
the lib is absent) + 3 code-span-safety cases + empty/no-link inputs. Covers both
round-3 regressions (parenthesized multi-line title valid; quote-glued-in-URL broken),
balanced parens, angle destinations, and multiline titles. 42 passed.
* ci: fix 2 grammar edges from Codex round-4 (escaped-> in angle dest, unbalanced bare-dest parens)
- Angle dest <...> now honors backslash escapes: [x](<foo\>bar>) renders (the \> is
escaped), was a false positive.
- Bare dest must have BALANCED parens: [x](foo(\n)) does not render (a '(' stays open
when whitespace ends the token) — now returns split, was a false negative.
Both verified against markdown-it-py + added as pytest cases. 46 passed, 0 FP on 43 docs.
* ci: escaped-newline in angle dest is still a raw newline (Codex round-5)
<...> escape handling skipped the char after backslash including a newline, so
[x](<foo\<nl>>) returned ok but doesn't render (blockquote on line 2). An escaped
newline inside an angle destination is still a raw newline -> split. Preserves
[x](<foo\>bar>). Added regression case. 48 pytest cases pass, 0 FP on 43 docs.
* ci: mirror escaped-newline guard to bare dest (Codex round-6, GFM-correct)
The angle branch already treated backslash-newline as split; the bare branch skipped
it, so [x](foo\<nl>bar) returned ok. GFM/CommonMark forbid line endings in bare
destinations (GitHub's cmark-gfm won't render it), though markdown-it-py permissively
does. Since these docs are GitHub-rendered we follow GFM: flag it. Added as a
SPEC_DIVERGENT test case (verdict-asserted, excluded from the permissive parser
cross-check). 49 pytest pass, escaped paren/space still valid, 0 FP on 43 docs.
* ci: delimiter-aware title scan (Codex round-7 unclosed-link false negatives)
Naive text.find(')') matched the TITLE's own ')' not the link's outer ')', so
[x](foo (title), [x](<foo> (title), [x](foo "title" all returned ok despite being
unclosed links. Now parse the title to its actual closing delimiter ("..", '..',
or a (..) that forbids nested unescaped '(' per CommonMark), then require the link's
own ')' after optional whitespace. Also catches the nested-paren-title break
[x](foo (a (b) c)). Verified vs markdown-it-py; escaped parens + single-quoted
titles containing parens still valid. 61 pytest pass, 0 FP on 43 docs.
* ci: remove unused variable (ruff F841 in critical_markdown_check)
The CI lint gate (ruff forward E9+F+B on new lines) caught a dead 'stripped =
line.lstrip()' leftover from an earlier refactor in _blank_code — the fence
detection matches on the raw line. Removed. No behavior change (61 pytest pass).
---------
Co-authored-by: nesquena-hermes <nesquena-hermes@users.noreply.github.com>
