@attalabs/vinaya 0.2.0 → 0.4.0

package/dist/checks/bin/check-closes-n.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;
 }
@@ -2112,8 +2170,11 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const codeReview = extractCodeReviewVerdict(input.comments);
-  const security = extractSecurityReviewVerdict(input.comments);
+  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
+  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verifiedBodies = verified.map((c) => c.body);
+  const codeReview = extractCodeReviewVerdict(verifiedBodies);
+  const security = extractSecurityReviewVerdict(verifiedBodies);
   const codeReviewClean = codeReview.value === "APPROVE";
   const securityClean = security.value === "PASS";
   if (codeReviewClean && securityClean) {
@@ -2128,9 +2189,10 @@ function checkReviewGate(input) {
     problems.push(`code-reviewer verdict is not a clean APPROVE (found: ${codeReview.value})`);
   if (!securityClean)
     problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`);
+  const ignoredNote = ignoredCount > 0 ? ` ${ignoredCount} verdict-shaped comment(s) from authors outside the principal allowlist were ignored.` : "";
   return {
     verdict: "fail",
-    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).`,
+    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).${ignoredNote}`,
     waived: false
   };
 }

package/dist/checks/bin/check-coherence.js

@@ -1514,15 +1514,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;
@@ -1535,13 +1578,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;
@@ -1558,9 +1603,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;
 }
@@ -2113,8 +2171,11 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const codeReview = extractCodeReviewVerdict(input.comments);
-  const security = extractSecurityReviewVerdict(input.comments);
+  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
+  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verifiedBodies = verified.map((c) => c.body);
+  const codeReview = extractCodeReviewVerdict(verifiedBodies);
+  const security = extractSecurityReviewVerdict(verifiedBodies);
   const codeReviewClean = codeReview.value === "APPROVE";
   const securityClean = security.value === "PASS";
   if (codeReviewClean && securityClean) {
@@ -2129,9 +2190,10 @@ function checkReviewGate(input) {
     problems.push(`code-reviewer verdict is not a clean APPROVE (found: ${codeReview.value})`);
   if (!securityClean)
     problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`);
+  const ignoredNote = ignoredCount > 0 ? ` ${ignoredCount} verdict-shaped comment(s) from authors outside the principal allowlist were ignored.` : "";
   return {
     verdict: "fail",
-    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).`,
+    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).${ignoredNote}`,
     waived: false
   };
 }

package/dist/checks/bin/check-dead-branch-push.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;
 }
@@ -2112,8 +2170,11 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const codeReview = extractCodeReviewVerdict(input.comments);
-  const security = extractSecurityReviewVerdict(input.comments);
+  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
+  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verifiedBodies = verified.map((c) => c.body);
+  const codeReview = extractCodeReviewVerdict(verifiedBodies);
+  const security = extractSecurityReviewVerdict(verifiedBodies);
   const codeReviewClean = codeReview.value === "APPROVE";
   const securityClean = security.value === "PASS";
   if (codeReviewClean && securityClean) {
@@ -2128,9 +2189,10 @@ function checkReviewGate(input) {
     problems.push(`code-reviewer verdict is not a clean APPROVE (found: ${codeReview.value})`);
   if (!securityClean)
     problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`);
+  const ignoredNote = ignoredCount > 0 ? ` ${ignoredCount} verdict-shaped comment(s) from authors outside the principal allowlist were ignored.` : "";
   return {
     verdict: "fail",
-    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).`,
+    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).${ignoredNote}`,
     waived: false
   };
 }

package/dist/checks/bin/check-dispatch-readiness.js

@@ -1514,15 +1514,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;
@@ -1535,13 +1578,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;
@@ -1558,9 +1603,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;
 }
@@ -2113,8 +2171,11 @@ function checkReviewGate(input) {
       waived: true
     };
   }
-  const codeReview = extractCodeReviewVerdict(input.comments);
-  const security = extractSecurityReviewVerdict(input.comments);
+  const verified = input.comments.filter((c) => c.author !== null && PRINCIPAL_ALLOWLIST.includes(c.author));
+  const ignoredCount = input.comments.filter((c) => (c.author === null || !PRINCIPAL_ALLOWLIST.includes(c.author)) && c.body.includes("VERDICT")).length;
+  const verifiedBodies = verified.map((c) => c.body);
+  const codeReview = extractCodeReviewVerdict(verifiedBodies);
+  const security = extractSecurityReviewVerdict(verifiedBodies);
   const codeReviewClean = codeReview.value === "APPROVE";
   const securityClean = security.value === "PASS";
   if (codeReviewClean && securityClean) {
@@ -2129,9 +2190,10 @@ function checkReviewGate(input) {
     problems.push(`code-reviewer verdict is not a clean APPROVE (found: ${codeReview.value})`);
   if (!securityClean)
     problems.push(`security-review verdict is not a clean PASS (found: ${security.value})`);
+  const ignoredNote = ignoredCount > 0 ? ` ${ignoredCount} verdict-shaped comment(s) from authors outside the principal allowlist were ignored.` : "";
   return {
     verdict: "fail",
-    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).`,
+    reason: `${problems.join("; ")}. A principal can apply an actor-verified \`${WAIVER_LABEL_REVIEW}\` label to skip this requirement, or post the missing/clean verdict comment(s).${ignoredNote}`,
     waived: false
   };
 }