From d770824aa9efebf70ed7a6ba6ebf024dd7ef5f36 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Sat, 28 Mar 2026 20:56:56 +0800 Subject: [PATCH] feat(markdown): replace markdownlint-cli2 with rumdl - Switch The markdown lint wrapper and repo config to rumdl. - Regenerate Third-party metadata and fixture coverage for rumdl. - Fix Prompt and docs markdown drift surfaced by rumdl. --- .markdownlint-cli2.jsonc | 25 ------------------- .rumdl.toml | 11 ++++++++ DEVELOPMENT.md | 2 +- THIRD_PARTY_LICENSES.md | 6 +++-- THIRD_PARTY_NOTICES.md | 5 ++-- docs/testing/docs-freshness-rules.md | 2 ++ prompts/actionable-advice.md | 1 - prompts/actionable-knowledge.md | 5 ++-- prompts/parallel-first.md | 1 - .../plan-issue-delivery-main-agent-init.md | 1 - prompts/plan-issue-delivery-subagent-init.md | 1 - scripts/README.md | 2 +- scripts/ci/markdownlint-audit.sh | 9 ++++--- scripts/generate-third-party-artifacts.sh | 17 +++++++------ tests/test_third_party_artifacts.py | 1 + 15 files changed, 40 insertions(+), 49 deletions(-) delete mode 100644 .markdownlint-cli2.jsonc create mode 100644 .rumdl.toml diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc deleted file mode 100644 index 866d230e..00000000 --- a/.markdownlint-cli2.jsonc +++ /dev/null @@ -1,25 +0,0 @@ -{ - "config": { - "default": true, - - // Staged tightening: enforce paragraph readability while keeping - // command snippets/tables/headings stable. - "MD013": { - "line_length": 140, - "code_blocks": false, - "headings": false, - "tables": false - }, - "MD024": { - "siblings_only": true - }, - "MD022": true, - "MD032": true, - "MD033": true, - "MD038": true, - "MD041": false, - "MD056": true, - "MD058": true, - "MD060": true - } -} diff --git a/.rumdl.toml b/.rumdl.toml new file mode 100644 index 00000000..2ee95f1c --- /dev/null +++ b/.rumdl.toml @@ -0,0 +1,11 @@ +[global] +disable = ["MD041"] + +[MD013] +line-length = 140 +code-blocks = false +headings = false +tables = false + +[MD024] +siblings-only = true diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 480c11b4..862a7064 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -14,7 +14,7 @@ - `requirements-dev.txt` includes `pytest`, `semgrep`, `ruff`, `mypy`, and `pyright` - System tools - `git` (required by lint scripts for tracked-file discovery) - - `node`/`npx` (required by markdown lint) + - `node`/`npx` (required by `rumdl` markdown lint) - `zsh` and `shellcheck` (macOS: `brew install shellcheck`; Ubuntu: `sudo apt-get install -y shellcheck zsh`) - `nils-cli` (Homebrew: `brew tap sympoies/tap && brew install nils-cli`; provides `plan-tooling`, `api-*`, `semantic-commit`) diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md index 2d53697a..ce00002f 100644 --- a/THIRD_PARTY_LICENSES.md +++ b/THIRD_PARTY_LICENSES.md @@ -34,13 +34,14 @@ Not included: | `@playwright/cli` | npm via npx --package | `@playwright/cli@latest` | floating (@latest) | `Apache-2.0` | [microsoft/playwright-cli](https://github.com/microsoft/playwright-cli) | | `agent-browser` | npm via npx --package | `agent-browser@latest` | floating (@latest) | `Apache-2.0` | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | | `chrome-devtools-mcp` | npm via npx | `chrome-devtools-mcp@latest` | floating (@latest) | `Unknown (check npm package metadata)` | [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | -| `markdownlint-cli2` | npm via npx | `markdownlint-cli2@0.21.0` | pinned (0.21.0) | `MIT` | [DavidAnson/markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) | +| `rumdl` | npm via npx | `rumdl@0.1.62` | pinned (0.1.62) | `MIT` | [rvben/rumdl](https://github.com/rvben/rumdl) | | `shellcheck` | Homebrew / apt | `brew install shellcheck / apt-get install -y shellcheck` | floating (package-manager resolved) | `GPL-3.0-or-later` | [koalaman/shellcheck](https://github.com/koalaman/shellcheck) | | `nils-cli` | Homebrew formula | `brew install nils-cli` | floating (formula latest) | `MIT OR Apache-2.0` | [graysurf/nils-cli](https://github.com/graysurf/nils-cli) | ## Declaration Sources - `requirements-dev.txt` +- `.rumdl.toml` - `scripts/ci/markdownlint-audit.sh` - `skills/tools/browser/playwright/scripts/playwright_cli.sh` - `skills/tools/browser/agent-browser/scripts/agent-browser.sh` @@ -53,7 +54,8 @@ Not included: ## Deterministic Input Fingerprints - `requirements-dev.txt` SHA256: `3ec1558abe1f337577861f60fd6824af6ad1b68436187819dedcd184b3548f2e` -- `scripts/ci/markdownlint-audit.sh` SHA256: `ce0e42cbbe8e274c135a4d7a859ce1d239d5b7e78c1891d837f3f327b5486b16` +- `.rumdl.toml` SHA256: `31667aa68116c0811cc8afcfa726ab5b6da25deb47cf737e54c51a7910a9cf5d` +- `scripts/ci/markdownlint-audit.sh` SHA256: `2f7a9fbabc675f3f7db2ce5930dd1d144f614d01b094d468e05619ae063189a1` - `skills/tools/browser/playwright/scripts/playwright_cli.sh` SHA256: `36a188349ae575e2ffd7fe47cad0f8b86317032f4f7bd75a1598b5d16eddf4e0` - `skills/tools/browser/agent-browser/scripts/agent-browser.sh` SHA256: `c9daa00c327c0258d8496b1e8a5cea3827af9cb73ee357682b670918ce7a1d94` - `scripts/chrome-devtools-mcp.sh` SHA256: `cf92382116a78c6d1a3dc5a1ac5d9be8498bdb17187cf26b26dae098718f8cd8` diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 8a73b01d..a2309482 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -19,14 +19,15 @@ Third-party notice obligations are tracked by linking each component to its upst | `@playwright/cli` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [microsoft/playwright-cli](https://github.com/microsoft/playwright-cli) | | `agent-browser` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | | `chrome-devtools-mcp` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | -| `markdownlint-cli2` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [DavidAnson/markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2) | +| `rumdl` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [rvben/rumdl](https://github.com/rvben/rumdl) | | `shellcheck` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [koalaman/shellcheck](https://github.com/koalaman/shellcheck) | | `nils-cli` | Use upstream license/notice files from the linked project. No separate vendored NOTICE file is distributed in this repository. | [graysurf/nils-cli](https://github.com/graysurf/nils-cli) | ## Deterministic Input Fingerprints - `requirements-dev.txt` SHA256: `3ec1558abe1f337577861f60fd6824af6ad1b68436187819dedcd184b3548f2e` -- `scripts/ci/markdownlint-audit.sh` SHA256: `ce0e42cbbe8e274c135a4d7a859ce1d239d5b7e78c1891d837f3f327b5486b16` +- `.rumdl.toml` SHA256: `31667aa68116c0811cc8afcfa726ab5b6da25deb47cf737e54c51a7910a9cf5d` +- `scripts/ci/markdownlint-audit.sh` SHA256: `2f7a9fbabc675f3f7db2ce5930dd1d144f614d01b094d468e05619ae063189a1` - `skills/tools/browser/playwright/scripts/playwright_cli.sh` SHA256: `36a188349ae575e2ffd7fe47cad0f8b86317032f4f7bd75a1598b5d16eddf4e0` - `skills/tools/browser/agent-browser/scripts/agent-browser.sh` SHA256: `c9daa00c327c0258d8496b1e8a5cea3827af9cb73ee357682b670918ce7a1d94` - `scripts/chrome-devtools-mcp.sh` SHA256: `cf92382116a78c6d1a3dc5a1ac5d9be8498bdb17187cf26b26dae098718f8cd8` diff --git a/docs/testing/docs-freshness-rules.md b/docs/testing/docs-freshness-rules.md index 79c4585c..691e08ee 100644 --- a/docs/testing/docs-freshness-rules.md +++ b/docs/testing/docs-freshness-rules.md @@ -45,6 +45,7 @@ Any discovered reference to a missing path is reported as a stale reference. The audit script parses only the block below. + ## Scoped docs @@ -74,3 +75,4 @@ REQUIRED_PATH|scripts/test.sh REQUIRED_PATH|skills/tools/agent-doc-init/scripts/agent_doc_init.sh REQUIRED_PATH|docs/testing/script-smoke.md + diff --git a/prompts/actionable-advice.md b/prompts/actionable-advice.md index eb2ec1ab..d7b3eca2 100644 --- a/prompts/actionable-advice.md +++ b/prompts/actionable-advice.md @@ -3,7 +3,6 @@ description: Ask clarifying questions when underspecified; otherwise provide act argument-hint: question --- - You are an engineering advisor. Your job is to produce explicit, actionable instructions (not vague suggestions) for the user’s question. USER QUESTION $ARGUMENTS diff --git a/prompts/actionable-knowledge.md b/prompts/actionable-knowledge.md index 34e2748b..171852ae 100644 --- a/prompts/actionable-knowledge.md +++ b/prompts/actionable-knowledge.md @@ -3,7 +3,6 @@ description: Humanities-aware tutor prompt with a clear baseline, multiple lense argument-hint: question / concept / confusion --- - You are a **knowledge tutor + problem clarifier** for general audiences (humanities-methods aware). Your job is to help the user learn a concept, clear up confusion, or decide what to focus on next—using **explicit, actionable guidance** (no vague encouragement). @@ -14,9 +13,9 @@ CONTEXT (optional but recommended) - Goal: - Current understanding: - Domain / scenario: -- Depth: +- Depth: `[high-level | practical | rigorous]` - Time budget: <5 min | 30 min | 2 hours | days> -- Constraints: +- Constraints: `[math level, preferred style, language, no jargon, etc]` CORE PRINCIPLES (Humanities version) diff --git a/prompts/parallel-first.md b/prompts/parallel-first.md index 6ce22c38..40d909b6 100644 --- a/prompts/parallel-first.md +++ b/prompts/parallel-first.md @@ -3,7 +3,6 @@ description: Enable a parallel-first policy for this thread and prefer delegate- argument-hint: preferences (optional) --- - Enable **parallel-first mode** for this conversation thread. PREFERENCES (optional) $ARGUMENTS diff --git a/prompts/plan-issue-delivery-main-agent-init.md b/prompts/plan-issue-delivery-main-agent-init.md index f86040c9..e6e6ff87 100644 --- a/prompts/plan-issue-delivery-main-agent-init.md +++ b/prompts/plan-issue-delivery-main-agent-init.md @@ -3,7 +3,6 @@ description: Init prompt for the orchestration-only main agent in plan-issue-del argument-hint: optional overrides for repo/plan/issue/sprint/grouping --- - You are the Main Agent for plan-driven issue delivery. Mission diff --git a/prompts/plan-issue-delivery-subagent-init.md b/prompts/plan-issue-delivery-subagent-init.md index de913cc2..d0947e87 100644 --- a/prompts/plan-issue-delivery-subagent-init.md +++ b/prompts/plan-issue-delivery-subagent-init.md @@ -3,7 +3,6 @@ description: Init prompt for implementation-owned subagents in plan-issue-delive argument-hint: optional overrides for task/worktree/branch/pr-mode --- - You are a Subagent for plan-driven sprint implementation. Mission diff --git a/scripts/README.md b/scripts/README.md index 1ebc8db0..ef01d896 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -71,7 +71,7 @@ scripts/ ### CI and docs/artifact audits - `scripts/ci/markdownlint-audit.sh` - - Markdown lint wrapper (`markdownlint-cli2`). + - Markdown lint wrapper (`rumdl` via `npx` + `.rumdl.toml`). - `scripts/ci/third-party-artifacts-audit.sh` - Verifies required third-party artifacts and drift. - `scripts/ci/docs-freshness-audit.sh` diff --git a/scripts/ci/markdownlint-audit.sh b/scripts/ci/markdownlint-audit.sh index deef94b7..e6433855 100755 --- a/scripts/ci/markdownlint-audit.sh +++ b/scripts/ci/markdownlint-audit.sh @@ -6,7 +6,7 @@ usage() { Usage: markdownlint-audit.sh [--strict] -Run repository Markdown lint checks using markdownlint-cli2 and the repo config. +Run repository Markdown lint checks using rumdl and the repo config. Options: --strict Treat lint failures as hard failures (exit 1) @@ -46,9 +46,9 @@ if ! command -v npx >/dev/null 2>&1; then exit 2 fi -config_file="$repo_root/.markdownlint-cli2.jsonc" +config_file="$repo_root/.rumdl.toml" if [[ ! -f "$config_file" ]]; then - echo "error: missing markdownlint config: $config_file" >&2 + echo "error: missing rumdl config: $config_file" >&2 exit 2 fi @@ -63,7 +63,8 @@ if [[ "${#md_files[@]}" -eq 0 ]]; then fi lint_cmd=( - npx --yes markdownlint-cli2@0.21.0 + npx --yes rumdl@0.1.62 + check --config "$config_file" "${md_files[@]}" ) diff --git a/scripts/generate-third-party-artifacts.sh b/scripts/generate-third-party-artifacts.sh index 118e58d7..4e07b11b 100755 --- a/scripts/generate-third-party-artifacts.sh +++ b/scripts/generate-third-party-artifacts.sh @@ -129,6 +129,7 @@ def upstream_label(url: str) -> str: requirements_path = repo_root / "requirements-dev.txt" +rumdl_config = repo_root / ".rumdl.toml" markdown_script = repo_root / "scripts" / "ci" / "markdownlint-audit.sh" playwright_script = repo_root / "skills" / "tools" / "browser" / "playwright" / "scripts" / "playwright_cli.sh" agent_browser_script = repo_root / "skills" / "tools" / "browser" / "agent-browser" / "scripts" / "agent-browser.sh" @@ -140,6 +141,7 @@ dockerfile = repo_root / "Dockerfile" required_inputs = [ requirements_path, + rumdl_config, markdown_script, playwright_script, agent_browser_script, @@ -205,11 +207,11 @@ npm_meta = { "license": "Unknown (check npm package metadata)", "upstream": "https://github.com/ChromeDevTools/chrome-devtools-mcp", }, - "markdownlint-cli2": { - "component": "markdownlint-cli2", + "rumdl": { + "component": "rumdl", "ecosystem": "npm via npx", "license": "MIT", - "upstream": "https://github.com/DavidAnson/markdownlint-cli2", + "upstream": "https://github.com/rvben/rumdl", }, } @@ -252,17 +254,17 @@ chrome_devtools_spec = extract_once( r"cmd=\(npx -y (chrome-devtools-mcp@[^\s\)]+)\)", "chrome-devtools-mcp spec", ) -markdownlint_spec = extract_once( +rumdl_spec = extract_once( markdown_script, - r"npx --yes (markdownlint-cli2@[0-9A-Za-z._-]+)", - "markdownlint-cli2 spec", + r"npx --yes (rumdl@[0-9A-Za-z._-]+)\s+check", + "rumdl spec", ) npm_specs = [ ("@playwright/cli", playwright_spec, "skills/tools/browser/playwright/scripts/playwright_cli.sh"), ("agent-browser", agent_browser_spec, "skills/tools/browser/agent-browser/scripts/agent-browser.sh"), ("chrome-devtools-mcp", chrome_devtools_spec, "scripts/chrome-devtools-mcp.sh"), - ("markdownlint-cli2", markdownlint_spec, "scripts/ci/markdownlint-audit.sh"), + ("rumdl", rumdl_spec, "scripts/ci/markdownlint-audit.sh"), ] for package_name, package_spec, source in npm_specs: @@ -305,6 +307,7 @@ rows.append( source_paths = [ "requirements-dev.txt", + ".rumdl.toml", "scripts/ci/markdownlint-audit.sh", "skills/tools/browser/playwright/scripts/playwright_cli.sh", "skills/tools/browser/agent-browser/scripts/agent-browser.sh", diff --git a/tests/test_third_party_artifacts.py b/tests/test_third_party_artifacts.py index a59ad1de..eefca995 100644 --- a/tests/test_third_party_artifacts.py +++ b/tests/test_third_party_artifacts.py @@ -31,6 +31,7 @@ def _prepare_third_party_fixture(tmp_path: Path) -> Path: "scripts/generate-third-party-artifacts.sh", "scripts/ci/third-party-artifacts-audit.sh", "requirements-dev.txt", + ".rumdl.toml", "scripts/ci/markdownlint-audit.sh", "skills/tools/browser/playwright/scripts/playwright_cli.sh", "skills/tools/browser/agent-browser/scripts/agent-browser.sh",