pi-braid 0.43.46 → 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,53 @@ 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
+
124
+ ## Core — a fixture identifier that a draw could shorten below the store's floor (2026-11-11)
125
+
126
+ The cognitive-memory fixture built its unique content from `Math.random().toString(36).slice(2, 12)`,
127
+ which returns fewer than ten characters whenever the draw's base-36 expansion ends in a run of zeroes:
128
+ 0.72% of 200,000 draws, measured, and `delete_me_` plus a nine-character suffix is nineteen characters,
129
+ one below the store's twenty-character floor. The store then refused the write and the suite reported
130
+ a duplicate-content failure in a test about deletion. The publisher's gate run hit that draw. The
131
+ suffix is now padded to a fixed width, so the tightest content sits two characters above the floor,
132
+ and the planted one-character draw that reproduces the old failure is recorded in the release notes
133
+ rather than left to chance.
134
+
135
+ ## Providers — a port is not an HTTP status, and a timeout is not a refusal (2026-11-11)
136
+
137
+ `classifyFailure` read the first three-digit run in an error text as an HTTP status, so a connect
138
+ timeout whose text carried `host:443` arrived as a shape rejection with "HTTP 443" and the walk
139
+ rotated the route away from a provider that had not refused anything. Driven through the sources: the
140
+ literal transport error now classifies `transport`, `status 403 from 10.0.0.1:443` still classifies
141
+ `key` with status 403, a bare `ECONNRESET at 203.0.113.7:443` classifies `transport`, and `HTTP 400`
142
+ still classifies `shape`. A status is accepted only where the text frames it as one, and a transport
143
+ failure means no key exhausted, no rotation and no marker claiming a refusal: the route's health is
144
+ the connectivity watchdog's business, not the rotation walk's.
145
+
99
146
  ## Core — 0.43.45 (2026-11-11: a re-read is a covered range, not a repeated path)
100
147
 
101
148
  The re-read whisper keyed `recentlyReadFiles` on the path, so a second slice of one document in a turn
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.46",
4
- "sha": "a57f85f08833b98c46ae3b5b171cc0eec520bd25",
5
- "shaShort": "a57f85f0",
3
+ "version": "0.43.50",
4
+ "sha": "0cbf68ab9dbcb4f9200114c3d4d64742437f90eb",
5
+ "shaShort": "0cbf68ab",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-11T08:48:25.856Z"
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 its NAME (name
13
- * token or trigger phrase) must reach a score of at least
14
- * MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
15
- * a signal: it fires broad skills on almost any prompt.
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 whole-name-token hit and a trigger hit are never
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 score for a skill whose match never touches its NAME (description
178
- * and/or filePath keyword hits only). Name matches qualify at any score.
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 MIN_NON_NAME_SCORE = 2;
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 its NAME (description
329
- * and/or filePath hits only) must reach a total score of at least
330
- * MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
331
- * lets generic skills fire on almost any prompt. Name and trigger matches
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
- * (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
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 its NAME (name
13
- * token or trigger phrase) must reach a score of at least
14
- * MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
15
- * a signal: it fires broad skills on almost any prompt.
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 whole-name-token hit and a trigger hit are never
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 score for a skill whose match never touches its NAME (description
193
- * and/or filePath keyword hits only). Name matches qualify at any score.
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 MIN_NON_NAME_SCORE = 2;
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
- * How a keyword occurs in a skill name: as a whole token, as the start of a
400
- * longer token, or not at all.
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 third answer is the fix: the name leg used to award points to any
403
- * substring anywhere in the name, so a corpus-common word ("line", df 7 of 22)
404
- * scored +2 for placement-disc**line** and release-pi**peline** and carried the
405
- * name-hit exemption from the qualification bar with it. A word buried inside
406
- * a coined token names the author's coinage, not the prompt's subject; a word
407
- * that starts a token still reads as the author's own vocabulary ("engine" in
408
- * software-engineer).
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
- if (tokens.includes(kw))
412
- return "token";
413
- for (const token of tokens)
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 its NAME (description
442
- * and/or filePath hits only) must reach a total score of at least
443
- * MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
444
- * lets generic skills fire on almost any prompt. Name and trigger matches
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
- // Exact token match in name: the skill's own identity vocabulary, never gated.
481
- if (occurrence === "token") {
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" in "software-engineer"): name
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 && score < MIN_NON_NAME_SCORE)
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
- * (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
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.46",
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 its NAME (name
13
- * token or trigger phrase) must reach a score of at least
14
- * MIN_NON_NAME_SCORE — a lone description/path keyword hit is too weak
15
- * a signal: it fires broad skills on almost any prompt.
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 whole-name-token hit and a trigger hit are never
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 score for a skill whose match never touches its NAME (description
225
- * and/or filePath keyword hits only). Name matches qualify at any score.
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 MIN_NON_NAME_SCORE = 2;
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
- * How a keyword occurs in a skill name: as a whole token, as the start of a
564
- * longer token, or not at all.
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 third answer is the fix: the name leg used to award points to any
567
- * substring anywhere in the name, so a corpus-common word ("line", df 7 of 22)
568
- * scored +2 for placement-disc**line** and release-pi**peline** and carried the
569
- * name-hit exemption from the qualification bar with it. A word buried inside
570
- * a coined token names the author's coinage, not the prompt's subject; a word
571
- * that starts a token still reads as the author's own vocabulary ("engine" in
572
- * software-engineer).
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(tokens: string[], kw: string): "token" | "prefix" | null {
575
- if (tokens.includes(kw)) return "token";
576
- for (const token of tokens) if (token.length > kw.length && token.startsWith(kw)) return "prefix";
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 its NAME (description
605
- * and/or filePath hits only) must reach a total score of at least
606
- * MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
607
- * lets generic skills fire on almost any prompt. Name and trigger matches
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
- // Exact token match in name: the skill's own identity vocabulary, never gated.
650
- if (occurrence === "token") {
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" in "software-engineer"): name
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 && score < MIN_NON_NAME_SCORE) return NO_MATCH;
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
- * (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
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