pi-braid 0.43.7 → 0.43.9

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 (64) hide show
  1. package/CHANGELOG.md +72 -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/auto-inject.d.ts +21 -0
  6. package/dist/extensions/core/skills-tool/auto-inject.js +105 -1
  7. package/dist/extensions/core/skills-tool/index.js +20 -2
  8. package/dist/extensions/core/skills-tool/loading-guidance.d.ts +4 -1
  9. package/dist/extensions/core/skills-tool/loading-guidance.js +4 -1
  10. package/dist/extensions/core/skills-tool/session-records.d.ts +107 -9
  11. package/dist/extensions/core/skills-tool/session-records.js +141 -5
  12. package/dist/extensions/enforcement/handlers/analysis/dreamer-handler.js +5 -1
  13. package/dist/extensions/enforcement/handlers/register-tool-call.js +5 -2
  14. package/dist/extensions/enforcement/verification-judge.d.ts +7 -0
  15. package/dist/extensions/enforcement/verification-judge.js +28 -21
  16. package/dist/extensions/memory/session-recall/ask.d.ts +95 -0
  17. package/dist/extensions/memory/session-recall/ask.js +376 -0
  18. package/dist/extensions/memory/session-recall/corpus-index.d.ts +200 -0
  19. package/dist/extensions/memory/session-recall/corpus-index.js +480 -0
  20. package/dist/extensions/memory/session-recall/index.js +173 -21
  21. package/dist/extensions/memory/session-recall/search.d.ts +29 -0
  22. package/dist/extensions/memory/session-recall/search.js +42 -9
  23. package/dist/lib/ai/payload-hygiene.d.ts +3 -0
  24. package/dist/lib/ai/payload-hygiene.js +34 -2
  25. package/dist/lib/config/braid-paths.d.ts +4 -0
  26. package/dist/lib/config/braid-paths.js +6 -0
  27. package/dist/lib/config/braid-settings.d.ts +44 -0
  28. package/dist/lib/config/braid-settings.js +41 -0
  29. package/dist/lib/detection/tool-loop-detector.d.ts +95 -46
  30. package/dist/lib/detection/tool-loop-detector.js +288 -180
  31. package/dist/lib/memory/constants.d.ts +38 -0
  32. package/dist/lib/memory/constants.js +196 -0
  33. package/dist/lib/memory/index.js +49 -10
  34. package/dist/lib/memory/lifecycle.d.ts +8 -0
  35. package/dist/lib/memory/lifecycle.js +43 -18
  36. package/dist/lib/reasoning/dreamer.d.ts +2 -1
  37. package/dist/lib/reasoning/dreamer.js +12 -7
  38. package/docs/LOCAL_DEV.md +1 -1
  39. package/docs/SETUP.md +2 -0
  40. package/package.json +1 -1
  41. package/src/extensions/core/AGENTS.md +3 -2
  42. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  43. package/src/extensions/core/skills-tool/auto-inject.ts +118 -1
  44. package/src/extensions/core/skills-tool/index.ts +21 -1
  45. package/src/extensions/core/skills-tool/loading-guidance.ts +4 -1
  46. package/src/extensions/core/skills-tool/session-records.ts +201 -9
  47. package/src/extensions/enforcement/handlers/analysis/dreamer-handler.ts +5 -1
  48. package/src/extensions/enforcement/handlers/register-tool-call.ts +5 -2
  49. package/src/extensions/enforcement/verification-judge.ts +32 -25
  50. package/src/extensions/memory/AGENTS.md +2 -2
  51. package/src/extensions/memory/session-recall/AGENTS.md +92 -18
  52. package/src/extensions/memory/session-recall/ask.ts +435 -0
  53. package/src/extensions/memory/session-recall/corpus-index.ts +609 -0
  54. package/src/extensions/memory/session-recall/index.ts +202 -21
  55. package/src/extensions/memory/session-recall/search.ts +61 -10
  56. package/src/lib/ai/payload-hygiene.ts +47 -3
  57. package/src/lib/config/braid-paths.ts +7 -0
  58. package/src/lib/config/braid-settings.ts +93 -3
  59. package/src/lib/detection/AGENTS.md +8 -7
  60. package/src/lib/detection/tool-loop-detector.ts +339 -195
  61. package/src/lib/memory/constants.ts +202 -0
  62. package/src/lib/memory/index.ts +59 -8
  63. package/src/lib/memory/lifecycle.ts +50 -16
  64. package/src/lib/reasoning/dreamer.ts +13 -6
