@event4u/agent-config 9.12.0 → 9.13.0

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`,
+    };
+}

package/src/scripts/ai_council/stance_tally.ts

@@ -51,7 +51,14 @@ export interface StanceTallyResult {
     consensus: OptionTally | null; // the option clearing the threshold, or null
     split: boolean; // true when no option clears the threshold
     abstain_count: number;
-    needs_repair: string[]; // members whose stance line was missing/unparseable
+    /**
+     * Members whose stance line was missing or unparseable. They COUNT toward
+     * `w_total` (they responded) and back no option — see the
+     * refusal-preservation invariant in `tally_stances`. Surfaced by
+     * `render_vote_tally` so a shrunken-signal quorum is visible rather than
+     * merely computed.
+     */
+    needs_repair: string[];
 }
 
 // Tolerant of whitespace and case; requires the three explicit fields in order.
@@ -150,7 +157,23 @@ export function tally_stances(
         parsed.push({ member, ...p });
     }
 
-    const w_total = parsed.length; // base weight 1.0 each, abstain included
+    // ── Refusal-preservation invariant (road-to-governance-invariants P2) ──
+    //
+    // Selection may never rank an option higher *because* a member refused
+    // less. A safety refusal is not a scored-down property, and — measured by
+    // spike S0.1 — the way this engine could be steered was not a weight but a
+    // DENOMINATOR: `w_total` once counted only members whose stance line
+    // parsed, so a refusal phrased as prose ("I will not answer this") vanished
+    // from the quorum and made consensus EASIER. Same two backers, margin
+    // −0.25 and no consensus when the refusal parsed as an abstention;
+    // +0.4167 and consensus when it did not parse. Δ 0.6667, outcome flipped.
+    //
+    // The fix is structural rather than a new gate: a member who RESPONDED
+    // counts toward the quorum whether or not its stance line parsed. It backs
+    // no option either way, so an unparseable response now behaves exactly like
+    // an abstention — the fail-safe direction. Members who never responded are
+    // dropped upstream (`!r.error`) and are correctly absent from `members`.
+    const w_total = parsed.length + needs_repair.length; // responded, abstain + unparseable included
     const threshold = CONSENSUS_FRACTION * w_total;
     let abstain_count = 0;
 
@@ -208,6 +231,18 @@ export function render_vote_tally(result: StanceTallyResult): string {
     if (result.abstain_count > 0) {
         lines.push(`- abstain — ${result.abstain_count} member(s) (raises the bar)`);
     }
+    // Refusal divergence, as an OBSERVATION and never a selection input
+    // (road-to-governance-invariants P2). A member whose stance did not parse
+    // still counts toward the quorum; saying so here is what makes a shrunken
+    // signal visible to a reader instead of merely present in a struct field
+    // no caller reads. Nothing in the tally consumes this string.
+    if (result.needs_repair.length > 0) {
+        lines.push(
+            `- unparsed — ${result.needs_repair.length} member(s) responded without a ` +
+                `readable stance (${result.needs_repair.join(', ')}); counted in the ` +
+                'quorum, backing nothing',
+        );
+    }
     lines.push(`Threshold: ⅔ × ${result.w_total} = ${result.threshold.toFixed(2)}`);
     lines.push(
         result.consensus !== null

package/src/scripts/audit_auto_rules.ts

@@ -136,14 +136,14 @@ export function _split_frontmatter(text: string): [Record<string, Json>, string]
 interface TriggerSummary {
     path_prefixes: string[];
     keywords: string[];
-    intents: string[];
+    phrases: string[];
 }
 
 /** Mirror `_trigger_summary`. */
 export function _trigger_summary(triggers: Json): TriggerSummary {
     const paths: string[] = [];
     const keywords: string[] = [];
-    const intents: string[] = [];
+    const phrases: string[] = [];
     const list: Json[] = Array.isArray(triggers) ? triggers : [];
     for (const entry of list) {
         if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
@@ -156,11 +156,11 @@ export function _trigger_summary(triggers: Json): TriggerSummary {
         if ('keyword' in e) {
             keywords.push(String(e['keyword']));
         }
-        if ('intent' in e) {
-            intents.push(String(e['intent']));
+        if ('phrase' in e) {
+            phrases.push(String(e['phrase']));
         }
     }
-    return { path_prefixes: paths, keywords, intents };
+    return { path_prefixes: paths, keywords, phrases };
 }
 
 interface RuleEntry {
@@ -208,7 +208,7 @@ export function collect(): RuleEntry[] {
             description_chars: pyLen(desc),
             triggers,
             trigger_count:
-                triggers.path_prefixes.length + triggers.keywords.length + triggers.intents.length,
+                triggers.path_prefixes.length + triggers.keywords.length + triggers.phrases.length,
             routes_to,
             body_chars: pyLen(body),
             file_chars: pyLen(text),
@@ -292,7 +292,7 @@ export function render_markdown(rules: RuleEntry[]): string {
         const triggers =
             `${r.triggers.path_prefixes.length}p / ` +
             `${r.triggers.keywords.length}k / ` +
-            `${r.triggers.intents.length}i`;
+            `${r.triggers.phrases.length}ph`;
         const routes = r.routes_to.map((x) => String(x)).join(', ') || '—';
         lines.push(
             `| ${i} | \`${r.name}\` | ${_pyTruthy(r.tier) ? String(r.tier) : '—'} | ` +
