@event4u/agent-config 14.14.0 → 14.15.0

package/src/scripts/hooks/merge_impact.ts

@@ -0,0 +1,207 @@
+/**
+ * Stage-2 impact analysis for a merge the guard is about to refuse.
+ *
+ * STAGE 1 asks "is this operation in the blocked set?" — a question about the
+ * command's shape, answered by `commandOp`. STAGE 2 asks "what would it
+ * actually do?" — a question about the diff, answered here.
+ *
+ * WHAT THIS DOES NOT DO, stated first because the opposite is the tempting
+ * reading: it never downgrades a refusal into an allow. Both council seats
+ * (2026-09-03, anthropic + codex-default, deep) rejected exactly that, and the
+ * argument is not about diff parsing being imperfect — it is that a purely
+ * additive diff can still fire a production deploy, close issues, hit outbound
+ * webhooks, and land against a base that moved since the review. Diff content
+ * is one axis; the destination is the other, and nothing readable from a patch
+ * tells you what merging into that branch triggers.
+ *
+ * So the verdict enriches the REFUSAL. A block that says "this PR adds two
+ * files and touches no migration, no exported symbol and no version — say
+ * `merge #1499` to authorize" is a question the user can answer in four words,
+ * including out loud. A block that says "refused" makes them go read the diff
+ * themselves. Same gate, and the difference is entirely in whether the human
+ * can act on it.
+ *
+ * THREE-VALUED ON PURPOSE. `undecidable` is a real answer and the most common
+ * one offline: no ref, no network, an unparsable patch. Collapsing it into
+ * `additive` would be the failure this module exists to avoid, so every unknown
+ * resolves toward "ask".
+ */
+import { execFileSync } from "node:child_process";
+
+export type ImpactVerdict = "additive" | "destructive" | "undecidable";
+
+export interface MergeImpact {
+  verdict: ImpactVerdict;
+  /** Human-readable markers behind a `destructive` verdict, in diff order. */
+  markers: string[];
+  /** Why the analysis could not run, when the verdict is `undecidable`. */
+  reason?: string;
+  /** Files the diff touches, for the one-line summary in a refusal. */
+  filesChanged?: number;
+}
+
+/**
+ * Destructive markers, each decidable from the patch text alone.
+ *
+ * DELIBERATELY A PROXY SET, NOT A BREAKING-CHANGE ORACLE. "Does this break a
+ * consumer" is undecidable in general; these are the shapes that are cheap to
+ * see and expensive to miss. A marker firing means "a human should look", never
+ * "this is certainly breaking" — and the absence of every marker means "nothing
+ * cheap to see fired", never "this is certainly safe". That asymmetry is why an
+ * `additive` verdict still refuses.
+ */
+const DESTRUCTIVE_MARKERS: ReadonlyArray<{ label: string; re: RegExp }> = [
+  // Schema removal. Matched on ADDED lines only — a migration that *removes* a
+  // dropColumn call is the opposite of destructive, and matching the raw patch
+  // would score it the same way.
+  { label: "migration drops a column or table", re: /^\+.*\b(dropColumn|dropTable|dropIfExists|removeColumn|drop_column|drop_table)\b/im },
+  { label: "raw DROP or TRUNCATE in a migration", re: /^\+.*\b(DROP\s+(TABLE|COLUMN|INDEX|CONSTRAINT)|TRUNCATE\s+TABLE)\b/im },
+  // The author said so themselves. Conventional Commits marks a breaking change
+  // with a `!` before the colon or a body trailer.
+  { label: "author marked a BREAKING CHANGE", re: /^\+.*BREAKING[ -]CHANGE/m },
+  // A removed export is the shape most likely to break an importer.
+  { label: "an exported symbol was removed", re: /^-\s*export\s+(default\s+|const\s+|function\s+|class\s+|interface\s+|type\s+|async\s+)/m },
+  { label: "a public PHP or Python symbol was removed", re: /^-\s*(public\s+function|def\s+[a-z_]+\s*\()/m },
+  // Route removal breaks callers that never imported anything.
+  { label: "a route or endpoint was removed", re: /^-.*\b(Route::(get|post|put|patch|delete)|@(Get|Post|Put|Patch|Delete)Mapping|app\.(get|post|put|patch|delete)\s*\()/m },
+  { label: "a whole file was deleted", re: /^deleted file mode /m },
+];
+
+/** A major-version bump in a manifest, which is the author declaring a break. */
+const MAJOR_BUMP =
+  /^-\s*"version"\s*:\s*"(\d+)\.[^"]*"[\s\S]{0,200}?^\+\s*"version"\s*:\s*"(\d+)\./m;
+
+/**
+ * Classify a unified diff.
+ *
+ * Pure — the caller supplies the patch, so this is testable without a network,
+ * a repository, or a fixture PR.
+ */
+export function classifyDiff(patch: string): MergeImpact {
+  if (patch.trim() === "") {
+    return { verdict: "undecidable", markers: [], reason: "empty diff" };
+  }
+
+  const markers: string[] = [];
+  for (const { label, re } of DESTRUCTIVE_MARKERS) {
+    if (re.test(patch)) {
+      markers.push(label);
+    }
+  }
+
+  const bump = MAJOR_BUMP.exec(patch);
+  if (bump && bump[1] !== bump[2]) {
+    markers.push(`major version bump ${bump[1]}.x to ${bump[2]}.x`);
+  }
+
+  const filesChanged = (patch.match(/^diff --git /gm) ?? []).length;
+
+  if (markers.length > 0) {
+    return { verdict: "destructive", markers, filesChanged };
+  }
+  return { verdict: "additive", markers: [], filesChanged };
+}
+
+/** How the patch was obtained, so a refusal can say which source answered. */
+export type PatchSource = "local" | "gh" | "none";
+
+export interface PatchResult {
+  patch: string;
+  source: PatchSource;
+  reason?: string;
+}
+
+/**
+ * Fetch the diff for a pull request, local first.
+ *
+ * The ordering is not a preference, it is a cost decision. A local
+ * `git diff` against the merge base costs milliseconds and works offline; a
+ * `gh pr diff` costs a network round trip on a `pre_tool_use` hook, which is in
+ * the user's critical path. Local answers whenever the ref happens to be
+ * fetched, which in a drain run is almost always, because the run just synced
+ * the branch it is about to merge.
+ *
+ * Every failure returns `none` rather than throwing. The caller turns that into
+ * `undecidable`, which asks the user — a hook that crashed would be worse than
+ * a hook that admitted it did not know.
+ */
+export function fetchPatch(
+  pr: number,
+  opts: { cwd?: string; allowNetwork?: boolean; exec?: typeof execFileSync } = {},
+): PatchResult {
+  const run = opts.exec ?? execFileSync;
+  const cwd = opts.cwd ?? process.cwd();
+  const capture = (file: string, args: string[]): string =>
+    run(file, args, { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 15_000 }) as unknown as string;
+
+  // A fetched PR ref is what a synced drain run leaves behind.
+  for (const ref of [`refs/pull/${pr}/head`, `pull/${pr}/head`]) {
+    try {
+      const base = capture("git", ["merge-base", "HEAD", ref]).trim();
+      if (base) {
+        const patch = capture("git", ["diff", `${base}...${ref}`]);
+        if (patch.trim() !== "") {
+          return { patch, source: "local" };
+        }
+      }
+    } catch {
+      /* try the next spelling, then the network */
+    }
+  }
+
+  if (opts.allowNetwork === false) {
+    return { patch: "", source: "none", reason: "no local ref and network reads disabled" };
+  }
+
+  try {
+    const patch = capture("gh", ["pr", "diff", String(pr), "--patch"]);
+    if (patch.trim() !== "") {
+      return { patch, source: "gh" };
+    }
+    return { patch: "", source: "none", reason: "gh returned an empty diff" };
+  } catch {
+    return { patch: "", source: "none", reason: "no local ref, and gh pr diff failed" };
+  }
+}
+
+/** Analyse a pull request end to end. `undecidable` whenever the patch is not readable. */
+export function analyseMergeImpact(
+  pr: number,
+  opts: Parameters<typeof fetchPatch>[1] = {},
+): MergeImpact {
+  const got = fetchPatch(pr, opts);
+  if (got.source === "none") {
+    return { verdict: "undecidable", markers: [], ...(got.reason ? { reason: got.reason } : {}) };
+  }
+  return classifyDiff(got.patch);
+}
+
+/**
+ * One line for a refusal message.
+ *
+ * Phrased so the user can answer it out loud, which is the point of the whole
+ * stage: the shortest reply that unblocks the operation is quoted back to them.
+ */
+export function describeImpact(pr: number, impact: MergeImpact): string {
+  const say = `Say "merge #${pr}" to authorize it.`;
+  switch (impact.verdict) {
+    case "additive":
+      return (
+        `Impact scan: PR #${pr} touches ${impact.filesChanged ?? 0} file(s) and trips no ` +
+        `destructive marker — no schema drop, no removed export or route, no major bump, ` +
+        `no BREAKING CHANGE. Additive as far as the diff can show, which is not the same ` +
+        `as safe to merge: the base has moved since review and merging may trigger a ` +
+        `deploy. ${say}`
+      );
+    case "destructive":
+      return (
+        `Impact scan: PR #${pr} is NOT additive — ${impact.markers.join("; ")}. ` +
+        `Read the diff before authorizing. ${say}`
+      );
+    default:
+      return (
+        `Impact scan: could not read the diff for PR #${pr} (${impact.reason ?? "unknown"}), ` +
+        `so nothing is known about what it changes. ${say}`
+      );
+  }
+}

package/src/scripts/hooks/run_continuation_hook.ts

@@ -64,6 +64,13 @@
  *                                inert mechanism that says nothing is
  *                                indistinguishable from a healthy idle run,
  *                                which is the failure this file exists over)
