@event4u/agent-config 14.18.0 → 14.19.0

package/src/scripts/measure_sibling_naming.ts

@@ -0,0 +1,150 @@
+/**
+ * measure_sibling_naming — how many skill descriptions name another skill.
+ *
+ * `road-to-one-motion-authority` step 5.2. An inbox census claimed "44/299
+ * descriptions name a sibling" and shipped no definition of *naming* and no
+ * script, so the figure could be neither reproduced nor refuted. A companion
+ * claim of "218/299 bodies" reproduced under no reading of the tree at all.
+ * This script exists so the next such number is falsifiable.
+ *
+ * WHAT "NAMES A SIBLING" MEANS HERE, stated because the census did not.
+ *
+ * A description names a sibling when it contains the exact `name:` value of a
+ * DIFFERENT shipped skill, delimited so it is not a fragment of a longer
+ * identifier. `\b` is not enough: it puts a boundary between `brand` and the
+ * hyphen in `brand-identity`, so a bare `\b`-matched `brand` would score every
+ * mention of `brand-identity` as naming `brand` too. The delimiter here is
+ * "not `[A-Za-z0-9-]`" on both sides, which is the smallest rule that keeps
+ * `mcp` out of `mcp-builder` and `laravel` out of `laravel-dto`.
+ *
+ * A skill naming ITSELF does not count — that is a description, not a pointer.
+ *
+ * WHAT THE NUMBER IS AND IS NOT.
+ *
+ * A KNOWN AND UNFIXABLE FALSE POSITIVE, named rather than left for a reader to
+ * find: some skill names are ordinary English words, so a description can score
+ * a match by accident. `canvas-design` scores `brand` on the phrase "brand
+ * assets", which is not a pointer to the `brand` skill. Excluding short or
+ * common names would trade this for a false negative on the skills whose names
+ * really are those words, and there is no rule that gets both. The count is
+ * therefore an upper bound; the per-skill list is printed so a reader can see
+ * which matches are real.
+ *
+ * It is a count of descriptions that mention a sibling by name. It is NOT a
+ * measure of routing quality: a description can name a sibling uselessly, and a
+ * description that names none can be perfectly routable on its own keywords.
+ * The reason the count is worth having is narrower — the router reads
+ * descriptions and nothing else, so a family whose members never point at each
+ * other is a family the router cannot traverse.
+ *
+ * Exit code is 0 unless `--min <n>` is given and the count falls below it.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, '..', '..');
+const SKILLS_REL = path.join('src', 'skills');
+
+export interface SkillRecord { name: string; description: string }
+
+/** Read `name:` and `description:` out of a SKILL.md frontmatter block. */
+export function parseSkill(text: string): SkillRecord | null {
+    if (!text.startsWith('---')) return null;
+    const end = text.indexOf('\n---', 3);
+    if (end < 0) return null;
+    const fm = text.slice(3, end);
+    const name = /^name:\s*(.+)$/m.exec(fm)?.[1]?.trim() ?? '';
+    let description = /^description:\s*(.+)$/m.exec(fm)?.[1]?.trim() ?? '';
+    if ((description.startsWith('"') && description.endsWith('"'))
+        || (description.startsWith("'") && description.endsWith("'"))) {
+        description = description.slice(1, -1);
+    }
+    description = description.replace(/\\"/g, '"');
+    if (name === '') return null;
+    return { name, description };
+}
+
+export function loadSkills(root: string): SkillRecord[] {
+    const dir = path.join(root, SKILLS_REL);
+    if (!fs.existsSync(dir)) return [];
+    const out: SkillRecord[] = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const file = path.join(dir, entry.name, 'SKILL.md');
+        if (!fs.existsSync(file)) continue;
+        const rec = parseSkill(fs.readFileSync(file, 'utf-8'));
+        if (rec !== null) out.push(rec);
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Identifier-boundary containment: `mcp` is not found inside `mcp-builder`. */
+export function namesIdentifier(haystack: string, id: string): boolean {
+    let from = 0;
+    for (;;) {
+        const i = haystack.indexOf(id, from);
+        if (i < 0) return false;
+        const before = i === 0 ? '' : haystack[i - 1] ?? '';
+        const after = haystack[i + id.length] ?? '';
+        const isPart = (c: string): boolean => c !== '' && /[A-Za-z0-9-]/.test(c);
+        if (!isPart(before) && !isPart(after)) return true;
+        from = i + 1;
+    }
+}
+
+/** For each skill, the OTHER skills its description names. Sorted, deterministic. */
+export function siblingsNamed(skills: readonly SkillRecord[]): Map<string, string[]> {
+    const names = skills.map((s) => s.name);
+    const out = new Map<string, string[]>();
+    for (const s of skills) {
+        const hits = names
+            .filter((n) => n !== s.name && namesIdentifier(s.description, n))
+            .sort();
+        out.set(s.name, hits);
+    }
+    return out;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const rootFlag = argv.indexOf('--root');
+    const root = rootFlag >= 0 ? (argv[rootFlag + 1] ?? REPO_ROOT) : REPO_ROOT;
+    const minFlag = argv.indexOf('--min');
+    const min = minFlag >= 0 ? Number(argv[minFlag + 1]) : null;
+    const json = argv.includes('--json');
+
+    const skills = loadSkills(root);
+    const map = siblingsNamed(skills);
+    const naming = [...map].filter(([, v]) => v.length > 0);
+
+    if (json) {
+        process.stdout.write(`${JSON.stringify({
+            total: skills.length,
+            naming: naming.length,
+            entries: Object.fromEntries(naming),
+        }, null, 1)}\n`);
+    } else {
+        process.stdout.write(`scanned: ${String(skills.length)}\n`);
+        process.stdout.write(
+            `sibling-naming: ${String(naming.length)}/${String(skills.length)} description(s) name at least one other shipped skill\n\n`,
+        );
+        for (const [name, hits] of naming) {
+            process.stdout.write(`  ${name} → ${hits.join(', ')}\n`);
+        }
+    }
+
+    if (min !== null && Number.isFinite(min) && naming.length < min) {
+        process.stderr.write(
+            `\n❌  measure_sibling_naming: ${String(naming.length)} below the declared floor of ${String(min)}\n`,
+        );
+        return 1;
+    }
+    return 0;
+}
+
+if (process.argv[1] !== undefined) {
+    const invoked = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (invoked === import.meta.url) process.exitCode = main();
+}

package/src/scripts/redact_hook_capture.ts

@@ -4,7 +4,7 @@
  *
  * Ported from the retired Python `redact_hook_capture.py` (Phase 8 / Wave 8g).
  *
- * Reads JSON capture files written by `dispatch_hook.py` (when
+ * Reads JSON capture files written by `dispatch_hook.ts` (when
  * `AGENT_HOOK_CAPTURE_DIR` is set) and produces a redacted version
  * suitable for pasting into the verified-platforms roadmap.
  *

package/src/scripts/report_skill_activation.ts

@@ -44,7 +44,19 @@
  * count descriptions against bare names. Until that runs, "most skills reach the
  * model without a description" is a suspicion.
  *
- * Exit: 0 always, except a usage/IO error (1). Deliberate.
+ * Exit: the REPORT is 0 always, except a usage/IO error (1). Deliberate — it
+ * gates on nothing and must not acquire a threshold.
+ *
+ * One later mode DOES carry a verdict, and it is not a threshold on the census:
+ * `--emit` exits 1 rather than writing a record from an empty store, because a
+ * zero-session reading is "no transcripts at this path" and publishing it as an
+ * activation figure is the defect this file exists to end.
+ *
+ * The assertion that the PUBLISHED figure still matches that record is a gate
+ * and lives in `check_skill_activation_claim.ts`. It is a separate script on
+ * purpose: `src/config/gate-coverage.yml` is a manifest of gates and
+ * `_lib/gate_population.ts` classifies one by prefix, so a `report_*` id
+ * registered there forks that population.
  */
 
 import * as fs from 'node:fs';
@@ -53,6 +65,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { projectStoreSlug } from './_lib/cc_transcript.js';
+import { reportScanned } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -73,11 +86,17 @@ export const DETERMINISTIC_RE = /^\s*(?:[-*]\s*)?(?:\*\*)?(MUST|NEVER|ALWAYS)\b/
 export interface SkillCensus {
   total: number;
   withTriggerKey: string[];
+  withTriggerCorpus: string[];
   withDeterministicObligation: string[];
 }
 
 export function censusSkills(root: string): SkillCensus {
-  const out: SkillCensus = { total: 0, withTriggerKey: [], withDeterministicObligation: [] };
+  const out: SkillCensus = {
+    total: 0,
+    withTriggerKey: [],
+    withTriggerCorpus: [],
+    withDeterministicObligation: [],
+  };
   if (!fs.existsSync(root)) {
     return out;
   }
@@ -98,6 +117,12 @@ export function censusSkills(root: string): SkillCensus {
     if (TRIGGER_KEYS.some((k) => new RegExp(`^${k}`, 'm').test(fm))) {
       out.withTriggerKey.push(entry.name);
     }
+    // A test fixture, not a routing input: no host reads it at selection time.
+    // Counted because it is the second of the three populations the surface
+    // splits into, and it is the one most often mistaken for the first.
+    if (fs.existsSync(path.join(root, entry.name, 'evals', 'triggers.json'))) {
+      out.withTriggerCorpus.push(entry.name);
+    }
     const body = fmEnd === -1 ? text : text.slice(fmEnd + 4);
     if (DETERMINISTIC_RE.test(body)) {
       out.withDeterministicObligation.push(entry.name);
@@ -178,7 +203,185 @@ function _pct(n: number, d: number): string {
   return d === 0 ? 'n/a' : `${((100 * n) / d).toFixed(1)}%`;
 }
 
-export function render(census: SkillCensus, usage: UsageReport[]): string {
+/** Repo-relative path of the record the published claim is derived from. */
+export const RECORD_PATH = 'agents/evidence/metrics/skill-activation-census.json';
+export const CLAIMS_PATH = 'docs/CLAIMS.md';
+/** The one ledger entry this census backs. */
+export const CLAIM_ID = 'skill-activation-census-zero';
+
+/**
+ * The three populations the shipped surface splits into, plus their overlap.
+ *
+ * They are computed from one pass rather than three greps because the whole
+ * point of 2.1 is that they reconcile: `humanNamedOnly` is a remainder, so it
+ * cannot be stated independently and then found to disagree.
+ */
+export interface Populations {
+  shipped: number;
+  triggerKey: number;
+  triggerCorpus: number;
+  bothKeyAndCorpus: number;
+  humanNamedOnly: number;
+}
+
+export function populations(census: SkillCensus): Populations {
+  const corpus = new Set(census.withTriggerCorpus);
+  const both = census.withTriggerKey.filter((s) => corpus.has(s));
+  const eitherOne = new Set([...census.withTriggerKey, ...census.withTriggerCorpus]);
+  return {
+    shipped: census.total,
+    triggerKey: census.withTriggerKey.length,
+    triggerCorpus: census.withTriggerCorpus.length,
+    bothKeyAndCorpus: both.length,
+    humanNamedOnly: census.total - eitherOne.size,
+  };
+}
+
+export interface CensusRecord {
+  schema_version: 1;
+  measured_at: string;
+  skills_shipped: number;
+  with_trigger_key: number;
+  with_trigger_corpus: number;
+  trigger_key_and_corpus: number;
+  human_named_only: number;
+  sessions: number;
+  assistant_turns: number;
+  invocations: number;
+  distinct_skills_invoked: number;
+  stores: string[];
+}
+
+export function buildRecord(census: SkillCensus, usage: UsageReport[], today: string): CensusRecord {
+  const pop = populations(census);
+  const distinct = new Set<string>();
+  for (const u of usage) {
+    for (const k of Object.keys(u.bySkill)) {
+      distinct.add(k);
+    }
+  }
+  return {
+    schema_version: 1,
+    measured_at: today,
+    skills_shipped: pop.shipped,
+    with_trigger_key: pop.triggerKey,
+    with_trigger_corpus: pop.triggerCorpus,
+    trigger_key_and_corpus: pop.bothKeyAndCorpus,
+    human_named_only: pop.humanNamedOnly,
+    sessions: usage.reduce((a, u) => a + u.sessions, 0),
+    assistant_turns: usage.reduce((a, u) => a + u.assistantTurns, 0),
+    invocations: usage.reduce((a, u) => a + u.invocations, 0),
+    distinct_skills_invoked: distinct.size,
+    stores: usage.map((u) => path.basename(u.store)),
+  };
+}
+
+export function readRecord(repoRoot: string): CensusRecord | null {
+  const file = path.join(repoRoot, RECORD_PATH);
+  if (!fs.existsSync(file)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(file, 'utf8')) as CensusRecord;
+}
+
+/**
+ * Numbers the published claim asserts, pulled back out of the claim text.
+ *
+ * Read from prose on purpose: the claim is the surface a reader believes, so
+ * comparing the record against a separate machine field would leave the
+ * sentence free to drift from both. `null` for any field the claim no longer
+ * states in the expected shape — which `checkClaim` reports as a defect rather
+ * than passing over, because a claim that stopped stating its figures is not a
+ * claim that agrees with the record.
+ */
+export interface ClaimFigures {
+  sessions: number | null;
+  assistantTurns: number | null;
+  invocations: number | null;
+  distinct: number | null;
+  shipped: number | null;
+  triggerKey: number | null;
+  triggerCorpus: number | null;
+  bothKeyAndCorpus: number | null;
+  humanNamedOnly: number | null;
+  measuredAt: string | null;
+  lastVerified: string | null;
+}
+
+function _num(text: string, re: RegExp): number | null {
+  const m = re.exec(text);
+  return m?.[1] === undefined ? null : Number.parseInt(m[1].replace(/,/gu, ''), 10);
+}
+
+export function claimBlock(claimsText: string, id: string): string | null {
+  const start = claimsText.indexOf(`### claim: ${id}\n`);
+  if (start === -1) {
+    return null;
+  }
+  const rest = claimsText.slice(start + 1);
+  const end = rest.indexOf('\n### claim: ');
+  return end === -1 ? claimsText.slice(start) : claimsText.slice(start, start + 1 + end);
+}
+
+export function parseClaimFigures(block: string): ClaimFigures {
+  return {
+    sessions: _num(block, /over ([\d,]+) sessions and/u),
+    assistantTurns: _num(block, /sessions and ([\d,]+) assistant turns/u),
+    invocations: _num(block, /records ([\d,]+) Skill invocations/u),
+    distinct: _num(block, /Skill invocations and ([\d,]+) of [\d,]+ distinct skills/u),
+    shipped: _num(block, /Skill invocations and [\d,]+ of ([\d,]+) distinct skills/u),
+    triggerKey: _num(block, /([\d,]+) declare a machine-matchable trigger key/u),
+    triggerCorpus: _num(block, /([\d,]+) carry an `evals\/triggers\.json` corpus/u),
+    bothKeyAndCorpus: _num(block, /([\d,]+) do both/u),
+    humanNamedOnly: _num(block, /([\d,]+) are reachable only by a human naming them/u),
+    measuredAt: /measured (\d{4}-\d{2}-\d{2})/u.exec(block)?.[1] ?? null,
+    lastVerified: /^- last_verified: (\d{4}-\d{2}-\d{2})/mu.exec(block)?.[1] ?? null,
+  };
+}
+
+/**
+ * Disagreements between the committed record and the published claim.
+ *
+ * This is the whole of what 1.3 buys, so it is worth being exact about what it
+ * does NOT buy: it cannot tell whether the RECORD still describes the world,
+ * because the transcript store it was taken from is one machine's and is absent
+ * from CI. Re-taking the measurement is `--emit`; this only forbids the
+ * published sentence and the record from telling two different stories.
+ */
+export function claimProblems(rec: CensusRecord, fig: ClaimFigures): string[] {
+  const out: string[] = [];
+  const pairs: Array<[string, number, number | null]> = [
+    ['sessions', rec.sessions, fig.sessions],
+    ['assistant turns', rec.assistant_turns, fig.assistantTurns],
+    ['Skill invocations', rec.invocations, fig.invocations],
+    ['distinct skills invoked', rec.distinct_skills_invoked, fig.distinct],
+    ['skills shipped', rec.skills_shipped, fig.shipped],
+    ['skills with a trigger key', rec.with_trigger_key, fig.triggerKey],
+    ['skills with a triggers.json corpus', rec.with_trigger_corpus, fig.triggerCorpus],
+    ['skills in both populations', rec.trigger_key_and_corpus, fig.bothKeyAndCorpus],
+    ['human-named-only skills', rec.human_named_only, fig.humanNamedOnly],
+  ];
+  for (const [label, recorded, claimed] of pairs) {
+    if (claimed === null) {
+      out.push(`${label}: the claim no longer states this figure; the record says ${String(recorded)}`);
+    } else if (claimed !== recorded) {
+      out.push(`${label}: claim says ${String(claimed)}, record says ${String(recorded)}`);
+    }
+  }
+  for (const [label, claimed] of [
+    ['measurement date', fig.measuredAt],
+    ['last_verified', fig.lastVerified],
+  ] as Array<[string, string | null]>) {
+    if (claimed === null) {
+      out.push(`${label}: the claim no longer states it; the record was measured ${rec.measured_at}`);
+    } else if (claimed !== rec.measured_at) {
+      out.push(`${label}: claim says ${claimed}, record was measured ${rec.measured_at}`);
+    }
+  }
+  return out;
+}
+
+export function render(census: SkillCensus, usage: UsageReport[], published: CensusRecord | null = null): string {
   const lines: string[] = [];
   lines.push('skill activation census — advisory, gates on nothing');
   lines.push('');
@@ -193,6 +396,16 @@ export function render(census: SkillCensus, usage: UsageReport[]): string {
     lines.push(`      ${census.withDeterministicObligation.join(', ')}`);
   }
   lines.push('');
+  const pop = populations(census);
+  lines.push('  populations — the three ways a skill can be reached, reconciled');
+  lines.push(`    machine-matchable trigger key        ${pop.triggerKey}`);
+  lines.push(`    evals/triggers.json corpus           ${pop.triggerCorpus}  (a test fixture; no host reads it at routing time)`);
+  lines.push(`    both of the above                    ${pop.bothKeyAndCorpus}`);
+  lines.push(`    human-named only (remainder)         ${pop.humanNamedOnly}`);
+  lines.push(
+    `    reconciles                           ${pop.triggerKey} + ${pop.triggerCorpus} - ${pop.bothKeyAndCorpus} + ${pop.humanNamedOnly} = ${String(pop.triggerKey + pop.triggerCorpus - pop.bothKeyAndCorpus + pop.humanNamedOnly)} of ${pop.shipped}`,
+  );
+  lines.push('');
   let totalInv = 0;
   const distinct = new Set<string>();
   for (const u of usage) {
@@ -213,6 +426,65 @@ export function render(census: SkillCensus, usage: UsageReport[]): string {
     lines.push(`      ${[...distinct].sort().join(', ')}`);
   }
   lines.push('');
+  const sessionsRead = usage.reduce((a, u) => a + u.sessions, 0);
+  if (sessionsRead === 0) {
+    // The store is keyed on the directory the process runs in, so a checkout
+    // that never hosted a session — a fresh worktree, a CI runner — yields a
+    // zero that means "no transcripts at this path". Publishing that as the
+    // activation reading would be the defect this census exists to end, so the
+    // two zeros are separated here rather than left to the reader.
+    lines.push('  EMPTY STORE: 0 sessions were read, so the zero above is "no transcripts at');
+    lines.push('  this path", NOT "no activations". It is not a measurement of the surface and');
+    lines.push('  must not be published as one. Run this where the store lives, or pass --store.');
+    lines.push('');
+  }
+  if (published !== null) {
+    // Staleness has to be readable from the run itself. Without this block the
+    // only way to tell a fresh published figure from a rotted one is to open
+    // the git log of `docs/CLAIMS.md`, which is exactly the thing 1.3 forbids.
+    const live = buildRecord(census, usage, published.measured_at);
+    // The two halves drift for different reasons and a single verdict over both
+    // would be worthless: the store is rolling, so its counts move between any
+    // two runs — including a run in the session that is adding to it. A reader
+    // who is told STALE every time stops reading the line. Only the repository
+    // half is a defect when it moves, because the published population split
+    // then no longer describes the tree it claims to count.
+    const REPO_FIELDS: Array<keyof CensusRecord> = [
+      'skills_shipped',
+      'with_trigger_key',
+      'with_trigger_corpus',
+      'trigger_key_and_corpus',
+      'human_named_only',
+    ];
+    const STORE_FIELDS: Array<keyof CensusRecord> = [
+      'sessions',
+      'assistant_turns',
+      'invocations',
+      'distinct_skills_invoked',
+    ];
+    const repoDrift = REPO_FIELDS.filter((k) => live[k] !== published[k]);
+    const storeDrift = STORE_FIELDS.filter((k) => live[k] !== published[k]);
+    lines.push(`  PUBLISHED RECORD (${RECORD_PATH}), measured ${published.measured_at}:`);
+    lines.push(
+      `    sessions=${String(published.sessions)} asst=${String(published.assistant_turns)} invocations=${String(published.invocations)} distinct=${String(published.distinct_skills_invoked)}`,
+    );
+    if (repoDrift.length > 0) {
+      lines.push(`    STALE: the published population split no longer describes this tree —`);
+      lines.push(`    ${repoDrift.join(', ')} moved. Re-take with --emit.`);
+    } else {
+      lines.push('    population split still describes this tree.');
+    }
+    if (sessionsRead === 0) {
+      lines.push('    Store reading: UNDECIDED — this run read no store, so it cannot say whether');
+      lines.push('    the published figures still hold. Re-run where the store lives.');
+    } else if (storeDrift.length === 0) {
+      lines.push('    Store reading: reproduces the published figures exactly.');
+    } else {
+      lines.push(`    Store reading: moved since the record (${storeDrift.join(', ')}). Expected —`);
+      lines.push('    the store is rolling, not append-only, and a later reading can be lower.');
+    }
+    lines.push('');
+  }
   if (census.withTriggerKey.length === 0) {
     lines.push('  VERDICT: activation is not measurable as a rate. No skill declares a');
     lines.push('  machine-matchable trigger, so a missed-activation detector has nothing to');
@@ -227,19 +499,32 @@ export function render(census: SkillCensus, usage: UsageReport[]): string {
   return lines.join('\n');
 }
 
+const USAGE =
+  'usage: report_skill_activation [--root DIR] [--limit N] [--store PATH]... [--emit] [--allow-empty-store]\n';
+
 function main(argv: string[]): number {
   let limit = 30;
+  let emit = false;
+  let allowEmpty = false;
+  const rootIdx = argv.indexOf('--root');
+  const root = rootIdx === -1 ? REPO_ROOT : (argv[rootIdx + 1] ?? REPO_ROOT);
   const stores: string[] = [];
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
-    if (a === '--limit' && argv[i + 1] !== undefined) {
+    if (a === '--root' && argv[i + 1] !== undefined) {
+      i += 1;
+    } else if (a === '--limit' && argv[i + 1] !== undefined) {
       limit = Number.parseInt(argv[i + 1] as string, 10);
       i += 1;
     } else if (a === '--store' && argv[i + 1] !== undefined) {
       stores.push(argv[i + 1] as string);
       i += 1;
+    } else if (a === '--emit') {
+      emit = true;
+    } else if (a === '--allow-empty-store') {
+      allowEmpty = true;
     } else if (a === '--help' || a === '-h') {
-      process.stdout.write('usage: report_skill_activation [--limit N] [--store PATH]...\n');
+      process.stdout.write(USAGE);
       return 0;
     }
   }
@@ -250,9 +535,36 @@ function main(argv: string[]): number {
   if (stores.length === 0) {
     stores.push(defaultStore(REPO_ROOT));
   }
-  const census = censusSkills(path.join(REPO_ROOT, SKILLS_ROOT));
+  const census = censusSkills(path.join(root, SKILLS_ROOT));
   const usage = stores.map((s) => measureUsage(s, limit));
-  process.stdout.write(`${render(census, usage)}\n`);
+  process.stdout.write(`${render(census, usage, readRecord(root))}\n`);
+  // The skills are the corpus this floor can hold: they are in the repository,
+  // so the count is the same everywhere. The transcript half is path-scoped and
+  // legitimately zero in CI, which is why it is reported above and not here — a
+  // floor over it would either red every CI run or be vacuous.
+  reportScanned({
+    gate: 'report_skill_activation',
+    scanned: census.total,
+    units: 'SKILL.md file(s)',
+    roots: [SKILLS_ROOT],
+  });
+  if (!emit) {
+    return 0;
+  }
+  const sessionsRead = usage.reduce((a, u) => a + u.sessions, 0);
+  if (sessionsRead === 0 && !allowEmpty) {
+    process.stderr.write(
+      'report_skill_activation --emit: refusing to write a record from 0 sessions — that zero\n' +
+        'is "no transcripts at this path", not an activation reading. Run where the store lives,\n' +
+        'pass --store, or pass --allow-empty-store if an empty store is genuinely the finding.\n',
+    );
+    return 1;
+  }
+  const today = new Date().toISOString().slice(0, 10);
+  const file = path.join(root, RECORD_PATH);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(buildRecord(census, usage, today), null, 2)}\n`);
+  process.stdout.write(`\nwrote ${RECORD_PATH} (measured ${today})\n`);
   return 0;
 }
 

package/src/scripts/schemas/review-findings.schema.json

@@ -51,6 +51,11 @@
         "type": "string"
       }
     },
+    "no_findings_reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Why the finding set is empty. REQUIRED whenever a ledger file exists and `findings` is empty — enforced in check_finding_dispositions.empty_ledger_problem rather than here, because the requirement is conditional on the array length and this repo's Draft-07 subset validator resolves no `if`/`then`. The field exists because `findings: []` and a missing file made the same claim to every reader while collapsing two states that differ entirely: a review that ran and reported nothing, and a review that never ran. The reason must pick one and say how a reader can check it."
+    },
     "findings": {
       "type": "array",
       "description": "May be empty. An empty array is an honest null, not a missing field — the distinction the Markdown track spells with its own §2.3 line. The item shape is INLINED rather than `$ref`-ed for the same measured reason: the subset validator does not resolve `$ref`, so a referenced definition would have validated nothing.",

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

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/skill.schema.json",
-  "x-schemaVersion": "1.1.0",
+  "x-schemaVersion": "1.1.1",
   "title": "Skill frontmatter",
   "$comment": "Source: agents/reference/docs/frontmatter-contract.md#skills. Keep in sync with inventory_frontmatter.py and the linter's lint_skill().",
   "type": "object",
@@ -276,7 +276,7 @@
         },
         "requires_confirmation": {
           "type": "boolean",
-          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: only claude both binds pre_tool_use and honours a deny (docs/contracts/hook-architecture-v1.md, section Which hosts carry pre_tool_use — 2 further hosts bind it and ignore the verdict, 3 alias it unbound, 2 have no pre-tool surface), so a guard would degrade to prose on 7 of 8 hosts while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
+          "description": "Optional, additive: the skill's action STAGES rather than executes, so an irreversible step waits for an explicit human confirmation naming the exact object (non-destructive-by-default § Never act while asking). A declaration only — it names the action class, never the object, which exists at stage time and not in frontmatter. The mechanism is stageAction/confirmOnce in work_engine/hooks/builtin/staged_confirmation.ts; enumerate what is pending with `agent-config gates --pending`. Nothing BINDS on this flag yet: only claude both binds pre_tool_use and honours a deny (docs/contracts/hook-architecture-v1.md, section Which hosts carry pre_tool_use — 2 further hosts bind it and ignore the verdict, 3 alias it unbound, 2 carry no pre-tool alias row), so a guard would degrade to prose on 7 of 8 hosts while the flag reads like a control — that decision is deferred behind blocker confirmation-degraded-host-semantics."
         },
         "command": {
           "type": "array",

package/src/scripts/session_canary_hook.ts

@@ -16,7 +16,7 @@
  * rule alone is exactly the kind of surface that is dropped in fresh
  * conversations (found RED baseline on the reply-close PR-URL contract,
  * 2026-07-27); the session_start injection makes the contract present in every
- * new conversation on hook-capable hosts. Copilot (no hook surface) falls back
+ * new conversation on hook-capable hosts. Copilot (nothing bound here) falls back
  * to the rule alone.
  *
  * Gate + name resolution (first non-empty wins — the canary is a PERSONAL,

package/src/scripts/session_register_hook.ts

@@ -37,9 +37,10 @@
  *
  * ## Honest coverage
  *
- * The heartbeat is a per-turn obligation and does not reach every host. `copilot`
- * has no hook surface at all; `cursor`'s per-turn slots are IDE-only and do not
- * fire in its CLI; `cowork`'s lifecycle events are wired but inert. Those hosts
+ * The heartbeat is a per-turn obligation and does not reach every host. This
+ * package binds nothing on `copilot`; `cursor`'s per-turn reachability is not
+ * established here, so it is excluded rather than assumed; `cowork`'s lifecycle
+ * events are wired but inert. Those hosts
  * are named in `HEARTBEAT_REACHABLE_PLATFORMS` by their absence, and a session
  * there simply stops being visible after its TTL rather than being reported as
  * covered.

package/src/scripts/trigger_eval_grandfather.json

@@ -1,5 +1,9 @@
 {
-  "_note": "Shrink-only grandfather allowlist for check_trigger_eval_presence (road-to-composition-ratchet). Skills listed here predate the trigger-eval presence gate and may lack evals/triggers.json. Entries may ONLY be removed (when the skill gains a triggers.json or is deleted) \u2014 never added. Frozen 2026-07-08 at 221 of 264 skills.",
+  "_note": "Shrink-only grandfather allowlist for check_trigger_eval_presence (road-to-composition-ratchet). Skills listed here predate the trigger-eval presence gate and may lack evals/triggers.json. Entries may ONLY be removed (when the skill gains a triggers.json or is deleted) — never added. Frozen 2026-07-08 at 221 of 264 skills.",
+  "_no_obligation_note": "Entries in `_no_obligation` are on the `skills` allowlist for a DIFFERENT reason from the rest. The list above records skills that predate the gate and owe a triggers.json; these owe none, because their description says explicit-request-only and they publish no auto-trigger keywords — there is no trigger to evaluate. Listing them without this distinction reads as a waived obligation when the obligation is absent. Read by humans only: check_trigger_eval_presence parses `skills` and ignores every other key, so this changes no verdict. Removing one from `skills` WOULD change a verdict — the gate would then demand a triggers.json for a skill that has nothing to trigger on.",
+  "_no_obligation": [
+    "sequential-thinking"
+  ],
   "skills": [
     "accessibility-auditor",
     "activation-design",

package/src/scripts/validate_agent_settings.ts

@@ -42,7 +42,7 @@ const SCHEMA_PATH = path.join(REPO_ROOT, 'src', 'scripts', 'schemas', 'agent-set
 const TEMPLATE_PATH = path.join(REPO_ROOT, 'src', 'config', 'agent-settings.template.yml');
 const LOCAL_PATHS = [project_settings_path(REPO_ROOT)];
 
-// Installer-default substitutions, mirroring scripts/install.py so the
+// Installer-default substitutions, mirroring the installer so the
 // template validates as it would after a fresh `balanced` install.
 const PLACEHOLDERS: Record<string, string> = {
     __RULE_LOADING_TIER__: 'balanced',