@event4u/agent-config 14.17.0 → 14.19.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.",
@@ -66,7 +71,7 @@
           "finding_id": {
             "type": "string",
             "pattern": "^[0-9a-f]{12}$",
-            "description": "First 12 hex of sha256(`kind|title|file`), per findingId() in self_review_gate.ts. Stable across runs, which is what lets the disposition ledger key on it. NOT required: an in-flight finding may not have been keyed yet, and requiring it would make the schema reject the shape the model returns before the gate stamps it."
+            "description": "First 12 hex of sha256(`kind|title|file`), per findingId() in self_review_gate.ts. Stable across runs, which is what lets the disposition ledger key on it. NOT required: an in-flight finding may not have been keyed yet, and requiring it would make the schema reject the shape the model returns before the gate stamps it. It is a FINDING id, NOT a commit SHA — a 12-hex string looks exactly like a short SHA, and searching the commit log for it finds nothing by design; the disposition lives in agents/evidence/release-findings/<version>.json."
           },
           "severity": {
             "enum": [

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.0.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",
@@ -472,6 +472,16 @@
       ],
       "description": "Classifier signal for auto-dispatch. 'steps' = ordered multi-step plan → do-in-steps. 'files' = N independent files of the same shape → do-in-parallel. 'independent' = N independent same-shape targets (not files) → do-in-parallel. Omit for skills that are always single-pass. Read by auto-dispatch-classification.md classifier signal 1."
     },
+    "enforced_by": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^(hook:[a-z0-9_-]+|validator:[A-Za-z0-9_./-]+|test:[A-Za-z0-9_./-]+|observer:[a-z0-9 _-]+|instruction-only: *[^ ].*|none)$"
+      },
+      "description": "What resolves a CHECKABLE CLAIM this skill makes about itself \u2014 a standard-conformance claim of the form `<standard> <version> <level>` (WCAG 2.2 AA). Deliberately the SAME key and the same value vocabulary as rule.schema.json's `enforced_by`, per council 2026-09-04 (anthropic + openai, 2/2 for frontmatter over body markers; the residual split between reusing this key and minting a new `claim_resolvers:` was resolved on measurement \u2014 reuse costs ONE schema addition where a new key costs two, and adds no second vocabulary for one idea). `test:<path>` names the resolver; `instruction-only: <reason>` declares an honest gap, and the reason is MANDATORY because a bare marker is a claim with no triage record behind it. Resolved by tests/contracts/conformance_claim_declaration.test.ts. NOT read by check_enforcement_coverage.ts or lint_rule_enforcement_declaration.ts \u2014 both scan `src/rules/` only, so a skill carrying this key does not join the rule-enforcement ratchet."
+    },
     "gaps": {
       "type": "array",
       "description": "B6 — honest-null known limitations. Human-curated (NOT auto-discovered), not all skills. Each entry documents a real limitation and cites a witness test that reproduces it. Rendered on the proof page's 'Known Limits'; check_skill_gaps enforces every witness path exists. The offensive-transparency surface a headline-benchmark cannot ship.",

package/src/scripts/self_review_gate.ts

@@ -356,6 +356,15 @@ export function renderReview(findings: Finding[], enforce: boolean, escalation:
             ? `❌ ${blocking.length} merge-blocking finding(s) (security/claim × high+).`
             : `⚠️ ${blocking.length} finding(s) WOULD block merge under an enforced gate (advisory now).`
         : '✅ No merge-blocking findings (style/correctness advise only).';
+    // Three reviewers in the 2026-09 round searched the commit log for a finding
+    // id's first eight characters, found nothing, and reported "no fix found". A
+    // 12-hex id looks exactly like a short SHA, so the rendered comment now says
+    // what it is and where its disposition lives. This is the only place a reader
+    // of the comment can learn it without opening the source.
+    const idNote =
+        '\n\n`id` above is a FINDING id — the first 12 hex of sha256(kind|title|file), '
+        + '**not a commit SHA**. Searching the git log for it finds nothing, by design. '
+        + 'Its disposition is recorded in `agents/evidence/release-findings/<version>.json`.';
     // Machine-readable block (release-truth Phase 3): invisible in the rendered
     // comment; `check_finding_dispositions --pr` reads it as the TRIGGER that
     // demands committed dispositions. The comment is transport, never the
@@ -363,7 +372,7 @@ export function renderReview(findings: Finding[], enforce: boolean, escalation:
     const machine = `\n\n<!-- release-findings-json: ${JSON.stringify(
         findings.map((f) => ({ finding_id: findingId(f), severity: f.severity, kind: f.kind, title: f.title, file: f.file ?? null })),
     )} -->`;
-    return `${banner}\n\n${verdictLine}\n\n| id | severity | kind | file | finding |\n|---|---|---|---|---|\n${rows}${esc}${machine}`;
+    return `${banner}\n\n${verdictLine}\n\n| id | severity | kind | file | finding |\n|---|---|---|---|---|\n${rows}${idNote}${esc}${machine}`;
 }
 
 function postReview(body: string): void {

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

package/src/shared/settingsConsent.ts

@@ -15,7 +15,7 @@
  * would mean the agent could arrive at its own permission by observing the
  * world, which is the confused-deputy shape in miniature.
  *
- * Modelled on `src/scripts/hooks/block_unauthorized_git.ts`: answer from a
+ * Modelled on `src/scripts/hooks/git_command_classifier.ts`: answer from a
  * recorded fact rather than from the model's recollection, and treat a missing
  * record as NOT granted rather than as probably-fine.
  *