package/CHANGELOG.md CHANGED
@@ -53,6 +53,78 @@ record; the tag scheme above applies unchanged.
53
53
 
54
54
  ---
55
55
 
56
+ ## Core — 0.43.9 (2026-10-31: a query is read as tokens, and the store can be told what to keep)
57
+
58
+ - **A question could not match a word it contained.** Recall split a query on whitespace alone, so a
59
+ question ending in `APIs?` carried the token `apis?` and never matched the stored word `apis`: the
60
+ content was invisible to the matcher, and no amount of weighting could reach it, because a token the
61
+ matcher cannot see cannot be weighted. Measured on a 260-entry store, that single defect kept a correct
62
+ answer out of a five-item result list entirely; it now returns at rank one. The query is tokenized on
63
+ non-alphanumeric characters as well as whitespace, and the test plants the revert: restoring the old
64
+ splitter reddens exactly the punctuation case and nothing else.
65
+ - **Function words stop counting as evidence, and rare words start.** Every query word longer than two
66
+ characters scored the same, so `which`, `should` and `when` each counted as a hit and a long entry
67
+ outranked a short precise one. A generic English stop list and `idf(w) = ln(1 + N/df)` now weight the
68
+ terms, and the effect was measured against a control of five ordinary entries chosen by margin rather
69
+ than by taste: all five hold rank one, and the leader-to-runner-up margins widen from 1.10–1.92× to
70
+ 2.06–3.55×. The honest attribution is in the report: the stop list and the weights alone moved no rank,
71
+ because tokenization was the defect; they sharpen what tokenization made reachable.
72
+ - **What the store keeps can be configured, and by default nothing changes.** `pruneMemories` ordered
73
+ every entry by utility alone, so a backfilled provenance entry scored 0.53 against a floor of 0.605 and
74
+ a prune one hour after the write kept four of sixty. A reserved partition — entries whose `source`
75
+ starts with a configured prefix may occupy up to a configured number of slots — ships **off**, and with
76
+ nothing configured the prune returns an element-identical id sequence to the previous build at one
77
+ minute, one hour and one day after the write. Configured at twenty slots it keeps twenty of sixty, and
78
+ the cost is stated rather than hidden: twenty ordinary entries leave the store, the reserve is a hard
79
+ cap rather than a home for all sixty, and which twenty survive among utility ties is the shipped
80
+ comparator's order, not anything about the entry.
81
+ - **The retrieval goal it was aimed at is one third reached, and the reason is not lexical.** Ten questions
82
+ were pre-registered; a presence scan then showed only three of them name an answer that both exists in
83
+ the corpus and survives the classifier, so the ceiling for any reordering was three. One is now at rank
84
+ one. The second cannot be reached by any scoring change: the winner and the correct ruling match exactly
85
+ the same two query terms, and the 1.5× gap is utility (0.815 against 0.670) plus a project boost the
86
+ ruling cannot earn plus an access boost its rival has. That is a policy question about provenance
87
+ entries, not a ranking question, and it is named here so the next change starts from the measurement.
88
+
89
+ ## Core — 0.43.8 (2026-10-31: the harness stops accusing work that happened, and starts answering from the archive)
90
+
91
+ - **An unterminated page cannot delete the evidence tail any more.** A redaction of a detected HTML page
92
+ ended at the end of the whole outbound prompt whenever the page arrived without its closing tag, and that
93
+ sanitizer runs on every internal LLM body, judges included. One unterminated page inside one tool result
94
+ deleted 85 of 140 evidence lines and all four ground-truth sections before the model saw them, and a
95
+ verification judge, whose schema has no way to say "cannot verify", then reported work-not-done against a
96
+ delivered project. The span now ends at the end of the enclosing line or at a page cap far above any
97
+ observed page, whichever comes first, and a clamped span logs one line naming the byte count so a tail loss
98
+ is visible instead of silent. The judge's prompt also puts git history, the deliverables manifest and the
99
+ code-changes flag ahead of the bounded sections, so a future bound degrades evidence rather than truth. The
100
+ module had no test before; it has one now, and it carries both directions, including the control that an
101
+ oversized unterminated page is still redacted up to the cap.
102
+ - **The loop whisper counts calls, not tool names.** The detector kept an array of tool names and fired on
103
+ sixteen consecutive equal names, so a chain of seventeen different shell commands was indistinguishable from
104
+ seventeen identical retries, and the message claimed "no progress" while looking at nothing but names. In
105
+ the archive that whisper appears in 485 of 2,526 sessions, and both owner-run sessions examined were false
106
+ accusations: twenty distinct commands in one, seventeen in the other. A call now has an identity (name plus
107
+ normalized arguments); consecutive identical calls still fire, two alternating calls still fire, a long
108
+ chain of distinct calls never does, and the sentence names the repeated call and its count instead of
109
+ claiming progress it cannot observe.
110
+ - **The archive's own words are queryable.** Every user turn in the session corpus is a quarter of one
111
+ percent of it: 20,484 turns totalling 9.66 MB across 3,833 sessions and 341 projects, out of an archive of
112
+ 3.8 GB. A derived index of exactly those turns is built in under two seconds and refreshed by file mtime, and
113
+ a `session ask` verb answers a question from them with citations, excluding the calling session by
114
+ construction. Recall at three is eight of ten on a pre-registered question set, with both misses shown and
115
+ mechanised, and the two existing search verbs are byte-identical when the index is absent.
116
+ - **A skill names the family it governs, and the harness says so once, after the call.** A refusal was
117
+ designed, measured and killed: simulated over 703 sessions and 107,463 tool calls, 2 of 30 refused calls
118
+ changed course. The mechanism that ships instead is an at-use inform, one line after a completed call in a
119
+ declared family when the body was never read, off by default, with its falsifier pre-registered: it must beat
120
+ the suggestion channel's own 18.8% read-follow conversion or it is noise to be deleted. Its own verdict is
121
+ undecided at zero informs, and 20 informs with 8 conversions is what would decide it.
122
+ - **The obligation rate exists and discriminates.** Per session and per skill, `suggested`, `listed`, `read`,
123
+ `called`, `applied`, where a call made before the read cannot be credited and a read with no call still
124
+ satisfies; an applicable skill with no leg row is counted unsatisfied rather than dropped. `allSatisfied`
125
+ over the sessions that carry both a verdict and a leg row, reported beside the read rate with that
126
+ denominator stated rather than implied, and a gap under five points marks the metric as worthless.
127
+
56
128
  ## Core — 0.43.7 (2026-10-30: an ignored skill is visible, and two rates say whether the obligation held)
