pi-braid 0.40.3 → 0.40.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/AGENTS.md +17 -18
  2. package/README.md +116 -130
  3. package/TOOLS.md +35 -35
  4. package/build-info.json +4 -4
  5. package/dist/extensions/core/agent-environment/index.js +4 -3
  6. package/dist/extensions/core/prompt-builder/index.js +12 -7
  7. package/dist/extensions/core/prompt-builder/instance-composition.d.ts +51 -10
  8. package/dist/extensions/core/prompt-builder/instance-composition.js +87 -14
  9. package/dist/extensions/core/prompt-builder/system-info-tool.d.ts +3 -3
  10. package/dist/extensions/core/prompt-builder/system-info-tool.js +3 -3
  11. package/dist/extensions/core/prompt-builder/tool-guidelines.js +1 -1
  12. package/dist/extensions/core/skills-tool/auto-inject.d.ts +178 -17
  13. package/dist/extensions/core/skills-tool/auto-inject.js +264 -23
  14. package/dist/extensions/core/skills-tool/index.d.ts +70 -2
  15. package/dist/extensions/core/skills-tool/index.js +149 -15
  16. package/dist/extensions/core/skills-tool/reach.d.ts +119 -0
  17. package/dist/extensions/core/skills-tool/reach.js +213 -0
  18. package/dist/extensions/core/skills-tool/skill-triggers.d.ts +74 -13
  19. package/dist/extensions/core/skills-tool/skill-triggers.js +105 -24
  20. package/dist/extensions/enforcement/handlers/register-session-compact.js +12 -1
  21. package/dist/extensions/enforcement/handlers/register-session-shutdown-resumption.js +15 -34
  22. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.d.ts +2 -1
  23. package/dist/extensions/enforcement/handlers/register-session-start-discoverability.js +55 -28
  24. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.d.ts +14 -10
  25. package/dist/extensions/enforcement/handlers/register-turn-end-hygiene.js +88 -82
  26. package/dist/extensions/enforcement/resume-state.d.ts +76 -0
  27. package/dist/extensions/enforcement/resume-state.js +90 -0
  28. package/dist/extensions/enforcement/substate/context-hygiene-state.d.ts +9 -0
  29. package/dist/extensions/enforcement/substate/context-hygiene-state.js +8 -0
  30. package/dist/extensions/enforcement/whisper.d.ts +12 -0
  31. package/dist/extensions/enforcement/whisper.js +16 -1
  32. package/dist/extensions/heartbeat/heartbeat-scheduler/index.js +14 -6
  33. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.d.ts +7 -0
  34. package/dist/extensions/heartbeat/heartbeat-scheduler/policies.js +372 -0
  35. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.d.ts +8 -2
  36. package/dist/extensions/memory/context-manager/handlers/tools/context-compress.js +54 -21
  37. package/dist/lib/config/braid-paths.d.ts +14 -0
  38. package/dist/lib/config/braid-paths.js +18 -0
  39. package/dist/lib/config/braid-settings.d.ts +21 -0
  40. package/dist/lib/config/braid-settings.js +16 -0
  41. package/dist/lib/detection/context-tiers.d.ts +47 -3
  42. package/dist/lib/detection/context-tiers.js +122 -13
  43. package/dist/lib/events/turn-boundary.d.ts +78 -0
  44. package/dist/lib/events/turn-boundary.js +91 -0
  45. package/dist/lib/orchestrator/workers.d.ts +3 -2
  46. package/dist/lib/orchestrator/workers.js +22 -4
  47. package/dist/lib/state/global-state.d.ts +1 -1
  48. package/docs/CONTEXT-POLICY.md +8 -0
  49. package/docs/LOCAL_DEV.md +0 -1
  50. package/docs/ROADMAP.md +5 -5
  51. package/docs/SETUP.md +19 -18
  52. package/package.json +2 -1
  53. package/skills/herdr-topology/SKILL.md +6 -1
  54. package/skills/research/SKILL.md +32 -0
  55. package/skills/subagent-orchestration/SKILL.md +2 -2
  56. package/src/extensions/core/agent-environment/index.ts +4 -3
  57. package/src/extensions/core/prompt-builder/AGENTS.md +8 -4
  58. package/src/extensions/core/prompt-builder/index.ts +12 -7
  59. package/src/extensions/core/prompt-builder/instance-composition.ts +98 -14
  60. package/src/extensions/core/prompt-builder/system-info-tool.ts +3 -3
  61. package/src/extensions/core/prompt-builder/tool-guidelines.ts +1 -1
  62. package/src/extensions/core/skills-tool/auto-inject.ts +350 -27
  63. package/src/extensions/core/skills-tool/index.ts +217 -15
  64. package/src/extensions/core/skills-tool/reach.ts +256 -0
  65. package/src/extensions/core/skills-tool/skill-triggers.ts +130 -23
  66. package/src/extensions/enforcement/handlers/register-session-compact.ts +12 -1
  67. package/src/extensions/enforcement/handlers/register-session-shutdown-resumption.ts +23 -36
  68. package/src/extensions/enforcement/handlers/register-session-start-discoverability.ts +59 -29
  69. package/src/extensions/enforcement/handlers/register-turn-end-hygiene.ts +101 -81
  70. package/src/extensions/enforcement/resume-state.ts +127 -0
  71. package/src/extensions/enforcement/substate/context-hygiene-state.ts +17 -0
  72. package/src/extensions/enforcement/whisper.ts +21 -1
  73. package/src/extensions/heartbeat/heartbeat-scheduler/index.ts +20 -5
  74. package/src/extensions/heartbeat/heartbeat-scheduler/policies.ts +370 -0
  75. package/src/extensions/memory/AGENTS.md +25 -1
  76. package/src/extensions/memory/context-manager/handlers/tools/context-compress.ts +80 -27
  77. package/src/lib/config/braid-paths.ts +20 -0
  78. package/src/lib/config/braid-settings.ts +46 -0
  79. package/src/lib/detection/context-tiers.ts +186 -13
  80. package/src/lib/events/AGENTS.md +1 -0
  81. package/src/lib/events/turn-boundary.ts +115 -0
  82. package/src/lib/orchestrator/workers.ts +33 -12
  83. package/src/lib/state/global-state.ts +1 -0
  84. package/src/lib/utils/AGENTS.md +1 -1
  85. package/src/types/extension-context.d.ts +22 -79
@@ -8,13 +8,27 @@
8
8
  *
9
9
  * Design:
10
10
  * 1. Relevance detection: keyword match of skill name/description plus
11
- * frontmatter trigger phrases against the user's current prompt.
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 AND out of the
19
+ * name leg's prefix hits: a word present in COMMON_KEYWORD_DF or more of
20
+ * the cached skills' documents cannot tell skills apart, so
21
+ * description/path hits from it score nothing. A name hit is word-shaped
22
+ * by construction — a whole name token, or the start of one — so a word
23
+ * 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
25
+ * gated: the skill's own identity vocabulary is what a prompt naming it
26
+ * looks like, and a curated phrase is the author's signal.
27
+ * 1b. Ranking: equal scores compare by more distinct matched signals, then
28
+ * by rarer evidence (lower summed document frequency), then by name.
29
+ * Alphabetical order alone decided which of two equally-scored skills
30
+ * took a slot, which is how a broadly-matching skill outranked the one
31
+ * whose evidence was the prompt's actual subject.
18
32
  * 2. Session-scoped state: track which skills were injected on which turn.
19
33
  * Cooldown is per-skill on top of the global floor: an injected skill
20
34
  * cools down at least COOLDOWN_TURNS, and once it was actually loaded
@@ -99,6 +113,7 @@ import {
99
113
  recordSessionStart,
100
114
  } from "./session-records.js";
101
115
  import { triggerMatches } from "./skill-triggers.js";
116
+ import type { TriggerSource } from "./skill-triggers.js";
102
117
 
103
118
  const log = createLogger("skills-auto-inject");
104
119
 
@@ -145,6 +160,34 @@ export const MAX_EXCERPT_CHARS = 300;
145
160
  */
146
161
  export const MIN_NON_NAME_SCORE = 2;
147
162
 
