mandrel-platform 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/audit-check.mjs

@@ -34,10 +34,16 @@
  *     {
  *       "id": "GHSA-xxxx-xxxx-xxxx",  // GitHub Advisory ID or CVE ID
  *       "reason": "No fix available; mitigated by X",
- *       "expires": "2026-12-31"        // ISO 8601 date — REQUIRED
+ *       "expires": "2026-12-31"        // REQUIRED — strictly YYYY-MM-DD
  *     }
  *   ]
  *
+ * `expires` is validated, not merely read: it must be exactly `YYYY-MM-DD` and
+ * a real calendar date. Anything else (a `<YYYY-MM-DD>` placeholder, a
+ * `12/31/2026`, an impossible `2026-02-30`) is a hard configuration error that
+ * exits 1 — it is NEVER treated as a distant future date, which would suppress
+ * the advisory forever.
+ *
  * The allowlist file path defaults to `audit-allowlist.json` in the
  * directory from which this script is invoked (i.e. the project root).
  * Override with `--allowlist <path>`.
@@ -57,31 +63,117 @@ const BLOCKING_SEVERITIES = new Set(["high", "critical"]);
  * @typedef {{ id: string; reason?: string; expires: string }} AllowlistEntry
  */
 
+/**
+ * Strictly parse a `YYYY-MM-DD` calendar date, returning UTC midnight in ms —
+ * or `null` when the value is not exactly that.
+ *
+ * Deliberately strict, because this validates a *config field* that decides
+ * whether a High/Critical CVE stays suppressed. Anything unparseable must be
+ * rejected outright rather than coerced, so:
+ *
+ *   - The regex is anchored. A value that merely CONTAINS a date is not a date,
+ *     which is what rejects `<YYYY-MM-DD>`, `expires 2026-01-01`, `12/31/2026`
+ *     and `2026-01-01T00:00:00Z`.
+ *   - The result is round-tripped. `Date.UTC` silently rolls overflow over
+ *     (`2026-13-45` → 2027-01-14, `2026-02-30` → 2026-03-02) and never returns
+ *     NaN for it, so comparing the parsed instant's calendar fields back
+ *     against the input is the only way to reject an impossible date.
+ *
+ * One consequence of the round-trip, noted rather than worked around: years
+ * 0–99 are rejected, because `Date.UTC` maps them into 1900–1999 (legacy
+ * two-digit-year behaviour) and so fail the comparison. No real expiry lands
+ * there, and rejecting is the fail-closed direction.
+ *
+ * @param {unknown} value
+ * @returns {number|null} UTC ms at midnight, or null when not a valid date
+ */
+export function parseIsoDateUtc(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!m) {
+    return null;
+  }
+
+  const year = Number(m[1]);
+  const month = Number(m[2]);
+  const day = Number(m[3]);
+  const ms = Date.UTC(year, month - 1, day);
+  const back = new Date(ms);
+
+  if (
+    back.getUTCFullYear() !== year ||
+    back.getUTCMonth() !== month - 1 ||
+    back.getUTCDate() !== day
+  ) {
+    return null;
+  }
+
+  return ms;
+}
+
 /**
  * Partition allowlist entries into the active (non-expired) suppression set
  * and the list of expired entries, relative to `today` (a `YYYY-MM-DD`
- * string). Entries missing a required `id` or `expires` field are surfaced
- * in `invalid` so the caller can fail closed on a malformed allowlist.
+ * string).
+ *
+ * Entries that are unusable — missing/non-string `id`, or an `expires` that is
+ * not a valid `YYYY-MM-DD` calendar date — are surfaced in `invalid` with the
+ * specific `problem`, so the caller can fail closed and name what is wrong.
+ * Treating `expires` as an opaque string was a fail-OPEN: the comparison was
+ * lexicographic, and every non-date value a caller might plausibly write
+ * (`<YYYY-MM-DD>` copy-pasted from the runbook, `not-a-date`, a typo) sorts
+ * ABOVE a real `20xx-..-..` date and so read as "not yet expired" — turning a
+ * malformed field into a permanent, silent CVE suppression.
  *
  * @param {AllowlistEntry[]} allowlist
  * @param {string} today `YYYY-MM-DD`
- * @returns {{ suppressed: Set<string>; expired: AllowlistEntry[]; invalid: AllowlistEntry[] }}
+ * @returns {{ suppressed: Set<string>; expired: AllowlistEntry[]; invalid: Array<{ entry: unknown; problem: string }> }}
  */
 export function partitionAllowlist(allowlist, today) {
   /** @type {Set<string>} */
   const suppressed = new Set();
   /** @type {AllowlistEntry[]} */
   const expired = [];
-  /** @type {AllowlistEntry[]} */
+  /** @type {Array<{ entry: unknown; problem: string }>} */
   const invalid = [];
 
+  const todayMs = parseIsoDateUtc(today);
+  if (todayMs === null) {
+    // Caller bug, not user data: `today` is derived from the system clock via
+    // toISOString(). Throwing beats any fallback, both of which would silently
+    // mis-classify every entry.
+    throw new Error(
+      `partitionAllowlist: "today" must be a YYYY-MM-DD date, got ${JSON.stringify(today)}.`,
+    );
+  }
+
   for (const entry of allowlist) {
-    if (!entry || !entry.id || !entry.expires) {
-      invalid.push(entry);
+    if (!entry || typeof entry !== "object") {
+      invalid.push({ entry, problem: "entry is not an object" });
       continue;
     }
 
-    if (entry.expires < today) {
+    if (typeof entry.id !== "string" || entry.id.trim() === "") {
+      invalid.push({ entry, problem: 'missing or non-string "id"' });
+      continue;
+    }
+
+    const expiresMs = parseIsoDateUtc(entry.expires);
+    if (expiresMs === null) {
+      invalid.push({
+        entry,
+        problem:
+          entry.expires === undefined || entry.expires === null
+            ? 'missing required "expires"'
+            : `"expires" is not a valid YYYY-MM-DD date: ${JSON.stringify(entry.expires)}`,
+      });
+      continue;
+    }
+
+    if (expiresMs < todayMs) {
       expired.push(entry);
     } else {
       suppressed.add(entry.id);
@@ -299,11 +391,19 @@ export function runCli(argv) {
   const { suppressed, expired, invalid } = partitionAllowlist(allowlist, today);
 
   if (invalid.length > 0) {
-    for (const entry of invalid) {
-      console.error(
-        `[audit-check] ERROR: Allowlist entry missing required "id" or "expires" field: ${JSON.stringify(entry)}`,
-      );
+    console.error("[audit-check] INVALID allowlist entries detected:");
+    for (const { entry, problem } of invalid) {
+      const id =
+        entry && typeof entry === "object" && typeof entry.id === "string"
+          ? entry.id
+          : "<no id>";
+      console.error(`  - ${id}: ${problem}`);
     }
+    console.error(
+      "[audit-check] An entry whose expiry cannot be read is never suppressed. " +
+        'Fix each entry to carry a non-empty "id" and an "expires" of the form ' +
+        "YYYY-MM-DD. Exit 1.",
+    );
     return 1;
   }
 

package/scripts/audit-check.test.mjs

@@ -8,6 +8,16 @@
  *   - a validly-suppressed high advisory (by GHSA id and by CVE id) passes
  *   - an expired allowlist entry fails closed (exit 1)
  *   - an unsuppressed critical fails closed (exit 1)
+ *   - a MALFORMED `expires` fails closed rather than suppressing forever
+ *
+ * That last one was a fail-OPEN. `expires` was compared as an opaque string
+ * (`entry.expires < today`), so any non-date value sorted lexicographically
+ * above a real `20xx-..-..` date and read as "not yet expired" — making a
+ * typo'd or placeholder expiry a permanent, silent CVE suppression. The
+ * `<YYYY-MM-DD>` placeholder the dependency-update runbook shows as its example
+ * value is the realistic way in. `parseIsoDateUtc` now validates the field, and
+ * the tests below assert the invariant (nothing unreadable is ever suppressed)
+ * across every malformed shape rather than the one spelling that motivated it.
  *
  * The suppression/expiry/interpretation logic is exercised through the pure
  * functions (`partitionAllowlist`, `isInterpretableReport`,
@@ -26,6 +36,7 @@ import { join } from "node:path";
 
 import {
   partitionAllowlist,
+  parseIsoDateUtc,
   isInterpretableReport,
   extractBlockingAdvisories,
   evaluateReport,
@@ -99,6 +110,154 @@ test("partitionAllowlist: entry missing id or expires is invalid", () => {
   assert.equal(invalid.length, 2);
 });
 
+test("partitionAllowlist: an expiry equal to today is still active, not expired", () => {
+  const { suppressed, expired } = partitionAllowlist(
+    [{ id: "GHSA-today", expires: TODAY }],
+    TODAY,
+  );
+  assert.ok(suppressed.has("GHSA-today"));
+  assert.equal(expired.length, 0);
+});
+
+// ── partitionAllowlist: the malformed-expiry fail-open ──────────────────────
+//
+// `expires` used to be compared as an opaque string (`entry.expires < today`),
+// so any non-date value sorted lexicographically ABOVE a real `20xx-..-..`
+// date and read as "not yet expired". A malformed field therefore became a
+// PERMANENT, SILENT CVE suppression — the exact inverse of what an expiry is
+// for. The realistic path in: `docs/runbooks/dependency-update.md` shows
+// `"expires": "<YYYY-MM-DD>"` as the example value, and `<` (0x3C) sorts above
+// `2` (0x32).
+//
+// The assertion below is on the invariant — nothing unreadable is EVER
+// suppressed — rather than on the handful of spellings that motivated it.
+
+const MALFORMED_EXPIRIES = [
+  ["<YYYY-MM-DD>", "runbook placeholder, copy-pasted verbatim"],
+  ["YYYY-MM-DD", "placeholder without brackets"],
+  ["not-a-date", "free text"],
+  ["expres 2026", "typo'd key/value smashed together"],
+  ["12/31/2026", "US-style separators"],
+  ["31-12-2026", "day-first ordering"],
+  ["2026-1-1", "unpadded month/day"],
+  ["2026-01-01T00:00:00Z", "full ISO 8601 timestamp, not a bare date"],
+  [" 2026-01-01 ", "surrounding whitespace"],
+  ["2026-01-01extra", "trailing junk"],
+  ["2026-13-01", "impossible month"],
+  ["2026-02-30", "impossible day for the month"],
+  ["", "empty string"],
+  [0, "number"],
+  [20261231, "date-ish number"],
+  [null, "null"],
+  [undefined, "undefined"],
+  [{ year: 2026 }, "object"],
+  [["2026-01-01"], "array"],
+  [true, "boolean"],
+];
+
+test("partitionAllowlist: no malformed expiry is ever suppressed (fail closed)", () => {
+  for (const [expires, label] of MALFORMED_EXPIRIES) {
+    const { suppressed, expired, invalid } = partitionAllowlist(
+      [{ id: "GHSA-aaaa-bbbb-cccc", reason: "why", expires }],
+      TODAY,
+    );
+    assert.equal(
+      suppressed.size,
+      0,
+      `${label} (${JSON.stringify(expires)}) must not suppress`,
+    );
+    assert.equal(
+      expired.length,
+      0,
+      `${label} (${JSON.stringify(expires)}) is unreadable, not expired`,
+    );
+    assert.equal(
+      invalid.length,
+      1,
+      `${label} (${JSON.stringify(expires)}) must be reported invalid`,
+    );
+  }
+});
+
+test("partitionAllowlist: an invalid entry names the offending id and problem", () => {
+  const { invalid } = partitionAllowlist(
+    [{ id: "GHSA-aaaa-bbbb-cccc", expires: "<YYYY-MM-DD>" }],
+    TODAY,
+  );
+  assert.equal(invalid.length, 1);
+  assert.equal(invalid[0].entry.id, "GHSA-aaaa-bbbb-cccc");
+  assert.match(invalid[0].problem, /expires/);
+  assert.match(invalid[0].problem, /YYYY-MM-DD/);
+});
+
+test("partitionAllowlist: a valid entry alongside a malformed one still fails closed", () => {
+  // The malformed entry must not be quietly skipped while the good one passes:
+  // the CLI gates on `invalid.length`, so the run has to stop.
+  const { suppressed, invalid } = partitionAllowlist(
+    [
+      { id: "GHSA-good", expires: FUTURE },
+      { id: "GHSA-bad", expires: "<YYYY-MM-DD>" },
+    ],
+    TODAY,
+  );
+  assert.ok(suppressed.has("GHSA-good"));
+  assert.equal(invalid.length, 1);
+  assert.equal(invalid[0].entry.id, "GHSA-bad");
+});
+
+test("partitionAllowlist: a non-string id is invalid, never a suppression key", () => {
+  for (const id of [42, null, undefined, "", "   ", {}, ["GHSA-x"]]) {
+    const { suppressed, invalid } = partitionAllowlist(
+      [{ id, expires: FUTURE }],
+      TODAY,
+    );
+    assert.equal(suppressed.size, 0, `id ${JSON.stringify(id)} must not suppress`);
+    assert.equal(invalid.length, 1);
+  }
+});
+
+test("partitionAllowlist: throws when `today` is not a YYYY-MM-DD date", () => {
+  assert.throws(
+    () => partitionAllowlist([{ id: "GHSA-x", expires: FUTURE }], "not-a-date"),
+    /must be a YYYY-MM-DD date/,
+  );
+});
+
+// ── parseIsoDateUtc ─────────────────────────────────────────────────────────
+
+test("parseIsoDateUtc: accepts a real calendar date and returns UTC midnight", () => {
+  assert.equal(parseIsoDateUtc("2026-07-02"), Date.UTC(2026, 6, 2));
+  assert.equal(parseIsoDateUtc("2024-02-29"), Date.UTC(2024, 1, 29)); // leap year
+  assert.equal(parseIsoDateUtc("2999-12-31"), Date.UTC(2999, 11, 31));
+});
+
+test("parseIsoDateUtc: rejects overflow dates that Date.UTC would roll over", () => {
+  // Date.UTC(2026, 12, 45) is 2027-01-14, not NaN — only a round-trip catches it.
+  assert.equal(parseIsoDateUtc("2026-13-45"), null);
+  assert.equal(parseIsoDateUtc("2026-02-30"), null);
+  assert.equal(parseIsoDateUtc("2025-02-29"), null); // 2025 is not a leap year
+  assert.equal(parseIsoDateUtc("2026-00-10"), null);
+  assert.equal(parseIsoDateUtc("2026-01-00"), null);
+});
+
+test("parseIsoDateUtc: rejects every malformed shape", () => {
+  for (const [value, label] of MALFORMED_EXPIRIES) {
+    assert.equal(
+      parseIsoDateUtc(value),
+      null,
+      `${label} (${JSON.stringify(value)}) must not parse`,
+    );
+  }
+});
+
+test("parseIsoDateUtc: ordering is chronological, not lexicographic", () => {
+  // The bug in one line: as strings, "<YYYY-MM-DD>" > "2026-07-02".
+  assert.ok("<YYYY-MM-DD>" > "2026-07-02");
+  // Parsed, it has no ordering at all — it is simply not a date.
+  assert.equal(parseIsoDateUtc("<YYYY-MM-DD>"), null);
+  assert.ok(parseIsoDateUtc("2026-01-01") < parseIsoDateUtc("2026-07-02"));
+});
+
 // ── isInterpretableReport ───────────────────────────────────────────────────
 
 test("isInterpretableReport: true for a report with an advisories object", () => {
@@ -219,6 +378,42 @@ test("runCli: malformed allowlist entry (missing expires) → exit non-zero", ()
   }
 });
 
+test("runCli: placeholder expiry copy-pasted from the runbook → exit non-zero", () => {
+  // The end-to-end shape of the fail-open: before validation this entry was
+  // suppressed forever, and runCli went on to pass the advisory it covered.
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-placeholder-"));
+  try {
+    const allowlistPath = join(dir, "audit-allowlist.json");
+    writeFileSync(
+      allowlistPath,
+      JSON.stringify([
+        {
+          id: "GHSA-aaaa-bbbb-cccc",
+          reason: "No fix available; upstream tracking issue: <URL>",
+          expires: "<YYYY-MM-DD>",
+        },
+      ]),
+    );
+    assert.equal(runCli(["--allowlist", allowlistPath]), 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("runCli: impossible calendar date in expires → exit non-zero", () => {
+  const dir = mkdtempSync(join(tmpdir(), "audit-check-impossible-"));
+  try {
+    const allowlistPath = join(dir, "audit-allowlist.json");
+    writeFileSync(
+      allowlistPath,
+      JSON.stringify([{ id: "GHSA-aaaa-bbbb-cccc", expires: "2026-02-30" }]),
+    );
+    assert.equal(runCli(["--allowlist", allowlistPath]), 1);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("runCli: non-array allowlist → exit non-zero", () => {
   const dir = mkdtempSync(join(tmpdir(), "audit-check-nonarray-"));
   try {

package/scripts/check-action-pins.mjs

@@ -27,13 +27,29 @@
  *     `pnpm/action-setup`.) A non-SHA ref (a tag like `v4`, a branch, a short
  *     SHA) FAILS the lint.
  *
- *   • FIRST-PARTY self-references — `dsj1984/mandrel-platform/...@<ref>` — are
- *     EXEMPT from this ratchet. They are this repo's OWN reusable workflows /
- *     composite actions, governed by the cross-repo portability lint's pin-lag
- *     guard (`check-workflow-portability.mjs`, Rule 3), and they carry a
- *     release-tag shape at publish time. The first-party owner is overridable
- *     via `--first-party-owner` for a fork. They ARE, however, subject to the
- *     single-pin invariant below.
+ *   • FIRST-PARTY self-references — `dsj1984/mandrel-platform/...@<ref>` — MUST
+ *     ALSO be a 40-char hex SHA, and are reported as their own violation class.
+ *     They were exempt until Story #354's audit: the exemption's stated
+ *     justification was that `check-workflow-portability.mjs` Rule 3 governs
+ *     them, but Rule 3's `collectInternalPins` skips any ref that is not
+ *     already a 40-hex SHA (`if (!isSha40(cls.ref)) return`), so a
+ *     branch-pinned self-reference was validated by NOTHING. The two other
+ *     first-party guards had the same hole — the single-pin invariant below
+ *     compares whatever refs it finds without requiring a SHA, and
+ *     `check-first-party-pin-freshness.mjs` files a non-SHA ref under an
+ *     informational `unpinnedRefs` note that never fails. So
+ *     `…/gitleaks-scan@main` was green on all three.
+ *
+ *     A moving self-ref is the same supply-chain risk the third-party ratchet
+ *     exists to close, with a wider blast radius: `pr-quality.yml` is inherited
+ *     by every consumer. It is also invisible to `platform-sync.mjs`, whose
+ *     rewrite regex matches `@[0-9a-fA-F]{40}` only — a branch-pinned consumer
+ *     workflow is silently skipped on every platform bump.
+ *
+ *     The land-then-bump flow is unaffected: it always pins full SHAs (see
+ *     docs/reusable-workflows.md § First-party self-pin freshness). The
+ *     first-party owner is overridable via `--first-party-owner` for a fork,
+ *     and first-party refs remain subject to the single-pin invariant below.
  *
  *   • LOCAL `./path` references and `docker://image` references are EXEMPT —
  *     a local path has no upstream tag to move, and a docker ref is pinned by
@@ -125,10 +141,18 @@ export function parseArgs(argv) {
 // ---------------------------------------------------------------------------
 
 /**
- * Scan a single file's TEXT for `uses:` step keys and evaluate each third-party
- * reference. Returns { violations: [...], scanned: <count> }. A violation is
- * `{ file, line, ref, owner, reason }`. `file` is left as passed-in (the
- * caller supplies a display path).
+ * Scan a single file's TEXT for `uses:` step keys and evaluate every REMOTE
+ * reference against the 40-hex SHA ratchet. Returns
+ * `{ violations, scanned, firstPartyViolations, firstPartyScanned }` — the two
+ * owner classes are counted and reported separately because their remediation
+ * differs (bump a vendored third-party pin vs. re-pin one of this repo's own
+ * call sites, which must move at every call site together to keep the
+ * single-pin invariant). A violation is `{ file, line, ref, owner, reason }`;
+ * `file` is left as passed-in (the caller supplies a display path).
+ *
+ * LOCAL (`./path`) and `docker://` references stay exempt: a local path has no
+ * upstream ref that can move, and a docker ref carries its own digest
+ * convention.
  *
  * Only lines whose first non-space token is `uses:` (a YAML mapping key) are
  * inspected — `uses:` appearing inside a comment or a `run:` heredoc never
@@ -138,13 +162,33 @@ export function parseArgs(argv) {
  */
 export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRST_PARTY_OWNER) {
   const violations = [];
+  const firstPartyViolations = [];
   let scanned = 0;
+  let firstPartyScanned = 0;
   const lines = String(content).split(/\r?\n/);
   for (let i = 0; i < lines.length; i++) {
     const bareRef = parseUsesLine(lines[i]);
     if (bareRef === null) continue;
     const cls = classifyUses(bareRef, firstPartyOwner);
-    if (cls.kind !== "third-party") continue; // local/docker/first-party/unparseable → exempt
+
+    // First-party self-references (Story #354 audit). A bare `owner/repo@ref`
+    // carrying no subpath is ratcheted too: the hazard is the MOVING REF, and
+    // it moves whether or not the reference names a subpath.
+    if (cls.kind === "first-party") {
+      firstPartyScanned++;
+      if (!isSha40(cls.ref)) {
+        firstPartyViolations.push({
+          file: displayFile,
+          line: i + 1,
+          ref: bareRef,
+          owner: cls.owner,
+          reason: `first-party self-reference "${cls.owner}" is pinned to "${cls.ref}", not a full 40-char commit SHA`,
+        });
+      }
+      continue;
+    }
+
+    if (cls.kind !== "third-party") continue; // local/docker/unparseable → exempt
     scanned++;
     if (!isSha40(cls.ref)) {
       violations.push({
@@ -156,7 +200,7 @@ export function scanContent(content, displayFile, firstPartyOwner = DEFAULT_FIRS
       });
     }
   }
-  return { violations, scanned };
+  return { violations, scanned, firstPartyViolations, firstPartyScanned };
 }
 
 // ---------------------------------------------------------------------------
@@ -178,7 +222,9 @@ export function runLint(opts) {
   const files = [...workflowFiles, ...listActionFiles(acDir)];
 
   const violations = [];
+  const firstPartyViolations = [];
   let scanned = 0;
+  let firstPartyScanned = 0;
   // Keep the raw workflow-file contents for the single-pin pass so we read
   // each file from disk once.
   const workflowRecords = [];
@@ -192,7 +238,9 @@ export function runLint(opts) {
     const display = relative(cwd, file) || file;
     const res = scanContent(content, display, opts.firstPartyOwner);
     violations.push(...res.violations);
+    firstPartyViolations.push(...res.firstPartyViolations);
     scanned += res.scanned;
+    firstPartyScanned += res.firstPartyScanned;
     if (workflowFiles.includes(file)) {
       workflowRecords.push({ file: display, content });
     }
@@ -204,9 +252,14 @@ export function runLint(opts) {
     : [];
 
   return {
-    ok: violations.length === 0 && singlePinViolations.length === 0,
+    ok:
+      violations.length === 0 &&
+      firstPartyViolations.length === 0 &&
+      singlePinViolations.length === 0,
     violations,
+    firstPartyViolations,
     scanned,
+    firstPartyScanned,
     files,
     singlePinViolations,
   };
@@ -242,6 +295,24 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
     );
   }
 
+  if (result.firstPartyViolations.length > 0) {
+    failed = true;
+    err(
+      `[action-pins] ❌ ${result.firstPartyViolations.length} first-party self-reference(s) pinned to a moving ref:`
+    );
+    for (const v of result.firstPartyViolations) {
+      err(`  • ${v.file}:${v.line} — ${v.reason}`);
+    }
+    err(
+      "[action-pins] Pin every first-party `uses:` to a full 40-char commit SHA " +
+        "too (keep the `# vX.Y.Z` tag note as a comment). A branch or tag ref " +
+        "means the revision that runs can change with no diff here — and " +
+        "`pr-quality.yml` is inherited by every consumer. It is also invisible " +
+        "to platform-sync.mjs, whose rewrite matches 40-hex SHAs only, so it " +
+        "would be skipped on every platform bump."
+    );
+  }
+
   if (result.singlePinViolations.length > 0) {
     failed = true;
     err(
@@ -263,7 +334,8 @@ export function runCli(argv, { log = console.log, err = console.error } = {}) {
   if (failed) return 1;
 
   log(
-    `[action-pins] ✅ all ${result.scanned} third-party action reference(s) are SHA-pinned ` +
+    `[action-pins] ✅ all ${result.scanned} third-party and ${result.firstPartyScanned} ` +
+      `first-party action reference(s) are SHA-pinned ` +
       `(${result.files.length} file(s) scanned); first-party single-pin invariant holds.`
   );
   return 0;