clckernel 1.2.19 → 2.0.0

package/tools/check_scope.py

@@ -11,29 +11,43 @@ import json
 import os
 import pathlib
 import re
-import subprocess
 import sys
 
-
-def _get_changed_files(target_dir: str) -> list[str] | None:
-    """Return list of changed files from git diff, or None on failure."""
-    for ref in ("HEAD~1", "--cached"):
-        try:
-            args = ["git", "diff", "--name-only"]
-            if ref == "--cached":
-                args.append("--cached")
-            else:
-                args.append(ref)
-            out = subprocess.check_output(
-                args, cwd=target_dir,
-                stderr=subprocess.DEVNULL, text=True,
-            )
-            files = [f.strip() for f in out.splitlines() if f.strip()]
-            if files:
-                return files
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            continue
-    return None
+# Sibling helper shipped next to the guards; works both as a script and when
+# loaded by audit.py through importlib.
+_TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _TOOLS_DIR not in sys.path:
+    sys.path.insert(0, _TOOLS_DIR)
+import _changes  # noqa: E402
+
+
+# A path with an extension, optionally starting with a dot
+# (src/a.js, .clckernel.yaml, .github/workflows/ci.yml).
+_PATH = r"\.?[A-Za-z_][\w./-]+\.\w+"
+# A dot-path without extension (.gitignore, .githooks/pre-commit): only
+# recognised in backticks, so prose such as "- .NET support" stays prose.
+_DOT_PATH = r"\.[A-Za-z_][\w./-]*"
+_BULLET_TICKED = re.compile(rf"\s*[-*]\s+`({_PATH}|{_DOT_PATH})`")
+_BULLET_BARE = re.compile(rf"\s*[-*]\s+({_PATH})(?=[.:,;)]?(?:\s|$))")
+_CELL_TICKED = re.compile(rf"`({_PATH}|{_DOT_PATH})`")
+_CELL_BARE = re.compile(_PATH)
+
+
+def _declared_in_line(line: str) -> list[str]:
+    """Paths one SDD line declares: the first token of a bullet, or every
+    table cell whose whole content is a path. Sentences declare nothing."""
+    m = _BULLET_TICKED.match(line) or _BULLET_BARE.match(line)
+    if m:
+        return [m.group(1)]
+    if not line.lstrip().startswith("|"):
+        return []
+    found = []
+    for cell in line.strip().strip("|").split("|"):
+        cell = cell.strip()
+        m = _CELL_TICKED.fullmatch(cell) or _CELL_BARE.fullmatch(cell)
+        if m:
+            found.append(m.group(1) if m.groups() else m.group(0))
+    return found
 
 
 def _find_sdd_declared_files(target_dir: str) -> list[str] | None:
@@ -69,14 +83,7 @@ def _find_sdd_declared_files(target_dir: str) -> list[str] | None:
         # Look for file references in common SDD patterns
         # Pattern: `- path/to/file` or `| path/to/file |`
         for line in content.splitlines():
-            # Match bullet-point file paths
-            m = re.match(r"\s*[-*]\s+`?([a-zA-Z_][\w./-]+\.\w+)`?", line)
-            if m:
-                declared.append(m.group(1))
-            # Match table cell file paths
-            m = re.match(r"\s*\|[^|]*`?([a-zA-Z_][\w./-]+\.\w+)`?[^|]*\|", line)
-            if m:
-                declared.append(m.group(1))
+            declared.extend(_declared_in_line(line))
 
     # Deduplicate while preserving order
     seen: set[str] = set()
