@event4u/agent-config 9.12.0 → 9.13.0

package/src/scripts/lint_skill_descriptions.ts

@@ -18,11 +18,32 @@
  *                            (em-dash / colon / comma list), no quoted example,
  *                            no imperative-verb lead. A bare topic restatement.
  *
- * (d) is signal-ABSENCE, not a phrase mandate: an imperative house-style
+ * (a)–(d) are signal-ABSENCE checks over every skill: an imperative house-style
  * description ("Writes Laravel PHP — Eloquent, Artisan …") carries routing
  * signal and passes. The farm-generator's name-echo frontmatter is the
  * must-fail specimen.
  *
+ * Two further checks are POSITIVE — they demand something be present — and are
+ * therefore scoped to CLUSTERED skills only (road-to-overlap-truth-and-skill-cut
+ * Phase 5):
+ *
+ *   (e) clustered-no-sibling-routing — the canonical overlap tool pairs this
+ *                            skill with a same-pack sibling at >= the canonical
+ *                            threshold, and the description never names that
+ *                            sibling. Two skills the router cannot tell apart,
+ *                            neither of which says which one loses.
+ *   (f) clustered-no-quoted-phrase — same cluster condition, and the description
+ *                            carries no quoted literal user phrase. In a cluster,
+ *                            the user's own words are the only tie-break the
+ *                            router gets.
+ *
+ * The cluster condition is what keeps these honest. A quoted-phrase mandate
+ * across all ~287 skills is noise, not routing — it would fire on skills with no
+ * neighbour to be confused with. Today the cluster set is EMPTY (the corpus has
+ * no same-pack pair at or above threshold), so (e) and (f) are dormant by
+ * construction and wake up exactly when a new skill lands close to an existing
+ * one. That is the point.
+ *
  * Deterministic, static-config only. Allowlist mirrors lint_skill_originality:
  * `lint_skill_descriptions_allowlist.json`, capped at 20 (autonomous-execution
  * allowlist-growth antipattern — over-cap means the linter is wrong).
@@ -39,6 +60,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import { OVERLAP_THRESHOLD, _cosine, collect } from './audit_skill_overlap.js';
 import { parse_frontmatter } from './skill_overlap.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -57,10 +79,54 @@ const IMPERATIVE_LEAD_RE =
 
 interface Violation {
     slug: string;
-    code: 'desc-equals-name' | 'duplicated-trigger' | 'triggers-are-name' | 'no-routing-signal';
+    code:
+        | 'desc-equals-name'
+        | 'duplicated-trigger'
+        | 'triggers-are-name'
+        | 'no-routing-signal'
+        | 'clustered-no-sibling-routing'
+        | 'clustered-no-quoted-phrase';
     detail: string;
 }
 
+/** A quoted literal phrase — `'expand this scene'` / `"film-grade scene"`. */
+const QUOTED_PHRASE_RE = /['"`][^'"`]{3,}['"`]/;
+
+/**
+ * Same-pack neighbours at or above the canonical overlap threshold, keyed by
+ * directory slug.
+ *
+ * Uses the canonical instrument, not a second implementation — one metric, one
+ * threshold, one answer. Cross-pack pairs are excluded for the same reason a
+ * cross-pack merge is out of scope: they do not compete for the same install.
+ */
+function computeClusters(root: string, threshold: number = OVERLAP_THRESHOLD): Map<string, string[]> {
+    const clusters = new Map<string, string[]>();
+    const skills = collect(root).map((s) => ({
+        slug: path.basename(path.dirname(s.relpath)),
+        packs: s.packs,
+        vector: s.vector,
+    }));
+    for (let i = 0; i < skills.length; i += 1) {
+        for (let j = i + 1; j < skills.length; j += 1) {
+            const a = skills[i]!;
+            const b = skills[j]!;
+            let sharesPack = false;
+            for (const p of a.packs) {
+                if (b.packs.has(p)) {
+                    sharesPack = true;
+                    break;
+                }
+            }
+            if (!sharesPack) continue;
+            if (_cosine(a.vector, b.vector) < threshold) continue;
+            clusters.set(a.slug, [...(clusters.get(a.slug) ?? []), b.slug]);
+            clusters.set(b.slug, [...(clusters.get(b.slug) ?? []), a.slug]);
+        }
+    }
+    return clusters;
+}
+
 /** A description carries routing signal if it names a condition, leads with an
  * imperative verb, enumerates specifics (em-dash / colon / ≥2 comma segments),
  * or embeds an example query (a quoted phrase). Absence of all four is the defect. */
@@ -89,7 +155,7 @@ function triggerPhrases(desc: string): string[] {
         .filter((p) => p.length >= 3);
 }
 
-function analyseSkill(slug: string, fm: Record<string, string>): Violation[] {
+function analyseSkill(slug: string, fm: Record<string, string>, siblings: readonly string[] = []): Violation[] {
     const out: Violation[] = [];
     const name = fm['name'] ?? slug;
     const desc = (fm['description'] ?? '').trim();
@@ -137,6 +203,25 @@ function analyseSkill(slug: string, fm: Record<string, string>): Violation[] {
         });
     }
 
+    // (e) + (f) fire ONLY for skills the canonical tool put in a cluster.
+    if (siblings.length > 0) {
+        const unrouted = siblings.filter((s) => !desc.includes(s));
+        if (unrouted.length > 0) {
+            out.push({
+                slug,
+                code: 'clustered-no-sibling-routing',
+                detail: `overlaps ${unrouted.map((s) => `\`${s}\``).join(', ')} at or above the canonical threshold, but the description never names ${unrouted.length === 1 ? 'it' : 'them'} — add a sibling-routing clause so the router knows which one loses`,
+            });
+        }
+        if (!QUOTED_PHRASE_RE.test(desc)) {
+            out.push({
+                slug,
+                code: 'clustered-no-quoted-phrase',
+                detail: `clustered with ${siblings.map((s) => `\`${s}\``).join(', ')} but carries no quoted literal user phrase — in a cluster the user's own words are the tie-break`,
+            });
+        }
+    }
+
     return out;
 }
 
