@opengsd/gsd-core 1.18.0 → 1.20.0

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

@@ -29,6 +29,14 @@
  *                                    # documented #934 advisory posture, but
  *                                    # its coverage is ALWAYS headline-reported.
  *
+ *     [--hunks]                      # pre-merge mode (#4435): per-hunk stock vs
+ *                                    # user text, content hash, recommendation
+ *                                    # and exception reasons; always exits 0
+ *     [--decisions <path>]           # gate mode only (#4435): JSON file of human
+ *                                    # keep/retire/rewrite decisions bound to
+ *                                    # hunk content hashes; retire/rewrite drop
+ *                                    # that hunk's required lines from the gate
+ *
  * 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); outranks
@@ -60,12 +68,15 @@ const { ExitError, runMain } = require('./lib/cli-exit.cjs');
 // 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');
+// #4435: line matcher (Myers, edit-distance capped) used to split a backup into
+// per-hunk user/stock regions and to locate upstream changes over the baseline.
+const { matchLines } = require('./lib/markdown-line-diff.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, classify: false, minBaselineCoverage: null };
+  const opts = { patchesDir: null, configDir: null, pristineDir: null, json: false, classify: false, minBaselineCoverage: null, hunks: false, decisionsPath: null };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === '--patches-dir') opts.patchesDir = argv[++i];
@@ -73,7 +84,12 @@ function parseArgs(argv) {
     else if (arg === '--pristine-dir') opts.pristineDir = argv[++i];
     else if (arg === '--json') opts.json = true;
     else if (arg === '--classify') opts.classify = true;
-    else if (arg === '--min-baseline-coverage') {
+    else if (arg === '--hunks') opts.hunks = true;
+    else if (arg === '--decisions') {
+      const raw = argv[++i];
+      if (raw === undefined) throw new ExitError(2, '--decisions requires a path');
+      opts.decisionsPath = raw;
+    } 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');
@@ -85,7 +101,7 @@ function parseArgs(argv) {
       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] [--classify] [--min-baseline-coverage <0..1>]\n',
+        'usage: verify-reapply-patches.cjs --patches-dir <path> --config-dir <path> [--pristine-dir <path>] [--json] [--classify] [--hunks] [--decisions <path>] [--min-baseline-coverage <0..1>]\n',
       );
       throw new ExitError(0);
     } else {
@@ -469,7 +485,279 @@ function coverageHeadline(covered, total) {
   return unverified > 0 ? `${base} (${unverified} unverified)` : base;
 }
 
-function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes, skillsRedirect }) {
+// ── #4435: per-hunk model ────────────────────────────────────────────────
+const HUNK_REASON = Object.freeze({
+  BASELINE_UNCONFIRMED: 'baseline_unconfirmed',
+  DIFF_TOO_LARGE: 'diff_too_large',
+  ALREADY_UPSTREAM: 'already_upstream',
+  PARTIALLY_UPSTREAM: 'partially_upstream',
+  ANCHOR_ORPHANED: 'anchor_orphaned',
+  REGION_CHANGED_UPSTREAM: 'region_changed_upstream',
+});
+const HUNK_RECOMMENDATION = Object.freeze({ KEEP: 'keep', RETIRE: 'retire', REVIEW: 'review' });
+const DISPOSITION = Object.freeze({ KEEP: 'keep', RETIRE: 'retire', REWRITE: 'rewrite' });
+
+/**
+ * #4435: split a backup into hunks against the pristine baseline. Pure. The
+ * union of every hunk's required_lines equals computeUserAddedLines(backup,
+ * pristine) — same significance + normalization predicate.
+ */
+function computeHunks(fileKey, backupContent, pristineContent) {
+  const B = backupContent.split(/\r?\n/);
+  if (!pristineContent) {
+    const required = computeUserAddedLines(backupContent, null);
+    if (required.length === 0) return [];
+    return numberHunks(fileKey, [{
+      kind: 'file',
+      user_lines: B.filter(isSignificantLine),
+      stock_lines: [],
+      required_lines: required,
+      anchor_before: null,
+      anchor_after: null,
+      stock_range: null,
+      diff_too_large: false,
+    }]);
+  }
+  const P = pristineContent.split(/\r?\n/);
+  const nP = P.map(normalizeUpstreamOwnedLine);
+  const nB = B.map(normalizeUpstreamOwnedLine);
+  const pristineSet = new Set(nP);
+  const isRequired = (line) =>
+    isSignificantLine(line) && !pristineSet.has(normalizeUpstreamOwnedLine(line));
+  const m = matchLines(nP, nB);
+  if (m === null) {
+    const required = B.filter(isRequired);
+    if (required.length === 0) return [];
+    return numberHunks(fileKey, [{
+      kind: 'replacement',
+      user_lines: required,
+      stock_lines: [],
+      required_lines: required.slice(),
+      anchor_before: null,
+      anchor_after: null,
+      stock_range: null,
+      diff_too_large: true,
+    }]);
+  }
+  const hunks = [];
+  let prevP = -1;
+  let run = [];
+  const flush = (s, e) => {
+    const userLines = run;
+    run = [];
+    const stockLines = P.slice(s, e);
+    if (!userLines.some(isSignificantLine) && !stockLines.some(isSignificantLine)) return;
+    const kind = userLines.length && stockLines.length ? 'replacement' : userLines.length ? 'addition' : 'deletion';
+    let before = null;
+    for (let i = s - 1; i >= 0; i--) {
+      if (isSignificantLine(P[i])) { before = P[i]; break; }
+    }
+    let after = null;
+    for (let i = e; i < P.length; i++) {
+      if (isSignificantLine(P[i])) { after = P[i]; break; }
+    }
+    hunks.push({
+      kind,
+      user_lines: userLines,
+      stock_lines: stockLines,
+      required_lines: userLines.filter(isRequired),
+      anchor_before: before,
+      anchor_after: after,
+      stock_range: [s, e],
+      diff_too_large: false,
+    });
+  };
+  for (let j = 0; j < B.length; j++) {
+    if (m[j] === -1) {
+      run.push(B[j]);
+    } else {
+      flush(prevP + 1, m[j]);
+      prevP = m[j];
+    }
+  }
+  flush(prevP + 1, P.length);
+  return numberHunks(fileKey, hunks);
+}
+
+function numberHunks(fileKey, hunks) {
+  return hunks.map((h, i) => ({
+    hunk_id: i + 1,
+    hunk_hash: sha256(JSON.stringify([fileKey, h.kind, h.user_lines, h.stock_lines, h.anchor_before, h.anchor_after, h.stock_range])),
+    kind: h.kind,
+    user_lines: h.user_lines,
+    stock_lines: h.stock_lines,
+    required_lines: h.required_lines,
+    anchor_before: h.anchor_before,
+    anchor_after: h.anchor_after,
+    stock_range: h.stock_range,
+    diff_too_large: h.diff_too_large,
+  }));
+}
+
+/**
+ * #4435: annotate hunks with presence in the fresh install, closed-vocabulary
+ * reasons and a recommendation. Pure; strips stock_range / diff_too_large.
+ */
+function annotateHunks(hunks, { pristineContent, installedContent, baselineConfirmed }) {
+  const installed = installedContent == null ? '' : installedContent;
+  const iLines = new Set(installed.split(/\r?\n/).map((l) => normalizeUpstreamOwnedLine(l).trim()));
+  let upstreamUnknown = false;
+  const intervals = [];
+  if (pristineContent && hunks.some((h) => h.stock_range)) {
+    const P = pristineContent.split(/\r?\n/);
+    const nP = P.map(normalizeUpstreamOwnedLine);
+    const nI = installed.split(/\r?\n/).map(normalizeUpstreamOwnedLine);
+    const u = matchLines(nP, nI);
+    if (u === null) {
+      upstreamUnknown = true;
+    } else {
+      let prevP = -1;
+      let pendingInsert = false;
+      for (let k = 0; k < nI.length; k++) {
+        if (u[k] === -1) {
+          pendingInsert = true;
+        } else {
+          if (pendingInsert || u[k] > prevP + 1) intervals.push([prevP + 1, u[k]]);
+          pendingInsert = false;
+          prevP = u[k];
+        }
+      }
+      if (pendingInsert || P.length > prevP + 1) intervals.push([prevP + 1, P.length]);
+    }
+  }
+  const touches = ([s, e]) => intervals.some(([a, b]) => a <= e && s <= b);
+  const inInstall = (l) => iLines.has(normalizeUpstreamOwnedLine(l).trim());
+
+  return hunks.map((h) => {
+    const required = h.required_lines;
+    const n = required.filter((l) => installed.includes(l)).length;
+    const present = required.length === 0 ? 'n/a' : n === required.length ? 'all' : n === 0 ? 'none' : 'some';
+    const reasons = [];
+    if (!baselineConfirmed) reasons.push(HUNK_REASON.BASELINE_UNCONFIRMED);
+    if (h.diff_too_large || (upstreamUnknown && h.stock_range)) reasons.push(HUNK_REASON.DIFF_TOO_LARGE);
+    const stockSig = h.stock_lines.filter(isSignificantLine);
+    if (
+      (h.kind !== 'deletion' && present === 'all') ||
+      (h.kind === 'deletion' && stockSig.length > 0 && stockSig.every((l) => !inInstall(l)))
+    ) reasons.push(HUNK_REASON.ALREADY_UPSTREAM);
+    if (present === 'some') reasons.push(HUNK_REASON.PARTIALLY_UPSTREAM);
+    const anchors = [h.anchor_before, h.anchor_after].filter(Boolean);
+    if (anchors.length > 0 && anchors.every((a) => !inInstall(a))) reasons.push(HUNK_REASON.ANCHOR_ORPHANED);
+    if (h.stock_range && !upstreamUnknown && touches(h.stock_range)) reasons.push(HUNK_REASON.REGION_CHANGED_UPSTREAM);
+    let recommendation;
+    if (reasons.includes(HUNK_REASON.BASELINE_UNCONFIRMED) || reasons.includes(HUNK_REASON.DIFF_TOO_LARGE)) {
+      recommendation = HUNK_RECOMMENDATION.REVIEW;
+    } else if (reasons.includes(HUNK_REASON.ALREADY_UPSTREAM)) {
+      recommendation = HUNK_RECOMMENDATION.RETIRE;
+    } else if (reasons.length > 0) {
+      recommendation = HUNK_RECOMMENDATION.REVIEW;
+    } else {
+      recommendation = HUNK_RECOMMENDATION.KEEP;
+    }
+    const { stock_range: _sr, diff_too_large: _dtl, ...rest } = h;
+    return { ...rest, present_in_install: present, reasons, recommendation, exception: recommendation !== HUNK_RECOMMENDATION.KEEP };
+  });
+}
+
+/**
+ * #4435: per-file hunk record shared by --hunks and --decisions validation.
+ */
+function buildFileHunks({ relPath, patchesDir, configDir, pristineDir, pristineHashes, skillsRedirect }) {
+  const out = { file: relPath, baseline: 'none', reason: null, hunks: [], installedContent: null, pristineContent: null };
+  const backupPath = path.join(patchesDir, relPath);
+  if (!fs.existsSync(backupPath) || !fs.statSync(backupPath).isFile()) return out;
+  let backupContent;
+  try {
+    backupContent = fs.readFileSync(backupPath, 'utf8');
+  } catch {
+    out.reason = REASON.FAIL_READ_ERROR;
+    return out;
+  }
+  const installedPath = resolveInstalledPath(configDir, relPath, skillsRedirect);
+  try {
+    const st = fs.statSync(installedPath);
+    if (!st.isFile()) out.reason = REASON.FAIL_INSTALLED_NOT_REGULAR_FILE;
+    else out.installedContent = fs.readFileSync(installedPath, 'utf8');
+  } catch (err) {
+    out.reason = err && err.code === 'ENOENT' ? REASON.FAIL_INSTALLED_MISSING : REASON.FAIL_READ_ERROR;
+  }
+  const { resolution, content } = resolvePristineBaseline({ relPath, configDir, pristineDir, pristineHashes });
+  let pristine = null;
+  if (resolution === PRISTINE_RESOLUTION.VALIDATED) {
+    out.baseline = 'validated';
+    pristine = content;
+  } else if (resolution === PRISTINE_RESOLUTION.UNVALIDATED) {
+    out.baseline = 'unvalidated';
+    pristine = content;
+  } else if (resolution === PRISTINE_RESOLUTION.DRIFTED) {
+    out.reason = REASON.OK_PRISTINE_DRIFT_DETECTED;
+  } else if (resolution === PRISTINE_RESOLUTION.ABSENT_RECORDED) {
+    out.reason = REASON.OK_NO_BASELINE;
+  }
+  out.pristineContent = pristine;
+  out.hunks = computeHunks(relPath.replace(/\\/g, '/'), backupContent, pristine);
+  return out;
+}
+
+/**
+ * #4435: strict loader for the human decisions file. Every malformed shape is
+ * a usage error (exit 2) — a decision file is a trust boundary.
+ */
+function loadDecisions(decisionsPath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(decisionsPath, 'utf8');
+  } catch (err) {
+    throw new ExitError(2, `cannot read decisions file: ${decisionsPath}${err && err.code ? ` (${err.code})` : ''}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new ExitError(2, `decisions file is not valid JSON: ${decisionsPath}`);
+  }
+  const isPlain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  if (!isPlain(parsed) || !Array.isArray(parsed.decisions)) {
+    throw new ExitError(2, 'decisions file must be an object with a "decisions" array');
+  }
+  const dispositions = new Set(Object.values(DISPOSITION));
+  const byKey = new Map();
+  parsed.decisions.forEach((d, i) => {
+    if (!isPlain(d)) throw new ExitError(2, `invalid decision at index ${i}: not an object`);
+    if (typeof d.file !== 'string' || d.file === '') throw new ExitError(2, `invalid decision at index ${i}: file must be a non-empty string`);
+    if (typeof d.hunk_hash !== 'string' || !/^[0-9a-f]{64}$/.test(d.hunk_hash)) {
+      throw new ExitError(2, `invalid decision at index ${i}: hunk_hash must be 64 lowercase hex characters`);
+    }
+    if (typeof d.disposition !== 'string' || !dispositions.has(d.disposition)) {
+      throw new ExitError(2, `invalid decision at index ${i}: disposition must be one of ${[...dispositions].join(', ')}`);
+    }
+    // #4435: a rewrite must carry the user's replacement text so the gate can
+    // verify it landed; keep/retire must not carry one.
+    let replacement = null;
+    if (d.disposition === DISPOSITION.REWRITE) {
+      if (!Array.isArray(d.replacement_lines) || d.replacement_lines.length === 0 || !d.replacement_lines.every((x) => typeof x === 'string')) {
+        throw new ExitError(2, `invalid decision at index ${i}: rewrite requires a non-empty replacement_lines array of strings`);
+      }
+      replacement = d.replacement_lines.slice();
+    } else if (Object.prototype.hasOwnProperty.call(d, 'replacement_lines')) {
+      throw new ExitError(2, `invalid decision at index ${i}: replacement_lines is allowed only for rewrite`);
+    }
+    const file = d.file.replace(/\\/g, '/');
+    const key = `${file}\0${d.hunk_hash}`;
+    const prior = byKey.get(key);
+    if (prior) {
+      if (prior.disposition !== d.disposition
+        || JSON.stringify(prior.replacement_lines) !== JSON.stringify(replacement)) {
+        throw new ExitError(2, `conflicting decisions for ${file} ${d.hunk_hash}`);
+      }
+      return;
+    }
+    byKey.set(key, { file, hunk_hash: d.hunk_hash, disposition: d.disposition, replacement_lines: replacement });
+  });
+  return [...byKey.values()];
+}
+
+function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashes, skillsRedirect, retiredHashes, extraRequired }) {
   const backupPath = path.join(patchesDir, relPath);
   const installedPath = resolveInstalledPath(configDir, relPath, skillsRedirect);
   const result = { file: relPath, status: 'ok', missing: [], reason: null };
@@ -535,7 +823,16 @@ function verifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHashe
   // content (null for OVERBROAD) feeds computeUserAddedLines, whose no-pristine
   // branch is the over-broad fallback.
 
-  const userAdded = computeUserAddedLines(backupContent, pristineContent);
+  let userAdded = computeUserAddedLines(backupContent, pristineContent);
+  // #4435: a hunk retired/rewritten by a recorded human decision (bound to its
+  // content hash) stops being required; every other hunk's lines still are.
+  if (retiredHashes && retiredHashes.size > 0) {
+    userAdded = computeHunks(relPath.replace(/\\/g, '/'), backupContent, pristineContent)
+      .filter((h) => !retiredHashes.has(h.hunk_hash))
+      .flatMap((h) => h.required_lines);
+  }
+  // #4435: a rewrite's user-supplied replacement must be present in the merge.
+  if (extraRequired && extraRequired.length > 0) userAdded = userAdded.concat(extraRequired);
   if (userAdded.length === 0) {
     // Backup and pristine match exactly (or no significant content) — nothing
     // to verify but also nothing to lose. Report as ok with diagnostic code.
@@ -654,6 +951,12 @@ function classifyFile({ relPath, patchesDir, configDir, pristineDir, pristineHas
 
 function main() {
   const opts = parseArgs(process.argv.slice(2));
+  if (opts.hunks && opts.classify) {
+    throw new ExitError(2, '--hunks and --classify are mutually exclusive');
+  }
+  if (opts.decisionsPath !== null && (opts.hunks || opts.classify)) {
+    throw new ExitError(2, '--decisions applies only to the post-merge gate');
+  }
   if (!opts.patchesDir || !opts.configDir) {
     throw new ExitError(2, '--patches-dir and --config-dir are required');
   }
@@ -672,6 +975,50 @@ function main() {
   // `home` override outside configDir (codex global → $HOME/.agents/skills).
   const skillsRedirect = resolveSkillsRedirect(opts.configDir);
 
+  // #4435: --hunks is the pre-merge per-hunk presentation mode. It recommends;
+  // it never decides and never gates (always exit 0).
+  if (opts.hunks) {
+    const fileRecords = files.map((relPath) => {
+      const rec = buildFileHunks({
+        relPath,
+        patchesDir: opts.patchesDir,
+        configDir: opts.configDir,
+        pristineDir: opts.pristineDir,
+        pristineHashes,
+        skillsRedirect,
+      });
+      return {
+        file: rec.file,
+        baseline: rec.baseline,
+        reason: rec.reason,
+        hunks: annotateHunks(rec.hunks, {
+          pristineContent: rec.pristineContent,
+          installedContent: rec.installedContent,
+          baselineConfirmed: rec.baseline === 'validated',
+        }),
+      };
+    });
+    const hunksTotal = fileRecords.reduce((n, f) => n + f.hunks.length, 0);
+    const exceptionsTotal = fileRecords.reduce((n, f) => n + f.hunks.filter((h) => h.exception).length, 0);
+    if (opts.json) {
+      process.stdout.write(
+        JSON.stringify({ checked: fileRecords.length, hunks_total: hunksTotal, exceptions_total: exceptionsTotal, files: fileRecords }, null, 2) + '\n',
+      );
+    } else {
+      process.stdout.write(`# Reapply Patch Hunks (#4435)\n\n`);
+      process.stdout.write(`Checked: ${fileRecords.length} file(s)\n`);
+      process.stdout.write(`Hunks: ${hunksTotal} (${exceptionsTotal} exception(s))\n`);
+      for (const f of fileRecords) {
+        for (const h of f.hunks) {
+          if (h.exception) {
+            process.stdout.write(`- ${f.file} hunk ${h.hunk_id} [${h.recommendation}] ${h.reasons.join(', ')}\n`);
+          }
+        }
+      }
+    }
+    return 0;
+  }
+
   // 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;
@@ -720,6 +1067,47 @@ function main() {
     return 0;
   }
 
+  // #4435: validate every decision against the current hunks BEFORE verifying.
+  // A decision whose hash no longer matches a hunk is stale and aborts (exit 2).
+  let decisions = null;
+  const retiredByFile = new Map();
+  const retiredList = [];
+  const rewriteLinesByFile = new Map();
+  if (opts.decisionsPath !== null) {
+    decisions = loadDecisions(opts.decisionsPath);
+    const fileSet = new Set(files.map((f) => f.replace(/\\/g, '/')));
+    const relByKey = new Map(files.map((f) => [f.replace(/\\/g, '/'), f]));
+    const hunkCache = new Map();
+    for (const d of decisions) {
+      if (!fileSet.has(d.file)) {
+        throw new ExitError(2, `decision names a file not in the patches dir: ${d.file}`);
+      }
+      if (!hunkCache.has(d.file)) {
+        hunkCache.set(d.file, buildFileHunks({
+          relPath: relByKey.get(d.file),
+          patchesDir: opts.patchesDir,
+          configDir: opts.configDir,
+          pristineDir: opts.pristineDir,
+          pristineHashes,
+          skillsRedirect,
+        }).hunks);
+      }
+      const hunk = hunkCache.get(d.file).find((h) => h.hunk_hash === d.hunk_hash);
+      if (!hunk) {
+        throw new ExitError(2, `stale decision: hunk ${d.hunk_hash} no longer matches ${d.file} (the backup or baseline changed since it was shown)`);
+      }
+      if (d.disposition === DISPOSITION.RETIRE || d.disposition === DISPOSITION.REWRITE) {
+        if (!retiredByFile.has(d.file)) retiredByFile.set(d.file, new Set());
+        retiredByFile.get(d.file).add(d.hunk_hash);
+        retiredList.push({ file: d.file, hunk_id: hunk.hunk_id, hunk_hash: d.hunk_hash, disposition: d.disposition });
+        if (d.disposition === DISPOSITION.REWRITE) {
+          if (!rewriteLinesByFile.has(d.file)) rewriteLinesByFile.set(d.file, []);
+          rewriteLinesByFile.get(d.file).push(...d.replacement_lines.filter(isSignificantLine));
+        }
+      }
+    }
+  }
+
   const results = files.map((relPath) =>
     verifyFile({
       relPath,
@@ -728,6 +1116,8 @@ function main() {
       pristineDir: opts.pristineDir,
       pristineHashes,
       skillsRedirect,
+      retiredHashes: retiredByFile.get(relPath.replace(/\\/g, '/')),
+      extraRequired: rewriteLinesByFile.get(relPath.replace(/\\/g, '/')),
     }),
   );
 
@@ -770,9 +1160,9 @@ function main() {
   }
 
   if (opts.json) {
-    process.stdout.write(
-      JSON.stringify({ checked: results.length, failures: failures.length, drifted, drifted_files, no_baseline, no_baseline_files, baseline_covered, results }, null, 2) + '\n',
-    );
+    const report = { checked: results.length, failures: failures.length, drifted, drifted_files, no_baseline, no_baseline_files, baseline_covered, results };
+    if (decisions) report.decisions = { applied: decisions.length, retired: retiredList };
+    process.stdout.write(JSON.stringify(report, null, 2) + '\n');
   } else {
     process.stdout.write(`# Hunk Verification Gate (#2969)\n\n`);
     process.stdout.write(`Checked: ${results.length} file(s)\n`);
@@ -780,7 +1170,18 @@ function main() {
     // #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`);
+    process.stdout.write(`${coverageHeadline(baseline_covered, results.length)}\n`);
+    if (decisions) {
+      process.stdout.write(`Decisions: ${decisions.length} applied, ${retiredList.length} hunk(s) retired by user decision\n`);
+    }
+    process.stdout.write('\n');
+    if (decisions && retiredList.length > 0) {
+      process.stdout.write(`## Hunks retired or rewritten by user decision\n\n`);
+      for (const r of retiredList) {
+        process.stdout.write(`- ${r.file} hunk ${r.hunk_id} (${r.disposition})\n`);
+      }
+      process.stdout.write('\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`);
@@ -821,5 +1222,5 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { computeUserAddedLines, isSignificantLine, verifyFile, classifyFile, walk, REASON, CLASSIFICATION, PRISTINE_RESOLUTION, resolvePristineBaseline, readPristineHashes, sha256, resolveInstalledPath, resolveSkillsRedirect, coverageHeadline, classifyBaselineCoverage };
+module.exports = { computeHunks, annotateHunks, buildFileHunks, HUNK_REASON, HUNK_RECOMMENDATION, DISPOSITION, computeUserAddedLines, isSignificantLine, verifyFile, classifyFile, walk, REASON, CLASSIFICATION, PRISTINE_RESOLUTION, resolvePristineBaseline, readPristineHashes, sha256, resolveInstalledPath, resolveSkillsRedirect, coverageHeadline, classifyBaselineCoverage };
 

package/gsd-core/references/cicd-review-patterns.md

@@ -0,0 +1,45 @@
+# CI/CD Pipeline Review Patterns
+
+Rubric for the **CI/CD pipelines** entry of `gsd-code-reviewer`'s language-aware checks. Read at `standard` and `deep` depth only, when a file in scope is a pipeline file. These defects rarely fail a test. They show up at release or deploy time, as a broken release or a bad production deploy.
+
+Pipeline files are recognized by path, not extension: `.github/workflows/*.yml` / `*.yaml`, `Dockerfile*` / `Containerfile`, `docker-compose*.yml` / `compose*.yaml`, and deploy scripts (`deploy*.sh` and equivalents). A deploy script is also a Shell file: apply both sets of checks.
+
+Adapted from the `ci-cd-reliability-architecture` skill in [l-gevity/l-gevity-skills](https://github.com/l-gevity/l-gevity-skills) (MIT), reduced to what is checkable from file contents at review time (#4101).
+
+## Checks
+
+| Check | Signal | Why it matters | Severity |
+|---|---|---|---|
+| **Non-idempotent step** | `npm install` where a `package-lock.json` exists (should be `npm ci`); `pip install` with no lock or pinned requirements; `mkdir` without `-p`; an unguarded `rm`; delete-then-create of a live resource | A re-run produces a different result, or fails part-way and leaves the target broken | Warning |
+| **Missing timeout** | A job with `runs-on:` and no job-level `timeout-minutes:` | A stuck job holds its runner until the 6-hour default | Warning |
+| **Missing concurrency guard** | A deploy workflow with no `concurrency` group and `cancel-in-progress: true` | Two pushes run in parallel; the older run can finish last and deploy over the newer one | Warning |
+| **Per-environment rebuild** | The same commit is built separately for each environment instead of build-once/promote | The artifact that reaches production is not the artifact that passed CI | Warning |
+| **Deploy without health check or rollback** | A deploy step with no post-deploy health check and no rollback path | A bad deploy stays live until a human notices | Warning |
+| **Load-bearing `continue-on-error`** | `continue-on-error: true` on a step whose success later steps assume | The failure is masked; later steps run on a broken state and the job reports green | Warning |
+| **Static cloud credentials** | Long-lived cloud keys stored as secrets for a provider that supports OIDC (`permissions: id-token: write`) | A leaked key stays valid until someone rotates it; OIDC tokens expire per run | Warning |
+| **Unpinned third-party action** | `uses: owner/action@main`, `@master` or `@latest` | An unpinned ref lets the action's code change between two runs of the same commit | Warning |
+
+A hardcoded secret in a pipeline file stays Critical under the existing secrets rule. Style-level pipeline findings (step naming, step ordering, redundant checkout options) are Info.
+
+## Evidence rule
+
+Cite the line. For the concurrency, rebuild and rollback checks, also name what makes the workflow a deploy workflow (the trigger, the environment, the deploy command): those checks are about deploys, not every workflow.
+
+## Negative space: NOT findings
+
+- **Global tool installs.** `npm install -g <tool>` installs a tool, not the project's dependency tree. A repository with no `package-lock.json` has nothing for `npm ci` to read.
+- **Reusable workflow calls.** A job that calls a reusable workflow (`uses:` at the job level) cannot set `timeout-minutes`; the called workflow owns its timeouts.
+- **Pinned refs.** A version tag (`@v4`) or a full commit SHA is a pin. Local actions (`./path`) and `docker://` references are not third-party action refs.
+- **CI-only workflows.** `cancel-in-progress` is required on deploy workflows. On a workflow that only runs tests it is an optimization, not a Warning.
+- **Informational steps.** `continue-on-error` on a step nothing depends on (a coverage upload, a notification) masks nothing.
+- **Providers without OIDC.** A secret for a provider that does not support OIDC is not a static-credential finding.
+
+## Example
+
+```markdown
+### WR-02: Deploy workflow lacks concurrency guard — stale commit can deploy last
+
+**File:** `.github/workflows/deploy.yml:8`
+**Issue:** Two pushes in quick succession run in parallel; the older run can finish after the newer one and overwrite production.
+**Fix:** Add a `concurrency` group keyed on the ref, with `cancel-in-progress: true`.
+```

package/gsd-core/references/git-integration.md

@@ -295,4 +295,15 @@ This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, a
 
 Files that don't match any configured sub-repo are reported as unmatched.
 
+### Milestone Tagging Across Sub-Repos
+
+A GSD milestone version names planned work in `.planning/`; it is not any repository's release version. With `git.repo_tagging: "per_repo"` and a non-empty `sub_repos`, `/gsd:complete-milestone` records one release map entry per repository (status, release, reference, environment, tag choice) instead of creating one `v[X.Y]` tag in the current directory:
+
+1. `gsd_run query milestone release-tags --map <tags.json> --dry-run` checks every requested tag (repository listed in `sub_repos`, ref resolves, tag name valid, no tag at a different commit) before anything is written.
+2. After one consolidated confirmation, `gsd_run query milestone release-tags --map <tags.json>` creates the annotated tags, each with the target repository as its working directory. Re-running the same map is idempotent (`already_tagged`).
+3. `milestone complete <version> --release-map <file>` archives the map by recorded value.
+4. Nothing is pushed by default. Each repository's tag has its own confirmation naming the repository and its remote.
+
+With `git.create_tag: false` the map is still recorded and no tag is created. See [How to tag a multi-repository milestone](../../docs/how-to/tag-a-multi-repo-milestone.md).
+
 </sub_repos_support>

package/gsd-core/references/loop-hook-dispatch.md

@@ -91,12 +91,19 @@ not one shape of one.
 capability manifest, which may be third-party — and `gates[].check` is **not** one of the
 executable surfaces the install consent prompt discloses (`hooks`, command modules,
 `mcpServers`, reviewer lanes), so a capability can be consented to as declarative-only and
-still reach a shell through a gate. Check the query value you read from `activeHooks` against
-`^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself, IN-CONTEXT — **never** by pasting it into a
-shell command to be tested there, because a value carrying a quote, `;`, a `` ` ``, `$(`, or a
-newline would terminate the assignment and run as its own statement before any shell-side
-check could execute. A value that fails is a malformed manifest: record a warning, route it
-per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
+still reach a shell through a gate. Normalize first, then validate: the registry declares query
+ids in dotted form (`ui.plan-gate`, `verify.codebase-drift`) and `gsd_run check` accepts them by
+turning each `.` into `-`, so replace every `.` with `-` in the query value you read from
+`activeHooks`, then check that normalized value against
+`^[a-z][a-z0-9]*(-[a-z0-9]+)*( [a-z][a-z0-9]*(-[a-z0-9]+)*)*$` yourself, IN-CONTEXT — **never** by
+pasting it into a shell command to be tested there, because a value carrying a quote, `;`, a
+`` ` ``, `$(`, or a newline would terminate the assignment and run as its own statement before
+any shell-side check could execute. The normalized value is the one value you validate and the
+one value you pass: wherever a workflow shows `${hook.check.query}`, write the normalized value.
+A leading dot, a trailing dot or consecutive dots become a leading, trailing or doubled hyphen,
+which the pattern rejects. A value that fails — or that passes but names no known check, which
+`gsd_run check` rejects as an unknown check subcommand — is a malformed manifest: record a
+warning, route it per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
 element** for the same reason — never re-quote it into a shell string, where an apostrophe
 would close the literal. This is the identical requirement `step` → `ref.command` carries
 above; it was stated there and omitted here, which is the gap #3559 closed.

package/gsd-core/references/necessity-review.md

@@ -0,0 +1,48 @@
+# Necessity Review
+
+Rubric for category 4 (Necessity) of `gsd-code-reviewer`. Read at `standard` and `deep` depth only, before classifying findings. It asks a question the other three categories do not: **does the problem this code addresses actually occur in this stack?** Correct, clean, well-tested code can still guard against nothing.
+
+Taxonomy adapted from the `functionality-complexity-tradeoff` skill in [l-gevity/l-gevity-skills](https://github.com/l-gevity/l-gevity-skills) (MIT), #4100.
+
+## Taxonomy
+
+| Subtype | Signal | Example |
+|---|---|---|
+| **Impossible-state guard** | Defends against a state ruled out by the type system, the deployment topology, or a runtime invariant | Null-check on a value whose type is non-nullable end to end; client/server version-skew check in a single-artifact deploy |
+| **Already-defended-elsewhere** | A concern fully owned by another layer, duplicated here | Manual HTML escaping on top of an auto-escaping template engine; manual rollback inside an outer transaction that already rolls back |
+| **Cargo-culted pattern** | A pattern whose prerequisites do not hold in this context | Connection pool in a CLI that runs for 200 ms; singleton cache in a stateless lambda |
+| **Phantom requirement** | Solves a requirement that was never real or has provably lapsed | Feature flag for a launch that completed and is on for every environment; a migration shim for data the repo proves was migrated everywhere |
+| **Generality without instantiation** | An abstraction with exactly one instantiation for its whole lifetime | Strategy pattern with one strategy; plugin registry with one plugin; config key holding the same value in every environment |
+
+## Evidence rule
+
+Verify the premise before reviewing the implementation. A necessity finding must state **why the guarded state cannot occur** (or why the requirement lapsed) and cite where that is proven: the type signature, the build/deploy configuration, the call sites, the flag's values. The pattern name alone is not a finding — drop it.
+
+## Severity
+
+- **Warning** (`WR-`) — the impossibility or lapse is provable from the repository.
+- **Info** (`IN-`) — it rests on judgment (likely, but not shown).
+- **Never Critical.** Removal is a scope decision for a human, not a defect fix.
+
+## Negative space — NOT necessity findings
+
+- **Trust boundary.** A guard on data crossing a trust boundary (user input, network, files, environment, deserialized data, another process) is never an impossible-state guard, even when internal types claim the value is safe — types do not hold across a trust boundary.
+- **Defense in depth.** A deliberate second security layer is not "already-defended-elsewhere".
+- **Test seams.** A single-implementation interface that exists as a dependency-injection or test seam is not "generality without instantiation".
+- **Unreachable code** is category 3 (Code Quality, dead code). Necessity is code that runs, but defends against nothing.
+- **Unproven lapse.** A flag or migration whose lapse cannot be shown from the repository is Info at most.
+
+## REVIEW.md format
+
+A necessity finding keeps its normal ID and section (`WR-` under `## Warnings`, `IN-` under `## Info`), names its subtype in the title, and carries the category marker line. The marker is what keeps `gsd-code-fixer` from removing the code under the default fix scope:
+
+```markdown
+### WR-04: Impossible-state guard — client version check in single-artifact SPA
+
+**File:** `src/api/client.ts:42`
+**Category:** necessity
+**Issue:** The guarded state (client/server version skew) cannot occur: both are built and deployed as one artifact (`vite.config.ts:12`, `deploy/Dockerfile:8`).
+**Fix:** Remove the check; record the invariant in a comment or ADR rather than a runtime branch.
+```
+
+Count every necessity finding in the frontmatter `necessity:` key. It is a subset of `warning` + `info`, never added to `total`.