pi-soly 1.7.0 → 1.9.0

package/commands.ts

@@ -3,7 +3,8 @@
 // =============================================================================
 //
 // Registers slash commands (via pi.registerCommand):
-//   - /rules         manage soly rules (list/show/analytics/reload/enable/disable/add/new)
+//   - /rules         manage soly rules (list/show/stats/analytics/reload/enable/disable/add/new)
+//   - /docs          manage soly intent docs (stats — context breakdown)
 //   - /soly          project state inspection (position/plan/phases/tasks/...)
 //                    subcommands: position, state, plan, context, research, roadmap,
 //                                 progress, phases, tasks, task <id>, features,
@@ -21,15 +22,24 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
 	analyzeRules,
 	buildProgressBar,
+	buildRulesContextStats,
 	CONTEXT_WINDOW_TOKENS,
 	extractFilePathsFromPrompt,
 	formatAnalyticsFull,
+	formatRulesContextStats,
 	formatTok,
 	readIfExists,
 	solyDirFor,
 	type RuleFile,
 	type SolyState,
 } from "./core.ts";
+import {
+	buildIntentStats,
+	formatIntentStats,
+	loadInlineIntentBodies,
+	type IntentDoc,
+	type IntentInlineDoc,
+} from "./intent.ts";
 import type { SolyConfig } from "./config.ts";
 import { migrateSolyDir } from "./migrate.js";
 import { initSolyProject } from "./init.js";
@@ -51,6 +61,7 @@ export interface CommandsDeps {
 	refreshState: () => void;
 	updateStatus: (ui: CommandUI) => void;
 	getConfig: () => SolyConfig;
+	getIntentDocs: () => IntentDoc[];
 }
 
 export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
@@ -62,6 +73,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 		refreshState,
 		updateStatus,
 		getConfig,
+		getIntentDocs,
 	} = deps;
 
 	// ============================================================================
