@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/verify-reapply-patches.cjs

@@ -17,37 +17,75 @@
  *                                    # false-positive halts beat silent successes
  *                                    # on lost content)
  *     [--json]                       # emit JSON report instead of human text
+ *     [--classify]                   # pre-merge mode: classify each backed-up
+ *                                    # file as incorporated / needs_merge /
+ *                                    # unknown (#4136); always exits 0
+ *     [--min-baseline-coverage <0..1>]  # OPT-IN strict gate (#4135): exit 3
+ *                                    # when the fraction of files verified
+ *                                    # against a resolved pristine baseline
+ *                                    # (baseline_covered / checked) falls below
+ *                                    # the threshold. Default: off — a
+ *                                    # low-coverage run stays green per the
+ *                                    # documented #934 advisory posture, but
+ *                                    # its coverage is ALWAYS headline-reported.
  *
- * Exit codes:
+ * Exit codes (default gate mode):
  *   0 — every user-added line is present in the merged file (gate passes)
- *   1 — at least one missing line in at least one file (gate fails)
+ *   1 — at least one missing line in at least one file (gate fails); outranks
+ *       a coverage-gate failure when both apply
  *   2 — usage / structural error (e.g. patches dir missing)
+ *   3 — opt-in coverage gate failed (--min-baseline-coverage not met; #4135)
  *
  * Bug #2969: the Step 5 gate previously trusted Claude's free-text "verified:
  * yes/no" reporting per hunk. The LLM was filling in `yes` even when content
  * had been silently dropped. Moving the check to a deterministic script is the
  * durability fix.
+ *
+ * Bug #4136 adds --classify (pre-merge mode, always exit 0 — informational;
+ * the binding gate remains the post-merge default run): per backed-up file,
+ * decides whether the user's modification was already adopted upstream
+ * ("Incorporated", reapply-patches.md Step 4 item 6). The classification is
+ * ONLY produced from a hash-validated pristine baseline with every
+ * significant user-added line present verbatim in the freshly installed
+ * version — a false Incorporated silently retires a live customization,
+ * which is worse than no Incorporated at all.
  */
 
 const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+// #4145: shared hash-first recovery for baselines stored at an unexpected