57
129
 
58
130
  - **A skill that applied and was ignored is now distinguishable from one that never applied.** The
package/TOOLS.md CHANGED
@@ -75,7 +75,7 @@ enablement (see appendix).
75
75
  | `memory` | Unified memory: recall/episodes/heuristics | memory-agent-bridge - default-enabled (manifest.ts:197) | when: before non-trivial work — build on known context; args: action recall_search / episodes_search / heuristics_list + query |
76
76
  | `explore_paths` | Per-hypothesis file search with first-15-lines evidence | memory-agent-bridge - default-enabled (manifest.ts:197) | when: debugging with a named failure-mode hypothesis; args: hypothesis_1/2/3, each 'file because reason'; caveat: local search — no sub-agent |
77
77
  | `conflict_qa` | Resolve contradictions between sources via the evidence pool | memory-agent-bridge - default-enabled (manifest.ts:197) | when: sources or beliefs contradict; args: action resolve + verdict; caveat: evidence-pool based, reports classification |
78
- | `session` | Access past session history (search/query/analyze/stats/context) | session-recall - default-enabled (manifest.ts:176, dep three-memory-stores) | when: prior-work context needed across sessions (search/query/analyze/stats); args: action + query/sessionPath; caveat: project-scoped by default |
78
+ | `session` | Access past session history: search/ask/query/analyze/stats/context | session-recall - default-enabled (manifest.ts:176, dep three-memory-stores) | when: prior-work context needed across sessions (search/query/analyze/stats), or a question about what was said or decided earlier (ask, which cites project, session, line and time); args: action + query/sessionPath; caveat: project-scoped by default, and ask refuses when the corpus index cannot answer |
79
79
  | `error` | Inspect captured extension errors (list/get/clear/stats) | error-tracking - opt-in, disabledByDefault (manifest.ts:276) | when: a tool or extension failed and you need the captured error history; args: action list/get/clear/stats |
80
80
  | `session_health` | Read/reset session LLM-provider health state | health-maintenance - opt-in, disabledByDefault (manifest.ts:259) | when: provider errors / auth / balance events occurred; args: action get/diagnose/recover; caveat: recover only after the user acted |