@@ -70,7 +82,7 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 
 	pi.registerCommand("rules", {
 		description:
-			"manage soly rules (list, show, analytics, reload, enable, disable)",
+			"manage soly rules (list, show, stats, analytics, reload, enable, disable)",
 		handler: async (args, ctx) => {
 			const ui: CommandUI = {
 				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
@@ -129,6 +141,16 @@ export function registerCommands(pi: ExtensionAPI, deps: CommandsDeps): void {
 				return;
 			}
 
+			if (sub === "stats") {
+				// Claude-memory-style breakdown: shows which rules are always-on
+				// (every turn) vs glob-matched (only when prompt has file paths).
+				// Surfaces context bloat and verifies rules will actually fire.
+				const rules = getRules();
+				const stats = buildRulesContextStats(rules, CONTEXT_WINDOW_TOKENS);
+				ui.notify(formatRulesContextStats(stats), "info");
+				return;
+			}
+
 			if (sub === "show") {
 				if (!target) {
 					ui.notify("Usage: /rules show <path>", "error");
@@ -335,6 +357,40 @@ What must the LLM do?
 	},
 	});
 
+	// ============================================================================
+	// /docs — manage soly intent docs (stats subcommand shows context usage)
+	// ============================================================================
+	pi.registerCommand("docs", {
+		description:
+			"manage soly intent docs (stats — show context breakdown)",
+		handler: async (args, ctx) => {
+			const ui: CommandUI = {
+				notify: (t, k) => ctx.ui.notify(t, k ?? "info"),
+				select: async (label, options) => {
+					const result = await ctx.ui.select(label, options);
+					return result === undefined ? null : options.indexOf(result);
+				},
+				confirm: (title, message) => ctx.ui.confirm(title, message),
+			};
+			const parts = args.trim().split(/\s+/);
+			const sub = parts[0] ?? "stats";
+
+			if (sub === "stats") {
+				const docs = getIntentDocs();
+				const inlineBodies: IntentInlineDoc[] = loadInlineIntentBodies(docs);
+				const stats = buildIntentStats(docs, inlineBodies);
+				ui.notify(formatIntentStats(stats), "info");
+				return;
+			}
+
+			ui.notify(
+				`Usage: /docs stats — show context breakdown for intent docs\n` +
+				`Found ${getIntentDocs().length} doc(s) loaded.`,
+				"info",
+			);
+		},
+	});
+
 	// ============================================================================
 	// /soly migrate — move .soly/ → .agents/ atomically
 	// ============================================================================

package/core.ts

@@ -993,6 +993,127 @@ export function formatAnalyticsFull(analytics: RuleAnalytics): string {
   return lines.join("\n");
 }
 
+// =============================================================================
+// Rules context stats — Claude-memory-style breakdown
+// =============================================================================
+//
+// Shows which rules are "always-on" (loaded every turn) vs "glob-matched"
+// (loaded only when file paths in prompt match). Useful for spotting
+// context bloat and verifying rules will actually fire.
+
+export interface RuleStat {
+  relPath: string;
+  tokens: number;
+  sourceLabel: string;
+  description?: string;
+  always: boolean;
+  globs: string[];
+  loadedLastTurn: boolean;
+}
+
+export interface RulesContextStats {
+  totalLoaded: number;
+  totalTokens: number;
+  contextBudgetPct: number;
+  alwaysOn: RuleStat[];
+  globMatched: RuleStat[];
+  disabled: RuleStat[];
+  lastTurn: {
+    promptFiles: string[];
+    matchedRulePaths: string[];
+  };
+}
+
+export function buildRulesContextStats(
+  rules: RuleFile[],
+  contextWindowTokens: number,
+  lastTurn?: { promptFiles: string[]; matchedRelPaths: string[] },
+): RulesContextStats {
+  const enabled = rules.filter((r) => r.enabled);
+  const disabled = rules.filter((r) => !r.enabled);
+  const lastTurnMatched = new Set(lastTurn?.matchedRelPaths ?? []);
+  const stat = (r: RuleFile, loadedLastTurn: boolean): RuleStat => ({
+    relPath: r.relPath,
+    tokens: estimateTokens(r.body),
+    sourceLabel: r.sourceLabel,
+    description: r.meta.description,
+    always: r.meta.always === true,
+    globs: r.meta.globs ?? [],
+    loadedLastTurn,
+  });
+  const alwaysOn: RuleStat[] = [];
+  const globMatched: RuleStat[] = [];
+  for (const r of enabled) {
+    const isAlways = r.meta.always === true;
+    const isLoadedLastTurn = lastTurnMatched.has(r.relPath) || isAlways;
+    const s = stat(r, isLoadedLastTurn);
+    if (isAlways) alwaysOn.push(s);
+    else globMatched.push(s);
+  }
+  const totalTokens = [...alwaysOn, ...globMatched].reduce((a, b) => a + b.tokens, 0);
+  return {
+    totalLoaded: enabled.length,
+    totalTokens,
+    contextBudgetPct:
+      contextWindowTokens > 0 ? (totalTokens / contextWindowTokens) * 100 : 0,
+    alwaysOn,
+    globMatched,
+    disabled: disabled.map((r) => stat(r, false)),
+    lastTurn: {
+      promptFiles: lastTurn?.promptFiles ?? [],
+      matchedRulePaths: lastTurn?.matchedRelPaths ?? [],
+    },
+  };
+}
+
+export function formatRulesContextStats(stats: RulesContextStats): string {
+  const lines: string[] = [];
+  lines.push(`📊 Rules context stats`);
+  lines.push(``);
+  const ctxWindow = stats.contextBudgetPct > 0
+    ? Math.round(stats.totalTokens / (stats.contextBudgetPct / 100))
+    : 0;
+  lines.push(
+    `Loaded: ${stats.totalLoaded} rule(s) · ${formatTok(stats.totalTokens)} · ${stats.contextBudgetPct.toFixed(1)}% of ${formatTok(ctxWindow)} context`,
+  );
+  lines.push(``);
+  if (stats.alwaysOn.length > 0) {
+    lines.push(`ALWAYS-ON (loaded every turn):`);
+    for (const r of stats.alwaysOn) {
+      const last = r.loadedLastTurn ? " ✓" : "";
+      const desc = r.description ? ` — "${r.description}"` : "";
+      lines.push(`  ● ${r.relPath}  ${formatTok(r.tokens)}${desc}${last}`);
+    }
+    lines.push(``);
+  }
+  if (stats.globMatched.length > 0) {
+    lines.push(`GLOB-MATCHED (loaded when prompt file matches):`);
+    for (const r of stats.globMatched) {
+      const last = r.loadedLastTurn ? " ✓" : "";
+      const desc = r.description ? ` — "${r.description}"` : "";
+      const globs = r.globs.length > 0 ? `  [globs: ${r.globs.join(", ")}]` : "";
+      lines.push(`  ◐ ${r.relPath}  ${formatTok(r.tokens)}${desc}${globs}${last}`);
+    }
+    lines.push(``);
+  }
+  if (stats.disabled.length > 0) {
+    lines.push(`DISABLED:`);
+    for (const r of stats.disabled) {
+      lines.push(`  ○ ${r.relPath}  ${formatTok(r.tokens)} — disabled`);
+    }
+    lines.push(``);
+  }
+  if (stats.lastTurn.promptFiles.length > 0) {
+    lines.push(`Last turn: ${stats.lastTurn.promptFiles.length} file path(s) in prompt`);
+    for (const f of stats.lastTurn.promptFiles) {
+      lines.push(`  → ${f}`);
+    }
+  } else {
+    lines.push(`Last turn: no file paths in prompt (only always-on rules loaded)`);
+  }
+  return lines.join("\n");
+}
+
 // ============================================================================
 // @import resolver (markdown only)
 // ============================================================================

package/index.ts

@@ -307,6 +307,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 		refreshState: () => refreshState(),
 		updateStatus: (ui) => updateStatus(ui),
 		getConfig: getActiveConfig,
+		getIntentDocs: () => intentDocs,
 	});
 
 	registerTools(pi, {

package/intent.ts

@@ -301,3 +301,109 @@ export function loadInlineIntentBodies(intent: IntentDoc[]): IntentInlineDoc[] {
 	}
 	return out;
 }
+
+// =============================================================================
+// Intent stats — Claude-memory-style breakdown for docs
+// =============================================================================
+//
+// Shows how docs consume context. Most docs are preview-only (cheap),
+// only `inline: true` docs inject their full body (expensive).
+
+export interface IntentDocStat {
+  relPath: string;
+  kind: "md" | "html";
+  title: string;
+  tokens: number;       // full file tokens (what would be loaded if inline)
+  previewTokens: number; // preview tokens (what's actually loaded by default)
+  inline: boolean;      // true if `inline: true` frontmatter — body is injected
+  oversized: boolean;
+  phaseNumber?: number;
+}
+
+export interface IntentStats {
+  totalDocs: number;
+  totalInlineTokens: number;     // tokens from inline: true docs (full body)
+  totalPreviewTokens: number;    // tokens from preview-only docs (always loaded)
+  totalPerTurnTokens: number;    // sum of what's actually in system prompt
+  inlineDocs: IntentDocStat[];
+  previewDocs: IntentDocStat[];
+  phaseSpecificDocs: IntentDocStat[];
+}
+
+export function buildIntentStats(
+  docs: IntentDoc[],
+  inlineBodies: IntentInlineDoc[],
+): IntentStats {
+  const inlineRelPaths = new Set(inlineBodies.map((d) => d.relPath));
+  const inlineBodyTokens = new Map(inlineBodies.map((d) => [d.relPath, d.tokens]));
+  const stat = (d: IntentDoc): IntentDocStat => ({
+    relPath: d.relPath,
+    kind: d.kind,
+    title: d.title,
+    tokens: d.tokens,
+    previewTokens: Math.ceil(d.preview.length / 4),
+    inline: inlineRelPaths.has(d.relPath),
+    oversized: d.oversized,
+    phaseNumber: d.phaseNumber,
+  });
+  const all = docs.map(stat);
+  const inlineDocs = all.filter((d) => d.inline);
+  const previewDocs = all.filter((d) => !d.inline);
+  const phaseSpecificDocs = all.filter((d) => d.phaseNumber != null);
+  const totalInlineTokens = inlineDocs.reduce(
+    (a, b) => a + (inlineBodyTokens.get(b.relPath) ?? b.tokens),
+    0,
+  );
+  const totalPreviewTokens = previewDocs.reduce((a, b) => a + b.previewTokens, 0);
+  return {
+    totalDocs: all.length,
+    totalInlineTokens,
+    totalPreviewTokens,
+    totalPerTurnTokens: totalInlineTokens + totalPreviewTokens,
+    inlineDocs,
+    previewDocs,
+    phaseSpecificDocs,
+  };
+}
+
+export function formatIntentStats(stats: IntentStats): string {
+  const lines: string[] = [];
+  lines.push(`📚 Docs context stats`);
+  lines.push(``);
+  lines.push(
+    `Loaded: ${stats.totalDocs} doc(s) · ${stats.totalPerTurnTokens} tok every turn`,
+  );
+  lines.push(
+    `  (${stats.totalInlineTokens} from inline bodies + ${stats.totalPreviewTokens} from previews)`,
+  );
+  lines.push(``);
+  if (stats.inlineDocs.length > 0) {
+    lines.push(`INLINE (full body loaded every turn):`);
+    for (const d of stats.inlineDocs) {
+      const title = d.title ? ` — "${d.title}"` : "";
+      lines.push(`  ● ${d.relPath}  ${d.tokens} tok${title}`);
+    }
+    lines.push(``);
+  }
+  if (stats.previewDocs.length > 0) {
+    lines.push(`PREVIEW-ONLY (only title + 180-char preview loaded):`);
+    for (const d of stats.previewDocs) {
+      const title = d.title ? ` — "${d.title}"` : "";
+      const size = d.oversized ? " (oversized)" : "";
+      lines.push(`  ○ ${d.relPath}  ${d.previewTokens} tok preview${title}${size}`);
+    }
+    lines.push(``);
+  }
+  if (stats.phaseSpecificDocs.length > 0) {
+    lines.push(`PHASE-SPECIFIC (only loaded for matching phase):`);
+    for (const d of stats.phaseSpecificDocs) {
+      const title = d.title ? ` — "${d.title}"` : "";
+      lines.push(`  ◐ phase ${d.phaseNumber}: ${d.relPath}${title}`);
+    }
+    lines.push(``);
+  }
+  if (stats.totalDocs === 0) {
+    lines.push(`No intent docs found in .soly/docs/ or ~/.soly/docs/`);
+  }
+  return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "Project management framework for pi-coding-agent. Workflows, planning, multi-question picker, agent switcher, live task list — one npm install, zero config.",
   "type": "module",
   "main": "index.ts",