163
+ /**
164
+ * A keyword present in this many skill documents or more is corpus-common: it
165
+ * appears in a large share of the catalog (5 of 22 skills = 23%), so it cannot
166
+ * distinguish one skill from another and contributes NOTHING to the weak legs
167
+ * (description, catalog path) — or to the name leg's token-prefix rule, the one
168
+ * name hit that can rest on a shared word.
169
+ *
170
+ * The number is measured, not guessed. Two measurements, one threshold:
171
+ *
172
+ * Corpus mass. Over 400 recorded prompts against the 22-skill catalog, the
173
+ * weak-leg points awarded to words by document frequency are df1 17.0%,
174
+ * df2 22.4%, df3 20.9%, df4 13.3%, df5 7.8%, df6 4.1%, df7 9.1%, df9 0.4%,
175
+ * df22 5.1%. Words at df ≥ 5 carry 26.4% of every weak-leg point the matcher
176
+ * awards; df ≥ 4 carries 39.7%, df ≥ 6 carries 18.6%. The catalog's generic
177
+ * vocabulary starts here (skill, read, prompt, text, build, change, agent,
178
+ * line); below it the words still describe work types (review, check, test,
179
+ * edit, documentation).
180
+ *
181
+ * Labelled set. 26 recorded prompts, recall@2 by threshold: df ≥ 4 → 12/23,
182
+ * df ≥ 5 → 13/23, df ≥ 6 → 13/23, df ≥ 7 → 14/23, no gate at all → 12/23.
183
+ * Recall alone cannot choose the number: every step that weakens the gate
184
+ * admits more skills (45, 54, 67, 71, 106 admissions) and admitting more can
185
+ * only raise a top-2 recall figure. 5 is where the gate removes a quarter of
186
+ * the corpus-common mass without also deleting the work-type words that are
187
+ * sometimes a skill's only reachable evidence.
188
+ */
189
+ export const COMMON_KEYWORD_DF = 5;
190
+
148
191
  /**
149
192
  * Common English words to exclude from keyword matching.
150
193
  * Kept small — only the most frequent noise words that would
@@ -249,6 +292,8 @@ export interface CachedSkill {
249
292
  disableModelInvocation?: boolean;
250
293
  /** Frontmatter trigger phrases (setCachedSkills resolves them from SKILL.md). */
251
294
  triggers?: string[];
295
+ /** Which source authored each phrase (the row's evidence label). */
296
+ triggerSources?: Record<string, TriggerSource>;
252
297
  }
253
298
 
254
299
  // Shared module-level variable rather than a per-module copy: the import