+// path under gsd-pristine/ (e.g. without the gsd-core/ prefix an earlier
+// release's writer dropped). Same module the installer's preserve-check uses,
+// so the two readers cannot drift apart again.
+const { findPristineByHash, findPristineInGit } = require('./lib/pristine-baseline.cjs');
 
 const SIGNIFICANT_MIN_CHARS = 12;
 const GSD_HOOK_VERSION_LINE_RE = /^(?:\/\/|#)\s*gsd-hook-version:\s*\S+\s*$/i;
 
 function parseArgs(argv) {
-  const opts = { patchesDir: null, configDir: null, pristineDir: null, json: false };
+  const opts = { patchesDir: null, configDir: null, pristineDir: null, json: false, classify: false, minBaselineCoverage: null };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--patches-dir') opts.patchesDir = argv[++i];
     else if (arg === '--config-dir') opts.configDir = argv[++i];
     else if (arg === '--pristine-dir') opts.pristineDir = argv[++i];
     else if (arg === '--json') opts.json = true;
-    else if (arg === '--help' || arg === '-h') {
+    else if (arg === '--classify') opts.classify = true;
+    else if (arg === '--min-baseline-coverage') {
+      const raw = argv[++i];
+      if (raw === undefined) {
+        throw new ExitError(2, '--min-baseline-coverage requires a value between 0 and 1');
+      }
+      const value = Number(raw);
+      if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new ExitError(2, `--min-baseline-coverage must be a number between 0 and 1, got: ${raw}`);
+      }
+      opts.minBaselineCoverage = value;
+    } else if (arg === '--help' || arg === '-h') {
       process.stdout.write(
-        'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json]\n',
+        'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json] [--classify] [--min-baseline-coverage <0..1>]\n',
       );
       throw new ExitError(0);
     } else {
@@ -178,15 +216,262 @@ const REASON = Object.freeze({
   // block" rather than "ignore everything" — it only applies when the hash was
   // recorded (modern installer) but the file is absent (specific gap).
   OK_NO_BASELINE: 'ok_no_baseline',
+  // Bug #4136: an on-disk gsd-pristine/ snapshot exists for this file but
+  // backup-meta.json records no pristine_hashes entry for it (older
+  // installer), so nothing confirms the snapshot is the baseline the backup
+  // was captured against — it could be a drifted newer-version snapshot the
+  // #3657 guard cannot see.  The default gate still uses it as the diff
+  // baseline (pre-#3657 behaviour, unchanged); --classify refuses to confirm
+  // adoption on an unvalidated baseline, so a file is never classified
+  // Incorporated on the snapshot's say-so alone.
+  OK_UNVALIDATED_BASELINE: 'ok_unvalidated_baseline',
   FAIL_INSTALLED_MISSING: 'fail_installed_missing',
   FAIL_INSTALLED_NOT_REGULAR_FILE: 'fail_installed_not_regular_file',
   FAIL_READ_ERROR: 'fail_read_error',
   FAIL_USER_LINES_MISSING: 'fail_user_lines_missing',
 });
 
-function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes }) {
+/**
+ * Bug #4136: stable per-file classification codes for --classify (pre-merge)
+ * mode. Tests assert via `assert.equal(result.classification, CLASSIFICATION.X)`
+ * rather than regex-matching prose, mirroring the REASON enum contract.
+ *
+ *   INCORPORATED — hash-validated pristine baseline confirms that every
+ *                  significant user-added line is already present verbatim
+ *                  in the freshly installed version: upstream adopted the
+ *                  customization. The workflow must NOT re-apply the diff.
+ *   NEEDS_MERGE  — validated baseline, but at least one significant
+ *                  user-added line is absent from the fresh install; the
+ *                  missing lines are listed for the merge step.
+ *   UNKNOWN      — no confirmable baseline (drift #3657, absent #934,
+ *                  unvalidated, or no --pristine-dir), zero significant
+ *                  user-added delta, or a structural failure. Never
+ *                  Incorporated.
+ */
+const CLASSIFICATION = Object.freeze({
+  INCORPORATED: 'incorporated',
+  NEEDS_MERGE: 'needs_merge',
+  UNKNOWN: 'unknown',
+});
+
+/**
+ * Typed outcome of resolving one file's pristine baseline. Shared by the
+ * post-merge gate (verifyFile) and the pre-merge classifier (classifyFile)
+ * so the two can never drift on what counts as a usable baseline (#4136).
+ */
+const PRISTINE_RESOLUTION = Object.freeze({
+  VALIDATED: 'validated',          // recorded hash matches the resolved snapshot
+  UNVALIDATED: 'unvalidated',      // snapshot present, no recorded hash to confirm it
+  DRIFTED: 'drifted',              // recorded hash mismatches the snapshot (#3657)
+  ABSENT_RECORDED: 'absent_recorded', // recorded hash, no snapshot anywhere (#934/#4145)
+  OVERBROAD: 'overbroad',          // no pristine dir, or a non-file at the path
+});
+
+/**
+ * Resolve the pristine baseline for one backed-up file, applying the #3657
+ * drift guard, the #4145 hash-first recovery, and the #934 absent-baseline
+ * guard. Extracted from verifyFile's inline block so --classify reasons over
+ * the exact same baseline semantics the post-merge gate enforces.
+ */
+function resolvePristineBaseline({ relPath, configDir, pristineDir, pristineHashes }) {
+  const hashKey = relPath.replace(/\\/g, '/');
+  const recordedHash = pristineHashes && pristineHashes[hashKey];
+  if (pristineDir) {
+    const pristinePath = path.join(pristineDir, relPath);
+    let pristinePathExists = false;
+    try {
+      const stat = fs.statSync(pristinePath);
+      pristinePathExists = true; // path exists (any type)
+      if (stat.isFile()) {
+        const candidate = fs.readFileSync(pristinePath, 'utf8');
+        if (recordedHash) {
+          if (sha256(candidate) === recordedHash) {
+            // Hash matches: the on-disk pristine is the correct baseline.
+            return { resolution: PRISTINE_RESOLUTION.VALIDATED, content: candidate };
+          }
+          // Hash mismatch: the on-disk gsd-pristine/ was refreshed to a newer
+          // GSD version after the backup was captured (Bug #3657).  Using it as
+          // the diff baseline would invert the delta and produce false
+          // FAIL_USER_LINES_MISSING reports.
+          return { resolution: PRISTINE_RESOLUTION.DRIFTED, content: null };
+        }
+        // No recorded hash for this file (older installer or absent
+        // backup-meta) — the default gate uses the on-disk pristine as-is
+        // (pre-fix behaviour); --classify treats it as unvalidated.
+        return { resolution: PRISTINE_RESOLUTION.UNVALIDATED, content: candidate };
+      }
+      // Non-file at pristinePath (e.g. a directory): fall through to
+      // over-broad mode below, which is safe and conservative.
+    } catch {
+      // Pristine stat threw — path is absent (ENOENT) or inaccessible.
+      // pristinePathExists stays false.
+    }
+
+    // Bug #4145: the canonical join missed, but the recorded hash is the
+    // baseline authority the #3657 drift guard already trusts. Before
+    // reporting ABSENT_RECORDED, scan gsd-pristine/ for byte-identical content
+    // (an earlier release may have stored the snapshot without the gsd-core/
+    // prefix). An exact sha-256 match cannot be the wrong baseline, and
+    // gsd-pristine/ holds only backed-up files, so the scan is small. The
+    // canonical path itself is excluded — a mismatching file at the joined
+    // path is drift (#3657), never re-adopted through the scan. A recovered
+    // baseline is hash-confirmed by construction, so it VALIDATES.
+    if (!pristinePathExists && recordedHash) {
+      try {
+        const recoveredRel = findPristineByHash(pristineDir, recordedHash, hashKey);
+        if (recoveredRel) {
+          return {
+            resolution: PRISTINE_RESOLUTION.VALIDATED,
+            content: fs.readFileSync(path.join(pristineDir, recoveredRel), 'utf8'),
+          };
+        }
+      } catch {
+        // scan or read failure — fall through to the ABSENT_RECORDED posture
+      }
+    }
+
+    if (pristinePathExists) {
+      // Present but not a regular file — over-broad mode is the safe side.
+      return { resolution: PRISTINE_RESOLUTION.OVERBROAD, content: null };
+    }
+
+    // Bug #4135: still nothing under gsd-pristine/ — the multi-version
+    // regeneration collapse (the #3407 promotion rule only keeps files
+    // byte-identical across the WHOLE version span, so the surviving set is
+    // precisely the files upstream did not change). When the config dir is
+    // itself a git repository, its history may hold the outgoing bytes: this
+    // is the workflow's documented Option A (reapply-patches.md Step 2),
+    // anchored by the SAME authority every other tier trusts — exact
+    // pristine_hashes equality. Read-only (git log / git show); any failure
+    // (no git, not a repo, no matching blob) degrades to ABSENT_RECORDED.
+    // A recovered baseline is hash-confirmed by construction, so it VALIDATES.
+    if (!pristinePathExists && recordedHash) {
+      try {
+        const fromGit = findPristineInGit(configDir, hashKey, recordedHash);
+        if (fromGit !== null) {
+          return { resolution: PRISTINE_RESOLUTION.VALIDATED, content: fromGit };
+        }
+      } catch {
+        // git unavailable or history walk failed — ABSENT_RECORDED posture
+      }
+    }
+    // Bug #934: recordedHash is present (modern installer) but no
+    // hash-matching pristine exists anywhere under gsd-pristine/ (the stat
+    // missed and the #4145 recovery found nothing).
+    if (recordedHash) {
+      return { resolution: PRISTINE_RESOLUTION.ABSENT_RECORDED, content: null };
+    }
+  }
+  return { resolution: PRISTINE_RESOLUTION.OVERBROAD, content: null };
+}
+
+/**
+ * #4086: resolve where a backed-up file's INSTALLED counterpart lives.
+ * Primary is the config-dir-relative join (the manifest key's native form).
+ * For skills/ keys of a runtime whose skills kind declares a `home` override
+ * (codex global → $HOME/.agents/skills), the file lives OUTSIDE configDir, so
+ * when the primary path is absent we fall back to the runtime's ACTUAL skills
+ * root — derived from the same `resolveRuntimeArtifactLayout` seam the
+ * installer writes through. Returns the primary path unchanged whenever the
+ * fallback is impossible (no manifest, no runtime, no override, no file).
+ */
+function resolveInstalledPath(configDir, relPath, skillsRedirect) {
+  const primary = path.join(configDir, relPath);
+  if (!skillsRedirect) return primary;
+  const hashKey = relPath.replace(/\\/g, '/');
+  if (!hashKey.startsWith(skillsRedirect.prefix)) return primary;
+  if (fs.existsSync(primary)) return primary;
+  const alt = path.join(skillsRedirect.root, hashKey.slice(skillsRedirect.prefix.length));
+  return fs.existsSync(alt) ? alt : primary;
+}
+
+/**
+ * #4086: build the skills-root fallback descriptor for a config dir from its
+ * own gsd-file-manifest.json (runtime + scope) and the runtime-artifact
+ * layout seam. Returns null whenever any step is unavailable — the verifier
+ * then behaves exactly as before (config-dir-relative only). Lazy + guarded
+ * require: runtime-artifact-layout.cjs is a built lib; a layout-unaware
+ * invocation must never crash the gate.
+ */
+function resolveSkillsRedirect(configDir) {
+  try {
+    const manifest = JSON.parse(
+      fs.readFileSync(path.join(configDir, 'gsd-file-manifest.json'), 'utf8'),
+    );
+    if (!manifest || typeof manifest.runtime !== 'string' || !manifest.runtime) return null;
+    const scope = manifest.scope === 'local' ? 'local' : 'global';
+    const { resolveRuntimeArtifactLayout } = require('./lib/runtime-artifact-layout.cjs');
+    const layout = resolveRuntimeArtifactLayout(manifest.runtime, configDir, scope);
+    const kind = layout.kinds.find((k) => k.kind === 'skills');
+    if (!kind) return null;
+    const root = path.resolve(path.join(kind.home || configDir, kind.destSubpath));
+    const resolvedConfig = path.resolve(configDir);
+    if (root === resolvedConfig || root.startsWith(resolvedConfig + path.sep)) return null; // allow-handrolled-containment: answers whether the skills root is a separate location, not a containment/admission decision
+    // Same descriptor-driven manifest prefix writeManifest uses for skills
+    // keys (hermes nests under 'skills/gsd/', everyone else 'skills/'), read
+    // from the same shipped registry the installer's _resolveHostBehaviors
+    // consults — never a re-derived literal (generative-fix-divergence guard).
+    let prefix = 'skills/';
+    try {
+      const { runtimes: registryRuntimes } = require('./lib/capability-registry.cjs');
+      const declared = registryRuntimes
+        && registryRuntimes[manifest.runtime]
+        && registryRuntimes[manifest.runtime].runtime
+        && registryRuntimes[manifest.runtime].runtime.hostBehaviors;
+      if (declared && typeof declared.skillsManifestPrefix === 'string') {
+        prefix = declared.skillsManifestPrefix;
+      }
+    } catch { /* keep default prefix */ }
+    return { root, prefix };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #4135: baseline-coverage accounting. A file counts as baseline-covered
+ * when its diff was actually computed against a resolved pristine baseline,
+ * i.e. its reason is one of the baseline-diff outcomes (null = lines
+ * verified present, OK_NO_USER_LINES_VS_PRISTINE = no user lines versus
+ * the baseline, FAIL_USER_LINES_MISSING = lines missing). Everything else
+ * is uncovered: the silent skips (no baseline anywhere per #934/#4135,
+ * drift per #3657, no-pristine over-broad with nothing significant) AND
+ * the structural failures (installed missing / not a file / read error),
+ * which never reached a baseline — they are loud blocking failures, but
+ * they were not baseline-verified either, and this aggregate exists to
+ * state exactly how much of the run the gate could reason about. When
+ * --pristine-dir is absent the whole run is over-broad (#2998 fallback):
+ * no file was verified against a baseline, covered is 0 by construction.
+ */
+const BASELINE_VERIFIED_REASONS = new Set([
+  REASON.OK_NO_USER_LINES_VS_PRISTINE,
+  REASON.FAIL_USER_LINES_MISSING,
+]);
+
+function classifyBaselineCoverage(results, pristineDirProvided) {
+  if (!pristineDirProvided) return 0;
+  let covered = 0;
+  for (const r of results) {
+    if (r.reason === null || BASELINE_VERIFIED_REASONS.has(r.reason)) covered++;
+  }
+  return covered;
+}
+
+/**
+ * #4135: the headline string for the human summary. A run with 12 of 13
+ * files unbaselined must not present the same way as a fully-verified one —
+ * the N-of-M form is the issue's own framing, and the unverified tail is
+ * only rendered when it is non-zero.
+ */
+function coverageHeadline(covered, total) {
+  const unverified = Math.max(0, total - covered);
+  const base = `Baseline coverage: ${covered} of ${total} file(s) verified against a pristine baseline`;
+  return unverified > 0 ? `${base} (${unverified} unverified)` : base;
+}
+
+function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes, skillsRedirect }) {
   const backupPath = path.join(patchesDir, relPath);
-  const installedPath = path.join(configDir, relPath);
+  const installedPath = resolveInstalledPath(configDir, relPath, skillsRedirect);
   const result = { file: relPath, status: 'ok', missing: [], reason: null };
 
   if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isFile()) {
@@ -224,80 +509,32 @@ function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashe
   // Normalize to forward slashes so the key lookup matches on Windows
   // where path.join produces backslash-separated relPath values but
   // backup-meta.json stores keys written with forward slashes.
-  const hashKey = relPath.replace(/\\/g, '/');
-  const recordedHash = pristineHashes && pristineHashes[hashKey];
+  // #4136: the inline baseline block (stat/read + #3657 drift guard + #4145
+  // hash-first recovery + #934 absent guard) moved into resolvePristineBaseline
+  // so the pre-merge classifier reasons over the exact same semantics.
+  const { resolution, content: pristineContent } =
+    resolvePristineBaseline({ relPath, configDir, pristineDir, pristineHashes });
 
-  let pristineContent = null;
-  if (pristineDir) {
-    const pristinePath = path.join(pristineDir, relPath);
-    // Bug #934: track whether the pristine path EXISTS on disk (stat did not
-    // throw ENOENT).  A regular file that fails to read, or a non-file path
-    // (e.g. a directory accidentally placed at the pristine path), is treated
-    // as "present but unusable" — we fall to over-broad mode (safe side).
-    // OK_NO_BASELINE is reserved for the strictly absent case: stat throws,
-    // meaning the file was never written (the gap the bug describes).
-    let pristinePathExists = false;
-    try {
-      const stat = fs.statSync(pristinePath);
-      pristinePathExists = true; // path exists (any type)
-      if (stat.isFile()) {
-        const candidate = fs.readFileSync(pristinePath, 'utf8');
-        // Bug #3657: if backup-meta.json recorded a pristine_hash for this
-        // file, validate that the on-disk pristine matches it.  A mismatch
-        // means the installer refreshed gsd-pristine/ to a newer GSD version
-        // after the backup was captured.  Using the wrong-version pristine as
-        // the diff baseline inverts the delta: upstream removals appear as
-        // "user-added lines that must survive", causing FAIL_USER_LINES_MISSING
-        // false positives.  When the hash is stale, skip the pristine and fall
-        // through to over-broad mode (every significant backup line is checked).
-        // Over-broad mode never false-fails for a different reason because all
-        // backup lines that are genuinely user-added will still be present in a
-        // correctly merged install.
-        if (recordedHash) {
-          if (sha256(candidate) === recordedHash) {
-            // Hash matches: the on-disk pristine is the correct baseline.
-            pristineContent = candidate;
-          } else {
-            // Hash mismatch: the on-disk gsd-pristine/ was refreshed to a newer
-            // GSD version after the backup was captured.  Using it as the diff
-            // baseline would invert the delta and produce false FAIL_USER_LINES_MISSING
-            // reports (Bug #3657).  Report the file as ok with a diagnostic code
-            // so the gate does not false-fail; a re-anchor or git-aware baseline
-            // step is required to verify this file correctly.
-            result.reason = REASON.OK_PRISTINE_DRIFT_DETECTED;
-            return result;
-          }
-        } else {
-          // No recorded hash for this file (older installer or absent
-          // backup-meta) — use the on-disk pristine as-is (pre-fix behaviour).
-          pristineContent = candidate;
-        }
-      }
-      // Non-file at pristinePath (e.g. a directory): stat succeeded so
-      // pristinePathExists is true; we fall through to over-broad mode below,
-      // which is safe and conservative.
-    } catch {
-      // Pristine stat threw — path is absent (ENOENT) or inaccessible.
-      // pristinePathExists stays false.
-    }
+  // Bug #3657: the resolved snapshot hash-mismatches the recorded baseline.
+  // Skip the file with a diagnostic code rather than diffing against the
+  // wrong baseline (a re-anchor or git-aware baseline step is required).
+  if (resolution === PRISTINE_RESOLUTION.DRIFTED) {
+    result.reason = REASON.OK_PRISTINE_DRIFT_DETECTED;
+    return result;
+  }
 
-    // Bug #934: recordedHash is present (modern installer) but the pristine
-    // path does not exist on disk at all (stat threw above).  This means
-    // saveLocalPatches recorded a hash but could not write the corresponding
-    // gsd-pristine/ file (the only candidate was discarded because it was from
-    // a newer release).  Falling to over-broad mode here would treat every
-    // upstream-changed line as a "user-added line that must survive", producing
-    // false FAIL_USER_LINES_MISSING for each upstream removal.  Since we
-    // cannot reason correctly without a baseline, the safe answer is advisory/
-    // non-blocking: return OK_NO_BASELINE and let the caller decide.
-    // NOTE: this guard fires ONLY when stat threw (path absent), not when the
-    // path is present but non-file — in that case over-broad mode is safer.
-    if (!pristinePathExists && recordedHash) {
-      result.reason = REASON.OK_NO_BASELINE;
-      return result;
-    }
+  // Bug #934 / #4145: a hash was recorded (modern installer) but no
+  // hash-matching pristine exists anywhere under gsd-pristine/ —
+  // advisory/non-blocking, the caller logs a warning.
+  if (resolution === PRISTINE_RESOLUTION.ABSENT_RECORDED) {
+    result.reason = REASON.OK_NO_BASELINE;
+    return result;
   }
 
+  // VALIDATED / UNVALIDATED keep the gate's pre-#4136 semantics: the resolved
+  // content (null for OVERBROAD) feeds computeUserAddedLines, whose no-pristine
+  // branch is the over-broad fallback.
+
   const userAdded = computeUserAddedLines(backupContent, pristineContent);
   if (userAdded.length === 0) {
     // Backup and pristine match exactly (or no significant content) — nothing
@@ -320,6 +557,101 @@ function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashe
   return result;
 }
 
+/**
+ * Bug #4136: pre-merge classification for reapply-patches Step 4. Runs over
+ * the SAME fixture state the gate sees (patches dir + freshly installed
+ * config dir + optional pristine dir) but BEFORE any merge, answering the
+ * question the gate cannot: is this file's user modification already adopted
+ * upstream, such that the workflow should leave the installed file untouched
+ * (status `Incorporated`) instead of re-grafting the diff?
+ *
+ * The classification is deliberately conservative in the direction the issue
+ * demands ("a false Incorporated is worse than no Incorporated"):
+ *   - only a hash-VALIDATED pristine baseline can confirm adoption — drift
+ *     (#3657), absent (#934/#4145), unvalidated (no recorded hash), and a
+ *     missing --pristine-dir all classify UNKNOWN;
+ *   - every significant user-added line (structural/trivial lines excluded by
+ *     isSignificantLine) must be present verbatim in the fresh install — a
+ *     signature-looking short line or a code fence matching anywhere in the
+ *     new file proves nothing;
+ *   - a backup with zero significant delta vs the validated pristine is
+ *     UNKNOWN (the workflow's Critical invariant: a backed-up file is never
+ *     concluded to have "no custom content", and Incorporated is a positive
+ *     adoption finding, not a skip);
+ *   - structural failures are reported with their FAIL_* reason but never
+ *     gate the run — the binding enforcement point stays the post-merge gate.
+ */
+function classifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes, skillsRedirect }) {
+  const backupPath = path.join(patchesDir, relPath);
+  const installedPath = resolveInstalledPath(configDir, relPath, skillsRedirect);
+  const result = { file: relPath, classification: CLASSIFICATION.UNKNOWN, reason: null, missing: [] };
+
+  if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isFile()) {
+    return result; // walked entry no longer exists — non-fatal
+  }
+
+  let installedStat;
+  try {
+    installedStat = fs.statSync(installedPath);
+  } catch {
+    result.reason = REASON.FAIL_INSTALLED_MISSING;
+    return result;
+  }
+  if (!installedStat.isFile()) {
+    result.reason = REASON.FAIL_INSTALLED_NOT_REGULAR_FILE;
+    return result;
+  }
+
+  let backupContent;
+  let installedContent;
+  try {
+    backupContent = fs.readFileSync(backupPath, 'utf8');
+    installedContent = fs.readFileSync(installedPath, 'utf8');
+  } catch {
+    result.reason = REASON.FAIL_READ_ERROR;
+    return result;
+  }
+
+  const { resolution, content: pristineContent } =
+    resolvePristineBaseline({ relPath, configDir, pristineDir, pristineHashes });
+
+  if (resolution === PRISTINE_RESOLUTION.DRIFTED) {
+    result.reason = REASON.OK_PRISTINE_DRIFT_DETECTED;
+    return result;
+  }
+  if (resolution === PRISTINE_RESOLUTION.ABSENT_RECORDED) {
+    result.reason = REASON.OK_NO_BASELINE;
+    return result;
+  }
+  if (resolution === PRISTINE_RESOLUTION.UNVALIDATED) {
+    result.reason = REASON.OK_UNVALIDATED_BASELINE;
+    return result;
+  }
+  if (resolution !== PRISTINE_RESOLUTION.VALIDATED) {
+    // OVERBROAD: no --pristine-dir (two-way fallback) or a non-file at the
+    // pristine path. Without a baseline there is no adoption evidence.
+    return result;
+  }
+
+  const userAdded = computeUserAddedLines(backupContent, pristineContent);
+  if (userAdded.length === 0) {
+    result.reason = REASON.OK_NO_USER_LINES_VS_PRISTINE;
+    return result;
+  }
+
+  for (const line of userAdded) {
+    if (!installedContent.includes(line)) {
+      result.missing.push(line.trim());
+    }
+  }
+  if (result.missing.length === 0) {
+    result.classification = CLASSIFICATION.INCORPORATED;
+  } else {
+    result.classification = CLASSIFICATION.NEEDS_MERGE;
+  }
+  return result;
+}
+
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (!opts.patchesDir || !opts.configDir) {
@@ -336,6 +668,58 @@ function main() {
   // Bug #3657: read pristine_hashes from backup-meta.json once and share
   // across all per-file verifications so each can detect drift independently.
   const pristineHashes = readPristineHashes(opts.patchesDir);
+  // #4086: skills-root fallback for runtimes whose skills kind declares a
+  // `home` override outside configDir (codex global → $HOME/.agents/skills).
+  const skillsRedirect = resolveSkillsRedirect(opts.configDir);
+
+  // Bug #4136: --classify is the pre-merge mode the workflow runs in Step 4
+  // to decide which files NOT to merge. It is informational — always exit 0 —
+  // because the binding enforcement stays with the post-merge gate below;
+  // a needs_merge or unknown outcome is direction for the merge step, not a
+  // failure, and halting here would block the very merge that resolves it.
+  if (opts.classify) {
+    const classifyResults = files.map((relPath) =>
+      classifyFile({
+        relPath,
+        patchesDir: opts.patchesDir,
+        configDir: opts.configDir,
+        pristineDir: opts.pristineDir,
+        pristineHashes,
+        skillsRedirect,
+      }),
+    );
+    const incorporatedResults = classifyResults.filter(
+      (r) => r.classification === CLASSIFICATION.INCORPORATED,
+    );
+    const incorporated = incorporatedResults.length;
+    const incorporated_files = incorporatedResults.map((r) => r.file);
+
+    if (opts.json) {
+      process.stdout.write(
+        JSON.stringify({ checked: classifyResults.length, incorporated, incorporated_files, results: classifyResults }, null, 2) + '\n',
+      );
+    } else {
+      process.stdout.write(`# Reapply Patch Classification (#4136)\n\n`);
+      process.stdout.write(`Checked: ${classifyResults.length} file(s)\n`);
+      process.stdout.write(`Incorporated: ${incorporated} file(s)\n`);
+      for (const f of incorporated_files) {
+        process.stdout.write(`  incorporated: ${f}\n`);
+      }
+      for (const r of classifyResults) {
+        if (r.classification === CLASSIFICATION.NEEDS_MERGE) {
+          process.stdout.write(`  needs merge: ${r.file}\n`);
+          for (const line of r.missing.slice(0, 5)) {
+            process.stdout.write(`    missing: ${line}\n`);
+          }
+          if (r.missing.length > 5) {
+            process.stdout.write(`    …and ${r.missing.length - 5} more line(s)\n`);
+          }
+        }
+      }
+    }
+    return 0;
+  }
+
   const results = files.map((relPath) =>
     verifyFile({
       relPath,
@@ -343,6 +727,7 @@ function main() {
       configDir: opts.configDir,
       pristineDir: opts.pristineDir,
       pristineHashes,
+      skillsRedirect,
     }),
   );
 
@@ -366,14 +751,52 @@ function main() {
   const no_baseline = noBaselineResults.length;
   const no_baseline_files = noBaselineResults.map((r) => r.file);
 
+  // Bug #4135: baseline coverage is a first-class aggregate. The collapse
+  // this reports is silent by design in every other surface (no_baseline is
+  // advisory, exit stays 0), which is exactly why it must be counted here:
+  // "A clean verifier exit reads as 'hunks survived'. On this run it meant
+  // '12 of 13 files were not checked at all.'"
+  const baseline_covered = classifyBaselineCoverage(results, Boolean(opts.pristineDir));
+
+  // Bug #4135: the opt-in strict coverage gate. Threshold semantics are >=
+  // (a run exactly at the threshold passes); an empty run is vacuously
+  // covered (nothing checked cannot be under-covered). A content failure
+  // (exit 1) outranks a coverage failure — it is the louder, more specific
+  // signal.
+  let coverageGateFailed = false;
+  if (opts.minBaselineCoverage !== null) {
+    const ratio = results.length === 0 ? 1 : baseline_covered / results.length;
+    coverageGateFailed = ratio < opts.minBaselineCoverage;
+  }
+
   if (opts.json) {
     process.stdout.write(
-      JSON.stringify({ checked: results.length, failures: failures.length, drifted, drifted_files, no_baseline, no_baseline_files, results }, null, 2) + '\n',
+      JSON.stringify({ checked: results.length, failures: failures.length, drifted, drifted_files, no_baseline, no_baseline_files, baseline_covered, results }, null, 2) + '\n',
     );
   } else {
     process.stdout.write(`# Hunk Verification Gate (#2969)\n\n`);
     process.stdout.write(`Checked: ${results.length} file(s)\n`);
-    process.stdout.write(`Failures: ${failures.length}\n\n`);
+    process.stdout.write(`Failures: ${failures.length}\n`);
+    // #4135: the coverage headline is printed on EVERY run, before any
+    // per-file detail, so a near-zero-coverage green run can never render
+    // identically to a fully-verified one.
+    process.stdout.write(`${coverageHeadline(baseline_covered, results.length)}\n\n`);
+    if (baseline_covered < results.length) {
+      if (!opts.pristineDir) {
+        process.stdout.write(`No --pristine-dir: over-broad fallback — nothing was verified against a pristine baseline (#2998).\n\n`);
+      } else {
+        const skipped = results.filter((r) => r.reason !== null && !BASELINE_VERIFIED_REASONS.has(r.reason));
+        process.stdout.write(`## Files not verified against a pristine baseline\n\n`);
+        process.stdout.write(`Advisory (non-blocking): their user customizations may or may not have survived the merge.\n\n`);
+        for (const r of skipped) {
+          process.stdout.write(`- ${r.file} (${r.reason})\n`);
+        }
+        process.stdout.write('\n');
+      }
+    }
+    if (coverageGateFailed) {
+      process.stdout.write(`COVERAGE GATE FAILED: baseline coverage ${(opts.minBaselineCoverage * 100).toFixed(1)}% required, ${results.length === 0 ? 100 : ((baseline_covered / results.length) * 100).toFixed(1)}% achieved (#4135 strict mode).\n\n`);
+    }
     if (failures.length > 0) {
       process.stdout.write(`## Files with missing user-added content\n\n`);
       for (const r of failures) {
@@ -389,11 +812,14 @@ function main() {
     }
   }
 
-  return failures.length > 0 ? 1 : 0;
+  if (failures.length > 0) return 1;
+  if (coverageGateFailed) return 3;
+  return 0;
 }
 
 if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, walk, REASON, readPristineHashes, sha256 };
+module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, classifyFile, walk, REASON, CLASSIFICATION, PRISTINE_RESOLUTION, resolvePristineBaseline, readPristineHashes, sha256, resolveInstalledPath, resolveSkillsRedirect, coverageHeadline, classifyBaselineCoverage };
+