Add markdown-exclude-globs Input to validate-task.yml

[ptr727]

Fixes #924.

validate-task.yml's Lint Markdown step hardcoded globs: '**/*.md' with no workflow_call input to narrow or exclude paths, and .markdownlint-cli2.jsonc is declared "fidelity": "verbatim", "whole": true in spec/files.json, so a downstream repo has no way to edit it locally either. Blog vendors the PaperMod theme under themes/PaperMod/ and carries an imported WordPress content archive under content/**, both git-tracked, so adopting the hub's validate-task.yml as documented would start linting several hundred posts and an entire vendored theme tree Blog does not author and cannot keep clean, breaking the PR gate rather than improving it.

The fix

An optional markdown-exclude-globs input, appended after **/*.md in the Lint Markdown step's own globs: block, so a caller only ever narrows the default, never restates or replaces it:

    with:
      markdown-exclude-globs: |
        !content/**
        !themes/*/**

Empty by default. Verified this doesn't error against the action's own source (DavidAnson/markdownlint-cli2-action's dist/index.mjs at the pinned SHA): getInput("globs").split(separator).filter(String), so the blank line an empty input leaves behind is dropped, not passed to the CLI as an empty glob. Confirmed with a local test fixture too: without the exclude globs, content/** and themes/** files are linted (and fail); with them, only the caller's own files are.

docs/reusable-workflows.md's "Adopting the Gates" section documents the new input with Blog's own case as the example.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

@ptr727, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 15 minutes

Limit details: You’ve used all 10 included reviews currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

Wait for the limit to reset, then comment @coderabbitai review or push new commits to the PR.

An organization admin can change what happens after included review limits in Billing.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ec541893-3ba2-46ef-9c32-4b88538edbc9

📥 Commits

Reviewing files that changed from the base of the PR and between 614604d and f3fdd7c.

📒 Files selected for processing (2)

• .github/workflows/validate-task.yml
• docs/reusable-workflows.md

---

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

[qodo-code-review]

PR Summary by Qodo

Add markdown-exclude-globs input to validate-task markdown lint

✨ Enhancement ⚙️ Configuration changes 📝 Documentation 🕐 10-20 Minutes

AI Description

• Add optional markdown-exclude-globs workflow_call input to narrow Markdown lint scope.
• Append exclude globs after default **/*.md to avoid replacing the baseline behavior.
• Document how to exclude vendored/imported content when adopting the reusable workflow.

Diagram

graph TD
  A["Caller workflow"] --> B["validate-task.yml"] --> C["markdownlint action"] --> D["Markdown files"]
  E["markdown-exclude-globs input"] --> B
  F["reusable-workflows.md"] --> A

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Allow full globs override (replace default **/*.md)

• ➕ Maximum flexibility for callers with atypical repository layouts
• ➕ Avoids implicit behavior by making callers explicitly specify all globs
• ➖ Higher foot-gun risk: callers can accidentally stop linting Markdown entirely
• ➖ More verbose for typical repos that just want a couple of exclusions

2. Make markdownlint config file overridable per repo

• ➕ Lets repos tune markdownlint rules and file selection without new workflow inputs
• ➕ Keeps workflow surface area smaller long-term
• ➖ Conflicts with the current "verbatim/whole" packaging model for shared specs
• ➖ More complex governance: local divergence can undermine consistent fleet gating

3. Add a first-class exclude input (separate from globs) if supported

• ➕ Clearer semantics than embedding '!path/**' lines into globs
• ➕ Potentially easier validation/escaping of patterns
• ➖ Depends on action/CLI interface; may not be available or stable
• ➖ Would still require composing inputs into the action call

Recommendation: The chosen approach (append-only markdown-exclude-globs) is a good balance: it preserves the baseline **/*.md linting while letting downstream repos exclude vendored/imported trees without duplicating defaults. Compared to a full override, it reduces misconfiguration risk and keeps adoption simple.

Files changed (2) +29 / -2

Documentation (1) +16 / -0

reusable-workflows.mdDocument markdown-exclude-globs for repos with vendored/imported content +16/-0

Document markdown-exclude-globs for repos with vendored/imported content

• Expands the adoption documentation with an example showing how to exclude content and theme directories via markdown-exclude-globs. Clarifies that the reusable workflow appends excludes after **/*.md so callers narrow rather than replace defaults.

