pi-braid 0.43.6 → 0.43.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/TOOLS.md +1 -1
  3. package/build-info.json +4 -4
  4. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  5. package/dist/extensions/core/skills-tool/applicability.d.ts +134 -0
  6. package/dist/extensions/core/skills-tool/applicability.js +161 -0
  7. package/dist/extensions/core/skills-tool/auto-inject.d.ts +31 -0
  8. package/dist/extensions/core/skills-tool/auto-inject.js +320 -1
  9. package/dist/extensions/core/skills-tool/index.js +83 -4
  10. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  11. package/dist/extensions/core/skills-tool/loading-guidance.js +6 -2
  12. package/dist/extensions/core/skills-tool/session-records.d.ts +395 -8
  13. package/dist/extensions/core/skills-tool/session-records.js +645 -5
  14. package/dist/extensions/core/skills-tool/skill-families.d.ts +60 -0
  15. package/dist/extensions/core/skills-tool/skill-families.js +105 -0
  16. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  17. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  18. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  19. package/dist/extensions/enforcement/verification-judge.js +28 -21
  20. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  21. package/dist/extensions/memory/session-recall/ask.js +376 -0
  22. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  23. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  24. package/dist/extensions/memory/session-recall/index.js +173 -21
  25. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  26. package/dist/extensions/memory/session-recall/search.js +42 -9
  27. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  28. package/dist/lib/ai/payload-hygiene.js +34 -2
  29. package/dist/lib/config/braid-paths.d.ts +4 -0
  30. package/dist/lib/config/braid-paths.js +6 -0
  31. package/dist/lib/config/braid-settings.d.ts +22 -0
  32. package/dist/lib/config/braid-settings.js +15 -0
  33. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  34. package/dist/lib/detection/tool-loop-detector.js +288 -180
  35. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  36. package/dist/lib/reasoning/dreamer.js +12 -7
  37. package/docs/LOCAL_DEV.md +1 -1
  38. package/docs/SETUP.md +1 -0
  39. package/package.json +1 -1
  40. package/src/extensions/core/AGENTS.md +3 -1
  41. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  42. package/src/extensions/core/skills-tool/applicability.ts +220 -0
  43. package/src/extensions/core/skills-tool/auto-inject.ts +391 -0
  44. package/src/extensions/core/skills-tool/index.ts +96 -3
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +6 -2
  46. package/src/extensions/core/skills-tool/session-records.ts +932 -5
  47. package/src/extensions/core/skills-tool/skill-families.ts +112 -0
  48. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  49. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  50. package/src/extensions/enforcement/verification-judge.ts +32 -25
  51. package/src/extensions/memory/AGENTS.md +2 -2
  52. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  53. package/src/extensions/memory/session-recall/ask.ts +435 -0
  54. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  55. package/src/extensions/memory/session-recall/index.ts +202 -21
  56. package/src/extensions/memory/session-recall/search.ts +61 -10
  57. package/src/lib/ai/payload-hygiene.ts +47 -3
  58. package/src/lib/config/braid-paths.ts +7 -0
  59. package/src/lib/config/braid-settings.ts +42 -3
  60. package/src/lib/detection/AGENTS.md +8 -7
  61. package/src/lib/detection/tool-loop-detector.ts +339 -195
  62. package/src/lib/reasoning/dreamer.ts +13 -6
@@ -95,6 +95,15 @@
95
95
  * and never within that window of a suggestion or a SKILL.md read). The
96
96
  * rule and its bounds live in loading-guidance.ts beside the floor text
97
97
  * the line points at; this module only wires them to tool results.
98
+ * 11. At-use inform (`braid.skills.inform`, default off): a COMPLETED call in
99
+ * a family a visible skill's file declares with `governs:` and no read of
100
+ * that body on the session record gets one steer line naming the file and
101
+ * the obligation. Once per session per skill, suppressed by the same
102
+ * obligation record the legs already write (the `informed` leg). It
103
+ * observes a call that already ran and can only add a line: no refusal,
104
+ * no delay, and no rewrite of the result it arrives after. This is the
105
+ * timed alternative to refusing the call, and the difference is the whole
106
+ * point of it.
98
107
  *
99
108
  * Structure matches the existing steer whisper pattern used by topic-drift,
100
109
  * turn-outcome, compaction-retry, context-lifecycle, and others.
