@event4u/agent-config 9.13.0 → 9.14.0

package/src/scripts/install.ts

@@ -74,6 +74,7 @@ import type * as YamlModule from 'yaml';
 import { build_merge_entries } from './_lib/json_pointers.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
+import * as scoped_projection from './_lib/scoped_projection.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
 import * as installed_tools from './_lib/installed_tools.js';
@@ -3344,89 +3345,16 @@ function _prune_lab_modules(
 // `requires` graph). Mirrors the core-only lab prune above — same
 // `_prune_modules_by` mechanics, a different predicate.
 
-/** `workspaces` values whose packs are ALWAYS active under `scoped` mode. */
-const SCOPED_ACTIVE_WORKSPACES: ReadonlySet<string> = new Set(['engineering', 'agent-config-maintainer']);
-
-interface PackRecord {
-    id: string;
-    workspaces: string[];
-    requires: string[];
-}
-
-/**
- * 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). The caller wraps this in a try/catch that restores the full
- * tree on any error instead.
- */
-function _load_packs_registry(package_root: string): PackRecord[] {
-    const vocab_path = path.join(package_root, 'src', 'config', 'discovery', 'packs.yml');
-    const data = yamlSafeLoad(readText(vocab_path));
-    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).
+/*
+ * The scoped-projection predicate lives in `_lib/scoped_projection.ts` so the
+ * installer and `count_scoped_projection.ts` — which produces the number the
+ * claims ledger publishes — run the SAME code rather than the same rule
+ * written twice. Re-exported under the existing private names to keep the
+ * prune tests' import surface unchanged.
  */
-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;
-}
+type PackRecord = scoped_projection.PackRecord;
+const _load_packs_registry = scoped_projection.load_packs_registry;
+const _compute_active_pack_ids = scoped_projection.compute_active_pack_ids;
 
 /**
  * Read the GLOBAL settings document that governs a global deploy, if one
@@ -3574,14 +3502,9 @@ function _prune_scoped_modules(
     deploy_results: Record<string, DeployResult>,
     active_ids: ReadonlySet<string>,
 ): [number, Record<string, DeployResult>] {
-    return _prune_modules_by(deploy_results, (p) => {
-        const packs = surface_tiers.frontmatter_packs(p);
-        if (packs.size === 0) return false;
-        for (const id of packs) {
-            if (active_ids.has(id)) return false;
-        }
-        return true;
-    });
+    return _prune_modules_by(deploy_results, (p) =>
+        scoped_projection.is_pruned_under_scoped(p, active_ids),
+    );
 }
 
 function install_global(

package/src/scripts/skill_linter.ts

@@ -2439,6 +2439,16 @@ export function gather_candidate_files_under(srcRoot: string): string[] {
  */
 export let last_changed_scope_reason = '';
 