docs/reusable-workflows.md

Other (1) +13 / -2

validate-task.ymlAdd workflow_call input to append Markdown exclude globs +13/-2

Add workflow_call input to append Markdown exclude globs

• Introduces an optional workflow_call input (markdown-exclude-globs) and appends it to the markdownlint-cli2-action globs list after the default **/*.md. Adds inline commentary clarifying that empty input results in no extra globs being passed.

.github/workflows/validate-task.yml

[Copilot]

🟡 Changes recommended

The new input is documented/commented as “only ever narrowing” the default, but callers can append arbitrary non-negated globs and thereby expand what gets linted, so the contract text should be corrected for accuracy.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a workflow_call input to the hub’s reusable validation workflow so downstream repos can exclude tracked-but-not-authored Markdown trees (e.g., vendored themes or imported archives) from the markdownlint gate, and documents the adoption pattern.

Changes:

• Add optional markdown-exclude-globs input to .github/workflows/validate-task.yml and append it to the markdownlint globs: list after **/*.md.
• Document the new input and an example use case in docs/reusable-workflows.md.

File summaries

File	Description
.github/workflows/validate-task.yml	Exposes a caller-provided markdownlint glob exclusion hook via workflow_call input.
docs/reusable-workflows.md	Documents how downstream repos can use markdown-exclude-globs when adopting the validate task.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. markdown-exclude-globs breaks Title Case ✗ Dismissed 📘 Rule violation ⚙ Maintainability

Description

The PR title uses lowercase words (for example markdown-exclude-globs, to) instead of Title Case
for significant words. This violates the repository's PR title Title Case requirement.

Code

.github/workflows/validate-task.yml[6]

+# No required inputs, markdown-exclude-globs is the one optional input, and CODECOV_TOKEN is the one optional secret, since coverage upload is best-effort.

Relevance

●●● Strong

The repository accepts capitalization/style corrections; Title Case compliance is a deterministic
PR-title fix.

PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2826422 requires Title Case for PR titles (with only a fixed set of short bind
words allowed to be lowercase in the middle). The provided PR title `Add markdown-exclude-globs
Input to validate-task.yml` contains significant lowercase words, so it does not meet the rule.

Rule 2826422: Enforce Title Case for Pull Request Titles with Lowercase Short Bind Words

---

2. Workflow header summary block ✗ Dismissed 📜 Skill insight ⚙ Maintainability

Description

The workflow begins with a file-level summary comment block describing the workflow contents. This
violates the rule that forbids file header summary blocks.

Code

.github/workflows/validate-task.yml[R3-6]

# The fleet validation gate, hosted here once and reached by every repo's test-pull-request stub and its own publish-release stub.
# Three jobs: lint (the fleet doc-lint block plus language lint by tree detection, the prose gate, and the repo gate), unit-test (a generic dotnet test or uv run pytest, skipped where the caller has no test project), and validate (the validate hook, a repo's own domain checks such as an ESPHome compile, a Hugo build, a KiCad ERC, a codegen-drift check, or PowerShell tests).
# No permissions beyond contents: read where a job needs one, since every job here only checks out and reads.
-# No required inputs, and CODECOV_TOKEN is the one optional secret, since coverage upload is best-effort.
+# No required inputs, markdown-exclude-globs is the one optional input, and CODECOV_TOKEN is the one optional secret, since coverage upload is best-effort.

Relevance

●●● Strong

Recent workflow comment corrections were accepted, supporting removal of prohibited header summary
comments.

PR-#621

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2826694 forbids file header summary blocks. The workflow contains a multi-line
summary header (lines 3-7), and this PR modifies that header (line 6), keeping the prohibited
pattern in the changed area.

.github/workflows/validate-task.yml[3-7]
Skill: comment-and-doc-style

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`.github/workflows/validate-task.yml` starts with a multi-line file header summary block that restates what the workflow contains, which is disallowed.

## Issue Context
License/provenance headers are exempt, but this block is descriptive boilerplate.