@@ -116,11 +125,20 @@ import { getSkillsUsageFilePath } from "../../../lib/config/braid-paths.js";
116
125
  import { SESSION_COMPACT, AGENT_SETTLED } from "../../../lib/core/event-names.js";
117
126
  import {
118
127
  getSessionProfile,
128
+ recordApplicabilityCensus,
129
+ recordApplicabilityVerdict,
130
+ recordObligationLegs,
119
131
  recordSessionSkillLoad,
120
132
  recordSessionStart,
121
133
  } from "./session-records.js";
134
+ import type { ObligationLegs } from "./session-records.js";
135
+ import { evaluateApplicability } from "./applicability.js";
136
+ import type { SkillApplicabilityVerdict } from "./applicability.js";
122
137
  import { triggerMatches } from "./skill-triggers.js";
123
138
  import type { TriggerSource } from "./skill-triggers.js";
139
+ import { toolFamilyToken } from "./skill-families.js";
140
+ import { getSkillsInformMode } from "../../../lib/config/braid-settings.js";
141
+ import type { SkillsInformMode } from "../../../lib/config/braid-settings.js";
124
142
  import {
125
143
  advanceDrift,
126
144
  driftDirectoryFor,
@@ -285,6 +303,57 @@ interface AutoInjectState {
285
303
  hintSent: boolean;
286
304
  /** Where the work is going, for the drift trigger (loading-guidance.ts). */
287
305
  drift: DriftTracker;
306
+ /** Which skills' own declared conditions held this session (applicability.ts). */
307
+ applicability: ApplicabilityState;
308
+ /** What the session did with each skill body it met (see ObligationState). */
309
+ obligations: ObligationState;
310
+ /**
311
+ * The resolved `braid.skills.inform` policy, read once per session. A
312
+ * settings edit takes effect in the next session, the same way the session
313
+ * profile does, so a tool_result never reads and parses settings.json.
314
+ */
315
+ informMode?: SkillsInformMode;
316
+ }
317
+
318
+ /**
319
+ * The session's obligation bookkeeping: one row of legs per skill, appended
320
+ * only when a leg changes, so at most a handful of lines per session.
321
+ *
322
+ * `called` holds the skills whose first call in a declared family was already
323
+ * decided; the applied leg is fixed at that moment and never revisited.
324
+ * `written` is the last signature that reached disk, which makes a repeated
325
+ * read, a repeated list row or a second call cost nothing.
326
+ */
327
+ interface ObligationState {
328
+ legs: Map<string, ObligationLegs>;
329
+ called: Set<string>;
330
+ written: Map<string, string>;
331
+ }
332
+
333
+ function initialObligations(): ObligationState {
334
+ return { legs: new Map(), called: new Set(), written: new Map() };
335
+ }
336
+
337
+ /**
338
+ * The session's applicability bookkeeping. Cumulative by design: once a task
339
+ * text met a skill's declared condition, the skill applied to that session, and
340
+ * a read that lands on a later turn is still a read of a skill that applied.
341
+ */
342
+ interface ApplicabilityState {
343
+ /** True once the session's census row landed on disk. */
344
+ censusWritten: boolean;
345
+ /** Verdicts by skill name; only ever grows, and an entry only ever upgrades. */
346
+ verdicts: Map<string, SkillApplicabilityVerdict>;
347
+ /** Skills declaring a condition, from the latest evaluation. */
348
+ evaluated: number;
349
+ /** Skills declaring none, from the latest evaluation. */
350
+ undeclared: string[];
351
+ /** Task-text length the latest evaluation read. */
352
+ taskChars: number;
353
+ }
354
+
355
+ function initialApplicability(): ApplicabilityState {
356
+ return { censusWritten: false, verdicts: new Map(), evaluated: 0, undeclared: [], taskChars: 0 };
288
357
  }
289
358
 
290
359
  const STATE_KEY = "skills-auto-inject";
@@ -295,6 +364,8 @@ function getState(ctx: ExtensionContext): AutoInjectState {
295
364
  currentTurn: 0,
296
365
  hintSent: false,
297
366
  drift: initialDrift(),
367
+ applicability: initialApplicability(),
368
+ obligations: initialObligations(),
298
369
  }));
299
370
  }
300
371
 
@@ -315,6 +386,8 @@ export interface CachedSkill {
315
386
  triggers?: string[];
316
387
  /** Which source authored each phrase (the row's evidence label). */
317
388
  triggerSources?: Record<string, TriggerSource>;
389
+ /** Tool families the file's `governs:` declaration claims (skill-families.ts). */
390
+ families?: string[];
318
391
  }
