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
package/CHANGELOG.md CHANGED
@@ -53,6 +53,89 @@ record; the tag scheme above applies unchanged.
53
53
 
54
54
  ---
55
55
 
56
+ ## Core — 0.43.8 (2026-10-31: the harness stops accusing work that happened, and starts answering from the archive)
57
+
58
+ - **An unterminated page cannot delete the evidence tail any more.** A redaction of a detected HTML page
59
+ ended at the end of the whole outbound prompt whenever the page arrived without its closing tag, and that
60
+ sanitizer runs on every internal LLM body, judges included. One unterminated page inside one tool result
61
+ deleted 85 of 140 evidence lines and all four ground-truth sections before the model saw them, and a
62
+ verification judge, whose schema has no way to say "cannot verify", then reported work-not-done against a
63
+ delivered project. The span now ends at the end of the enclosing line or at a page cap far above any
64
+ observed page, whichever comes first, and a clamped span logs one line naming the byte count so a tail loss
65
+ is visible instead of silent. The judge's prompt also puts git history, the deliverables manifest and the
66
+ code-changes flag ahead of the bounded sections, so a future bound degrades evidence rather than truth. The
67
+ module had no test before; it has one now, and it carries both directions, including the control that an
68
+ oversized unterminated page is still redacted up to the cap.
69
+ - **The loop whisper counts calls, not tool names.** The detector kept an array of tool names and fired on
70
+ sixteen consecutive equal names, so a chain of seventeen different shell commands was indistinguishable from
71
+ seventeen identical retries, and the message claimed "no progress" while looking at nothing but names. In
72
+ the archive that whisper appears in 485 of 2,526 sessions, and both owner-run sessions examined were false
73
+ accusations: twenty distinct commands in one, seventeen in the other. A call now has an identity (name plus
74
+ normalized arguments); consecutive identical calls still fire, two alternating calls still fire, a long
75
+ chain of distinct calls never does, and the sentence names the repeated call and its count instead of
76
+ claiming progress it cannot observe.
77
+ - **The archive's own words are queryable.** Every user turn in the session corpus is a quarter of one
78
+ percent of it: 20,484 turns totalling 9.66 MB across 3,833 sessions and 341 projects, out of an archive of
79
+ 3.8 GB. A derived index of exactly those turns is built in under two seconds and refreshed by file mtime, and
80
+ a `session ask` verb answers a question from them with citations, excluding the calling session by
81
+ construction. Recall at three is eight of ten on a pre-registered question set, with both misses shown and
82
+ mechanised, and the two existing search verbs are byte-identical when the index is absent.
83
+ - **A skill names the family it governs, and the harness says so once, after the call.** A refusal was
84
+ designed, measured and killed: simulated over 703 sessions and 107,463 tool calls, 2 of 30 refused calls
85
+ changed course. The mechanism that ships instead is an at-use inform, one line after a completed call in a
86
+ declared family when the body was never read, off by default, with its falsifier pre-registered: it must beat
87
+ the suggestion channel's own 18.8% read-follow conversion or it is noise to be deleted. Its own verdict is
88
+ undecided at zero informs, and 20 informs with 8 conversions is what would decide it.
89
+ - **The obligation rate exists and discriminates.** Per session and per skill, `suggested`, `listed`, `read`,
90
+ `called`, `applied`, where a call made before the read cannot be credited and a read with no call still
91
+ satisfies; an applicable skill with no leg row is counted unsatisfied rather than dropped. `allSatisfied`
92
+ over the sessions that carry both a verdict and a leg row, reported beside the read rate with that
93
+ denominator stated rather than implied, and a gap under five points marks the metric as worthless.
94
+
95
+ ## Core — 0.43.7 (2026-10-30: an ignored skill is visible, and two rates say whether the obligation held)
96
+
97
+ - **A skill that applied and was ignored is now distinguishable from one that never applied.** The
98
+ subsystem could tell whether an agent read a skill and could not tell whether it should have. It now
99
+ records, per session and per skill, a verdict with the phrase that decided it and where the skill
100
+ declares it: `read`, `ignored`, or `not-applicable`, plus a census row naming the installed skills whose
101
+ files declare no condition at all. The record is additive by construction: a new record kind on the
102
+ existing store, refused by the adoption reader so the two cannot silently merge, and an existing
103
+ reader's output is byte-identical when the record is absent. `ignored` over `read + ignored` is the
104
+ rate nobody could compute before, and it is computable from the record alone.
105
+ - **The condition is the author's own declaration, not a coincidence.** Applicability reads the trigger
106
+ phrases the injector already matches, with the injector's own word-boundary rule, so the verdict can
107
+ never disagree with the whisper about whether a phrase is present; 1,098 phrase/text pairs over both
108
+ installed packs were checked for that agreement. The addition is polarity: "do not research this" is a
109
+ session where research did not apply. The negation rule is one cue, not a composed one, so a double
110
+ negative reads as negation and the ignored rate is a lower bound; that is pinned by a test with its
111
+ reason rather than left as a surprise.
112
+ - **A skill declares the tool family its body directs, and the session records what it did with it.** Three
113
+ of the shipped skills declare a family, five declare none because a body that governs no tool family
114
+ genuinely has none, and the contract reports both numbers rather than padding the count. The per-session
115
+ leg records `suggested`, `listed`, `read`, `called`, `applied`, where `applied` is ordered: a call made
116
+ before the read cannot be credited, and a read with no call still satisfies. An applicable skill with no
117
+ leg row is counted unsatisfied rather than dropped, which keeps the ignored population inside the
118
+ denominator.
119
+ - **The obligation rate ships with its own falsifier.** `allSatisfied` over the sessions that carry both a
120
+ verdict and a leg row, reported beside the read rate with that denominator stated rather than implied,
121
+ and a gap below five points marks the metric as non-discriminating. On a constructed population the two
122
+ rates separate three satisfied sessions from four that all read, so the number distinguishes what it
123
+ claims to.
124
+ - **The label vocabulary refuses both spellings on both surfaces.** The source gate's vocabulary was
125
+ uppercase while the spelling seats actually typed was lowercase, so 73 handles sat in 22 fixture files
126
+ the gate never saw, plus 23 glued spellings inside them and 11 more in two files the sweep could not
127
+ name. They are renamed to the fixtures' own subjects, the shared set now matches either case, and the
128
+ history gate's two redundant patterns are gone so one subject yields one problem line. A planted token
129
+ reddens the gate at a named line and column; a word character before a handle, two digits, four digits,
130
+ and an ISO calendar week are none of them hits.
131
+ - **A refusal was designed, measured, and killed by its own test.** The candidate enforcement was to refuse
132
+ the first call in a declared family once when the body was never read. Simulated over 703 sessions and
133
+ 107,463 tool calls with the production functions imported, 2 of 30 refused calls changed course (6.7%,
134
+ interval 1.8 to 21.3%), 0 of 30 on a stricter reading, and the gate could reach at most 8% of the calls
135
+ it governs. The best case in the data refutes the shape: the model read the body when the body mattered,
136
+ after the work it needed, without a gate. What ships is the measurement that makes that answer
137
+ possible; what does not ship is the gate.
138
+
56
139
  ## Core — 0.43.6 (2026-10-29: the rule says one thing, and a merge states what landed)
