pi-soly 1.13.4 → 1.14.0

package/index.ts

@@ -2,7 +2,7 @@
 // index.ts — Main soly extension entry point
 // =============================================================================
 //
-// Loads .soly/rules/ and .soly/ project state into the agent's system
+// Loads .agents/rules/ and .agents/ project state into the agent's system
 // prompt, and registers:
 //   - slash commands  /rules /soly /rulewizard /why
 //   - LLM tools       soly_read soly_log_decision soly_list_phases
@@ -42,6 +42,7 @@ import {
 	rulesApplicableToFiles,
 	STATUS_ID,
 	solyDirFor,
+	SOLY_DIRNAME,
 	isLegacySolyDir,
 	buildNextHint,
 	buildDriftReminder,
@@ -94,7 +95,7 @@ const SOLY_TOOLS_POINTER = `
 ## soly — interactive & visual tools
 
 When terminal text isn't the best medium, reach for these (details + when-NOT in the soly-framework skill):
-- \`ask_pro\` — multi-question picker (single/multi-select, free-text, per-option previews).
+- \`ask_pro\` — multi-question picker (single/multi-select, free-text, per-option previews); every options question always offers a free-text "Other…" so the user can answer in their own words.
 - \`decision_deck\` — full-screen cards comparing design options by their concrete code shape.
 - \`html_artifact\` — render HTML to a self-contained, browseable per-project gallery.`;
 
@@ -178,7 +179,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 	let codeMap: CodeMap | null = null;
 	let lastCodeMapSection = "";
 
-	// Project intent (zero-point docs from .soly/docs/) — always loaded
+	// Project intent (zero-point docs from .agents/docs/) — always loaded
 	let intentDocs: IntentDoc[] = [];
 	let lastIntentSection = "";
 
@@ -237,14 +238,14 @@ export default function solyExtension(pi: ExtensionAPI) {
 	/**
 	 * Persistent storage of rule mtimes from the previous session, so we can
 	 * show a "rules changed since last session" diff at startup.
-	 * Stored in <solyDir>/.soly-rule-mtimes.json (project) or
-	 * <homedir>/.soly/rule-mtimes.json (global fallback).
+	 * Stored in <solyDir>/rule-mtimes.json (project) or
+	 * <homedir>/.agents/rule-mtimes.json (global fallback).
 	 */
 	let lastSessionMtimes: Record<string, number> = {};
 	const mtimeStorePath = (): string => {
 		const base = state.solyDir && fs.existsSync(state.solyDir)
 			? state.solyDir
-			: path.join(os.homedir(), ".soly");
+			: path.join(os.homedir(), SOLY_DIRNAME);
 		try {
 			fs.mkdirSync(base, { recursive: true });
 		} catch {}
@@ -293,7 +294,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 		// Soly doesn't render the agent badge itself.
 		const agentGroup = "";
 
-		// Cross-extension: show pi-todo progress if either .soly/todos.json
+		// Cross-extension: show pi-todo progress if either .agents/todos.json
 		// (soly-integration mode) OR .pi-todos.json (standalone mode) exists.
 		// Cheap (one stat + one small JSON read); cached only for the
 		// lifetime of one updateStatus call.
@@ -407,32 +408,30 @@ export default function solyExtension(pi: ExtensionAPI) {
 	// ============================================================================
 
 	pi.on("session_start", async (event, ctx) => {
-		// Deprecation warning: if the project still uses `.soly/`, nudge the
-		// user toward `.agents/`. One-time per session.
+		// Legacy detection: a project with only a `.soly/` dir (no `.agents/`)
+		// is now invisible to soly — warn the user to rename it. soly no longer
+		// reads `.soly/`. One-time per session.
 		if (isLegacySolyDir(ctx.cwd)) {
 			notifyDeprecation(
 				ctx.ui,
-				`.soly/ (legacy)`,
-				`.agents/ (vendor-neutral)`,
-				`Run \`mv .soly .agents\` to migrate. Both names work for now.`,
+				`.soly/ (legacy, no longer read)`,
+				`.agents/`,
+				`Run \`mv .soly .agents\` — soly now reads only \`.agents/\`.`,
 			);
 		}
 
 		// Rules sources (priority order, higher wins on relPath collision).
-		// Project rules always beat global rules. .soly/rules.local/ is
+		// Project rules always beat global rules. `.agents/rules.local/` is
 		// gitignored — for personal overrides on top of the project's rules.
-		// .agents/rules/ is the vendor-neutral project-level convention
-		// (same role as the old .claude/rules/).
+		// `.agents/rules/` is the vendor-neutral project-level convention.
 		ruleSources = [
-			{ dir: path.join(ctx.cwd, ".soly", "rules.local"), source: "project-soly", sourceLabel: "local", priority: 5 },
-			{ dir: path.join(ctx.cwd, ".soly", "rules"), source: "project-soly", sourceLabel: "soly", priority: 4 },
+			{ dir: path.join(ctx.cwd, ".agents", "rules.local"), source: "project-agents", sourceLabel: "local", priority: 5 },
 			{ dir: path.join(ctx.cwd, ".agents", "rules"), source: "project-agents", sourceLabel: "agents", priority: 3 },
-			{ dir: path.join(os.homedir(), ".soly", "rules"), source: "global-soly", sourceLabel: "soly", priority: 2 },
 			{ dir: path.join(os.homedir(), ".agents", "rules"), source: "global-agents", sourceLabel: "agents", priority: 1 },
 		];
 		refreshRules();
 
-		// Project state — soly owns .soly/ at the project root
+		// Project state — soly owns .agents/ at the project root
 		state.solyDir = solyDirFor(ctx.cwd);
 		refreshState();
 
@@ -499,7 +498,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 			lastCodeMapSection = "";
 		}
 
-		// Load project intent (zero-point docs from .soly/docs/) — always
+		// Load project intent (zero-point docs from .agents/docs/) — always
 		refreshIntent();
 
 		// Start hot-reload watcher on rules dirs
@@ -570,7 +569,7 @@ export default function solyExtension(pi: ExtensionAPI) {
 				);
 			}
 		} else {
-			ctx.ui.notify("soly rules: none found in .soly/rules.local, .soly/rules, or ~/.soly/rules", "info");
+			ctx.ui.notify("soly rules: none found in .agents/rules.local, .agents/rules, or ~/.agents/rules", "info");
 		}
 
 		if (state.exists) {
@@ -892,12 +891,23 @@ export default function solyExtension(pi: ExtensionAPI) {
 	// Bundled into pi-soly as of v1.11.0 with UE5 session-retry fix + framed
 	// notifications + compact per-server status footer.
 	// We import dynamically because mcp/ has heavy deps (modelcontextprotocol/sdk)
-	// and we want soly to still load if MCP fails for any reason.
-	void import("./mcp/index.ts").then((m) => {
-		try {
-			m.default(pi);
-		} catch (err) {
-			console.error("[soly] MCP adapter failed to initialize:", err);
-		}
-	});
+	// and we want soly to still load if MCP fails for any reason. The import()
+	// itself can reject (e.g. `pi install` didn't resolve a transitive peer dep
+	// like @modelcontextprotocol/sdk) or throw synchronously under jiti — both
+	// must be swallowed so a broken MCP never takes down the whole agent.
+	try {
+		void import("./mcp/index.ts")
+			.then((m) => {
+				try {
+					m.default(pi);
+				} catch (err) {
+					console.error("[soly] MCP adapter failed to initialize:", err);
+				}
+			})
+			.catch((err) => {
+				console.error("[soly] MCP adapter unavailable (load failed):", err);
+			});
+	} catch (err) {
+		console.error("[soly] MCP adapter unavailable (load threw):", err);
+	}
 }

package/init.ts

@@ -27,9 +27,9 @@
 //   "cli"      — adds command/, flags/, shell-compat/ example rules
 //
 // Usage:
-//   /soly-init                  # interactive: pick template
-//   /soly-init minimal          # no prompts
-//   /soly-init web-app --yes
+//   /soly init                  # interactive: pick template
+//   /soly init minimal          # no prompts
+//   /soly init web-app --yes
 // =============================================================================
 
 import * as fs from "node:fs";
@@ -208,7 +208,7 @@ export async function initSolyProject(
 	// Preconditions
 	if (fs.existsSync(agentsDir) || fs.existsSync(path.join(cwd, ".soly"))) {
 		ui.notify(
-			`soly-init: project already initialized (found ${SOLY_DIRNAME}/ or .soly/). ` +
+			`soly init: project already initialized (found ${SOLY_DIRNAME}/ or .soly/). ` +
 				`Aborting to avoid overwriting.`,
 			"error",
 		);
@@ -223,7 +223,7 @@ export async function initSolyProject(
 			["minimal", "web-app", "library", "cli"],
 		);
 		if (!pick) {
-			ui.notify("soly-init: cancelled", "info");
+			ui.notify("soly init: cancelled", "info");
 			return { created: false, template: null, projectName };
 		}
 		template = pick as InitTemplate;
@@ -237,7 +237,7 @@ export async function initSolyProject(
 			`Create .agents/ structure in:\n  ${cwd}\n\nProject name: ${projectName}`,
 		);
 		if (!ok) {
-			ui.notify("soly-init: cancelled", "info");
+			ui.notify("soly init: cancelled", "info");
 			return { created: false, template: null, projectName };
 		}
 	}
@@ -289,7 +289,7 @@ export async function initSolyProject(
 		created.push(`.agents/${extra.file}`);
 	}
 	ui.notify(
-		`soly-init: done (${template}). Created:\n  - ${created.join("\n  - ")}\n\n` +
+		`soly init: done (${template}). Created:\n  - ${created.join("\n  - ")}\n\n` +
 			`Next:\n  1. Edit \`.agents/docs/vision.md\`\n  2. \`/plan 1\` to start the first phase`,
 		"info",
 	);

package/intent.ts

@@ -2,27 +2,27 @@
 // intent.ts — Project intent loader (the "0 point" of every soly project)
 // =============================================================================
 //
-// `.soly/docs/` is the zero-point of the project: documents written BEFORE
+// `.agents/docs/` is the zero-point of the project: documents written BEFORE
 // any soly plans, research, or code. It holds the user's vision, business
 // context, and architectural intent. Other soly artifacts (STATE, PLANS,
 // RESEARCH) flow FROM this input.
 //
 // Supported files: `.md` (full text) and `.html` (parsed for title + preview).
-// Nested directories are supported (e.g. `.soly/docs/api/auth.md`).
+// Nested directories are supported (e.g. `.agents/docs/api/auth.md`).
 //
-// Convention: any document in `.soly/docs/` is loaded into the system
+// Convention: any document in `.agents/docs/` is loaded into the system
 // prompt as "project intent". This is separate from:
-//   - rules (`.soly/rules/`) — how to behave
-//   - state (`.soly/STATE.md`, ROADMAP.md) — where we are
+//   - rules (`.agents/rules/`) — how to behave
+//   - state (`.agents/STATE.md`, ROADMAP.md) — where we are
 //   - planning (PLAN.md, CONTEXT.md) — what to do next
 //
-// Optional: `.soly/phases/<N>/docs/` is also scanned if the directory exists
+// Optional: `.agents/phases/<N>/docs/` is also scanned if the directory exists
 // (for backward compat / phase-specific intent). Not required.
 // =============================================================================
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { formatTok, resolveImports } from "./core.ts";
+import { formatTok, resolveImports, solyDirFor } from "./core.ts";
 import { extractTitleAndPreview, stripHtml } from "./html.ts";
 
 const DOC_EXTS = new Set([".md", ".html", ".htm"]);
@@ -148,15 +148,15 @@ function walkIntentDir(
 
 export function loadIntentDocs(cwd: string, currentPhaseNumber?: number): IntentDoc[] {
 	const out: IntentDoc[] = [];
-	const docsRoot = path.join(cwd, ".soly", "docs");
+	const docsRoot = path.join(solyDirFor(cwd), "docs");
 	walkIntentDir(docsRoot, "", undefined, out);
 
 	// Optional: phase-specific docs (only if current phase is known)
 	if (currentPhaseNumber != null) {
 		// We don't know the slug here without re-walking phases; scan any
-		// directory in .soly/phases/ whose name starts with the phase number.
+		// directory in .agents/phases/ whose name starts with the phase number.
 		// Skip if no phases dir exists.
-		const phasesRoot = path.join(cwd, ".soly", "phases");
+		const phasesRoot = path.join(solyDirFor(cwd), "phases");
 		if (fs.existsSync(phasesRoot)) {
 			try {
 				const phaseEntries = fs.readdirSync(phasesRoot, { withFileTypes: true });
@@ -196,7 +196,7 @@ export function buildIntentSection(intent: IntentDoc[]): IntentSection {
 		return { hasContent: false, section: "" };
 	}
 
-	const lines: string[] = ["", "## project intent (from .soly/docs/)", ""];
+	const lines: string[] = ["", "## project intent (from .agents/docs/)", ""];
 	lines.push(
 		"These documents are the **0 point** of this project — the user's vision, business context, and design intent, written BEFORE any soly plans. Read them first when planning, discussing, or executing. If implementation diverges from intent, fix one or the other — don't let drift compound.",
 	);
@@ -403,7 +403,7 @@ export function formatIntentStats(stats: IntentStats): string {
     lines.push(``);
   }
   if (stats.totalDocs === 0) {
-    lines.push(`No intent docs found in .soly/docs/ or ~/.soly/docs/`);
+    lines.push(`No intent docs found in .agents/docs/ or ~/.agents/docs/`);
   }
   return lines.join("\n");
 }

package/iteration.ts

@@ -2,7 +2,7 @@
 // iteration.ts — Per-iteration context bundle (B2 of the soly design)
 // =============================================================================
 //
-// Writes a self-contained .md file under `.soly/iterations/` that bundles
+// Writes a self-contained .md file under `.agents/iterations/` that bundles
 // everything a worker needs for ONE iteration of a plan / task / phase:
 // intent docs, STATE.md, ROADMAP row, phase CONTEXT, phase RESEARCH, up
 // to 3 prior SUMMARYs, and the current PLAN.md (for exec).
@@ -18,8 +18,8 @@
 // the worker's task string itself, so the worker has the most critical
 // bits available even before opening the file.
 //
-// All worktree writes go to `.soly/iterations/` (under the project's
-// `.soly/`), never to the project root. See workflow markdown templates
+// All worktree writes go to `.agents/iterations/` (under the project's
+// `.agents/`), never to the project root. See workflow markdown templates
 // for the hard rule.
 // =============================================================================
 
@@ -160,7 +160,7 @@ export function findRecentSummaries(dir: string, n: number): string[] {
 
 /** Find a phase's `<NN>-CONTEXT.md` path (or null).
  *  Convention: filename starts with the padded phase number, not the full
- *  slug. e.g. `.soly/phases/05-auth/05-CONTEXT.md`, not `05-auth-CONTEXT.md`. */
+ *  slug. e.g. `.agents/phases/05-auth/05-CONTEXT.md`, not `05-auth-CONTEXT.md`. */
 export function findPhaseContextPath(phaseDir: string): string | null {
 	const slug = path.basename(phaseDir);
 	const numMatch = slug.match(/^(\d+)/);
@@ -192,7 +192,7 @@ export function findContinueHerePath(phaseDir: string): string | null {
 
 function loadIntentSummary(solyDir: string, maxTokens: number): string {
 	const docsRoot = path.join(solyDir, "docs");
-	if (!fs.existsSync(docsRoot)) return "_(no \`.soly/docs/\` directory — drop your 0-point docs there)_";
+	if (!fs.existsSync(docsRoot)) return "_(no \`.agents/docs/\` directory — drop your 0-point docs there)_";
 
 	const files: string[] = [];
 	for (const e of fs.readdirSync(docsRoot, { withFileTypes: true })) {
@@ -206,7 +206,7 @@ function loadIntentSummary(solyDir: string, maxTokens: number): string {
 			files.push(full);
 		}
 	}
-	if (files.length === 0) return "_(no \`.md\` files in \`.soly/docs/\`)_";
+	if (files.length === 0) return "_(no \`.md\` files in \`.agents/docs/\`)_";
 
 	files.sort();
 	const out: string[] = [];
@@ -223,7 +223,7 @@ function loadIntentSummary(solyDir: string, maxTokens: number): string {
 			.join(" ");
 		const chunk = `- \`${relPath}\`: ${preview.slice(0, 240)}\n`;
 		if (usedChars + chunk.length > maxChars) {
-			out.push(`\n_(truncated at ${maxTokens} tokens; full files in \`.soly/docs/\`)_\n`);
+			out.push(`\n_(truncated at ${maxTokens} tokens; full files in \`.agents/docs/\`)_\n`);
 			break;
 		}
 		out.push(chunk);
@@ -370,7 +370,7 @@ function loadAntiPatterns(phaseDir: string, maxTokens: number): string {
 
 function loadFeatureReadme(feature: string, solyDir: string, maxTokens: number): string {
 	const readme = path.join(solyDir, "features", feature, "README.md");
-	if (!fs.existsSync(readme)) return `_(no \`.soly/features/${feature}/README.md\`)_`;
+	if (!fs.existsSync(readme)) return `_(no \`.agents/features/${feature}/README.md\`)_`;
 	return truncate(readIfExists(readme) ?? "", maxTokens);
 }
 
@@ -508,7 +508,7 @@ export function buildIterationContent(input: IterationInput): string {
 	sections.push(title);
 	sections.push("");
 	sections.push(`**Generated**: ${generatedAt}`);
-	sections.push(`**Soly dir**: \`${rel(projectRoot, input.solyDir) || ".soly"}\``);
+	sections.push(`**Soly dir**: \`${rel(projectRoot, input.solyDir) || ".agents"}\``);
 	if (input.taskId) {
 		sections.push(`**Task**: \`${input.taskId}\` in feature \`${input.feature ?? "?"}\``);
 	} else if (input.phaseNumber != null) {
@@ -524,10 +524,10 @@ export function buildIterationContent(input: IterationInput): string {
 	sections.push("");
 
 	// ---- Section 0: Intent ----
-	sections.push("## 0. Project Intent (from `.soly/docs/`)");
+	sections.push("## 0. Project Intent (from `.agents/docs/`)");
 	sections.push("");
 	sections.push(
-		`_Source: \`.soly/docs/\` (full files in \`.soly/docs/\`, see also \`soly_intent\` tool)_`,
+		`_Source: \`.agents/docs/\` (full files in \`.agents/docs/\`, see also \`soly_intent\` tool)_`,
 	);
 	sections.push("");
 	sections.push(loadIntentSummary(input.solyDir, SECTION_BUDGETS.intent));
@@ -548,7 +548,7 @@ export function buildIterationContent(input: IterationInput): string {
 
 	// ---- Section 1: State (only if there's a project state) ----
 	if (input.kind !== "pause") {
-		sections.push("## 1. Project State (`.soly/STATE.md` — Current Position + Decisions)");
+		sections.push("## 1. Project State (`.agents/STATE.md` — Current Position + Decisions)");
 		sections.push("");
 		sections.push(`_Source: \`${rel(projectRoot, path.join(input.solyDir, "STATE.md"))}\`_`);
 		sections.push("");

package/mcp/ext-apps-bridge.ts

@@ -0,0 +1,76 @@
+// =============================================================================
+// ext-apps-bridge.ts — lazy, guarded access to @modelcontextprotocol/ext-apps
+// =============================================================================
+//
+// `@modelcontextprotocol/ext-apps@1.7.4` (its peer is sdk `^1.29.0`, yet its
+// compiled CJS `app-bridge.js` does `require("@modelcontextprotocol/sdk/types.js")`
+// — a subpath sdk 1.29 no longer exposes to CJS) is currently broken upstream.
+// Importing it statically threw at module-eval and crashed the whole pi agent.
+//
+// So we load it LAZILY, exactly once, behind a try/catch. If it loads, the MCP-UI
+// (app-bridge) features work; if it can't, the cache is null and those features
+// degrade gracefully (no UI resource URIs, empty iframe allow-list, fallback MIME)
+// while core MCP keeps working. `preloadAppBridge()` is awaited early in MCP init
+// so the synchronous accessors below see a populated (or null) cache.
+//
+// The dynamic specifier is typed as `string` on purpose so TypeScript does not
+// resolve ext-apps' types (which themselves reference the missing sdk subpath).
+// =============================================================================
+
+/** Minimal shape of the bits of ext-apps/app-bridge we use. */
+interface AppBridge {
+	RESOURCE_MIME_TYPE: string;
+	getToolUiResourceUri(meta: { _meta?: unknown }): string | undefined;
+	buildAllowAttribute(permissions: unknown): string;
+}
+
+/** Mirrors ext-apps' RESOURCE_MIME_TYPE; used when the module can't be loaded. */
+const FALLBACK_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
+
+// `: string` (not a string literal) so `import()` is typed `Promise<any>` and TS
+// never tries to resolve ext-apps' (broken) types.
+const APP_BRIDGE_SPECIFIER: string = "@modelcontextprotocol/ext-apps/app-bridge";
+
+let cached: AppBridge | null = null;
+let attempted = false;
+
+/** Load ext-apps once (idempotent), swallowing any failure. Safe to await many
+ *  times. Call early in MCP init before the sync accessors are used. */
+export async function preloadAppBridge(): Promise<void> {
+	if (attempted) return;
+	attempted = true;
+	try {
+		cached = (await import(APP_BRIDGE_SPECIFIER)) as unknown as AppBridge;
+	} catch {
+		cached = null;
+		console.error(
+			"[soly] MCP UI (ext-apps/app-bridge) could not load — app-bridge features are disabled " +
+				"(upstream ext-apps/sdk version mismatch, not a soly bug). Core MCP is unaffected.",
+		);
+	}
+}
+
+/** ext-apps' RESOURCE_MIME_TYPE when loaded, else the fallback literal. */
+export function resourceMimeType(): string {
+	return cached?.RESOURCE_MIME_TYPE ?? FALLBACK_RESOURCE_MIME_TYPE;
+}
+
+/** ext-apps getToolUiResourceUri, or undefined when the bridge isn't available. */
+export function getToolUiResourceUri(meta: { _meta?: unknown }): string | undefined {
+	if (!cached) return undefined;
+	try {
+		return cached.getToolUiResourceUri(meta);
+	} catch {
+		return undefined;
+	}
+}
+
+/** ext-apps buildAllowAttribute, or "" (most restrictive) when not available. */
+export function buildAllowAttribute(permissions: unknown): string {
+	if (!cached) return "";
+	try {
+		return cached.buildAllowAttribute(permissions);
+	} catch {
+		return "";
+	}
+}

package/mcp/index.ts

@@ -13,6 +13,7 @@ import { getConfigPathFromArgv, truncateAtWord } from "./utils.ts";
 import { initializeOAuth, shutdownOAuth } from "./mcp-auth-flow.ts";
 import { createMcpDirectToolCallRenderer, renderMcpProxyToolCall, renderMcpToolResult } from "./tool-result-renderer.ts";
 import { ToolCache, cacheKey as makeCacheKey } from "./tool-cache.ts";
+import { preloadAppBridge } from "./ext-apps-bridge.ts";
 
 /** Default TTL for cached MCP tool results (60s). Tools that hit a stable
  *  server benefit; volatile ones are penalized for 60s — call sites can
@@ -131,6 +132,10 @@ export default function mcpAdapter(pi: ExtensionAPI) {
       console.error("MCP OAuth initialization failed:", err);
     });
 
+    // Load the (optional, sometimes-broken upstream) ext-apps UI bridge once,
+    // before metadata is built. Guarded — a failure disables UI features only.
+    await preloadAppBridge();
+
     const promise = initializeMcp(pi, ctx);
     initPromise = promise;
 

package/mcp/metadata-cache.ts

@@ -3,7 +3,7 @@ import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "
 import { dirname } from "node:path";
 import { getAgentPath } from "./agent-dir.ts";
 import { createHash } from "node:crypto";
-import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { getToolUiResourceUri } from "./ext-apps-bridge.ts";
 import type { McpTool, McpResource, ServerEntry, ToolMetadata } from "./types.ts";
 import { formatToolName, isToolExcluded } from "./types.ts";
 import { resourceNameToToolName } from "./resource-tools.ts";

package/mcp/tool-metadata.ts

@@ -1,4 +1,4 @@
-import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { getToolUiResourceUri } from "./ext-apps-bridge.ts";
 import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata, McpTool, McpResource, ServerEntry } from "./types.ts";
 import { formatToolName, isToolExcluded } from "./types.ts";

package/mcp/ui-resource-handler.ts

@@ -1,4 +1,4 @@
-import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { resourceMimeType } from "./ext-apps-bridge.ts";
 import { UrlElicitationRequiredError, type ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import { ResourceFetchError, ResourceParseError } from "./errors.ts";
 import { logger } from "./logger.ts";
@@ -47,7 +47,7 @@ export class UiResourceHandler {
       log.warn("Unsupported MIME type", { mimeType });
       throw new ResourceParseError(
         uri,
-        `unsupported MIME type "${mimeType}" (expected text/html or ${RESOURCE_MIME_TYPE})`,
+        `unsupported MIME type "${mimeType}" (expected text/html or ${resourceMimeType()})`,
         { server: serverName, mimeType }
       );
     }
@@ -69,7 +69,7 @@ export class UiResourceHandler {
     return {
       uri: content.uri ?? uri,
       html,
-      mimeType: mimeType ?? RESOURCE_MIME_TYPE,
+      mimeType: mimeType ?? resourceMimeType(),
       meta: {
         csp: contentMeta.csp ?? listMeta.csp,
         permissions: contentMeta.permissions ?? listMeta.permissions,
@@ -107,7 +107,7 @@ function selectContent(result: ReadResourceResult, preferredUri: string): Resour
 
 function isHtmlMimeType(mimeType: string): boolean {
   const normalized = mimeType.toLowerCase();
-  return normalized.startsWith("text/html") || normalized === RESOURCE_MIME_TYPE.toLowerCase();
+  return normalized.startsWith("text/html") || normalized === resourceMimeType().toLowerCase();
 }
 
 function toHtml(content: ResourceContentRecord): string {

package/mcp/ui-server.ts

@@ -2,7 +2,7 @@ import http, { type IncomingMessage, type ServerResponse } from "node:http";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { buildAllowAttribute } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { buildAllowAttribute } from "./ext-apps-bridge.ts";
 import type {
   CallToolRequest,
   CallToolResult,

package/notification.ts

@@ -168,7 +168,7 @@ export function notifyDeprecation(
 
 // ---------------------------------------------------------------------------
 // Plain-text fallback (no widget, just framed Unicode text via notify).
-// Used for the .soly/ migration banner and other places that don't have
+// Used for the legacy .soly/ detection banner and other places that don't have
 // access to a UI context yet (CLI startup, print mode, etc.)
 // ---------------------------------------------------------------------------
 

package/notifications-log.ts

@@ -2,7 +2,7 @@
 // notifications-log.ts — Persistent record of soly notifications
 // =============================================================================
 //
-// Appends every nudge/deprecation to a JSONL file at .agents/.soly/notifications.log
+// Appends every nudge/deprecation to a JSONL file at .agents/notifications.log
 // (inside the project dir; safe to commit if the user wants a public audit
 // trail, or .gitignore if not). One line per notification, JSON-encoded.
 //
@@ -33,7 +33,7 @@ export interface NotificationEntry {
 /** Where the log file lives. Respects HOME for tests. */
 export function logFilePath(cwd: string, home?: string): string {
 	const h = home ?? process.env.HOME ?? process.env.USERPROFILE ?? os.homedir();
-	return path.join(cwd, SOLY_DIRNAME, ".soly", "notifications.log");
+	return path.join(cwd, SOLY_DIRNAME, "notifications.log");
 }
 
 /** Append a single entry to the log. Creates parent dirs as needed. */

package/nudge.ts

@@ -82,9 +82,42 @@ export function classifyTaskHeuristics(prompt: string): TaskHeuristics {
 	return { nonTrivial, researchHeavy, mentions, suggestedAngles };
 }
 
+// ---------------------------------------------------------------------------
+// Confirm-before-coding gate
+// ---------------------------------------------------------------------------
+
+/** How hard soly pushes the LLM to clarify before writing code.
+ *   - "scope" — batch the substantive decisions (placement, pattern, scope,
+ *               interface) via ask_pro, then wait. Strongest.
+ *   - "ask"   — lighter: one "ready to implement, or discuss?" question.
+ *   - "off"   — no gate. */
+export type ConfirmLevel = "off" | "ask" | "scope";
+
+/** Normalize the config value (boolean back-compat) to a confirm level.
+ *  `true` → "scope" (strongest), `false` / absent → "off". */
+export function confirmLevelOf(v: boolean | ConfirmLevel | undefined): ConfirmLevel {
+	if (v === true) return "scope";
+	if (v === "ask" || v === "scope") return v;
+	return "off";
+}
+
+// "scope": pull the decisions only the user can make BEFORE coding, as one
+// batched ask_pro call — placement, pattern, scope, interface — instead of
+// guessing and editing files on assumptions.
+const SCOPE_DIRECTIVE = `**Scope it with me before you code.** For non-trivial work, do NOT start writing or editing files on assumptions about decisions only I can make. First surface them as a single \`ask_pro\` batch (2–5 questions in one call), covering the dimensions that actually matter for this task — typically:
+   - **Placement** — where should this live? (which file / module / layer; extend an existing unit or add a new one)
+   - **Architecture / pattern** — which approach? (follow an existing pattern in the codebase vs introduce a new one; reuse a dependency vs hand-roll)
+   - **Scope** — what's in vs out for this change? (defer adjacent work to its own task)
+   - **Interface** — the shape callers see (API / CLI / signature / return), when it's a genuine fork
+   - **Data / state** — schema, storage, or state-shape decisions, when relevant
+   Give each question 2–4 concrete options with a ⭐ recommended default + one-line rationale, and add \`allowOther\` so I can steer freely. Wait for my answers before touching files. Skip only for trivial fixes (typo / rename / one-liner) or when I've already decided ("just do it", "go", or a follow-up turn in an already-scoped task). Prefer 2–3 sharp questions over a long list — ask what changes the result, not ceremony.`;
+
+// "ask": lighter — a single "ready, or discuss first?" confirmation.
+const ASK_DIRECTIVE = `**Confirm before coding.** Don't jump straight into writing/editing code. First state your understanding and intended approach in 1–3 sentences and list anything still open, then ask via the \`ask_pro\` picker whether to proceed — one question with options like "Go — implement now", "Discuss / refine the approach", "Adjust scope first" (add an \`allowOther\` for a free-text steer). Wait for the choice before touching files. Skip only for trivial fixes, or when the user already said to proceed ("just do it", "go", "yes").`;
+
 export function buildNudgeSection(
 	heuristics: TaskHeuristics,
-	opts: { hasProject?: boolean; confirmBeforeCode?: boolean } = {},
+	opts: { hasProject?: boolean; confirmBeforeCode?: boolean | ConfirmLevel } = {},
 ): string {
 	// Always-on rules (cheap to add, high signal):
 	//   - Don't dive in on non-trivial tasks without a brief check
@@ -112,14 +145,16 @@ export function buildNudgeSection(
 	// model toward the workflow lifecycle instead of ad-hoc edits.
 	const workflowPoint =
 		opts.hasProject && heuristics.nonTrivial
-			? `\n\n4. **Route project work through the soly workflow.** For phase/task work in \`.soly/\`, prefer the lifecycle over ad-hoc edits: \`soly discuss <N>\` (scope) → \`soly plan <N>\` (write tasks) → \`soly execute <N>\` (do them) → \`soly verify\` (review). Run \`soly status\` to see where you are. Skip only for a genuine one-off.`
+			? `\n\n4. **Route project work through the soly workflow.** For phase/task work in \`.agents/\`, prefer the lifecycle over ad-hoc edits: \`soly discuss <N>\` (scope) → \`soly plan <N>\` (write tasks) → \`soly execute <N>\` (do them) → \`soly verify\` (review). Run \`soly status\` to see where you are. Skip only for a genuine one-off.`
 			: "";
 
-	// Confirm-before-coding gate: for non-trivial implementation, don't start
-	// editing files until the user has greenlit the approach.
+	// Confirm-before-coding gate: for non-trivial implementation, pull the
+	// open decisions out of the user before editing files. Strength is config-
+	// driven ("scope" = batch the substantive questions; "ask" = one go/discuss).
+	const confirmLevel = confirmLevelOf(opts.confirmBeforeCode);
 	const confirmBlock =
-		opts.confirmBeforeCode && heuristics.nonTrivial
-			? `\n\n   **Confirm before coding.** Don't jump straight into writing/editing code. First state your understanding and intended approach in 1–3 sentences and list anything still open, then ask via the \`ask_pro\` picker whether to proceed — one question with options like "Go — implement now", "Discuss / refine the approach", "Adjust scope first" (add an \`allowOther\` for a free-text steer). Wait for the choice before touching files. Skip only for trivial fixes, or when the user already said to proceed ("just do it", "go", "yes").`
+		confirmLevel !== "off" && heuristics.nonTrivial
+			? `\n\n   ${confirmLevel === "scope" ? SCOPE_DIRECTIVE : ASK_DIRECTIVE}`
 			: "";
 
 	return `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-soly",
-  "version": "1.13.4",
+  "version": "1.14.0",
   "description": "Project management + workflow framework for pi-coding-agent. Plans, state, MANDATORY rules, self-review, multi-question picker, native footer + welcome chrome — one npm install, zero config. The LLM drives execution and delegates to a worker subagent when available.",
   "type": "module",
   "main": "index.ts",
@@ -58,7 +58,6 @@
     "notifications-log.ts",
     "status.ts",
     "init.ts",
-    "migrate.ts",
     "codemap.ts",
     "state.ts",
     "hotreload.ts"