@event4u/agent-config 9.12.0 → 9.14.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/_lib/scoped_projection.ts

@@ -0,0 +1,212 @@
+/**
+ * The scoped-projection predicate — ONE implementation, two callers.
+ *
+ * `projection.mode: scoped` narrows a GLOBAL deploy to the active profile's
+ * packs. Two places need to know exactly which skills survive that prune:
+ *
+ *   1. `install.ts` — which artefacts it actually writes to the user's tree.
+ *   2. `count_scoped_projection.ts` — the number the claims ledger publishes.
+ *
+ * Before this module those were the same rule written once and *typed* a
+ * second time into `docs/CLAIMS.md`. The published pair drifted from the
+ * benchmark doc it cited as its own method (217/288 vs 215/286) and grew by
+ * one on every skill added, because nothing could compare them. The fix is
+ * not a second counter — a second counting path that disagrees with the
+ * first is the failure this replaces. It is this module: the installer and
+ * the counter call the same functions, so a divergence is impossible rather
+ * than merely unlikely.
+ *
+ * Consumers: `install.ts` (the prune itself) and `count_scoped_projection.ts`
+ * (the published number).
+ */
+
+import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
+import * as path from 'node:path';
+import type * as YamlModule from 'yaml';
+
+import * as surface_tiers from './surface_tiers.js';
+
+/**
+ * ESM-safe `require`. A bare `require('yaml')` is `undefined` under tsx (the
+ * runner every `./scripts-run` gate uses), so the older lazy-require pattern
+ * elsewhere in this tree degrades to "no yaml" silently. `createRequire`
+ * keeps the load lazy — `yaml` stays out of the installer bundle's static
+ * graph — while actually resolving.
+ */
+const _require = createRequire(import.meta.url);
+
+/** `workspaces` values whose packs are ALWAYS active under `scoped` mode. */
+export const SCOPED_ACTIVE_WORKSPACES: ReadonlySet<string> = new Set([
+    'engineering',
+    'agent-config-maintainer',
+]);
+
+export interface PackRecord {
+    id: string;
+    workspaces: string[];
+    requires: string[];
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Lazy YAML safe_load mirroring PyYAML (version 1.1); `null` when absent. */
+function yamlSafeLoad(text: string): unknown {
+    let YAML: typeof YamlModule;
+    try {
+        YAML = _require('yaml') as typeof YamlModule;
+    } catch {
+        return null;
+    }
+    try {
+        return YAML.parse(text, { version: '1.1' }) ?? null;
+    } catch {
+        return null;
+    }
+}
+
+/** Repo-relative location of the pack vocabulary. */
+export const PACKS_YML_REL = path.join('src', 'config', 'discovery', 'packs.yml');
+
+/**
+ * Parse `src/config/discovery/packs.yml` into `{id, workspaces, requires}`
+ * records. `requires` falls back to the legacy `requires_hint` field name
+ * when `requires` is absent.
+ *
+ * Deliberately THROWS on a missing file or a parse result that is not a
+ * list — an empty active-pack set would be the LEAST safe fallback here
+ * (it would prune every tagged artefact, the opposite of the fail-safe
+ * contract). Callers wrap this in a try/catch that restores the full tree
+ * on any error instead.
+ */
+export function load_packs_registry(package_root: string): PackRecord[] {
+    const vocab_path = path.join(package_root, PACKS_YML_REL);
+    const data = yamlSafeLoad(fs.readFileSync(vocab_path, 'utf-8'));
+    if (!Array.isArray(data)) {
+        throw new Error(`packs.yml did not parse to a list: ${vocab_path}`);
+    }
+    const out: PackRecord[] = [];
+    for (const entry of data) {
+        if (!isPlainObject(entry)) continue;
+        const id = entry['id'];
+        if (typeof id !== 'string' || id === '') continue;
+        const workspaces_raw = entry['workspaces'];
+        const workspaces = Array.isArray(workspaces_raw)
+            ? workspaces_raw.filter((w): w is string => typeof w === 'string')
+            : [];
+        const requires_raw = entry['requires'] ?? entry['requires_hint'];
+        const requires = Array.isArray(requires_raw)
+            ? requires_raw.filter((r): r is string => typeof r === 'string')
+            : [];
+        out.push({ id, workspaces, requires });
+    }
+    return out;
+}
+
+/**
+ * Active pack id set for `scoped` mode: every pack whose `workspaces`
+ * intersects `SCOPED_ACTIVE_WORKSPACES`, unioned with `runtime_active_packs`,
+ * expanded over the `requires` graph (transitive closure).
+ */
+export function compute_active_pack_ids(
+    packs: readonly PackRecord[],
+    runtime_active_packs: readonly string[],
+): Set<string> {
+    const by_id = new Map<string, PackRecord>();
+    for (const p of packs) by_id.set(p.id, p);
+
+    const active = new Set<string>();
+    for (const p of packs) {
+        if (p.workspaces.some((w) => SCOPED_ACTIVE_WORKSPACES.has(w))) {
+            active.add(p.id);
+        }
+    }
+    for (const id of runtime_active_packs) {
+        active.add(id);
+    }
+
+    let frontier = [...active];
+    while (frontier.length > 0) {
+        const next: string[] = [];
+        for (const id of frontier) {
+            const rec = by_id.get(id);
+            if (rec === undefined) continue;
+            for (const dep of rec.requires) {
+                if (!active.has(dep)) {
+                    active.add(dep);
+                    next.push(dep);
+                }
+            }
+        }
+        frontier = next;
+    }
+    return active;
+}
+
+/**
+ * The prune predicate itself: `true` when this artefact is DROPPED under
+ * `scoped`. Untagged artefacts (empty `packs:` frontmatter) are core/shared
+ * and always kept; a tagged artefact survives iff its tags intersect the
+ * active set.
+ */
+export function is_pruned_under_scoped(md_path: string, active_ids: ReadonlySet<string>): boolean {
+    const packs = surface_tiers.frontmatter_packs(md_path);
+    if (packs.size === 0) return false;
+    for (const id of packs) {
+        if (active_ids.has(id)) return false;
+    }
+    return true;
+}
+
+export interface ScopedProjectionStats {
+    /** Skills a default `projection.mode: scoped` install deploys. */
+    projected: number;
+    /** Every skill in the catalog — identical to canonical `count('skills')`. */
+    total: number;
+    /** `total - projected`; the reduction the claim reports. */
+    pruned: number;
+    /** Pack ids active by default, sorted — the requires-closure result. */
+    active_packs: string[];
+    /** The workspaces whose packs are always on under `scoped`. */
+    workspaces: string[];
+}
+
+/**
+ * Partition a skill catalog with the installer's own predicate.
+ *
+ * The caller supplies the file set — in practice always
+ * `update_counts.iter_skills()`, the walk behind the canonical
+ * `count('skills')`, so `projected + pruned === total` holds by
+ * construction. Taking it as a parameter (rather than importing
+ * `update_counts` here) keeps this module free of a cycle: `update_counts`
+ * imports it, not the other way round.
+ *
+ * `runtime_active_packs` defaults to empty: the published claim is about the
+ * DEFAULT for a new install, and a fresh machine has no overlay.
+ */
+export function scoped_projection_stats(
+    package_root: string,
+    skills: Iterable<string>,
+    runtime_active_packs: readonly string[] = [],
+): ScopedProjectionStats {
+    const active = compute_active_pack_ids(load_packs_registry(package_root), runtime_active_packs);
+
+    let projected = 0;
+    let total = 0;
+    for (const skill of skills) {
+        total += 1;
+        if (!is_pruned_under_scoped(skill, active)) {
+            projected += 1;
+        }
+    }
+
+    return {
+        projected,
+        total,
+        pruned: total - projected,
+        active_packs: [...active].sort(),
+        workspaces: [...SCOPED_ACTIVE_WORKSPACES].sort(),
+    };
+}

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);