@@ -192,13 +277,14 @@ function parseArgs(argv: string[]): Args {
 function main(argv: string[]): number {
     const args = parseArgs(argv);
     const allow = loadAllowlist();
+    const clusters = computeClusters(args.root);
     const violations: Violation[] = [];
     let scanned = 0;
     for (const md of skillMds(args.root)) {
         scanned += 1;
         const slug = path.basename(path.dirname(md));
         const [fm] = parse_frontmatter(fs.readFileSync(md, 'utf-8'));
-        for (const v of analyseSkill(slug, fm)) {
+        for (const v of analyseSkill(slug, fm, clusters.get(slug) ?? [])) {
             if (!allow.has(`${v.slug}::${v.code}`)) violations.push(v);
         }
     }
@@ -216,7 +302,9 @@ function main(argv: string[]): number {
         return 1;
     }
     if (!args.quiet) {
-        process.stdout.write(`✅  lint_skill_descriptions: ${scanned} skill(s) scanned, no description defects.\n`);
+        process.stdout.write(
+            `✅  lint_skill_descriptions: ${scanned} skill(s) scanned (${clusters.size} clustered), no description defects.\n`,
+        );
     }
     return 0;
 }

package/src/scripts/project_thin_rules.ts

@@ -155,8 +155,8 @@ const _TRIGGER_HINT_LIMIT = 6;
 /** A short, comma-joined sample of the rule's trigger keywords/phrases. */
 function _trigger_hint(fm: string): string {
     const hits: string[] = [];
-    // re.finditer(r'^\s*-\s*(?:keyword|phrase|intent):\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
-    const re = /^\s*-\s*(?:keyword|phrase|intent):\s*"?(.+?)"?\s*$/gm;
+    // re.finditer(r'^\s*-\s*(?:keyword|phrase):\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
+    const re = /^\s*-\s*(?:keyword|phrase):\s*"?(.+?)"?\s*$/gm;
     let m: RegExpExecArray | null;
     while ((m = re.exec(fm)) !== null) {
         hits.push((m[1] as string).trim());

package/src/scripts/release.ts

@@ -357,6 +357,109 @@ const SECTIONS: ReadonlyArray<readonly [string, string | null, readonly string[]
     ['Chores', null, ['chore']],
 ];
 
+// ---------------------------------------------------------------------------
+// Curated head (road-to-release-shape-honesty Phase 2)
+// ---------------------------------------------------------------------------
+
+/**
+ * The five head lines, in the order an operator reads them.
+ *
+ * Reviewers of 9.9.0 and 9.10.0 repeatedly could not tell, from a generated
+ * commit log, which entries change consumer behaviour, which need migration,
+ * which are internal gate repairs, and which ended as nulls. The log is a
+ * faithful record of *what was committed*; it is not a statement of *what
+ * changed for you*. The head is that statement, and it sits above the log
+ * rather than replacing it.
+ *
+ * Wording is taken from `docs/RELEASE_STORY_TEMPLATE.md` rather than invented,
+ * so the package does not end up with two competing definitions of a curated
+ * head.
+ */
+const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = [
+    'Behaviour changes',
+    'Default changes + migration',
+    'Security and correctness',
+    'Honest nulls',
+    'Known limitations',
+];
+
+/**
+ * Cap on the head, in rendered lines.
+ *
+ * Roughly ten operator-relevant lines: past that it stops being a summary and
+ * becomes a second changelog. The era budget is also finite
+ * (`_lib/changelog_eras.ts`, 250 lines per era), so an unbounded head would
+ * quietly consume it.
+ */
+export const RELEASE_HEAD_CAP_LINES = 10;
+
+/**
+ * The default value of every head line.
+ *
+ * `_none_` and not a placeholder token: for most releases it is the **true**
+ * answer, and a release that genuinely changed no defaults should say so
+ * rather than carry an unfilled marker. That also keeps the skeleton free of
+ * the placeholder prose `output-discipline` bans — there is nothing here that
+ * is wrong-if-shipped, only something that is uninformative-if-unedited.
+ */
+const HEAD_DEFAULT = '_none_';
+
+/**
+ * Render the curated head. Emitted by the generator on every release so it
+ * cannot be forgotten; edited by the maintainer before merge.
+ */
+export function render_release_head(
+    filled: Readonly<Record<string, string>> = {},
+): string[] {
+    const lines: string[] = [
+        '### Release highlights',
+        '',
+        '<!-- Curated head: fill before merge, keep it under ' +
+            `${RELEASE_HEAD_CAP_LINES} lines, and leave \`${HEAD_DEFAULT}\` where it is ` +
+            'genuinely the answer. The generated log below is unchanged. -->',
+    ];
+    for (const label of RELEASE_HEAD_SECTIONS) {
+        const value = (filled[label] ?? '').trim();
+        lines.push(`- **${label}:** ${value === '' ? HEAD_DEFAULT : value}`);
+    }
+    return lines;
+}
+
+/**
+ * Drop commits whose rendered line would be identical.
+ *
+ * The generated log is keyed by SHA, but a reader is not: a cherry-pick, a
+ * re-land, or one change split across branches produces the same
+ * `scope: subject` twice with different SHAs, and the notes then say the same
+ * thing twice with two links. Keyed on `type + scope + subject` — the parts
+ * that reach the rendered line — keeping the first occurrence, so the earliest
+ * SHA stays the citation.
+ *
+ * Breaking commits are never folded into a non-breaking twin: `!` changes what
+ * the line *means*, and collapsing them would hide a breaking change behind a
+ * routine one.
+ */
+export function dedupe_commit_lines(commits: readonly Commit[]): Commit[] {
+    const seen = new Set<string>();
+    const out: Commit[] = [];
+    for (const c of commits) {
+        const key = [c.breaking ? '!' : '', c.type, c.scope ?? '', c.subject].join('\x1f');
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+
+/** Rendered length of the head, for the cap assertion. */
+export function release_head_line_count(head: readonly string[]): number {
+    // The HTML comment is invisible to a reader, so it does not count against
+    // an operator-facing cap.
+    return head.filter((l) => !l.trimStart().startsWith('<!--')).length;
+}
+
 const BREAKING_RE = /^([a-z]+)(\([^)]+\))?!:/;
 const CONVENTIONAL_RE = /^(?<type>[a-z]+)(?:\((?<scope>[^)]+)\))?(?<bang>!)?: (?<subject>.+)$/;
 
@@ -687,7 +790,7 @@ function render_changelog_entry(
     prev: string | null,
     commits: readonly Commit[],
     today: string,
-    opts: { test_trend_line?: string | null } = {},
+    opts: { test_trend_line?: string | null; head?: Readonly<Record<string, string>> } = {},
 ): [string, string] {
     const test_trend_line = opts.test_trend_line ?? null;
     let heading: string;
@@ -706,7 +809,7 @@ function render_changelog_entry(
     }
     grouped['BREAKING CHANGES'] = [];
     const other: Commit[] = [];
-    for (const c of commits) {
+    for (const c of dedupe_commit_lines(commits)) {
         if (c.breaking) {
             grouped['BREAKING CHANGES']!.push(c);
             continue;
@@ -724,7 +827,8 @@ function render_changelog_entry(
         }
     }
 
-    const body_lines: string[] = [];
+    // The curated head sits above the generated log, which stays unchanged.
+    const body_lines: string[] = [...render_release_head(opts.head ?? {})];
     const ordered_labels = ['BREAKING CHANGES', ...SECTIONS.map(([label]) => label)];
     for (const label of ordered_labels) {
         const bucket = grouped[label] ?? [];

package/src/scripts/resolve_lint_scope.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env tsx
+/**
+ * Print the diff base a content check should compare HEAD against.
+ *
+ * A resolver, not a gate — it decides nothing and blocks nothing. It exists so
+ * the shell-side checks in `.github/workflows/skill-lint.yml` resolve their
+ * scope from the same source as `skill_linter --changed`, instead of hardcoding
+ * `origin/${base_ref}` and going blind on a release PR (the "0 changed corpus
+ * files, INCONCLUSIVE" outcome).
+ *
+ * Usage:
+ *   resolve_lint_scope [--base-ref <ref>] [--json]
+ *
+ * Prints the base ref on stdout and the reason on stderr, so a caller can do
+ *   BASE="$(./scripts-run src/scripts/resolve_lint_scope --base-ref "origin/$X")"
+ * and still see the explanation in the log.
+ *
+ * Exit codes: 0 always — a resolver that cannot widen reports the ordinary
+ * base and says why. Failing here would turn an unresolvable tag into a red
+ * release for the wrong reason; the emptiness decision belongs to the gate.
+ */
+import { resolveContentLintScope } from './_lib/release_scope.js';
+
+export function main(argv: string[]): number {
+    let baseRef: string | undefined;
+    let asJson = false;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i] as string;
+        if (a === '--base-ref') {
+            baseRef = argv[i + 1];
+            i += 1;
+        } else if (a.startsWith('--base-ref=')) {
+            baseRef = a.slice('--base-ref='.length);
+        } else if (a === '--json') {
+            asJson = true;
+        }
+    }
+
+    const scope = resolveContentLintScope(baseRef === undefined ? {} : { baseRef });
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify(scope)}\n`);
+        return 0;
+    }
+    process.stderr.write(`resolve_lint_scope: ${scope.reason}\n`);
+    process.stdout.write(`${scope.base}\n`);
+    return 0;
+}
+
+const invokedDirectly =
+    process.argv[1] !== undefined && /resolve_lint_scope\.ts$/.test(process.argv[1]);
+if (invokedDirectly) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/router_telemetry.ts

@@ -24,7 +24,6 @@
  *   | `keyword`      | case-insensitive substring inside the prompt text                |
  *   | `phrase`       | case-insensitive substring (multi-word) inside the prompt text   |
  *   | `command`      | case-sensitive prefix on `command:` field (optional context)     |
- *   | `intent`       | informational only — never auto-matches; counted separately      |
  *   | `path_prefix`  | prefix match against any path in `open_files` (optional context) |
  *   | `file_pattern` | fnmatch against any path in `open_files` (optional context)      |
  *
@@ -227,10 +226,6 @@ export function trigger_matches(
     }
     return false;
   }
-  if ("intent" in trigger) {
-    // Intent triggers are informational and never auto-match.
-    return false;
-  }
   return false;
 }
 

package/src/scripts/runtime_dispatcher.ts

@@ -34,6 +34,7 @@ import { build_registry } from './runtime_registry.js';
 import type { ExecutionResult} from './runtime_handler.js';
 import { HandlerError, execute_shell } from './runtime_handler.js';
 import { resolve_level } from './_lib/script_output.js';
+import { validate_tool_declarations } from './tool_registry.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -187,6 +188,45 @@ export function dispatch(skillName: string, registry: SkillRuntime[]): DispatchR
                 warnings: [],
             });
         }
+        // Gate integrity — the grant resolves against TRUSTED config, never
+        // against the skill's own frontmatter.
+        //
+        // road-to-governance-invariants Phase 4, property (b). Every field the
+        // three checks above read (`execution_type`, `handler`, `safety_mode`)
+        // comes out of the skill file's own YAML, so a skill that writes
+        // `safety_mode: strict` self-certifies past all of them. `tool-safety`
+        // states "Allowlist only — tool names must match the tool registry",
+        // and `validate_tool_declarations` implemented exactly that — but
+        // nothing called it. Measured before this branch existed: a skill
+        // declaring `allowed_tools: ["NotInRegistry", "Bash(*)"]` dispatched
+        // `ready`.
+        //
+        // Scoped to the automated path deliberately. That is where
+        // `runtime-safety` puts the hard requirement, and it is the path that
+        // would execute with no human in the loop. Assisted skills get a
+        // warning instead (below): blocking them would reject the scoped-grant
+        // syntax (`Bash(scripts-run:*)`) that `tool-safety` itself prefers and
+        // that this two-entry registry does not model.
+        const toolCheck = validate_tool_declarations(skill.allowed_tools);
+        if (!toolCheck.valid) {
+            return new DispatchResult({
+                request: new ExecutionRequest({
+                    skill_name: skill.name,
+                    execution_type: skill.execution_type,
+                    handler: skill.handler,
+                    timeout_seconds: skill.timeout_seconds,
+                    safety_mode: skill.safety_mode,
+                    allowed_tools: skill.allowed_tools,
+                    status: 'blocked',
+                    reason: `Automated skill declares an untrusted tool grant — ${toolCheck.errors.join('; ')}`,
+                }),
+                warnings: [],
+            });
+        }
+    } else if (skill.allowed_tools.length > 0) {
+        // Not silently ignored: an unregistered grant on a human-confirmed
+        // path is surfaced as a warning rather than a block.
+        warnings.push(...validate_tool_declarations(skill.allowed_tools).errors);
     }
 
     // Assisted/automated skill is ready

package/src/scripts/schemas/pack.schema.json

@@ -6,7 +6,7 @@
   "$comment": "Generated by scripts/generate_pack_manifests.py and validated on load by scripts/validate_pack_yaml.py. Schema introduced in road-to-6.0.0-D Phase 0 Step 2. `dependencies` is the artefact-level include graph (skills/rules the pack's commands reference); `requires` is the pack-level hard-dependency graph (must be acyclic — enforced by scripts/lint_pack_dependencies.py).",
   "type": "object",
   "additionalProperties": false,
-  "required": ["id", "version", "artefact_count"],
+  "required": ["id", "artefact_count"],
   "properties": {
     "id": {
       "type": "string",
@@ -58,10 +58,6 @@
     "trust_level_default": {
       "type": "string"
     },
-    "version": {
-      "type": "string",
-      "minLength": 1
-    },
     "artefact_count": {
       "type": "integer",
       "minimum": 0

package/src/scripts/schemas/rule.schema.json

@@ -63,14 +63,13 @@
         "properties": {
           "keyword": {"type": "string"},
           "phrase": {"type": "string"},
-          "intent": {"type": "string"},
           "file_pattern": {"type": "string"},
           "path_prefix": {"type": "string", "description": "Literal path-prefix match pattern the host evaluates against the file the agent is editing — NOT a file reference. The rewriter leaves it verbatim. Source-of-truth rules that must fire on edits under `.agent-src.uncondensed/` keep that prefix here (the prefix ban applies only to `load_context:` and body links — see road-to-path-fixes.md P2.2 / AI-Council 2026-05-06)."},
           "command": {"type": "string"},
           "reason": {"type": "string"}
         }
       },
-      "description": "Router activation triggers (Phase 3 of road-to-kernel-and-router.md). Forbidden on kernel rules, required on non-kernel rules. Schema: docs/contracts/rule-router.md."
+      "description": "Router activation triggers (Phase 3 of road-to-kernel-and-router.md). Forbidden on kernel rules, required on non-kernel rules. Five match keys: keyword, phrase, file_pattern, path_prefix, command. `intent` was removed — it never auto-matched at runtime and only gave rule authors false confidence that an activation path existed; additionalProperties:false now rejects it. Schema: docs/contracts/rule-router.md."
     },
     "routes_to": {
       "type": "array",

package/src/scripts/self_review_gate.ts

@@ -125,79 +125,21 @@ function changedLineCount(baseRef: string, files: string[], cwd: string = REPO_R
 }
 
 // ── Release-PR detection (road-to-feedback-9.2.0-followups Phase 3) ────
-/**
- * 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.
- */
-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;
-}
+//
+// Moved to `_lib/release_scope.ts` so the release-aware content checks reuse
+// this detector instead of re-deriving it (road-to-release-shape-honesty
+// Phase 1). Imported for local use AND re-exported — a bare `export … from`
+// would not bind the names in this module's scope. Public surface unchanged.
+import {
+    detectReleaseVersionFromGit,
+    pickPreviousTag,
+} from './_lib/release_scope.js';
+
+export {
+    detectReleaseVersion,
+    detectReleaseVersionFromGit,
+    pickPreviousTag,
+} from './_lib/release_scope.js';
 
 function listGitTags(cwd: string): string[] {
     const r = spawnSync('git', ['tag'], { cwd, encoding: 'utf8' });