@@ -302,7 +302,7 @@ export function render_markdown(rules: RuleEntry[]): string {
         i++;
     }
     lines.push('');
-    lines.push('Trigger key: `Np` = path-prefix, `Nk` = keyword, `Ni` = intent.');
+    lines.push('Trigger key: `Np` = path-prefix, `Nk` = keyword, `Nph` = phrase.');
     lines.push('');
     return lines.join('\n');
 }
@@ -393,7 +393,7 @@ function _ruleToJson(r: RuleEntry): Record<string, Json> {
         triggers: {
             path_prefixes: r.triggers.path_prefixes,
             keywords: r.triggers.keywords,
-            intents: r.triggers.intents,
+            phrases: r.triggers.phrases,
         },
         trigger_count: r.trigger_count,
         routes_to: r.routes_to,

package/src/scripts/audit_likelihood.ts

@@ -16,7 +16,7 @@
  * For every auto-rule from `agents/reports/auto-rules-audit.json`:
  *
  * 1. Build a token set from `description`, `triggers[].keyword`,
- *    `triggers[].intent`, and the rule name itself.
+ *    `triggers[].phrase`, and the rule name itself.
  * 2. Index a corpus of skills (`SKILL.md`), contexts, guidelines, and
  *    command files.
  * 3. Score `corpus_hits = sum(1 for token in tokens if token in corpus)`.
@@ -197,9 +197,9 @@ function _ruleTokens(rule: Json): Set<string> {
     add(tokens(String(rule['name'] ?? '').replaceAll('-', ' ')));
     const trig = rule['triggers'] ?? {};
     const kw: Json[] = Array.isArray(trig['keywords']) ? trig['keywords'] : [];
-    const intents: Json[] = Array.isArray(trig['intents']) ? trig['intents'] : [];
+    const phrases: Json[] = Array.isArray(trig['phrases']) ? trig['phrases'] : [];
     add(tokens(kw.map((x) => String(x)).join(' ')));
-    add(tokens(intents.map((x) => String(x)).join(' ')));
+    add(tokens(phrases.map((x) => String(x)).join(' ')));
     return out;
 }
 

package/src/scripts/audit_overlap.ts

@@ -54,7 +54,7 @@ const _ALL_DIGITS = /^[0-9]+$/;
 interface RuleTriggers {
     path_prefixes: string[];
     keywords: string[];
-    intents: string[];
+    phrases: string[];
 }
 
 interface RuleEntry {
@@ -194,7 +194,7 @@ function analyse(rules: RuleEntry[]): Pair[] {
         for (const x of keyword_set(r.triggers.keywords.join(' '))) {
             kw.add(x);
         }
-        for (const x of keyword_set(r.triggers.intents.join(' '))) {
+        for (const x of keyword_set(r.triggers.phrases.join(' '))) {
             kw.add(x);
         }
         keywords.push(kw);