@event4u/agent-config 9.11.0 → 9.13.0

package/src/install/wizard-plan.ts

@@ -91,6 +91,16 @@ const CLAUDE_SKILL_BUNDLE: ReadonlyArray<readonly [string, string]> = [
  * — they either follow a marker-only convention (handled by bridges in
  * Phase A6) or have no markdown convention at all.
  */
+/**
+ * The one deploy-source row that carries install-time rule scoping.
+ *
+ * Exported so the CLI global path (`scripts/install.ts::_deploy_global_content`)
+ * keys its filter off the SAME string this expander does. Two paths agreeing on
+ * the predicate but disagreeing on which source it applies to would reproduce
+ * exactly the divergence rule scoping exists to prevent.
+ */
+export const RULE_SOURCE_REL = 'dist/agent-src/rules';
+
 export const GLOBAL_DEPLOY_SOURCES: Readonly<Record<string, ReadonlyArray<readonly [string, string]>>> = {
     'claude-code': CLAUDE_SKILL_BUNDLE,
     augment: [
@@ -195,7 +205,7 @@ export function expandWizardSources(inputs: WizardExpandInputs): PlanSource[] {
             // Rule sources get the install-time scoping filter — the same
             // predicate the projection path uses (Phase 1b: the consumer
             // install may never drift from Pipeline A, the source projection).
-            const isRuleSource = srcRel === 'dist/agent-src/rules';
+            const isRuleSource = srcRel === RULE_SOURCE_REL;
             out.push({
                 toolId,
                 srcDir,

package/src/scripts/_lib/counted_probe.ts

@@ -0,0 +1,142 @@
+/**
+ * Bounded shell-out for probes that parse a count or a list out of stdout.
+ *
+ * `spawnSync` buffers the child's whole stdout in memory and fails with
+ * `ENOBUFS` past `maxBuffer`, whose default is 1 MiB. A probe that treats that
+ * failure as "no output" reports **zero** — and zero, for a counting probe, is
+ * indistinguishable from a clean result. That is how a release shipped without
+ * its `Tests:` footer: the `vitest list` output had grown to 1,254,812 bytes,
+ * the probe degraded silently, and the omission surfaced only as a red gate
+ * downstream.
+ *
+ * Raising the buffer alone just moves the cliff. The invariant this module
+ * enforces is the other half: **a truncated read is an error, never a zero.**
+ *
+ * The distinction that matters:
+ *
+ * - `ENOBUFS` — the command *succeeded* and we lost its output. There is no
+ *   honest count to report, so this throws.
+ * - `ENOENT` / non-zero exit — the command did not run, or ran and failed.
+ *   The caller may legitimately degrade (a dev box without `npx`), so these
+ *   are reported as a typed outcome rather than thrown.
+ *
+ * Scope note: this is deliberately not a general exec wrapper. It covers the
+ * counting/listing class, where a short read silently manufactures a passing
+ * result.
+ */
+import { spawnSync, type SpawnSyncReturns } from 'node:child_process';
+
+/**
+ * Default ceiling: 64 MiB.
+ *
+ * ~50× the largest listing this repository currently produces, at no cost
+ * when the output is small — `maxBuffer` is a ceiling, not an allocation.
+ */
+export const DEFAULT_PROBE_MAX_BUFFER = 64 * 1024 * 1024;
+
+/** Raised when a probe's output exceeded the buffer, so its count is unknowable. */
+export class ProbeOverflowError extends Error {
+    constructor(
+        readonly command: string,
+        readonly maxBuffer: number,
+    ) {
+        super(
+            `probe \`${command}\` exceeded its ${Math.round(maxBuffer / (1024 * 1024))} MiB ` +
+                'output buffer — the read was truncated, so any count derived from it ' +
+                'would be wrong. This is an error rather than a zero on purpose: a ' +
+                'counting probe that degrades to zero reports a clean result it never ' +
+                'measured. Raise the buffer or narrow the command.',
+        );
+        this.name = 'ProbeOverflowError';
+    }
+}
+
+export interface ProbeOptions {
+    readonly cwd?: string;
+    readonly maxBuffer?: number;
+    readonly timeout?: number;
+    readonly env?: NodeJS.ProcessEnv;
+}
+
+export interface ProbeResult {
+    /** True when the command ran and exited 0. */
+    readonly ok: boolean;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly status: number | null;
+    /** Populated when the command could not be run or failed; never set for overflow (that throws). */
+    readonly failure: string | null;
+}
+
+/**
+ * Run a command and capture stdout with an explicit buffer ceiling.
+ *
+ * @throws {ProbeOverflowError} when the child's output exceeded `maxBuffer`.
+ */
+export function runCountedProbe(
+    command: string,
+    args: readonly string[],
+    opts: ProbeOptions = {},
+): ProbeResult {
+    const maxBuffer = opts.maxBuffer ?? DEFAULT_PROBE_MAX_BUFFER;
+    const res: SpawnSyncReturns<string> = spawnSync(command, [...args], {
+        cwd: opts.cwd,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        maxBuffer,
+        ...(opts.timeout === undefined ? {} : { timeout: opts.timeout }),
+        ...(opts.env === undefined ? {} : { env: opts.env }),
+    });
+    return interpretProbeResult(res, `${command} ${args.join(' ')}`.trim(), maxBuffer);
+}
+
+/**
+ * Classify a finished spawn. Split out from `runCountedProbe` so the failure
+ * modes are unit-testable without spawning a real, slow, large-output child.
+ *
+ * @throws {ProbeOverflowError} on `ENOBUFS`.
+ */
+export function interpretProbeResult(
+    res: {
+        error?: (Error & { code?: string }) | undefined;
+        status: number | null;
+        stdout: string | null;
+        stderr?: string | null;
+    },
+    command: string,
+    maxBuffer: number = DEFAULT_PROBE_MAX_BUFFER,
+): ProbeResult {
+    const stdout = res.stdout ?? '';
+    const stderr = res.stderr ?? '';
+    if (res.error) {
+        if (res.error.code === 'ENOBUFS') {
+            throw new ProbeOverflowError(command, maxBuffer);
+        }
+        return {
+            ok: false,
+            stdout,
+            stderr,
+            status: res.status,
+            failure: `${res.error.code ?? res.error.message}`,
+        };
+    }
+    if ((res.status ?? 1) !== 0) {
+        return {
+            ok: false,
+            stdout,
+            stderr,
+            status: res.status,
+            failure: `exited ${res.status ?? '(null)'}`,
+        };
+    }
+    return { ok: true, stdout, stderr, status: res.status, failure: null };
+}
+
+/** Non-empty, trimmed lines of a successful probe — the usual "list" shape. */
+export function probeLines(result: ProbeResult): string[] {
+    if (!result.ok) return [];
+    return result.stdout
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}

package/src/scripts/_lib/global_deploy_inventory.ts

@@ -254,6 +254,13 @@ function json_string_ascii(s: string): string {
   return out;
 }
 
+/**
+ * Predicate over a SOURCE file path — `true` = the file arrives in the install.
+ * Identical shape to `PlanSource.fileFilter` (`src/install/plan.ts`), so the
+ * plan path and the deploy path can share one predicate instance.
+ */
+export type FileFilter = (srcFile: string) => boolean;
+
 /**
  * Anchor-relative paths the deploy of `src` → `<anchor>/<dest_rel>` maintains
  * — written OR skipped-as-identical.
@@ -262,8 +269,20 @@ function json_string_ascii(s: string): string {
  * symlinked files resolve to file entries, symlinked subdirectories are walked
  * through their resolved targets. `dest_rel` may be empty (`""`) for plan
  * entries that deploy into the anchor root.
+ *
+ * `file_filter` MUST be the same predicate the copy was given. This set is what
+ * the reaper treats as "should exist"; a file the copy skipped but this set
+ * still lists is never reaped, and a file this set omits while the copy wrote it
+ * is deleted on the next deploy. Passing the filter to one and not the other is
+ * the failure mode the rule-scoping work exists to avoid — see
+ * `install._deploy_global_content`, which derives one filter and hands it to
+ * both.
  */
-export function expected_deploy_files(src: string, dest_rel: string): Set<string> {
+export function expected_deploy_files(
+  src: string,
+  dest_rel: string,
+  file_filter: FileFilter | null = null,
+): Set<string> {
   const out = new Set<string>();
   let src_stat: fs.Stats;
   try {
@@ -273,6 +292,9 @@ export function expected_deploy_files(src: string, dest_rel: string): Set<string
     return out;
   }
   if (!src_stat.isDirectory()) {
+    if (file_filter !== null && !file_filter(src)) {
+      return out;
+    }
     out.add(as_posix(dest_rel));
     return out;
   }
@@ -298,6 +320,12 @@ export function expected_deploy_files(src: string, dest_rel: string): Set<string
         _walk(fs.realpathSync(entry), rel);
         continue;
       }
+      // The predicate sees the SOURCE path, never `rel`: the rule-scope
+      // predicate reads the file's own frontmatter tags, so a dest-relative
+      // path would not resolve. Same contract as the copy twin.
+      if (file_filter !== null && !file_filter(entry)) {
+        continue;
+      }
       out.add(as_posix(rel));
     }
   };
@@ -554,7 +582,15 @@ function prune_empty_dirs(prune_candidates: Set<string>, anchor_resolved: string
 }
 
 /** `anchor in node.parents` — is `anchor` a strict ancestor of `node`? */
-function is_ancestor(anchor: string, node: string): boolean {
+/**
+ * Is `node` strictly inside `anchor`? Pure path arithmetic, no I/O — callers
+ * pass already-resolved (realpath'd) paths when symlink escape matters.
+ *
+ * Exported for `install._copy_dir_dereferencing_symlinks`, which must reject a
+ * symlink whose target leaves the package root. One definition rather than a
+ * second copy of the `path.relative` idiom.
+ */
+export function is_ancestor(anchor: string, node: string): boolean {
   const rel = path.relative(anchor, node);
   return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }

package/src/scripts/_lib/overbuild_lens_contract.ts

@@ -0,0 +1,196 @@
+/**
+ * Output-contract parser + scorer for `overbuild-review-lens`.
+ *
+ * The lens's own SKILL.md states an output contract. This is the half of that
+ * contract a machine can check: tag grammar, the mandatory Chesterton's-Fence
+ * line on every `delete:` finding, the honest-null form, and the sign of the
+ * net-lines figure. Whether a live model *finds the plant* in a fixture is not
+ * checkable here — that needs a scored eval run — and the split is stated in
+ * `tests/fixtures/overbuild-lens/README.md` rather than blurred.
+ *
+ * Deliberately dependency-free and side-effect-free: parse a string, return a
+ * verdict. Nothing reads the filesystem or the network.
+ */
+
+/** The six tags the lens may emit. Anything else is a contract violation. */
+export const LENS_TAGS = ['delete', 'stdlib', 'native', 'yagni', 'shrink', 'flatten'] as const;
+export type LensTag = (typeof LENS_TAGS)[number];
+
+export const LENS_VERDICTS = ['lean', 'trim', 'overbuilt'] as const;
+export type LensVerdict = (typeof LENS_VERDICTS)[number];
+
+export interface LensFinding {
+    tag: LensTag;
+    location: string;
+    text: string;
+    /** Present only on `delete:` findings; the contract requires it there. */
+    fence?: { why: string; safe: string; covered: string };
+}
+
+export interface ParsedLensOutput {
+    verdict: LensVerdict | null;
+    findings: LensFinding[];
+    isNull: boolean;
+    netLines: number | null;
+    /** Contract violations found while parsing. Empty means the shape is legal. */
+    errors: string[];
+}
+
+const _TAG_RE = new RegExp(
+    String.raw`^\s*\d+\.\s+(` + LENS_TAGS.join('|') + String.raw`):\s+(\S+)\s+(.*\S)\s*$`,
+);
+const _FENCE_RE =
+    /^\s*Fence:\s*why=(.+?)\s+safe=(.+?)\s+covered=(yes|no|partial)\s*$/;
+const _VERDICT_RE = /^\s*Verdict:\s*(\S+)\s*$/;
+const _NET_RE = /^\s*Net:\s*([+-]?\d+)\s+lines?\s*$/;
+const _NULL_RE = /^\s*Findings:\s*none\b/;
+const _COVERED_VALUES = new Set(['yes', 'no', 'partial']);
+
+/**
+ * Parse a lens verdict block. Never throws — a malformed block comes back with
+ * a populated `errors` array, because a parser that throws on bad input cannot
+ * report *how many* ways the input was bad.
+ */
+export function parseLensOutput(raw: string): ParsedLensOutput {
+    const lines = raw.split('\n');
+    const errors: string[] = [];
+    const findings: LensFinding[] = [];
+    let verdict: LensVerdict | null = null;
+    let netLines: number | null = null;
+    let isNull = false;
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line: string = lines[i] ?? '';
+
+        const v = line.match(_VERDICT_RE);
+        if (v) {
+            if ((LENS_VERDICTS as readonly string[]).includes(v[1] ?? '')) {
+                verdict = v[1] as LensVerdict;
+            } else {
+                errors.push(`unknown verdict \`${v[1]}\` (allowed: ${LENS_VERDICTS.join('/')})`);
+            }
+            continue;
+        }
+
+        const n = line.match(_NET_RE);
+        if (n) {
+            netLines = Number.parseInt(n[1] ?? '0', 10);
+            continue;
+        }
+
+        if (_NULL_RE.test(line)) {
+            isNull = true;
+            continue;
+        }
+
+        const m = line.match(_TAG_RE);
+        if (!m) {
+            // An unrecognised numbered line is a finding the grammar rejects.
+            if (/^\s*\d+\.\s+\S+:/.test(line)) {
+                errors.push(`line ${i + 1}: not a legal tag — \`${line.trim()}\``);
+            }
+            continue;
+        }
+
+        const finding: LensFinding = {
+            tag: m[1] as LensTag,
+            location: m[2] ?? '',
+            text: m[3] ?? '',
+        };
+
+        if (finding.tag === 'delete') {
+            const fenceLine: string = lines[i + 1] ?? '';
+            const f = fenceLine.match(_FENCE_RE);
+            if (!f) {
+                errors.push(
+                    `line ${i + 1}: \`delete:\` finding at ${finding.location} has no valid ` +
+                        'Fence line (why= / safe= / covered=yes|no|partial)',
+                );
+            } else {
+                const covered = f[3] ?? '';
+                finding.fence = {
+                    why: (f[1] ?? '').trim(),
+                    safe: (f[2] ?? '').trim(),
+                    covered,
+                };
+                if (!_COVERED_VALUES.has(covered)) {
+                    errors.push(`line ${i + 2}: covered= must be yes|no|partial`);
+                }
+            }
+        }
+
+        findings.push(finding);
+    }
+
+    if (verdict === null) errors.push('no `Verdict:` line');
+    if (netLines === null) errors.push('no `Net: <n> lines` line');
+    if (isNull && findings.length > 0) {
+        errors.push('emitted the null AND findings — pick one');
+    }
+    if (!isNull && findings.length === 0) {
+        errors.push('no findings and no null block — the null is mandatory, not optional');
+    }
+    if (verdict === 'lean' && findings.length > 0) {
+        errors.push('`lean` verdict with findings — a lean diff has nothing to cut');
+    }
+    if (verdict !== 'lean' && isNull) {
+        errors.push('null block with a non-`lean` verdict');
+    }
+
+    return { verdict, findings, isNull, netLines, errors };
+}
+
+export interface ExpectedLabels {
+    verdict: string;
+    must_tags: string[];
+    forbidden_tags: string[];
+    must_be_null: boolean;
+    net_sign: 'negative' | 'zero' | 'positive';
+    requires_fence?: boolean;
+}
+
+/**
+ * Score a parsed output against a fixture's expected labels. Returns the list
+ * of failures — empty means the output is correct for that fixture.
+ */
+export function scoreAgainstExpected(
+    parsed: ParsedLensOutput,
+    expected: ExpectedLabels,
+): string[] {
+    const failures = [...parsed.errors];
+
+    if (parsed.verdict !== expected.verdict) {
+        failures.push(`verdict ${parsed.verdict} ≠ expected ${expected.verdict}`);
+    }
+    if (parsed.isNull !== expected.must_be_null) {
+        failures.push(
+            expected.must_be_null
+                ? 'expected the honest null, got findings (invented a finding on a lean diff)'
+                : 'expected findings, got the null (missed the plant)',
+        );
+    }
+
+    const seen = new Set(parsed.findings.map((f) => f.tag));
+    for (const tag of expected.must_tags) {
+        if (!seen.has(tag as LensTag)) failures.push(`missing required tag \`${tag}:\``);
+    }
+    for (const tag of expected.forbidden_tags) {
+        if (seen.has(tag as LensTag)) failures.push(`emitted forbidden tag \`${tag}:\``);
+    }
+
+    if (expected.requires_fence) {
+        const unfenced = parsed.findings.filter((f) => f.tag === 'delete' && !f.fence);
+        if (unfenced.length > 0) failures.push('a `delete:` finding is missing its fence');
+    }
+
+    const sign =
+        parsed.netLines === null ? 'unknown'
+        : parsed.netLines < 0 ? 'negative'
+        : parsed.netLines > 0 ? 'positive'
+        : 'zero';
+    if (sign !== expected.net_sign) {
+        failures.push(`net-lines sign ${sign} ≠ expected ${expected.net_sign}`);
+    }
+
+    return failures;
+}

package/src/scripts/_lib/release_scope.ts

@@ -0,0 +1,207 @@
+/**
+ * Release-aware diff scope for content checks.
+ *
+ * A release PR's own diff is version, changelog, pack metadata and marketplace
+ * files: the substantive work arrived in the commits *before* the cut. Any
+ * check scoped to "files changed in this PR" therefore measures the release
+ * wrapper, not the release. The visible consequence was a 179-commit release
+ * whose skill lint reported **"0 skills checked, INCONCLUSIVE"** and merged.
+ *
+ * The fix is a range, not a new gate: on a release PR the content checks
+ * resolve their scope to `previous_release_tag...HEAD`. Everywhere else the
+ * base is unchanged.
+ *
+ * The three release-detection primitives below were written for
+ * `self_review_gate.ts`, which already switched its own analysis range this
+ * way. They live here so the second consumer reuses the precedent instead of
+ * re-deriving it — two copies of "is this a release PR?" is exactly the drift
+ * this package has paid for before. `self_review_gate.ts` re-exports them, so
+ * its public surface is unchanged.
+ */
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+/**
+ * A release PR is detected from its own packaging diff (baseRef...HEAD,
+ * scoped to CHANGELOG.md + package.json): an added changelog heading and an
+ * added package.json version bump, agreeing on the same version. Pure over
+ * the patch text — no git call — so it is unit-testable with synthetic
+ * patches. See docs/design/release-pr-review-mode.md.
+ */
+export function detectReleaseVersion(patchText: string): string | null {
+    const addedLines = patchText
+        .split('\n')
+        .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
+        .map((l) => l.slice(1));
+
+    let changelogVersion: string | null = null;
+    let packageVersion: string | null = null;
+    for (const line of addedLines) {
+        const changelogMatch = /^##\s*\[(\d+\.\d+\.\d+)\]/.exec(line);
+        if (changelogMatch) changelogVersion = changelogMatch[1] ?? null;
+        const packageMatch = /^\s*"version"\s*:\s*"(\d+\.\d+\.\d+)"/.exec(line);
+        if (packageMatch) packageVersion = packageMatch[1] ?? null;
+    }
+    if (changelogVersion && packageVersion && changelogVersion === packageVersion) {
+        return changelogVersion;
+    }
+    return null;
+}
+
+function releaseDetectionPatch(baseRef: string, cwd: string): string {
+    const r = spawnSync('git', ['diff', `${baseRef}...HEAD`, '--', 'CHANGELOG.md', 'package.json'], {
+        cwd,
+        encoding: 'utf8',
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    return (r.stdout ?? '').toString();
+}
+
+/** Impure wrapper: collects the packaging patch via git, then detects. */
+export function detectReleaseVersionFromGit(
+    baseRef: string,
+    cwd: string = REPO_ROOT,
+): string | null {
+    return detectReleaseVersion(releaseDetectionPatch(baseRef, cwd));
+}
+
+/** `major.minor.patch`, tolerating an optional `v` prefix; null if not semver-shaped. */
+function parseSemver(raw: string): [number, number, number] | null {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(raw.trim());
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function semverLessThan(a: [number, number, number], b: [number, number, number]): boolean {
+    const [aMajor, aMinor, aPatch] = a;
+    const [bMajor, bMinor, bPatch] = b;
+    if (aMajor !== bMajor) return aMajor < bMajor;
+    if (aMinor !== bMinor) return aMinor < bMinor;
+    return aPatch < bPatch;
+}
+
+/**
+ * Highest semver-shaped tag strictly below `version`, or null if none. Pure
+ * over the supplied tag list — no git call. Non-semver tags (branch-backup
+ * names etc.) are ignored rather than throwing.
+ *
+ * The filtering is load-bearing, not defensive: this repository carries 152
+ * semver tags alongside names like `rebase-backup-pre-squash`, and those sort
+ * *above* every version under `git tag --sort=-v:refname`. A naive "newest
+ * tag" would resolve the scope to a backup ref.
+ */
+export function pickPreviousTag(version: string, tags: readonly string[]): string | null {
+    const target = parseSemver(version);
+    if (!target) return null;
+    let best: { raw: string; parsed: [number, number, number] } | null = null;
+    for (const raw of tags) {
+        const parsed = parseSemver(raw);
+        if (!parsed) continue;
+        if (!semverLessThan(parsed, target)) continue;
+        if (!best || semverLessThan(best.parsed, parsed)) best = { raw, parsed };
+    }
+    return best ? best.raw : null;
+}
+
+/** Local semver tags, newest first is not assumed — `pickPreviousTag` orders them. */
+function localTags(cwd: string): string[] {
+    const r = spawnSync('git', ['tag', '--list'], { cwd, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+    if ((r.status ?? 1) !== 0) return [];
+    return (r.stdout ?? '')
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+
+export interface ContentLintScope {
+    /** The ref a diff-scoped content check should compare HEAD against. */
+    readonly base: string;
+    /** True when the current head is a release PR whose scope was widened. */
+    readonly isRelease: boolean;
+    /** The release version, when detected. */
+    readonly version: string | null;
+    /** The tag the scope widened to, when resolved. */
+    readonly previousTag: string | null;
+    /** One line naming what was resolved and why — for the check's own output. */
+    readonly reason: string;
+}
+
+export interface ResolveOptions {
+    /** Branch a normal PR is compared against. */
+    readonly baseRef?: string;
+    readonly cwd?: string;
+    /**
+     * Explicit override, highest precedence. Set by a caller that already
+     * knows the range (a workflow input, a `--since` flag).
+     */
+    readonly since?: string | null | undefined;
+}
+
+/**
+ * Resolve the diff base a content check should use.
+ *
+ * Precedence: explicit `since` → `RELEASE_LINT_BASE` env → release-PR widening
+ * → the ordinary base ref. The release branch is *not* inferred from the
+ * branch name alone: the packaging-diff detector is what proves a release, so
+ * a branch merely named `release/...` with no version bump stays on the
+ * ordinary base rather than silently widening to a whole tag span.
+ *
+ * Never throws. A release whose previous tag cannot be resolved (the very
+ * first release, or a shallow clone with no tags) falls back to the ordinary
+ * base and says so in `reason` — a check that cannot widen its scope should
+ * report a small scope honestly, not crash the release.
+ */
+export function resolveContentLintScope(opts: ResolveOptions = {}): ContentLintScope {
+    const cwd = opts.cwd ?? REPO_ROOT;
+    const baseRef = opts.baseRef ?? 'origin/main';
+
+    const explicit = opts.since ?? process.env['RELEASE_LINT_BASE'] ?? null;
+    if (explicit !== null && explicit.trim() !== '') {
+        const base = explicit.trim();
+        return {
+            base,
+            isRelease: false,
+            version: null,
+            previousTag: null,
+            reason: `scope pinned to ${base} by an explicit override`,
+        };
+    }
+
+    const version = detectReleaseVersionFromGit(baseRef, cwd);
+    if (version === null) {
+        return {
+            base: baseRef,
+            isRelease: false,
+            version: null,
+            previousTag: null,
+            reason: `ordinary PR — scope is ${baseRef}...HEAD`,
+        };
+    }
+
+    const previousTag = pickPreviousTag(version, localTags(cwd));
+    if (previousTag === null) {
+        return {
+            base: baseRef,
+            isRelease: true,
+            version,
+            previousTag: null,
+            reason:
+                `release ${version} detected, but no earlier semver tag is reachable — ` +
+                `scope stays ${baseRef}...HEAD and therefore sees only the release wrapper`,
+        };
+    }
+
+    return {
+        base: previousTag,
+        isRelease: true,
+        version,
+        previousTag,
+        reason:
+            `release ${version} detected — scope widened to ${previousTag}...HEAD ` +
+            `so the check sees the release, not the version bump`,
+    };
+}