Skip to content

CI: 'Linting' and 'Validation' jobs cannot pass on any PR — PARTIALLY FIXED, ROOT CAUSE REMAINS #1961

Closed

Description

@eleshar

Status: REOPENED — Partially Fixed But Root Issues Remain

CRITICAL: This issue was prematurely closed as "completed" on 2026-08-20, but ~3,099 markdown linting errors remain unresolved in critical directories.


Problems

1. ❌ Linting — ~3,099 markdownlint errors remain (MD022/MD032/MD031)

Current Status:

  • Total errors in repo: 3,099 errors
  • Errors in target directories (.github/agents/, agents/, docs/): 2,557 errors
  • PR fix: Restore frontmatter validator CLI flag parsing #2193 attempted fix by excluding .github/reports/** and .github/projects/** from linting
  • But this only masked the problem in those directories — the main backlog remains

Error breakdown (target directories):

  • .github/agents/release.agent.md: Multiple MD031/MD032 violations
  • agents/ai-readiness-estimator-agent/README.md: 20+ MD022 violations (headings not surrounded by blank lines)
  • docs/ files: Widespread MD022/MD032 violations

Root Causes:

  • MD022: Headings not surrounded by blank lines
  • MD031: Code fences not surrounded by blank lines
  • MD032: Lists not surrounded by blank lines

What PR #2193 Did NOT Fix:

  • PR fix: Restore frontmatter validator CLI flag parsing #2193 added .markdownlintignore exclusions for .github/reports/** and .github/projects/**
  • This stopped the linting job from FAILING on those directories
  • But the ~3,099 errors in .github/agents/, agents/, and docs/ still exist
  • The CI linting job still fails when checking changed files in these directories

2. ⚠️ Validation — validate:footers still not properly scoped

Current Status:

  • PR fix: resolve CI linting blocker in #1961 #2171 created a basic validate:footers implementation
  • But it doesn't properly handle the --changed-only --base --head flags from the workflow
  • The validator is not respecting the changed-files-only scope that CI requires

Impact

❌ CI checks still fail on any PR that:

  • Modifies .github/agents/ files (2,557+ errors)
  • Modifies agents/ files (significant portion of the 2,557)
  • Modifies docs/ files (significant portion of the 2,557)

❌ Related PRs blocked:

  • Any PR touching agent documentation
  • Any PR adding/updating documentation
  • Branch name validation and other checks still cascading failures

Evidence

Output from npm run lint:md (current develop):

Summary: 3099 error(s)

Sample errors in target directories:

.github/agents/release.agent.md:161 error MD032/blanks-around-lists
agents/ai-readiness-estimator-agent/README.md:11 error MD022/blanks-around-headings
docs/[multiple files] error MD022/blanks-around-headings

Definition of Done

✅ Must complete ALL of the following:

  • Fix all 2,557 markdown linting errors in .github/agents/, agents/, docs/
  • Verify npm run lint:md returns 0 errors in those directories
  • Fix validate:footers to properly handle --changed-only flag
  • Run full CI check on a test PR to confirm all validators pass
  • Create a follow-up PR with fixes that passes all CI checks without overrides

Notes for Implementer

  • Do NOT close this issue again until all errors are actually fixed
  • Do NOT use .markdownlintignore to hide the problem — fix the actual markdown
  • All 2,557 errors need to be addressed for CI to be truly fixed
  • This is the root cause why PR docs: Phase 5A Week 3 — Testing & Documentation Framework #1936 and others required admin merge overrides

Activity

  1. linear-code commented on Aug 17, 2026

    @linear-code
  2. github-actions commented on Aug 17, 2026

    @github-actions
    Contributor

    ⚠️ This issue was closed but does not meet our completion requirements.

    Issues preventing closure:

    • Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)
    • Issue is flagged status:needs-more-info — resolve outstanding feedback first

    What you can do:

    1. Fix the issue: Edit this issue and update the body with the correct template sections (DoR and DoD sections)
    2. Reopen it: Click the "Reopen issue" button on this page to reopen after fixing
    3. Force close: Add the meta:force-close label to this issue if closure is necessary despite incomplete requirements

    After fixing: The issue will no longer show this warning and can be closed normally.
    Need help? See the issue template guide: https://github.com/lightspeedwp/.github/issues/new/choose

  3. github-actions commented on Aug 17, 2026

    @github-actions
    Contributor

    ⏱️ Aging and SLA annotation

    • Age: 3 day(s)
    • SLA state: Within SLA
    • Thresholds: warn at 7 days, breach at 14 days
    • Last updated: 2026-08-20T18:58:32.283Z

    Maintained by project-meta-sync workflow.

  4. added a commit that references this issue on Aug 20, 2026
  5. github-actions commented on Aug 20, 2026

    @github-actions
    Contributor

    Milestone Allocation

    
    
  6. ashleyshaw commented on Aug 20, 2026

    @ashleyshaw
    Member

    Reopened for Proper Resolution

    This issue was closed prematurely after PR #2171 only addressed the missing validate:footers script. However, the core problem remains unresolved:

    Still Outstanding

    Linting job failure — ~3,500 markdownlint errors (MD022/MD032 violations) across agent documentation files remain unfixed:

    • Files like agents/zendesk-support-agent/shared/core-prompt.md have massive backlog of violations
    • These errors block the lint:md step on every PR
    • npm run lint:all cannot pass until this is resolved

    What Was Fixed

    What Still Needs Fixing

    • ❌ ~3,500 markdownlint errors need resolution (via formatting commit, rule relaxation, or scope changes)
    • ❌ CI linting continues to fail on every PR

    Action Required

    Implement one of the original options:

    1. Run markdownlint-cli2 --fix repo-wide as a single formatting commit
    2. Relax offending rules in .markdownlint-cli2.jsonc
    3. Scope lint:md to changed files only

    Reopened: 2026-08-20 — Incomplete resolution detected


    Generated by Claude Code

  7. 1 remaining item

  8. github-actions commented on Aug 20, 2026

    @github-actions
    Contributor

    Milestone Allocation

    
    
  9. changed the title [-]CI: 'Linting' and 'Validation' jobs cannot pass on any PR[/-] [+]CI: 'Linting' and 'Validation' jobs cannot pass on any PR — PARTIALLY FIXED, ROOT CAUSE REMAINS[/+] on Aug 20, 2026
  10. github-actions commented on Aug 21, 2026

    @github-actions
    Contributor

    Milestone Allocation

    
    
  11. self-assigned this
    on Sep 8, 2026
  12. github-actions commented on Sep 8, 2026

    @github-actions
    Contributor

    ⚠️ Bare Labels Detected

    This issue has labels that are not in the canonical taxonomy:

    • migrate:priority:normal
    • migrate:status:needs-more-info
    • migrate:type:bug
    • status:needs-template-fix

    Valid Canonical Labels

    Please use labels with a prefix from the canonical taxonomy:

    • Type: type:bug, type:feature, type:task, type:documentation, etc.
    • Status: status:needs-triage, status:in-progress, status:done, etc.
    • Priority: priority:critical, priority:high, priority:normal, priority:low
    • Area: area:ci, area:docs, area:labels, area:security, etc.
    • Meta: meta:needs-changelog, meta:duplicate, meta:blocked, etc.

    For the complete list, see .github/labels.yml.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Fields

Priority

None yet

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions