Skip to content

[bug] markdownlint lints node_modules/ — vendored READMEs fail Lint, silently halting pr-review #1450

Closed

Description

@don-petry

Problem

Lint fails on PR #1449 with errors from node_modules/bats/README.md — a vendored dependency's README that no PR authored. #1449 touches zero markdown files.

node_modules/bats/README.md:9:1   MD033/no-inline-html Inline HTML [Element: div]
node_modules/bats/README.md:59:3  MD004/ul-style Unordered list style
node_modules/bats/README.md:59:5  MD051/link-fragments Link fragments should be valid
…

Cause: .markdownlint-cli2.jsonc ignores only .claude/**, frameworks/**, prompts/**. node_modules/** is not ignored — and node_modules is not in .gitignore either. So whenever node_modules/ exists on the runner at the time markdownlint runs, it lints third-party package docs and fails on style rules those packages were never written against.

Why this is more than a lint nuisance

A red Lint is not a required check, but compute_ci_status (scripts/lib/ci-status.sh) has no required/non-required notion — any failing check makes it return failing, and review-one-pr.sh:141 then skips the review silently, posting nothing on the PR. That is #1427 AC #7.

So this defect silently halts pr-review on any PR it hits. That exact failure mode cost roughly six hours of zero merges earlier today via a different red check (template-drift, #1435/#1436). This is a second, independent trigger for the same halt.

It is currently blocking #1449, which implements #687 — itself the blocker for completing the #1184 channel migration.

Acceptance Criteria

  1. node_modules/** is excluded from markdown linting — added to the ignores array in .markdownlint-cli2.jsonc.
  2. node_modules/ is added to .gitignore, so a local install can never be committed and never enters a diff.
  3. Lint passes on a PR whose CI has node_modules/ present on the runner; feat: implement issue #687 — [Phase 2] Generalized CI compliance test: reject SHA / # main pins on any first-party reusable #1449 is the regression case.
  4. The ignore list is reviewed for the same class of gap — any other directory populated by a package manager or vendored at build time (not just node_modules) is excluded, so this does not recur under a different name.
  5. No repo-authored markdown is newly exempted: the change must not silence lint on files this repo actually owns. Diff the pre/post file set that markdownlint evaluates and confirm only third-party paths are removed.

Tasks / Subtasks

Dev Notes

References

Activity

  1. don-petry commented on Aug 3, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead Implementation Plan

    Issue: #1450 — [bug] markdownlint lints node_modules/ — vendored READMEs fail Lint, silently halting pr-review

    Scope

    Exclude node_modules/ (and other package-manager/build-populated dirs) from markdownlint so third-party/vendored READMEs never fail Lint, and gitignore node_modules/ so an install can't be committed — completing the existing frameworks/**/prompts/** vendored-exclusion pattern.

    Implementation Checklist

    Tests to Write

    Test Command

    bash .dev-lead/scripts/dev-lead-lint.sh + scripts/run-bats.sh (repo lint/test suite); markdownlint evaluated-set diff for AC #5

  2. don-petry commented on Aug 3, 2026

    @don-petry
    CollaboratorAuthor

    Dev-Lead: Implementation Complete

    Plan Execution

    Test Results

    Reproduction + fix proof (markdownlint-cli2 v0.23.2 / markdownlint v0.41.1, run with node_modules/ present on disk — the #1449 condition):

    BEFORE (original config, no node_modules ignore):
      Finding: **/*.md !.claude/** !frameworks/** !prompts/**
      Linting: 116 files
      Summary: 7 issues in 1 file
      node_modules/bats/README.md:9  MD033/no-inline-html  (div/picture/source/img)
      node_modules/bats/README.md:59 MD004/ul-style, MD051/link-fragments
      node_modules/bats/README.md:60 MD004/ul-style
      exit=1   ← the exact #1450 failure signature
    
    AFTER (this change):
      Finding: **/*.md !.claude/** !frameworks/** !prompts/** !node_modules/** !vendor/** !dist/** !build/** !coverage/**
      Linting: 113 files
      Summary: 0 issues in 0 files
      exit=0   ← Lint green
    

    Evaluated-file-set diff (AC #5): 116 → 113 files. The three files removed are all third-party:
    node_modules/bats/README.md, node_modules/bats/LICENSE.md, node_modules/bats/man/README.md.
    No repo-owned markdown is newly exempted — confirmed there is zero .md under any vendor/, dist/,
    build/, or coverage/ path in the tree, so the AC #4 preventive globs remove nothing today; they
    only guard the future.

    Required repo lint:

    bash .dev-lead/scripts/dev-lead-lint.sh   → all checks passed (shellcheck on 102 files, 4 agent profiles, CODEOWNERS)
    

    Relevant unit suite (.gitignore-emitting logic — vendored bats 1.13.0):

    bats tests/test_seed_repo_template.bats   → 41/41 ok
    

    (The full run-bats.sh list from lint.yml was not exercised locally: no test references either changed
    file, the change is config-only, and most suites require gh/network. dev-lead-lint.sh — the required
    gate — passes.)

    Files Changed

    • .markdownlint-cli2.jsonc: added node_modules/**, vendor/**, dist/**, build/**, coverage/** to ignores, completing the existing vendored-exclusion pattern (frameworks/**, prompts/**).
    • .gitignore: added node_modules/ to the per-repo (non-baseline) section.

    Notes

    • Phase 2 (TDD) exception: configuration-only change with no behavioral code path; verification is the before/after evaluated-file-set diff above rather than a new unit test.
    • Follow-up worth a separate issue: node_modules/ is currently tracked in git (33 files under node_modules/bats/, committed on main). This change stops future commits and stops linting them, satisfying all five ACs, but a .gitignore entry does not untrack already-committed files. A git rm -r --cached node_modules (leaving the working copy) would fully honor AC Go-live improvements for PR review agent #2's "never enters a diff" intent. I did not include it here because it is outside this issue's stated two-file scope and touches git tracking of files this issue did not enumerate — flagging it for a human decision.
  3. added 2 commits that reference this issue on Aug 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugBug reportsdev-leadFor dev-lead agent pickup

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions