pi-skill-shiori 0.6.9 → 0.6.11

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## [0.6.11] - 2026-09-21
+
+### Fixed
+
+- Rank curated trigger matches ahead of heuristic description matches when enforcing candidate limits. Derived single-token query variants can score a perfect `1.00` from substring matches while trigger matches are fixed at `0.95`, so a genuine trigger match could be dropped by the candidate cap. The same ordering now applies at both cap sites, because the per-variant cap runs before expanded retrieval merges variants and a match dropped there can never be restored.
+- Apply the original query's `exclude` triggers across merged variants in expanded retrieval. A derived single-token variant could drop the context that made an exclude match (`do not use auth` becomes `auth`), which reintroduced an excluded skill.
+
+## [0.6.10] - 2026-09-21
+
+### Fixed
+
+- Prune stale `.pi/cache/skill-shiori/index-*.sqlite` databases. Every index rebuild wrote a new `index-<pid>-<ts>.sqlite` file and never removed the older ones, so a long-lived vault accumulated hundreds of files (336 files / 33 MB in the local vault). Rebuilds now delete databases older than a one hour grace window; the live database, recent files, and locked files are left in place.
+
 ## [0.6.9] - 2026-08-22
 
 ### Changed

package/Docs/usage.md

@@ -100,7 +100,7 @@ Generate a starter policy from discovered skills:
 /shiori:bootstrap
 ```
 
-This writes a generated review file next to `.pi/skill-shiori.yml`. Review it before using it as your real policy.
+This writes `.pi/skill-shiori.generated.yml` next to your project policy. Review the draft, copy the sections you want into `.pi/skill-shiori.yml`, then run `/shiori:reload`.
 
 ## Suppression statuses
 
@@ -167,6 +167,24 @@ command: offers=1, loaded=2, zeroHits=1
 top skills: auth-helper(1/2), deploy-kit(1/1)
 ```
 
+## Agent tools
+
+Shiori registers two tools the agent can call after candidates appear:
+
+```ts
+// Discover matching skills for a natural-language task (may pre-load multiple bodies)
+shiori_recommend({ task: "browser scraping screenshot" })
+
+// Load one selected skill body after a candidate matches
+shiori_load_skill({ skill: "reddit-research" })
+```
+
+`shiori_recommend` returns compact summaries and may pre-load matching `SKILL.md` bodies. The Pi UI shows a collapsed result like `✓ Shiori playwright-cli [trigger], gstack-browse [description]`.
+
+`shiori_load_skill` loads one skill by name. The Pi UI shows a compact result like `✓ Loaded reddit-research (6.3KB)`.
+
+See [Recommendation surface](recommendation-surface.md) for badge vocabulary and multi-skill examples.
+
 ## Related docs
 
 - [Recommendation surface](recommendation-surface.md) — reason badges, Always Visible policy, and metrics interplay

package/README.md

