@attalabs/vinaya 0.2.0 → 0.3.0

package/dist/checks/bin/check-no-disk-state.js

@@ -1513,15 +1513,58 @@ function pointerToPath(p) {
   return idx === -1 ? p : p.slice(0, idx);
 }
 var SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source;
-function readDocAcks(body) {
-  const acks = [];
-  const re = new RegExp(`^[ \\t]*Doc-ack[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
+function readPointerNoteField(body, field) {
+  const out = [];
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
   for (const m of body.matchAll(re)) {
-    acks.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+    out.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+  }
+  return out;
+}
+function readDocAcks(body) {
+  return readPointerNoteField(body, "Doc-ack");
+}
+function readDocNeutrals(body) {
+  return readPointerNoteField(body, "Doc-neutral");
+}
+var LANGUAGE_COMMENT_PREFIXES = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ["//"] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ["#"] },
+  { test: /\.(sh|bash)$/, prefixes: ["#"] },
+  { test: /\.ya?ml$/, prefixes: ["#"] },
+  { test: /\.py$/, prefixes: ["#"] }
+];
+function commentPrefixesForPath(path) {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path))
+      return prefixes;
+  }
+  return [];
+}
+function isNeutralDiffContentLine(line, prefixes) {
+  const t = line.trim();
+  if (t === "")
+    return true;
+  if (t.startsWith("#!"))
+    return false;
+  return prefixes.some((p) => t.startsWith(p));
+}
+function isMechanicallyNeutralDiff(diffText, path) {
+  const prefixes = commentPrefixesForPath(path);
+  let sawChange = false;
+  for (const raw of diffText.split(`
+`)) {
+    if (raw.startsWith("+++ ") || raw.startsWith("--- ") || raw.startsWith("@@"))
+      continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes))
+        return false;
+      sawChange = true;
+    }
   }
-  return acks;
+  return sawChange;
 }
-function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive) {
+function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive, getDiff) {
   const out = { errors: [], notes: [] };
   if (docOwnersContent === null)
     return out;
@@ -1534,13 +1577,15 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
   const fired = [];
   for (const b of bindings) {
     const re = globToRegex(b.glob);
-    if (codeFiles.some((f) => re.test(f)))
-      fired.push(b);
+    const matchedFiles = codeFiles.filter((f) => re.test(f));
+    if (matchedFiles.length > 0)
+      fired.push({ binding: b, matchedFiles });
   }
   if (fired.length === 0)
     return out;
   const acks = readDocAcks(prBody);
-  for (const b of fired) {
+  const neutrals = readDocNeutrals(prBody);
+  for (const { binding: b, matchedFiles } of fired) {
     if (waiverActive) {
       out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`);
       continue;
@@ -1557,9 +1602,22 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
       out.errors.push(`C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`);
       continue;
     }
-    if (!changed.includes(pointerPath)) {
-      out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+    if (changed.includes(pointerPath))
+      continue;
+    const declared = neutrals.find((n) => n.surface === b.pointer);
+    if (declared) {
+      const evidenced = getDiff !== undefined && matchedFiles.every((f) => {
+        const diff = getDiff(f);
+        return diff !== null && isMechanicallyNeutralDiff(diff, f);
+      });
+      if (evidenced) {
+        out.notes.push(`C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(", ")} confirmed comment/whitespace-only.`);
+        continue;
+      }
+      out.errors.push(`C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(", ")} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+      continue;
     }
+    out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
   }
   return out;
 }

package/dist/checks/bin/check-reader-resolvable-prose.js

@@ -1515,15 +1515,58 @@ function pointerToPath(p) {
   return idx === -1 ? p : p.slice(0, idx);
 }
 var SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source;
-function readDocAcks(body) {
-  const acks = [];
-  const re = new RegExp(`^[ \\t]*Doc-ack[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
+function readPointerNoteField(body, field) {
+  const out = [];
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
   for (const m of body.matchAll(re)) {
-    acks.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+    out.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+  }
+  return out;
+}
+function readDocAcks(body) {
+  return readPointerNoteField(body, "Doc-ack");
+}
+function readDocNeutrals(body) {
+  return readPointerNoteField(body, "Doc-neutral");
+}
+var LANGUAGE_COMMENT_PREFIXES = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ["//"] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ["#"] },
+  { test: /\.(sh|bash)$/, prefixes: ["#"] },
+  { test: /\.ya?ml$/, prefixes: ["#"] },
+  { test: /\.py$/, prefixes: ["#"] }
+];
+function commentPrefixesForPath(path) {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path))
+      return prefixes;
   }