81
81
  | `health_maintenance` | Health-based maintenance (check/commit/rollback/benchmark) | health-maintenance - opt-in, disabledByDefault (manifest.ts:259) | when: agent self-state hygiene (check/commit/rollback/benchmark); args: action; caveat: rollback needs a checkpoint hash |
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.7",
4
- "sha": "202c7b26bdcfe036b330cde4d98470951553502f",
5
- "shaShort": "202c7b26",
3
+ "version": "0.43.9",
4
+ "sha": "bce25581c535c3a318787d6c3a12b6beb76ff7ca",
5
+ "shaShort": "bce25581",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-30T08:48:55.796Z"
8
+ "packedAt": "2026-10-31T15:50:23.130Z"
9
9
  }
@@ -91,7 +91,7 @@ export const TOOL_GUIDELINES = {
91
91
  explore_paths: "when: debugging with a named failure-mode hypothesis; args: hypothesis_1/2/3, each 'file because reason'; caveat: local search — no sub-agent",
92
92
  conflict_qa: "when: sources or beliefs contradict; args: action resolve + verdict; caveat: evidence-pool based, reports classification",
93
93
  // ── session-recall (default-enabled) ──
94
- session: "when: prior-work context needed across sessions (search/query/analyze/stats); args: action + query/sessionPath; caveat: project-scoped by default",
94
+ session: "when: prior-work context needed across sessions (search/query/analyze/stats), or a question about what was said or decided earlier (ask, which cites project, session, line and time); args: action + query/sessionPath; caveat: project-scoped by default, and ask refuses when the corpus index cannot answer",
95
95
  // ── error-tracking (opt-in) ──
96
96
  error: "when: a tool or extension failed and you need the captured error history; args: action list/get/clear/stats",
97
97
  // ── health-maintenance (opt-in) ──
@@ -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.
@@ -507,6 +516,18 @@ export declare function resolveDiscoveryMode(ctx: ExtensionContext): DiscoverySt
507
516
  export declare function noteObligationSuggested(ctx: ExtensionContext, names: string[]): void;
508
517
  /** Record the skills a catalog page listed (called from the list_skills tool). */
509
518
  export declare function noteObligationListed(ctx: ExtensionContext, names: string[]): void;
519
+ /**
520
+ * The at-use line: the payload names the file and the obligation, and nothing
521
+ * else.
522
+ *
523
+ * Both facts are derivable from the declaration and the catalog entry. The path
524
+ * is the cached skill's own file path, never constructed; the family is the
525
+ * token the call's own name yields, which is the same token the declaration is
526
+ * written in. No skill name is invented in code, no tool argument is echoed,
527
+ * and there is nothing here for a model to reconcile with the result it just
528
+ * received. Pure.
529
+ */
530
+ export declare function formatInformPayload(filePath: string, family: string): string;
510
531
  /**
511
532
  * Register the auto-inject handler on before_agent_start, the read-tool load
512
533
  * detector and the drift trigger on tool_result.
@@ -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,6 +125,7 @@ import { getSessionProfile, recordApplicabilityCensus, recordApplicabilityVerdic
116
125
  import { evaluateApplicability } from "./applicability.js";
117
126
  import { triggerMatches } from "./skill-triggers.js";
118
127
  import { toolFamilyToken } from "./skill-families.js";
128
+ import { getSkillsInformMode } from "../../../lib/config/braid-settings.js";
119
129
  import { advanceDrift, driftDirectoryFor, driftPayload, initialDrift, noteDriftSurface, recordDriftDrop, recordDriftFire, skillReadRoot, } from "./loading-guidance.js";
120
130
  const log = createLogger("skills-auto-inject");
121
131
  // Constants
@@ -1010,6 +1020,7 @@ function legsFor(state, name) {
1010
1020
  skill: name,
1011
1021
  suggested: false,
1012
1022
  listed: false,
1023
+ informed: false,
1013
1024
  read: false,
1014
1025
  called: false,
1015
1026
  applied: false,
@@ -1028,7 +1039,14 @@ function appendObligationRow(ctx, state, name) {
1028
1039
  const legs = state.obligations.legs.get(name);
1029
1040
  if (!legs)
1030
1041
  return;
1031
- const signature = [legs.suggested, legs.listed, legs.read, legs.called, legs.applied]
1042
+ const signature = [
1043
+ legs.suggested,
1044
+ legs.listed,
1045
+ legs.informed,
1046
+ legs.read,
1047
+ legs.called,
1048
+ legs.applied,
1049
+ ]
1032
1050
  .map((flag) => (flag ? "1" : "0"))
1033
1051
  .join("");
1034
1052
  if (state.obligations.written.get(name) === signature)
@@ -1133,6 +1151,89 @@ function stepFamilyCalls(ctx, state, event) {
1133
1151
  appendObligationRow(ctx, state, skill.name);
1134
1152
  }
1135
1153
  }
1154
+ /**
1155
+ * The at-use line: the payload names the file and the obligation, and nothing
1156
+ * else.
1157
+ *
1158
+ * Both facts are derivable from the declaration and the catalog entry. The path
1159
+ * is the cached skill's own file path, never constructed; the family is the
1160
+ * token the call's own name yields, which is the same token the declaration is
1161
+ * written in. No skill name is invented in code, no tool argument is echoed,
1162
+ * and there is nothing here for a model to reconcile with the result it just
1163
+ * received. Pure.
1164
+ */
1165
+ export function formatInformPayload(filePath, family) {
1166
+ return (`[SKILL INFORM] \`${filePath}\` governs the \`${family}\` tool family; ` +
1167
+ `a call in it just ran, and that file has not been read this session. ` +
1168
+ `Read it before the next call in the family.`);
1169
+ }
1170
+ /**
1171
+ * Inform at use: a COMPLETED call landed in a tool family a visible skill's
1172
+ * file declares with `governs:`, and no read of that body is on the session
1173
+ * record. One steer line, once per session per skill.
1174
+ *
1175
+ * This is the timed alternative to refusing the call. It runs after the result
1176
+ * exists, it touches no result, and the only thing it can do is add a line to
1177
+ * the stream; every gating decision below can only make it quieter. The
1178
+ * suppression is the obligation record itself (the `informed` leg, beside the
1179
+ * `read` leg), not a parallel set, so the record that says what the session did
1180
+ * and the record that stops a second line are one row.
1181
+ *
1182
+ * The applied leg counts a failed call because a refusal would fire before the
1183
+ * tool ran and could not know the outcome; this line does not, because its
1184
+ * premise is a call that ran in a family the body governs.
1185
+ */
1186
+ function stepInform(pi, ctx, state, ev) {
1187
+ state.informMode ??= getSkillsInformMode();
1188
+ if (state.informMode !== "inform")
1189
+ return;
1190
+ if (!ev?.toolName)
1191
+ return;
1192
+ if (ev.isError)
1193
+ return;
1194
+ const family = toolFamilyToken(ev.toolName);
1195
+ if (!family)
1196
+ return;
1197
+ for (const skill of _skillsCache) {
1198
+ // The at-use line is an advertisement with a path: a body the prompt
1199
+ // deliberately hides from the model must not be named by it either.
1200
+ if (skill.disableModelInvocation)
1201
+ continue;
1202
+ if (!skill.families?.length || !skill.families.includes(family))
1203
+ continue;
1204
+ const held = state.obligations.legs.get(skill.name);
1205
+ if (held?.read)
1206
+ continue; // the body is in context; the obligation is met
1207
+ if (held?.informed)
1208
+ continue; // one line per session per skill
1209
+ const delivered = sendTrackedMessage(pi, {
1210
+ customType: "skills-inform",
1211
+ content: [{ type: "text", text: formatInformPayload(skill.filePath, family) }],
1212
+ display: true,
1213
+ details: {
1214
+ [BRAID_INJECTED]: true,
1215
+ [BRAID_SOURCE]: "skills-auto-inject",
1216
+ skill: skill.name,
1217
+ family,
1218
+ },
1219
+ }, { delivery: "park", deliverAs: "steer" }, { type: "context", source: "skills-auto-inject" },
1220
+ // The module's own budget is the bound: one line per session per skill,
1221
+ // and only on a call in a family the body itself declares. A flood cap
1222
+ // would drop the line in exactly the call it exists for.
1223
+ { bypassFloodCap: true });
1224
+ if (!delivered) {
1225
+ log.debug("[skills-auto-inject] at-use line suppressed before delivery; not counted");
1226
+ continue;
1227
+ }
1228
+ const legs = legsFor(state, skill.name);
1229
+ legs.informed = true;
1230
+ appendObligationRow(ctx, state, skill.name);
1231
+ // The line is a skill surface: the drift trigger stays quiet for its
1232
+ // window, because the pointer it exists to supply has just landed.
1233
+ noteDriftSurface(state.drift);
1234
+ log.info(`[skills-auto-inject] at-use line for "${skill.name}" (family ${family})`);
1235
+ }
1236
+ }
1136
1237
  /**
1137
1238
  * Fire the drift line when the work has moved into a new work area (the rule
1138
1239
  * and its bounds live in loading-guidance.ts, beside the floor text the line
@@ -1195,6 +1296,9 @@ export function registerAutoInject(pi) {
1195
1296
  // detector so a SKILL.md read of the very tool call in flight is already
1196
1297
  // on record when the family is looked up.
1197
1298
  stepFamilyCalls(ctx, state, ev);
1299
+ // The at-use line runs after both: it needs the read leg (a read in this
1300
+ // very result silences it) and it does not depend on the applied leg.
1301
+ stepInform(pi, ctx, state, ev);
1198
1302
  stepDrift(pi, ctx, state, ev);
1199
1303
  }
1200
1304
  catch {
@@ -33,12 +33,12 @@
33
33
  */
34
34
  import { Type } from "typebox";
35
35
  import { createLogger } from "../../../lib/core/logger.js";
36
- import { getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
36
+ import { getSkillsInformMode, getSkillsRankingMode } from "../../../lib/config/braid-settings.js";
37
37
  import { registerAutoInject, updateSkillCache, getSkillStats, getDurableSkillStats, noteObligationListed, resolveDiscoveryMode, rankSkillsDeterministic, } from "./auto-inject.js";
38
38
  import { readSkillTriggerEntries } from "./skill-triggers.js";
39
39
  import { readGovernedFamilies } from "./skill-families.js";
40
40
  import { clampSectionsMax, DEFAULT_SECTIONS_MAX, SECTIONS_MAX_LIMIT, readSkillReach, } from "./reach.js";
41
- import { getMonthlyAdoptionRollup, getObligationRate, getSessionApplicability, getSessionObligation, judgeSessionObligations, } from "./session-records.js";
41
+ import { getInformRate, getMonthlyAdoptionRollup, getObligationRate, getSessionApplicability, getSessionObligation, judgeSessionObligations, } from "./session-records.js";
42
42
  import { checkArgumentValues } from "../../../lib/utils/argument-report.js";
43
43
  const log = createLogger("skills-tool");
44
44
  let cachedSkills = [];
@@ -358,6 +358,12 @@ export default function skillsToolExtension(pi) {
358
358
  // obligation row at all: a build that predates the leg reads the same
359
359
  // sessions and must see the same payload.
360
360
  const obligationRate = getObligationRate();
361
+ // The at-use line's counters, folded from the same store as the channel
362
+ // arm beside them. Absent when the mode is off and no row was ever
363
+ // written, so a reader of a pre-inform store is unchanged.
364
+ const informRate = getInformRate();
365
+ const informMode = getSkillsInformMode();
366
+ const inform = informMode !== "off" || informRate ? { mode: informMode, ...informRate } : undefined;
361
367
  return {
362
368
  content: [
363
369
  {
@@ -380,6 +386,7 @@ export default function skillsToolExtension(pi) {
380
386
  ...(applicability ? { applicability } : {}),
381
387
  ...(obligations ? { obligations } : {}),
382
388
  ...(obligationRate ? { obligationRate } : {}),
389
+ ...(inform ? { inform } : {}),
383
390
  discovery: {
384
391
  // Whether the stock skill catalog sits in the persisted
385
392
  // transcript (it re-enters via pi's post-compaction
@@ -408,6 +415,17 @@ export default function skillsToolExtension(pi) {
408
415
  }
409
416
  : {}),
410
417
  ...(obligationRate ? { obligationRate } : {}),
418
+ ...(inform
419
+ ? {
420
+ inform: {
421
+ mode: informMode,
422
+ informs: informRate?.informs ?? 0,
423
+ readFollowed: informRate?.readFollowed ?? 0,
424
+ conversion: informRate?.conversion ?? 0,
425
+ verdict: informRate?.verdict ?? "undecided",
426
+ },
427
+ }
428
+ : {}),
411
429
  },
412
430
  };
413
431
  },
@@ -160,7 +160,10 @@ export declare function recordDriftFire(tracker: DriftTracker, directory: string
160
160
  * a suppressed line is retried only after the session has done more work.
161
161
  */
162
162
  export declare function recordDriftDrop(tracker: DriftTracker): void;
163
- /** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
163
+ /**
164
+ * Note that a skill surface (a suggestion, an at-use line, or a SKILL.md read)
165
+ * just landed.
166
+ */
164
167
  export declare function noteDriftSurface(tracker: DriftTracker): void;
165
168
  /**
166
169
  * The one-line steer: the work area and a pointer back at the catalog in the
@@ -298,7 +298,10 @@ export function recordDriftDrop(tracker) {
298
298
  tracker.lastFire = tracker.calls;
299
299
  tracker.entries = {};
300
300
  }
301
- /** Note that a skill surface (a suggestion or a SKILL.md read) just landed. */
301
+ /**
302
+ * Note that a skill surface (a suggestion, an at-use line, or a SKILL.md read)
303
+ * just landed.
304
+ */
302
305
  export function noteDriftSurface(tracker) {
303
306
  tracker.lastSurface = tracker.calls;
304
307
  }
@@ -237,9 +237,10 @@ export declare function getSessionApplicability(ctx: ExtensionContext, options?:
237
237
  * no family; most declare none, and an obligation that names no family is
238
238
  * satisfied by the read alone.
239
239
  *
240
- * `suggested` and `listed` are the surfaces that made the body findable in
241
- * this session (a delivered suggestion, a list_skills row); they carry the
242
- * "was it offered" half of adoption, which the call facts cannot.
240
+ * `suggested`, `listed` and `informed` are the surfaces that offered the body
241
+ * in this session (a delivered suggestion, a list_skills row, a delivered
242
+ * at-use line); they carry the "was it offered" half of adoption, which the
243
+ * call facts cannot.
243
244
  */
244
245
  export interface ObligationLegRecord {
245
246
  kind: "obligation";
@@ -250,15 +251,18 @@ export interface ObligationLegRecord {
250
251
  skill: string;
251
252
  suggested: boolean;
252
253
  listed: boolean;
254
+ /** An at-use inform was DELIVERED for this body in this session. */
255
+ informed: boolean;
253
256
  read: boolean;
254
257
  called: boolean;
255
258
  applied: boolean;
256
259
  }
257
- /** A record's five legs, read back as one row per skill. */
260
+ /** A record's six legs, read back as one row per skill. */
258
261
  export interface ObligationLegs {
259
262
  skill: string;
260
263
  suggested: boolean;
261
264
  listed: boolean;
265
+ informed: boolean;
262
266
  read: boolean;
263
267
  called: boolean;
264
268
  applied: boolean;
@@ -280,11 +284,11 @@ export declare function normalizeObligationRecord(raw: unknown): ObligationLegRe
280
284
  */
281
285
  export declare function readObligationRecords(storePath?: string): ObligationLegRecord[];
282
286
  /**
283
- * Fold a session's obligation rows into one record: the five legs OR across
284
- * every row, so a row that saw one leg never erases a leg a later row did not
285
- * have. `called`/`applied` are written once per skill, so the OR is exact
286
- * rather than convenient. A torn or duplicated row folds; a malformed one is
287
- * dropped at normalize, before this sees it.
287
+ * Fold a session's obligation rows into one record: the legs OR across every
288
+ * row, so a row that saw one leg never erases a leg a later row did not have.
289
+ * `called`/`applied` are written once per skill, so the OR is exact rather
290
+ * than convenient. A torn or duplicated row folds; a malformed one is dropped
291
+ * at normalize, before this sees it.
288
292
  */
289
293
  export declare function foldObligationRecords(records: ObligationLegRecord[]): SessionObligation[];
290
294
  /**
@@ -371,6 +375,100 @@ export declare function computeObligationRate(sessions: SessionApplicability[],
371
375
  export declare function getObligationRate(options?: {
372
376
  storePath?: string;
373
377
  }): ObligationRate | undefined;
378
+ /**
379
+ * The suggestion channel's pair conversion as published from session-file
380
+ * mining: 95 read-followed pairs out of 506 delivered ones, Wilson 15.6-22.4.
381
+ *
382
+ * It is a measurement constant, not a target: it stands in as the comparison
383
+ * arm only while the same store carries too few suggested pairs of its own to
384
+ * stand on its own (see INFORM_DECISION_MIN_PAIRS). A two-pair store arm that
385
+ * happens to have converted nothing is not a baseline; it is a sample. The
386
+ * moment the store holds the floor of suggested pairs, their own fold answers
387
+ * and this number is not read.
388
+ */
389
+ export declare const CHANNEL_PUBLISHED_CONVERSION = 0.188;
390
+ /** Wilson 95% bounds for that published figure, as proportions. */
391
+ export declare const CHANNEL_PUBLISHED_INTERVAL: WilsonInterval;
392
+ /**
393
+ * Informs needed before the comparison decides anything. Below this the
394
+ * answer is "undecided": a verdict from a handful of pairs would be a verdict
395
+ * about the sample, and the report's decision rule says so in writing before
396
+ * the first inform lands. The same floor governs the comparison arm: a store
397
+ * carrying fewer suggested pairs than this is not a baseline to beat.
398
+ */
399
+ export declare const INFORM_DECISION_MIN_PAIRS = 20;
400
+ /** A two-sided interval on a proportion, both ends in 0-1. */
401
+ export interface WilsonInterval {
402
+ lower: number;
403
+ upper: number;
404
+ }
405
+ /**
406
+ * Wilson score interval for k successes in n trials (95% by default). Chosen
407
+ * over the normal approximation because the inform population is small and a
408
+ * small-sample interval is the only one that can say "undecided" honestly.
409
+ * Returns zeros for n = 0. Pure.
410
+ */
411
+ export declare function wilsonInterval(successes: number, total: number, z?: number): WilsonInterval;
412
+ /** One skill's at-use pairs: informs delivered, and how many a read followed. */
413
+ export interface InformSkillRow {
414
+ skill: string;
415
+ informs: number;
416
+ readFollowed: number;
417
+ }
418
+ /** Where the comparison arm's number came from. */
419
+ export type ChannelBaselineSource = "store" | "published";
420
+ /**
421
+ * The at-use line's numbers beside the suggestion channel's, same store.
422
+ *
423
+ * A pair is (session, skill). An inform pair carries `informed: true`; it
424
+ * converted when that session also carries the `read` leg for the same skill.
425
+ * The read leg is ordered by construction here: a read silences the inform, so
426
+ * a pair that has both legs can only have read after the line landed.
427
+ */
428
+ export interface InformRate {
429
+ /** Inform pairs in the store. */
430
+ informs: number;
431
+ /** Of those, pairs whose session carries the read leg. */
432
+ readFollowed: number;
433
+ /** readFollowed / informs, 4 decimals; 0 when no inform. */
434
+ conversion: number;
435
+ /** Wilson 95% bounds on `conversion`. */
436
+ ci: WilsonInterval;
437
+ /** Per skill, in first-seen order (only skills with an inform). */
438
+ skills: InformSkillRow[];
439
+ /** The comparison arm: the same fold's suggested pairs. */
440
+ channel: {
441
+ pairs: number;
442
+ readFollowed: number;
443
+ conversion: number;
444
+ ci: WilsonInterval;
445
+ source: ChannelBaselineSource;
446
+ };
447
+ /** conversion - channel.conversion, in percentage points, 2 decimals. */
448
+ gapPoints: number;
449
+ /** False below INFORM_DECISION_MIN_PAIRS: no verdict is derivable. */
450
+ decidable: boolean;
451
+ /** undecided | beats | noise (see the report's pre-registered rule). */
452
+ verdict: "undecided" | "beats" | "noise";
453
+ }
454
+ /**
455
+ * Fold the obligation rows into the at-use rate and the channel arm beside it.
456
+ * Pure.
457
+ *
458
+ * The rule, applied literally: fewer than the floor is undecided; at the floor
459
+ * the inform beats the channel only when its point estimate is above the
460
+ * channel's AND its lower Wilson bound is above it too. Anything else at the
461
+ * floor is noise, which is the falsifier firing rather than a neutral result.
462
+ */
463
+ export declare function computeInformRate(obligations: SessionObligation[]): InformRate;
464
+ /**
465
+ * The store-wide at-use rate, or undefined when the store carries no inform row
466
+ * at all. Undefined keeps every existing `skill_stats` payload byte-identical
467
+ * for a build or an install that never emitted one.
468
+ */
469
+ export declare function getInformRate(options?: {
470
+ storePath?: string;
471
+ }): InformRate | undefined;
374
472
  /** Adoption numbers for one profile in one month. */
375
473
  export interface ProfileAdoption {
376
474
  /** Sessions active in the month (records with a turn). */