@event4u/agent-config 9.13.0 → 9.14.0

package/dist/mcp/registry-manifest.json

@@ -1,6 +1,6 @@
 {
   "discovery": {
-    "artefact_count": 593,
+    "artefact_count": 594,
     "scanner_version": "c24312e116f8"
   },
   "generated_at": "2026-08-02",
@@ -9,7 +9,7 @@
     "homepage": "https://event4u-app.github.io/agent-config",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "9.13.0"
+    "version": "9.14.0"
   },
   "registries": [
     {

package/dist/mcp/server.json

@@ -9,12 +9,12 @@
       "transport": {
         "type": "stdio"
       },
-      "version": "9.13.0"
+      "version": "9.14.0"
     }
   ],
   "repository": {
     "source": "github",
     "url": "https://github.com/event4u-app/agent-config"
   },
-  "version": "9.13.0"
+  "version": "9.14.0"
 }

package/dist/mcp/server.mjs

@@ -14036,6 +14036,7 @@ __export(skill_linter_exports, {
   gather_all_candidate_files: () => gather_all_candidate_files,
   gather_candidate_files_under: () => gather_candidate_files_under,
   gather_changed_candidate_files: () => gather_changed_candidate_files,
+  last_changed_base_diff_ok: () => last_changed_base_diff_ok,
   last_changed_scope_reason: () => last_changed_scope_reason,
   lint_command: () => lint_command,
   lint_file: () => lint_file,
@@ -15984,6 +15985,7 @@ function gather_candidate_files_under(srcRoot) {
 function gather_changed_candidate_files(root, since) {
   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"],
@@ -15991,8 +15993,13 @@ function gather_changed_candidate_files(root, since) {
   ];
   try {
     let rawLines = [];
+    let first = true;
     for (const cmd of diffCommands) {
       const result = runCountedProbe(cmd[0], 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;
@@ -17398,6 +17405,25 @@ function _release_scope_requires_findings(root, since) {
   const scope = resolveContentLintScope({ cwd: root, since: since ?? null });
   return scope.isRelease && scope.previousTag !== null;
 }
+function _changed_filter_matches_head(root) {
+  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;
+}
 function main7(argv) {
   let args;
   try {
@@ -17442,20 +17468,26 @@ function main7(argv) {
 `);
       }
       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) {
-            process7.stderr.write(`\u274C  ${exc.message}
+        if (last_changed_base_diff_ok && _changed_filter_matches_head(root)) {
+          process7.stderr.write(
+            "\u2705  verified-empty release scope: the base-span diff ran cleanly and the corpus filter still matches tracked files at HEAD \u2014 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) {
+              process7.stderr.write(`\u274C  ${exc.message}
 `);
-            return 2;
+              return 2;
+            }
+            throw exc;
           }
-          throw exc;
         }
       }
       process7.stderr.write("No matching skill/rule files found.\n");
@@ -17635,7 +17667,7 @@ function _isCliEntry7() {
     return false;
   }
 }
-var _HERE4, REQUIRED_PERSONA_SECTIONS_CORE, REQUIRED_PERSONA_SECTIONS_SPECIALIST, VALID_PERSONA_TIERS, PERSONA_LINE_BUDGETS, REQUIRED_USERTYPE_SECTIONS, USERTYPE_LINE_BUDGET, VALID_PERSONA_WINGS, PERSONA_LINE_BUDGETS_BY_WING, REQUIRED_SKILL_SECTIONS, SECTION_ALIASES, RECOMMENDED_SKILL_SECTIONS, RULE_BAD_SIGNS, FRUGALITY_WRITER_SKILLS, FRUGALITY_CHARTER_RELPATH, FRUGALITY_CHARTER_INDEX_RULES, VAGUE_VALIDATION_PATTERNS, TRIGGER_WARNING_PATTERNS, ORDERED_STEP_PATTERN, SECTION_PATTERN, FRONTMATTER_PATTERN, DESCRIPTION_PATTERN, STATUS_PATTERN, REPLACED_BY_PATTERN, TIER_PATTERN, TYPE_PATTERN, SOURCE_PATTERN, SENIOR_RELATED_SKILLS_PATTERN, SENIOR_RELATED_WHEN_PATTERN, SENIOR_RELATED_WHEN_NOT_PATTERN, SENIOR_PROACTIVE_PATTERN, SENIOR_OUTPUT_PATTERN, H1_PATTERN, DOUBLE_BLANK_PATTERN, VALID_RULE_TYPES, VALID_RULE_SOURCES, ROUTER_ALLOWED_TRIGGER_KEYS, KERNEL_RULE_IDS, VALID_EXECUTION_TYPES, VALID_EXECUTION_HANDLERS, VALID_EXECUTION_SAFETY_MODES, VALID_EXECUTION_FIELDS, WING3_SPINE_SLOTS, CONTEXT_SPINE_INLINE_PATTERN, WING3_SAAS_URL_PATTERN, WING3_VENDOR_BLACKLIST, WING3_STACK_LOCKED_PATTERN, WING3_CHANNEL_TACTIC_PATTERN, WING4_SPINE_SLOTS, WING4_SAAS_URL_PATTERN, WING4_VENDOR_BLACKLIST, WING4_STAGE_AGNOSTIC_PATTERN, Issue, LintResult, _ROLE_CONTRACT_CANDIDATES, _ROLE_CONTRACT_SLUGS_CACHE, _ROLE_CONTRACT_REF_PATTERN, PROCEDURE_HEADING_PATTERN, COMMAND_FRONTMATTER_DELEGATION_KEYS, MD_LINK_PATTERN_G, NAME_PATTERN, DISABLE_MODEL_PATTERN, _INSPECT_VERB_PATTERN, last_changed_scope_reason, _INTERACTION_NAME_PATTERNS, _INTERACTION_CONTENT_KEYWORDS, _EXEC_FILE_SIGNALS, _EXEC_CONTENT_SIGNALS, _TASK_TYPE_SIGNALS, _VERIFICATION_TOOLS, _FRUGALITY_STANDARDS_PATTERN, _FRUGALITY_CHARTER_LINK_PATTERN, _MD_LINK_PATTERN, _MALICE_CRED_EXFIL, _MALICE_REMOTE_EXEC, _MALICE_FORCE_PUSH, _MALICE_CHMOD_SECRETS, _MALICE_SHELL_INJECT, _MALICE_PATTERNS, _NAG_UPDATE_CHECK, _NAG_STAY_CURRENT, _NAG_SELF_PROMO, _NAG_BEST_SKILL, _NAG_MUST_USE, _NAG_ALWAYS_USE, _NAG_PATTERNS, _OUTPUT_SCHEMA_KEY_PATTERN, _SCHEMA_ARTEFACT_TYPES, ArgError, isCliEntry2;
+var _HERE4, REQUIRED_PERSONA_SECTIONS_CORE, REQUIRED_PERSONA_SECTIONS_SPECIALIST, VALID_PERSONA_TIERS, PERSONA_LINE_BUDGETS, REQUIRED_USERTYPE_SECTIONS, USERTYPE_LINE_BUDGET, VALID_PERSONA_WINGS, PERSONA_LINE_BUDGETS_BY_WING, REQUIRED_SKILL_SECTIONS, SECTION_ALIASES, RECOMMENDED_SKILL_SECTIONS, RULE_BAD_SIGNS, FRUGALITY_WRITER_SKILLS, FRUGALITY_CHARTER_RELPATH, FRUGALITY_CHARTER_INDEX_RULES, VAGUE_VALIDATION_PATTERNS, TRIGGER_WARNING_PATTERNS, ORDERED_STEP_PATTERN, SECTION_PATTERN, FRONTMATTER_PATTERN, DESCRIPTION_PATTERN, STATUS_PATTERN, REPLACED_BY_PATTERN, TIER_PATTERN, TYPE_PATTERN, SOURCE_PATTERN, SENIOR_RELATED_SKILLS_PATTERN, SENIOR_RELATED_WHEN_PATTERN, SENIOR_RELATED_WHEN_NOT_PATTERN, SENIOR_PROACTIVE_PATTERN, SENIOR_OUTPUT_PATTERN, H1_PATTERN, DOUBLE_BLANK_PATTERN, VALID_RULE_TYPES, VALID_RULE_SOURCES, ROUTER_ALLOWED_TRIGGER_KEYS, KERNEL_RULE_IDS, VALID_EXECUTION_TYPES, VALID_EXECUTION_HANDLERS, VALID_EXECUTION_SAFETY_MODES, VALID_EXECUTION_FIELDS, WING3_SPINE_SLOTS, CONTEXT_SPINE_INLINE_PATTERN, WING3_SAAS_URL_PATTERN, WING3_VENDOR_BLACKLIST, WING3_STACK_LOCKED_PATTERN, WING3_CHANNEL_TACTIC_PATTERN, WING4_SPINE_SLOTS, WING4_SAAS_URL_PATTERN, WING4_VENDOR_BLACKLIST, WING4_STAGE_AGNOSTIC_PATTERN, Issue, LintResult, _ROLE_CONTRACT_CANDIDATES, _ROLE_CONTRACT_SLUGS_CACHE, _ROLE_CONTRACT_REF_PATTERN, PROCEDURE_HEADING_PATTERN, COMMAND_FRONTMATTER_DELEGATION_KEYS, MD_LINK_PATTERN_G, NAME_PATTERN, DISABLE_MODEL_PATTERN, _INSPECT_VERB_PATTERN, last_changed_scope_reason, last_changed_base_diff_ok, _INTERACTION_NAME_PATTERNS, _INTERACTION_CONTENT_KEYWORDS, _EXEC_FILE_SIGNALS, _EXEC_CONTENT_SIGNALS, _TASK_TYPE_SIGNALS, _VERIFICATION_TOOLS, _FRUGALITY_STANDARDS_PATTERN, _FRUGALITY_CHARTER_LINK_PATTERN, _MD_LINK_PATTERN, _MALICE_CRED_EXFIL, _MALICE_REMOTE_EXEC, _MALICE_FORCE_PUSH, _MALICE_CHMOD_SECRETS, _MALICE_SHELL_INJECT, _MALICE_PATTERNS, _NAG_UPDATE_CHECK, _NAG_STAY_CURRENT, _NAG_SELF_PROMO, _NAG_BEST_SKILL, _NAG_MUST_USE, _NAG_ALWAYS_USE, _NAG_PATTERNS, _OUTPUT_SCHEMA_KEY_PATTERN, _SCHEMA_ARTEFACT_TYPES, ArgError, isCliEntry2;
 var init_skill_linter = __esm({
   "src/scripts/skill_linter.ts"() {
     "use strict";
@@ -17811,6 +17843,7 @@ var init_skill_linter = __esm({
     DISABLE_MODEL_PATTERN = /^disable-model-invocation:\s*"?(true|false)"?\s*$/m;
     _INSPECT_VERB_PATTERN = /\b(?:inspect|examine|audit|survey|read|look\s+at|check|review|understand|identify|analyze|analyse|detect|gather|discover)\b/i;
     last_changed_scope_reason = "";
+    last_changed_base_diff_ok = false;
     _INTERACTION_NAME_PATTERNS = /skill-router|handoff|analysis-skill|skill-writing|skill-reviewer|model-recommendation|developer-like-execution|universal-project-analysis|interaction|autonomous-mode|feature-planning/i;
     _INTERACTION_CONTENT_KEYWORDS = [
       "handoff",

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.13.0",
+    "version": "9.14.0",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/scripts/_lib/exec_evidence.ts

@@ -47,6 +47,11 @@ export const ALLOWLIST_PREFIXES: readonly (readonly string[])[] = [
     ['skill_eval_coverage'],
     ['domain_soundness_status'],
     ['check_artefact_count_messaging'],
+    // `update_counts --check` re-derives every anchored number in the docs and
+    // exits non-zero on any disagreement — so its exit code IS the verdict for
+    // a published count, not merely evidence that some report exists. Read-only
+    // under `--check`; same deterministic, model-free class as its neighbours.
+    ['update_counts'],
     ['check_enforcement_coverage'],
     ['check_token_regression'],
     ['lint_agent_security'],

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/check_artefact_count_messaging.ts

@@ -33,7 +33,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { canonical_counts } from './check_command_count_messaging.js';
-import { count } from './update_counts.js';
+import { count, TARGETS } from './update_counts.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -164,6 +164,93 @@ export function scan_structured(
     return { findings, seen };
 }
 
+// --- Anchor-coverage pass (road-to-reproducible-artefact-counts) ----------
+//
+// The two gates used to overlap only by accident. This scanner flags any
+// count-shaped prose; `update_counts` rewrites a hand-written list of
+// anchors. Nothing asserted the second list covered the first, so positions
+// existed that the scanner could turn red and the generator could not fix —
+// the README Commands badge and the getting-started browse line drifted to
+// 191 against a canonical 192 exactly there, each explicitly left unanchored
+// to "avoid double-ownership". The reconciliation was a human's job, and the
+// gate's own advice said so ("run update_counts … OR correct the prose").
+//
+// This pass removes the human: every position this scanner can flag must be
+// rewritable by the generator, or be a generated file whose source is. A new
+// count-shaped sentence with no anchor now fails CI as a coverage gap.
+
+/**
+ * Scanner kind → the generator kinds that legitimately write it.
+ *
+ * One prose kind can have several canonical numbers and they are NOT
+ * interchangeable: "N commands" in prose means ACTIVE commands (total minus
+ * deprecation shims), and a scoped-projection sentence carries the projected
+ * skill count beside the catalog total. Anchoring an active-count position
+ * to the raw `commands` total would silently write the wrong number the day
+ * a command is superseded — which is why this is a mapping and not equality.
+ */
+const ANCHOR_KINDS: Readonly<Record<string, readonly string[]>> = {
+    skills: ['skills', 'skills_scoped'],
+    commands: ['commands', 'commands_active'],
+    rules: ['rules'],
+    guidelines: ['guidelines'],
+    personas: ['personas'],
+};
+
+/**
+ * Surfaces regenerated from an anchored source — exempt because fixing the
+ * source fixes them. Each entry names the generator, so the exemption stays
+ * falsifiable rather than becoming a place to hide drift.
+ */
+export const GENERATED_DOWNSTREAM: Readonly<Record<string, string>> = {
+    'docs/proof.md': 'generated from docs/CLAIMS.md by src/scripts/build_proof.ts',
+};
+
+export interface CoverageGap {
+    file: string;
+    line: number;
+    kind: string;
+    text: string;
+}
+
+/**
+ * Positions this scanner can flag that `update_counts` cannot rewrite.
+ *
+ * A position counts as anchored when some `TARGETS` pattern for the same
+ * file, bound to a compatible kind, matches the same line.
+ */
+export function anchor_coverage_gaps(root: string = ROOT): CoverageGap[] {
+    const anchorsByFile = new Map<string, ReadonlyArray<[string, string]>>();
+    for (const [rel, patterns] of TARGETS) {
+        anchorsByFile.set(rel, patterns);
+    }
+
+    const gaps: CoverageGap[] = [];
+    for (const rel of SURFACES) {
+        if (rel in GENERATED_DOWNSTREAM) continue;
+        const p = path.join(root, rel);
+        if (!fs.existsSync(p)) continue;
+        const lines = fs.readFileSync(p, 'utf-8').split('\n');
+        const anchors = anchorsByFile.get(rel) ?? [];
+        for (const [kind, pattern] of KIND_PATTERNS) {
+            const allowed = ANCHOR_KINDS[kind] ?? [kind];
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i]!;
+                const re = new RegExp(pattern.source, pattern.flags);
+                if (!re.test(line)) continue;
+                const anchored = anchors.some(
+                    ([raw, anchorKind]) =>
+                        allowed.includes(anchorKind) && new RegExp(raw).test(line),
+                );
+                if (!anchored) {
+                    gaps.push({ file: rel, line: i + 1, kind, text: line.trim().slice(0, 100) });
+                }
+            }
+        }
+    }
+    return gaps;
+}
+
 export function main(argv: readonly string[] = process.argv.slice(2)): number {
     const QUIET = argv.includes('--quiet');
     const expected: Record<string, number> = {};
@@ -213,29 +300,55 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
         }
     }
 
-    if (allFindings.length === 0 && inconsistent.length === 0) {
+    // Anchor coverage — every position this gate can flag must be a position
+    // `update_counts` can rewrite, so the two never need a human to reconcile.
+    const gaps = anchor_coverage_gaps();
+
+    if (allFindings.length === 0 && inconsistent.length === 0 && gaps.length === 0) {
         if (!QUIET) {
-            process.stdout.write('✅  All artefact-count prose in sync with source.\n');
+            process.stdout.write(
+                '✅  All artefact-count prose in sync with source, every position anchored.\n',
+            );
         }
         return 0;
     }
 
-    process.stdout.write(
-        `❌  Artefact-count messaging drift — ${allFindings.length} mismatch(es):\n`,
-    );
-    for (const f of allFindings) {
-        const tag = f.approx ? ' (approximation "~" not allowed on flagship surfaces)' : '';
+    if (allFindings.length > 0 || inconsistent.length > 0) {
+        process.stdout.write(
+            `❌  Artefact-count messaging drift — ${allFindings.length} mismatch(es):\n`,
+        );
+        for (const f of allFindings) {
+            const tag = f.approx ? ' (approximation "~" not allowed on flagship surfaces)' : '';
+            process.stdout.write(
+                `    ${f.file}:${f.line}: ${f.kind} says ${f.found}, expected ${f.expected}${tag}\n`,
+            );
+        }
+        for (const line of inconsistent) {
+            process.stdout.write(`    internal inconsistency — ${line}\n`);
+        }
         process.stdout.write(
-            `    ${f.file}:${f.line}: ${f.kind} says ${f.found}, expected ${f.expected}${tag}\n`,
+            '\nFix: run `./scripts-run src/scripts/update_counts` — every checked position\n' +
+                'is anchored, so the generator can write it. Never hand-type a count.\n',
         );
     }
-    for (const line of inconsistent) {
-        process.stdout.write(`    internal inconsistency — ${line}\n`);
+
+    if (gaps.length > 0) {
+        process.stdout.write(
+            `❌  Anchor-coverage gap — ${gaps.length} position(s) this gate checks but\n` +
+                '    `update_counts` cannot rewrite:\n',
+        );
+        for (const g of gaps) {
+            process.stdout.write(`    ${g.file}:${g.line}: ${g.kind} — ${g.text}\n`);
+        }
+        process.stdout.write(
+            '\nFix: add an anchor for each position to `TARGETS` in\n' +
+                '`src/scripts/update_counts.ts`, bound to the kind that position\n' +
+                'actually carries (`commands_active` for active-command mentions,\n' +
+                '`skills_scoped` for the projected-skill figure). If the file is\n' +
+                'generated from an anchored source, register it in\n' +
+                '`GENERATED_DOWNSTREAM` with the generator that produces it.\n',
+        );
     }
-    process.stdout.write(
-        '\nFix: run `./scripts-run src/scripts/update_counts` for anchored positions,\n' +
-            'or correct the prose to the canonical number (never hand-type a new one).\n',
-    );
     return 1;
 }
 

package/src/scripts/count_scoped_projection.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env tsx
+/**
+ * Emit the scoped-projection skill count — the number `docs/CLAIMS.md`
+ * publishes for the default install
+ * (road-to-reproducible-artefact-counts).
+ *
+ * The claim used to read "217 of 288 skills … with the counting method
+ * pinned in the benchmark doc", while that benchmark doc said 215 of 286.
+ * Both numbers were hand-typed, only one of them tracked the catalog, and
+ * the gap grew by one on every skill added because no gate could compare
+ * them. This script is the single derivation both now come from.
+ *
+ * It adds no counting mechanism of its own — that would be a second path
+ * free to disagree with the first, which is the defect, not the fix:
+ *
+ *   - the file set is `update_counts.iter_skills()`, the exact walk behind
+ *     the canonical `count('skills')`, so `projected + pruned === total`
+ *     holds by construction;
+ *   - the in/out predicate is `_lib/scoped_projection.is_pruned_under_scoped`,
+ *     the exact function `install.ts` applies when it prunes a real user's
+ *     tree, so the published number cannot describe a projection the
+ *     installer does not perform.
+ *
+ * `runtime.active_packs` is deliberately empty here: the claim is about the
+ * DEFAULT for a new install, and a fresh machine has no overlay. An operator
+ * who activates extra packs gets more skills than the claim states — the
+ * claim is a floor, and `--json` exposes `active_packs` so a reader can see
+ * the assumption rather than infer it.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/count_scoped_projection            # "217 of 288"
+ *   ./scripts-run src/scripts/count_scoped_projection --json
+ *   ./scripts-run src/scripts/count_scoped_projection --projected
+ *
+ * Exit codes: 0 ok · 1 the pack registry could not be read.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import {
+    scoped_projection_stats,
+    type ScopedProjectionStats,
+} from './_lib/scoped_projection.js';
+import { iter_skills, REPO_ROOT } from './update_counts.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+
+export type { ScopedProjectionStats };
+
+/** Partition the canonical skill catalog with the installer's own predicate. */
+export function stats(package_root: string = REPO_ROOT): ScopedProjectionStats {
+    return scoped_projection_stats(package_root, iter_skills());
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let s: ScopedProjectionStats;
+    try {
+        s = stats();
+    } catch (err) {
+        process.stderr.write(
+            `❌  scoped-projection count unavailable: ${(err as Error).message}\n` +
+                '    (src/config/discovery/packs.yml must exist and parse to a list)\n',
+        );
+        return 1;
+    }
+
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(s, null, 2)}\n`);
+        return 0;
+    }
+    if (argv.includes('--projected')) {
+        process.stdout.write(`${s.projected}\n`);
+        return 0;
+    }
+    if (argv.includes('--total')) {
+        process.stdout.write(`${s.total}\n`);
+        return 0;
+    }
+    process.stdout.write(`${s.projected} of ${s.total}\n`);
+    return 0;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main(process.argv.slice(2)));
+}