@opengsd/gsd-core 1.19.0 → 1.20.0

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -30,7 +30,7 @@ const state_document_cjs_1 = require("./state-document.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
 const frontmatterMod = require("./frontmatter.cjs");
 const { extractFrontmatter, stripFrontmatter } = frontmatterMod;
-const markdown_table_cjs_1 = require("./markdown-table.cjs");
+const roadmap_progress_cjs_1 = require("./roadmap-progress.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete, isVerificationStatus, VERIFICATION_STATUS } = verificationMod;
@@ -41,6 +41,9 @@ const { phaseKeyFromDir, phaseKeyFromProse, parentPhaseKey } = phaseIdMod;
 const roadmapParserMod = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter, isMilestoneShippedInRoadmap } = roadmapParserMod;
 const workstream_inventory_builder_cjs_1 = require("./workstream-inventory-builder.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLocatorMod = require("./phase-locator.cjs");
+const { phaseDirectoryOptions } = phaseLocatorMod;
 // ─── Implementation ───────────────────────────────────────────────────────────
 function workstreamsRoot(cwd) {
     return node_path_1.default.join(planningRoot(cwd), 'workstreams');
@@ -75,7 +78,7 @@ function countRoadmapPhases(roadmapPath, fallbackCount, cwd, ws, versionOverride
         // `null` -> 0 (fallback), `undefined` -> 3. A non-bracket workstream
         // resolves to a value that compiles the same base grammar `null` did, so
         // its count is unchanged (verified against a legacy control).
-        const filter = getMilestonePhaseFilter(cwd, versionOverride ?? null, undefined, ws ?? null);
+        const filter = getMilestonePhaseFilter(cwd, versionOverride ?? null, undefined, ws ?? null, phaseDirectoryOptions(cwd, undefined, undefined, ws ?? null));
         // A pass-all degrade (phaseCount 0) means the window declared no phases —
         // fall back rather than reporting a confident zero.
         return filter.phaseCount > 0 ? filter.phaseCount : fallbackCount;
@@ -98,25 +101,22 @@ function countRoadmapPhases(roadmapPath, fallbackCount, cwd, ws, versionOverride
  * `phaseKeyFromDir` uses for directories, so a `| 01. … |` row and a `1-slug`
  * directory cannot land in different key spaces (the padding-asymmetry defect).
  */
-function parseRoadmapProgressRows(roadmapPath) {
-    let content;
-    try {
-        content = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-    }
-    catch {
-        return []; /* no roadmap */
-    }
+function parseRoadmapProgressRows(content, directoryContext) {
     // Milestone-ATTRIBUTING shape first. Both shapes carry `Plans Complete`, so
     // probing that column first would pick a flat table appearing earlier in the
     // document over a milestone-grouped one later — every row would come back
     // unattributed and be treated as current-milestone, silently over-including.
-    const table = (0, markdown_table_cjs_1.findTableWithColumns)(content, ['Phase', 'Milestone'])
-        ?? (0, markdown_table_cjs_1.findTableWithColumns)(content, ['Phase', 'Plans Complete']);
-    if (!table)
-        return [];
+    // #5761: the roadmap-progress owner picks the table (heading-scoped, so a
+    // decoy table elsewhere cannot be mistaken for it); this reader only supplies
+    // the probe order. A table outside a table-less `## Progress` section has
+    // always been read here (#5692: no behavior change), hence `sectionMiss`.
+    const { rows: tableRows } = (0, roadmap_progress_cjs_1.locateRoadmapProgress)(content, {
+        columns: [['Phase', 'Milestone'], ['Phase', 'Plans Complete']],
+        sectionMiss: 'document',
+    });
     const rows = [];
-    for (const row of table.rows) {
-        const key = phaseKeyFromProse(row['Phase']);
+    for (const row of tableRows) {
+        const key = phaseKeyFromProse(row['Phase'], directoryContext);
         if (key === null)
             continue;
         const cell = (row['Milestone'] ?? '').trim();
@@ -428,12 +428,18 @@ function inspectWorkstream(cwd, name, options = {}) {
     const writeDiagnostic = options.writeDiagnostic ?? ((message) => process.stderr.write(message));
     const p = planningPaths(cwd, name);
     const phaseDirNames = readSubdirectories(p.phases);
+    let roadmap = '';
+    try {
+        roadmap = node_fs_1.default.readFileSync(p.roadmap, 'utf8');
+    }
+    catch { /* no roadmap */ }
+    const directoryContext = phaseDirectoryOptions(cwd, undefined, roadmap, name);
     // #2562: scope progress to the CURRENT milestone. Membership and the
     // denominator are derived in ONE key space (`phaseKeyFromDir` /
     // `phaseKeyFromProse`, both from the phase-id owner module) so the two sides
     // of the rollup cannot disagree.
     const currentVersion = readCurrentMilestoneVersion(p.state, p.roadmap);
-    const progressRows = parseRoadmapProgressRows(p.roadmap);
+    const progressRows = parseRoadmapProgressRows(roadmap, directoryContext);
     // Phase keys the ROADMAP attributes to the current milestone. A row whose
     // Milestone cell is blank or malformed is INCLUDED rather than dropped: a
     // phase we cannot attribute must still be visible to the rollup. Dropping it
@@ -458,7 +464,7 @@ function inspectWorkstream(cwd, name, options = {}) {
     // it is exactly the caller that cannot set `GSD_WORKSTREAM`; spelling `null`
     // pinned every workstream to the legacy grammar and made `headingScoped`
     // unreachable (`phaseCount > 0` never held) on a bracket workstream.
-    const headingFilter = getMilestonePhaseFilter(cwd, currentVersion, undefined, name);
+    const headingFilter = getMilestonePhaseFilter(cwd, currentVersion, undefined, name, directoryContext);
     const headingScoped = headingFilter.versionScoped && headingFilter.phaseCount > 0;
     // Phase keys the ROADMAP attributes to some OTHER milestone. A row carrying an
     // explicit version that is not the current one is a positive claim by a prior
@@ -507,7 +513,7 @@ function inspectWorkstream(cwd, name, options = {}) {
     const isDirInCurrentMilestone = (dir) => {
         if (!scoped)
             return true;
-        const key = phaseKeyFromDir(dir);
+        const key = phaseKeyFromDir(dir, undefined, directoryContext);
         if (currentMilestoneKeys.has(key))
             return true;
         const parent = parentPhaseKey(key);
@@ -563,7 +569,7 @@ function inspectWorkstream(cwd, name, options = {}) {
         }
         return {
             directory: dir,
-            phaseKey: phaseKeyFromDir(dir),
+            phaseKey: phaseKeyFromDir(dir, undefined, directoryContext),
             mtimeMs: phaseDirMtime(phaseDir),
             planCount: counts.planCount,
             summaryCount: counts.summaryCount,

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`.
+```