@@ -99,8 +106,10 @@ def check(target_dir: str | None = None) -> dict:
     """
     dir_path = target_dir or os.getcwd()
 
-    changed = _get_changed_files(dir_path)
-    if changed is None:
+    # The snapshot being verified: the index, or HEAD when nothing is staged.
+    changes = _changes.changed_files(dir_path)
+    changed = changes["files"]
+    if changes["mode"] is None:
         return {
             "exit_code": 0, "skipped": True, "name": "check_scope",
             "data": {

package/tools/check_seo.js

@@ -13,28 +13,15 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
-const check = async function checkSeo(targetDir) {
-  const fs = require('fs');
-  const path = require('path');
-  const { execSync } = require('child_process');
+const { changedFiles, readFile } = require('./_changes');
 
+const check = async function checkSeo(targetDir) {
   const dir = targetDir || process.cwd();
 
-  let files;
-  try {
-    const out = execSync('git diff --name-only HEAD~1', {
-      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-    });
-    files = out.split('\n').filter(f => /\.(tsx|jsx|vue|astro|html)$/.test(f.trim()));
-  } catch {
-    try {
-      const out = execSync('git diff --name-only --cached', {
-        cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-      });
-      files = out.split('\n').filter(f => /\.(tsx|jsx|vue|astro|html)$/.test(f.trim()));
-    } catch {
-      return { exitCode: 0, skipped: true, name: 'check_seo', data: { violations: {}, message: 'No git diff available' } };
-    }
+  // The snapshot being verified: the index, or HEAD when nothing is staged.
+  const { mode, files } = changedFiles(dir, { extensions: ['.tsx', '.jsx', '.vue', '.astro', '.html'] });
+  if (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_seo', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -44,15 +31,8 @@ const check = async function checkSeo(targetDir) {
   const violations = {};
 
   for (const file of files) {
-    const filePath = path.join(dir, file);
-    if (!fs.existsSync(filePath)) continue;
-
-    let content;
-    try {
-      content = fs.readFileSync(filePath, 'utf-8');
-    } catch {
-      continue;
-    }
+    const content = readFile(dir, file, mode);
+    if (content === null) continue;
 
     const lines = content.split('\n');
     const fileViolations = [];

package/tools/check_skills.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * Skill Frontmatter Guard
+ * Every SKILL.md changed in the snapshot must open with a YAML frontmatter
+ * block holding a non-empty `name` (lowercase letters and digits joined by
+ * hyphens or underscores) and a non-empty `description` of at most 1024
+ * characters. The `name` must be unique among all the skills of the
+ * repository (read from the same snapshot). A name that differs from the
+ * skill's folder is reported as a warning only.
+ * Skills the harness installs (clckernel_cli, files in the registry) are ignored.
+ * Self-contained: uses only Node.js built-ins.
+ *
+ * @param {string} targetDir - Repository root (defaults to cwd)
+ * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
+ */
+const path = require('path');
+const { changedFiles, readFile, listFiles } = require('./_changes');
+
+const NAME = 'check_skills';
+const SKILL_FILE = 'SKILL.md';
+const MANAGED_REGISTRY = 'tools/.clckernel-managed.json';
+const HARNESS_SKILLS = new Set(['clckernel_cli', 'clc_forge_cli']);
+const NAME_RE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+const MAX_DESCRIPTION = 1024;
+
+/** True for a SKILL.md path that does not belong to a skill the harness installs. */
+function isUserSkill(file) {
+  if (path.posix.basename(file) !== SKILL_FILE) return false;
+  return !file.split('/').some(segment => HARNESS_SKILLS.has(segment));
+}
+
+/** Removes matching surrounding quotes of a YAML scalar. */
+function unquote(value) {
+  const v = value.trim();
+  if (v.length >= 2 && ((v[0] === '"' && v.endsWith('"')) || (v[0] === "'" && v.endsWith("'")))) {
+    return v.slice(1, -1);
+  }
+  return v;
+}
+
+/**
+ * Parses the top-level scalar keys of a frontmatter block: `key: value`,
+ * quoted values, block scalars (`|`, `>`, with chomping indicators) and plain
+ * values continued on indented lines.
+ * @param {string} text - Content of the SKILL.md
+ * @returns {Record<string, string>|null} null when there is no frontmatter block
+ */
+function parseFrontmatter(text) {
+  const lines = text.replace(/^/, '').split(/\r?\n/);
+  if (lines[0].trim() !== '---') return null;
+  const end = lines.findIndex((line, i) => i > 0 && /^(---|\.\.\.)\s*$/.test(line));
+  if (end < 0) return null;
+
+  const fields = {};
+  const body = lines.slice(1, end);
+  for (let i = 0; i < body.length; i++) {
+    const match = /^([A-Za-z0-9_-]+):(.*)$/.exec(body[i]);
+    if (!match) continue;
+    const [, key, rest] = match;
+    const continuation = [];
+    while (i + 1 < body.length && (/^\s+\S/.test(body[i + 1]) || body[i + 1].trim() === '')) {
+      continuation.push(body[++i]);
+    }
+    const head = rest.trim();
+    if (/^[|>][+-]?$/.test(head)) {
+      const joiner = head[0] === '|' ? '\n' : ' ';
+      fields[key] = continuation.map(l => l.trim()).filter(Boolean).join(joiner);
+    } else {
+      fields[key] = [unquote(head), ...continuation.map(l => l.trim())].filter(Boolean).join(' ');
+    }
+  }
+  return fields;
+}
+
+const check = async function checkSkills(targetDir) {
+  const dir = targetDir || process.cwd();
+  const { mode, files } = changedFiles(dir);
+  const changed = files.filter(isUserSkill);
+
+  if (changed.length === 0) {
+    return {
+      exitCode: 0, skipped: true, name: NAME,
+      data: { violations: [], warnings: [], message: 'No changed SKILL.md files' },
+    };
+  }
+
+  // Every skill of the snapshot, for the uniqueness check (registry entries excluded).
+  const registry = new Set();
+  try {
+    const listed = JSON.parse(readFile(dir, MANAGED_REGISTRY, mode) || '[]');
+    if (Array.isArray(listed)) listed.forEach(f => registry.add(f));
+  } catch {
+    // Malformed registry: exclude nothing.
+  }
+  const names = new Map();
+  for (const file of listFiles(dir, mode).filter(f => isUserSkill(f) && !registry.has(f))) {
+    const fields = parseFrontmatter(readFile(dir, file, mode) || '');
+    const name = fields && fields.name;
+    if (!name) continue;
+    if (!names.has(name)) names.set(name, []);
+    names.get(name).push(file);
+  }
+
+  const violations = [];
+  const warnings = [];
+  for (const file of changed) {
+    const fail = message => violations.push({ file, message });
+    const fields = parseFrontmatter(readFile(dir, file, mode) || '');
+    if (!fields) {
+      fail('Missing YAML frontmatter (a leading --- block with name and description)');
+      continue;
+    }
+
+    const name = fields.name || '';
+    const description = fields.description || '';
+    if (!name) {
+      fail('Frontmatter `name` is missing or empty');
+    } else if (!NAME_RE.test(name)) {
+      fail(`Frontmatter name "${name}" must be lowercase letters/digits joined by hyphens or underscores`);
+    }
+    if (!description) {
+      fail('Frontmatter `description` is missing or empty');
+    } else if (description.length > MAX_DESCRIPTION) {
+      fail(`Frontmatter description is ${description.length} characters (max ${MAX_DESCRIPTION})`);
+    }
+
+    if (name) {
+      const others = (names.get(name) || []).filter(f => f !== file);
+      if (others.length > 0) fail(`Duplicate skill name "${name}": already used by ${others.join(', ')}`);
+      const folder = path.posix.basename(path.posix.dirname(file));
+      if (folder !== '.' && folder !== name) {
+        warnings.push({ file, message: `Skill name "${name}" differs from its folder "${folder}"` });
+      }
+    }
+  }
+
+  return {
+    exitCode: violations.length > 0 ? 1 : 0,
+    skipped: false,
+    name: NAME,
+    data: {
+      violations,
+      warnings,
+      message: violations.length > 0
+        ? `${violations.length} SKILL.md frontmatter problem(s) found`
+        : `${changed.length} changed SKILL.md file(s) have valid frontmatter`,
+    },
+  };
+};
+
+module.exports = check;
+
+if (require.main === module) {
+  check(process.argv[2]).then(result => {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.exitCode);
+  });
+}

package/tools/check_storybook.js

@@ -7,10 +7,11 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
+const { changedFiles, exists } = require('./_changes');
+
 const check = async function checkStorybook(targetDir) {
   const fs = require('fs');
   const path = require('path');
-  const { execSync } = require('child_process');
 
   const dir = targetDir || process.cwd();
 
@@ -23,22 +24,10 @@ const check = async function checkStorybook(targetDir) {
     return { exitCode: 0, skipped: true, name: 'check_storybook', data: { violations: {}, message: 'Storybook not configured — skipping' } };
   }
 
-  // Collect changed component files
-  let files;
-  try {
-    const out = execSync('git diff --name-only HEAD~1', {
-      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-    });
-    files = out.split('\n').filter(f => /\.(tsx|jsx)$/.test(f.trim()));
-  } catch {
-    try {
-      const out = execSync('git diff --name-only --cached', {
-        cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-      });
-      files = out.split('\n').filter(f => /\.(tsx|jsx)$/.test(f.trim()));
-    } catch {
-      return { exitCode: 0, skipped: true, name: 'check_storybook', data: { violations: {}, message: 'No git diff available' } };
-    }
+  // The snapshot being verified: the index, or HEAD when nothing is staged.
+  const { mode, files } = changedFiles(dir, { extensions: ['.tsx', '.jsx'] });
+  if (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_storybook', data: { violations: {}, message: 'No git diff available' } };
   }
 
   if (!files || files.length === 0) {
@@ -63,9 +52,6 @@ const check = async function checkStorybook(targetDir) {
   const violations = {};
 
   for (const file of componentFiles) {
-    const filePath = path.join(dir, file);
-    if (!fs.existsSync(filePath)) continue;
-
     // Check if a corresponding .stories.tsx file exists
     const basename = path.basename(file, path.extname(file));
     const ext = path.extname(file);
@@ -74,7 +60,8 @@ const check = async function checkStorybook(targetDir) {
     // Also check co-located stories directory pattern
     const storiesDir = path.join(path.dirname(file), '__stories__', `${basename}.stories${ext}`);
 
-    const hasStory = fs.existsSync(path.join(dir, storyFile)) || fs.existsSync(path.join(dir, storiesDir));
+    // The story must be part of the snapshot too: one only in the working copy does not count.
+    const hasStory = exists(dir, storyFile, mode) || exists(dir, storiesDir, mode);
 
     if (!hasStory) {
       violations[file] = [{

package/tools/check_symlinks.js

@@ -1,25 +1,36 @@
 #!/usr/bin/env node
 /**
  * Symlink & AI IDE Interoperability Guard
- * Verifies that AI agent rule mirrors (CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules)
- * exist and resolve to valid files without broken symlinks.
- * Self-contained: uses only Node.js built-ins.
+ * Every AI agent rule mirror that exists (CLAUDE.md, GEMINI.md, .cursorrules,
+ * .windsurfrules) must point to AGENTS.md: a symlink that resolves to
+ * AGENTS.md, or a regular file whose content is identical to it. Broken
+ * symlinks, symlinks to another file and diverging copies fail. A missing
+ * mirror is not an error. Mirrors are gitignored, so the working copy is read.
+ *
+ * The project config (.clckernel.yaml) can change both: `mirrors.list` is
+ * the list of mirrors to verify, and `mirrors.required: true` makes a listed
+ * mirror that is missing a violation.
+ * Self-contained: uses only Node.js built-ins (and the sibling _config.js
+ * when the project has a config file).
  *
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
+const DEFAULT_MIRRORS = ['CLAUDE.md', 'GEMINI.md', '.cursorrules', '.windsurfrules'];
+
 const check = async function checkSymlinks(targetDir) {
   const fs = require('fs');
   const path = require('path');
+  const { projectConfig } = require('./_changes');
 
   const dir = targetDir || process.cwd();
-  const rules = ['CLAUDE.md', 'GEMINI.md', '.cursorrules', '.windsurfrules'];
+  const config = projectConfig(dir);
+  const rules = config && config.mirrors.list ? config.mirrors.list : DEFAULT_MIRRORS;
+  const required = Boolean(config && config.mirrors.required);
   const violations = [];
 
   const agentsPath = path.join(dir, 'AGENTS.md');
-  const hasAgents = fs.existsSync(agentsPath);
-
-  if (!hasAgents) {
+  if (!fs.existsSync(agentsPath)) {
     return {
       exitCode: 0,
       skipped: true,
@@ -27,28 +38,35 @@ const check = async function checkSymlinks(targetDir) {
       data: { violations: [], message: 'No AGENTS.md present in project' }
     };
   }
+  const agentsReal = fs.realpathSync(agentsPath);
 
   for (const rule of rules) {
     const filePath = path.join(dir, rule);
+    let lstat;
+    try {
+      lstat = fs.lstatSync(filePath);
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        violations.push({ file: rule, message: `Error reading mirror: ${err.message}` });
+      } else if (required) {
+        violations.push({ file: rule, message: 'Missing mirror: mirrors.required is true; create it as a symlink to AGENTS.md' });
+      }
+      continue;
+    }
+
     try {
-      const lstat = fs.lstatSync(filePath);
       if (lstat.isSymbolicLink()) {
         const target = fs.readlinkSync(filePath);
-        const resolved = path.isAbsolute(target) ? target : path.resolve(dir, target);
-        if (!fs.existsSync(resolved)) {
-          violations.push({
-            file: rule,
-            message: `Broken symlink: points to non-existent target "${target}"`
-          });
+        if (!fs.existsSync(filePath)) {
+          violations.push({ file: rule, message: `Broken symlink: points to non-existent target "${target}"` });
+        } else if (fs.realpathSync(filePath) !== agentsReal) {
+          violations.push({ file: rule, message: `Symlink points to "${target}" instead of AGENTS.md` });
         }
+      } else if (!fs.readFileSync(filePath).equals(fs.readFileSync(agentsPath))) {
+        violations.push({ file: rule, message: 'Regular file differs from AGENTS.md: make it a symlink to AGENTS.md or an identical copy' });
       }
     } catch (err) {
-      if (err.code !== 'ENOENT') {
-        violations.push({
-          file: rule,
-          message: `Error reading symlink: ${err.message}`
-        });
-      }
+      violations.push({ file: rule, message: `Error reading mirror: ${err.message}` });
     }
   }
 
@@ -60,8 +78,8 @@ const check = async function checkSymlinks(targetDir) {
     data: {
       violations,
       message: violations.length > 0
-        ? `${violations.length} broken or invalid symlink(s) detected`
-        : 'All AI IDE rule mirrors & symlinks verified'
+        ? `${violations.length} AI IDE rule mirror(s) do not point to AGENTS.md`
+        : 'All existing AI IDE rule mirrors point to AGENTS.md'
     }
   };
 };

package/tools/check_ui_reuse.js

@@ -7,46 +7,34 @@
  * @param {string} targetDir - Directory to scan (defaults to cwd)
  * @returns {{ exitCode: number, skipped: boolean, name: string, data: object }}
  */
-const check = async function checkUiReuse(targetDir) {
-  const fs = require('fs');
-  const path = require('path');
-  const { execSync } = require('child_process');
+const { changedFiles, readFile } = require('./_changes');
 
+const check = async function checkUiReuse(targetDir) {
   const dir = targetDir || process.cwd();
 
-  let files;
-  try {
-    const out = execSync('git diff --name-only HEAD~1', {
-      cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-    });
-    files = out.split('\n').filter(f => /\.(tsx|jsx|ts|js)$/.test(f.trim()));
-  } catch {
-    try {
-      const out = execSync('git diff --name-only --cached', {
-        cwd: dir, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe']
-      });
-      files = out.split('\n').filter(f => /\.(tsx|jsx|ts|js)$/.test(f.trim()));
-    } catch {
-      return { exitCode: 0, skipped: true, name: 'check_ui_reuse', data: { violations: {}, message: 'No git diff available' } };
-    }
+  // The snapshot being verified: the index, or HEAD when nothing is staged.
+  const { mode, files: changed } = changedFiles(dir, { extensions: ['.tsx', '.jsx', '.ts', '.js'] });
+  if (mode === null) {
+    return { exitCode: 0, skipped: true, name: 'check_ui_reuse', data: { violations: {}, message: 'No git diff available' } };
   }
+  let files = changed;
+
+  // tools/ is owned by the harness: guard sources mention raw elements as
+  // pattern strings, which are not rendered UI. Test files render raw
+  // elements as fixtures, so they are not product UI either.
+  const isTestFile = f =>
+    /(^|\/)(test|tests|__tests__)\//.test(f) || /\.(test|spec)\.[jt]sx?$/.test(f);
+  files = (files || []).map(f => f.trim()).filter(f => !f.startsWith('tools/') && !isTestFile(f));
 
-  if (!files || files.length === 0) {
+  if (files.length === 0) {
     return { exitCode: 0, skipped: false, name: 'check_ui_reuse', data: { violations: {}, message: 'No files changed' } };
   }
 
   const violations = {};
 
   for (const file of files) {
-    const filePath = path.join(dir, file);
-    if (!fs.existsSync(filePath)) continue;
-
-    let content;
-    try {
-      content = fs.readFileSync(filePath, 'utf-8');
-    } catch {
-      continue;
-    }
+    const content = readFile(dir, file, mode);
+    if (content === null) continue;
 
     const fileViolations = [];
 

package/tools/docker_guard.py

@@ -9,43 +9,23 @@ from __future__ import annotations
 import json
 import os
 import re
-import subprocess
 import sys
-from pathlib import Path
-
-
-def _get_changed_dockerfiles(target_dir: str) -> list[str] | None:
-    """Return list of changed Docker-related files from git diff, or None on failure."""
-    for ref in ("HEAD~1", "--cached"):
-        try:
-            args = ["git", "diff", "--name-only"]
-            if ref == "--cached":
-                args.append("--cached")
-            else:
-                args.append(ref)
-            out = subprocess.check_output(
-                args, cwd=target_dir,
-                stderr=subprocess.DEVNULL, text=True,
-            )
-            files = [
-                f.strip() for f in out.splitlines()
-                if f.strip().endswith(('Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'))
-                or 'Dockerfile' in f
-                or 'docker-compose' in f
-            ]
-            if files:
-                return files
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            continue
-    return None
+
+# Sibling helper shipped next to the guards; works both as a script and when
+# loaded by audit.py through importlib.
+_TOOLS_DIR = os.path.dirname(os.path.abspath(__file__))
+if _TOOLS_DIR not in sys.path:
+    sys.path.insert(0, _TOOLS_DIR)
+import _changes  # noqa: E402
 
 
-def _read_file_content(full_path: Path) -> str | None:
-    """Read file content safely, return None on failure."""
-    try:
-        return full_path.read_text(encoding="utf-8", errors="replace")
-    except (OSError, PermissionError):
-        return None
+def _is_docker_file(path: str) -> bool:
+    """True for Dockerfile and docker-compose paths."""
+    return (
+        path.endswith(('Dockerfile', 'docker-compose.yml', 'docker-compose.yaml'))
+        or 'Dockerfile' in path
+        or 'docker-compose' in path
+    )
 
 
 def _check_dockerfile(content: str, filepath: str) -> list[dict]:
@@ -161,8 +141,10 @@ def check(target_dir: str | None = None) -> dict:
     """
     dir_path = target_dir or os.getcwd()
 
-    files = _get_changed_dockerfiles(dir_path)
-    if files is None:
+    # The snapshot being verified: the index, or HEAD when nothing is staged.
+    changes = _changes.changed_files(dir_path)
+    mode, files = changes["mode"], [f for f in changes["files"] if _is_docker_file(f)]
+    if mode is None:
         return {
             "exit_code": 0, "skipped": True, "name": "docker_guard",
             "data": {"findings": [], "message": "No git diff available"},
@@ -177,11 +159,7 @@ def check(target_dir: str | None = None) -> dict:
     all_violations: list[dict] = []
 
     for filepath in files:
-        full_path = Path(dir_path) / filepath
-        if not full_path.exists():
-            continue
-
-        content = _read_file_content(full_path)
+        content = _changes.read_file(dir_path, filepath, mode)
         if content is None:
             continue