@event4u/agent-config 14.18.0 → 14.20.0

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

@@ -48,6 +48,7 @@ import {
     attachReleaseErrors,
     listRecords,
     markReleased,
+    writeTargetIndex,
     openRecords,
     readOverflow,
     readRecord,
@@ -503,6 +504,30 @@ function releaseCmd(root: string, argv: string[]): number {
     return EXIT_OK;
 }
 
+/**
+ * Rebuild the per-target occurrence index and print it.
+ *
+ * A DERIVED read: the record files are the source, the index is regenerable
+ * and gitignored with the rest of `agents/runtime/`. It exists because
+ * `occurrences` counts a fingerprint (class + normalised evidence shape), so a
+ * rule's weakness showing up in three different shapes was three records with
+ * one occurrence each — and the third-recurrence escalation had nothing that
+ * could ever establish its own precondition.
+ */
+function targetsCmd(root: string): number {
+    const counts = writeTargetIndex(root);
+    if (counts.length === 0) {
+        process.stdout.write('self-repair: no record carries a resolved target yet.\n');
+        return EXIT_OK;
+    }
+    for (const c of counts) {
+        process.stdout.write(
+            `  ${c.target}  ${c.occurrences} occurrence(s) across ${c.records.length} record(s)\n`,
+        );
+    }
+    return EXIT_OK;
+}
+
 export function main(argv: readonly string[]): number {
     const root = process.cwd();
     const sub = argv[0] ?? 'status';
@@ -512,7 +537,12 @@ export function main(argv: readonly string[]): number {
     if (sub === 'release') {
         return releaseCmd(root, [...argv.slice(1)]);
     }
-    process.stderr.write(`self-repair: unknown subcommand '${sub}' (status | release).\n`);
+    if (sub === 'targets') {
+        return targetsCmd(root);
+    }
+    process.stderr.write(
+        `self-repair: unknown subcommand '${sub}' (status | release | targets).\n`,
+    );
     return EXIT_FAIL;
 }
 

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

@@ -48,6 +48,12 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { collect, _keyword_vector, _cosine } from './audit_skill_overlap.js';
 import { reportScanned, DeadScopeError } from './_lib/scan_scope.js';
+import * as sl from './_lib/security_lint.js';
+import { _scan as _scanHiddenUnicode } from './lint_hidden_unicode.js';
+import { _scan as _scanConfusables } from './lint_confusables.js';
+import { _scan as _scanInstructionSmuggling } from './lint_instruction_smuggling.js';
+import { _scan as _scanMcpConfigSecurity } from './lint_mcp_config_security.js';
+import { _scan as _scanFrontmatterSafety } from './lint_skill_frontmatter_safety.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const _DEFAULT_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -262,6 +268,60 @@ export function resolveCandidateDir(
     return { dir, refusal: null };
 }
 
+/**
+ * The five content linters, by the check id each one reports under.
+ *
+ * The SAME functions the `lint_agent_security` umbrella spawns as processes.
+ * Called in-process here rather than shelled out: five `tsx` cold starts per
+ * candidate is a cost with no benefit, and the thing that must be identical is
+ * the DETECTION, which is these functions.
+ */
+const CONTENT_LINTERS: ReadonlyArray<readonly [string, (sf: sl.ScannedFile) => sl.Finding[]]> = [
+    ['hidden-unicode', _scanHiddenUnicode],
+    ['mixed-script-confusable', _scanConfusables],
+    ['instruction-smuggling', _scanInstructionSmuggling],
+    ['mcp-config-security', _scanMcpConfigSecurity],
+    ['dangerous-frontmatter', _scanFrontmatterSafety],
+];
+
+/**
+ * Read what a quarantined candidate SAYS, and refuse on a payload.
+ *
+ * `intake`'s other checks are properties of the file — symlink, extension, exec
+ * bit, size. Every one of them can be true of a file whose text tells an agent
+ * to hide its output from the user. "Inert" was a claim about the container that
+ * the gate read as a claim about the contents.
+ *
+ * TWO DELIBERATE DIFFERENCES FROM HOW THESE LINTERS RUN OVER THIS PACKAGE:
+ *
+ * 1. **Any HIGH refuses, whatever its weight.** The 0.25 confidence weighting is
+ *    a false-positive containment device for THIS repository's own corpus, where
+ *    a path containing `docs` or `examples` really is documentation somebody
+ *    here wrote. A quarantined third-party candidate carries no such provenance,
+ *    and a directory named `examples/` in it is an attacker's word for it. A
+ *    refusal is also cheaper than a false pass in exactly this direction: the
+ *    candidate is rejected and a human reads it.
+ * 2. **Every text extension is scanned, not just `.md`.** The candidate
+ *    allow-list already bounds what may be present; a payload in the `.yml` a
+ *    candidate ships is a payload.
+ *
+ * The refusal NAMES the linter, because "the content scan refused this" sends a
+ * reader to five detectors.
+ */
+export function scanCandidateContent(candidateDir: string): string[] {
+    const out: string[] = [];
+    for (const sf of sl.iter_corpus(['.'], [...ALLOWED_EXT], candidateDir)) {
+        for (const [check, scan] of CONTENT_LINTERS) {
+            for (const finding of scan(sf)) {
+                if (finding.severity !== 'HIGH') continue;
+                const loc = finding.line ? `${sf.rel}:${String(finding.line)}` : sf.rel;
+                out.push(`${loc}: flagged by ${check} — ${finding.message}`);
+            }
+        }
+    }
+    return out;
+}
+
 /**
  * Refuse a candidate that is not inert.
  *
@@ -296,6 +356,15 @@ export function intake(candidateDir: string): IntakeResult {
     if (files.length === 0) {
         refusals.push('candidate directory is empty');
     }
+    // Content, after the file properties. Ordering is not cosmetic: a candidate
+    // that fails an inertness check may not be safe to READ (a symlink out of
+    // quarantine is the case the read-time re-check exists for), so the bytes
+    // are only opened once the container has been judged.
+    if (refusals.length === 0) {
+        for (const flagged of scanCandidateContent(candidateDir)) {
+            refusals.push(flagged);
+        }
+    }
     return { accepted: refusals.length === 0, refusals, files_seen: files.length };
 }
 

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',