-  return acks;
+  return [];
 }
-function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive) {
+function isNeutralDiffContentLine(line, prefixes) {
+  const t = line.trim();
+  if (t === "")
+    return true;
+  if (t.startsWith("#!"))
+    return false;
+  return prefixes.some((p) => t.startsWith(p));
+}
+function isMechanicallyNeutralDiff(diffText, path) {
+  const prefixes = commentPrefixesForPath(path);
+  let sawChange = false;
+  for (const raw of diffText.split(`
+`)) {
+    if (raw.startsWith("+++ ") || raw.startsWith("--- ") || raw.startsWith("@@"))
+      continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes))
+        return false;
+      sawChange = true;
+    }
+  }
+  return sawChange;
+}
+function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive, getDiff) {
   const out = { errors: [], notes: [] };
   if (docOwnersContent === null)
     return out;
@@ -1536,13 +1579,15 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
   const fired = [];
   for (const b of bindings) {
     const re = globToRegex(b.glob);
-    if (codeFiles.some((f) => re.test(f)))
-      fired.push(b);
+    const matchedFiles = codeFiles.filter((f) => re.test(f));
+    if (matchedFiles.length > 0)
+      fired.push({ binding: b, matchedFiles });
   }
   if (fired.length === 0)
     return out;
   const acks = readDocAcks(prBody);
-  for (const b of fired) {
+  const neutrals = readDocNeutrals(prBody);
+  for (const { binding: b, matchedFiles } of fired) {
     if (waiverActive) {
       out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`);
       continue;
@@ -1559,9 +1604,22 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
       out.errors.push(`C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`);
       continue;
     }
-    if (!changed.includes(pointerPath)) {
-      out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+    if (changed.includes(pointerPath))
+      continue;
+    const declared = neutrals.find((n) => n.surface === b.pointer);
+    if (declared) {
+      const evidenced = getDiff !== undefined && matchedFiles.every((f) => {
+        const diff = getDiff(f);
+        return diff !== null && isMechanicallyNeutralDiff(diff, f);
+      });
+      if (evidenced) {
+        out.notes.push(`C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(", ")} confirmed comment/whitespace-only.`);
+        continue;
+      }
+      out.errors.push(`C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(", ")} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+      continue;
     }
+    out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
   }
   return out;
 }

package/dist/checks/bin/check-registry-gates.js

@@ -1515,15 +1515,58 @@ function pointerToPath(p) {
   return idx === -1 ? p : p.slice(0, idx);
 }
 var SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source;
-function readDocAcks(body) {
-  const acks = [];
-  const re = new RegExp(`^[ \\t]*Doc-ack[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
+function readPointerNoteField(body, field) {
+  const out = [];
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
   for (const m of body.matchAll(re)) {
-    acks.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+    out.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+  }
+  return out;
+}
+function readDocAcks(body) {
+  return readPointerNoteField(body, "Doc-ack");
+}
+function readDocNeutrals(body) {
+  return readPointerNoteField(body, "Doc-neutral");
+}
+var LANGUAGE_COMMENT_PREFIXES = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ["//"] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ["#"] },
+  { test: /\.(sh|bash)$/, prefixes: ["#"] },
+  { test: /\.ya?ml$/, prefixes: ["#"] },
+  { test: /\.py$/, prefixes: ["#"] }
+];
+function commentPrefixesForPath(path) {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path))
+      return prefixes;
+  }
+  return [];
+}
+function isNeutralDiffContentLine(line, prefixes) {
+  const t = line.trim();
+  if (t === "")
+    return true;
+  if (t.startsWith("#!"))
+    return false;
+  return prefixes.some((p) => t.startsWith(p));
+}
+function isMechanicallyNeutralDiff(diffText, path) {
+  const prefixes = commentPrefixesForPath(path);
+  let sawChange = false;
+  for (const raw of diffText.split(`
+`)) {
+    if (raw.startsWith("+++ ") || raw.startsWith("--- ") || raw.startsWith("@@"))
+      continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes))
+        return false;
+      sawChange = true;
+    }
   }
-  return acks;
+  return sawChange;
 }
-function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive) {
+function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive, getDiff) {
   const out = { errors: [], notes: [] };
   if (docOwnersContent === null)
     return out;
@@ -1536,13 +1579,15 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
   const fired = [];
   for (const b of bindings) {
     const re = globToRegex(b.glob);
-    if (codeFiles.some((f) => re.test(f)))
-      fired.push(b);
+    const matchedFiles = codeFiles.filter((f) => re.test(f));
+    if (matchedFiles.length > 0)
+      fired.push({ binding: b, matchedFiles });
   }
   if (fired.length === 0)
     return out;
   const acks = readDocAcks(prBody);
-  for (const b of fired) {
+  const neutrals = readDocNeutrals(prBody);
+  for (const { binding: b, matchedFiles } of fired) {
     if (waiverActive) {
       out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`);
       continue;
@@ -1559,9 +1604,22 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
       out.errors.push(`C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`);
       continue;
     }