## Fix Focus Areas
- .github/workflows/validate-task.yml[3-7]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Two-line input comment block ✓ Resolved 📜 Skill insight ⚙ Maintainability

Description

The new markdown-exclude-globs input is preceded by a two-line explanatory comment block. The
second line reads as elaboration rather than a genuine constraint that the code cannot carry.

Code

.github/workflows/validate-task.yml[R11-12]

+      # Appended after '**/*.md' rather than replacing it, so a caller only ever narrows the default rather than restating it.
+      # A repo that vendors a theme or imports content it does not author excludes that tree here instead of failing the gate on prose it cannot fix.

Relevance

●●● Strong

Recent accepted feedback favors splitting or shortening long explanatory comments and documentation
lines.

PR-#901
PR-#621

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2826677 requires comments to be one line by default, with a second line only for
genuine constraints. The added two-line block above markdown-exclude-globs (lines 11-12) provides
extended explanation across lines, triggering the rule.

.github/workflows/validate-task.yml[10-12]
Skill: comment-and-doc-style

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new `markdown-exclude-globs` input comment is two lines, where the second line is explanatory elaboration rather than a necessary constraint.

## Issue Context
Repository policy expects single-line comments by default; add a second line only when expressing a constraint the code cannot carry.

## Fix Focus Areas
- .github/workflows/validate-task.yml[10-12]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View medium (1)

4. Multi-sentence doc line ✗ Dismissed 📜 Skill insight ✧ Quality

Description

The newly added Markdown prose uses multiple sentences on a single line. This violates the rule
requiring one sentence per line in multi-line comment/doc prose.

Code

docs/reusable-workflows.md[352]

+A repo that vendors a theme or imports content it does not author narrows the Lint Markdown step's glob instead. Blog carries a WordPress archive and the PaperMod theme, for instance. `.markdownlint-cli2.jsonc` is declared `"fidelity": "verbatim", "whole": true` in `spec/files.json`, so it is not locally editable:

Relevance

●●● Strong

Recent documentation feedback accepted splitting long multi-clause prose into shorter sentences or
lines.

PR-#901
PR-#383

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 2826725 requires one sentence per line (no multi-sentence run-ons on a single
line). The added prose at lines 352 and 366 each contains multiple sentences on one line.

docs/reusable-workflows.md[352-352]
docs/reusable-workflows.md[366-366]
Skill: comment-and-doc-style

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The added documentation paragraphs contain multiple sentences on the same line, which violates the "one sentence per line" rule.

## Issue Context
This repository's documentation style requires exactly one sentence per line and no mid-sentence wrapping.

## Fix Focus Areas
- docs/reusable-workflows.md[352-366]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 68 rules

✅ Skills: 5 invoked

  comment-and-doc-style

  dotnet-codestyle

  python-codestyle

  shell-codestyle

  workflow-ci-contract

✅ Web pages:

  🌐 action.yml at main · DavidAnson/markdownlint-cli2-action

  🌐 DavidAnson/markdownlint-cli2-action

  🌐 https://raw.githubusercontent.com/DavidAnson/markdownlint-cli2-action/v23.1.0/action.yml

  +18 more

Review mode: ⚖️ Balanced: This changes a reusable workflow's public input and Markdown lint behavior, so it carries configuration and caller-compatibility risk despite being localized.

Tip of the day

💡 Did you know, you can turn these tips off under Display preferences

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[Copilot]

🟢 Approval recommended

The change is small, scoped, and matches the stated intent; the only finding is a minor comment-accuracy improvement.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

.github/workflows/validate-task.yml:39

• The comment relies on a specific implementation detail (globs.split(...).filter(String)) that doesn’t match the action’s current parsing (it trims entries and filters truthy values). Prefer describing the observable behavior (blank/whitespace-only lines are ignored), so the comment stays correct even if the action’s internal code changes while behavior remains the same.

      # An empty markdown-exclude-globs leaves a blank line here, which the action's own globs.split(separator).filter(String) drops, so the default caller passes nothing extra.

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The new optional input is correctly plumbed through without changing default behavior, and the documentation matches the implementation.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite