@selesai/code 0.10.2 → 0.12.0

package/dist/modes/interactive/interactive-mode.js

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as TuiLayouts from "@earendil-works/pi-tui";
-import { CombinedAutocompleteProvider, Container, fuzzyFilter, Markdown, matchesKey, ProcessTerminal, Spacer, setKeybindings, Text, TruncatedText, TuiAltScreen, TuiMainScreen, visibleWidth, } from "@earendil-works/pi-tui";
+import { CombinedAutocompleteProvider, Container, fuzzyFilter, Markdown, matchesKey, ProcessTerminal, Spacer, setCapabilityOverrides, setKeybindings, Text, TruncatedText, TuiAltScreen, TuiMainScreen, visibleWidth, } from "@earendil-works/pi-tui";
 import chalk from "chalk";
 import { spawn, spawnSync } from "child_process";
 import { APP_NAME, APP_TITLE, CONFIG_DIR_NAME, getAgentDir, getAuthPath, getBundledDefaultsDir, getDebugLogPath, getDocsPath, getShareViewerUrl, getUpdateInstruction, PACKAGE_NAME, VERSION, } from "../../config.js";
@@ -107,8 +107,22 @@ const SELESAI_LOGO = [
     " \\/_\\__ \\\\ \\  _\\L\\ \\ \\  __\\ \\  _\\L\\/_\\__ \\\\ \\  __ \\ \\ \\ \\",
     "   /\\ \\L\\ \\ \\ \\L\\ \\ \\ \\L\\ \\\\ \\ \\L\\ \\/\\ \\L\\ \\ \\ \\/\\ \\ \\_\\ \\__",
     "   \\ `\\____\\ \\____/\\ \\____/ \\ \\____/\\ `\\____\\ \\_\\ \\_\\/\\_____\\",
-    "    \\/_____/\\/___/  \\/___/   \\/___/  \\/_____/\\/_/\\/_/\\/_____/",
-].join("\n");
+    "    \\/_____/\\/___/  \\/___/   \\/___/  \\/_____/\\/_\\/\\/_\\/\\/_____\\",
+];
+// Vertical gradient across logo lines: top #ff6b2c → bottom #fb923c.
+function gradientLogo(lines, from, to) {
+    const a = [0xff, 0x6b, 0x2c];
+    const b = [0xfb, 0x92, 0x3c];
+    return lines
+        .map((line, i) => {
+        const t = lines.length === 1 ? 0 : i / (lines.length - 1);
+        const r = Math.round(a[0] + (b[0] - a[0]) * t);
+        const g = Math.round(a[1] + (b[1] - a[1]) * t);
+        const bl = Math.round(a[2] + (b[2] - a[2]) * t);
+        return chalk.hex(`#${((r << 16) | (g << 8) | bl).toString(16).padStart(6, "0")}`).bold(line);
+    })
+        .join("\n");
+}
 function isAnthropicSubscriptionAuthKey(apiKey) {
     return typeof apiKey === "string" && apiKey.startsWith("sk-ant-oat");
 }
@@ -185,6 +199,7 @@ export function createInteractiveTui(options) {
             searchCurrentMatchStyle: (text) => theme.bold(theme.inverse(styleSearchMatch(text))),
             openUrl: openBrowser,
             onRightClickPaste: options.onRightClickPaste,
+            copyOnSelect: options.fullscreenCopyOnSelect,
             copySelection: async (text) => {
                 try {
                     await copyToClipboard(text);
@@ -345,6 +360,7 @@ export class InteractiveMode {
     }
     constructor(runtimeHost, options = {}) {
         this.runtimeHost = runtimeHost;
+        setCapabilityOverrides(this.settingsManager.getTerminalCapabilityOverrides());
         const tuiMode = options.tuiMode ?? this.settingsManager.getTuiMode();
         this.options = { ...options, tuiMode };
         this.autoTrustOnReloadCwd = options.autoTrustOnReloadCwd;
@@ -360,6 +376,7 @@ export class InteractiveMode {
             showHardwareCursor: this.settingsManager.getShowHardwareCursor(),
             logDirectory: getAgentDir(),
             onRightClickPaste: this.onRightClickPaste,
+            fullscreenCopyOnSelect: this.settingsManager.getFullscreenCopyOnSelect(),
         });
         this.ui = createInteractiveTuiReference(() => this.renderer);
         this.ui.setClearOnShrink(this.settingsManager.getClearOnShrink());
@@ -596,6 +613,7 @@ export class InteractiveMode {
             logDirectory: getAgentDir(),
             terminal,
             onRightClickPaste: this.onRightClickPaste,
+            fullscreenCopyOnSelect: this.settingsManager.getFullscreenCopyOnSelect(),
         });
         nextUi.setClearOnShrink(clearOnShrink);
         nextUi.onDebug = onDebug;
@@ -678,7 +696,7 @@ export class InteractiveMode {
         this.isInitialized = true;
         await this.themeController.applyFromSettings();
         // Brand banner always appears; quiet startup only hides keybinding help.
-        const logo = `${theme.bold(theme.fg("accent", SELESAI_LOGO))}\n${theme.fg("dim", `  ${APP_NAME} v${this.version} · /help for commands`)}`;
+        const logo = `${gradientLogo(SELESAI_LOGO, "#ff6b2c", "#fb923c")}\n${theme.fg("dim", `  ${APP_NAME} v${this.version} · /help for commands`)}`;
         // Build startup instructions using keybinding hint helpers
         const hint = (keybinding, description) => keyHint(keybinding, description);
         const expandedInstructions = [
@@ -1410,7 +1428,11 @@ export class InteractiveMode {
         this.showStartupNoticesIfNeeded();
     }
     applyRuntimeSettings() {
+        setCapabilityOverrides(this.settingsManager.getTerminalCapabilityOverrides());
         configureHttpDispatcher(this.settingsManager.getHttpIdleTimeoutMs());
+        if (this.renderer instanceof TuiAltScreen) {
+            this.renderer.setCopyOnSelect(this.settingsManager.getFullscreenCopyOnSelect());
+        }
         this.footer.setSession(this.session);
         this.footer.setAutoCompactEnabled(this.session.autoCompactionEnabled);
         this.footerDataProvider.setCwd(this.sessionManager.getCwd());
@@ -1557,6 +1579,9 @@ export class InteractiveMode {
             this.statusContainer.addChild(this.idleStatus);
         }
     }
+    showWorkingStatusIndicator() {
+        this.showStatusIndicator(new WorkingStatusIndicator(this.ui, this.workingMessage ?? this.defaultWorkingMessage, this.workingIndicatorOptions));
+    }
     setWorkingVisible(visible) {
         this.workingVisible = visible;
         if (!visible) {
@@ -1565,7 +1590,7 @@ export class InteractiveMode {
             return;
         }
         if (this.session.isStreaming && this.activeStatusIndicator?.kind !== "working") {
-            this.showStatusIndicator(new WorkingStatusIndicator(this.ui, this.workingMessage ?? this.defaultWorkingMessage, this.workingIndicatorOptions));
+            this.showWorkingStatusIndicator();
         }
         this.ui.requestRender();
     }
@@ -2177,7 +2202,7 @@ export class InteractiveMode {
         this.defaultEditor.onAction("app.tools.expand", () => this.toggleToolOutputExpansion());
         this.defaultEditor.onAction("app.thinking.toggle", () => this.toggleThinkingBlockVisibility());
         this.defaultEditor.onAction("app.editor.external", () => void this.handleOpenExternalEditor());
-        this.defaultEditor.onAction("app.message.copy", () => void this.handleCopyCommand());
+        this.defaultEditor.onAction("app.message.copy", () => void this.handleCopyCommand({ flashConfirmation: true, preferSelection: true }));
         this.defaultEditor.onAction("app.message.followUp", () => this.handleFollowUp());
         this.defaultEditor.onAction("app.message.dequeue", () => this.handleDequeue());
         this.defaultEditor.onAction("app.session.new", () => this.handleClearCommand());
@@ -2496,17 +2521,21 @@ export class InteractiveMode {
         switch (event.type) {
             case "agent_start":
                 this.pendingTools.clear();
-                if (this.settingsManager.getShowTerminalProgress()) {
-                    this.ui.terminal.setProgress(true);
-                }
                 // Restore main escape handler if retry handler is still active
                 // (retry success event fires later, but we need main handler now)
                 if (this.retryEscapeHandler) {
                     this.defaultEditor.onEscape = this.retryEscapeHandler;
                     this.retryEscapeHandler = undefined;
                 }
+                break;
+            case "turn_start":
+                if (this.settingsManager.getShowTerminalProgress()) {
+                    this.ui.terminal.setProgress(true);
+                }
                 if (this.workingVisible) {
-                    this.showStatusIndicator(new WorkingStatusIndicator(this.ui, this.workingMessage ?? this.defaultWorkingMessage, this.workingIndicatorOptions));
+                    if (this.activeStatusIndicator?.kind !== "working") {
+                        this.showWorkingStatusIndicator();
+                    }
                 }
                 else {
                     this.clearStatusIndicator();
@@ -3358,18 +3387,19 @@ export class InteractiveMode {
         }
         this.showStatus(`Tool output: ${expanded ? "expanded" : "collapsed"}`);
     }
+    /** Update rendered assistant messages without rebuilding live tool components. */
+    updateThinkingBlockVisibility() {
+        for (const child of this.chatContainer.children) {
+            if (child instanceof AssistantMessageComponent) {
+                child.setHideThinkingBlock(this.hideThinkingBlock);
+            }
+        }
+        this.ui.requestRender();
+    }
     toggleThinkingBlockVisibility() {
         this.hideThinkingBlock = !this.hideThinkingBlock;
         this.settingsManager.setHideThinkingBlock(this.hideThinkingBlock);
-        // Rebuild chat from session messages
-        this.chatContainer.clear();
-        this.rebuildChatFromMessages();
-        // If streaming, re-add the streaming component with updated visibility and re-render
-        if (this.streamingComponent && this.streamingMessage) {
-            this.streamingComponent.setHideThinkingBlock(this.hideThinkingBlock);
-            this.streamingComponent.updateContent(this.streamingMessage);
-            this.chatContainer.addChild(this.streamingComponent);
-        }
+        this.updateThinkingBlockVisibility();
         this.showStatus(`Thinking blocks: ${this.hideThinkingBlock ? "hidden" : "visible"}`);
     }
     async handleOpenExternalEditor() {
@@ -3666,6 +3696,7 @@ export class InteractiveMode {
                 tuiMode: this.settingsManager.getTuiMode(),
                 fullscreenExitOutput: this.settingsManager.getFullscreenExitOutput(),
                 fullscreenScrollbar: this.settingsManager.getFullscreenScrollbar(),
+                fullscreenCopyOnSelect: this.settingsManager.getFullscreenCopyOnSelect(),
                 warnings: this.settingsManager.getWarnings(),
                 skills: this.buildSkillToggleItems(),
             }, {
@@ -3737,13 +3768,7 @@ export class InteractiveMode {
                 onHideThinkingBlockChange: (hidden) => {
                     this.hideThinkingBlock = hidden;
                     this.settingsManager.setHideThinkingBlock(hidden);
-                    for (const child of this.chatContainer.children) {
-                        if (child instanceof AssistantMessageComponent) {
-                            child.setHideThinkingBlock(hidden);
-                        }
-                    }
-                    this.chatContainer.clear();
-                    this.rebuildChatFromMessages();
+                    this.updateThinkingBlockVisibility();
                 },
                 onShowCacheMissNoticesChange: (shown) => {
                     this.settingsManager.setShowCacheMissNotices(shown);
@@ -3833,6 +3858,11 @@ export class InteractiveMode {
                     this.transcriptScrollView?.setScrollbar(mode);
                     this.ui.requestRender();
                 },
+                onFullscreenCopyOnSelectChange: (enabled) => {
+                    this.settingsManager.setFullscreenCopyOnSelect(enabled);
+                    if (this.renderer instanceof TuiAltScreen)
+                        this.renderer.setCopyOnSelect(enabled);
+                },
                 onWarningsChange: (warnings) => {
                     this.settingsManager.setWarnings(warnings);
                 },
@@ -4043,6 +4073,7 @@ export class InteractiveMode {
                     return;
                 try {
                     await this.session.setModel(model);
+                    this.updateAvailableProviderCount();
                     this.footer.invalidate();
                     this.updateEditorBorderColor();
                     done();
@@ -4856,21 +4887,8 @@ export class InteractiveMode {
                 activeHeader.setExpanded(this.toolOutputExpanded);
             }
             setRegisteredThemes(this.session.resourceLoader.getThemes().themes);
+            this.applyRuntimeSettings();
             await this.themeController.applyFromSettings();
-            const editorPaddingX = this.settingsManager.getEditorPaddingX();
-            const autocompleteMaxVisible = this.settingsManager.getAutocompleteMaxVisible();
-            this.defaultEditor.setPaddingX(editorPaddingX);
-            this.defaultEditor.setAutocompleteMaxVisible(autocompleteMaxVisible);
-            if (this.editor !== this.defaultEditor) {
-                this.editor.setPaddingX?.(editorPaddingX);
-                this.editor.setAutocompleteMaxVisible?.(autocompleteMaxVisible);
-            }
-            this.ui.setShowHardwareCursor(this.settingsManager.getShowHardwareCursor());
-            const clearOnShrink = this.settingsManager.getClearOnShrink();
-            this.ui.setClearOnShrink(clearOnShrink);
-            if (!clearOnShrink && !this.activeStatusIndicator) {
-                this.statusContainer.clear();
-            }
             this.setupAutocompleteProvider();
             const runner = this.session.extensionRunner;
             this.setupExtensionShortcuts(runner);
@@ -5068,7 +5086,14 @@ export class InteractiveMode {
             }
         }
     }
-    async handleCopyCommand() {
+    async handleCopyCommand(options = {}) {
+        if (options.preferSelection &&
+            this.ui instanceof TuiAltScreen &&
+            !this.ui.getCopyOnSelect() &&
+            this.ui.hasActiveSelection()) {
+            await this.ui.copyActiveSelectionToClipboard();
+            return;
+        }
         const text = this.session.getLastAssistantText();
         if (!text) {
             this.showError("No agent messages to copy yet.");
@@ -5076,7 +5101,12 @@ export class InteractiveMode {
         }
         try {
             await copyToClipboard(text);
-            this.showStatus("Copied last agent message to clipboard");
+            if (options.flashConfirmation && this.ui instanceof TuiAltScreen) {
+                this.ui.flash("Copied!");
+            }
+            else {
+                this.showStatus("Copied last agent message to clipboard");
+            }
         }
         catch (error) {
             this.showError(error instanceof Error ? error.message : String(error));

package/dist/modes/rpc/rpc-client.d.ts

@@ -75,6 +75,13 @@ export declare class RpcClient {
      * Abort current operation.
      */
     abort(): Promise<void>;
+    /**
+     * Clear queued steering and follow-up messages, returning their text.
+     */
+    clearQueue(): Promise<{
+        steering: string[];
+        followUp: string[];
+    }>;
     /**
      * Start a new session, optionally with parent tracking.
      * @param parentSession - Optional parent session path for lineage tracking

package/dist/modes/rpc/rpc-client.js

@@ -153,6 +153,13 @@ export class RpcClient {
     async abort() {
         await this.send({ type: "abort" });
     }
+    /**
+     * Clear queued steering and follow-up messages, returning their text.
+     */
+    async clearQueue() {
+        const response = await this.send({ type: "clear_queue" });
+        return this.getData(response);
+    }
     /**
      * Start a new session, optionally with parent tracking.
      * @param parentSession - Optional parent session path for lineage tracking

package/dist/modes/rpc/rpc-mode.js

@@ -331,6 +331,9 @@ export async function runRpcMode(runtimeHost) {
                 await session.abort();
                 return success(id, "abort");
             }
+            case "clear_queue": {
+                return success(id, "clear_queue", session.clearQueue());
+            }
             case "new_session": {
                 const options = command.parentSession ? { parentSession: command.parentSession } : undefined;
                 const result = await runtimeHost.newSession(options);

package/dist/modes/rpc/rpc-types.d.ts

@@ -30,6 +30,9 @@ export type RpcCommand = {
 } | {
     id?: string;
     type: "abort";
+} | {
+    id?: string;
+    type: "clear_queue";
 } | {
     id?: string;
     type: "new_session";
@@ -206,6 +209,15 @@ export type RpcResponse = {
     type: "response";
     command: "abort";
     success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "clear_queue";
+    success: true;
+    data: {
+        steering: string[];
+        followUp: string[];
+    };
 } | {
     id?: string;
     type: "response";

package/dist/package-manager-cli.js

@@ -52,91 +52,91 @@ function getPackageCommandUsage(command) {
 }
 const CONFIG_COMMAND_USAGE = `${APP_NAME} config [-l] [--approve|--no-approve]`;
 function printConfigCommandHelp() {
-    console.log(`${chalk.bold("Usage:")}
-  ${CONFIG_COMMAND_USAGE}
-
-Open the resource configuration TUI to enable or disable package resources.
-Without -l, starts in global settings (~/${CONFIG_DIR_NAME}/agent/settings.json).
-Press Tab in the TUI to switch between global and project-local modes.
-
-Options:
-  -l, --local       Edit project overrides (${CONFIG_DIR_NAME}/settings.json)
-  -a, --approve     Trust project-local files for this command with -l
-  -na, --no-approve Ignore project-local files for this command with -l
+    console.log(`${chalk.bold("Usage:")}
+  ${CONFIG_COMMAND_USAGE}
+
+Open the resource configuration TUI to enable or disable package resources.
+Without -l, starts in global settings (~/${CONFIG_DIR_NAME}/agent/settings.json).
+Press Tab in the TUI to switch between global and project-local modes.
+
+Options:
+  -l, --local       Edit project overrides (${CONFIG_DIR_NAME}/settings.json)
+  -a, --approve     Trust project-local files for this command with -l
+  -na, --no-approve Ignore project-local files for this command with -l
 `);
 }
 function printPackageCommandHelp(command) {
     switch (command) {
         case "install":
-            console.log(`${chalk.bold("Usage:")}
-  ${getPackageCommandUsage("install")}
-
-Install a package and add it to settings.
-
-Options:
-  -l, --local       Install project-locally (${CONFIG_DIR_NAME}/settings.json)
-  -a, --approve     Trust project-local files for this command
-  -na, --no-approve Ignore project-local files for this command
-
-Examples:
-  ${APP_NAME} install npm:@foo/bar
-  ${APP_NAME} install git:github.com/user/repo
-  ${APP_NAME} install git:git@github.com:user/repo
-  ${APP_NAME} install https://github.com/user/repo
-  ${APP_NAME} install ssh://git@github.com/user/repo
-  ${APP_NAME} install ./local/path
+            console.log(`${chalk.bold("Usage:")}
+  ${getPackageCommandUsage("install")}
+
+Install a package and add it to settings.
+
+Options:
+  -l, --local       Install project-locally (${CONFIG_DIR_NAME}/settings.json)
+  -a, --approve     Trust project-local files for this command
+  -na, --no-approve Ignore project-local files for this command
+
+Examples:
+  ${APP_NAME} install npm:@foo/bar
+  ${APP_NAME} install git:github.com/user/repo
+  ${APP_NAME} install git:git@github.com:user/repo
+  ${APP_NAME} install https://github.com/user/repo
+  ${APP_NAME} install ssh://git@github.com/user/repo
+  ${APP_NAME} install ./local/path
 `);
             return;
         case "remove":
-            console.log(`${chalk.bold("Usage:")}
-  ${getPackageCommandUsage("remove")}
-
-Remove a package and its source from settings.
-Alias: ${APP_NAME} uninstall <source> [-l]
-
-Options:
-  -l, --local       Remove from project settings (${CONFIG_DIR_NAME}/settings.json)
-  -a, --approve     Trust project-local files for this command
-  -na, --no-approve Ignore project-local files for this command
-
-Examples:
-  ${APP_NAME} remove npm:@foo/bar
-  ${APP_NAME} uninstall npm:@foo/bar
+            console.log(`${chalk.bold("Usage:")}
+  ${getPackageCommandUsage("remove")}
+
+Remove a package and its source from settings.
+Alias: ${APP_NAME} uninstall <source> [-l]
+
+Options:
+  -l, --local       Remove from project settings (${CONFIG_DIR_NAME}/settings.json)
+  -a, --approve     Trust project-local files for this command
+  -na, --no-approve Ignore project-local files for this command
+
+Examples:
+  ${APP_NAME} remove npm:@foo/bar
+  ${APP_NAME} uninstall npm:@foo/bar
 `);
             return;
         case "update":
-            console.log(`${chalk.bold("Usage:")}
-  ${getPackageCommandUsage("update")}
-
-Update pi, installed packages, or model catalogs.
-
-Options:
-  --self                  Update pi only (default when no target is given)
-  --extensions            Update installed packages only
-  --models                Refresh model catalogs only
-  --all                   Update pi and installed packages
-  --extension <source>    Update one package only
-  -a, --approve           Trust project-local files for this command
-  -na, --no-approve       Ignore project-local files for this command
-  --force                 Reinstall pi even if the current version is latest
-
-Short forms:
-  ${APP_NAME} update                Update pi only
-  ${APP_NAME} update --all          Update pi and all extensions
-  ${APP_NAME} update --models       Refresh model catalogs only
-  ${APP_NAME} update <source>       Update one package
-  ${APP_NAME} update pi             Update pi only (self works as alias to pi)
+            console.log(`${chalk.bold("Usage:")}
+  ${getPackageCommandUsage("update")}
+
+Update pi, installed packages, or model catalogs.
+
+Options:
+  --self                  Update pi only (default when no target is given)
+  --extensions            Update installed packages only
+  --models                Refresh model catalogs only
+  --all                   Update pi and installed packages
+  --extension <source>    Update one package only
+  -a, --approve           Trust project-local files for this command
+  -na, --no-approve       Ignore project-local files for this command
+  --force                 Reinstall pi even if the current version is latest
+
+Short forms:
+  ${APP_NAME} update                Update pi only
+  ${APP_NAME} update --all          Update pi and all extensions
+  ${APP_NAME} update --models       Refresh model catalogs only
+  ${APP_NAME} update <source>       Update one package
+  ${APP_NAME} update pi             Update pi only (self works as alias to pi)
 `);
             return;
         case "list":
-            console.log(`${chalk.bold("Usage:")}
-  ${getPackageCommandUsage("list")}
-
-List installed packages from user and project settings.
-
-Options:
-  -a, --approve      Trust project-local files for this command
-  -na, --no-approve  Ignore project-local files for this command
+            console.log(`${chalk.bold("Usage:")}
+  ${getPackageCommandUsage("list")}
+
+List installed packages from user and project settings.
+
+Options:
+  -a, --approve      Trust project-local files for this command
+  -na, --no-approve  Ignore project-local files for this command
 `);
             return;
     }

package/dist/skills/improve-codebase/REFERENCE.md

@@ -1,78 +1,78 @@
-# Reference
-
-## Dependency Categories
-
-When assessing a candidate for deepening, classify its dependencies:
-
-### 1. In-process
-
-Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
-
-### 2. Local-substitutable
-
-Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
-
-### 3. Remote but owned (Ports & Adapters)
-
-Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
-
-Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
-
-### 4. True external (Mock)
-
-Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
-
-## Testing Strategy
-
-The core principle: **replace, don't layer.**
-
-- Old unit tests on shallow modules are waste once boundary tests exist — delete them
-- Write new tests at the deepened module's interface boundary
-- Tests assert on observable outcomes through the public interface, not internal state
-- Tests should survive internal refactors — they describe behavior, not implementation
-
-## Issue Template
-
-<issue-template>
-
-## Problem
-
-Describe the architectural friction:
-
-- Which modules are shallow and tightly coupled
-- What integration risk exists in the seams between them
-- Why this makes the codebase harder to navigate and maintain
-
-## Proposed Interface
-
-The chosen interface design:
-
-- Interface signature (types, methods, params)
-- Usage example showing how callers use it
-- What complexity it hides internally
-
-## Dependency Strategy
-
-Which category applies and how dependencies are handled:
-
-- **In-process**: merged directly
-- **Local-substitutable**: tested with [specific stand-in]
-- **Ports & adapters**: port definition, production adapter, test adapter
-- **Mock**: mock boundary for external services
-
-## Testing Strategy
-
-- **New boundary tests to write**: describe the behaviors to verify at the interface
-- **Old tests to delete**: list the shallow module tests that become redundant
-- **Test environment needs**: any local stand-ins or adapters required
-
-## Implementation Recommendations
-
-Durable architectural guidance that is NOT coupled to current file paths:
-
-- What the module should own (responsibilities)
-- What it should hide (implementation details)
-- What it should expose (the interface contract)
-- How callers should migrate to the new interface
-
-</issue-template>
+# Reference
+
+## Dependency Categories
+
+When assessing a candidate for deepening, classify its dependencies:
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — just merge the modules and test directly.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (e.g., PGLite for Postgres, in-memory filesystem). Deepenable if the test substitute exists. The deepened module is tested with the local stand-in running in the test suite.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a port (interface) at the module boundary. The deep module owns the logic; the transport is injected. Tests use an in-memory adapter. Production uses the real HTTP/gRPC/queue adapter.
+
+Recommendation shape: "Define a shared interface (port), implement an HTTP adapter for production and an in-memory adapter for testing, so the logic can be tested as one deep module even though it's deployed across a network boundary."
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. Mock at the boundary. The deepened module takes the external dependency as an injected port, and tests provide a mock implementation.
+
+## Testing Strategy
+
+The core principle: **replace, don't layer.**
+
+- Old unit tests on shallow modules are waste once boundary tests exist — delete them
+- Write new tests at the deepened module's interface boundary
+- Tests assert on observable outcomes through the public interface, not internal state
+- Tests should survive internal refactors — they describe behavior, not implementation
+
+## Issue Template
+
+<issue-template>
+
+## Problem
+
+Describe the architectural friction:
+
+- Which modules are shallow and tightly coupled
+- What integration risk exists in the seams between them
+- Why this makes the codebase harder to navigate and maintain
+
+## Proposed Interface
+
+The chosen interface design:
+
+- Interface signature (types, methods, params)
+- Usage example showing how callers use it
+- What complexity it hides internally
+
+## Dependency Strategy
+
+Which category applies and how dependencies are handled:
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Strategy
+
+- **New boundary tests to write**: describe the behaviors to verify at the interface
+- **Old tests to delete**: list the shallow module tests that become redundant
+- **Test environment needs**: any local stand-ins or adapters required
+
+## Implementation Recommendations
+
+Durable architectural guidance that is NOT coupled to current file paths:
+
+- What the module should own (responsibilities)
+- What it should hide (implementation details)
+- What it should expose (the interface contract)
+- How callers should migrate to the new interface
+
+</issue-template>