pi-braid 0.43.48 → 0.43.50
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/CHANGELOG.md
CHANGED
|
@@ -96,6 +96,31 @@ Adding a thirteenth extension moves the counts six source claims pin to the mani
|
|
|
96
96
|
schema's recorded line for the `braid.contrib.*` reader; `check:doc-drift` and `check:schema` demanded
|
|
97
97
|
both repairs in the same commit.
|
|
98
98
|
|
|
99
|
+
## Core — a skill's class noun stopped qualifying it on its own (2026-11-11)
|
|
100
|
+
|
|
101
|
+
A question about search quality was answered with `cv-improvement`: the word `improvements` stems to a
|
|
102
|
+
whole token of that name, and the exact-token leg of the matcher was exempt from both the rarity gate and
|
|
103
|
+
the two-signal bar, so one ordinary English word bought a slot. The exemption now holds only for a name
|
|
104
|
+
whose token is not the prompt's own class noun: such a token is ranked but never counted toward the bar,
|
|
105
|
+
so `cv-improvement` needs a second real signal and `meta-improvement` no longer rides the same word. The
|
|
106
|
+
labelled set records the cost honestly: recall@2 moved 14/24 to 13/24, one pair (`doc-identifier-audit`,
|
|
107
|
+
reached by the same class-noun shape via `audit`), and the report shows that no knob in the matcher
|
|
108
|
+
separates that pair from the defect, so restoring it is curation's job, not the matcher's. Slots spent on
|
|
109
|
+
prompts with no applicable skill fell 3/7 to 2/7 and the reported prompt now admits nothing.
|
|
110
|
+
|
|
111
|
+
## Telegram — a heartbeat that could not write did not just fail, it ended the process (2026-11-11)
|
|
112
|
+
|
|
113
|
+
`startPollerHeartbeat` refreshed the poller lock from a `setInterval` callback that called
|
|
114
|
+
`writeLock`, which called `writeFileSync` with no handler. On a full disk that write raised `ENOSPC`
|
|
115
|
+
inside the timer, reached the uncaught-exception handler, and the agent exited: one timestamp that
|
|
116
|
+
could not be written cost the seat its channel, its poller and an in-flight turn. The lock is now
|
|
117
|
+
written to a staging file and renamed, so a failed beat cannot truncate the record that names the
|
|
118
|
+
holder; a write failure is returned instead of thrown and recorded on the heartbeat handle, which keeps
|
|
119
|
+
its schedule and clears the record on the next successful beat. Proven in a child process: the module
|
|
120
|
+
before this change exits 1 with `Timeout.beat` and an uncaught `EACCES`, the module after it survives
|
|
121
|
+
two denied beats, reports the code, keeps the record byte-identical, and advances the heartbeat once the
|
|
122
|
+
directory is writable again.
|
|
123
|
+
|
|
99
124
|
## Core — a fixture identifier that a draw could shorten below the store's floor (2026-11-11)
|
|
100
125
|
|
|
101
126
|
The cognitive-memory fixture built its unique content from `Math.random().toString(36).slice(2, 12)`,
|
package/build-info.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
4
|
-
"sha": "
|
|
5
|
-
"shaShort": "
|
|
3
|
+
"version": "0.43.50",
|
|
4
|
+
"sha": "0cbf68ab9dbcb4f9200114c3d4d64742437f90eb",
|
|
5
|
+
"shaShort": "0cbf68ab",
|
|
6
6
|
"branch": "detached",
|
|
7
7
|
"dirty": false,
|
|
8
|
-
"packedAt": "2026-11-
|
|
8
|
+
"packedAt": "2026-11-11T19:58:55.773Z"
|
|
9
9
|
}
|
|
@@ -9,10 +9,14 @@
|
|
|
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
|
-
* Qualification bar: a skill whose match never touches
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* a
|
|
12
|
+
* Qualification bar: a skill whose match never touches the IDENTITY part
|
|
13
|
+
* of its name (a differentia token, the start of one, a one-word name, or
|
|
14
|
+
* a curated trigger phrase) must reach MIN_NON_NAME_SIGNALS distinct
|
|
15
|
+
* signals — a lone description/path keyword hit is too weak a signal: it
|
|
16
|
+
* fires broad skills on almost any prompt. The final token of a compound
|
|
17
|
+
* name is the class the skill belongs to ("improvement" for any
|
|
18
|
+
* name ending -improvement), the word a prompt about that class carries,
|
|
19
|
+
* so it is ranked and never counted as evidence.
|
|
16
20
|
* Keywords are stemmed with one suffix rule (trailing s/es) so plural
|
|
17
21
|
* prompts hit singular name tokens ("skills" → "skill").
|
|
18
22
|
* Corpus-common words are gated out of the weak legs AND out of the
|
|
@@ -21,7 +25,7 @@
|
|
|
21
25
|
* description/path hits from it score nothing. A name hit is word-shaped
|
|
22
26
|
* by construction — a whole name token, or the start of one — so a word
|
|
23
27
|
* buried inside a coined token ("line" in placement-disc**line**) is not
|
|
24
|
-
* a name hit at all. A
|
|
28
|
+
* a name hit at all. A differentia token and a trigger hit are never
|
|
25
29
|
* gated: the skill's own identity vocabulary is what a prompt naming it
|
|
26
30
|
* looks like, and a curated phrase is the author's signal.
|
|
27
31
|
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
@@ -174,10 +178,17 @@ export declare const MAX_EXCERPT_CHARS = 300;
|
|
|
174
178
|
*/
|
|
175
179
|
export declare const FULL_BODY_MAX_CHARS = 12000;
|
|
176
180
|
/**
|
|
177
|
-
* Minimum
|
|
178
|
-
*
|
|
181
|
+
* Minimum number of distinct matched signals for a skill whose match never
|
|
182
|
+
* touches the identity part of its NAME (a differentia token, the start of
|
|
183
|
+
* one, a one-word name, or a trigger phrase). Identity and trigger matches
|
|
184
|
+
* qualify at any count.
|
|
185
|
+
*
|
|
186
|
+
* The unit is signals, not points: one word in both the description and the
|
|
187
|
+
* catalog path scores twice but is one piece of evidence, and a class-noun hit
|
|
188
|
+
* scores three without being evidence at all. Two distinct words are the
|
|
189
|
+
* weakest match that says anything about a skill's subject.
|
|
179
190
|
*/
|
|
180
|
-
export declare const
|
|
191
|
+
export declare const MIN_NON_NAME_SIGNALS = 2;
|
|
181
192
|
/**
|
|
182
193
|
* A keyword present in this many skill documents or more is corpus-common: it
|
|
183
194
|
* appears in a large share of the catalog, so it cannot distinguish one skill
|
|
@@ -317,6 +328,16 @@ export type RelevanceReason = "trigger" | "heading" | "name" | "description";
|
|
|
317
328
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
318
329
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
319
330
|
*
|
|
331
|
+
* A whole-token match on the FINAL token of a compound name is the class noun:
|
|
332
|
+
* the word the name shares with everything else of its kind ("improvement" for
|
|
333
|
+
* a name ending -improvement, "quality" for one ending -quality). It scores —
|
|
334
|
+
* identity vocabulary is ranked — but it qualifies nothing: a prompt about the
|
|
335
|
+
* class carries that word anyway, so it cannot be evidence about this skill,
|
|
336
|
+
* neither on its own nor as the second signal. The tokens before it are the
|
|
337
|
+
* differentia the author chose to separate this skill from everything else of
|
|
338
|
+
* that class; a match on one of them (or the whole name of a one-word skill)
|
|
339
|
+
* qualifies.
|
|
340
|
+
*
|
|
320
341
|
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
321
342
|
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
322
343
|
* nothing on the weak legs, and nothing on the name leg's token-prefix rule:
|
|
@@ -325,11 +346,11 @@ export type RelevanceReason = "trigger" | "heading" | "name" | "description";
|
|
|
325
346
|
* every keyword at full weight (the pre-rarity behavior, which the unit
|
|
326
347
|
* fixtures pin).
|
|
327
348
|
*
|
|
328
|
-
* Qualification bar: a skill whose match never touches
|
|
329
|
-
*
|
|
330
|
-
*
|
|
331
|
-
* lets generic skills fire on almost any prompt.
|
|
332
|
-
* always qualify.
|
|
349
|
+
* Qualification bar: a skill whose match never touches the identity part of
|
|
350
|
+
* its name (see the class-noun rule below) must carry at least
|
|
351
|
+
* MIN_NON_NAME_SIGNALS distinct signals — one description keyword is too weak
|
|
352
|
+
* a signal and lets generic skills fire on almost any prompt. Identity and
|
|
353
|
+
* trigger matches always qualify.
|
|
333
354
|
*
|
|
334
355
|
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
335
356
|
* available and only keyword scoring should run.
|
|
@@ -374,8 +395,8 @@ export declare function selectSuggestions(scored: ScoredSkill[], injected: Injec
|
|
|
374
395
|
* (`thin-margin`) instead of presenting the order as a decision. The number is
|
|
375
396
|
* deliberate, not measured: one description keyword (+1) is exactly the
|
|
376
397
|
* distance the scorer says is too weak to qualify a skill on its own
|
|
377
|
-
* (
|
|
378
|
-
* lead.
|
|
398
|
+
* (MIN_NON_NAME_SIGNALS), so a lead that one extra weak hit could erase is not
|
|
399
|
+
* a lead.
|
|
379
400
|
*/
|
|
380
401
|
export declare const RANK_MARGIN_THRESHOLD = 2;
|
|
381
402
|
/**
|
|
@@ -9,10 +9,14 @@
|
|
|
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
|
-
* Qualification bar: a skill whose match never touches
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* a
|
|
12
|
+
* Qualification bar: a skill whose match never touches the IDENTITY part
|
|
13
|
+
* of its name (a differentia token, the start of one, a one-word name, or
|
|
14
|
+
* a curated trigger phrase) must reach MIN_NON_NAME_SIGNALS distinct
|
|
15
|
+
* signals — a lone description/path keyword hit is too weak a signal: it
|
|
16
|
+
* fires broad skills on almost any prompt. The final token of a compound
|
|
17
|
+
* name is the class the skill belongs to ("improvement" for any
|
|
18
|
+
* name ending -improvement), the word a prompt about that class carries,
|
|
19
|
+
* so it is ranked and never counted as evidence.
|
|
16
20
|
* Keywords are stemmed with one suffix rule (trailing s/es) so plural
|
|
17
21
|
* prompts hit singular name tokens ("skills" → "skill").
|
|
18
22
|
* Corpus-common words are gated out of the weak legs AND out of the
|
|
@@ -21,7 +25,7 @@
|
|
|
21
25
|
* description/path hits from it score nothing. A name hit is word-shaped
|
|
22
26
|
* by construction — a whole name token, or the start of one — so a word
|
|
23
27
|
* buried inside a coined token ("line" in placement-disc**line**) is not
|
|
24
|
-
* a name hit at all. A
|
|
28
|
+
* a name hit at all. A differentia token and a trigger hit are never
|
|
25
29
|
* gated: the skill's own identity vocabulary is what a prompt naming it
|
|
26
30
|
* looks like, and a curated phrase is the author's signal.
|
|
27
31
|
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
@@ -189,10 +193,17 @@ export const MAX_EXCERPT_CHARS = 300;
|
|
|
189
193
|
*/
|
|
190
194
|
export const FULL_BODY_MAX_CHARS = 12_000;
|
|
191
195
|
/**
|
|
192
|
-
* Minimum
|
|
193
|
-
*
|
|
196
|
+
* Minimum number of distinct matched signals for a skill whose match never
|
|
197
|
+
* touches the identity part of its NAME (a differentia token, the start of
|
|
198
|
+
* one, a one-word name, or a trigger phrase). Identity and trigger matches
|
|
199
|
+
* qualify at any count.
|
|
200
|
+
*
|
|
201
|
+
* The unit is signals, not points: one word in both the description and the
|
|
202
|
+
* catalog path scores twice but is one piece of evidence, and a class-noun hit
|
|
203
|
+
* scores three without being evidence at all. Two distinct words are the
|
|
204
|
+
* weakest match that says anything about a skill's subject.
|
|
194
205
|
*/
|
|
195
|
-
export const
|
|
206
|
+
export const MIN_NON_NAME_SIGNALS = 2;
|
|
196
207
|
/**
|
|
197
208
|
* A keyword present in this many skill documents or more is corpus-common: it
|
|
198
209
|
* appears in a large share of the catalog, so it cannot distinguish one skill
|
|
@@ -396,23 +407,27 @@ const REASON_STRENGTH = {
|
|
|
396
407
|
description: 1,
|
|
397
408
|
};
|
|
398
409
|
/**
|
|
399
|
-
*
|
|
400
|
-
*
|
|
410
|
+
* Where a keyword occurs in a skill name: which token it names, and whether it
|
|
411
|
+
* is that whole token or only its start. Null when it occurs nowhere.
|
|
401
412
|
*
|
|
402
|
-
* The
|
|
403
|
-
*
|
|
404
|
-
*
|
|
405
|
-
*
|
|
406
|
-
*
|
|
407
|
-
*
|
|
408
|
-
*
|
|
413
|
+
* The spellings matter because they carry different authority. The third
|
|
414
|
+
* answer — no occurrence — is the earlier fix: the name leg used to award
|
|
415
|
+
* points to any substring anywhere in the name, so a corpus-common word ("line",
|
|
416
|
+
* df 7 of 22) scored +2 for two coined names that ended -line and -pipeline and
|
|
417
|
+
* carried the name-hit exemption from the qualification bar with it. A word
|
|
418
|
+
* buried inside a coined token names the author's coinage, not the prompt's
|
|
419
|
+
* subject; a word that starts a token still reads as the author's own
|
|
420
|
+
* vocabulary ("engine" starting "engineer").
|
|
409
421
|
*/
|
|
410
422
|
function nameOccurrence(tokens, kw) {
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
423
|
+
const exact = tokens.indexOf(kw);
|
|
424
|
+
if (exact >= 0)
|
|
425
|
+
return { index: exact, form: "token" };
|
|
426
|
+
for (let index = 0; index < tokens.length; index++) {
|
|
427
|
+
const token = tokens[index];
|
|
414
428
|
if (token.length > kw.length && token.startsWith(kw))
|
|
415
|
-
return "prefix";
|
|
429
|
+
return { index, form: "prefix" };
|
|
430
|
+
}
|
|
416
431
|
return null;
|
|
417
432
|
}
|
|
418
433
|
const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0, reason: null };
|
|
@@ -430,6 +445,16 @@ const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0, reason: null };
|
|
|
430
445
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
431
446
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
432
447
|
*
|
|
448
|
+
* A whole-token match on the FINAL token of a compound name is the class noun:
|
|
449
|
+
* the word the name shares with everything else of its kind ("improvement" for
|
|
450
|
+
* a name ending -improvement, "quality" for one ending -quality). It scores —
|
|
451
|
+
* identity vocabulary is ranked — but it qualifies nothing: a prompt about the
|
|
452
|
+
* class carries that word anyway, so it cannot be evidence about this skill,
|
|
453
|
+
* neither on its own nor as the second signal. The tokens before it are the
|
|
454
|
+
* differentia the author chose to separate this skill from everything else of
|
|
455
|
+
* that class; a match on one of them (or the whole name of a one-word skill)
|
|
456
|
+
* qualifies.
|
|
457
|
+
*
|
|
433
458
|
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
434
459
|
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
435
460
|
* nothing on the weak legs, and nothing on the name leg's token-prefix rule:
|
|
@@ -438,11 +463,11 @@ const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0, reason: null };
|
|
|
438
463
|
* every keyword at full weight (the pre-rarity behavior, which the unit
|
|
439
464
|
* fixtures pin).
|
|
440
465
|
*
|
|
441
|
-
* Qualification bar: a skill whose match never touches
|
|
442
|
-
*
|
|
443
|
-
*
|
|
444
|
-
* lets generic skills fire on almost any prompt.
|
|
445
|
-
* always qualify.
|
|
466
|
+
* Qualification bar: a skill whose match never touches the identity part of
|
|
467
|
+
* its name (see the class-noun rule below) must carry at least
|
|
468
|
+
* MIN_NON_NAME_SIGNALS distinct signals — one description keyword is too weak
|
|
469
|
+
* a signal and lets generic skills fire on almost any prompt. Identity and
|
|
470
|
+
* trigger matches always qualify.
|
|
446
471
|
*
|
|
447
472
|
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
448
473
|
* available and only keyword scoring should run.
|
|
@@ -452,6 +477,7 @@ const NO_MATCH = { score: 0, signals: 0, evidenceDf: 0, reason: null };
|
|
|
452
477
|
export function matchSkill(skill, keywords, promptText, keywordDf) {
|
|
453
478
|
let score = 0;
|
|
454
479
|
let signals = 0;
|
|
480
|
+
let qualifying = 0;
|
|
455
481
|
let evidenceDf = 0;
|
|
456
482
|
let nameHit = false;
|
|
457
483
|
let reason = null;
|
|
@@ -461,6 +487,8 @@ export function matchSkill(skill, keywords, promptText, keywordDf) {
|
|
|
461
487
|
};
|
|
462
488
|
const name = skill.name.toLowerCase();
|
|
463
489
|
const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
|
|
490
|
+
// The class the name belongs to: the final token of a compound name.
|
|
491
|
+
const classToken = nameTokens.length > 1 ? nameTokens.length - 1 : -1;
|
|
464
492
|
const desc = skill.description.toLowerCase();
|
|
465
493
|
const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
466
494
|
const dfOf = (kw) => keywordDf?.get(kw) ?? 0;
|
|
@@ -477,23 +505,31 @@ export function matchSkill(skill, keywords, promptText, keywordDf) {
|
|
|
477
505
|
for (const kw of keywords) {
|
|
478
506
|
const df = dfOf(kw);
|
|
479
507
|
const occurrence = nameOccurrence(nameTokens, kw);
|
|
480
|
-
//
|
|
481
|
-
|
|
508
|
+
// The class noun: the whole final token of a compound name. A word that
|
|
509
|
+
// only starts that token ("engine" in "engineer") is already gated by
|
|
510
|
+
// corpus frequency, so it keeps the weight of the author's own vocabulary;
|
|
511
|
+
// the whole class token is what every skill of the class shares.
|
|
512
|
+
const classNoun = occurrence?.form === "token" && occurrence.index === classToken;
|
|
513
|
+
if (occurrence?.form === "token") {
|
|
482
514
|
score += 3;
|
|
483
515
|
signals++;
|
|
484
|
-
nameHit = true;
|
|
485
516
|
evidenceDf += df;
|
|
486
517
|
noteReason("name");
|
|
518
|
+
if (!classNoun) {
|
|
519
|
+
nameHit = true;
|
|
520
|
+
qualifying++;
|
|
521
|
+
}
|
|
487
522
|
continue;
|
|
488
523
|
}
|
|
489
|
-
// Token-prefix match in name ("engine"
|
|
524
|
+
// Token-prefix match in name ("engine" starting "engineer"): name
|
|
490
525
|
// evidence, but only while the word is distinctive enough to mean it.
|
|
491
|
-
if (occurrence === "prefix" && df < COMMON_KEYWORD_DF) {
|
|
526
|
+
if (occurrence?.form === "prefix" && df < COMMON_KEYWORD_DF) {
|
|
492
527
|
score += 2;
|
|
493
528
|
signals++;
|
|
494
|
-
nameHit = true;
|
|
495
529
|
evidenceDf += df;
|
|
496
530
|
noteReason("name");
|
|
531
|
+
nameHit = true;
|
|
532
|
+
qualifying++;
|
|
497
533
|
continue;
|
|
498
534
|
}
|
|
499
535
|
// Corpus-common keyword: the weak legs score nothing for it, so a prompt
|
|
@@ -511,14 +547,16 @@ export function matchSkill(skill, keywords, promptText, keywordDf) {
|
|
|
511
547
|
weakHit = true;
|
|
512
548
|
}
|
|
513
549
|
// One signal per distinct keyword: a word present in both the description
|
|
514
|
-
// and the path is one piece of evidence, not two.
|
|
550
|
+
// and the path is one piece of evidence, not two. The score counts both
|
|
551
|
+
// fields; the qualification bar counts the word once.
|
|
515
552
|
if (weakHit) {
|
|
516
553
|
signals++;
|
|
554
|
+
qualifying++;
|
|
517
555
|
evidenceDf += df;
|
|
518
556
|
noteReason("description");
|
|
519
557
|
}
|
|
520
558
|
}
|
|
521
|
-
if (!nameHit &&
|
|
559
|
+
if (!nameHit && qualifying < MIN_NON_NAME_SIGNALS)
|
|
522
560
|
return NO_MATCH;
|
|
523
561
|
return { score, signals, evidenceDf, reason };
|
|
524
562
|
}
|
|
@@ -576,8 +614,8 @@ export function selectSuggestions(scored, injected, currentTurn) {
|
|
|
576
614
|
* (`thin-margin`) instead of presenting the order as a decision. The number is
|
|
577
615
|
* deliberate, not measured: one description keyword (+1) is exactly the
|
|
578
616
|
* distance the scorer says is too weak to qualify a skill on its own
|
|
579
|
-
* (
|
|
580
|
-
* lead.
|
|
617
|
+
* (MIN_NON_NAME_SIGNALS), so a lead that one extra weak hit could erase is not
|
|
618
|
+
* a lead.
|
|
581
619
|
*/
|
|
582
620
|
export const RANK_MARGIN_THRESHOLD = 2;
|
|
583
621
|
/**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-braid",
|
|
3
|
-
"version": "0.43.
|
|
3
|
+
"version": "0.43.50",
|
|
4
4
|
"description": "🥨 Braid - Metacognitive extension suite for pi coding agent: Adds memory, plan tracking, structured cognitive signals and completion checks on top of pi core loop, so long sessions keep their context and stop claiming unfinished work.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -9,10 +9,14 @@
|
|
|
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
|
-
* Qualification bar: a skill whose match never touches
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
* a
|
|
12
|
+
* Qualification bar: a skill whose match never touches the IDENTITY part
|
|
13
|
+
* of its name (a differentia token, the start of one, a one-word name, or
|
|
14
|
+
* a curated trigger phrase) must reach MIN_NON_NAME_SIGNALS distinct
|
|
15
|
+
* signals — a lone description/path keyword hit is too weak a signal: it
|
|
16
|
+
* fires broad skills on almost any prompt. The final token of a compound
|
|
17
|
+
* name is the class the skill belongs to ("improvement" for any
|
|
18
|
+
* name ending -improvement), the word a prompt about that class carries,
|
|
19
|
+
* so it is ranked and never counted as evidence.
|
|
16
20
|
* Keywords are stemmed with one suffix rule (trailing s/es) so plural
|
|
17
21
|
* prompts hit singular name tokens ("skills" → "skill").
|
|
18
22
|
* Corpus-common words are gated out of the weak legs AND out of the
|
|
@@ -21,7 +25,7 @@
|
|
|
21
25
|
* description/path hits from it score nothing. A name hit is word-shaped
|
|
22
26
|
* by construction — a whole name token, or the start of one — so a word
|
|
23
27
|
* buried inside a coined token ("line" in placement-disc**line**) is not
|
|
24
|
-
* a name hit at all. A
|
|
28
|
+
* a name hit at all. A differentia token and a trigger hit are never
|
|
25
29
|
* gated: the skill's own identity vocabulary is what a prompt naming it
|
|
26
30
|
* looks like, and a curated phrase is the author's signal.
|
|
27
31
|
* 1b. Ranking: equal scores compare by more distinct matched signals, then
|
|
@@ -221,10 +225,17 @@ export const MAX_EXCERPT_CHARS = 300;
|
|
|
221
225
|
export const FULL_BODY_MAX_CHARS = 12_000;
|
|
222
226
|
|
|
223
227
|
/**
|
|
224
|
-
* Minimum
|
|
225
|
-
*
|
|
228
|
+
* Minimum number of distinct matched signals for a skill whose match never
|
|
229
|
+
* touches the identity part of its NAME (a differentia token, the start of
|
|
230
|
+
* one, a one-word name, or a trigger phrase). Identity and trigger matches
|
|
231
|
+
* qualify at any count.
|
|
232
|
+
*
|
|
233
|
+
* The unit is signals, not points: one word in both the description and the
|
|
234
|
+
* catalog path scores twice but is one piece of evidence, and a class-noun hit
|
|
235
|
+
* scores three without being evidence at all. Two distinct words are the
|
|
236
|
+
* weakest match that says anything about a skill's subject.
|
|
226
237
|
*/
|
|
227
|
-
export const
|
|
238
|
+
export const MIN_NON_NAME_SIGNALS = 2;
|
|
228
239
|
|
|
229
240
|
/**
|
|
230
241
|
* A keyword present in this many skill documents or more is corpus-common: it
|
|
@@ -560,20 +571,28 @@ const REASON_STRENGTH: Record<RelevanceReason, number> = {
|
|
|
560
571
|
};
|
|
561
572
|
|
|
562
573
|
/**
|
|
563
|
-
*
|
|
564
|
-
*
|
|
574
|
+
* Where a keyword occurs in a skill name: which token it names, and whether it
|
|
575
|
+
* is that whole token or only its start. Null when it occurs nowhere.
|
|
565
576
|
*
|
|
566
|
-
* The
|
|
567
|
-
*
|
|
568
|
-
*
|
|
569
|
-
*
|
|
570
|
-
*
|
|
571
|
-
*
|
|
572
|
-
*
|
|
577
|
+
* The spellings matter because they carry different authority. The third
|
|
578
|
+
* answer — no occurrence — is the earlier fix: the name leg used to award
|
|
579
|
+
* points to any substring anywhere in the name, so a corpus-common word ("line",
|
|
580
|
+
* df 7 of 22) scored +2 for two coined names that ended -line and -pipeline and
|
|
581
|
+
* carried the name-hit exemption from the qualification bar with it. A word
|
|
582
|
+
* buried inside a coined token names the author's coinage, not the prompt's
|
|
583
|
+
* subject; a word that starts a token still reads as the author's own
|
|
584
|
+
* vocabulary ("engine" starting "engineer").
|
|
573
585
|
*/
|
|
574
|
-
function nameOccurrence(
|
|
575
|
-
|
|
576
|
-
|
|
586
|
+
function nameOccurrence(
|
|
587
|
+
tokens: string[],
|
|
588
|
+
kw: string,
|
|
589
|
+
): { index: number; form: "token" | "prefix" } | null {
|
|
590
|
+
const exact = tokens.indexOf(kw);
|
|
591
|
+
if (exact >= 0) return { index: exact, form: "token" };
|
|
592
|
+
for (let index = 0; index < tokens.length; index++) {
|
|
593
|
+
const token = tokens[index];
|
|
594
|
+
if (token.length > kw.length && token.startsWith(kw)) return { index, form: "prefix" };
|
|
595
|
+
}
|
|
577
596
|
return null;
|
|
578
597
|
}
|
|
579
598
|
|
|
@@ -593,6 +612,16 @@ const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0, reason: null
|
|
|
593
612
|
* A trigger hit counts as a name hit: the phrase is the skill author's own
|
|
594
613
|
* relevance signal, so it qualifies the skill the same way a name match does.
|
|
595
614
|
*
|
|
615
|
+
* A whole-token match on the FINAL token of a compound name is the class noun:
|
|
616
|
+
* the word the name shares with everything else of its kind ("improvement" for
|
|
617
|
+
* a name ending -improvement, "quality" for one ending -quality). It scores —
|
|
618
|
+
* identity vocabulary is ranked — but it qualifies nothing: a prompt about the
|
|
619
|
+
* class carries that word anyway, so it cannot be evidence about this skill,
|
|
620
|
+
* neither on its own nor as the second signal. The tokens before it are the
|
|
621
|
+
* differentia the author chose to separate this skill from everything else of
|
|
622
|
+
* that class; a match on one of them (or the whole name of a one-word skill)
|
|
623
|
+
* qualifies.
|
|
624
|
+
*
|
|
596
625
|
* `keywordDf` is the corpus document frequency of the prompt's keywords (see
|
|
597
626
|
* corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
|
|
598
627
|
* nothing on the weak legs, and nothing on the name leg's token-prefix rule:
|
|
@@ -601,11 +630,11 @@ const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0, reason: null
|
|
|
601
630
|
* every keyword at full weight (the pre-rarity behavior, which the unit
|
|
602
631
|
* fixtures pin).
|
|
603
632
|
*
|
|
604
|
-
* Qualification bar: a skill whose match never touches
|
|
605
|
-
*
|
|
606
|
-
*
|
|
607
|
-
* lets generic skills fire on almost any prompt.
|
|
608
|
-
* always qualify.
|
|
633
|
+
* Qualification bar: a skill whose match never touches the identity part of
|
|
634
|
+
* its name (see the class-noun rule below) must carry at least
|
|
635
|
+
* MIN_NON_NAME_SIGNALS distinct signals — one description keyword is too weak
|
|
636
|
+
* a signal and lets generic skills fire on almost any prompt. Identity and
|
|
637
|
+
* trigger matches always qualify.
|
|
609
638
|
*
|
|
610
639
|
* `promptText` enables trigger matching; omit it where the raw prompt is not
|
|
611
640
|
* available and only keyword scoring should run.
|
|
@@ -620,6 +649,7 @@ export function matchSkill(
|
|
|
620
649
|
): SkillMatch {
|
|
621
650
|
let score = 0;
|
|
622
651
|
let signals = 0;
|
|
652
|
+
let qualifying = 0;
|
|
623
653
|
let evidenceDf = 0;
|
|
624
654
|
let nameHit = false;
|
|
625
655
|
let reason: RelevanceReason | null = null;
|
|
@@ -628,6 +658,8 @@ export function matchSkill(
|
|
|
628
658
|
};
|
|
629
659
|
const name = skill.name.toLowerCase();
|
|
630
660
|
const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
|
|
661
|
+
// The class the name belongs to: the final token of a compound name.
|
|
662
|
+
const classToken = nameTokens.length > 1 ? nameTokens.length - 1 : -1;
|
|
631
663
|
const desc = skill.description.toLowerCase();
|
|
632
664
|
const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
|
|
633
665
|
const dfOf = (kw: string) => keywordDf?.get(kw) ?? 0;
|
|
@@ -646,23 +678,31 @@ export function matchSkill(
|
|
|
646
678
|
for (const kw of keywords) {
|
|
647
679
|
const df = dfOf(kw);
|
|
648
680
|
const occurrence = nameOccurrence(nameTokens, kw);
|
|
649
|
-
//
|
|
650
|
-
|
|
681
|
+
// The class noun: the whole final token of a compound name. A word that
|
|
682
|
+
// only starts that token ("engine" in "engineer") is already gated by
|
|
683
|
+
// corpus frequency, so it keeps the weight of the author's own vocabulary;
|
|
684
|
+
// the whole class token is what every skill of the class shares.
|
|
685
|
+
const classNoun = occurrence?.form === "token" && occurrence.index === classToken;
|
|
686
|
+
if (occurrence?.form === "token") {
|
|
651
687
|
score += 3;
|
|
652
688
|
signals++;
|
|
653
|
-
nameHit = true;
|
|
654
689
|
evidenceDf += df;
|
|
655
690
|
noteReason("name");
|
|
691
|
+
if (!classNoun) {
|
|
692
|
+
nameHit = true;
|
|
693
|
+
qualifying++;
|
|
694
|
+
}
|
|
656
695
|
continue;
|
|
657
696
|
}
|
|
658
|
-
// Token-prefix match in name ("engine"
|
|
697
|
+
// Token-prefix match in name ("engine" starting "engineer"): name
|
|
659
698
|
// evidence, but only while the word is distinctive enough to mean it.
|
|
660
|
-
if (occurrence === "prefix" && df < COMMON_KEYWORD_DF) {
|
|
699
|
+
if (occurrence?.form === "prefix" && df < COMMON_KEYWORD_DF) {
|
|
661
700
|
score += 2;
|
|
662
701
|
signals++;
|
|
663
|
-
nameHit = true;
|
|
664
702
|
evidenceDf += df;
|
|
665
703
|
noteReason("name");
|
|
704
|
+
nameHit = true;
|
|
705
|
+
qualifying++;
|
|
666
706
|
continue;
|
|
667
707
|
}
|
|
668
708
|
// Corpus-common keyword: the weak legs score nothing for it, so a prompt
|
|
@@ -679,15 +719,17 @@ export function matchSkill(
|
|
|
679
719
|
weakHit = true;
|
|
680
720
|
}
|
|
681
721
|
// One signal per distinct keyword: a word present in both the description
|
|
682
|
-
// and the path is one piece of evidence, not two.
|
|
722
|
+
// and the path is one piece of evidence, not two. The score counts both
|
|
723
|
+
// fields; the qualification bar counts the word once.
|
|
683
724
|
if (weakHit) {
|
|
684
725
|
signals++;
|
|
726
|
+
qualifying++;
|
|
685
727
|
evidenceDf += df;
|
|
686
728
|
noteReason("description");
|
|
687
729
|
}
|
|
688
730
|
}
|
|
689
731
|
|
|
690
|
-
if (!nameHit &&
|
|
732
|
+
if (!nameHit && qualifying < MIN_NON_NAME_SIGNALS) return NO_MATCH;
|
|
691
733
|
return { score, signals, evidenceDf, reason };
|
|
692
734
|
}
|
|
693
735
|
|
|
@@ -773,8 +815,8 @@ export function selectSuggestions(
|
|
|
773
815
|
* (`thin-margin`) instead of presenting the order as a decision. The number is
|
|
774
816
|
* deliberate, not measured: one description keyword (+1) is exactly the
|
|
775
817
|
* distance the scorer says is too weak to qualify a skill on its own
|
|
776
|
-
* (
|
|
777
|
-
* lead.
|
|
818
|
+
* (MIN_NON_NAME_SIGNALS), so a lead that one extra weak hit could erase is not
|
|
819
|
+
* a lead.
|
|
778
820
|
*/
|
|
779
821
|
export const RANK_MARGIN_THRESHOLD = 2;
|
|
780
822
|
|