@@ -19,7 +19,7 @@ For maintenance priorities and the phased plan, see [`ROADMAP.md`](ROADMAP.md).
 
 Pi Skill Shiori is a [Pi](https://pi.dev/) package for vaults or projects with many Agent Skills where the default catalog becomes noisy and expensive. It hides the normal skill catalog when safe, recommends triggerable skills with compact summaries, and loads full `SKILL.md` bodies on demand.
 
-`0.6.9` is the current working release. Prompt-boundary suppression is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
+`0.6.11` is the current working release. Prompt-boundary suppression is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
 
 ## Features
 
@@ -37,7 +37,7 @@ Pi Skill Shiori is a [Pi](https://pi.dev/) package for vaults or projects with m
 ### Global install from npm
 
 ```bash
-pi install npm:pi-skill-shiori@0.6.9
+pi install npm:pi-skill-shiori@0.6.11
 ```
 
 Without a version pin:
@@ -49,7 +49,7 @@ pi install npm:pi-skill-shiori
 ### Project-local install from npm
 
 ```bash
-pi install -l npm:pi-skill-shiori@0.6.9
+pi install -l npm:pi-skill-shiori@0.6.11
 ```
 
 Without a version pin:
@@ -61,7 +61,7 @@ pi install -l npm:pi-skill-shiori
 ### Install from GitHub
 
 ```bash
-pi install git:github.com/eiei114/pi-skill-shiori@v0.6.9
+pi install git:github.com/eiei114/pi-skill-shiori@v0.6.11
 pi install -l git:github.com/eiei114/pi-skill-shiori
 ```
 
@@ -83,7 +83,7 @@ pi install -l /absolute/path/to/pi-skill-shiori
 1. Install the package (see [Install](#install)).
 2. Create `.pi/skill-shiori.yml` in your Pi project (see [Docs/usage.md](Docs/usage.md#configure)).
 3. Start Pi and run `/shiori:doctor` to confirm policy path, indexed roots, and suppression status.
-4. Use `/shiori:bootstrap` to draft a policy from discovered skills, then `/shiori:reload` after edits.
+4. Use `/shiori:bootstrap` to write `.pi/skill-shiori.generated.yml`, review it, copy needed sections into `.pi/skill-shiori.yml`, then run `/shiori:reload`.
 5. Ask the agent for help; Shiori injects compact candidates or use `/shiori:recommend` for an interactive flow.
 
 Commands take no inline arguments. Details are collected after launch via Pi UI prompts.
@@ -98,13 +98,19 @@ Commands take no inline arguments. Details are collected after launch via Pi UI
 | `/shiori:recommend` | Interactive recommendation flow with optional pre-load. |
 | `/shiori:stats` | Show operational counters and recommendation quality summary. |
 
-Shiori registers one tool:
+Shiori registers two tools:
 
 ```ts
+// Discover matching skills for a natural-language task (may pre-load multiple bodies)
+shiori_recommend({ task: "browser scraping screenshot" })
+
+// Load one selected skill body after a candidate matches
 shiori_load_skill({ skill: "reddit-research" })
 ```
 
-The model receives the full selected `SKILL.md` content. The Pi UI shows a compact result like `✓ Loaded reddit-research (6.3KB)`.
+`shiori_recommend` returns compact summaries and may pre-load matching `SKILL.md` bodies. The Pi UI shows a collapsed result like `✓ Shiori playwright-cli [trigger], gstack-browse [description]`.
+
+`shiori_load_skill` loads one skill by name. The Pi UI shows a compact result like `✓ Loaded reddit-research (6.3KB)`.
 
 Recommended skills show compact reason badges (`[trigger]`, `[description]`, `[low match]`). See [`Docs/recommendation-surface.md`](Docs/recommendation-surface.md) for badge vocabulary and metrics interplay.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.6.9",
+  "version": "0.6.11",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",
@@ -54,9 +54,9 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-ai": "^0.85.0",
     "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.85.1",
     "@types/node": "^26.0.0",
     "tsx": "^4.22.4",
     "typebox": "latest",

package/src/indexer.ts

@@ -1,8 +1,62 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, readdir, stat, unlink } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import type { RetrievalBackend, ShioriPolicy, SkillRecord } from "./types.js";
 
+const INDEX_FILE_PATTERN = /^index-\d+-\d+\.sqlite(?:-(?:wal|shm|journal))?$/;
+
+/**
+ * Index databases are written with a per-process name, so every rebuild adds a
+ * file. Prune older ones after a grace window: long enough that a concurrent
+ * process keeps its database, short enough that a busy vault does not grow
+ * without bound.
+ */
+export const DEFAULT_INDEX_GRACE_MS = 60 * 60 * 1000;
+
+export interface PruneIndexOptions {
+  /** File name to keep, usually the database this process just opened. */
+  keep?: string;
+  /** Files newer than this window are left alone. */
+  graceMs?: number;
+  /** Clock override for tests. */
+  now?: number;
+}
+
+/**
+ * Best-effort cleanup of stale index databases. Locked files (a live process on
+ * Windows) and unreadable entries are skipped instead of failing the build.
+ */
+export async function pruneStaleIndexFiles(cacheDir: string, options: PruneIndexOptions = {}): Promise<string[]> {
+  const graceMs = options.graceMs ?? DEFAULT_INDEX_GRACE_MS;
+  const now = options.now ?? Date.now();
+  const removed: string[] = [];
+
+  let entries: string[];
+  try {
+    entries = await readdir(cacheDir);
+  } catch {
+    return removed;
+  }
+
+  for (const entry of entries) {
+    if (!INDEX_FILE_PATTERN.test(entry)) continue;
+    if (options.keep && entry === options.keep) continue;
+
+    const target = join(cacheDir, entry);
+    try {
+      const info = await stat(target);
+      if (!info.isFile()) continue;
+      if (now - info.mtimeMs < graceMs) continue;
+      await unlink(target);
+      removed.push(entry);
+    } catch {
+      // Locked (a live process owns it) or already gone: leave it for next time.
+    }
+  }
+
+  return removed;
+}
+
 export interface SkillIndex {
   skills: SkillRecord[];
   policy: ShioriPolicy;
@@ -24,6 +78,7 @@ export async function buildSkillIndex(cwd: string, skills: SkillRecord[], policy
     await mkdir(cacheDir, { recursive: true });
 
     const db = new sqlite.DatabaseSync(dbPath);
+    await pruneStaleIndexFiles(cacheDir, { keep: basename(dbPath) });
     db.exec(
       "CREATE VIRTUAL TABLE skill_fts USING fts5(name, description, triggers, path, tokenize='unicode61 remove_diacritics 2')",
     );

package/src/retrieval-expanded.ts

@@ -1,5 +1,5 @@
 import { buildRetrievalQueries } from "./query.js";
-import { retrieveCandidates } from "./retrieval.js";
+import { compareCandidates, excludedSkillNames, retrieveCandidates } from "./retrieval.js";
 import type { ShioriPolicy, SkillCandidate, SkillRecord } from "./types.js";
 
 interface RetrievalIndex {
@@ -14,17 +14,21 @@ export function retrieveCandidatesExpanded(
 ): SkillCandidate[] {
   const byName = new Map<string, SkillCandidate>();
   const max = policy.candidateInjection.maxCandidates;
+  // Apply the original query's excludes across the merged set. A derived
+  // single-token variant can drop the context that made an exclude match
+  // ("do not use auth" becomes "auth"), which would otherwise let an excluded
+  // skill back in once variants are merged.
+  const excluded = excludedSkillNames(query, skills, policy);
 
   for (const variant of buildRetrievalQueries(query)) {
     for (const candidate of retrieveCandidates(variant, skills, policy, index)) {
+      if (excluded.has(candidate.skill.name)) continue;
       const previous = byName.get(candidate.skill.name);
       byName.set(candidate.skill.name, preferExpandedCandidate(previous, candidate));
     }
   }
 
-  return [...byName.values()]
-    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
-    .slice(0, max);
+  return [...byName.values()].sort(compareCandidates).slice(0, max);
 }
 
 /** Keep trigger badges when expanded query variants also score the description higher. */

package/src/retrieval.ts

@@ -34,10 +34,58 @@ export function retrieveCandidates(
   }
 
   return [...candidatesByName.values()]
-    .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
+    .sort(compareCandidates)
     .slice(0, policy.candidateInjection.maxCandidates);
 }
 
+/**
+ * Order candidates so curated trigger matches rank ahead of heuristic
+ * description matches.
+ *
+ * Trigger matches carry a fixed score (0.95, see `evaluateSkill`), while
+ * description matches can reach a higher score from short query tokens that
+ * happen to appear as substrings — "is" in "history", "fix" in "prefix".
+ * Sorting by score alone therefore lets that noise push a genuine trigger match
+ * past a candidate cap, where it is dropped without a trace. A trigger is an
+ * explicit statement that the skill is relevant, so it outranks a heuristic
+ * substring match even when the heuristic scored higher.
+ *
+ * Every cap site must use this comparator: the per-variant cap inside
+ * `retrieveCandidates` runs before expanded retrieval merges variants, so a
+ * trigger match dropped there can never be restored downstream.
+ */
+export function compareCandidates(a: SkillCandidate, b: SkillCandidate): number {
+  const triggerDelta = Number(b.reason === "trigger") - Number(a.reason === "trigger");
+  if (triggerDelta !== 0) return triggerDelta;
+  return b.score - a.score || a.skill.name.localeCompare(b.skill.name);
+}
+
+/**
+ * Skill names the original query excludes via policy exclude triggers.
+ *
+ * `retrieveCandidates` evaluates excludes against whichever query string it
+ * receives. Expanded retrieval passes derived variants, and a derived variant can
+ * drop the surrounding context that made an exclude match ("do not use auth"
+ * becomes "auth"), so the exclusion no longer applies and the skill leaks back
+ * in. Callers that merge variants should apply the original query's excludes
+ * across the merged set.
+ */
+export function excludedSkillNames(
+  query: string,
+  skills: SkillRecord[],
+  policy: ShioriPolicy,
+): Set<string> {
+  const normalizedQuery = normalize(query);
+  const excluded = new Set<string>();
+  for (const skill of skills) {
+    const excludes = policy.skills[skill.name]?.triggers?.exclude ?? [];
+    if (excludes.some((trigger) => includesNormalized(normalizedQuery, trigger))) {
+      excluded.add(skill.name);
+    }
+  }
+  return excluded;
+}
+
 function evaluateSkill(
   skill: SkillRecord,
   normalizedQuery: string,