pi-skill-shiori 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.5.0] - 2026-06-28
+
+### Added
+
+- Vault-wide skill inventory: Shiori indexes skills from project `.pi/skills`, `.agents/skills`, the user-global `~/.pi/agent/skills` root, and optional policy `inventory.roots`.
+- Automatic inventory refresh when skill files change under any indexed root (enabled by default; disable with `inventory.autoRefreshOnChange: false`).
+- `/shiori:doctor` now lists indexed roots with per-root skill counts and auto-refresh status.
+- `/shiori:stats` counters for manual and automatic inventory refreshes.
+- Tests for multi-root discovery, refresh after local changes, and policy-aware retrieval.
+
+### Changed
+
+- `/shiori:reload` rebuilds the vault-wide inventory and SQLite FTS index instead of relying on the session-start snapshot only.
+
 ## [0.4.0] - 2026-06-28
 
 ### Added

package/README.md

@@ -12,12 +12,13 @@ For maintenance priorities and the phased plan, see [`ROADMAP.md`](ROADMAP.md).
 - **Policy-based retrieval**: treats skills as explicit by default and only candidates skills marked as triggerable.
 - **Compact candidate injection**: injects short skill suggestions instead of full `SKILL.md` files.
 - **On-demand loading**: exposes `shiori_load_skill` so the model can load one selected skill body when needed.
+- **Vault-wide skill inventory**: indexes skills from project and user-global roots, with optional extra roots in policy.
 - **SQLite FTS retrieval**: indexes skill names, descriptions, and policy triggers with `node:sqlite` + FTS5, with token-match fallback.
 - **Compact UI output**: keeps skill-load logs short while still passing full skill text to the model.
 
 ## Status
 
-`0.4.0` is an early working release. It is useful for local Pi workflows, but the prompt-boundary suppression logic is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
+`0.5.0` is an early working release. It is useful for local Pi workflows, but the prompt-boundary suppression logic is intentionally conservative: if Shiori cannot safely recognize a catalog boundary, it leaves the prompt untouched and warns instead of deleting too much.
 
 ## Requirements
 
@@ -39,7 +40,7 @@ Pi core packages are peer dependencies and should be supplied by the Pi runtime:
 After the package is published to npm:
 
 ```bash
-pi install npm:pi-skill-shiori@0.4.0
+pi install npm:pi-skill-shiori@0.5.0
 ```
 
 Without a version pin:
@@ -53,7 +54,7 @@ pi install npm:pi-skill-shiori
 Use `-l` to write the package to the current project’s `.pi/settings.json`:
 
 ```bash
-pi install -l npm:pi-skill-shiori@0.4.0
+pi install -l npm:pi-skill-shiori@0.5.0
 ```
 
 Without a version pin:
@@ -67,7 +68,7 @@ Equivalent pinned manual `.pi/settings.json` entry:
 ```json
 {
   "packages": [
-    "npm:pi-skill-shiori@0.4.0"
+    "npm:pi-skill-shiori@0.5.0"
   ]
 }
 ```
@@ -85,7 +86,7 @@ Equivalent unpinned manual `.pi/settings.json` entry:
 ### Global install from GitHub
 
 ```bash
-pi install git:github.com/eiei114/pi-skill-shiori@v0.4.0
+pi install git:github.com/eiei114/pi-skill-shiori@v0.5.0
 ```
 
 Without a tag pin:
@@ -97,7 +98,7 @@ pi install git:github.com/eiei114/pi-skill-shiori
 ### Project-local install from GitHub
 
 ```bash
-pi install -l git:github.com/eiei114/pi-skill-shiori@v0.4.0
+pi install -l git:github.com/eiei114/pi-skill-shiori@v0.5.0
 ```
 
 Without a tag pin:
@@ -131,7 +132,38 @@ Or add a relative local path to `.pi/settings.json`:
 }
 ```
 
-> Note: policy/index changes can be refreshed with `/shiori:reload`, but extension code changes require restarting the Pi process because Node keeps imported extension modules cached.
+> Note: policy/index changes can be refreshed with `/shiori:reload`, and Shiori auto-refreshes the vault-wide inventory when skill files change under indexed roots. Extension code changes still require restarting the Pi process because Node keeps imported extension modules cached.
+
+## Vault-wide skill inventory
+
+Shiori builds a searchable inventory from these roots (in discovery order; first match wins on duplicate skill names):
+
+| Root | Scope |
+|---|---|
+| `<cwd>/.pi/skills` | Project-local Pi skills |
+| `<cwd>/.agents/skills` | Project-local Agent skills |
+| `~/.pi/agent/skills` | User-global Pi agent skills |
+| `inventory.roots` entries | Optional extra roots (relative to `<cwd>` or absolute) |
+
+Refresh behavior:
+
+- **Session start** builds the initial inventory and SQLite FTS index.
+- **Auto-refresh** (default) rescans roots before retrieval when any `SKILL.md` path changes. This is a directory walk only; it rebuilds the FTS index when the fingerprint changes.
+- **Manual refresh** via `/shiori:reload` always rebuilds the inventory and FTS index immediately.
+- Disable auto-refresh when you prefer a fixed snapshot:
+
+```yaml
+inventory:
+  autoRefreshOnChange: false
+  roots:
+    - custom-skills
+```
+
+Cost/latency trade-offs:
+
+- Auto-refresh adds a shallow filesystem walk on each agent turn while enabled. It avoids stale search results after local skill edits without restarting Pi.
+- A full refresh rebuilds the SQLite FTS database and scales with total indexed skills and description length. Large vaults with many roots may prefer `autoRefreshOnChange: false` plus explicit `/shiori:reload` after bulk imports.
+- Search stays description-first and policy-aware: only `triggerable` skills become candidates, with FTS ranking over names, descriptions, and policy triggers.
 
 ## Configure
 
@@ -185,7 +217,7 @@ This writes a generated review file next to `.pi/skill-shiori.yml`. Review it be
 
 | Command | Purpose |
 |---|---|
-| `/shiori:doctor` | Show policy path, inventory count, retrieval backend, suppression status, and code marker. |
+| `/shiori:doctor` | Show policy path, indexed roots, inventory count, retrieval backend, suppression status, and code marker. |
 | `/shiori:bootstrap` | Generate a review draft policy from discovered skill descriptions. |
 | `/shiori:reload` | Ask what to reload, then rebuild Shiori’s skill inventory and optionally ask Pi to reload runtime resources. Code changes may still need full restart. |
 | `/shiori:recommend` | Ask what you need help with, then either pre-load matches and queue the task for the agent or review recommendations only. Planning phrases (e.g. `計画を立てたい`) return the dev-plan intake template without dumping SKILL bodies. |
@@ -281,7 +313,7 @@ npm login
 After publishing, verify the Pi install path:
 
 ```bash
-pi install npm:pi-skill-shiori@0.4.0
+pi install npm:pi-skill-shiori@0.5.0
 pi install npm:pi-skill-shiori
 pi list
 /shiori:doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",

package/src/discovery.ts

@@ -1,18 +1,42 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
-import type { SkillRecord } from "./types.js";
+import type { ShioriPolicy, SkillRecord } from "./types.js";
 
 const SKILL_FILE = "SKILL.md";
 
