<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/configuration/linting-cutoff-policy/">
  <id>https://docs.spec-kitty.ai/configuration/linting-cutoff-policy/</id>
  <title>Linting Cutoff Policy</title>
  <updated>2026-02-25T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/configuration/linting-cutoff-policy/"/>
  <summary>How the CI Quality workflow applies commitlint and markdownlint only to commits and files after the 2026-02-25 cutoff, so legacy history is not retroactively failed.</summary>
  <content type="html">&lt;span id=&quot;linting-cutoff-policy&quot;&gt;&lt;/span&gt;
&lt;h2 id=&quot;overview&quot;&gt;Overview&lt;/h2&gt;
&lt;p&gt;The CI Quality workflow includes linting checks for commit messages (commitlint) and markdown files (markdownlint). These checks were introduced to maintain code quality going forward, but they run in &lt;strong&gt;informational mode&lt;/strong&gt; rather than blocking mode.&lt;/p&gt;
&lt;h2 id=&quot;cutoff-date&quot;&gt;Cutoff Date&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Cutoff Date: 2026-02-25T00:00:00Z&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;This date corresponds to when the linting infrastructure was introduced into the codebase.&lt;/p&gt;
&lt;h2 id=&quot;behavior&quot;&gt;Behavior&lt;/h2&gt;
&lt;h3 id=&quot;commit-message-linting-commitlint&quot;&gt;Commit Message Linting (commitlint)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Only commits created &lt;strong&gt;after&lt;/strong&gt; the cutoff date are checked&lt;/li&gt;
&lt;li&gt;Commits before the cutoff date are ignored&lt;/li&gt;
&lt;li&gt;Non-compliant commits trigger a PR comment but do not fail the workflow&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;markdown-linting-markdownlint&quot;&gt;Markdown Linting (markdownlint)&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Only markdown files last modified &lt;strong&gt;after&lt;/strong&gt; the cutoff date are checked&lt;/li&gt;
&lt;li&gt;Files last modified before the cutoff date are ignored&lt;/li&gt;
&lt;li&gt;Non-compliant files trigger a PR comment but do not fail the workflow&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;workflow-integration&quot;&gt;Workflow Integration&lt;/h2&gt;
&lt;p&gt;When linting failures are detected on a pull request:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;The linting steps complete with &lt;code dir=&quot;auto&quot;&gt;continue-on-error: true&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;A PR comment is posted with:
&lt;ul&gt;
&lt;li&gt;List of non-compliant commits (with commit hash and message)&lt;/li&gt;
&lt;li&gt;List of non-compliant markdown files&lt;/li&gt;
&lt;li&gt;A note that these are informational warnings&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;The workflow continues and does not fail due to linting issues&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;non-blocking-checks&quot;&gt;Non-Blocking Checks&lt;/h2&gt;
&lt;p&gt;The following checks remain &lt;strong&gt;blocking&lt;/strong&gt; (will fail the workflow):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Unit tests&lt;/li&gt;
&lt;li&gt;Integration tests&lt;/li&gt;
&lt;li&gt;Python linting (ruff)&lt;/li&gt;
&lt;li&gt;Type checking (mypy)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The following checks are &lt;strong&gt;informational&lt;/strong&gt; (will not fail the workflow):&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Commit message linting (commitlint)&lt;/li&gt;
&lt;li&gt;Markdown style linting (markdownlint)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;Security scans (bandit, pip-audit) do not run on pull requests. They run in the
&lt;code dir=&quot;auto&quot;&gt;security-scans&lt;/code&gt; job of the nightly workflow (&lt;code dir=&quot;auto&quot;&gt;ci-nightly.yml&lt;/code&gt;), which fails the
nightly and opens a deduped issue on a new finding: bandit at MEDIUM severity
and above against &lt;code dir=&quot;auto&quot;&gt;scripts/ci/bandit-baseline.json&lt;/code&gt;, pip-audit against the
commented ignore list &lt;code dir=&quot;auto&quot;&gt;scripts/ci/pip-audit-ignore.txt&lt;/code&gt;.&lt;/p&gt;
&lt;h2 id=&quot;updating-the-cutoff-date&quot;&gt;Updating the Cutoff Date&lt;/h2&gt;
&lt;p&gt;If you need to update the cutoff date:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Edit &lt;code dir=&quot;auto&quot;&gt;.github/workflows/ci-quality.yml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Find the “Determine commit range and cutoff date” step&lt;/li&gt;
&lt;li&gt;Update the &lt;code dir=&quot;auto&quot;&gt;CUTOFF_DATE&lt;/code&gt; variable&lt;/li&gt;
&lt;li&gt;Commit and push the change&lt;/li&gt;
&lt;/ol&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;- &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;name&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;Determine commit range and cutoff date&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;id&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;commit_range&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;|&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;# Set cutoff date for linting (when linting was introduced)&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;CUTOFF_DATE=&quot;2026-02-25T00:00:00Z&quot;  # &amp;#x3C;-- Update this line&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;    &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;echo &quot;cutoff_date=$CUTOFF_DATE&quot; &gt;&gt; &quot;$GITHUB_OUTPUT&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;rationale&quot;&gt;Rationale&lt;/h2&gt;
&lt;p&gt;This approach allows the project to:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Avoid blocking existing work&lt;/strong&gt;: Historical commits and files are not affected&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Encourage best practices&lt;/strong&gt;: New commits and files are checked&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Provide visibility&lt;/strong&gt;: Developers are informed of issues without workflow failures&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Maintain flexibility&lt;/strong&gt;: The cutoff date can be adjusted as needed&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Preserve workflow structure&lt;/strong&gt;: The tiered workflow (lint → tests → sonar) remains intact&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;best-practices&quot;&gt;Best Practices&lt;/h2&gt;
&lt;p&gt;While linting failures are informational, developers should still:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Follow conventional commit message format for new commits&lt;/li&gt;
&lt;li&gt;Ensure markdown files follow the project’s style guide&lt;/li&gt;
&lt;li&gt;Address linting issues when convenient&lt;/li&gt;
&lt;li&gt;Review PR comments for guidance on compliance&lt;/li&gt;
&lt;/ol&gt;</content>
</entry>