@@ -296,93 +341,267 @@ export function extractKeywords(text: string): string[] {
296
341
 
297
342
  // Relevance Scoring
298
343
 
344
+ /**
345
+ * The text a skill contributes to the corpus-frequency count: its description
346
+ * plus its own catalog path (`<dir>/skill.md`). Deliberately NOT the absolute
347
+ * path: a checkout root puts its own directory names ("private", "packages",
348
+ * a worktree name) in every one of the 22 documents — measured at df 22 for
349
+ * `private`, `package`, `pack` and `core`, and different on every machine the
350
+ * agent runs on. On description plus the skill's own directory those four
351
+ * measure df 0, 1, 1 and 2; `skill` and `kill` stay catalog-wide because the
352
+ * file itself is named SKILL.md, and the rarity gate is what removes them.
353
+ * Lowercased; the matcher tests substrings. Pure.
354
+ */
355
+ export function skillCorpusDocument(skill: CachedSkill): string {
356
+ const tail = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
357
+ return `${skill.description.toLowerCase()} ${tail}`;
358
+ }
359
+
360
+ /**
361
+ * Document frequency of each keyword across the cached skills: how many skill
362
+ * documents contain it as a substring (the test every weak leg performs).
363
+ * Computed once per turn from the cache, for the prompt's keywords only. Pure
364
+ * given the cache.
365
+ */
366
+ export function corpusKeywordFrequency(
367
+ keywords: string[],
368
+ skills: CachedSkill[],
369
+ ): Map<string, number> {
370
+ const docs = skills.map(skillCorpusDocument);
371
+ const freq = new Map<string, number>();
372
+ for (const kw of keywords) {
373
+ let n = 0;
374
+ for (const doc of docs) if (doc.includes(kw)) n++;
375
+ freq.set(kw, n);
376
+ }
377
+ return freq;
378
+ }
379
+
380
+ /** One skill's match against a prompt: points, distinct signals, evidence rarity. */
381
+ export interface SkillMatch {
382
+ /** Score the qualification bar and the ranking read (same scale as before). */
383
+ score: number;
384
+ /** Distinct matched signals: each trigger phrase, each distinct keyword. */
385
+ signals: number;
386
+ /** Summed document frequency of the matched keywords — lower is rarer. */
387
+ evidenceDf: number;
388
+ /** Strongest evidence behind the score; null when the skill did not qualify. */
389
+ reason: RelevanceReason | null;
390
+ }
391
+
392
+ /**
393
+ * What the strongest evidence for a row was. Short on purpose: a ranking row
394
+ * says "trigger", not a sentence — the reader is choosing a read, not reading
395
+ * an explanation.
396
+ *
397
+ * trigger — an authored phrase from frontmatter or the description tail
398
+ * heading — an authored phrase from a `## trigger:` body heading
399
+ * name — a keyword in the skill's own name
400
+ * description — a description or catalog-path keyword (the weak legs)
401
+ */
402
+ export type RelevanceReason = "trigger" | "heading" | "name" | "description";
403
+
404
+ /** Evidence strength for the row's single `reason` field. */
405
+ const REASON_STRENGTH: Record<RelevanceReason, number> = {
406
+ trigger: 4,
407
+ heading: 3,
408
+ name: 2,
409
+ description: 1,
410
+ };
411
+
412
+ /**
413
+ * How a keyword occurs in a skill name: as a whole token, as the start of a
414
+ * longer token, or not at all.
415
+ *
416
+ * The third answer is the fix: the name leg used to award points to any
417
+ * substring anywhere in the name, so a corpus-common word ("line", df 7 of 22)
418
+ * scored +2 for placement-disc**line** and release-pi**peline** and carried the
419
+ * name-hit exemption from the qualification bar with it. A word buried inside
420
+ * a coined token names the author's coinage, not the prompt's subject; a word
421
+ * that starts a token still reads as the author's own vocabulary ("engine" in
422
+ * software-engineer).
423
+ */
424
+ function nameOccurrence(tokens: string[], kw: string): "token" | "prefix" | null {
425
+ if (tokens.includes(kw)) return "token";
426
+ for (const token of tokens) if (token.length > kw.length && token.startsWith(kw)) return "prefix";
427
+ return null;
428
+ }
429
+
430
+ const NO_MATCH: SkillMatch = { score: 0, signals: 0, evidenceDf: 0, reason: null };
431
+
299
432
  /**
300
433
  * Score a skill against a set of keywords.
301
434
  *
302
435
  * Scoring rules:
303
- * +3 skill name contains a keyword (exact match)
304
- * +2 skill name contains a keyword as substring
305
- * +2 a frontmatter trigger phrase occurs in the prompt (word-bounded)
436
+ * +3 skill name carries a keyword as a whole token (exact match)
437
+ * +2 skill name starts a token with a keyword, below the frequency gate
438
+ * +2 a trigger phrase occurs in the prompt (word-bounded)
306
439
  * +1 skill description contains a keyword
307
- * +1 skill filePath contains a keyword (e.g. "research" in "research/SKILL.md")
440
+ * +1 the skill's own catalog path contains a keyword (e.g. "research" in
441
+ * "research/skill.md")
308
442
  *
309
443
  * A trigger hit counts as a name hit: the phrase is the skill author's own
310
444
  * relevance signal, so it qualifies the skill the same way a name match does.
311
445
  *
446
+ * `keywordDf` is the corpus document frequency of the prompt's keywords (see
447
+ * corpusKeywordFrequency). A keyword at COMMON_KEYWORD_DF or above scores
448
+ * nothing on the weak legs, and nothing on the name leg's token-prefix rule:
449
+ * a common word that only starts a token ("line" in "line-counting") is
450
+ * vocabulary the catalog shares, not the skill's own. Passing no map scores
451
+ * every keyword at full weight (the pre-rarity behavior, which the unit
452
+ * fixtures pin).
453
+ *
312
454
  * Qualification bar: a skill whose match never touches its NAME (description
313
455
  * and/or filePath hits only) must reach a total score of at least
314
456
  * MIN_NON_NAME_SCORE — one description keyword is too weak a signal and
315
457
  * lets generic skills fire on almost any prompt. Name and trigger matches
316
458
  * always qualify.
317
459
  *
318
- * `promptText` (lowercased by the caller or raw — matching is case-insensitive
319
- * on our side) enables trigger matching; omit it where the raw prompt is not
460
+ * `promptText` enables trigger matching; omit it where the raw prompt is not
320
461
  * available and only keyword scoring should run.
321
462
  *
322
- * Returns 0 if the skill does not qualify.
463
+ * Returns the zero match if the skill does not qualify.
323
464
  */
324
- export function scoreSkill(skill: CachedSkill, keywords: string[], promptText?: string): number {
465
+ export function matchSkill(
466
+ skill: CachedSkill,
467
+ keywords: string[],
468
+ promptText?: string,
469
+ keywordDf?: ReadonlyMap<string, number>,
470
+ ): SkillMatch {
325
471
  let score = 0;
472
+ let signals = 0;
473
+ let evidenceDf = 0;
326
474
  let nameHit = false;
475
+ let reason: RelevanceReason | null = null;
476
+ const noteReason = (candidate: RelevanceReason) => {
477
+ if (!reason || REASON_STRENGTH[candidate] > REASON_STRENGTH[reason]) reason = candidate;
478
+ };
327
479
  const name = skill.name.toLowerCase();
480
+ const nameTokens = name.split(/[^a-z0-9]+/).filter(Boolean);
328
481
  const desc = skill.description.toLowerCase();
329
- const path = skill.filePath.toLowerCase();
482
+ const path = skill.filePath.toLowerCase().split(/[\\/]/).filter(Boolean).slice(-2).join("/");
483
+ const dfOf = (kw: string) => keywordDf?.get(kw) ?? 0;
330
484
 
331
485
  for (const trig of skill.triggers ?? []) {
332
486
  if (triggerMatches(trig, promptText ?? "")) {
333
487
  score += 2;
488
+ signals++;
334
489
  nameHit = true;
490
+ // A curated phrase is the rarest evidence a skill can offer: df 0. Its
491
+ // provenance is what the row reports as its evidence label.
492
+ noteReason(skill.triggerSources?.[trig] === "heading" ? "heading" : "trigger");
335
493
  }
336
494
  }
337
495
 
338
496
  for (const kw of keywords) {
339
- // Exact token match in name
340
- if (name.split(/[^a-z0-9]+/).includes(kw)) {
497
+ const df = dfOf(kw);
498
+ const occurrence = nameOccurrence(nameTokens, kw);
499
+ // Exact token match in name: the skill's own identity vocabulary, never gated.
500
+ if (occurrence === "token") {
341
501
  score += 3;
502
+ signals++;
342
503
  nameHit = true;
504
+ evidenceDf += df;
505
+ noteReason("name");
343
506
  continue;
344
507
  }
345
- // Substring match in name (catches compound names like "code-search")
346
- if (name.includes(kw)) {
508
+ // Token-prefix match in name ("engine" in "software-engineer"): name
509
+ // evidence, but only while the word is distinctive enough to mean it.
510
+ if (occurrence === "prefix" && df < COMMON_KEYWORD_DF) {
347
511
  score += 2;
512
+ signals++;
348
513
  nameHit = true;
514
+ evidenceDf += df;
515
+ noteReason("name");
349
516
  continue;
350
517
  }
351
- // Description contains keyword
518
+ // Corpus-common keyword: the weak legs score nothing for it, so a prompt
519
+ // full of generic vocabulary cannot buy a slot.
520
+ if (df >= COMMON_KEYWORD_DF) continue;
521
+ let weakHit = false;
352
522
  if (desc.includes(kw)) {
353
523
  score += 1;
354
- continue;
524
+ weakHit = true;
355
525
  }
356
526
  // File path matches (e.g. "research" in "research/SKILL.md")
357
527
  if (path.includes(kw)) {
358
528
  score += 1;
529
+ weakHit = true;
530
+ }
531
+ // One signal per distinct keyword: a word present in both the description
532
+ // and the path is one piece of evidence, not two.
533
+ if (weakHit) {
534
+ signals++;
535
+ evidenceDf += df;
536
+ noteReason("description");
359
537
  }
360
538
  }
361
539
 
362
- if (!nameHit && score < MIN_NON_NAME_SCORE) return 0;
363
- return score;
540
+ if (!nameHit && score < MIN_NON_NAME_SCORE) return NO_MATCH;
541
+ return { score, signals, evidenceDf, reason };
542
+ }
543
+
544
+ /** The score alone (see matchSkill for the rules and the rarity gate). */
545
+ export function scoreSkill(
546
+ skill: CachedSkill,
547
+ keywords: string[],
548
+ promptText?: string,
549
+ keywordDf?: ReadonlyMap<string, number>,
550
+ ): number {
551
+ return matchSkill(skill, keywords, promptText, keywordDf).score;
552
+ }
553
+
554
+ /**
555
+ * A skill with its match evidence, as the selection step consumes it. The
556
+ * evidence fields are optional so a caller holding only a score still selects;
557
+ * they then default to zero and the name stays the tie-breaker.
558
+ */
559
+ export interface ScoredSkill {
560
+ skill: CachedSkill;
561
+ score: number;
562
+ signals?: number;
563
+ evidenceDf?: number;
564
+ }
565
+
566
+ /**
567
+ * The ranking comparator, shared by the whisper's selection and the catalog
568
+ * read: score, then breadth of match (distinct signals), then rarity of the
569
+ * evidence (summed document frequency), then name. Pure.
570
+ */
571
+ function compareScored(a: ScoredSkill, b: ScoredSkill): number {
572
+ return (
573
+ b.score - a.score ||
574
+ (b.signals ?? 0) - (a.signals ?? 0) ||
575
+ (a.evidenceDf ?? 0) - (b.evidenceDf ?? 0) ||
576
+ a.skill.name.localeCompare(b.skill.name)
577
+ );
364
578
  }
365
579
 
366
580
  /**
367
581
  * Decide which scored skills to suggest given the session injection state.
582
+ *
368
583
  * Pure — mirrors the handler's decision path so it can be unit-tested:
369
- * sort (score desc, name asc) → cooldown filter (global floor + per-skill
370
- * loaded extension) → slot budget over ACTIVE held slots (a loaded skill
371
- * released its slot) → top-N slice.
584
+ * sort (score desc, distinct signals desc, evidence df asc, name asc) →
585
+ * cooldown filter (global floor + per-skill loaded extension) → slot budget
586
+ * over ACTIVE held slots (a loaded skill released its slot) → top-N slice.
587
+ *
588
+ * The rank order is the fix for alphabetical slot allocation: two skills with
589
+ * equal points used to be ordered by name, so a broadly-matching skill took
590
+ * the slot from one whose evidence was the prompt's actual subject. Distinct
591
+ * signals separate breadth of match; evidence df separates a match on the
592
+ * prompt's distinctive words from one on its filler.
372
593
  *
373
594
  * Returns the chosen scored items (empty when nothing qualifies). The
374
595
  * caller is responsible for recording the picks in session state.
375
596
  */
376
597
  export function selectSuggestions(
377
- scored: Array<{ skill: CachedSkill; score: number }>,
598
+ scored: ScoredSkill[],
378
599
  injected: InjectedSkill[],
379
600
  currentTurn: number,
380
- ): Array<{ skill: CachedSkill; score: number }> {
601
+ ): ScoredSkill[] {
381
602
  if (!scored.length) return [];
382
603
 
383
- const sorted = [...scored].sort(
384
- (a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name),
385
- );
604
+ const sorted = [...scored].sort(compareScored);
386
605
 
387
606
  const available = sorted.filter((s) => !onCooldown(s.skill.name, injected, currentTurn));
388
607
  if (!available.length) return [];
@@ -396,6 +615,106 @@ export function selectSuggestions(
396
615
  return available.slice(0, slotBudget);
397
616
  }
398
617
 
618
+ // Deterministic ranking for the catalog read
619
+
620
+ /**
621
+ * Declared margin: a gap smaller than this between the first and second
622
+ * qualified skill means the top is a coin flip, and the read says so
623
+ * (`thin-margin`) instead of presenting the order as a decision. The number is
624
+ * deliberate, not measured: one description keyword (+1) is exactly the
625
+ * distance the scorer says is too weak to qualify a skill on its own
626
+ * (MIN_NON_NAME_SCORE), so a lead that one extra weak hit could erase is not a
627
+ * lead.
628
+ */
629
+ export const RANK_MARGIN_THRESHOLD = 2;
630
+
631
+ /**
632
+ * A task text shorter than this cannot carry a ranking signal: a greeting or a
633
+ * two-word nudge names no domain, so the deterministic tier reports itself
634
+ * short rather than confidently wrong.
635
+ */
636
+ export const RANK_SHORT_TASK_CHARS = 24;
637
+
638
+ /** Why the deterministic tier answered the way it did. */
639
+ export type RankingBasis =
640
+ | "no-task"
641
+ | "short-task"
642
+ | "no-score"
643
+ | "unambiguous"
644
+ | "tie"
645
+ | "thin-margin";
646
+
647
+ /** One skill as the ranking read consumes it: match evidence plus its label. */
648
+ export interface RankedSkill {
649
+ skill: CachedSkill;
650
+ score: number;
651
+ signals: number;
652
+ evidenceDf: number;
653
+ reason: RelevanceReason | null;
654
+ }
655
+
656
+ /** The deterministic tier's whole answer: an ordered list and a verdict on it. */
657
+ export interface DeterministicRanking {
658
+ /** Qualified skills only, best first (the order the whisper ranks by). */
659
+ ranked: RankedSkill[];
660
+ /** True when the list cannot separate its own top — the escalation trigger. */
661
+ ambiguous: boolean;
662
+ basis: RankingBasis;
663
+ }
664
+
665
+ /**
666
+ * Rank the catalog against a task text without a model. Pure given the cache.
667
+ *
668
+ * Ordering is the whisper's comparator (score, then distinct signals, then
669
+ * summed evidence df, then name) so the two surfaces can never disagree about
670
+ * which skill is better. `ambiguous` is the one thing the whisper does not
671
+ * need: it decides every turn with slots and cooldowns, while a catalog read
672
+ * shows the whole list and therefore must say when its own top is not decided
673
+ * (a tie or a thin margin) or when the task text could not inform it at all.
674
+ *
675
+ * The verdict:
676
+ * no-task — no task text at all; nothing to rank.
677
+ * short-task — the text carries no significant keyword, or is shorter than
678
+ * RANK_SHORT_TASK_CHARS: nothing here can rank a catalog.
679
+ * no-score — every skill scored zero: unambiguous (nothing applies).
680
+ * tie — the top two score the same: ambiguous.
681
+ * thin-margin — the top two sit closer than RANK_MARGIN_THRESHOLD: ambiguous.
682
+ * unambiguous — one skill leads the field by at least the margin.
683
+ */
684
+ export function rankSkillsDeterministic(
685
+ skills: CachedSkill[],
686
+ taskText: string,
687
+ ): DeterministicRanking {
688
+ const text = (taskText ?? "").trim();
689
+ if (!text) return { ranked: [], ambiguous: false, basis: "no-task" };
690
+ const keywords = extractKeywords(text);
691
+ const ranked: RankedSkill[] = [];
692
+ if (keywords.length) {
693
+ const keywordDf = corpusKeywordFrequency(keywords, skills);
694
+ for (const skill of skills) {
695
+ const match = matchSkill(skill, keywords, text, keywordDf);
696
+ if (match.score <= 0) continue;
697
+ ranked.push({
698
+ skill,
699
+ score: match.score,
700
+ signals: match.signals,
701
+ evidenceDf: match.evidenceDf,
702
+ reason: match.reason,
703
+ });
704
+ }
705
+ }
706
+ ranked.sort(compareScored);
707
+ if (text.length < RANK_SHORT_TASK_CHARS || !keywords.length) {
708
+ return { ranked, ambiguous: true, basis: "short-task" };
709
+ }
710
+ if (!ranked.length) return { ranked, ambiguous: false, basis: "no-score" };
711
+ if (ranked.length === 1) return { ranked, ambiguous: false, basis: "unambiguous" };
712
+ const margin = ranked[0].score - ranked[1].score;
713
+ if (margin === 0) return { ranked, ambiguous: true, basis: "tie" };
714
+ if (margin < RANK_MARGIN_THRESHOLD) return { ranked, ambiguous: true, basis: "thin-margin" };
715
+ return { ranked, ambiguous: false, basis: "unambiguous" };
716
+ }
717
+
399
718
  /**
400
719
  * Cooldown gate: the global floor applies to every injection; a skill that
401
720
  * was loaded after its injection additionally cools down for
@@ -928,9 +1247,13 @@ export function registerAutoInject(pi: ExtensionAPI): void {
928
1247
  return; // No significant keywords to match
929
1248
  }
930
1249
 
1250
+ // Corpus-common words cannot tell skills apart. Their document frequency
1251
+ // is measured once per turn from the same cache the scorer reads.
1252
+ const keywordDf = corpusKeywordFrequency(keywords, skills);
1253
+
931
1254
  // Score each skill. The raw prompt rides along for trigger matching.
932
1255
  const scored = skills
933
- .map((s) => ({ skill: s, score: scoreSkill(s, keywords, prompt) }))
1256
+ .map((s) => ({ skill: s, ...matchSkill(s, keywords, prompt, keywordDf) }))
934
1257
  .filter((s) => s.score > 0);
935
1258
 
936
1259
  if (!scored.length) {