319
392
 
320
393
  // Shared module-level variable rather than a per-module copy: the import
@@ -1151,6 +1224,176 @@ export function resolveDiscoveryMode(ctx: ExtensionContext): DiscoveryState {
1151
1224
  return state;
1152
1225
  }
1153
1226
 
1227
+ // Applicability verdict (recorded, never enforced)
1228
+
1229
+ /**
1230
+ * Classify the catalog against this turn's task text and record what changed.
1231
+ *
1232
+ * Two writes, both append-only:
1233
+ * - the session's census row, once, retried until it lands. It is what makes
1234
+ * "not-applicable" derivable (evaluated minus the verdict rows) and what
1235
+ * names the skills whose files state no condition at all.
1236
+ * - one verdict row per skill whose declared condition held, and never twice
1237
+ * for the same (session, skill): the set only grows because the verdict is
1238
+ * per-session — a skill whose condition held on any turn applied to the
1239
+ * session.
1240
+ *
1241
+ * The row shape is the joint the sibling compliance record expects: it joins on
1242
+ * (sessionId, skill) and adds its own `suggested`/`listed`/`read`/`applied`
1243
+ * beside this verdict, so `ignored / (read + ignored)` becomes computable. This
1244
+ * module writes no `applied` leg: a tool belong to a skill's family only once
1245
+ * the skill declares that family, and no skill does yet.
1246
+ *
1247
+ * Reads only — it never touches `injected`, a counter or a send. That is the
1248
+ * whole point of the ordering in before_agent_start: this step cannot move the
1249
+ * suggestion, and the suggestion cannot move the verdict.
1250
+ */
1251
+ function stepApplicability(
1252
+ ctx: ExtensionContext,
1253
+ state: AutoInjectState,
1254
+ skills: CachedSkill[],
1255
+ prompt: string,
1256
+ ): void {
1257
+ const evaluation = evaluateApplicability(skills, prompt);
1258
+ const app = state.applicability;
1259
+ const fresh = evaluation.applicable.filter((verdict) => !app.verdicts.has(verdict.name));
1260
+ for (const verdict of fresh) app.verdicts.set(verdict.name, verdict);
1261
+ app.evaluated = evaluation.evaluated;
1262
+ app.undeclared = evaluation.undeclared;
1263
+ app.taskChars = prompt.length;
1264
+
1265
+ if (!app.censusWritten) {
1266
+ const wrote = recordApplicabilityCensus(ctx, {
1267
+ taskChars: app.taskChars,
1268
+ evaluated: app.evaluated,
1269
+ undeclared: app.undeclared,
1270
+ });
1271
+ // A session without an id, or a refused store: retry on the next turn.
1272
+ if (wrote) app.censusWritten = true;
1273
+ }
1274
+ if (!fresh.length) return;
1275
+ log.debug(
1276
+ `[skills-auto-inject] applicability: ${fresh.length} newly applicable, ` +
1277
+ `${evaluation.evaluated} evaluated, ${evaluation.undeclared.length} undeclared`,
1278
+ );
1279
+ for (const verdict of fresh) {
1280
+ recordApplicabilityVerdict(ctx, {
1281
+ skill: verdict.name,
1282
+ applicability: verdict.verdict,
1283
+ evidence: verdict.evidence,
1284
+ });
1285
+ // The obligation row lands with the verdict, not with the first leg: a
1286
+ // session that is merely told which body it owes, and then does nothing,
1287
+ // is the population the rate exists to count. Without this row that
1288
+ // session would be mistaken for one the instrument never saw.
1289
+ legsFor(state, verdict.name);
1290
+ appendObligationRow(ctx, state, verdict.name);
1291
+ }
1292
+ }
1293
+
1294
+ /**
1295
+ * Upgrade an applicable skill to `read` and append its verdict row. A read of a
1296
+ * skill whose declared condition never held gets no row: the three classes are
1297
+ * about skills that applied, and a read is not a fourth one.
1298
+ */
1299
+ function markApplicabilityRead(ctx: ExtensionContext, state: AutoInjectState, name: string): void {
1300
+ const app = state.applicability;
1301
+ const held = app.verdicts.get(name);
1302
+ if (!held || held.verdict === "read") return;
1303
+ app.verdicts.set(name, { ...held, verdict: "read" });
1304
+ recordApplicabilityVerdict(ctx, {
1305
+ skill: name,
1306
+ applicability: "read",
1307
+ evidence: held.evidence,
1308
+ });
1309
+ }
1310
+
1311
+ // Obligation rows (the applied leg)
1312
+
1313
+ /**
1314
+ * The session's legs for one skill, created on first sight. The object is the
1315
+ * snapshot every row carries, so a row states all five legs as of the moment
1316
+ * the leg changed rather than the single delta that triggered the write.
1317
+ */
1318
+ function legsFor(state: AutoInjectState, name: string): ObligationLegs {
1319
+ let legs = state.obligations.legs.get(name);
1320
+ if (!legs) {
1321
+ legs = {
1322
+ skill: name,
1323
+ suggested: false,
1324
+ listed: false,
1325
+ informed: false,
1326
+ read: false,
1327
+ called: false,
1328
+ applied: false,
1329
+ };
1330
+ state.obligations.legs.set(name, legs);
1331
+ }
1332
+ return legs;
1333
+ }
1334
+
1335
+ /**
1336
+ * Append the skill's legs when they changed since the last row. One row per
1337
+ * distinct state rather than one per event: a session that reads the same body
1338
+ * three times, or lists it on every turn, writes one line. A refused write
1339
+ * leaves the signature unset, so the next leg change retries.
1340
+ */
1341
+ function appendObligationRow(ctx: ExtensionContext, state: AutoInjectState, name: string): void {
1342
+ const legs = state.obligations.legs.get(name);
1343
+ if (!legs) return;
1344
+ const signature = [
1345
+ legs.suggested,
1346
+ legs.listed,
1347
+ legs.informed,
1348
+ legs.read,
1349
+ legs.called,
1350
+ legs.applied,
1351
+ ]
1352
+ .map((flag) => (flag ? "1" : "0"))
1353
+ .join("");
1354
+ if (state.obligations.written.get(name) === signature) return;
1355
+ if (!recordObligationLegs(ctx, legs)) return;
1356
+ state.obligations.written.set(name, signature);
1357
+ }
1358
+
1359
+ /** Note one observed leg for a skill and record the row it changed. */
1360
+ function noteObligationLeg(
1361
+ ctx: ExtensionContext,
1362
+ state: AutoInjectState,
1363
+ name: string,
1364
+ leg: "suggested" | "listed" | "read",
1365
+ ): void {
1366
+ if (!name) return;
1367
+ const legs = legsFor(state, name);
1368
+ if (legs[leg]) return;
1369
+ legs[leg] = true;
1370
+ appendObligationRow(ctx, state, name);
1371
+ }
1372
+
1373
+ /**
1374
+ * Record the skills a delivered suggestion offered this session. Called only
1375
+ * after the send was accepted, so the row counts arrivals like the `suggested`
1376
+ * counter does. Never throws: a record is not worth a broken turn.
1377
+ */
1378
+ export function noteObligationSuggested(ctx: ExtensionContext, names: string[]): void {
1379
+ try {
1380
+ const state = getState(ctx);
1381
+ for (const name of names) noteObligationLeg(ctx, state, name, "suggested");
1382
+ } catch (err) {
1383
+ log.debug(`[skills-auto-inject] obligation suggested leg failed (best-effort): ${err}`);
1384
+ }
1385
+ }
1386
+
1387
+ /** Record the skills a catalog page listed (called from the list_skills tool). */
1388
+ export function noteObligationListed(ctx: ExtensionContext, names: string[]): void {
1389
+ try {
1390
+ const state = getState(ctx);
1391
+ for (const name of names) noteObligationLeg(ctx, state, name, "listed");
1392
+ } catch (err) {
1393
+ log.debug(`[skills-auto-inject] obligation listed leg failed (best-effort): ${err}`);
1394
+ }
1395
+ }
1396
+
1154
1397
  // Main Handler