-    if (!changed.includes(pointerPath)) {
-      out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+    if (changed.includes(pointerPath))
+      continue;
+    const declared = neutrals.find((n) => n.surface === b.pointer);
+    if (declared) {
+      const evidenced = getDiff !== undefined && matchedFiles.every((f) => {
+        const diff = getDiff(f);
+        return diff !== null && isMechanicallyNeutralDiff(diff, f);
+      });
+      if (evidenced) {
+        out.notes.push(`C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(", ")} confirmed comment/whitespace-only.`);
+        continue;
+      }
+      out.errors.push(`C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(", ")} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+      continue;
     }
+    out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
   }
   return out;
 }

package/dist/checks/bin/check-review-gate.js

@@ -1513,15 +1513,58 @@ function pointerToPath(p) {
   return idx === -1 ? p : p.slice(0, idx);
 }
 var SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source;
-function readDocAcks(body) {
-  const acks = [];
-  const re = new RegExp(`^[ \\t]*Doc-ack[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
+function readPointerNoteField(body, field) {
+  const out = [];
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
   for (const m of body.matchAll(re)) {
-    acks.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+    out.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+  }
+  return out;
+}
+function readDocAcks(body) {
+  return readPointerNoteField(body, "Doc-ack");
+}
+function readDocNeutrals(body) {
+  return readPointerNoteField(body, "Doc-neutral");
+}
+var LANGUAGE_COMMENT_PREFIXES = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ["//"] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ["#"] },
+  { test: /\.(sh|bash)$/, prefixes: ["#"] },
+  { test: /\.ya?ml$/, prefixes: ["#"] },
+  { test: /\.py$/, prefixes: ["#"] }
+];
+function commentPrefixesForPath(path) {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path))
+      return prefixes;
   }
-  return acks;
+  return [];
 }
-function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive) {
+function isNeutralDiffContentLine(line, prefixes) {
+  const t = line.trim();
+  if (t === "")
+    return true;
+  if (t.startsWith("#!"))
+    return false;
+  return prefixes.some((p) => t.startsWith(p));
+}
+function isMechanicallyNeutralDiff(diffText, path) {
+  const prefixes = commentPrefixesForPath(path);
+  let sawChange = false;
+  for (const raw of diffText.split(`
+`)) {
+    if (raw.startsWith("+++ ") || raw.startsWith("--- ") || raw.startsWith("@@"))
+      continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes))
+        return false;
+      sawChange = true;
+    }
+  }
+  return sawChange;
+}
+function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive, getDiff) {
   const out = { errors: [], notes: [] };
   if (docOwnersContent === null)
     return out;
@@ -1534,13 +1577,15 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
   const fired = [];
   for (const b of bindings) {
     const re = globToRegex(b.glob);
-    if (codeFiles.some((f) => re.test(f)))
-      fired.push(b);
+    const matchedFiles = codeFiles.filter((f) => re.test(f));
+    if (matchedFiles.length > 0)
+      fired.push({ binding: b, matchedFiles });
   }
   if (fired.length === 0)
     return out;
   const acks = readDocAcks(prBody);
-  for (const b of fired) {
+  const neutrals = readDocNeutrals(prBody);
+  for (const { binding: b, matchedFiles } of fired) {
     if (waiverActive) {
       out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`);
       continue;
@@ -1557,9 +1602,22 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
       out.errors.push(`C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`);
       continue;
     }
-    if (!changed.includes(pointerPath)) {
-      out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+    if (changed.includes(pointerPath))
+      continue;
+    const declared = neutrals.find((n) => n.surface === b.pointer);
+    if (declared) {
+      const evidenced = getDiff !== undefined && matchedFiles.every((f) => {
+        const diff = getDiff(f);
+        return diff !== null && isMechanicallyNeutralDiff(diff, f);
+      });
+      if (evidenced) {
+        out.notes.push(`C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(", ")} confirmed comment/whitespace-only.`);
+        continue;
+      }
+      out.errors.push(`C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(", ")} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+      continue;
     }
+    out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
   }
   return out;
 }

