pi-braid 0.40.3 → 0.40.5
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.
- package/build-info.json +4 -4
- package/dist/extensions/core/skills-tool/auto-inject.d.ts +99 -17
- package/dist/extensions/core/skills-tool/auto-inject.js +129 -17
- package/dist/extensions/core/skills-tool/skill-triggers.d.ts +37 -13
- package/dist/extensions/core/skills-tool/skill-triggers.js +54 -16
- package/package.json +2 -1
- package/src/extensions/core/skills-tool/auto-inject.ts +170 -19
- package/src/extensions/core/skills-tool/skill-triggers.ts +53 -16
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.40.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.40.5",
|
|
4
|
+
"sha": "5302e19de5f827e43f8e88ae90adef379842a002",
|
|
5
|
+
"shaShort": "5302e19",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-10-
|
|
8
|
+
"packedAt": "2026-10-20T14:50:06.898Z"
|
|
9
9
|
}
|
|
@@ -8,13 +8,23 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Design:
|
|
10
10
|
* 1. Relevance detection: keyword match of skill name/description plus
|
|
11
|
-
*
|
|
11
|
+
* curated trigger phrases against the user's current prompt.
|
|
12
12
|
* Qualification bar: a skill whose match never touches its NAME (name
|
|
13
13
|
* token or trigger phrase) must reach a score of at least
|
|
14
14
|
* MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
|
|
15
15
|
* a signal: it fires broad skills on almost any prompt.
|
|
16
16
|
* Keywords are stemmed with one suffix rule (trailing s/es) so plural
|
|
17
17
|
* prompts hit singular name tokens ("skills" → "skill").
|
|
18
|
+
* Corpus-common words are gated out of the weak legs: a word present in
|
|
19
|
+
* COMMON_KEYWORD_DF or more of the cached skills' documents cannot tell
|
|
20
|
+
* skills apart, so description/path hits from it score nothing. Name and
|
|
21
|
+
* trigger hits are never gated — the skill's own identity vocabulary is
|
|
22
|
+
* what a prompt naming it looks like.
|
|
23
|
+
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
24
|
+
* by rarer evidence (lower summed document frequency), then by name.
|
|
25
|
+
* Alphabetical order alone decided which of two equally-scored skills
|
|
26
|
+
* took a slot, which is how a broadly-matching skill outranked the one
|
|
27
|
+
* whose evidence was the prompt's actual subject.
|
|
18
28
|
* 2. Session-scoped state: track which skills were injected on which turn.
|
|
19
29
|
* Cooldown is per-skill on top of the global floor: an injected skill
|
|
20
30
|
* cools down at least COOLDOWN_TURNS, and once it was actually loaded
|
|
@@ -117,6 +127,32 @@ export declare const MAX_EXCERPT_CHARS = 300;
|
|
|
117
127
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
118
128
|
*/
|
|
119
129
|
export declare const MIN_NON_NAME_SCORE = 2;
|
|
130
|
+
/**
|
|
131
|
+
* A keyword present in this many skill documents or more is corpus-common: it
|
|
132
|
+
* appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
|
|
133
|
+
* distinguish one skill from another and contributes NOTHING to the weak legs
|
|
134
|
+
* (description, catalog path).
|
|
135
|
+
*
|
|
136
|
+
* The number is measured, not guessed. Two measurements, one threshold:
|
|
137
|
+
*
|
|
138
|
+
* Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
|
|
139
|
+
* weak-leg points awarded to words by document frequency are df1 17.0%,
|
|
140
|
+
* df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
|
|
141
|
+
* df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
|
|
142
|
+
* awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
|
|
143
|
+
* vocabulary starts here (skill, read, prompt, text, build, change, agent,
|
|
144
|
+
* line); below it the words still describe work types (review, check, test,
|
|
145
|
+
* edit, documentation).
|
|
146
|
+
*
|
|
147
|
+
* Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
|
|
148
|
+
* df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
|
|
149
|
+
* Recall alone cannot choose the number: every step that weakens the gate
|
|
150
|
+
* admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
|
|
151
|
+
* only raise a top-2 recall figure. 5 is where the gate removes a quarter of
|
|
152
|
+
* the corpus-common mass without also deleting the work-type words that are
|
|
153
|
+
* sometimes a skill's only reachable evidence.
|
|
154
|
+
*/
|
|
155
|
+
export declare const COMMON_KEYWORD_DF = 5;
|
|
120
156
|
export interface InjectedSkill {
|
|
121
157
|
name: string;
|
|
122
158
|
turnNumber: number;
|
|
@@ -156,49 +192,95 @@ export declare function stemKeyword(word: string): string;
|
|
|
156
192
|
* bar (stemming "tasks" lands on the noise word "task", which stays out).
|
|
157
193
|
*/
|
|
158
194
|
export declare function extractKeywords(text: string): string[];
|
|
195
|
+
/**
|
|
196
|
+
* The text a skill contributes to the corpus-frequency count: its description
|
|
197
|
+
* plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
|
|
198
|
+
* path: a checkout root puts its own directory names ("private", "packages",
|
|
199
|
+
* a worktree name) in every one of the 22 documents — measured at df 22 for
|
|
200
|
+
* `private`, `package`, `pack` and `core`, and different on every machine the
|
|
201
|
+
* agent runs on. On description plus the skill's own directory those four
|
|
202
|
+
* measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
|
|
203
|
+
* file itself is named SKILL.md, and the rarity gate is what removes them.
|
|
204
|
+
* Lowercased; the matcher tests substrings. Pure.
|
|
205
|
+
*/
|
|
206
|
+
export declare function skillCorpusDocument(skill: CachedSkill): string;
|
|
207
|
+
/**
|
|
208
|
+
* Document frequency of each keyword across the cached skills: how many skill
|
|
209
|
+
* documents contain it as a substring (the test every weak leg performs).
|
|
210
|
+
* Computed once per turn from the cache, for the prompt's keywords only. Pure
|
|
211
|
+
* given the cache.
|
|
212
|
+
*/
|
|
213
|
+
export declare function corpusKeywordFrequency(keywords: string[], skills: CachedSkill[]): Map<string, number>;
|
|
214
|
+
/** One skill's match against a prompt: points, distinct signals, evidence rarity. */
|
|
215
|
+
export interface SkillMatch {
|
|
216
|
+
/** Score the qualification bar and the ranking read (same scale as before). */
|
|
217
|
+
score: number;
|
|
218
|
+
/** Distinct matched signals: each trigger phrase, each distinct keyword. */
|
|
219
|
+
signals: number;
|
|
220
|
+
/** Summed document frequency of the matched keywords — lower is rarer. */
|
|
221
|
+
evidenceDf: number;
|
|
222
|
+
}
|
|
159
223
|
/**
|
|
160
224
|
* Score a skill against a set of keywords.
|
|
161
225
|
*
|
|
162
226
|
* Scoring rules:
|
|
163
227
|
* +3 skill name contains a keyword (exact match)
|
|
164
228
|
* +2 skill name contains a keyword as substring
|
|
165
|
-
* +2 a
|
|
229
|
+
* +2 a trigger phrase occurs in the prompt (word-bounded)
|
|
166
230
|
* +1 skill description contains a keyword
|
|
167
|
-
* +1 skill
|
|
231
|
+
* +1 the skill's own catalog path contains a keyword (e.g. "research" in
|
|
232
|
+
* "research/skill.md")
|
|
168
233
|
*
|
|
169
234
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
170
235
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
171
236
|
*
|
|
237
|
+
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
238
|
+
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
239
|
+
* nothing on the weak legs; passing no map scores every keyword at full weight
|
|
240
|
+
* (the pre-rarity behavior, which the unit fixtures pin).
|
|
241
|
+
*
|
|
172
242
|
* Qualification bar: a skill whose match never touches its NAME (description
|
|
173
243
|
* and/or filePath hits only) must reach a total score of at least
|
|
174
244
|
* MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
|
|
175
245
|
* lets generic skills fire on almost any prompt. Name and trigger matches
|
|
176
246
|
* always qualify.
|
|
177
247
|
*
|
|
178
|
-
* `promptText`
|
|
179
|
-
* on our side) enables trigger matching; omit it where the raw prompt is not
|
|
248
|
+
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
180
249
|
* available and only keyword scoring should run.
|
|
181
250
|
*
|
|
182
|
-
* Returns
|
|
251
|
+
* Returns the zero match if the skill does not qualify.
|
|
252
|
+
*/
|
|
253
|
+
export declare function matchSkill(skill: CachedSkill, keywords: string[], promptText?: string, keywordDf?: ReadonlyMap<string, number>): SkillMatch;
|
|
254
|
+
/** The score alone (see matchSkill for the rules and the rarity gate). */
|
|
255
|
+
export declare function scoreSkill(skill: CachedSkill, keywords: string[], promptText?: string, keywordDf?: ReadonlyMap<string, number>): number;
|
|
256
|
+
/**
|
|
257
|
+
* A skill with its match evidence, as the selection step consumes it. The
|
|
258
|
+
* evidence fields are optional so a caller holding only a score still selects;
|
|
259
|
+
* they then default to zero and the name stays the tie-breaker.
|
|
183
260
|
*/
|
|
184
|
-
export
|
|
261
|
+
export interface ScoredSkill {
|
|
262
|
+
skill: CachedSkill;
|
|
263
|
+
score: number;
|
|
264
|
+
signals?: number;
|
|
265
|
+
evidenceDf?: number;
|
|
266
|
+
}
|
|
185
267
|
/**
|
|
186
268
|
* Decide which scored skills to suggest given the session injection state.
|
|
187
269
|
* Pure — mirrors the handler's decision path so it can be unit-tested:
|
|
188
|
-
* sort (score desc,
|
|
189
|
-
* loaded extension) → slot budget
|
|
190
|
-
* released its slot) → top-N slice.
|
|
270
|
+
* sort (score desc, distinct signals desc, evidence df asc, name asc) →
|
|
271
|
+
* cooldown filter (global floor + per-skill loaded extension) → slot budget
|
|
272
|
+
* over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
|
|
273
|
+
*
|
|
274
|
+
* The rank order is the fix for alphabetical slot allocation: two skills with
|
|
275
|
+
* equal points used to be ordered by name, so a broadly-matching skill took
|
|
276
|
+
* the slot from one whose evidence was the prompt's actual subject. Distinct
|
|
277
|
+
* signals separate breadth of match; evidence df separates a match on the
|
|
278
|
+
* prompt's distinctive words from one on its filler.
|
|
191
279
|
*
|
|
192
280
|
* Returns the chosen scored items (empty when nothing qualifies). The
|
|
193
281
|
* caller is responsible for recording the picks in session state.
|
|
194
282
|
*/
|
|
195
|
-
export declare function selectSuggestions(scored:
|
|
196
|
-
skill: CachedSkill;
|
|
197
|
-
score: number;
|
|
198
|
-
}>, injected: InjectedSkill[], currentTurn: number): Array<{
|
|
199
|
-
skill: CachedSkill;
|
|
200
|
-
score: number;
|
|
201
|
-
}>;
|
|
283
|
+
export declare function selectSuggestions(scored: ScoredSkill[], injected: InjectedSkill[], currentTurn: number): ScoredSkill[];
|
|
202
284
|
/**
|
|
203
285
|
* Strip YAML frontmatter from a SKILL.md body. Pure.
|
|
204
286
|
*
|
|
@@ -8,13 +8,23 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Design:
|
|
10
10
|
* 1. Relevance detection: keyword match of skill name/description plus
|
|
11
|
-
*
|
|
11
|
+
* curated trigger phrases against the user's current prompt.
|
|
12
12
|
* Qualification bar: a skill whose match never touches its NAME (name
|
|
13
13
|
* token or trigger phrase) must reach a score of at least
|
|
14
14
|
* MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
|
|
15
15
|
* a signal: it fires broad skills on almost any prompt.
|
|
16
16
|
* Keywords are stemmed with one suffix rule (trailing s/es) so plural
|
|
17
17
|
* prompts hit singular name tokens ("skills" → "skill").
|
|
18
|
+
* Corpus-common words are gated out of the weak legs: a word present in
|
|
19
|
+
* COMMON_KEYWORD_DF or more of the cached skills' documents cannot tell
|
|
20
|
+
* skills apart, so description/path hits from it score nothing. Name and
|
|
21
|
+
* trigger hits are never gated — the skill's own identity vocabulary is
|
|
22
|
+
* what a prompt naming it looks like.
|
|
23
|
+
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
24
|
+
* by rarer evidence (lower summed document frequency), then by name.
|
|
25
|
+
* Alphabetical order alone decided which of two equally-scored skills
|
|
26
|
+
* took a slot, which is how a broadly-matching skill outranked the one
|
|
27
|
+
* whose evidence was the prompt's actual subject.
|
|
18
28
|
* 2. Session-scoped state: track which skills were injected on which turn.
|
|
19
29
|
* Cooldown is per-skill on top of the global floor: an injected skill
|
|
20
30
|
* cools down at least COOLDOWN_TURNS, and once it was actually loaded
|
|
@@ -130,6 +140,32 @@ export const MAX_EXCERPT_CHARS = 300;
|
|
|
130
140
|
* and/or filePath keyword hits only). Name matches qualify at any score.
|
|
131
141
|
*/
|
|
132
142
|
export const MIN_NON_NAME_SCORE = 2;
|
|
143
|
+
/**
|
|
144
|
+
* A keyword present in this many skill documents or more is corpus-common: it
|
|
145
|
+
* appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
|
|
146
|
+
* distinguish one skill from another and contributes NOTHING to the weak legs
|
|
147
|
+
* (description, catalog path).
|
|
148
|
+
*
|
|
149
|
+
* The number is measured, not guessed. Two measurements, one threshold:
|
|
150
|
+
*
|
|
151
|
+
* Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
|
|
152
|
+
* weak-leg points awarded to words by document frequency are df1 17.0%,
|
|
153
|
+
* df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
|
|
154
|
+
* df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
|
|
155
|
+
* awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
|
|
156
|
+
* vocabulary starts here (skill, read, prompt, text, build, change, agent,
|
|
157
|
+
* line); below it the words still describe work types (review, check, test,
|
|
158
|
+
* edit, documentation).
|
|
159
|
+
*
|
|
160
|
+
* Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
|
|
161
|
+
* df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
|
|
162
|
+
* Recall alone cannot choose the number: every step that weakens the gate
|
|
163
|
+
* admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
|
|
164
|
+
* only raise a top-2 recall figure. 5 is where the gate removes a quarter of
|
|
165
|
+
* the corpus-common mass without also deleting the work-type words that are
|
|
166
|
+
* sometimes a skill's only reachable evidence.
|
|
167
|
+
*/
|
|
168
|
+
export const COMMON_KEYWORD_DF = 5;
|
|
133
169
|
/**
|
|
134
170
|
* Common English words to exclude from keyword matching.
|
|
135
171
|
* Kept small — only the most frequent noise words that would
|
|
@@ -237,76 +273,146 @@ export function extractKeywords(text) {
|
|
|
237
273
|
return [...new Set(words)];
|
|
238
274
|
}
|
|
239
275
|
// Relevance Scoring
|
|
276
|
+
/**
|
|
277
|
+
* The text a skill contributes to the corpus-frequency count: its description
|
|
278
|
+
* plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
|
|
279
|
+
* path: a checkout root puts its own directory names ("private", "packages",
|
|
280
|
+
* a worktree name) in every one of the 22 documents — measured at df 22 for
|
|
281
|
+
* `private`, `package`, `pack` and `core`, and different on every machine the
|
|
282
|
+
* agent runs on. On description plus the skill's own directory those four
|
|
283
|
+
* measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
|
|
284
|
+
* file itself is named SKILL.md, and the rarity gate is what removes them.
|
|
285
|
+
* Lowercased; the matcher tests substrings. Pure.
|
|
286
|
+
*/
|
|
287
|
+
export function skillCorpusDocument(skill) {
|
|
288
|
+
const tail = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
289
|
+
return `${skill.description.toLowerCase()} ${tail}`;
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Document frequency of each keyword across the cached skills: how many skill
|
|
293
|
+
* documents contain it as a substring (the test every weak leg performs).
|
|
294
|
+
* Computed once per turn from the cache, for the prompt's keywords only. Pure
|
|
295
|
+
* given the cache.
|
|
296
|
+
*/
|
|
297
|
+
export function corpusKeywordFrequency(keywords, skills) {
|
|
298
|
+
const docs = skills.map(skillCorpusDocument);
|
|
299
|
+
const freq = new Map();
|
|
300
|
+
for (const kw of keywords) {
|
|
301
|
+
let n = 0;
|
|
302
|
+
for (const doc of docs)
|
|
303
|
+
if (doc.includes(kw))
|
|
304
|
+
n++;
|
|
305
|
+
freq.set(kw, n);
|
|
306
|
+
}
|
|
307
|
+
return freq;
|
|
308
|
+
}
|
|
309
|
+
const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0 };
|
|
240
310
|
/**
|
|
241
311
|
* Score a skill against a set of keywords.
|
|
242
312
|
*
|
|
243
313
|
* Scoring rules:
|
|
244
314
|
* +3 skill name contains a keyword (exact match)
|
|
245
315
|
* +2 skill name contains a keyword as substring
|
|
246
|
-
* +2 a
|
|
316
|
+
* +2 a trigger phrase occurs in the prompt (word-bounded)
|
|
247
317
|
* +1 skill description contains a keyword
|
|
248
|
-
* +1 skill
|
|
318
|
+
* +1 the skill's own catalog path contains a keyword (e.g. "research" in
|
|
319
|
+
* "research/skill.md")
|
|
249
320
|
*
|
|
250
321
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
251
322
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
252
323
|
*
|
|
324
|
+
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
325
|
+
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
326
|
+
* nothing on the weak legs; passing no map scores every keyword at full weight
|
|
327
|
+
* (the pre-rarity behavior, which the unit fixtures pin).
|
|
328
|
+
*
|
|
253
329
|
* Qualification bar: a skill whose match never touches its NAME (description
|
|
254
330
|
* and/or filePath hits only) must reach a total score of at least
|
|
255
331
|
* MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
|
|
256
332
|
* lets generic skills fire on almost any prompt. Name and trigger matches
|
|
257
333
|
* always qualify.
|
|
258
334
|
*
|
|
259
|
-
* `promptText`
|
|
260
|
-
* on our side) enables trigger matching; omit it where the raw prompt is not
|
|
335
|
+
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
261
336
|
* available and only keyword scoring should run.
|
|
262
337
|
*
|
|
263
|
-
* Returns
|
|
338
|
+
* Returns the zero match if the skill does not qualify.
|
|
264
339
|
*/
|
|
265
|
-
export function
|
|
340
|
+
export function matchSkill(skill, keywords, promptText, keywordDf) {
|
|
266
341
|
let score = 0;
|
|
342
|
+
let signals = 0;
|
|
343
|
+
let evidenceDf = 0;
|
|
267
344
|
let nameHit = false;
|
|
268
345
|
const name = skill.name.toLowerCase();
|
|
269
346
|
const desc = skill.description.toLowerCase();
|
|
270
|
-
const path = skill.filePath.toLowerCase();
|
|
347
|
+
const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
348
|
+
const dfOf = (kw) => keywordDf?.get(kw) ?? 0;
|
|
271
349
|
for (const trig of skill.triggers ?? []) {
|
|
272
350
|
if (triggerMatches(trig, promptText ?? "")) {
|
|
273
351
|
score += 2;
|
|
352
|
+
signals++;
|
|
274
353
|
nameHit = true;
|
|
354
|
+
// A curated phrase is the rarest evidence a skill can offer: df 0.
|
|
275
355
|
}
|
|
276
356
|
}
|
|
277
357
|
for (const kw of keywords) {
|
|
358
|
+
const df = dfOf(kw);
|
|
278
359
|
// Exact token match in name
|
|
279
360
|
if (name.split(/[^a-z0-9]+/).includes(kw)) {
|
|
280
361
|
score += 3;
|
|
362
|
+
signals++;
|
|
281
363
|
nameHit = true;
|
|
364
|
+
evidenceDf += df;
|
|
282
365
|
continue;
|
|
283
366
|
}
|
|
284
367
|
// Substring match in name (catches compound names like "code-search")
|
|
285
368
|
if (name.includes(kw)) {
|
|
286
369
|
score += 2;
|
|
370
|
+
signals++;
|
|
287
371
|
nameHit = true;
|
|
372
|
+
evidenceDf += df;
|
|
288
373
|
continue;
|
|
289
374
|
}
|
|
290
|
-
//
|
|
375
|
+
// Corpus-common keyword: the weak legs score nothing for it, so a prompt
|
|
376
|
+
// full of generic vocabulary cannot buy a slot.
|
|
377
|
+
if (df >= COMMON_KEYWORD_DF)
|
|
378
|
+
continue;
|
|
379
|
+
let weakHit = false;
|
|
291
380
|
if (desc.includes(kw)) {
|
|
292
381
|
score += 1;
|
|
293
|
-
|
|
382
|
+
weakHit = true;
|
|
294
383
|
}
|
|
295
384
|
// File path matches (e.g. "research" in "research/SKILL.md")
|
|
296
385
|
if (path.includes(kw)) {
|
|
297
386
|
score += 1;
|
|
387
|
+
weakHit = true;
|
|
388
|
+
}
|
|
389
|
+
// One signal per distinct keyword: a word present in both the description
|
|
390
|
+
// and the path is one piece of evidence, not two.
|
|
391
|
+
if (weakHit) {
|
|
392
|
+
signals++;
|
|
393
|
+
evidenceDf += df;
|
|
298
394
|
}
|
|
299
395
|
}
|
|
300
396
|
if (!nameHit && score < MIN_NON_NAME_SCORE)
|
|
301
|
-
return
|
|
302
|
-
return score;
|
|
397
|
+
return NO_MATCH;
|
|
398
|
+
return { score, signals, evidenceDf };
|
|
399
|
+
}
|
|
400
|
+
/** The score alone (see matchSkill for the rules and the rarity gate). */
|
|
401
|
+
export function scoreSkill(skill, keywords, promptText, keywordDf) {
|
|
402
|
+
return matchSkill(skill, keywords, promptText, keywordDf).score;
|
|
303
403
|
}
|
|
304
404
|
/**
|
|
305
405
|
* Decide which scored skills to suggest given the session injection state.
|
|
306
406
|
* Pure — mirrors the handler's decision path so it can be unit-tested:
|
|
307
|
-
* sort (score desc,
|
|
308
|
-
* loaded extension) → slot budget
|
|
309
|
-
* released its slot) → top-N slice.
|
|
407
|
+
* sort (score desc, distinct signals desc, evidence df asc, name asc) →
|
|
408
|
+
* cooldown filter (global floor + per-skill loaded extension) → slot budget
|
|
409
|
+
* over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
|
|
410
|
+
*
|
|
411
|
+
* The rank order is the fix for alphabetical slot allocation: two skills with
|
|
412
|
+
* equal points used to be ordered by name, so a broadly-matching skill took
|
|
413
|
+
* the slot from one whose evidence was the prompt's actual subject. Distinct
|
|
414
|
+
* signals separate breadth of match; evidence df separates a match on the
|
|
415
|
+
* prompt's distinctive words from one on its filler.
|
|
310
416
|
*
|
|
311
417
|
* Returns the chosen scored items (empty when nothing qualifies). The
|
|
312
418
|
* caller is responsible for recording the picks in session state.
|
|
@@ -314,7 +420,10 @@ export function scoreSkill(skill, keywords, promptText) {
|
|
|
314
420
|
export function selectSuggestions(scored, injected, currentTurn) {
|
|
315
421
|
if (!scored.length)
|
|
316
422
|
return [];
|
|
317
|
-
const sorted = [...scored].sort((a, b) => b.score - a.score ||
|
|
423
|
+
const sorted = [...scored].sort((a, b) => b.score - a.score ||
|
|
424
|
+
(b.signals ?? 0) - (a.signals ?? 0) ||
|
|
425
|
+
(a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
|
|
426
|
+
a.skill.name.localeCompare(b.skill.name));
|
|
318
427
|
const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
|
|
319
428
|
if (!available.length)
|
|
320
429
|
return [];
|
|
@@ -762,9 +871,12 @@ export function registerAutoInject(pi) {
|
|
|
762
871
|
if (!keywords.length) {
|
|
763
872
|
return; // No significant keywords to match
|
|
764
873
|
}
|
|
874
|
+
// Corpus-common words cannot tell skills apart. Their document frequency
|
|
875
|
+
// is measured once per turn from the same cache the scorer reads.
|
|
876
|
+
const keywordDf = corpusKeywordFrequency(keywords, skills);
|
|
765
877
|
// Score each skill. The raw prompt rides along for trigger matching.
|
|
766
878
|
const scored = skills
|
|
767
|
-
.map((s) => ({ skill: s,
|
|
879
|
+
.map((s) => ({ skill: s, ...matchSkill(s, keywords, prompt, keywordDf) }))
|
|
768
880
|
.filter((s) => s.score > 0);
|
|
769
881
|
if (!scored.length) {
|
|
770
882
|
return; // No relevant skills found
|
|
@@ -1,18 +1,36 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Curated trigger phrases for the suggestion matcher.
|
|
3
3
|
*
|
|
4
4
|
* pi's skill objects carry a fixed shape (name, description, path, source),
|
|
5
5
|
* so curated trigger phrases never reach braid through the prompt-builder
|
|
6
|
-
* cache — read them from the SKILL.md
|
|
7
|
-
*
|
|
8
|
-
*
|
|
6
|
+
* cache — read them from the SKILL.md itself. Reads are memoized by file
|
|
7
|
+
* mtime + size: repeated turns stat, only changed or first-seen files parse.
|
|
8
|
+
*
|
|
9
|
+
* Authors wrote the phrases in three places, and all three are read:
|
|
10
|
+
* 1. frontmatter, under `trigger:` (a comma-separated string) or
|
|
11
|
+
* `triggers:` (a YAML list) — the canonical field;
|
|
12
|
+
* 2. a `## trigger:` body heading, quoted or bare (9 of core's 22 skills
|
|
13
|
+
* carry the phrases here and nowhere else);
|
|
14
|
+
* 3. the description's trailing "Triggers: …" segment, the pack's older
|
|
15
|
+
* convention.
|
|
16
|
+
* A file may use any of them; the first source that yields phrases wins, so
|
|
17
|
+
* the frontmatter stays authoritative and a body heading never silently
|
|
18
|
+
* overrides it.
|
|
9
19
|
*
|
|
10
20
|
* A trigger hit scores like a name hit and qualifies a skill whose
|
|
11
21
|
* description alone would stay under the qualification bar — the phrase is
|
|
12
22
|
* the author's own signal of when the skill applies, sharper than any
|
|
13
|
-
* description keyword.
|
|
23
|
+
* description keyword. Matching is case-insensitive: prompts arrive
|
|
24
|
+
* capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
|
|
25
|
+
* lowercase text would be dead in production while a lowercase-only unit
|
|
26
|
+
* fixture kept the suite green.
|
|
27
|
+
*/
|
|
28
|
+
/**
|
|
29
|
+
* Max trigger phrases read per skill — a longer list is an authoring bug, not a
|
|
30
|
+
* matcher input. Two authored lists reach the cap (braid-reference 16,
|
|
31
|
+
* pi-reference 15), so their tail phrases are not read: raising the cap needs
|
|
32
|
+
* the assertion in test-skill-decision.mjs changed with it.
|
|
14
33
|
*/
|
|
15
|
-
/** Max trigger phrases read per skill — a longer list is an authoring bug, not a matcher input. */
|
|
16
34
|
export declare const MAX_TRIGGERS = 12;
|
|
17
35
|
/** Max characters of one trigger phrase. */
|
|
18
36
|
export declare const MAX_TRIGGER_CHARS = 64;
|
|
@@ -23,14 +41,19 @@ export declare const MAX_TRIGGER_CHARS = 64;
|
|
|
23
41
|
*/
|
|
24
42
|
export declare function normalizeTriggers(value: unknown): string[];
|
|
25
43
|
/**
|
|
26
|
-
* Read a skill's trigger phrases: frontmatter `triggers
|
|
27
|
-
* then
|
|
28
|
-
*
|
|
29
|
-
* the matcher
|
|
30
|
-
*
|
|
31
|
-
* name/description scoring alone). Memoized: unchanged files never re-read.
|
|
44
|
+
* Read a skill's trigger phrases: frontmatter (`trigger` or `triggers`) first,
|
|
45
|
+
* then a `## trigger:` body heading, then the description's trailing
|
|
46
|
+
* "Triggers: …" segment. Missing/unreadable file or malformed YAML → no
|
|
47
|
+
* triggers (the matcher falls back to name/description scoring alone).
|
|
48
|
+
* Memoized: unchanged files never re-read.
|
|
32
49
|
*/
|
|
33
50
|
export declare function readSkillTriggers(filePath: string, description?: string): string[];
|
|
51
|
+
/**
|
|
52
|
+
* Trigger phrases from a body `## trigger: "a, b, c"` heading. The FIRST such
|
|
53
|
+
* heading is the whole input: a body with several is an authoring error, not
|
|
54
|
+
* extra matcher input. Quotes around the value are stripped. Pure.
|
|
55
|
+
*/
|
|
56
|
+
export declare function parseBodyTriggers(body: string): string[];
|
|
34
57
|
/**
|
|
35
58
|
* Trigger phrases from a description's trailing "Triggers: …" segment —
|
|
36
59
|
* the contrib pack convention ("… Use when X. Triggers: meme, image macro.").
|
|
@@ -42,7 +65,8 @@ export declare function clearSkillTriggerCache(): void;
|
|
|
42
65
|
/**
|
|
43
66
|
* True when the phrase occurs in the prompt on word boundaries ("pane" does
|
|
44
67
|
* not match "paneled"). Multi-word phrases match literally; hyphenated
|
|
45
|
-
* prompt tokens count as boundaries.
|
|
68
|
+
* prompt tokens count as boundaries. Phrases are normalized to lowercase, so
|
|
69
|
+
* the prompt is folded to match: the boundary classes stay lowercase-only.
|
|
46
70
|
*/
|
|
47
71
|
export declare function triggerMatches(phrase: string, promptText: string): boolean;
|
|
48
72
|
//# sourceMappingURL=skill-triggers.d.ts.map
|
|
@@ -1,20 +1,38 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Curated trigger phrases for the suggestion matcher.
|
|
3
3
|
*
|
|
4
4
|
* pi's skill objects carry a fixed shape (name, description, path, source),
|
|
5
5
|
* so curated trigger phrases never reach braid through the prompt-builder
|
|
6
|
-
* cache — read them from the SKILL.md
|
|
7
|
-
*
|
|
8
|
-
*
|
|
6
|
+
* cache — read them from the SKILL.md itself. Reads are memoized by file
|
|
7
|
+
* mtime + size: repeated turns stat, only changed or first-seen files parse.
|
|
8
|
+
*
|
|
9
|
+
* Authors wrote the phrases in three places, and all three are read:
|
|
10
|
+
* 1. frontmatter, under `trigger:` (a comma-separated string) or
|
|
11
|
+
* `triggers:` (a YAML list) — the canonical field;
|
|
12
|
+
* 2. a `## trigger:` body heading, quoted or bare (9 of core's 22 skills
|
|
13
|
+
* carry the phrases here and nowhere else);
|
|
14
|
+
* 3. the description's trailing "Triggers: …" segment, the pack's older
|
|
15
|
+
* convention.
|
|
16
|
+
* A file may use any of them; the first source that yields phrases wins, so
|
|
17
|
+
* the frontmatter stays authoritative and a body heading never silently
|
|
18
|
+
* overrides it.
|
|
9
19
|
*
|
|
10
20
|
* A trigger hit scores like a name hit and qualifies a skill whose
|
|
11
21
|
* description alone would stay under the qualification bar — the phrase is
|
|
12
22
|
* the author's own signal of when the skill applies, sharper than any
|
|
13
|
-
* description keyword.
|
|
23
|
+
* description keyword. Matching is case-insensitive: prompts arrive
|
|
24
|
+
* capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
|
|
25
|
+
* lowercase text would be dead in production while a lowercase-only unit
|
|
26
|
+
* fixture kept the suite green.
|
|
14
27
|
*/
|
|
15
28
|
import { statSync, readFileSync } from "node:fs";
|
|
16
29
|
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
17
|
-
/**
|
|
30
|
+
/**
|
|
31
|
+
* Max trigger phrases read per skill — a longer list is an authoring bug, not a
|
|
32
|
+
* matcher input. Two authored lists reach the cap (braid-reference 16,
|
|
33
|
+
* pi-reference 15), so their tail phrases are not read: raising the cap needs
|
|
34
|
+
* the assertion in test-skill-decision.mjs changed with it.
|
|
35
|
+
*/
|
|
18
36
|
export const MAX_TRIGGERS = 12;
|
|
19
37
|
/** Max characters of one trigger phrase. */
|
|
20
38
|
export const MAX_TRIGGER_CHARS = 64;
|
|
@@ -42,12 +60,11 @@ export function normalizeTriggers(value) {
|
|
|
42
60
|
return cleaned;
|
|
43
61
|
}
|
|
44
62
|
/**
|
|
45
|
-
* Read a skill's trigger phrases: frontmatter `triggers
|
|
46
|
-
* then
|
|
47
|
-
*
|
|
48
|
-
* the matcher
|
|
49
|
-
*
|
|
50
|
-
* name/description scoring alone). Memoized: unchanged files never re-read.
|
|
63
|
+
* Read a skill's trigger phrases: frontmatter (`trigger` or `triggers`) first,
|
|
64
|
+
* then a `## trigger:` body heading, then the description's trailing
|
|
65
|
+
* "Triggers: …" segment. Missing/unreadable file or malformed YAML → no
|
|
66
|
+
* triggers (the matcher falls back to name/description scoring alone).
|
|
67
|
+
* Memoized: unchanged files never re-read.
|
|
51
68
|
*/
|
|
52
69
|
export function readSkillTriggers(filePath, description) {
|
|
53
70
|
let st;
|
|
@@ -63,8 +80,13 @@ export function readSkillTriggers(filePath, description) {
|
|
|
63
80
|
return cached.triggers;
|
|
64
81
|
let triggers;
|
|
65
82
|
try {
|
|
66
|
-
const { frontmatter } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
67
|
-
|
|
83
|
+
const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
84
|
+
const fm = frontmatter;
|
|
85
|
+
triggers = normalizeTriggers(fm.trigger);
|
|
86
|
+
if (!triggers.length)
|
|
87
|
+
triggers = normalizeTriggers(fm.triggers);
|
|
88
|
+
if (!triggers.length)
|
|
89
|
+
triggers = parseBodyTriggers(body);
|
|
68
90
|
}
|
|
69
91
|
catch {
|
|
70
92
|
triggers = []; // malformed frontmatter — score on name/description only
|
|
@@ -74,6 +96,21 @@ export function readSkillTriggers(filePath, description) {
|
|
|
74
96
|
cache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, triggers });
|
|
75
97
|
return triggers;
|
|
76
98
|
}
|
|
99
|
+
/** First `## trigger:` / `## triggers:` heading; a heading-shaped line cannot come from frontmatter. */
|
|
100
|
+
const BODY_TRIGGER_HEADING = /^##\s*triggers?\s*:\s*(.*)$/i;
|
|
101
|
+
/**
|
|
102
|
+
* Trigger phrases from a body `## trigger: "a, b, c"` heading. The FIRST such
|
|
103
|
+
* heading is the whole input: a body with several is an authoring error, not
|
|
104
|
+
* extra matcher input. Quotes around the value are stripped. Pure.
|
|
105
|
+
*/
|
|
106
|
+
export function parseBodyTriggers(body) {
|
|
107
|
+
for (const line of body.split(/\r?\n/)) {
|
|
108
|
+
const match = BODY_TRIGGER_HEADING.exec(line);
|
|
109
|
+
if (match)
|
|
110
|
+
return normalizeTriggers(match[1].trim().replace(/^["']|["']$/g, ""));
|
|
111
|
+
}
|
|
112
|
+
return [];
|
|
113
|
+
}
|
|
77
114
|
/**
|
|
78
115
|
* Trigger phrases from a description's trailing "Triggers: …" segment —
|
|
79
116
|
* the contrib pack convention ("… Use when X. Triggers: meme, image macro.").
|
|
@@ -99,7 +136,8 @@ export function clearSkillTriggerCache() {
|
|
|
99
136
|
/**
|
|
100
137
|
* True when the phrase occurs in the prompt on word boundaries ("pane" does
|
|
101
138
|
* not match "paneled"). Multi-word phrases match literally; hyphenated
|
|
102
|
-
* prompt tokens count as boundaries.
|
|
139
|
+
* prompt tokens count as boundaries. Phrases are normalized to lowercase, so
|
|
140
|
+
* the prompt is folded to match: the boundary classes stay lowercase-only.
|
|
103
141
|
*/
|
|
104
142
|
export function triggerMatches(phrase, promptText) {
|
|
105
143
|
let re = regexCache.get(phrase);
|
|
@@ -108,6 +146,6 @@ export function triggerMatches(phrase, promptText) {
|
|
|
108
146
|
re = new RegExp(`(?:^|[^a-z0-9])${escaped}(?:$|[^a-z0-9])`);
|
|
109
147
|
regexCache.set(phrase, re);
|
|
110
148
|
}
|
|
111
|
-
return re.test(promptText);
|
|
149
|
+
return re.test(promptText.toLowerCase());
|
|
112
150
|
}
|
|
113
151
|
//# sourceMappingURL=skill-triggers.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.40.
|
|
3
|
+
"version": "0.40.5",
|
|
4
4
|
"description": "Metacognitive extension suite for pi-coding-agent: enforcement, memory, reasoning, self-improvement, and structured cognitive signals.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -86,6 +86,7 @@
|
|
|
86
86
|
"pi-package",
|
|
87
87
|
"pi",
|
|
88
88
|
"pi-extension",
|
|
89
|
+
"pi-coding-agent",
|
|
89
90
|
"llm-agent",
|
|
90
91
|
"cognitive-systems",
|
|
91
92
|
"enforcement",
|
|
@@ -8,13 +8,23 @@
|
|
|
8
8
|
*
|
|
9
9
|
* Design:
|
|
10
10
|
* 1. Relevance detection: keyword match of skill name/description plus
|
|
11
|
-
*
|
|
11
|
+
* curated trigger phrases against the user's current prompt.
|
|
12
12
|
* Qualification bar: a skill whose match never touches its NAME (name
|
|
13
13
|
* token or trigger phrase) must reach a score of at least
|
|
14
14
|
* MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
|
|
15
15
|
* a signal: it fires broad skills on almost any prompt.
|
|
16
16
|
* Keywords are stemmed with one suffix rule (trailing s/es) so plural
|
|
17
17
|
* prompts hit singular name tokens ("skills" → "skill").
|
|
18
|
+
* Corpus-common words are gated out of the weak legs: a word present in
|
|
19
|
+
* COMMON_KEYWORD_DF or more of the cached skills' documents cannot tell
|
|
20
|
+
* skills apart, so description/path hits from it score nothing. Name and
|
|
21
|
+
* trigger hits are never gated — the skill's own identity vocabulary is
|
|
22
|
+
* what a prompt naming it looks like.
|
|
23
|
+
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
24
|
+
* by rarer evidence (lower summed document frequency), then by name.
|
|
25
|
+
* Alphabetical order alone decided which of two equally-scored skills
|
|
26
|
+
* took a slot, which is how a broadly-matching skill outranked the one
|
|
27
|
+
* whose evidence was the prompt's actual subject.
|
|
18
28
|
* 2. Session-scoped state: track which skills were injected on which turn.
|
|
19
29
|
* Cooldown is per-skill on top of the global floor: an injected skill
|
|
20
30
|
* cools down at least COOLDOWN_TURNS, and once it was actually loaded
|
|
@@ -145,6 +155,33 @@ export const MAX_EXCERPT_CHARS = 300;
|
|
|
145
155
|
*/
|
|
146
156
|
export const MIN_NON_NAME_SCORE = 2;
|
|
147
157
|
|
|
158
|
+
/**
|
|
159
|
+
* A keyword present in this many skill documents or more is corpus-common: it
|
|
160
|
+
* appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
|
|
161
|
+
* distinguish one skill from another and contributes NOTHING to the weak legs
|
|
162
|
+
* (description, catalog path).
|
|
163
|
+
*
|
|
164
|
+
* The number is measured, not guessed. Two measurements, one threshold:
|
|
165
|
+
*
|
|
166
|
+
* Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
|
|
167
|
+
* weak-leg points awarded to words by document frequency are df1 17.0%,
|
|
168
|
+
* df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
|
|
169
|
+
* df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
|
|
170
|
+
* awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
|
|
171
|
+
* vocabulary starts here (skill, read, prompt, text, build, change, agent,
|
|
172
|
+
* line); below it the words still describe work types (review, check, test,
|
|
173
|
+
* edit, documentation).
|
|
174
|
+
*
|
|
175
|
+
* Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
|
|
176
|
+
* df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
|
|
177
|
+
* Recall alone cannot choose the number: every step that weakens the gate
|
|
178
|
+
* admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
|
|
179
|
+
* only raise a top-2 recall figure. 5 is where the gate removes a quarter of
|
|
180
|
+
* the corpus-common mass without also deleting the work-type words that are
|
|
181
|
+
* sometimes a skill's only reachable evidence.
|
|
182
|
+
*/
|
|
183
|
+
export const COMMON_KEYWORD_DF = 5;
|
|
184
|
+
|
|
148
185
|
/**
|
|
149
186
|
* Common English words to exclude from keyword matching.
|
|
150
187
|
* Kept small — only the most frequent noise words that would
|
|
@@ -296,92 +333,202 @@ export function extractKeywords(text: string): string[] {
|
|
|
296
333
|
|
|
297
334
|
// Relevance Scoring
|
|
298
335
|
|
|
336
|
+
/**
|
|
337
|
+
* The text a skill contributes to the corpus-frequency count: its description
|
|
338
|
+
* plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
|
|
339
|
+
* path: a checkout root puts its own directory names ("private", "packages",
|
|
340
|
+
* a worktree name) in every one of the 22 documents — measured at df 22 for
|
|
341
|
+
* `private`, `package`, `pack` and `core`, and different on every machine the
|
|
342
|
+
* agent runs on. On description plus the skill's own directory those four
|
|
343
|
+
* measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
|
|
344
|
+
* file itself is named SKILL.md, and the rarity gate is what removes them.
|
|
345
|
+
* Lowercased; the matcher tests substrings. Pure.
|
|
346
|
+
*/
|
|
347
|
+
export function skillCorpusDocument(skill: CachedSkill): string {
|
|
348
|
+
const tail = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
349
|
+
return `${skill.description.toLowerCase()} ${tail}`;
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Document frequency of each keyword across the cached skills: how many skill
|
|
354
|
+
* documents contain it as a substring (the test every weak leg performs).
|
|
355
|
+
* Computed once per turn from the cache, for the prompt's keywords only. Pure
|
|
356
|
+
* given the cache.
|
|
357
|
+
*/
|
|
358
|
+
export function corpusKeywordFrequency(
|
|
359
|
+
keywords: string[],
|
|
360
|
+
skills: CachedSkill[],
|
|
361
|
+
): Map<string, number> {
|
|
362
|
+
const docs = skills.map(skillCorpusDocument);
|
|
363
|
+
const freq = new Map<string, number>();
|
|
364
|
+
for (const kw of keywords) {
|
|
365
|
+
let n = 0;
|
|
366
|
+
for (const doc of docs) if (doc.includes(kw)) n++;
|
|
367
|
+
freq.set(kw, n);
|
|
368
|
+
}
|
|
369
|
+
return freq;
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
/** One skill's match against a prompt: points, distinct signals, evidence rarity. */
|
|
373
|
+
export interface SkillMatch {
|
|
374
|
+
/** Score the qualification bar and the ranking read (same scale as before). */
|
|
375
|
+
score: number;
|
|
376
|
+
/** Distinct matched signals: each trigger phrase, each distinct keyword. */
|
|
377
|
+
signals: number;
|
|
378
|
+
/** Summed document frequency of the matched keywords — lower is rarer. */
|
|
379
|
+
evidenceDf: number;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0 };
|
|
383
|
+
|
|
299
384
|
/**
|
|
300
385
|
* Score a skill against a set of keywords.
|
|
301
386
|
*
|
|
302
387
|
* Scoring rules:
|
|
303
388
|
* +3 skill name contains a keyword (exact match)
|
|
304
389
|
* +2 skill name contains a keyword as substring
|
|
305
|
-
* +2 a
|
|
390
|
+
* +2 a trigger phrase occurs in the prompt (word-bounded)
|
|
306
391
|
* +1 skill description contains a keyword
|
|
307
|
-
* +1 skill
|
|
392
|
+
* +1 the skill's own catalog path contains a keyword (e.g. "research" in
|
|
393
|
+
* "research/skill.md")
|
|
308
394
|
*
|
|
309
395
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
310
396
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
311
397
|
*
|
|
398
|
+
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
399
|
+
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
400
|
+
* nothing on the weak legs; passing no map scores every keyword at full weight
|
|
401
|
+
* (the pre-rarity behavior, which the unit fixtures pin).
|
|
402
|
+
*
|
|
312
403
|
* Qualification bar: a skill whose match never touches its NAME (description
|
|
313
404
|
* and/or filePath hits only) must reach a total score of at least
|
|
314
405
|
* MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
|
|
315
406
|
* lets generic skills fire on almost any prompt. Name and trigger matches
|
|
316
407
|
* always qualify.
|
|
317
408
|
*
|
|
318
|
-
* `promptText`
|
|
319
|
-
* on our side) enables trigger matching; omit it where the raw prompt is not
|
|
409
|
+
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
320
410
|
* available and only keyword scoring should run.
|
|
321
411
|
*
|
|
322
|
-
* Returns
|
|
412
|
+
* Returns the zero match if the skill does not qualify.
|
|
323
413
|
*/
|
|
324
|
-
export function
|
|
414
|
+
export function matchSkill(
|
|
415
|
+
skill: CachedSkill,
|
|
416
|
+
keywords: string[],
|
|
417
|
+
promptText?: string,
|
|
418
|
+
keywordDf?: ReadonlyMap<string, number>,
|
|
419
|
+
): SkillMatch {
|
|
325
420
|
let score = 0;
|
|
421
|
+
let signals = 0;
|
|
422
|
+
let evidenceDf = 0;
|
|
326
423
|
let nameHit = false;
|
|
327
424
|
const name = skill.name.toLowerCase();
|
|
328
425
|
const desc = skill.description.toLowerCase();
|
|
329
|
-
const path = skill.filePath.toLowerCase();
|
|
426
|
+
const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
427
|
+
const dfOf = (kw: string) => keywordDf?.get(kw) ?? 0;
|
|
330
428
|
|
|
331
429
|
for (const trig of skill.triggers ?? []) {
|
|
332
430
|
if (triggerMatches(trig, promptText ?? "")) {
|
|
333
431
|
score += 2;
|
|
432
|
+
signals++;
|
|
334
433
|
nameHit = true;
|
|
434
|
+
// A curated phrase is the rarest evidence a skill can offer: df 0.
|
|
335
435
|
}
|
|
336
436
|
}
|
|
337
437
|
|
|
338
438
|
for (const kw of keywords) {
|
|
439
|
+
const df = dfOf(kw);
|
|
339
440
|
// Exact token match in name
|
|
340
441
|
if (name.split(/[^a-z0-9]+/).includes(kw)) {
|
|
341
442
|
score += 3;
|
|
443
|
+
signals++;
|
|
342
444
|
nameHit = true;
|
|
445
|
+
evidenceDf += df;
|
|
343
446
|
continue;
|
|
344
447
|
}
|
|
345
448
|
// Substring match in name (catches compound names like "code-search")
|
|
346
449
|
if (name.includes(kw)) {
|
|
347
450
|
score += 2;
|
|
451
|
+
signals++;
|
|
348
452
|
nameHit = true;
|
|
453
|
+
evidenceDf += df;
|
|
349
454
|
continue;
|
|
350
455
|
}
|
|
351
|
-
//
|
|
456
|
+
// Corpus-common keyword: the weak legs score nothing for it, so a prompt
|
|
457
|
+
// full of generic vocabulary cannot buy a slot.
|
|
458
|
+
if (df >= COMMON_KEYWORD_DF) continue;
|
|
459
|
+
let weakHit = false;
|
|
352
460
|
if (desc.includes(kw)) {
|
|
353
461
|
score += 1;
|
|
354
|
-
|
|
462
|
+
weakHit = true;
|
|
355
463
|
}
|
|
356
464
|
// File path matches (e.g. "research" in "research/SKILL.md")
|
|
357
465
|
if (path.includes(kw)) {
|
|
358
466
|
score += 1;
|
|
467
|
+
weakHit = true;
|
|
468
|
+
}
|
|
469
|
+
// One signal per distinct keyword: a word present in both the description
|
|
470
|
+
// and the path is one piece of evidence, not two.
|
|
471
|
+
if (weakHit) {
|
|
472
|
+
signals++;
|
|
473
|
+
evidenceDf += df;
|
|
359
474
|
}
|
|
360
475
|
}
|
|
361
476
|
|
|
362
|
-
if (!nameHit && score < MIN_NON_NAME_SCORE) return
|
|
363
|
-
return score;
|
|
477
|
+
if (!nameHit && score < MIN_NON_NAME_SCORE) return NO_MATCH;
|
|
478
|
+
return { score, signals, evidenceDf };
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
/** The score alone (see matchSkill for the rules and the rarity gate). */
|
|
482
|
+
export function scoreSkill(
|
|
483
|
+
skill: CachedSkill,
|
|
484
|
+
keywords: string[],
|
|
485
|
+
promptText?: string,
|
|
486
|
+
keywordDf?: ReadonlyMap<string, number>,
|
|
487
|
+
): number {
|
|
488
|
+
return matchSkill(skill, keywords, promptText, keywordDf).score;
|
|
489
|
+
}
|
|
490
|
+
|
|
491
|
+
/**
|
|
492
|
+
* A skill with its match evidence, as the selection step consumes it. The
|
|
493
|
+
* evidence fields are optional so a caller holding only a score still selects;
|
|
494
|
+
* they then default to zero and the name stays the tie-breaker.
|
|
495
|
+
*/
|
|
496
|
+
export interface ScoredSkill {
|
|
497
|
+
skill: CachedSkill;
|
|
498
|
+
score: number;
|
|
499
|
+
signals?: number;
|
|
500
|
+
evidenceDf?: number;
|
|
364
501
|
}
|
|
365
502
|
|
|
366
503
|
/**
|
|
367
504
|
* Decide which scored skills to suggest given the session injection state.
|
|
368
505
|
* Pure — mirrors the handler's decision path so it can be unit-tested:
|
|
369
|
-
* sort (score desc,
|
|
370
|
-
* loaded extension) → slot budget
|
|
371
|
-
* released its slot) → top-N slice.
|
|
506
|
+
* sort (score desc, distinct signals desc, evidence df asc, name asc) →
|
|
507
|
+
* cooldown filter (global floor + per-skill loaded extension) → slot budget
|
|
508
|
+
* over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
|
|
509
|
+
*
|
|
510
|
+
* The rank order is the fix for alphabetical slot allocation: two skills with
|
|
511
|
+
* equal points used to be ordered by name, so a broadly-matching skill took
|
|
512
|
+
* the slot from one whose evidence was the prompt's actual subject. Distinct
|
|
513
|
+
* signals separate breadth of match; evidence df separates a match on the
|
|
514
|
+
* prompt's distinctive words from one on its filler.
|
|
372
515
|
*
|
|
373
516
|
* Returns the chosen scored items (empty when nothing qualifies). The
|
|
374
517
|
* caller is responsible for recording the picks in session state.
|
|
375
518
|
*/
|
|
376
519
|
export function selectSuggestions(
|
|
377
|
-
scored:
|
|
520
|
+
scored: ScoredSkill[],
|
|
378
521
|
injected: InjectedSkill[],
|
|
379
522
|
currentTurn: number,
|
|
380
|
-
):
|
|
523
|
+
): ScoredSkill[] {
|
|
381
524
|
if (!scored.length) return [];
|
|
382
525
|
|
|
383
526
|
const sorted = [...scored].sort(
|
|
384
|
-
(a, b) =>
|
|
527
|
+
(a, b) =>
|
|
528
|
+
b.score - a.score ||
|
|
529
|
+
(b.signals ?? 0) - (a.signals ?? 0) ||
|
|
530
|
+
(a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
|
|
531
|
+
a.skill.name.localeCompare(b.skill.name),
|
|
385
532
|
);
|
|
386
533
|
|
|
387
534
|
const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
|
|
@@ -928,9 +1075,13 @@ export function registerAutoInject(pi: ExtensionAPI): void {
|
|
|
928
1075
|
return; // No significant keywords to match
|
|
929
1076
|
}
|
|
930
1077
|
|
|
1078
|
+
// Corpus-common words cannot tell skills apart. Their document frequency
|
|
1079
|
+
// is measured once per turn from the same cache the scorer reads.
|
|
1080
|
+
const keywordDf = corpusKeywordFrequency(keywords, skills);
|
|
1081
|
+
|
|
931
1082
|
// Score each skill. The raw prompt rides along for trigger matching.
|
|
932
1083
|
const scored = skills
|
|
933
|
-
.map((s) => ({ skill: s,
|
|
1084
|
+
.map((s) => ({ skill: s, ...matchSkill(s, keywords, prompt, keywordDf) }))
|
|
934
1085
|
.filter((s) => s.score > 0);
|
|
935
1086
|
|
|
936
1087
|
if (!scored.length) {
|
|
@@ -1,22 +1,40 @@
|
|
|
1
1
|
/**
|
|
2
|
-
*
|
|
2
|
+
* Curated trigger phrases for the suggestion matcher.
|
|
3
3
|
*
|
|
4
4
|
* pi's skill objects carry a fixed shape (name, description, path, source),
|
|
5
5
|
* so curated trigger phrases never reach braid through the prompt-builder
|
|
6
|
-
* cache — read them from the SKILL.md
|
|
7
|
-
*
|
|
8
|
-
*
|
|
6
|
+
* cache — read them from the SKILL.md itself. Reads are memoized by file
|
|
7
|
+
* mtime + size: repeated turns stat, only changed or first-seen files parse.
|
|
8
|
+
*
|
|
9
|
+
* Authors wrote the phrases in three places, and all three are read:
|
|
10
|
+
* 1. frontmatter, under `trigger:` (a comma-separated string) or
|
|
11
|
+
* `triggers:` (a YAML list) — the canonical field;
|
|
12
|
+
* 2. a `## trigger:` body heading, quoted or bare (9 of core's 22 skills
|
|
13
|
+
* carry the phrases here and nowhere else);
|
|
14
|
+
* 3. the description's trailing "Triggers: …" segment, the pack's older
|
|
15
|
+
* convention.
|
|
16
|
+
* A file may use any of them; the first source that yields phrases wins, so
|
|
17
|
+
* the frontmatter stays authoritative and a body heading never silently
|
|
18
|
+
* overrides it.
|
|
9
19
|
*
|
|
10
20
|
* A trigger hit scores like a name hit and qualifies a skill whose
|
|
11
21
|
* description alone would stay under the qualification bar — the phrase is
|
|
12
22
|
* the author's own signal of when the skill applies, sharper than any
|
|
13
|
-
* description keyword.
|
|
23
|
+
* description keyword. Matching is case-insensitive: prompts arrive
|
|
24
|
+
* capitalized ("MASTERSHIP TRANSFER: …"), and a phrase that only matched
|
|
25
|
+
* lowercase text would be dead in production while a lowercase-only unit
|
|
26
|
+
* fixture kept the suite green.
|
|
14
27
|
*/
|
|
15
28
|
|
|
16
29
|
import { statSync, readFileSync } from "node:fs";
|
|
17
30
|
import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
|
|
18
31
|
|
|
19
|
-
/**
|
|
32
|
+
/**
|
|
33
|
+
* Max trigger phrases read per skill — a longer list is an authoring bug, not a
|
|
34
|
+
* matcher input. Two authored lists reach the cap (braid-reference 16,
|
|
35
|
+
* pi-reference 15), so their tail phrases are not read: raising the cap needs
|
|
36
|
+
* the assertion in test-skill-decision.mjs changed with it.
|
|
37
|
+
*/
|
|
20
38
|
export const MAX_TRIGGERS = 12;
|
|
21
39
|
|
|
22
40
|
/** Max characters of one trigger phrase. */
|
|
@@ -52,12 +70,11 @@ export function normalizeTriggers(value: unknown): string[] {
|
|
|
52
70
|
}
|
|
53
71
|
|
|
54
72
|
/**
|
|
55
|
-
* Read a skill's trigger phrases: frontmatter `triggers
|
|
56
|
-
* then
|
|
57
|
-
*
|
|
58
|
-
* the matcher
|
|
59
|
-
*
|
|
60
|
-
* name/description scoring alone). Memoized: unchanged files never re-read.
|
|
73
|
+
* Read a skill's trigger phrases: frontmatter (`trigger` or `triggers`) first,
|
|
74
|
+
* then a `## trigger:` body heading, then the description's trailing
|
|
75
|
+
* "Triggers: …" segment. Missing/unreadable file or malformed YAML → no
|
|
76
|
+
* triggers (the matcher falls back to name/description scoring alone).
|
|
77
|
+
* Memoized: unchanged files never re-read.
|
|
61
78
|
*/
|
|
62
79
|
export function readSkillTriggers(filePath: string, description?: string): string[] {
|
|
63
80
|
let st;
|
|
@@ -71,8 +88,11 @@ export function readSkillTriggers(filePath: string, description?: string): strin
|
|
|
71
88
|
if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) return cached.triggers;
|
|
72
89
|
let triggers: string[];
|
|
73
90
|
try {
|
|
74
|
-
const { frontmatter } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
75
|
-
|
|
91
|
+
const { frontmatter, body } = parseFrontmatter(readFileSync(filePath, "utf-8"));
|
|
92
|
+
const fm = frontmatter as Record<string, unknown>;
|
|
93
|
+
triggers = normalizeTriggers(fm.trigger);
|
|
94
|
+
if (!triggers.length) triggers = normalizeTriggers(fm.triggers);
|
|
95
|
+
if (!triggers.length) triggers = parseBodyTriggers(body);
|
|
76
96
|
} catch {
|
|
77
97
|
triggers = []; // malformed frontmatter — score on name/description only
|
|
78
98
|
}
|
|
@@ -81,6 +101,22 @@ export function readSkillTriggers(filePath: string, description?: string): strin
|
|
|
81
101
|
return triggers;
|
|
82
102
|
}
|
|
83
103
|
|
|
104
|
+
/** First `## trigger:` / `## triggers:` heading; a heading-shaped line cannot come from frontmatter. */
|
|
105
|
+
const BODY_TRIGGER_HEADING = /^##\s*triggers?\s*:\s*(.*)$/i;
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Trigger phrases from a body `## trigger: "a, b, c"` heading. The FIRST such
|
|
109
|
+
* heading is the whole input: a body with several is an authoring error, not
|
|
110
|
+
* extra matcher input. Quotes around the value are stripped. Pure.
|
|
111
|
+
*/
|
|
112
|
+
export function parseBodyTriggers(body: string): string[] {
|
|
113
|
+
for (const line of body.split(/\r?\n/)) {
|
|
114
|
+
const match = BODY_TRIGGER_HEADING.exec(line);
|
|
115
|
+
if (match) return normalizeTriggers(match[1].trim().replace(/^["']|["']$/g, ""));
|
|
116
|
+
}
|
|
117
|
+
return [];
|
|
118
|
+
}
|
|
119
|
+
|
|
84
120
|
/**
|
|
85
121
|
* Trigger phrases from a description's trailing "Triggers: …" segment —
|
|
86
122
|
* the contrib pack convention ("… Use when X. Triggers: meme, image macro.").
|
|
@@ -106,7 +142,8 @@ export function clearSkillTriggerCache(): void {
|
|
|
106
142
|
/**
|
|
107
143
|
* True when the phrase occurs in the prompt on word boundaries ("pane" does
|
|
108
144
|
* not match "paneled"). Multi-word phrases match literally; hyphenated
|
|
109
|
-
* prompt tokens count as boundaries.
|
|
145
|
+
* prompt tokens count as boundaries. Phrases are normalized to lowercase, so
|
|
146
|
+
* the prompt is folded to match: the boundary classes stay lowercase-only.
|
|
110
147
|
*/
|
|
111
148
|
export function triggerMatches(phrase: string, promptText: string): boolean {
|
|
112
149
|
let re = regexCache.get(phrase);
|
|
@@ -115,5 +152,5 @@ export function triggerMatches(phrase: string, promptText: string): boolean {
|
|
|
115
152
|
re = new RegExp(`(?:^|[^a-z0-9])${escaped}(?:$|[^a-z0-9])`);
|
|
116
153
|
regexCache.set(phrase, re);
|
|
117
154
|
}
|
|
118
|
-
return re.test(promptText);
|
|
155
|
+
return re.test(promptText.toLowerCase());
|
|
119
156
|
}
|