1155
1398
 
1156
1399
  /** The tool_result fields this module reads. */
@@ -1183,10 +1426,135 @@ function detectSkillLoad(
1183
1426
  const held = state.injected.find((i) => i.name === name && i.loadedTurn === undefined);
1184
1427
  if (held) held.loadedTurn = state.currentTurn;
1185
1428
  recordSkillLoad(ctx, name);
1429
+ // The load counters say a read happened; this says whether the session was
1430
+ // one where the skill applied. Independent writes, independent failures.
1431
+ markApplicabilityRead(ctx, state, name);
1432
+ noteObligationLeg(ctx, state, name, "read");
1186
1433
  log.debug(`[skills-auto-inject] counted actual load of "${name}" via read`);
1187
1434
  return name;
1188
1435
  }
1189
1436
 
1437
+ /**
1438
+ * Record a call into a declared family (the applied leg).
1439
+ *
1440
+ * The FIRST call per (session, skill) decides it: a read already on record
1441
+ * means the body came first and the call applies what it says; no read means
1442
+ * the call came first, and no later read can turn that into satisfaction — the
1443
+ * ordering is a fact about what happened, not a state that improves.
1444
+ *
1445
+ * A failed call still counts: a refusal would fire before the tool ran and
1446
+ * could not know the outcome. Skills that declare no family are never reached
1447
+ * here, which is most of them.
1448
+ */
1449
+ function stepFamilyCalls(
1450
+ ctx: ExtensionContext,
1451
+ state: AutoInjectState,
1452
+ event: ToolResultEvent,
1453
+ ): void {
1454
+ const toolName = event?.toolName;
1455
+ if (!toolName) return;
1456
+ const family = toolFamilyToken(toolName);
1457
+ if (!family) return;
1458
+ for (const skill of _skillsCache) {
1459
+ if (!skill.families?.length || !skill.families.includes(family)) continue;
1460
+ if (state.obligations.called.has(skill.name)) continue;
1461
+ const legs = legsFor(state, skill.name);
1462
+ state.obligations.called.add(skill.name);
1463
+ legs.called = true;
1464
+ legs.applied = legs.read;
1465
+ appendObligationRow(ctx, state, skill.name);
1466
+ }
1467
+ }
1468
+
1469
+ /**
1470
+ * The at-use line: the payload names the file and the obligation, and nothing
1471
+ * else.
1472
+ *
1473
+ * Both facts are derivable from the declaration and the catalog entry. The path
1474
+ * is the cached skill's own file path, never constructed; the family is the
1475
+ * token the call's own name yields, which is the same token the declaration is
1476
+ * written in. No skill name is invented in code, no tool argument is echoed,
1477
+ * and there is nothing here for a model to reconcile with the result it just
1478
+ * received. Pure.
1479
+ */
1480
+ export function formatInformPayload(filePath: string, family: string): string {
1481
+ return (
1482
+ `[SKILL INFORM] \`${filePath}\` governs the \`${family}\` tool family; ` +
1483
+ `a call in it just ran, and that file has not been read this session. ` +
1484
+ `Read it before the next call in the family.`
1485
+ );
1486
+ }
1487
+
1488
+ /**
1489
+ * Inform at use: a COMPLETED call landed in a tool family a visible skill's
1490
+ * file declares with `governs:`, and no read of that body is on the session
1491
+ * record. One steer line, once per session per skill.
1492
+ *
1493
+ * This is the timed alternative to refusing the call. It runs after the result
1494
+ * exists, it touches no result, and the only thing it can do is add a line to
1495
+ * the stream; every gating decision below can only make it quieter. The
1496
+ * suppression is the obligation record itself (the `informed` leg, beside the
1497
+ * `read` leg), not a parallel set, so the record that says what the session did
1498
+ * and the record that stops a second line are one row.
1499
+ *
1500
+ * The applied leg counts a failed call because a refusal would fire before the
1501
+ * tool ran and could not know the outcome; this line does not, because its
1502
+ * premise is a call that ran in a family the body governs.
1503
+ */
1504
+ function stepInform(
1505
+ pi: ExtensionAPI,
1506
+ ctx: ExtensionContext,
1507
+ state: AutoInjectState,
1508
+ ev: ToolResultEvent,
1509
+ ): void {
1510
+ state.informMode ??= getSkillsInformMode();
1511
+ if (state.informMode !== "inform") return;
1512
+ if (!ev?.toolName) return;
1513
+ if (ev.isError) return;
1514
+ const family = toolFamilyToken(ev.toolName);
1515
+ if (!family) return;
1516
+ for (const skill of _skillsCache) {
1517
+ // The at-use line is an advertisement with a path: a body the prompt
1518
+ // deliberately hides from the model must not be named by it either.
1519
+ if (skill.disableModelInvocation) continue;
1520
+ if (!skill.families?.length || !skill.families.includes(family)) continue;
1521
+ const held = state.obligations.legs.get(skill.name);
1522
+ if (held?.read) continue; // the body is in context; the obligation is met
1523
+ if (held?.informed) continue; // one line per session per skill
1524
+ const delivered = sendTrackedMessage(
1525
+ pi,
1526
+ {
1527
+ customType: "skills-inform",
1528
+ content: [{ type: "text" as const, text: formatInformPayload(skill.filePath, family) }],
1529
+ display: true,
1530
+ details: {
1531
+ [BRAID_INJECTED]: true,
1532
+ [BRAID_SOURCE]: "skills-auto-inject",
1533
+ skill: skill.name,
1534
+ family,
1535
+ },
1536
+ },
1537
+ { delivery: "park", deliverAs: "steer" },
1538
+ { type: "context", source: "skills-auto-inject" },
1539
+ // The module's own budget is the bound: one line per session per skill,
1540
+ // and only on a call in a family the body itself declares. A flood cap
1541
+ // would drop the line in exactly the call it exists for.
1542
+ { bypassFloodCap: true },
1543
+ );
1544
+ if (!delivered) {
1545
+ log.debug("[skills-auto-inject] at-use line suppressed before delivery; not counted");
1546
+ continue;
1547
+ }
1548
+ const legs = legsFor(state, skill.name);
1549
+ legs.informed = true;
1550
+ appendObligationRow(ctx, state, skill.name);
1551
+ // The line is a skill surface: the drift trigger stays quiet for its
1552
+ // window, because the pointer it exists to supply has just landed.
1553
+ noteDriftSurface(state.drift);
1554
+ log.info(`[skills-auto-inject] at-use line for "${skill.name}" (family ${family})`);
1555
+ }
1556
+ }
1557
+
1190
1558
  /**
1191
1559
  * Fire the drift line when the work has moved into a new work area (the rule
1192
1560
  * and its bounds live in loading-guidance.ts, beside the floor text the line
@@ -1259,6 +1627,13 @@ export function registerAutoInject(pi: ExtensionAPI): void {
1259
1627
  const ev = event as ToolResultEvent;
1260
1628
  const state = getState(ctx);
1261
1629
  if (detectSkillLoad(ev, ctx, state)) noteDriftSurface(state.drift);
1630
+ // A call in a declared family is the applied leg. It runs after the load
1631
+ // detector so a SKILL.md read of the very tool call in flight is already
1632
+ // on record when the family is looked up.
1633
+ stepFamilyCalls(ctx, state, ev);
1634
+ // The at-use line runs after both: it needs the read leg (a read in this
1635
+ // very result silences it) and it does not depend on the applied leg.
1636
+ stepInform(pi, ctx, state, ev);
1262
1637
  stepDrift(pi, ctx, state, ev);
1263
1638
  } catch {
1264
1639
  // best-effort — never break the tool loop over a counter or a whisper
@@ -1316,6 +1691,17 @@ export function registerAutoInject(pi: ExtensionAPI): void {
1316
1691
  return; // No user input to match against
1317
1692
  }
1318
1693
 
1694
+ // Applicability is recorded BEFORE every scoring early-return below.
1695
+ // Most sessions match no skill, and those are exactly the sessions the
1696
+ // adoption counters cannot explain: the returns would erase them. The
1697
+ // step reads the catalog and the prompt only, so the suggestion decision
1698
+ // below is untouched by it (and its failure cannot cost a suggestion).
1699
+ try {
1700
+ stepApplicability(ctx, state, skills, prompt);
1701
+ } catch (err) {
1702
+ log.debug(`[skills-auto-inject] applicability step failed (best-effort): ${err}`);
1703
+ }
1704
+
1319
1705
  // One-shot profile hint: the first non-empty prompt of a session whose
1320
1706
  // configured profile carries a hint gets exactly one steer — the hint
1321
1707
  // text itself, byte-for-byte. Profiles without a hint and sessions
@@ -1432,6 +1818,11 @@ export function registerAutoInject(pi: ExtensionAPI): void {
1432
1818
  ctx,
1433
1819
  skillsToInject.map((s) => s.name),
1434
1820
  );
1821
+ // The same delivery is an obligation leg: the body was offered here.
1822
+ noteObligationSuggested(
1823
+ ctx,
1824
+ skillsToInject.map((s) => s.name),
1825
+ );
1435
1826
  } catch (err) {
1436
1827
  log.debug(`[skills-auto-inject] Error in before_agent_start: ${err}`);
1437
1828
  }
@@ -36,26 +36,35 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
36
36
  import { Type } from "typebox";
37
37
  import type { Static } from "typebox";
38
38
  import { createLogger } from "../../../lib/core/logger.js";
39
- import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
39
+ import { getSkillsInformMode, getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
40
40
  import type { SkillsRankingMode } from "../../../lib/config/braid-settings.js";
41
41
  import {
42
42
  registerAutoInject,
43
43
  updateSkillCache,
44
44
  getSkillStats,
45
45
  getDurableSkillStats,
46
+ noteObligationListed,
46
47
  resolveDiscoveryMode,
47
48
  rankSkillsDeterministic,
48
49
  } from "./auto-inject.js";
49
50
  import type { DeterministicRanking, RankedSkill, RelevanceReason } from "./auto-inject.js";
50
51
  import { readSkillTriggerEntries } from "./skill-triggers.js";
51
52
  import type { TriggerSource } from "./skill-triggers.js";
53
+ import { readGovernedFamilies } from "./skill-families.js";
52
54
  import {
53
55
  clampSectionsMax,
54
56
  DEFAULT_SECTIONS_MAX,
55
57
  SECTIONS_MAX_LIMIT,
56
58
  readSkillReach,
57
59
  } from "./reach.js";
58
- import { getMonthlyAdoptionRollup } from "./session-records.js";
60
+ import {
61
+ getInformRate,
62
+ getMonthlyAdoptionRollup,
63
+ getObligationRate,
64
+ getSessionApplicability,
65
+ getSessionObligation,
66
+ judgeSessionObligations,
67
+ } from "./session-records.js";
59
68
  import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
60
69
 
61
70
  const log = createLogger("skills-tool");
@@ -93,7 +102,15 @@ export function setCachedSkills(skills: CachedSkill[]): void {
93
102
  const entries = readSkillTriggerEntries(s.filePath, s.description);
94
103
  const triggerSources: Record<string, TriggerSource> = {};
95
104
  for (const entry of entries) triggerSources[entry.phrase] = entry.source;
96
- return { ...s, triggers: entries.map((entry) => entry.phrase), triggerSources };
105
+ return {
106
+ ...s,
107
+ triggers: entries.map((entry) => entry.phrase),
108
+ triggerSources,
109
+ // The families the file says its advice directs, resolved from the same
110
+ // frontmatter read the phrases come from (one extra parse per file per
111
+ // process). An empty list is a declaration of no family, not a miss.
112
+ families: readGovernedFamilies(s.filePath),
113
+ };
97
114
  });
98
115
  // Sync with auto-inject subsystem (enriched cache — triggers ride along)
99
116
  updateSkillCache(cachedSkills);
@@ -348,6 +365,14 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
348
365
  ...(answer.relevance.has(s.name) ? { relevance: answer.relevance.get(s.name) } : {}),
349
366
  }));
350
367
 
368
+ // A listed row is one of the session's obligation legs: the catalog is
369
+ // where a body becomes findable without a whisper. Recorded before the
370
+ // response is built so the row and the page describe the same read.
371
+ noteObligationListed(
372
+ ctx,
373
+ skills.map((s) => s.name),
374
+ );
375
+
351
376
  return {
352
377
  content: [
353
378
  {
@@ -417,6 +442,49 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
417
442
  }
418
443
  const monthly = getMonthlyAdoptionRollup();
419
444
  const discovery = resolveDiscoveryMode(ctx);
445
+ // The session's skill verdicts (read | ignored, plus the not-applicable
446
+ // remainder of the census) from the durable record, never from memory:
447
+ // the point of the record is that it outlives the turn that saw it.
448
+ // Absent when the session wrote none — an older store, or a session that
449
+ // never reached a task text — so an exhausted reader of the old counters
450
+ // keeps byte-identical output. Only the verdict classes are summarized in
451
+ // details; the full evidence stays in the text payload.
452
+ const recorded = getSessionApplicability(ctx);
453
+ const applicability = recorded
454
+ ? {
455
+ taskChars: recorded.taskChars,
456
+ evaluated: recorded.evaluated,
457
+ undeclared: recorded.undeclared,
458
+ classes: recorded.classes,
459
+ verdicts: recorded.verdicts,
460
+ updatedAt: recorded.updatedAt,
461
+ }
462
+ : undefined;
463
+ // The session's obligation legs and its boolean: what the session did
464
+ // with the bodies whose conditions held. Absent when the session has no
465
+ // leg row, so a store this build never wrote to reads byte for byte as
466
+ // it did before (the same rule the applicability block above follows).
467
+ const legRecord = getSessionObligation(ctx);
468
+ const judgement = judgeSessionObligations(recorded, legRecord);
469
+ const obligations =
470
+ judgement && legRecord && legRecord.skills.length
471
+ ? {
472
+ allSatisfied: judgement.allSatisfied,
473
+ obligations: judgement.obligations,
474
+ skills: judgement.skills,
475
+ }
476
+ : undefined;
477
+ // Both rates over one population, or absent while the store carries no
478
+ // obligation row at all: a build that predates the leg reads the same
479
+ // sessions and must see the same payload.
480
+ const obligationRate = getObligationRate();
481
+ // The at-use line's counters, folded from the same store as the channel
482
+ // arm beside them. Absent when the mode is off and no row was ever
483
+ // written, so a reader of a pre-inform store is unchanged.
484
+ const informRate = getInformRate();
485
+ const informMode = getSkillsInformMode();
486
+ const inform =
487
+ informMode !== "off" || informRate ? { mode: informMode, ...informRate } : undefined;
420
488
  return {
421
489
  content: [
422
490
  {
@@ -437,6 +505,10 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
437
505
  suggestedEpoch: suggestedMixed === 0 ? "delivered" : "mixed",
438
506
  },
439
507
  monthly,
508
+ ...(applicability ? { applicability } : {}),
509
+ ...(obligations ? { obligations } : {}),
510
+ ...(obligationRate ? { obligationRate } : {}),
511
+ ...(inform ? { inform } : {}),
440
512
  discovery: {
441
513
  // Whether the stock skill catalog sits in the persisted
442
514
  // transcript (it re-enters via pi's post-compaction
@@ -458,6 +530,27 @@ export default function skillsToolExtension(pi: ExtensionAPI): void {
458
530
  allTimeSkills: Object.keys(allTime).length,
459
531
  allTimeTotals: { ...totals, suggestedDelivered, suggestedMixed },
460
532
  monthly,
533
+ ...(applicability ? { applicability: applicability.classes } : {}),
534
+ ...(obligations
535
+ ? {
536
+ obligations: {
537
+ allSatisfied: obligations.allSatisfied,
538
+ count: obligations.obligations,
539
+ },
540
+ }
541
+ : {}),
542
+ ...(obligationRate ? { obligationRate } : {}),
543
+ ...(inform
544
+ ? {
545
+ inform: {
546
+ mode: informMode,
547
+ informs: informRate?.informs ?? 0,
548
+ readFollowed: informRate?.readFollowed ?? 0,
549
+ conversion: informRate?.conversion ?? 0,
550
+ verdict: informRate?.verdict ?? "undecided",
551
+ },
552
+ }
553
+ : {}),
461
554
  },
462
555
  };
463
556
  },
@@ -37,6 +37,7 @@
37
37
  */