57
140
 
58
141
  - **The identity block contradicted itself, and the contradiction is gone.** One sentence forbade
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.6",
4
- "sha": "e7ebbc542f5983f2270e96628def7a9b6d654610",
5
- "shaShort": "e7ebbc54",
3
+ "version": "0.43.8",
4
+ "sha": "62f2682ee788864913159b5de15fe8cd58f39dc2",
5
+ "shaShort": "62f2682e",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-10-29T14:29:10.456Z"
8
+ "packedAt": "2026-10-31T11:13:27.517Z"
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) ──
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Skill applicability — did a skill's own declared condition hold for the task?
3
+ *
4
+ * The suggestion whisper, the catalog ranking and the adoption counters all
5
+ * answer "might this skill help?". None answers the question the counters
6
+ * cannot: of the sessions that read nothing, which of them had a skill whose
7
+ * stated condition the task text actually met? A suggestion that was ignored
8
+ * and a skill that never applied looked identical in `suggested`/`loaded`.
9
+ * This module decides that difference and keeps its evidence.
10
+ *
11
+ * The condition is the skill's OWN declaration, never a heuristic invented
12
+ * here: the trigger phrases its file declares — frontmatter `trigger:` /
13
+ * `triggers:`, a `## trigger:` body heading, the description's `Triggers:`
14
+ * tail — the same entries `skill-triggers.ts` reads and the same provenance
15
+ * labels it records. The shipped pack's contract already treats that list as
16
+ * the machine-readable form of applicability ("a description that cannot fire
17
+ * is indistinguishable from one that fires"), so a skill file needs no new
18
+ * field for this module to see it. A file that declares no phrase yields no
19
+ * verdict at all; the caller reports it as undeclared rather than asserting
20
+ * "does not apply" on no evidence.
21
+ *
22
+ * Matching mirrors the injector on purpose. The occurrence boundary is the one
23
+ * `triggerMatches` uses (a phrase occurs where neither neighbour is a letter or
24
+ * digit, so "pane" is not an occurrence in "paneled"), because a verdict that
25
+ * disagreed with the whisper would be worse than no verdict: the suite pins
26
+ * the two answers equal over the installed catalog. What this module adds is
27
+ * polarity — a phrase inside a negated clause ("do not research this") is not
28
+ * the author's condition holding, so the clause is read and the phrase is
29
+ * dropped as evidence.
30
+ *
31
+ * What this module does NOT do: it decides nothing about delivery, slots,
32
+ * cooldowns, counters or ranking. It returns a classification and the caller
33
+ * records it. Nothing here reads the session, writes a file or sends a
34
+ * message.
35
+ *
36
+ * Cost: one pass over the task text per phrase of the cached catalog, with the
37
+ * native substring scan as the cheap reject before any boundary work. The
38
+ * caller holds the prompt in memory already (the injector matches against the
39
+ * same string), so no I/O is added per turn.
40
+ */
41
+ import type { TriggerSource } from "./skill-triggers.js";
42
+ /**
43
+ * A skill as the applicability read consumes it: its name and the phrase list
44
+ * the cache resolved from its file. `triggers` and `triggerSources` are the
45
+ * fields `setCachedSkills` fills, so this read never touches the disk — the
46
+ * phrases and their provenance are the ones the injector matched against.
47
+ */
48
+ export interface ConditionalSkill {
49
+ name: string;
50
+ /** Authored phrases (lowercased, deduped, capped) — empty when the file declares none. */
51
+ triggers?: string[];
52
+ /** Which authored source declared each phrase. */
53
+ triggerSources?: Record<string, TriggerSource>;
54
+ }
55
+ /** One authored phrase that matched, with the place in the file that declares it. */
56
+ export interface ApplicabilityEvidence {
57
+ /** The authored phrase, as the reader normalized it. */
58
+ phrase: string;
59
+ /**
60
+ * frontmatter | heading | description — absent only when the cached skill
61
+ * carried no provenance map (an unenriched cache, never a production one).
62
+ */
63
+ source?: TriggerSource;
64
+ }
65
+ /**
66
+ * One skill's verdict for a session.
67
+ *
68
+ * `ignored` is the evaluation's answer: the declared condition held and no
69
+ * detected read followed. `read` is the read-detector's upgrade of the same
70
+ * row. The third class, not-applicable, is never a row — it is a skill that
71
+ * declared a condition and did not meet the task text, so a reader derives it
72
+ * from the record's census (`evaluated` minus the verdict rows).
73
+ */
74
+ export interface SkillApplicabilityVerdict {
75
+ name: string;
76
+ verdict: "read" | "ignored";
77
+ evidence: ApplicabilityEvidence[];
78
+ }
79
+ /** Max evidence rows carried per skill: enough to review, bounded like every other surface. */
80
+ export declare const MAX_APPLICABILITY_EVIDENCE = 4;
81
+ /**
82
+ * Word tokens a negation cue may sit before the phrase and still negate it.
83
+ * "do not research this" (0) and "no need to research" (2) are negated;
84
+ * "do not stop, then research it later" puts the cue past the clauseless
85
+ * distance and reads as the assertion it is. Four is the smallest window that
86
+ * covers the "no need to"/"there is no reason to" shapes without reaching
87
+ * across a clause.
88
+ */
89
+ export declare const NEGATION_GAP_TOKENS = 4;
90
+ /**
91
+ * Every index in `lowered` where `phrase` occurs as a whole phrase, using the
92
+ * matcher's boundary rule: neither neighbour may be a letter or digit. Phrase
93
+ * must already be lowercase. Pure.
94
+ */
95
+ export declare function phraseOccurrences(phrase: string, lowered: string): number[];
96
+ /**
97
+ * Index where the clause containing `at` begins: after the nearest sentence
98
+ * terminator. A clause boundary is what stops a negation in one statement from
99
+ * reaching a phrase in the next ("do not use the catalog; research the topic"
100
+ * asserts research). Pure.
101
+ */
102
+ export declare function clauseStart(lowered: string, at: number): number;
103
+ /**
104
+ * True when the clause text preceding a phrase carries a negation cue close
105
+ * enough to negate it. The LAST cue decides, so "not only did we not ask" is
106
+ * read by its nearest cue rather than its first. Pure.
107
+ */
108
+ export declare function isNegatedPrefix(prefix: string): boolean;
109
+ /**
110
+ * The evidence for one skill's declared condition holding on `taskText`.
111
+ *
112
+ * A phrase is evidence when at least one of its occurrences is asserted:
113
+ * negating one occurrence does not erase another ("do not skip research" and
114
+ * "research this" in the same text both count). Phrases are evidence at most
115
+ * MAX_APPLICABILITY_EVIDENCE times per skill, in authored order. An empty
116
+ * return means the condition did not hold. Pure.
117
+ */
118
+ export declare function skillApplicability(skill: ConditionalSkill, taskText: string): ApplicabilityEvidence[];
119
+ /** The whole catalog's answer for one task text. */
120
+ export interface ApplicabilityEvaluation {
121
+ /** Skills whose declared condition held, each still an `ignored` verdict. */
122
+ applicable: SkillApplicabilityVerdict[];
123
+ /** Installed skills that declare at least one condition phrase. */
124
+ evaluated: number;
125
+ /** Installed skills that declare none — no condition, so no verdict either way. */
126
+ undeclared: string[];
127
+ }
128
+ /**
129
+ * Classify every installed skill against one task text. Pure: the catalog
130
+ * arrives as the cache already resolved it, and the text is the prompt the
131
+ * injector matched against.
132
+ */
133
+ export declare function evaluateApplicability(skills: ConditionalSkill[], taskText: string): ApplicabilityEvaluation;
134
+ //# sourceMappingURL=applicability.d.ts.map
@@ -0,0 +1,161 @@
1
+ /**
2
+ * Skill applicability — did a skill's own declared condition hold for the task?
3
+ *
4
+ * The suggestion whisper, the catalog ranking and the adoption counters all
5
+ * answer "might this skill help?". None answers the question the counters
6
+ * cannot: of the sessions that read nothing, which of them had a skill whose
7
+ * stated condition the task text actually met? A suggestion that was ignored
8
+ * and a skill that never applied looked identical in `suggested`/`loaded`.
9
+ * This module decides that difference and keeps its evidence.
10
+ *
11
+ * The condition is the skill's OWN declaration, never a heuristic invented
12
+ * here: the trigger phrases its file declares — frontmatter `trigger:` /
13
+ * `triggers:`, a `## trigger:` body heading, the description's `Triggers:`
14
+ * tail — the same entries `skill-triggers.ts` reads and the same provenance
15
+ * labels it records. The shipped pack's contract already treats that list as
16
+ * the machine-readable form of applicability ("a description that cannot fire
17
+ * is indistinguishable from one that fires"), so a skill file needs no new
18
+ * field for this module to see it. A file that declares no phrase yields no
19
+ * verdict at all; the caller reports it as undeclared rather than asserting
20
+ * "does not apply" on no evidence.
21
+ *
22
+ * Matching mirrors the injector on purpose. The occurrence boundary is the one
23
+ * `triggerMatches` uses (a phrase occurs where neither neighbour is a letter or
24
+ * digit, so "pane" is not an occurrence in "paneled"), because a verdict that
25
+ * disagreed with the whisper would be worse than no verdict: the suite pins
26
+ * the two answers equal over the installed catalog. What this module adds is
27
+ * polarity — a phrase inside a negated clause ("do not research this") is not
28
+ * the author's condition holding, so the clause is read and the phrase is
29
+ * dropped as evidence.
30
+ *
31
+ * What this module does NOT do: it decides nothing about delivery, slots,
32
+ * cooldowns, counters or ranking. It returns a classification and the caller
33
+ * records it. Nothing here reads the session, writes a file or sends a
34
+ * message.
35
+ *
36
+ * Cost: one pass over the task text per phrase of the cached catalog, with the
37
+ * native substring scan as the cheap reject before any boundary work. The
38
+ * caller holds the prompt in memory already (the injector matches against the
39
+ * same string), so no I/O is added per turn.
40
+ */
41
+ /** Max evidence rows carried per skill: enough to review, bounded like every other surface. */
42
+ export const MAX_APPLICABILITY_EVIDENCE = 4;
43
+ /**
44
+ * Word tokens a negation cue may sit before the phrase and still negate it.
45
+ * "do not research this" (0) and "no need to research" (2) are negated;
46
+ * "do not stop, then research it later" puts the cue past the clauseless
47
+ * distance and reads as the assertion it is. Four is the smallest window that
48
+ * covers the "no need to"/"there is no reason to" shapes without reaching
49
+ * across a clause.
50
+ */
51
+ export const NEGATION_GAP_TOKENS = 4;
52
+ /**
53
+ * Negation cues, matched in the clause text BEFORE a phrase. The `-n't`
54
+ * alternative is spelled out rather than listed per verb so a contraction the
55
+ * list forgot ("won't", "shouldn't") still counts.
56
+ */
57
+ const NEGATION_CUE = /\b(?:not|never|no|nor|without|avoid|avoiding|skip|skipping)\b|\b[a-z]+n['\u2019]t\b/gi;
58
+ /** True when `char` continues a word (the boundary rule `triggerMatches` uses). */
59
+ function isWordChar(char) {
60
+ return char !== undefined && /[a-z0-9]/.test(char);
61
+ }
62
+ /**
63
+ * Every index in `lowered` where `phrase` occurs as a whole phrase, using the
64
+ * matcher's boundary rule: neither neighbour may be a letter or digit. Phrase
65
+ * must already be lowercase. Pure.
66
+ */
67
+ export function phraseOccurrences(phrase, lowered) {
68
+ if (!phrase)
69
+ return [];
70
+ const out = [];
71
+ let from = 0;
72
+ for (;;) {
73
+ const at = lowered.indexOf(phrase, from);
74
+ if (at < 0)
75
+ break;
76
+ if (!isWordChar(lowered[at - 1]) && !isWordChar(lowered[at + phrase.length]))
77
+ out.push(at);
78
+ from = at + 1;
79
+ }
80
+ return out;
81
+ }
82
+ /**
83
+ * Index where the clause containing `at` begins: after the nearest sentence
84
+ * terminator. A clause boundary is what stops a negation in one statement from
85
+ * reaching a phrase in the next ("do not use the catalog; research the topic"
86
+ * asserts research). Pure.
87
+ */
88
+ export function clauseStart(lowered, at) {
89
+ for (let i = at - 1; i >= 0; i--) {
90
+ const char = lowered[i];
91
+ if (char === "." || char === "!" || char === "?" || char === ";" || char === "\n")
92
+ return i + 1;
93
+ }
94
+ return 0;
95
+ }
96
+ /**
97
+ * True when the clause text preceding a phrase carries a negation cue close
98
+ * enough to negate it. The LAST cue decides, so "not only did we not ask" is
99
+ * read by its nearest cue rather than its first. Pure.
100
+ */
101
+ export function isNegatedPrefix(prefix) {
102
+ const cue = new RegExp(NEGATION_CUE.source, "gi");
103
+ let last = null;
104
+ let match;
105
+ while ((match = cue.exec(prefix)))
106
+ last = match;
107
+ if (!last)
108
+ return false;
109
+ const gap = prefix.slice(last.index + last[0].length);
110
+ return (gap.match(/[a-z0-9]+/g) ?? []).length <= NEGATION_GAP_TOKENS;
111
+ }
112
+ /**
113
+ * The evidence for one skill's declared condition holding on `taskText`.
114
+ *
115
+ * A phrase is evidence when at least one of its occurrences is asserted:
116
+ * negating one occurrence does not erase another ("do not skip research" and
117
+ * "research this" in the same text both count). Phrases are evidence at most
118
+ * MAX_APPLICABILITY_EVIDENCE times per skill, in authored order. An empty
119
+ * return means the condition did not hold. Pure.
120
+ */
121
+ export function skillApplicability(skill, taskText) {
122
+ const lowered = taskText.toLowerCase();
123
+ const evidence = [];
124
+ for (const authored of skill.triggers ?? []) {
125
+ if (evidence.length >= MAX_APPLICABILITY_EVIDENCE)
126
+ break;
127
+ const phrase = authored.toLowerCase();
128
+ // Cheap reject first: most phrases are absent from most prompts.
129
+ if (!phrase || !lowered.includes(phrase))
130
+ continue;
131
+ const asserted = phraseOccurrences(phrase, lowered).some((at) => !isNegatedPrefix(lowered.slice(clauseStart(lowered, at), at)));
132
+ if (!asserted)
133
+ continue;
134
+ const source = skill.triggerSources?.[authored] ?? skill.triggerSources?.[phrase];
135
+ evidence.push(source ? { phrase, source } : { phrase });
136
+ }
137
+ return evidence;
138
+ }
139
+ /**
140
+ * Classify every installed skill against one task text. Pure: the catalog
141
+ * arrives as the cache already resolved it, and the text is the prompt the
142
+ * injector matched against.
143
+ */
144
+ export function evaluateApplicability(skills, taskText) {
145
+ const applicable = [];
146
+ const undeclared = [];
147
+ let evaluated = 0;
148
+ const text = taskText ?? "";
149
+ for (const skill of skills) {
150
+ if (!skill.triggers?.length) {
151
+ undeclared.push(skill.name);
152
+ continue;
153
+ }
154
+ evaluated++;
155
+ const evidence = skillApplicability(skill, text);
156
+ if (evidence.length)
157
+ applicable.push({ name: skill.name, verdict: "ignored", evidence });
158
+ }
159
+ return { applicable, evaluated, undeclared };
160
+ }
161
+ //# sourceMappingURL=applicability.js.map
@@ -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.
@@ -189,6 +198,8 @@ export interface CachedSkill {
189
198
  triggers?: string[];
190
199
  /** Which source authored each phrase (the row's evidence label). */
191
200
  triggerSources?: Record<string, TriggerSource>;
201
+ /** Tool families the file's `governs:` declaration claims (skill-families.ts). */
202
+ families?: string[];
192
203
  }
193
204
  /** Called by index.ts's setCachedSkills to keep the auto-inject cache in sync. */
194
205
  export declare function updateSkillCache(skills: CachedSkill[]): void;
@@ -497,6 +508,26 @@ interface DiscoveryState {
497
508
  * discovery mode. Returns the current record for skill_stats.
498
509
  */
499
510
  export declare function resolveDiscoveryMode(ctx: ExtensionContext): DiscoveryState;
511
+ /**
512
+ * Record the skills a delivered suggestion offered this session. Called only
513
+ * after the send was accepted, so the row counts arrivals like the `suggested`
514
+ * counter does. Never throws: a record is not worth a broken turn.
515
+ */
516
+ export declare function noteObligationSuggested(ctx: ExtensionContext, names: string[]): void;
517
+ /** Record the skills a catalog page listed (called from the list_skills tool). */
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;
500
531
  /**
501
532
  * Register the auto-inject handler on before_agent_start, the read-tool load
502
533
  * detector and the drift trigger on tool_result.