package/dist/checks/bin/check-single-plan-pr.js

@@ -1513,15 +1513,58 @@ function pointerToPath(p) {
   return idx === -1 ? p : p.slice(0, idx);
 }
 var SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source;
-function readDocAcks(body) {
-  const acks = [];
-  const re = new RegExp(`^[ \\t]*Doc-ack[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
+function readPointerNoteField(body, field) {
+  const out = [];
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
   for (const m of body.matchAll(re)) {
-    acks.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+    out.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+  }
+  return out;
+}
+function readDocAcks(body) {
+  return readPointerNoteField(body, "Doc-ack");
+}
+function readDocNeutrals(body) {
+  return readPointerNoteField(body, "Doc-neutral");
+}
+var LANGUAGE_COMMENT_PREFIXES = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ["//"] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ["#"] },
+  { test: /\.(sh|bash)$/, prefixes: ["#"] },
+  { test: /\.ya?ml$/, prefixes: ["#"] },
+  { test: /\.py$/, prefixes: ["#"] }
+];
+function commentPrefixesForPath(path) {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path))
+      return prefixes;
   }
-  return acks;
+  return [];
 }
-function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive) {
+function isNeutralDiffContentLine(line, prefixes) {
+  const t = line.trim();
+  if (t === "")
+    return true;
+  if (t.startsWith("#!"))
+    return false;
+  return prefixes.some((p) => t.startsWith(p));
+}
+function isMechanicallyNeutralDiff(diffText, path) {
+  const prefixes = commentPrefixesForPath(path);
+  let sawChange = false;
+  for (const raw of diffText.split(`
+`)) {
+    if (raw.startsWith("+++ ") || raw.startsWith("--- ") || raw.startsWith("@@"))
+      continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes))
+        return false;
+      sawChange = true;
+    }
+  }
+  return sawChange;
+}
+function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive, getDiff) {
   const out = { errors: [], notes: [] };
   if (docOwnersContent === null)
     return out;
@@ -1534,13 +1577,15 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
   const fired = [];
   for (const b of bindings) {
     const re = globToRegex(b.glob);
-    if (codeFiles.some((f) => re.test(f)))
-      fired.push(b);
+    const matchedFiles = codeFiles.filter((f) => re.test(f));
+    if (matchedFiles.length > 0)
+      fired.push({ binding: b, matchedFiles });
   }
   if (fired.length === 0)
     return out;
   const acks = readDocAcks(prBody);
-  for (const b of fired) {
+  const neutrals = readDocNeutrals(prBody);
+  for (const { binding: b, matchedFiles } of fired) {
     if (waiverActive) {
       out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`);
       continue;
@@ -1557,9 +1602,22 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
       out.errors.push(`C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`);
       continue;
     }