+ *   plan premise moved         → allow  (event: halt-premise-invalidated, ONCE per
+ *                                run. Engaged-under fingerprint and newest
+ *                                observation both known and differing. Before the
+ *                                counter rungs: iterating against a stale plan
+ *                                does not make it current, and capping out would
+ *                                report `exhausted`, a budget word, for staleness.
+ *                                Never fires on traffic the run did not observe)
  *   quality-gate refusal       → defer            (event: deferred-quality-gate)
  *   duplicate stop fire        → repeat the BLOCK, no count (event: none —
  *                                an allow here would END the reply the block
@@ -173,8 +180,35 @@ import {
     readUnavailableDependency,
     stallSignal,
     type StallLevel,
-    type UnavailableDependency,
 } from '../_lib/loop_guards.js';
+import { premiseMoved, readContextObservation } from '../_lib/context_observation.js';
+import { RUN_TERMINAL_VOCABULARY_VERSION } from '../_lib/outcome_vocabularies.js';
+import {
+    HALT_ACTIONS,
+    ladder,
+    MAX_ITERATIONS,
+    parseHaltStamp,
+    STALL_WINDOW,
+    terminalStateFor,
+    WALL_CLOCK_CAP_MS,
+    type LadderAction,
+} from '../_lib/continuation_ladder.js';
+
+/**
+ * DECLARED in `_lib/continuation_ladder.ts`, re-exported here: one declaration,
+ * two import paths, no second copy to drift. That module's header says why the
+ * move happened (`road-to-wired-instruments` Phase 2).
+ */
+export {
+    HALT_ACTIONS,
+    ladder,
+    MAX_ITERATIONS,
+    parseHaltStamp,
+    STALL_WINDOW,
+    terminalStateFor,
+    WALL_CLOCK_CAP_MS,
+    type LadderAction,
+};
 
 /** Re-exported so a test can assert the IDENTITY, not two matching literals. */
 export { TRANSCRIPT_READ_MAX_BYTES };
@@ -198,11 +232,6 @@ export const EVENTS_RELPATH = path.join(
 );
 const STATE_DIR_REL = path.join('agents', 'runtime', 'state');
 
-/** Ladder defaults. Phase 1.1 pre-registers all three for revisit, not tuning. */
-export const MAX_ITERATIONS = 25;
-export const WALL_CLOCK_CAP_MS = 4 * 60 * 60 * 1000;
-export const STALL_WINDOW = 3;
-
 /**
  * How many consecutive absent-roadmap fires confirm the absence.
  *
@@ -285,6 +314,14 @@ export interface RunState {
      * cannot finish") named these rungs as its mitigation.
      */
     halted?: LadderAction;
+    /**
+     * The fingerprint this run ENGAGED under — its plan premise, recorded once on
+     * the first engagement from `_lib/context_observation` and then left alone.
+     * Refreshing it every fire would make both sides of the premise comparison
+     * equal by construction and the rung unreachable. Absent means the run never
+     * observed one, which is never a disagreement (`premiseMoved`).
+     */
+    context_fingerprint?: string;
 }
 
 /**
@@ -347,34 +384,6 @@ export interface ScanResult {
     next: NextStep | null;
 }
 
-export type LadderAction =
-    | 'engage'
-    | 'complete'
-    | 'blocked'
-    | 'halt-max-iterations'
-    | 'halt-wall-clock'
-    | 'halt-stall'
-    | 'halt-dependency-unavailable';
-
-/** The terminal rungs — the set `RunState.halted` may hold. */
-/**
- * `halt-roadmap-absent` is deliberately NOT in this union and not in
- * `LadderAction`. It is an event name the caller emits directly when the claimed
- * roadmap is unreadable from the authoritative tree, and it CLEARS the state
- * rather than stamping `halted` — widening the union would let `parseRecord`
- * accept it as a `halted` value, which would mean a run whose budget was cleared
- * also carried a halt stamp. The two are mutually exclusive by construction.
- */
-export const HALT_ACTIONS: readonly LadderAction[] = [
-    'halt-max-iterations',
-    'halt-wall-clock',
-    'halt-stall',
-    // Phase 5.4. Checked BEFORE the counter rungs: a dependency the run cannot
-    // obtain is not something more iterations close, so consuming the budget
-    // against it is the waste the rung exists to stop.
-    'halt-dependency-unavailable',
-];
-
 /**
  * Frontmatter `execution.mode`, or null. Line-oriented on purpose: the
  * frontmatter this repo writes is two levels deep at most, and a YAML parser
@@ -480,50 +489,6 @@ export function extractVerify(stepText: string): string | null {
     return null;
 }
 
-/**
- * The termination ladder, pure. `state` is the record BEFORE this stop;
- * `openCount` is the scan of the claimed roadmap as it stands now.
- */
-export function ladder(
-    state: RunState,
-    openCount: number,
-    nowMs: number,
-    // No default: `= 0` would silently restore the complete-instead-of-blocked
-    // behaviour for any caller that omitted it.
-    blockedCount: number,
-    caps: { maxIterations: number; wallClockMs: number; stallWindow: number } = {
-        maxIterations: MAX_ITERATIONS,
-        wallClockMs: WALL_CLOCK_CAP_MS,
-        stallWindow: STALL_WINDOW,
-    },
-    // Phase 5.4. `null` when nothing unobtainable was detected. Optional so every
-    // existing caller and test keeps its meaning unchanged.
-    unavailable: UnavailableDependency | null = null,
-): LadderAction {
-    // A halt is terminal for this run id. Checked BEFORE `complete` so a
-    // halted run whose roadmap later reads zero-open does not report a
-    // completion it never reached.
-    if (state.halted) return state.halted;
-    // `scanOpenSteps` EXCLUDES `blocked-by:` steps from `openCount`, so zero-open
-    // with blocked steps left is exhaustion of runnable work, not completion —
-    // ADR-235's own terminal outcome, and never a sixth halt.
-    if (openCount === 0) return blockedCount > 0 ? 'blocked' : 'complete';
-    // BEFORE the counter rungs, deliberately: a missing credential, an absent
-    // binary or an exhausted quota is not closed by iterating, so spending the
-    // budget on it converts a nameable blocker into an anonymous cap-out.
-    if (unavailable !== null) return 'halt-dependency-unavailable';
-    if (state.iterations >= caps.maxIterations) return 'halt-max-iterations';
-    const started = Date.parse(state.started_at);
-    if (Number.isFinite(started) && nowMs - started >= caps.wallClockMs) {
-        return 'halt-wall-clock';
-    }
-    const tail = state.history.slice(-caps.stallWindow);
-    if (tail.length >= caps.stallWindow && tail.every((n) => n === openCount)) {
-        return 'halt-stall';
-    }
-    return 'engage';
-}
-
 /**
  * Where a run's state lives: keyed on the session AND the roadmap.
  *
@@ -686,16 +651,17 @@ function readState(file: string): RunState | null {
         if (o['inert_reported'] === true) {
             rec.inert_reported = true;
         }
-        // Validated against the halt set rather than accepted as any string:
-        // an unrecognised value would be returned verbatim by `ladder` and
-        // become an action no branch below handles.
-        const halted = o['halted'];
-        if (
-            typeof halted === 'string' &&
-            (HALT_ACTIONS as readonly string[]).includes(halted)
-        ) {
-            rec.halted = halted as LadderAction;
+        // Round-tripped for the same reason `history_source` is: dropped, the
+        // premise would be re-recorded every fire from the newest observation, so
+        // the two sides could never differ and the rung would be dead code.
+        if (typeof o['context_fingerprint'] === 'string' && o['context_fingerprint'] !== '') {
+            rec.context_fingerprint = o['context_fingerprint'];
         }
+        // Tolerant, not permissive — see `parseHaltStamp` for what it accepts
+        // beyond the halt set and why dropping a newer build's stamp was the
+        // wrong failure direction for a budget.
+        const halted = parseHaltStamp(o['halted']);
+        if (halted !== null) rec.halted = halted;
         return rec;
     } catch {
         return null;
@@ -1412,7 +1378,21 @@ export function main(): number {
     // differently. One producer, one definition.
     state.stall = stallSignal(state.history, STALL_WINDOW).level;
 
-    const action = ladder(state, scan.open, Date.now(), scan.blocked, undefined, unavailable);
+    // 2.1 — repository drift, from the newest observation `roadmap:context`
+    // recorded. No probe here: the fingerprint costs a `gh` call and this is the
+    // Stop path. An unknown on either side is never a halt.
+    const observed = readContextObservation(workspaceRoot)?.fingerprint ?? null;
+    const premiseInvalidated = premiseMoved(state.context_fingerprint, observed);
+
+    const action = ladder(
+        state,
+        scan.open,
+        Date.now(),
+        scan.blocked,
+        undefined,
+        unavailable,
+        premiseInvalidated,
+    );
 
     if (action !== 'engage') {
         // A run that is ALREADY stamped emits nothing further — round 6 finding 6.
@@ -1436,6 +1416,12 @@ export function main(): number {
                 iterations: state.iterations,
                 open: scan.open,
                 blocked: scan.blocked,
+                // A ledger line is a persisted shape carrying a `RunTerminalState`,
+                // so it names the vocabulary version it was written against: a
+                // reader meeting an unknown value can then tell a newer writer
+                // from a corrupt row.
+                terminal_state: terminalStateFor(action),
+                terminal_vocabulary_version: RUN_TERMINAL_VOCABULARY_VERSION,
                 at: new Date().toISOString(),
                 ...roots,
             });
@@ -1472,6 +1458,10 @@ export function main(): number {
 
     state.iterations += 1;
     state.last_turn = turnOrdinal;
+    // Recorded ONCE — the premise this run engaged under. See the field's docblock.
+    if (state.context_fingerprint === undefined && observed !== null) {
+        state.context_fingerprint = observed;
+    }
     state.history.push(scan.open);
     state.last_engaged_at = new Date().toISOString();
     if (!writeState(stateFile, state)) {

package/src/scripts/hooks/session_eol_hook.ts

@@ -54,6 +54,7 @@ import {
     scanEolSlice,
     type EolCounters,
 } from '../_lib/session_eol.js';
+import { readContextObservation } from '../_lib/context_observation.js';
 import { buildCheckpoint, writeCheckpoint } from '../_lib/run_checkpoint.js';
 import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
@@ -381,7 +382,17 @@ export function main(): number {
         try {
             const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
             if (slug !== null) {
-                const cp = buildCheckpoint(workspaceRoot, eolSessionKey(checkpointRunId), slug);
+                // `road-to-wired-instruments` 2.1. The fingerprint was never
+                // passed here, so `context_fingerprint` was null in every
+                // checkpoint this package has ever written and the resume-time
+                // drift check it exists for could not fire. The value comes from
+                // the newest recorded probe rather than from a fresh one: this is
+                // the Stop path, and the probe costs a `gh` call. Absent stays
+                // absent, which reads as "not known" and never as "unchanged".
+                const observed = readContextObservation(workspaceRoot)?.fingerprint ?? null;
+                const cp = buildCheckpoint(workspaceRoot, eolSessionKey(checkpointRunId), slug, {
+                    ...(observed !== null ? { contextFingerprint: observed } : {}),
+                });
                 if (cp !== null) writeCheckpoint(workspaceRoot, cp);
             }
         } catch {

package/src/scripts/install-hooks.sh

@@ -26,6 +26,24 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # Pre-push hook: mirror the CI "Sync + Generate Tools Consistency" gate LOCALLY
 # so derived-output drift is caught BEFORE push, not in remote CI.
 #
+# THIS HOOK REFUSES. IT NEVER MERGES, AND NO ONE MAY "IMPROVE" IT INTO ONE.
+# A merge inside pre-push rewrites the working tree at the exact moment the
+# contributor believes their work is finished: one rejected push silently
+# becomes an unreviewed commit, and a conflict lands them mid-merge with no
+# warning and no way back to the state they typed `git push` from. Detection
+# belongs here; resolution belongs to a step run with the result in front of
+# you. When this hook refuses for staleness, the thing that fixes it is
+#
+#     task push-ready          # fetch -> integrate the base SET -> regenerate
+#                              # -> verify -> re-check freshness -> push
+#     task push-ready DRY=1    # the same six steps, read-only
+#
+# The base is a SET: a branch targeting a release line or a stacked parent may
+# also have to integrate the default branch, per the branch-convergence policy
+# read at the TARGET commit (src/scripts/_lib/branch_convergence.ts). The
+# default is merged FIRST, so a conflict surfaces against the broader base
+# where it is cheapest to abandon.
+#
 # History: the remote "Consistency" check failed in a large share of PRs because
 # the old hook only verified dist sync + the COMMAND count — it missed
 # guideline/skill/rule count drift and the generate-tools / router / corpus

package/src/scripts/lint_code_comments.ts

@@ -353,6 +353,107 @@ function changedFiles(root: string, base: string): string[] {
     return [...new Set([...tracked, ...untracked, ...dirty])].filter((f) => f.trim().length > 0);
 }
 
+/**
+ * Line numbers this diff ADDED, per file. `'all'` for an untracked file, whose
+ * every line is new.
+ *
+ * The gate is described in `.github/workflows/rule-backstops.yml` as
+ * *"diff-scoped, so a pre-existing tree does not turn red"*, and selecting the
+ * FILE set from the diff while scanning each file WHOLE only delivers that for
+ * files nobody touches. Measured 2026-09-02 on PR #1813, which added no
+ * flagged comment at all and was refused on eleven legacy lines — four
+ * provenance paths and seven box rules — in four files it edited for unrelated
+ * reasons. A gate that reds on debt in any file you open makes every edit to an
+ * old file carry an unbounded comment sweep, and the escape it offers per line
+ * turns into exactly the allowlist growth `autonomous-execution` forbids.
+ *
+ * Teeth are unchanged where they belong: a comment the diff writes is scanned
+ * on the line it writes. The explicit-path mode (`--files`) stays whole-file,
+ * because a caller naming a path is asking for that file, not for a diff.
+ *
+ * Parsed from `--unified=0` hunk headers rather than from a patch body: the
+ * header carries the post-image start and count directly, so no line of added
+ * content has to be counted by hand.
+ */
+export function addedLineMap(root: string, base: string): Map<string, Set<number> | 'all'> {
+    const out = new Map<string, Set<number> | 'all'>();
+    const u = spawnSync('git', ['ls-files', '--others', '--exclude-standard'], {
+        cwd: root, encoding: 'utf-8',
+    });
+    if (u.status === 0) {
+        for (const f of u.stdout.split('\n')) {
+            if (f.trim()) out.set(f.trim(), 'all');
+        }
+    }
+    for (const argv of [
+        ['diff', '--unified=0', '--diff-filter=ACMR', `${base}...HEAD`],
+        ['diff', '--unified=0', '--diff-filter=ACMR'],
+    ]) {
+        const r = spawnSync('git', argv, { cwd: root, encoding: 'utf-8' });
+        if (r.status !== 0) continue;
+        mergeAddedLines(out, parseAddedLines(r.stdout));
+    }
+    return out;
+}
+
+/**
+ * Added line numbers per file, from a `git diff --unified=0` patch.
+ *
+ * Split out from the git call so the parse is testable without a repository
+ * whose diff the test would have to manufacture. A `@@` header with no count
+ * means one line — `@@ -4 +4 @@` — and a `+++ /dev/null` header is a deletion,
+ * which adds nothing.
+ */
+export function parseAddedLines(diffText: string): Map<string, Set<number>> {
+    const out = new Map<string, Set<number>>();
+    let file: string | null = null;
+    for (const line of diffText.split('\n')) {
+        if (line.startsWith('+++ ')) {
+            const p = line.slice(4).trim();
+            file = p === '/dev/null' ? null : p.replace(/^b\//, '');
+            continue;
+        }
+        if (!file || !line.startsWith('@@')) continue;
+        const m = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,(\d+))? @@/.exec(line);
+        if (!m) continue;
+        const start = Number.parseInt(m[1] as string, 10);
+        const count = m[2] === undefined ? 1 : Number.parseInt(m[2], 10);
+        const set = out.get(file) ?? new Set<number>();
+        for (let n = start; n < start + count; n += 1) set.add(n);
+        out.set(file, set);
+    }
+    return out;
+}
+
+/** Fold one parsed patch into the accumulator; `'all'` always wins. */
+function mergeAddedLines(
+    into: Map<string, Set<number> | 'all'>,
+    from: Map<string, Set<number>>,
+): void {
+    for (const [file, lines] of from) {
+        const prev = into.get(file);
+        if (prev === 'all') continue;
+        const set = prev ?? new Set<number>();
+        for (const n of lines) set.add(n);
+        into.set(file, set);
+    }
+}
+
+/**
+ * Findings the diff is answerable for: those sitting on a line it added.
+ *
+ * `'all'` (an untracked file) keeps everything, `undefined` (a file the diff
+ * did not touch) keeps nothing — the two ends of the same rule.
+ */
+export function findingsOnAddedLines(
+    findings: readonly CommentFinding[],
+    lines: Set<number> | 'all' | undefined,
+): CommentFinding[] {
+    if (lines === undefined) return [];
+    if (lines === 'all') return [...findings];
+    return findings.filter((f) => lines.has(f.line));
+}
+
 /** One fixture: a file body and the classes the gate must report on it. */
 export interface CommentCase {
     /** Printed by both consumers, so it reads as the assertion it makes. */
@@ -575,12 +676,16 @@ export function main(argv: string[]): number {
     if (!base && explicit.length === 0) { process.stderr.write('--base needs a ref\n'); return 1; }
 
     const candidates = (explicit.length > 0 ? explicit : changedFiles(root, base)).filter(isScannable);
+    // Whole file when a caller named the path; only the lines the diff added
+    // when the scope IS the diff — see `addedLineMap` for the measured reason.
+    const added = explicit.length > 0 ? null : addedLineMap(root, base);
     const findings: CommentFinding[] = [];
     for (const rel of candidates) {
         const abs = path.isAbsolute(rel) ? rel : path.join(root, rel);
         let text: string;
         try { text = fs.readFileSync(abs, 'utf-8'); } catch { continue; }
-        findings.push(...scanText(rel, text));
+        const all = scanText(rel, text);
+        findings.push(...(added ? findingsOnAddedLines(all, added.get(rel)) : all));
     }
 
     try {

package/src/scripts/release.ts

@@ -160,6 +160,8 @@ import {
     SystemExitError,
     set_augment_manifest_version,
     set_marketplace_version,
+    _rstrip,
+    _splitlines,
 } from './release_env.js';
 import type { RunResult } from './release_publication.js';
 // Re-export surface for the six names tests import from `release.js` and that
@@ -192,6 +194,7 @@ import {
     _target_from_branch,
     create_and_push_annotated_tag,
     guard_publication,
+    guard_release_curation,
     die,
     gh,
     git,
@@ -744,22 +747,6 @@ function prepend_changelog(p: string, entry: string): void {
 }
 
 /** Mirror of Python `str.splitlines()` (no trailing empty for a final newline). */
-function _splitlines(text: string): string[] {
-    if (text === '') {
-        return [];
-    }
-    const parts = text.split(/\r\n|\r|\n/);
-    if (parts.length > 0 && parts[parts.length - 1] === '') {
-        parts.pop();
-    }
-    return parts;
-}
-
-/** Mirror of Python `str.rstrip()` (trailing whitespace). */
-function _rstrip(text: string): string {
-    return text.replace(/\s+$/u, '');
-}
-
 // ─── file mutations ───────────────────────────────────────────────────────────
 
 /** Update the top-level `version` field; preserve 4-space indentation. */
@@ -1167,7 +1154,6 @@ function _step(n: number, total: number, msg: string): void {
     process.stdout.write(`[${n}/${total}] ${msg}\n`);
 }
 
-
 function execute(
     plan: Plan,
     opts: { wait_for_checks: boolean; dry_run: boolean; resume?: boolean; ci?: boolean },
@@ -1276,6 +1262,8 @@ function execute(
         run(['task', 'release-prepare']);
     }
 
+    guard_release_curation(plan.target, pr_merged);
+
     // ─── 3. commit ──────────────────────────────────────────────────────────
     if (pr_merged) {
         _step(3, total, 'PR already merged — skip commit');