38
38
 
39
39
  import { isAbsolute, relative, resolve, sep } from "node:path";
40
+ import { toolFamilyToken } from "./skill-families.js";
40
41
 
41
42
  /** One visible skill as the floor renders it. */
42
43
  export interface CatalogEntry {
@@ -158,7 +159,7 @@ export function mechanicalTriggerExamples(toolNames: string[], skillNames: strin
158
159
  // Family token (lowercased) -> lexicographically smallest active tool name.
159
160
  const familyTool = new Map<string, string>();
160
161
  for (const tool of toolNames) {
161
- const family = tool.split("_")[0].toLowerCase();
162
+ const family = toolFamilyToken(tool);
162
163
  const incumbent = familyTool.get(family);
163
164
  if (incumbent === undefined || tool < incumbent) familyTool.set(family, tool);
164
165
  }
@@ -345,7 +346,10 @@ export function recordDriftDrop(tracker: DriftTracker): void {
345
346
  tracker.entries = {};
346
347
  }
347
348
 
348
- /** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
349
+ /**
350
+ * Note that a skill surface (a suggestion, an at-use line, or a SKILL.md read)
351
+ * just landed.
352
+ */
349
353
  export function noteDriftSurface(tracker: DriftTracker): void {
350
354
  tracker.lastSurface = tracker.calls;
351
355
  }