-    if (!changed.includes(pointerPath)) {
-      out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+    if (changed.includes(pointerPath))
+      continue;
+    const declared = neutrals.find((n) => n.surface === b.pointer);
+    if (declared) {
+      const evidenced = getDiff !== undefined && matchedFiles.every((f) => {
+        const diff = getDiff(f);
+        return diff !== null && isMechanicallyNeutralDiff(diff, f);
+      });
+      if (evidenced) {
+        out.notes.push(`C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(", ")} confirmed comment/whitespace-only.`);
+        continue;
+      }
+      out.errors.push(`C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(", ")} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+      continue;
     }
+    out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
   }
   return out;
 }

package/dist/checks/bin/check-test-plan.js

@@ -1510,15 +1510,58 @@ function pointerToPath(p) {
   return idx === -1 ? p : p.slice(0, idx);
 }
 var SEPARATOR = /(?:[ \t]*[—–][ \t]*|[ \t]+-[ \t]+)/.source;
-function readDocAcks(body) {
-  const acks = [];
-  const re = new RegExp(`^[ \\t]*Doc-ack[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
+function readPointerNoteField(body, field) {
+  const out = [];
+  const re = new RegExp(`^[ \\t]*${field}[ \\t]*:[ \\t]*(.+?)${SEPARATOR}(.+?)[ \\t]*$`, "gim");
   for (const m of body.matchAll(re)) {
-    acks.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+    out.push({ surface: (m[1] ?? "").trim(), note: (m[2] ?? "").trim() });
+  }
+  return out;
+}
+function readDocAcks(body) {
+  return readPointerNoteField(body, "Doc-ack");
+}
+function readDocNeutrals(body) {
+  return readPointerNoteField(body, "Doc-neutral");
+}
+var LANGUAGE_COMMENT_PREFIXES = [
+  { test: /\.(ts|tsx|js|jsx|mjs|cjs)$/, prefixes: ["//"] },
+  { test: /(^|\/)(pre-push|pre-commit|pre-merge-commit)$/, prefixes: ["#"] },
+  { test: /\.(sh|bash)$/, prefixes: ["#"] },
+  { test: /\.ya?ml$/, prefixes: ["#"] },
+  { test: /\.py$/, prefixes: ["#"] }
+];
+function commentPrefixesForPath(path) {
+  for (const { test, prefixes } of LANGUAGE_COMMENT_PREFIXES) {
+    if (test.test(path))
+      return prefixes;
   }
-  return acks;
+  return [];
 }
-function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive) {
+function isNeutralDiffContentLine(line, prefixes) {
+  const t = line.trim();
+  if (t === "")
+    return true;
+  if (t.startsWith("#!"))
+    return false;
+  return prefixes.some((p) => t.startsWith(p));
+}
+function isMechanicallyNeutralDiff(diffText, path) {
+  const prefixes = commentPrefixesForPath(path);
+  let sawChange = false;
+  for (const raw of diffText.split(`
+`)) {
+    if (raw.startsWith("+++ ") || raw.startsWith("--- ") || raw.startsWith("@@"))
+      continue;
+    if (raw.startsWith("+") || raw.startsWith("-")) {
+      if (!isNeutralDiffContentLine(raw.slice(1), prefixes))
+        return false;
+      sawChange = true;
+    }
+  }
+  return sawChange;
+}
+function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive, getDiff) {
   const out = { errors: [], notes: [] };
   if (docOwnersContent === null)
     return out;
@@ -1531,13 +1574,15 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
   const fired = [];
   for (const b of bindings) {
     const re = globToRegex(b.glob);
-    if (codeFiles.some((f) => re.test(f)))
-      fired.push(b);
+    const matchedFiles = codeFiles.filter((f) => re.test(f));
+    if (matchedFiles.length > 0)
+      fired.push({ binding: b, matchedFiles });
   }
   if (fired.length === 0)
     return out;
   const acks = readDocAcks(prBody);
-  for (const b of fired) {
+  const neutrals = readDocNeutrals(prBody);
+  for (const { binding: b, matchedFiles } of fired) {
     if (waiverActive) {
       out.notes.push(`C5 doc-waiver active for ${b.pointer} (binding ${DOC_OWNERS_PATH}:${b.lineNum})`);
       continue;
@@ -1554,9 +1599,22 @@ function evaluateC5(changed, docOwnersContent, prBody, fileExists, waiverActive)
       out.errors.push(`C5 doc-owners-dangling: ${DOC_OWNERS_PATH}:${b.lineNum} points to ${b.pointer}, which does not exist on disk. Fix the binding or add the doc.`);
       continue;
     }
-    if (!changed.includes(pointerPath)) {
-      out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+    if (changed.includes(pointerPath))
+      continue;
+    const declared = neutrals.find((n) => n.surface === b.pointer);
+    if (declared) {
+      const evidenced = getDiff !== undefined && matchedFiles.every((f) => {
+        const diff = getDiff(f);
+        return diff !== null && isMechanicallyNeutralDiff(diff, f);
+      });
+      if (evidenced) {
+        out.notes.push(`C5 doc-neutral: ${b.pointer} not required for ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\`) — declared neutral ("${declared.note}"), diff of ${matchedFiles.join(", ")} confirmed comment/whitespace-only.`);
+        continue;
+      }
+      out.errors.push(`C5 doc-neutral-unverified: ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}) declared \`Doc-neutral: ${b.pointer} — ${declared.note}\`, but the diff of ${matchedFiles.join(", ")} contains changes beyond comments/whitespace. Update ${pointerPath}, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
+      continue;
     }
+    out.errors.push(`C5 doc-coverage: code change matched ${DOC_OWNERS_PATH}:${b.lineNum} (glob \`${b.glob}\` → ${b.pointer}), but ${pointerPath} is not in the PR diff. Update it, declare \`Doc-neutral: ${b.pointer} — <why>\` if the change is genuinely mechanically-neutral, or have a principal apply the \`${WAIVER_LABEL}\` label.`);
   }
   return out;
 }