-export async function discoverSkills(cwd: string): Promise<SkillRecord[]> {
+/** Project-local skill roots scanned on every vault-wide inventory build. */
+export const VAULT_LOCAL_SKILL_ROOT_SEGMENTS = [".pi/skills", ".agents/skills"] as const;
+
+/** User-global Pi agent skills root (lowest discovery precedence). */
+export const GLOBAL_AGENT_SKILL_ROOT_SEGMENTS = ".pi/agent/skills";
+
+export function resolveVaultSkillRoots(cwd: string, policy?: Pick<ShioriPolicy, "inventory">): string[] {
   const roots = [
     join(cwd, ".pi", "skills"),
     join(cwd, ".agents", "skills"),
     join(homedir(), ".pi", "agent", "skills"),
   ];
 
+  for (const entry of policy?.inventory?.roots ?? []) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+    const resolved = isAbsolute(trimmed) ? resolve(trimmed) : resolve(cwd, trimmed);
+    if (!roots.includes(resolved)) {
+      roots.push(resolved);
+    }
+  }
+
+  return roots;
+}
+
+export async function discoverSkills(cwd: string, policy?: ShioriPolicy): Promise<SkillRecord[]> {
+  const roots = resolveVaultSkillRoots(cwd, policy);
+  return discoverSkillsFromRoots(roots);
+}
+
+export async function discoverSkillsFromRoots(roots: string[]): Promise<SkillRecord[]> {
   const records: SkillRecord[] = [];
   for (const root of roots) {
     const files = await findSkillFiles(root);
@@ -23,6 +47,15 @@ export async function discoverSkills(cwd: string): Promise<SkillRecord[]> {
   return dedupeByDiscoveryOrder(records);
 }
 
+export async function computeInventoryFingerprint(roots: string[]): Promise<string> {
+  const parts: string[] = [];
+  for (const root of roots) {
+    const files = await findSkillFiles(root);
+    parts.push(`${root}:${files.sort().join(",")}`);
+  }
+  return parts.join("|");
+}
+
 export function findDuplicates(records: SkillRecord[]): Map<string, SkillRecord[]> {
   const groups = new Map<string, SkillRecord[]>();
   for (const record of records) {

package/src/index.ts

@@ -3,8 +3,8 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { readFile, writeFile } from "node:fs/promises";
 import { evaluateAlwaysVisible, formatAlwaysVisibleDiagnostics } from "./always-visible.js";
-import { discoverSkills, findDuplicates } from "./discovery.js";
-import { buildSkillIndex, type SkillIndex } from "./indexer.js";
+import { findDuplicates, formatInventoryRoots, isAutoRefreshEnabled, isInventoryStale, refreshSkillInventory } from "./inventory.js";
+import type { SkillIndex } from "./indexer.js";
 import { loadRecommendedSkills } from "./load-skills.js";
 import { formatPlanningKickoffMessage, isPlanningIntent } from "./planning-kickoff.js";
 import { createStats } from "./metrics.js";
@@ -36,23 +36,42 @@ const CANCEL_CHOICE = "Cancel";
 
 export default function piSkillShiori(pi: ExtensionAPI) {
   let index: SkillIndex | undefined;
+  let inventoryFingerprint: string | undefined;
+  let inventoryRoots: string[] = [];
   let warnedAlwaysVisibleMissing = new Set<string>();
   const stats = createStats();
 
   async function reload(cwd: string): Promise<SkillIndex> {
-    const [policy, skills] = await Promise.all([loadPolicy(cwd), discoverSkills(cwd)]);
-    index?.close?.();
-    index = await buildSkillIndex(cwd, skills, policy);
-    stats.inventoryCount = skills.length;
-    stats.duplicateCount = findDuplicates(skills).size;
+    const policy = await loadPolicy(cwd);
+    const inventory = await refreshSkillInventory(cwd, policy, index);
+    index = inventory.index;
+    inventoryFingerprint = inventory.fingerprint;
+    inventoryRoots = inventory.roots;
+    stats.inventoryCount = index.skills.length;
+    stats.duplicateCount = findDuplicates(index.skills).size;
     stats.lastReloadAt = index.builtAt;
     stats.retrievalBackend = index.retrievalBackend;
     stats.suppressionStatus = policy.zeroCatalog.enabled ? "not-needed" : "disabled";
+    stats.inventoryRefreshCount += 1;
     return index;
   }
 
   async function ensureIndex(cwd: string): Promise<SkillIndex> {
-    return index ?? reload(cwd);
+    if (!index || !inventoryFingerprint) {
+      return reload(cwd);
+    }
+
+    const policy = await loadPolicy(cwd);
+    if (!isAutoRefreshEnabled(policy)) {
+      return index;
+    }
+
+    if (await isInventoryStale(cwd, policy, inventoryFingerprint)) {
+      stats.inventoryAutoRefreshCount += 1;
+      return reload(cwd);
+    }
+
+    return index;
   }
 
   function withRecommendLimits(current: SkillIndex) {
@@ -72,6 +91,8 @@ export default function piSkillShiori(pi: ExtensionAPI) {
   pi.on("session_shutdown", () => {
     index?.close?.();
     index = undefined;
+    inventoryFingerprint = undefined;
+    inventoryRoots = [];
   });
 
   pi.on("input", async (event) => {
@@ -210,6 +231,9 @@ export default function piSkillShiori(pi: ExtensionAPI) {
         `duplicates: ${duplicates.size}`,
         `alwaysVisible: ${current.policy.alwaysVisible.join(", ") || "none"}`,
         ...formatAlwaysVisibleDiagnostics(alwaysVisible),
+        "inventoryRoots:",
+        ...formatInventoryRoots(inventoryRoots, current.skills).map((line) => `  - ${line}`),
+        `autoRefreshOnChange: ${isAutoRefreshEnabled(current.policy) ? "enabled" : "disabled"}`,
         `retrievalBackend: ${current.retrievalBackend}`,
         `suppression: ${stats.suppressionStatus}`,
         `code: ${SHIORI_CODE_MARKER}`,

package/src/inventory.ts

@@ -0,0 +1,58 @@
+import {
+  computeInventoryFingerprint,
+  discoverSkillsFromRoots,
+  findDuplicates,
+  resolveVaultSkillRoots,
+} from "./discovery.js";
+import { buildSkillIndex, type SkillIndex } from "./indexer.js";
+import type { ShioriPolicy } from "./types.js";
+
+export interface SkillInventory {
+  index: SkillIndex;
+  roots: string[];
+  fingerprint: string;
+}
+
+export function isAutoRefreshEnabled(policy: ShioriPolicy): boolean {
+  return policy.inventory?.autoRefreshOnChange !== false;
+}
+
+export async function refreshSkillInventory(
+  cwd: string,
+  policy: ShioriPolicy,
+  previous?: SkillIndex,
+): Promise<SkillInventory> {
+  previous?.close?.();
+  const roots = resolveVaultSkillRoots(cwd, policy);
+  const [skills, fingerprint] = await Promise.all([
+    discoverSkillsFromRoots(roots),
+    computeInventoryFingerprint(roots),
+  ]);
+  const index = await buildSkillIndex(cwd, skills, policy);
+  return { index, roots, fingerprint };
+}
+
+export async function isInventoryStale(
+  cwd: string,
+  policy: ShioriPolicy,
+  fingerprint: string,
+): Promise<boolean> {
+  const roots = resolveVaultSkillRoots(cwd, policy);
+  const current = await computeInventoryFingerprint(roots);
+  return current !== fingerprint;
+}
+
+export function countSkillsByRoot(skills: SkillIndex["skills"], roots: string[]): Map<string, number> {
+  const counts = new Map(roots.map((root) => [root, 0]));
+  for (const skill of skills) {
+    counts.set(skill.source, (counts.get(skill.source) ?? 0) + 1);
+  }
+  return counts;
+}
+
+export function formatInventoryRoots(roots: string[], skills: SkillIndex["skills"]): string[] {
+  const counts = countSkillsByRoot(skills, roots);
+  return roots.map((root) => `${root} (${counts.get(root) ?? 0} skills)`);
+}
+
+export { findDuplicates };

package/src/metrics.ts

@@ -10,5 +10,7 @@ export function createStats(): ShioriStats {
     explicitInvocationCount: 0,
     retrievalBackend: "token-match",
     suppressionStatus: "disabled",
+    inventoryRefreshCount: 0,
+    inventoryAutoRefreshCount: 0,
   };
 }

package/src/policy.ts

@@ -30,6 +30,10 @@ export async function loadPolicy(cwd: string): Promise<ShioriPolicy> {
 }
 
 function normalizePolicy(policy: Partial<ShioriPolicy> | undefined): ShioriPolicy {
+  const extraRoots = (policy?.inventory?.roots ?? [])
+    .map((root) => (typeof root === "string" ? root.trim() : ""))
+    .filter(Boolean);
+
   return {
     zeroCatalog: {
       enabled: policy?.zeroCatalog?.enabled ?? DEFAULT_POLICY.zeroCatalog.enabled,
@@ -42,6 +46,13 @@ function normalizePolicy(policy: Partial<ShioriPolicy> | undefined): ShioriPolic
       minScore: policy?.candidateInjection?.minScore ?? DEFAULT_POLICY.candidateInjection.minScore,
     },
     alwaysVisible: normalizeAlwaysVisible(policy?.alwaysVisible ?? DEFAULT_POLICY.alwaysVisible).allowlist,
+    inventory:
+      extraRoots.length > 0 || policy?.inventory?.autoRefreshOnChange === false
+        ? {
+            roots: extraRoots.length > 0 ? extraRoots : undefined,
+            autoRefreshOnChange: policy?.inventory?.autoRefreshOnChange,
+          }
+        : undefined,
     skills: policy?.skills ?? DEFAULT_POLICY.skills,
   };
 }

package/src/types.ts

@@ -14,6 +14,12 @@ export interface ShioriPolicy {
     minScore: number;
   };
   alwaysVisible: string[];
+  inventory?: {
+    /** Extra skill roots relative to cwd or absolute paths. */
+    roots?: string[];
+    /** Rebuild the index when skill files change under any root (default: true). */
+    autoRefreshOnChange?: boolean;
+  };
   skills: Record<string, SkillPolicy>;
 }
 
@@ -49,4 +55,6 @@ export interface ShioriStats {
   retrievalBackend: RetrievalBackend;
   suppressionStatus: SuppressionStatus;
   lastReloadAt?: string;
+  inventoryRefreshCount: number;
+  inventoryAutoRefreshCount: number;
 }