+/**
+ * Whether the base-span diff (`base...HEAD`) itself ran cleanly.
+ *
+ * The verified-empty release outcome (see `main`) may only rest on an empty
+ * change set that was actually COMPUTED — a base diff that errored (missing
+ * tag object, corrupt ref) degrades to the worktree fallbacks and would
+ * otherwise be indistinguishable from a genuinely empty span.
+ */
+export let last_changed_base_diff_ok = false;
+
 /**
  * Candidate files changed against the resolved base.
  *
@@ -2454,6 +2464,7 @@ export let last_changed_scope_reason = '';
 export function gather_changed_candidate_files(root: string, since?: string | null): string[] {
     const scope = resolveContentLintScope({ cwd: root, since: since ?? null });
     last_changed_scope_reason = scope.reason;
+    last_changed_base_diff_ok = false;
     const diffCommands = [
         ['git', 'diff', '--name-only', `${scope.base}...HEAD`],
         ['git', 'diff', '--name-only', '--cached', 'HEAD'],
@@ -2461,10 +2472,15 @@ export function gather_changed_candidate_files(root: string, since?: string | nu
     ];
     try {
         let rawLines: string[] = [];
+        let first = true;
         for (const cmd of diffCommands) {
             // A truncated diff would silently shrink the change set — the same
             // degrade-to-zero shape this roadmap closes elsewhere.
             const result = runCountedProbe(cmd[0] as string, cmd.slice(1), { cwd: root });
+            if (first) {
+                last_changed_base_diff_ok = result.ok;
+                first = false;
+            }
             if (result.ok && result.stdout.trim()) {
                 rawLines = splitlines(result.stdout);
                 break;
@@ -4202,6 +4218,43 @@ function _release_scope_requires_findings(root: string, since?: string | null):
     return scope.isRelease && scope.previousTag !== null;
 }
 
+/**
+ * True when the `--changed` corpus filter still matches tracked files at HEAD.
+ *
+ * The discriminator between a DEAD scope and a VERIFIED-EMPTY release span.
+ * A release that touches no skill/rule file is a legitimate outcome — but only
+ * provably so when the exact predicate `gather_changed_candidate_files`
+ * applies to diff lines demonstrably still sees the corpus. Probing
+ * `git ls-files` with that same predicate means a moved projection root
+ * (the ADR-051 blindness class) fails this probe exactly as it would blind
+ * the diff — so "empty because the root moved" cannot masquerade as
+ * "empty because nothing changed".
+ */
+function _changed_filter_matches_head(root: string): boolean {
+    // Probes the canonical projection root only (ADR-051): a corpus that
+    // exists solely under a legacy path counts as dead, not alive.
+    const result = runCountedProbe('git', ['ls-files', '--', 'dist/agent-src'], { cwd: root });
+    if (!result.ok) {
+        return false;
+    }
+    for (const raw of splitlines(result.stdout)) {
+        const norm = raw.trim().replace(/\\/g, '/');
+        if (!norm || norm.includes('/evals/')) {
+            continue;
+        }
+        if (!norm.startsWith('dist/agent-src/') && !norm.includes('/dist/agent-src/')) {
+            continue;
+        }
+        if (
+            norm.endsWith('/SKILL.md') ||
+            (norm.endsWith('.md') && (norm.includes('/rules/') || norm.includes('/commands/')))
+        ) {
+            return true;
+        }
+    }
+    return false;
+}
+
 export function main(argv: string[]): number {
     let args: Args;
     try {
@@ -4244,25 +4297,39 @@ export function main(argv: string[]): number {
                 process.stdout.write(`${format_json([])}\n`);
             }
             // A release PR that resolved a real tag span and still matched
-            // nothing has not passed — it examined nothing. Mirrors the
-            // scan-scope regime the other gates already adopted
+            // nothing needs a discriminator: DEAD scope (the diff errored, or
+            // the corpus filter no longer matches anything at HEAD — the
+            // ADR-051 moved-root blindness) fails; VERIFIED-EMPTY (the base
+            // diff ran cleanly AND the filter provably still sees tracked
+            // corpus files) is a legitimate release that simply changed no
+            // skill/rule — failing it would red every scripts-/docs-only
+            // release forever. Mirrors the scan-scope regime
             // (`_lib/scan_scope.ts`; exit 2, as `check_iron_law_prominence`).
             // Ordinary PRs keep the historical exit 0: a change set with no
             // skill or rule in it is a legitimate empty scope, not a dead one.
             if (args.changed && _release_scope_requires_findings(root, args.since)) {
-                try {
-                    assertScanned({
-                        gate: 'skill_linter --changed (release PR)',
-                        scanned: 0,
-                        units: 'skill/rule files',
-                        roots: [last_changed_scope_reason],
-                    });
-                } catch (exc) {
-                    if (exc instanceof DeadScopeError) {
-                        process.stderr.write(`❌  ${exc.message}\n`);
-                        return 2;
+                if (last_changed_base_diff_ok && _changed_filter_matches_head(root)) {
+                    process.stderr.write(
+                        '✅  verified-empty release scope: the base-span diff ran cleanly and ' +
+                            'the corpus filter still matches tracked files at HEAD — this ' +
+                            'release genuinely changes no skill/rule file. The gate is alive, ' +
+                            'not blind.\n',
+                    );
+                } else {
+                    try {
+                        assertScanned({
+                            gate: 'skill_linter --changed (release PR)',
+                            scanned: 0,
+                            units: 'skill/rule files',
+                            roots: [last_changed_scope_reason],
+                        });
+                    } catch (exc) {
+                        if (exc instanceof DeadScopeError) {
+                            process.stderr.write(`❌  ${exc.message}\n`);
+                            return 2;
+                        }
+                        throw exc;
                     }
-                    throw exc;
                 }
             }
             process.stderr.write('No matching skill/rule files found.\n');

package/src/scripts/update_counts.ts

@@ -26,6 +26,8 @@ import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { artefact_roots, iter_commands } from './_lib/agent_src.js';
+import { scoped_projection_stats } from './_lib/scoped_projection.js';
+import { canonical_counts } from './check_command_count_messaging.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // _HERE === <repo>/src/scripts/update_counts.ts ; the retired Python implementation derives
@@ -77,7 +79,48 @@ function _exists(p: string): boolean {
     }
 }
 
+/**
+ * Every `SKILL.md` the canonical `count('skills')` counts, as absolute paths.
+ *
+ * Exported so `count_scoped_projection.ts` partitions the SAME file set the
+ * ledger's total is derived from. That is what makes the published pair
+ * ("N of M skills") coherent by construction: `projected + pruned === M`
+ * cannot drift, because there is one walk, not two.
+ */
+export function* iter_skills(): Generator<string> {
+    const seen = new Set<string>();
+    for (const root of artefact_roots()) {
+        const subdir = path.join(root, 'skills');
+        if (!_exists(subdir)) {
+            continue;
+        }
+        for (const f of _rglob(subdir, (n) => n === 'SKILL.md')) {
+            const rel = path.relative(root, f).split(path.sep).join('/');
+            if (seen.has(rel)) continue;
+            seen.add(rel);
+            yield f;
+        }
+    }
+}
+
 export function count(kind: string): number {
+    if (kind === 'commands_active') {
+        // Commands MINUS deprecation shims — the number the hero badge and the
+        // "Browse all N active commands" line carry, and the one prose
+        // mentions resolve to. Distinct from `commands` (raw file count):
+        // they are equal only while the shim set is empty, so anchoring an
+        // active-count position to `commands` would rewrite it to the wrong
+        // number the moment a command is superseded.
+        const [, , active] = canonical_counts();
+        return active;
+    }
+    if (kind === 'skills_scoped') {
+        // Skills a DEFAULT `projection.mode: scoped` install deploys. Derived
+        // by the installer's own prune predicate over the same walk the
+        // canonical `skills` total uses, so the published pair
+        // ("N of M skills") cannot drift apart. See count_scoped_projection.ts.
+        return scoped_projection_stats(REPO_ROOT, iter_skills()).projected;
+    }
     if (kind === 'router_rules') {
         // Routed rule entries in the compiled router (kernel + tier_1 +
         // tier_2). Read from dist/router.json — the artifact hosts consume —
@@ -119,19 +162,19 @@ export function count(kind: string): number {
         }
         return total;
     }
+    if (kind === 'skills') {
+        // Single walk, shared with count_scoped_projection.ts — see iter_skills.
+        for (const _ of iter_skills()) {
+            total += 1;
+        }
+        return total;
+    }
     for (const root of artefact_roots()) {
         const subdir = path.join(root, kind);
         if (!_exists(subdir)) {
             continue;
         }
-        if (kind === 'skills') {
-            for (const f of _rglob(subdir, (n) => n === 'SKILL.md')) {
-                const rel = path.relative(root, f).split(path.sep).join('/');
-                if (seen.has(rel)) continue;
-                seen.add(rel);
-                total += 1;
-            }
-        } else if (kind === 'personas') {
+        if (kind === 'personas') {
             // personas live as flat .md files, README excluded
             for (const f of _glob(subdir, (n) => n.endsWith('.md'))) {
                 if (path.basename(f) === 'README.md') continue;
@@ -164,6 +207,12 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
             // badge is owned by check_command_count_messaging.
             ['(/badge/Skills-)(\\d+)(-)', 'skills'],
             ['(/badge/Rules-)(\\d+)(-)', 'rules'],
+            // The Commands badge WAS left to check_command_count_messaging
+            // alone ("avoids double-ownership"). Nothing generated it, so it
+            // drifted to 191 against a canonical 192 and only the checker
+            // noticed — the exact gap this roadmap closes. Generator writes,
+            // checker verifies: that IS the ownership split, not a conflict.
+            ['(/badge/Commands-)(\\d+)(-)', 'commands_active'],
             ['(/badge/Guidelines-)(\\d+)(-)', 'guidelines'],
             ['(/badge/Personas-)(\\d+)(-)', 'personas'],
         ],
@@ -177,8 +226,22 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
             ['(- claim: )(\\d+)( skills\\.)', 'skills'],
             ['(- claim: )(\\d+)( commands\\.)', 'commands'],
             ['(- claim: )(\\d+)( governed rules\\.)', 'rules'],
+            // The scoped-projection claim: BOTH halves of "N of M skills".
+            // `M` was scanner-checked but generator-blind (a maintainer
+            // hand-edited it on every skill addition); `N` was guarded by
+            // nothing at all and had drifted 2 from the benchmark doc the
+            // claim names as its own method.
+            ['(installs ships )(\\d+)( of )', 'skills_scoped'],
+            ['( of )(\\d+)( skills \\(untagged core)', 'skills'],
+            // "14 of 111 governed rules" — the total was scanner-checked and
+            // generator-blind for the same reason.
+            ['( of )(\\d+)( governed rules \\()', 'rules'],
         ],
     ],
+    [
+        'docs/command-flows.md',
+        [['(\\*\\*)(\\d+)( commands\\*\\*)', 'commands_active']],
+    ],
     [
         'docs/getting-started-by-role.md',
         [
@@ -206,6 +269,11 @@ export const TARGETS: ReadonlyArray<[string, ReadonlyArray<[string, string]>]> =
         'docs/getting-started.md',
         [
             ['(automatically by )(\\d+)( rules)', 'rules'],
+            // Was deliberately unsynced to avoid double-ownership with
+            // check_command_count_messaging; it drifted to 191 as a result.
+            // Now generated from `commands_active` — the SAME canonical the
+            // checker compares against, so the two cannot disagree.
+            ['(Browse all )(\\d+)( active commands)', 'commands_active'],
             // NOTE: the "Browse all N active commands" line here carries the
             // *active* command count and is owned by
             // check_command_count_messaging.py — intentionally not synced
@@ -254,7 +322,16 @@ export function apply_to_text(
     return [new_text, drifts];
 }
 
-const KINDS = ['skills', 'rules', 'commands', 'guidelines', 'personas', 'router_rules'] as const;
+const KINDS = [
+    'skills',
+    'skills_scoped',
+    'rules',
+    'commands',
+    'commands_active',
+    'guidelines',
+    'personas',
+    'router_rules',
+] as const;
 
 function parse_args(argv: readonly string[]): { check: boolean } {
     const args = { check: false };
@@ -282,8 +359,10 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         counts[k] = count(k);
     }
     process.stdout.write(
-        `📊  Truth: skills=${counts['skills']} rules=${counts['rules']} ` +
-            `commands=${counts['commands']} guidelines=${counts['guidelines']} ` +
+        `📊  Truth: skills=${counts['skills']} skills_scoped=${counts['skills_scoped']} ` +
+            `rules=${counts['rules']} commands=${counts['commands']} ` +
+            `commands_active=${counts['commands_active']} ` +
+            `guidelines=${counts['guidelines']} ` +
             `personas=${counts['personas']} router_rules=${counts['router_rules']}\n`,
     );