yadflow 3.12.0 → 3.12.2

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [3.12.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.1...v3.12.2) (2026-07-14)
+
+
+### Bug Fixes
+
+* **checks:** waive verified-commits signature for content-free merge commits ([1e73837](https://github.com/abdelrahmannasr/yadflow/commit/1e738372f821e93020069b565d40315cd7be2591)), closes [#138](https://github.com/abdelrahmannasr/yadflow/issues/138)
+
+## [3.12.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.12.0...v3.12.1) (2026-07-14)
+
+
+### Bug Fixes
+
+* **cli:** reject unsafe detected IDE targets and opencode write destinations ([792a40b](https://github.com/abdelrahmannasr/yadflow/commit/792a40b399b92f8db9d560e314110c432b98d93e)), closes [#134](https://github.com/abdelrahmannasr/yadflow/issues/134)
+* **cli:** repair and validate persisted IDE targets ([81242ed](https://github.com/abdelrahmannasr/yadflow/commit/81242ed9a075ea067acb2f4497a745ee40e540a6))
+
 # [3.12.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.11.1...v3.12.0) (2026-07-11)
 
 

package/cli/manifest.mjs

@@ -116,8 +116,10 @@ export const LEGACY_HUB_FILES = {
 };
 
 // IDE install targets (relative to the target project root).
-export const IDE_FOLDER_TARGETS = ['.claude', '.agents', '.zencoder']; // <ide>/skills/<skill>/ (folder copy)
-export const IDE_OPENCODE_DIR = '.opencode/commands'; // <skill>.md (flat SKILL.md copy)
+export const IDE_FOLDER_TARGETS = Object.freeze(['.claude', '.agents', '.zencoder']); // <ide>/skills/<skill>/ (folder copy)
+export const IDE_OPENCODE_TARGET = '.opencode';
+export const IDE_TARGETS = Object.freeze([...IDE_FOLDER_TARGETS, IDE_OPENCODE_TARGET]);
+export const IDE_OPENCODE_DIR = `${IDE_OPENCODE_TARGET}/commands`; // <skill>.md (flat SKILL.md copy)
 
 // Module registration files copied from skills/sdlc/ into _bmad/sdlc/.
 export const MODULE_FILES = ['config.yaml', 'module-help.csv'];

package/cli/plan.mjs

@@ -7,7 +7,7 @@ import {
   asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON,
 } from './lib.mjs';
 import {
-  SKILLS, IDE_FOLDER_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
+  SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
   LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES,
 } from './manifest.mjs';
 
@@ -36,13 +36,149 @@ const dirAction = (scope, item, src, dest, { root } = {}) => ({
   apply: () => copyDir(src, dest),
 });
 
-// Which IDE targets this project wants. Recorded at setup time; falls back to
-// whichever IDE base dirs already exist, else .claude.
+// Persisted state gets one deliberately narrow compatibility repair. Explicit setup/planner input
+// does not: a caller typo is an error, while the known v3.11.1 `.cluade` stamp is safely migrated.
+const PERSISTED_IDE_ALIASES = new Map([['.cluade', '.claude']]);
+const IDE_TARGET_ERROR_CODE = 'YAD_IDE_TARGET';
+const sameTargets = (a, b) => Array.isArray(a) && a.length === b.length && a.every((v, i) => v === b[i]);
+const displayTarget = (value) => {
+  if (value === undefined) return 'undefined';
+  try { return JSON.stringify(value) ?? String(value); } catch { return String(value); }
+};
+const ideTargetError = (message) => Object.assign(new Error(message), { code: IDE_TARGET_ERROR_CODE });
+const lstatIfPresent = (full) => {
+  try {
+    return fs.lstatSync(full);
+  } catch (e) {
+    if (e?.code === 'ENOENT') return null;
+    throw e;
+  }
+};
+const ideContainers = (ide) => ide === '.opencode'
+  ? [ide, IDE_OPENCODE_DIR]
+  : [ide, path.join(ide, 'skills')];
+
+function assertSafeIdeContainers(root, ide) {
+  for (const relPath of ideContainers(ide)) {
+    const stat = lstatIfPresent(path.join(root, relPath));
+    if (!stat) continue;
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      const kind = stat.isSymbolicLink() ? 'a symbolic link' : 'not a directory';
+      throw ideTargetError(`unsafe IDE target '${ide}': ${relPath} is ${kind}`);
+    }
+  }
+}
+
+function assertSafeOpenCodeWriteDestinations(root, skills) {
+  for (const skill of new Set(skills)) {
+    const relPath = path.join(IDE_OPENCODE_DIR, `${skill}.md`);
+    const stat = lstatIfPresent(path.join(root, relPath));
+    if (!stat) continue;
+    let kind = null;
+    if (stat.isSymbolicLink()) kind = 'a symbolic link';
+    else if (!stat.isFile()) kind = 'not a regular file';
+    else if (stat.nlink > 1) kind = 'linked to multiple paths';
+    if (kind) throw ideTargetError(`unsafe IDE target '.opencode': ${relPath} is ${kind}`);
+  }
+}
+
+// Pure target inspection. Valid entries are trimmed and deduplicated in input order; unsupported
+// entries are returned to the caller for reporting rather than ever becoming filesystem paths.
+export function normalizeIdeTargets(input, { repairAliases = false } = {}) {
+  const shapeValid = Array.isArray(input);
+  const invalid = shapeValid ? [] : [input];
+  const repaired = [];
+  const targets = [];
+  const seen = new Set();
+  for (const raw of shapeValid ? input : []) {
+    if (typeof raw !== 'string') { invalid.push(raw); continue; }
+    const trimmed = raw.trim();
+    const target = repairAliases ? (PERSISTED_IDE_ALIASES.get(trimmed) || trimmed) : trimmed;
+    if (!IDE_TARGETS.includes(target)) { invalid.push(raw); continue; }
+    if (target !== trimmed) repaired.push({ from: trimmed, to: target });
+    if (!seen.has(target)) { seen.add(target); targets.push(target); }
+  }
+  return { targets, invalid, repaired, shapeValid };
+}
+
+// Strict boundary for every explicit action-builder/setup input. Returning only canonical values
+// makes path construction below safe by construction.
+export function canonicalIdeTargets(input) {
+  const state = normalizeIdeTargets(input);
+  if (!state.shapeValid) {
+    throw ideTargetError(`IDE targets must be a non-empty array (supported: ${IDE_TARGETS.join(', ')})`);
+  }
+  if (state.invalid.length) {
+    throw ideTargetError(`unsupported IDE target(s): ${state.invalid.map(displayTarget).join(', ')} (supported: ${IDE_TARGETS.join(', ')})`);
+  }
+  if (!state.targets.length) {
+    throw ideTargetError(`at least one IDE target is required (supported: ${IDE_TARGETS.join(', ')})`);
+  }
+  return state.targets;
+}
+
+// A canonical relative name is necessary but not sufficient: an existing IDE root (or its install
+// container) could be a file or symlink that redirects writes/removals outside the project. Validate
+// every target before constructing ANY actions, so a bad later target cannot cause a partial install.
+export function safeIdeTargetsFor(root, input) {
+  const targets = canonicalIdeTargets(input);
+  for (const ide of targets) assertSafeIdeContainers(root, ide);
+  return targets;
+}
+
+// Fallback discovery must not promote a supported-looking file/symlink into an install target.
+// Keep unsafe entries for diagnostics, while returning only real IDE directories with safe install
+// containers. Unexpected filesystem errors remain fatal instead of being mistaken for bad input.
+export function detectedIdeTargetStateFor(root) {
+  const targets = [];
+  const unsafe = [];
+  for (const ide of IDE_TARGETS) {
+    if (!lstatIfPresent(path.join(root, ide))) continue;
+    try {
+      assertSafeIdeContainers(root, ide);
+      targets.push(ide);
+    } catch (e) {
+      if (e?.code !== IDE_TARGET_ERROR_CODE) throw e;
+      unsafe.push({ target: ide, message: e.message });
+    }
+  }
+  return { targets, unsafe };
+}
+
+// Which IDE targets this project wants. Persisted values are recovery-oriented: repair the one known
+// alias, filter everything else, then fall back to supported IDE dirs already present (or .claude).
+// The full state lets reconcile report drift without mutating during a read-only check.
+export function ideTargetStateFor(root) {
+  const stampPath = path.join(root, PROJECT_FILES.version);
+  const hasStamp = exists(stampPath);
+  const rec = readJSON(stampPath);
+  const recordIsObject = !!rec && typeof rec === 'object' && !Array.isArray(rec);
+  const hasField = recordIsObject && Object.hasOwn(rec, 'ideTargets');
+  const raw = hasField ? rec.ideTargets : undefined;
+  const normalized = normalizeIdeTargets(raw, { repairAliases: true });
+  let targets = normalized.targets;
+  let usedFallback = false;
+  let unsafeDetected = [];
+  if (!targets.length) {
+    const detected = detectedIdeTargetStateFor(root);
+    targets = detected.targets.length ? detected.targets : ['.claude'];
+    unsafeDetected = detected.unsafe;
+    usedFallback = true;
+  }
+  return {
+    ...normalized,
+    targets,
+    hasStamp,
+    recordIsObject,
+    hasField,
+    usedFallback,
+    unsafeDetected,
+    needsRepair: hasStamp && !sameTargets(raw, targets),
+  };
+}
+
 export function ideTargetsFor(root) {
-  const rec = readJSON(path.join(root, PROJECT_FILES.version));
-  if (rec?.ideTargets?.length) return rec.ideTargets;
-  const present = [...IDE_FOLDER_TARGETS, '.opencode'].filter((d) => exists(path.join(root, d)));
-  return present.length ? present : ['.claude'];
+  return ideTargetStateFor(root).targets;
 }
 
 // A brand-new first-party skill is `missing` on every existing install. Relabel that to status `'new'`
@@ -53,8 +189,10 @@ const asNewSkill = (a) => (a.status === 'missing' ? { ...a, status: 'new' } : a)
 
 // Module = skills installed into each IDE target + the _bmad/sdlc registration.
 export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
+  const targets = safeIdeTargetsFor(root, ideTargets);
+  if (targets.includes('.opencode')) assertSafeOpenCodeWriteDestinations(root, SKILLS);
   const actions = [];
-  for (const ide of ideTargets) {
+  for (const ide of targets) {
     if (ide === '.opencode') {
       for (const s of SKILLS) {
         actions.push(asNewSkill(fileAction(
@@ -92,8 +230,15 @@ export function moduleActions(root, ideTargets = ideTargetsFor(root)) {
 // one, so a single update completes the rename even when the new copy would otherwise be
 // skipped as missing-scope.
 export function legacyModuleActions(root, ideTargets = ideTargetsFor(root)) {
+  const targets = safeIdeTargetsFor(root, ideTargets);
+  if (targets.includes('.opencode')) {
+    const writes = Object.entries(LEGACY_SKILLS)
+      .filter(([, old]) => exists(path.join(root, IDE_OPENCODE_DIR, `${old}.md`)))
+      .map(([skill]) => skill);
+    assertSafeOpenCodeWriteDestinations(root, writes);
+  }
   const actions = [];
-  for (const ide of ideTargets) {
+  for (const ide of targets) {
     for (const [skill, old] of Object.entries(LEGACY_SKILLS)) {
       if (ide === '.opencode') {
         const oldDest = path.join(root, IDE_OPENCODE_DIR, `${old}.md`);
@@ -137,8 +282,9 @@ export function legacyModuleActions(root, ideTargets = ideTargetsFor(root)) {
 // clean tree yields nothing and the purge is idempotent. apply() just deletes the install (no
 // replacement — that is what makes this a removal, not a rename).
 export function removedModuleActions(root, ideTargets = ideTargetsFor(root)) {
+  const targets = safeIdeTargetsFor(root, ideTargets);
   const actions = [];
-  for (const ide of ideTargets) {
+  for (const ide of targets) {
     for (const skill of REMOVED_SKILLS) {
       if (ide === '.opencode') {
         const dest = path.join(root, IDE_OPENCODE_DIR, `${skill}.md`);

package/cli/reconcile.mjs

@@ -14,6 +14,7 @@ import { VERSION, PROJECT_FILES } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
+  ideTargetStateFor,
 } from './plan.mjs';
 import { gitHead, packRepo } from './setup.mjs';
 import { groupByRoot, commitUpdates } from './update-commit.mjs';
@@ -31,14 +32,36 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
   if (!exists(path.join(root, PROJECT_FILES.reposRegistry))) gaps.push('no repos registered (.sdlc/repos.json absent)');
 
+  // Resolve untrusted persisted IDE targets once, before any filesystem action is constructed.
+  // The returned list contains canonical allowlisted roots only.
+  const ideState = ideTargetStateFor(root);
+  const ideTargets = ideState.targets;
+  const stampPath = path.join(root, PROJECT_FILES.version);
+  const writeCanonicalStamp = () => {
+    const current = readJSON(stampPath, {});
+    const record = current && typeof current === 'object' && !Array.isArray(current) ? current : {};
+    writeJSON(stampPath, { ...record, version: VERSION, ideTargets });
+  };
+
   // --- deterministic file actions (module + hub CI + author allowlists + every registered repo),
   //     plus pre-2.0 sdlc-* -> yad-* migrations ('legacy': old name installed; rename in place)
   //     and purge of skills removed in a later release ('removed': delete the lingering install) ---
   const actions = [
-    ...moduleActions(root), ...legacyModuleActions(root), ...removedModuleActions(root),
+    ...moduleActions(root, ideTargets), ...legacyModuleActions(root, ideTargets), ...removedModuleActions(root, ideTargets),
     ...hubActions(root), ...legacyHubActions(root),
     ...authorsActions(root, registry.repos),
   ];
+  if (ideState.needsRepair) {
+    actions.push({
+      scope: 'hub',
+      item: `${PROJECT_FILES.version} ideTargets`,
+      status: 'outdated',
+      root,
+      paths: [PROJECT_FILES.version],
+      // The canonical stamp is written once, after every filesystem action succeeds below.
+      apply: () => undefined,
+    });
+  }
   for (const repo of registry.repos) actions.push(...repoActions(root, repo), ...legacyRepoActions(root, repo));
 
   // --- stale code-context (HEAD moved since last pack) ---
@@ -77,6 +100,30 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
     for (const i of notOk) log(`    ${MARK[i.status]}  ${i.item}`);
   }
   for (const g of gaps) warn(g);
+  const shownInvalid = ideState.invalid.map((v) => {
+    try { return JSON.stringify(v) ?? String(v); } catch { return String(v); }
+  });
+  if (ideState.hasStamp && !ideState.recordIsObject) {
+    warn(`${PROJECT_FILES.version}: version stamp is unreadable or not a JSON object; using safe targets: ${ideTargets.join(', ')}`);
+  } else if (ideState.hasStamp && !ideState.hasField) {
+    warn(`${PROJECT_FILES.version}: ideTargets is missing; using safe targets: ${ideTargets.join(', ')}`);
+  } else if (ideState.hasStamp && !ideState.shapeValid) {
+    warn(`${PROJECT_FILES.version}: ideTargets is not an array; ignored persisted value: ${shownInvalid.join(', ')}; using safe targets: ${ideTargets.join(', ')}`);
+  } else if (ideState.hasStamp && ideState.usedFallback && !ideState.invalid.length) {
+    warn(`${PROJECT_FILES.version}: ideTargets is empty; using safe targets: ${ideTargets.join(', ')}`);
+  }
+  if (ideState.invalid.length && ideState.shapeValid) {
+    warn(`${PROJECT_FILES.version}: ignored unsupported persisted IDE target(s): ${shownInvalid.join(', ')}`);
+  }
+  if (ideState.repaired.length) {
+    warn(`${PROJECT_FILES.version}: persisted .cluade target will be repaired to .claude`);
+  }
+  for (const unsafe of ideState.unsafeDetected) {
+    warn(`${PROJECT_FILES.version}: ignored unsafe detected IDE path '${unsafe.target}'; ${unsafe.message}; using safe targets: ${ideTargets.join(', ')}`);
+  }
+  if (exists(path.join(root, '.cluade'))) {
+    warn('existing .cluade path was left untouched; review its contents and remove it manually');
+  }
 
   const fixable = actions.filter((a) =>
     a.status !== 'ok' && (scope === 'all' ? true : a.status !== 'missing'),
@@ -103,9 +150,9 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   if (force) {
     for (const a of actions.filter((a) => a.status === 'ok')) { a.apply(); appliedActions.push(a); }
   }
-  // refresh the version stamp (preserve recorded ideTargets) and let it ride the hub's update commit
-  const rec = readJSON(path.join(root, PROJECT_FILES.version), {});
-  writeJSON(path.join(root, PROJECT_FILES.version), { ...rec, version: VERSION });
+  // Refresh the version stamp and persist only the canonical targets used to build actions. This also
+  // completes legacy/corrupt target migration even when no skill content itself needed an update.
+  writeCanonicalStamp();
   appliedActions.push({ scope: 'hub', item: PROJECT_FILES.version, status: 'stamp', root, paths: [PROJECT_FILES.version] });
   applied ? ok(`reconciled ${applied} item(s)`) : info('nothing to fix');
   if (gaps.length) hand('one-time setup still missing — run `yad setup`.');

package/cli/setup.mjs

@@ -6,10 +6,11 @@ import {
   c, log, step, guide, ok, info, warn, hand, fail, ask, askYesNo, run, has,
   exists, readJSON, readJSONStrict, writeJSON,
 } from './lib.mjs';
-import { VERSION, IDE_FOLDER_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
+import { VERSION, IDE_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
 import {
   moduleActions, repoActions, hubActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
+  safeIdeTargetsFor, detectedIdeTargetStateFor,
 } from './plan.mjs';
 import { validateLogin, rolesForScope } from './platform.mjs';
 
@@ -34,7 +35,26 @@ export function parseRolesSpec(s) {
   return out;
 }
 
-const ALL_IDES = [...IDE_FOLDER_TARGETS, '.opencode'];
+// Programmatic setup is strict; interactive setup keeps asking until it receives at least one valid
+// canonical target. Both paths return the same trimmed, ordered, deduplicated representation.
+export async function selectIdeTargets(root, provided, asker = ask) {
+  if (provided !== undefined) return safeIdeTargetsFor(root, provided);
+  const detected = detectedIdeTargetStateFor(root);
+  const present = detected.targets;
+  for (const unsafe of detected.unsafe) warn(`${unsafe.message}; excluded from IDE defaults`);
+  const def = (present.length ? present : ['.claude']).join(',');
+  for (;;) {
+    const answer = await asker(`IDE targets to install ${c.dim('(comma-separated: ' + IDE_TARGETS.join(', ') + ')')}`, def);
+    if (answer === undefined || answer === null) throw new Error('IDE target selection ended before a valid choice was provided');
+    const values = String(answer ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    try {
+      return safeIdeTargetsFor(root, values);
+    } catch (e) {
+      if (process.env.SDLC_NONINTERACTIVE || e?.code !== 'YAD_IDE_TARGET') throw e;
+      warn(e.message);
+    }
+  }
+}
 
 export function detectPlatform(remoteUrl = '') {
   if (/gitlab/i.test(remoteUrl)) return 'gitlab';
@@ -416,13 +436,7 @@ export async function runSetup(root, opts = {}) {
     'Copies the yad-* skills into your AI tool(s) so they appear in Claude Code / agents / opencode.',
     'Enter the IDE folders to install into, comma-separated; default = whatever is already present.',
   ]);
-  let ideTargets = opts.ideTargets;
-  if (!ideTargets) {
-    const present = ALL_IDES.filter((d) => exists(path.join(root, d)));
-    const def = (present.length ? present : ['.claude']).join(',');
-    const answer = await ask(`IDE targets to install ${c.dim('(comma-separated: ' + ALL_IDES.join(', ') + ')')}`, def);
-    ideTargets = answer.split(',').map((s) => s.trim()).filter(Boolean);
-  }
+  const ideTargets = await selectIdeTargets(root, opts.ideTargets);
   applyActions(moduleActions(root, ideTargets), { force: true });
   // Migrate any pre-2.0 install in place: remove the old sdlc-* skill copies in the project's
   // IDE targets and install their yad-* renames. Without this, setup only ADDED yad-* and left

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.12.0",
+  "version": "3.12.2",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-checks/references/check-gates.md

@@ -93,6 +93,13 @@ repo. For each commit in `<base>..HEAD`, two independent checks:
   (2+ parents) — a merge's author is whoever pressed merge (often a platform noreply), not a roster
   human, and its content already passed the PR gate suite. This waiver matters for the push-on-default
   `yad-update-guard` (§9), which — unlike this PR-triggered gate — sees merge commits.
+  A merge commit is **additionally signature-waived when it introduces no content of its own** (its
+  combined diff — `git diff-tree --cc` — is empty, i.e. no conflict-resolution or evil-merge hunks):
+  every change it carries already lives in an individually author+signature-checked parent, so there
+  is nothing to protect. This unblocks **self-hosted GitLab**, which does not sign UI-created merge
+  commits (the signature API returns 404) — without it every routine merge would red the branch. A
+  merge that *does* introduce content of its own still requires a verified signature (fail-closed),
+  so an evil merge pushed direct-to-default cannot smuggle in unverified changes.
 
 Degradation is explicit, never silent: a missing allowlist SKIPs the author check with a warning
 (configure roster emails, re-wire); no GitHub/GitLab remote SKIPs the signature check (the badge is a

package/skills/yad-checks/templates/checks/verified-commits.sh

@@ -11,6 +11,12 @@
 # commits set the platform itself as the committer (e.g. noreply@github.com), and their integrity is
 # covered by the signature check (the platform signs them).
 #
+# Merge-commit signature exemption: a merge that introduces NO content of its own (its combined diff
+# is empty — no conflict-resolution / evil-merge hunks) is signature-waived, because every change it
+# carries already lives in its individually author+signature-checked parents. This unblocks self-hosted
+# GitLab, which does not sign UI-created merge commits (the signature API returns 404). A merge that
+# DOES introduce content of its own still requires a verified signature (fail-closed).
+#
 # Degradation is explicit, never silent:
 #   - no allowlist file        -> author check SKIPPED with a warning (configure emails, re-wire)
 #   - no GitHub/GitLab remote  -> signature check SKIPPED with a warning (no platform, no badge)
@@ -88,6 +94,19 @@ signature_verified() {
   esac
 }
 
+# 0 when a merge commit introduced NO content of its own. The combined diff (--cc) lists only hunks
+# that differ from ALL parents, so empty output means every change lives in an individually-checked
+# parent — there is no conflict-resolution or evil-merge content unique to the merge commit, hence
+# nothing an unverified author could smuggle in past the per-parent author+signature checks.
+merge_introduces_no_content() {
+  # `local` on its own line: `local out=$(...)` would mask the substitution's exit status (local
+  # always returns 0). A git error (e.g. a parent tree missing in a shallow clone) must fail closed —
+  # an empty stdout from a *failed* command is not evidence the merge is content-free.
+  local out
+  out="$(git diff-tree --cc --no-commit-id -r "$1")" || return 1
+  [ -z "$out" ]
+}
+
 rc=0
 while IFS= read -r sha; do
   [ -z "$sha" ] && continue
@@ -126,6 +145,11 @@ while IFS= read -r sha; do
   if [ -n "$platform" ]; then
     if signature_verified "$sha"; then
       echo "PASS [verified-commits]: ${short} signature verified by ${platform}"
+    elif [ "$is_merge" = 1 ] && merge_introduces_no_content "$sha"; then
+      # Content-free merge: nothing to protect. Self-hosted GitLab does not sign UI merge commits, so
+      # requiring a signature here would block every routine merge. An evil merge (content of its own)
+      # falls through to FAIL below.
+      echo "WARN [verified-commits]: ${short} unsigned merge commit — introduces no content of its own (covered by verified parents); signature waived. (Self-hosted GitLab does not sign UI merge commits; on a platform that signs its merges an unsigned content-free merge is unusual but still harmless.)"
     else
       echo "FAIL [verified-commits]: ${short} signature missing/unverified — sign commits (GPG/SSH key registered on ${platform}), or the signature API was unreachable (GitLab: set GITLAB_TOKEN/SDLC_API_TOKEN with read_api)."
       rc=1