pi-usereq 0.11.0 → 0.13.0

package/src/core/extension-status.ts

@@ -14,6 +14,7 @@ import type {
   ThemeColor,
 } from "@mariozechner/pi-coding-agent";
 import type { UseReqConfig } from "./config.js";
+import type { PiNotifySoundLevel } from "./pi-notify.js";
 import type { PromptCommandExecutionPlan } from "./prompt-command-runtime.js";
 import {
   restorePersistedPromptCommandRuntimeStateForSession,
@@ -111,7 +112,7 @@ export type PiUsereqWorkflowState = "idle" | "checking" | "running" | "merging"
 
 /**
  * @brief Stores the mutable runtime facts displayed by the status bar.
- * @details Persists the prompt-orchestration workflow state, the latest context-usage snapshot, the active run start timestamp, the most recent normally completed run duration, the accumulated duration of all normally completed runs, and prompt-request metadata carried from command dispatch into the next runtime execution. Runtime state is mutated in-place by controller helpers. Compile-time only and introduces no runtime cost.
+ * @details Persists the prompt-orchestration workflow state, the latest context-usage snapshot, the active run start timestamp, the most recent normally completed run duration, the accumulated duration of all normally completed runs, the in-memory runtime sound level, and prompt-request metadata carried from command dispatch into the next runtime execution. Runtime state is mutated in-place by controller helpers. Compile-time only and introduces no runtime cost.
  */
 export interface PiUsereqStatusState {
   workflowState: PiUsereqWorkflowState;
@@ -119,6 +120,7 @@ export interface PiUsereqStatusState {
   runStartTimeMs: number | undefined;
   lastRunDurationMs: number | undefined;
   totalRunDurationMs: number | undefined;
+  runtimeSoundLevel: PiNotifySoundLevel | undefined;
   pendingPromptRequest: PiUsereqPromptRequest | undefined;
   activePromptRequest: PiUsereqPromptRequest | undefined;
 }
@@ -403,7 +405,7 @@ function resolveContextUsageIconText(
 
 /**
  * @brief Formats one icon-based context-usage gauge.
- * @details Renders the documented gauge icon with theme `error` for `>=90%`, enables terminal blink only for `>=100%`, and otherwise leaves the gauge in the default terminal color. Runtime is O(1). No external state is mutated.
+ * @details Renders the documented gauge icon with the same non-error status-value theme token used by `status` below `90%`, switches to theme `error` for `>=90%`, and enables terminal blink only for `>=100%`. Runtime is O(1). No external state is mutated.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
  * @return {string} Rendered fixed-width gauge icon.
@@ -420,7 +422,7 @@ function formatContextUsageBar(
   if (percent >= 90) {
     return theme.colorize("error", "▕█▏");
   }
-  return resolveContextUsageIconText(contextUsage);
+  return theme.value(resolveContextUsageIconText(contextUsage));
 }
 
 /**
@@ -548,9 +550,24 @@ function didAgentEndAbort(messages: AgentEndEvent["messages"]): boolean {
   );
 }
 
+/**
+ * @brief Resolves the active runtime sound level used by status and notify flows.
+ * @details Prefers the mutable runtime sound state, then falls back to the cached persisted boot value, and finally defaults to `none` before `session_start` loads configuration. Runtime is O(1). No external state is mutated.
+ * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
+ * @param[in] config {UseReqConfig | undefined} Cached project configuration.
+ * @return {PiNotifySoundLevel} Active runtime sound level.
+ * @satisfies REQ-180, REQ-285
+ */
+function resolvePiUsereqRuntimeSoundLevel(
+  state: PiUsereqStatusState,
+  config: UseReqConfig | undefined,
+): PiNotifySoundLevel {
+  return state.runtimeSoundLevel ?? config?.["notify-sound"] ?? "none";
+}
+
 /**
  * @brief Builds the full single-line pi-usereq status-bar payload.
- * @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, and the documented icon-based context gauge. Runtime is O(1). No external state is mutated.
+ * @details Renders status, branch, context, elapsed, and sound fields in the canonical order with dim bullet separators, workflow-state highlighting, the documented icon-based context gauge, and the active runtime sound level instead of the persisted boot value. Runtime is O(1). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] theme {StatusThemeAdapter} Normalized status theme.
  * @param[in] state {PiUsereqStatusState} Mutable status state snapshot.
@@ -567,7 +584,7 @@ function buildPiUsereqStatusText(
   nowMs: number,
 ): string {
   const elapsedText = formatElapsedStatusValue(state, nowMs);
-  const soundText = config["notify-sound"];
+  const soundText = resolvePiUsereqRuntimeSoundLevel(state, config);
   return [
     formatRenderedStatusField(
       theme,
@@ -630,7 +647,7 @@ function syncPiUsereqStatusTicker(
 
 /**
  * @brief Creates an empty pi-usereq status controller.
- * @details Initializes the mutable status snapshot, including empty prompt-request tracking, and starts with no config, no context, and no live ticker. Runtime is O(1). No external state is mutated.
+ * @details Initializes the mutable status snapshot, including empty prompt-request tracking and an unset runtime sound level that later loads from persisted config during `session_start`, and starts with no config, no context, and no live ticker. Runtime is O(1). No external state is mutated.
  * @return {PiUsereqStatusController} New status controller.
  * @satisfies DES-010
  */
@@ -644,6 +661,7 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
       runStartTimeMs: undefined,
       lastRunDurationMs: undefined,
       totalRunDurationMs: undefined,
+      runtimeSoundLevel: undefined,
       pendingPromptRequest: undefined,
       activePromptRequest: undefined,
     },
@@ -654,8 +672,9 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
 /**
  * @brief Stores the effective project configuration used by status rendering.
  * @details Replaces the controller's cached configuration so later status
- * renders reuse the latest docs, tests, source-path, and pi-notify values
- * without reading from disk on every event. Runtime is O(1). Side effect:
+ * renders reuse the latest docs, tests, source-path, and persisted pi-notify
+ * values without reading from disk on every event, while leaving the active
+ * runtime sound level in `controller.state`. Runtime is O(1). Side effect:
  * mutates `controller.config`.
  * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] config {UseReqConfig} Effective project configuration.
@@ -668,13 +687,47 @@ export function setPiUsereqStatusConfig(
   controller.config = config;
 }
 
+/**
+ * @brief Returns the active runtime sound level tracked by the status controller.
+ * @details Exposes the in-memory runtime sound state so shortcut handlers and prompt-end notification dispatch can stay decoupled from the persisted boot value stored in global configuration. Runtime is O(1). No external state is mutated.
+ * @param[in] controller {PiUsereqStatusController} Mutable status controller.
+ * @return {PiNotifySoundLevel} Active runtime sound level.
+ * @satisfies REQ-180, REQ-285
+ */
+export function getPiUsereqRuntimeSoundLevel(
+  controller: PiUsereqStatusController,
+): PiNotifySoundLevel {
+  return resolvePiUsereqRuntimeSoundLevel(controller.state, controller.config);
+}
+
+/**
+ * @brief Stores one new runtime sound level and refreshes the status bar.
+ * @details Mutates only the in-memory runtime sound state so shortcut-driven sound changes do not update persisted local or global configuration, then re-renders the footer when an active extension context is available. Runtime is O(1). Side effect: mutates `controller.state.runtimeSoundLevel` and may update `ctx.ui` status.
+ * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
+ * @param[in] runtimeSoundLevel {PiNotifySoundLevel} Next active runtime sound level.
+ * @param[in] ctx {ExtensionContext | undefined} Optional active extension context.
+ * @return {void} No return value.
+ * @satisfies REQ-180, REQ-286, REQ-287
+ */
+export function setPiUsereqRuntimeSoundLevel(
+  controller: PiUsereqStatusController,
+  runtimeSoundLevel: PiNotifySoundLevel,
+  ctx?: ExtensionContext,
+): void {
+  controller.state.runtimeSoundLevel = runtimeSoundLevel;
+  const renderContext = ctx ?? controller.latestContext;
+  if (renderContext) {
+    renderPiUsereqStatus(controller, renderContext);
+  }
+}
+
 /**
  * @brief Renders the current pi-usereq status bar into the active UI context.
- * @details Updates the controller's latest context pointer and writes the single-line status text only when configuration is available, including the active branch field and documented icon-based context gauge. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `ctx.ui` status when the context is still active.
+ * @details Updates the controller's latest context pointer, refreshes the live `getContextUsage()` snapshot for direct render call sites that do not pass through `updateExtensionStatus(...)`, and writes the single-line status text only when configuration is available, including the active branch field, documented icon-based context gauge, and active runtime sound level. When pi has already invalidated the supplied context after session replacement or reload, the helper clears the stale cached context and returns without surfacing the stale-instance exception. Runtime is O(1) plus git execution for branch refresh. Side effect: mutates `controller.state.contextUsage` and `ctx.ui` status when the context is still active.
  * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {void} No return value.
- * @satisfies REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
+ * @satisfies REQ-118, REQ-119, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-159, REQ-180, REQ-233, REQ-280, REQ-283, REQ-284
  */
 export function renderPiUsereqStatus(
   controller: PiUsereqStatusController,
@@ -685,6 +738,7 @@ export function renderPiUsereqStatus(
     return;
   }
   try {
+    refreshContextUsage(controller.state, ctx);
     const theme = createStatusThemeAdapter(ctx.ui.theme as RawStatusTheme);
     const branchName = resolveStatusBranchValue(ctx);
     ctx.ui.setStatus(
@@ -732,13 +786,13 @@ export function setPiUsereqWorkflowState(
 
 /**
  * @brief Updates mutable status state for one intercepted lifecycle hook.
- * @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
+ * @details Refreshes stored context usage on every hook, resets or restores persisted elapsed counters during `session_start`, loads the active runtime sound level from persisted config during `session_start`, restores persisted prompt-command metadata when the active session matches a forked execution session, resynchronizes that metadata on later lifecycle hooks so post-switch workflow transitions performed by the initiating command handler become visible to the replacement-session runtime, resets workflow state to `idle` for documented session-start reasons, starts run timing on `agent_start`, promotes pending prompt-request metadata into the active run, captures non-aborted run duration on `agent_end`, accumulates successful runtime into `Σ`, preserves in-memory prompt-command state plus process-scoped persistence across switch-triggered `session_shutdown`, tolerates stale post-replacement render contexts, synchronizes the live ticker, and re-renders the status bar when configuration is available. Runtime is O(n) in `agent_end` message count and otherwise O(1). Side effects include in-memory state mutation, interval scheduling, process-scoped persistence mutation, and footer-status updates.
  * @param[in,out] controller {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded from the wrapper.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {void} No return value.
- * @satisfies REQ-009, REQ-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169, REQ-217, REQ-221, REQ-278, REQ-279, REQ-280
+ * @satisfies REQ-009, REQ-117, REQ-118, REQ-119, REQ-123, REQ-124, REQ-125, REQ-159, REQ-169, REQ-217, REQ-221, REQ-278, REQ-279, REQ-280, REQ-285
  */
 export function updateExtensionStatus(
   controller: PiUsereqStatusController,
@@ -757,6 +811,9 @@ export function updateExtensionStatus(
     } else {
       restorePersistedElapsedState(controller.state);
     }
+    controller.state.runtimeSoundLevel = controller.config?.["notify-sound"]
+      ?? controller.state.runtimeSoundLevel
+      ?? "none";
     const shouldResetWorkflowState = shouldResetWorkflowStateOnSessionStart(event);
     if (shouldResetWorkflowState) {
       controller.state.workflowState = "idle";

package/src/core/path-context.ts

@@ -11,11 +11,17 @@ import { fileURLToPath } from "node:url";
 import type { UseReqConfig } from "./config.js";
 
 /**
- * @brief Defines the per-project configuration file name.
- * @details The file lives directly under `base-path` and stores only persisted project configuration. Access complexity is O(1).
+ * @brief Defines the per-project local configuration file name.
+ * @details The file lives directly under `base-path` and stores only persisted project-scoped configuration. Access complexity is O(1).
  */
 export const PROJECT_CONFIG_FILENAME = ".pi-usereq.json";
 
+/**
+ * @brief Defines the home-relative global configuration file path.
+ * @details The path is resolved against the current user home directory and stores persisted cross-project configuration. Access complexity is O(1).
+ */
+export const GLOBAL_CONFIG_RELATIVE_PATH = ".config/pi-usereq/config.json";
+
 /**
  * @brief Defines the bundled resources directory name under the installation path.
  * @details The directory contains prompts, templates, and guidelines shipped with the installed extension payload. Access complexity is O(1).
@@ -155,15 +161,24 @@ export function normalizeRelativeDirContract(value: string): string {
 }
 
 /**
- * @brief Computes the absolute project config path for one base path.
+ * @brief Computes the absolute local project config path for one base path.
  * @details Appends `.pi-usereq.json` to the supplied base path using the canonical repository-local configuration layout. Runtime is O(1). No external state is mutated.
  * @param[in] basePath {string} Absolute or relative base path.
- * @return {string} Absolute config-file path.
+ * @return {string} Absolute local config-file path.
  */
 export function getConfigPath(basePath: string): string {
   return path.join(path.resolve(basePath), PROJECT_CONFIG_FILENAME);
 }
 
+/**
+ * @brief Computes the absolute global config path for the current user.
+ * @details Resolves `~/.config/pi-usereq/config.json` from the current user home directory without consulting project state. Runtime is O(1). No external state is mutated.
+ * @return {string} Absolute global config-file path.
+ */
+export function getGlobalConfigPath(): string {
+  return path.join(os.homedir(), GLOBAL_CONFIG_RELATIVE_PATH);
+}
+
 /**
  * @brief Tests whether one path is identical to or an ancestor of another path.
  * @details Resolves both inputs, computes a relative traversal from the candidate ancestor to the candidate child, and accepts only exact matches or descendant traversals that stay within the ancestor subtree. Runtime is O(p) in path length. No external state is mutated.

package/src/core/pi-notify.ts

@@ -110,7 +110,7 @@ export interface PiNotifyEventRequest {
 
 /**
  * @brief Describes the configuration fields consumed by pi-notify helpers.
- * @details Narrows the full project config to the persisted notify, sound, and Pushover fields used by status rendering, prompt-end routing, and shortcut toggles. Compile-time only and introduces no runtime cost.
+ * @details Narrows the full project config to the notify, sound, and Pushover fields used by status rendering and prompt-end routing. Callers may override `notify-sound` with the active runtime sound level before dispatch. Compile-time only and introduces no runtime cost.
  */
 export type PiNotifyConfigFields = Pick<
   UseReqConfig,
@@ -363,10 +363,10 @@ export function formatPiNotifyPushoverStatus(config: Pick<UseReqConfig, "notify-
 
 /**
  * @brief Cycles one sound level through the canonical shortcut order.
- * @details Advances persisted sound state in the exact order `none -> low -> mid -> high -> none`, enabling deterministic shortcut toggling and menu reuse. Runtime is O(1). No external state is mutated.
- * @param[in] currentLevel {PiNotifySoundLevel} Current persisted sound level.
- * @return {PiNotifySoundLevel} Next sound level in the cycle.
- * @satisfies REQ-134
+ * @details Advances the active runtime sound state in the exact order `none -> low -> mid -> high -> none`, enabling deterministic shortcut toggling without mutating persisted boot configuration. Runtime is O(1). No external state is mutated.
+ * @param[in] currentLevel {PiNotifySoundLevel} Current active runtime sound level.
+ * @return {PiNotifySoundLevel} Next runtime sound level in the cycle.
+ * @satisfies REQ-286
  */
 export function cyclePiNotifySoundLevel(currentLevel: PiNotifySoundLevel): PiNotifySoundLevel {
   const currentIndex = PI_NOTIFY_SOUND_LEVELS.indexOf(currentLevel);

package/src/core/pi-usereq-tools.ts

@@ -10,9 +10,10 @@
  */
 export const PI_USEREQ_CUSTOM_TOOL_NAMES = [
   "files-tokens",
-  "files-references",
+  "files-summarize",
   "files-compress",
   "files-search",
+  "summarize",
   "references",
   "compress",
   "search",
@@ -51,9 +52,10 @@ export const PI_USEREQ_STARTUP_TOOL_NAMES = [
  */
 export const PI_USEREQ_DEFAULT_ENABLED_TOOL_NAMES = [
   "files-tokens",
-  "files-references",
+  "files-summarize",
   "files-compress",
   "files-search",
+  "summarize",
   "references",
   "compress",
   "search",

package/src/core/prompt-command-catalog.ts

@@ -1,12 +1,12 @@
 /**
  * @file
- * @brief Declares the canonical bundled `req-*` prompt-command inventory.
- * @details Centralizes prompt-command names shared by extension registration, configuration normalization, debug-menu rendering, and prompt-runtime orchestration. The module is side-effect free. Lookup cost is O(1) per exported constant access.
+ * @brief Declares the canonical bundled prompt-backed `req-*` command inventory.
+ * @details Centralizes only prompt-template-backed command names shared by extension registration, configuration normalization, debug-menu rendering, and prompt-runtime orchestration. Specialized slash commands such as `req-references` and `req-reset` are registered outside this inventory. The module is side-effect free. Lookup cost is O(1) per exported constant access.
  */
 
 /**
- * @brief Lists bundled prompt-command names handled by the extension.
- * @details Provides the single source of truth for `req-*` prompt registration, required-document routing, debug-prompt inventory derivation, and prompt-command worktree orchestration. Access complexity is O(1).
+ * @brief Lists bundled prompt-backed command names handled by the extension.
+ * @details Provides the single source of truth for prompt-template-backed `req-*` registration, required-document routing, debug-prompt inventory derivation, and prompt-command worktree orchestration. Access complexity is O(1).
  */
 export const PROMPT_COMMAND_NAMES = [
   "analyze",
@@ -21,7 +21,6 @@ export const PROMPT_COMMAND_NAMES = [
   "readme",
   "recreate",
   "refactor",
-  "references",
   "renumber",
   "workflow",
   "write",

package/src/core/prompt-command-runtime.ts

@@ -1,7 +1,7 @@
 /**
  * @file
- * @brief Implements prompt-command preflight and worktree orchestration.
- * @details Centralizes `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, session-backed cwd switching plus verification, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success fast-forward merge finalization with restored-session transcript preservation, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, and filesystem reads and writes.
+ * @brief Implements bundled prompt-command preflight and worktree orchestration.
+ * @details Centralizes prompt-template-backed `req-<prompt>` repository validation, prompt-specific required-document checks, slash-command-owned worktree naming and lifecycle handling, reusable transcript-preservation plus session-restoration helpers, persisted replacement-session context reuse for non-command lifecycle handlers, matched-success stash-assisted fast-forward merge finalization, and command-side abort cleanup. Runtime is dominated by git subprocess execution plus bounded filesystem and session-file metadata checks. Side effects include active-session replacement, worktree creation and deletion, branch merges, stash-stack mutation, and filesystem reads and writes.
  */
 
 import fs from "node:fs";
@@ -19,10 +19,7 @@ import {
   logDebugPromptWorkflowEvent,
   type DebugWorkflowState,
 } from "./debug-runtime.js";
-import {
-  PROMPT_COMMAND_NAMES,
-  type PromptCommandName,
-} from "./prompt-command-catalog.js";
+import { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
   isSameOrAncestorPath,
   normalizeRelativeDirContract,
@@ -483,9 +480,9 @@ function readPromptSessionJsonLines(
  * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose original and execution session files must be synchronized.
  * @return {void} No return value.
  * @throws {ReqError} Throws when either session file is unreadable or when appended execution records are not persisted to the original session file.
- * @satisfies REQ-208
+ * @satisfies REQ-208, REQ-307
  */
-function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void {
+export function preservePromptCommandExecutionTranscript(plan: PromptCommandExecutionPlan): void {
   const normalizedOriginalSessionFile = path.resolve(plan.originalSessionFile);
   const normalizedExecutionSessionFile = path.resolve(plan.executionSessionFile);
   if (normalizedOriginalSessionFile === normalizedExecutionSessionFile) {
@@ -829,9 +826,6 @@ const PROMPT_REQUIRED_DOCS: Record<PromptCommandName, readonly PromptRequiredDoc
     { fileName: "WORKFLOW.md", promptCommand: "/req-workflow" },
     { fileName: "REFERENCES.md", promptCommand: "/req-references" },
   ],
-  references: [
-    { fileName: "REQUIREMENTS.md", promptCommand: "/req-write" },
-  ],
   renumber: [
     { fileName: "REQUIREMENTS.md", promptCommand: "/req-write" },
     { fileName: "WORKFLOW.md", promptCommand: "/req-workflow" },
@@ -855,6 +849,166 @@ function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync
   });
 }
 
+/**
+ * @brief Lists tracked `base-path` status rows that require stash-assisted merge handling.
+ * @details Executes `git status --porcelain`, retains only tracked rows whose index or worktree slot reports a change, and excludes untracked or ignored rows because the required `git stash` command does not preserve them. Runtime is dominated by one git subprocess plus O(n) parsing in status-line count. Side effects include process spawning.
+ * @param[in] basePath {string} Restored project base path.
+ * @return {string[]} Tracked status rows requiring stash-assisted merge handling.
+ * @throws {ReqError} Throws when git status cannot be read from `basePath`.
+ * @satisfies REQ-291
+ */
+function listPromptTrackedBasePathChanges(basePath: string): string[] {
+  const statusResult = runCapture(["git", "status", "--porcelain"], basePath);
+  if (statusResult.error || statusResult.status !== 0) {
+    throw new ReqError("ERROR: Unable to inspect base-path changes before merge.", 1);
+  }
+  return statusResult.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trimEnd())
+    .filter((line) => line !== "")
+    .filter((line) => {
+      const statusCode = line.slice(0, 2);
+      if (statusCode === "??" || statusCode === "!!") {
+        return false;
+      }
+      const indexStatus = statusCode[0] ?? " ";
+      const worktreeStatus = statusCode[1] ?? " ";
+      return indexStatus !== " " || worktreeStatus !== " ";
+    });
+}
+
+/**
+ * @brief Executes the successful-closure merge sequence from restored `base-path`.
+ * @details Detects tracked staged or unstaged `base-path` changes, wraps the existing fast-forward merge in `git stash` and `git stash pop` when required, preserves the direct merge path when no tracked changes exist, emits a warning-only result after successful local-change restoration, and writes one merge-finalization debug entry when enabled. Runtime is dominated by up to four git subprocesses plus O(n) status parsing. Side effects include stash-stack mutation, branch merge attempts, and optional debug-log writes.
+ * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan whose branch should be merged.
+ * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
+ * @return {{ mergeAttempted: boolean; mergeSucceeded: boolean; errorMessage?: string; warningMessage?: string }} Merge-attempt facts plus optional warning text.
+ * @satisfies REQ-208, REQ-245, REQ-291, REQ-292
+ */
+function finalizePromptCommandMerge(
+  plan: PromptCommandExecutionPlan,
+  debugOptions?: PromptCommandDebugOptions,
+): {
+  mergeAttempted: boolean;
+  mergeSucceeded: boolean;
+  errorMessage?: string;
+  warningMessage?: string;
+} {
+  const worktreeDir = plan.worktreeDir ?? plan.branchName;
+  const mergeLogInput = {
+    worktree_dir: worktreeDir,
+    branch_name: plan.branchName,
+  };
+  let trackedStatusLines: string[];
+  try {
+    trackedStatusLines = listPromptTrackedBasePathChanges(plan.basePath);
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (debugOptions) {
+      logDebugPromptEvent(
+        plan.basePath,
+        debugOptions.config,
+        debugOptions.workflowState,
+        plan.promptName,
+        "merge",
+        mergeLogInput,
+        {
+          success: false,
+          merge_attempted: false,
+          error: errorMessage,
+        },
+        true,
+      );
+    }
+    return {
+      mergeAttempted: false,
+      mergeSucceeded: false,
+      errorMessage,
+    };
+  }
+  const usedStash = trackedStatusLines.length > 0;
+  let stashStatus: number | null | undefined;
+  if (usedStash) {
+    const stashResult = runCapture(["git", "stash"], plan.basePath);
+    stashStatus = stashResult.status;
+    if (stashResult.error || stashResult.status !== 0) {
+      const errorMessage = `ERROR: Unable to stash base-path changes before merge for worktree ${worktreeDir}.`;
+      if (debugOptions) {
+        logDebugPromptEvent(
+          plan.basePath,
+          debugOptions.config,
+          debugOptions.workflowState,
+          plan.promptName,
+          "merge",
+          {
+            ...mergeLogInput,
+            used_stash: true,
+            tracked_change_count: trackedStatusLines.length,
+          },
+          {
+            success: false,
+            merge_attempted: false,
+            error: errorMessage,
+            stash_status: stashStatus,
+          },
+          true,
+        );
+      }
+      return {
+        mergeAttempted: false,
+        mergeSucceeded: false,
+        errorMessage,
+      };
+    }
+  }
+  const mergeResult = runCapture(
+    ["git", "merge", "--ff-only", plan.branchName],
+    plan.basePath,
+  );
+  const mergeSucceeded = !mergeResult.error && mergeResult.status === 0;
+  const errorMessage = mergeSucceeded
+    ? undefined
+    : `ERROR: Fast-forward merge failed for worktree ${worktreeDir}.`;
+  let stashPopStatus: number | null | undefined;
+  let warningMessage: string | undefined;
+  if (usedStash) {
+    const stashPopResult = runCapture(["git", "stash", "pop"], plan.basePath);
+    stashPopStatus = stashPopResult.status;
+    if (mergeSucceeded) {
+      warningMessage = "WARNING: Restored base-path changes after merge; base-path is not clean.";
+    }
+  }
+  if (debugOptions) {
+    logDebugPromptEvent(
+      plan.basePath,
+      debugOptions.config,
+      debugOptions.workflowState,
+      plan.promptName,
+      "merge",
+      {
+        ...mergeLogInput,
+        used_stash: usedStash,
+        tracked_change_count: trackedStatusLines.length,
+      },
+      {
+        success: mergeSucceeded,
+        merge_attempted: true,
+        error: errorMessage,
+        warning: warningMessage,
+        stash_status: stashStatus,
+        stash_pop_status: stashPopStatus,
+      },
+      !mergeSucceeded,
+    );
+  }
+  return {
+    mergeAttempted: true,
+    mergeSucceeded,
+    errorMessage,
+    warningMessage,
+  };
+}
+
 /**
  * @brief Stores or clears the prompt-command post-create test hook.
  * @details Enables deterministic simulation of post-create worktree verification failures without altering production control flow. Runtime is O(1). Side effect: mutates module-local test state.
@@ -950,15 +1104,15 @@ function throwPromptGitStatusError(): never {
 }
 
 /**
- * @brief Runs prompt-command-owned git validation and returns the runtime git root.
- * @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
+ * @brief Runs slash-command-owned git validation and returns the runtime git root.
+ * @details Validates work-tree membership, porcelain cleanliness, and symbolic or detached `HEAD` presence for bundled prompt commands and `req-references` without invoking extension custom-tool executors. Runtime is dominated by git subprocess execution. Side effects include process spawning.
  * @param[in] projectBase {string} Absolute current project base.
  * @param[in] config {UseReqConfig | undefined} Optional effective project configuration used to ignore extension-owned debug-log artifacts.
  * @return {string} Absolute runtime git root.
  * @throws {ReqError} Throws the canonical prompt-command git-preflight error on any validation failure.
  * @satisfies REQ-200, REQ-220
  */
-function validatePromptGitState(projectBase: string, config?: UseReqConfig): string {
+export function validatePromptGitState(projectBase: string, config?: UseReqConfig): string {
   const gitPath = resolveRuntimeGitPath(projectBase);
   if (!gitPath) {
     throwPromptGitStatusError();
@@ -1280,9 +1434,9 @@ function createPromptWorktree(
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
  * @return {void} No return value.
  * @throws {ReqError} Throws when cleanup cannot remove the worktree and branch fully.
- * @satisfies REQ-208, REQ-220, REQ-245
+ * @satisfies REQ-208, REQ-220, REQ-245, REQ-309
  */
-function deletePromptWorktree(
+export function deletePromptWorktree(
   basePath: string,
   worktreeDir: string,
   worktreeRootPath: string,
@@ -1691,12 +1845,12 @@ export async function abortPromptCommandExecution(
 
 /**
  * @brief Finalizes one matched successful worktree-backed prompt execution.
- * @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, fast-forward merges the successful worktree branch from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Re-verifies persisted execution-session metadata plus worktree artifacts, copies any execution-session transcript records missing from the original session file, restores the original session-backed `base-path`, executes the stash-assisted fast-forward merge sequence from `base-path`, deletes the worktree after merge success, and preserves the restored base session across closure failures. Closure intentionally treats `base-path` restoration as authoritative even when pi CLI has already started end-of-session session replacement or other housekeeping that moved the live runtime away from `worktree-path`. Runtime is dominated by session switching plus git subprocess execution. Side effects include session-file appends, active-session replacement, branch merges, stash-stack mutation, worktree deletion, and optional debug-log writes.
  * @param[in] plan {PromptCommandExecutionPlan} Prompt execution plan.
  * @param[in] ctx {PromptCommandSessionContext | undefined} Optional prompt-command context.
  * @param[in] debugOptions {PromptCommandDebugOptions | undefined} Optional prompt debug logging context.
- * @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
- * @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282
+ * @return {Promise<{ mergeAttempted: boolean; mergeSucceeded: boolean; cleanupSucceeded: boolean; errorMessage?: string; warningMessage?: string; activeContext?: PromptCommandSessionContext }>} Finalization facts plus the last valid active prompt-command context.
+ * @satisfies REQ-208, REQ-209, REQ-220, REQ-245, REQ-282, REQ-291, REQ-292
  */
 export async function finalizePromptCommandExecution(
   plan: PromptCommandExecutionPlan,
@@ -1707,6 +1861,7 @@ export async function finalizePromptCommandExecution(
   mergeSucceeded: boolean;
   cleanupSucceeded: boolean;
   errorMessage?: string;
+  warningMessage?: string;
   activeContext?: PromptCommandSessionContext;
 }> {
   let activeContext = ctx;
@@ -1749,32 +1904,14 @@ export async function finalizePromptCommandExecution(
       activeContext,
     };
   }
-  const mergeResult = runCapture(
-    ["git", "merge", "--ff-only", plan.branchName],
-    plan.basePath,
-  );
-  const mergeSucceeded = !mergeResult.error && mergeResult.status === 0;
-  const errorMessage = mergeSucceeded
-    ? undefined
-    : `ERROR: Fast-forward merge failed for worktree ${plan.worktreeDir}.`;
-  if (debugOptions) {
-    logDebugPromptEvent(
-      plan.basePath,
-      debugOptions.config,
-      debugOptions.workflowState,
-      plan.promptName,
-      "merge",
-      { worktree_dir: plan.worktreeDir, branch_name: plan.branchName },
-      { success: mergeSucceeded, error: errorMessage },
-      !mergeSucceeded,
-    );
-  }
-  if (!mergeSucceeded) {
+  const mergeFinalization = finalizePromptCommandMerge(plan, debugOptions);
+  if (!mergeFinalization.mergeSucceeded) {
     return {
-      mergeAttempted: true,
+      mergeAttempted: mergeFinalization.mergeAttempted,
       mergeSucceeded: false,
       cleanupSucceeded: true,
-      errorMessage,
+      errorMessage: mergeFinalization.errorMessage,
+      warningMessage: mergeFinalization.warningMessage,
       activeContext,
     };
   }
@@ -1788,17 +1925,19 @@ export async function finalizePromptCommandExecution(
     );
   } catch {
     return {
-      mergeAttempted: true,
+      mergeAttempted: mergeFinalization.mergeAttempted,
       mergeSucceeded: true,
       cleanupSucceeded: false,
       errorMessage: `ERROR: Unable to remove worktree or branch ${plan.worktreeDir}.`,
+      warningMessage: mergeFinalization.warningMessage,
       activeContext,
     };
   }
   return {
-    mergeAttempted: true,
+    mergeAttempted: mergeFinalization.mergeAttempted,
     mergeSucceeded: true,
     cleanupSucceeded: true,
+    warningMessage: mergeFinalization.warningMessage,
     activeContext,
   };
 }

package/src/core/prompts.ts

@@ -22,14 +22,12 @@ import { readBundledInstruction, readBundledPrompt } from "./resources.js";
 const TOOL_REFERENCE_REPLACEMENTS: Array<[RegExp, string]> = [
   [/`req --find`/g, "`search` tool"],
   [/`req --files-find`/g, "`files-search` tool"],
-  [/`req --references`/g, "`references` tool"],
   [/`req --compress`/g, "`compress` tool"],
   [/`req --tokens`/g, "`tokens` tool"],
   [/`req --static-check`/g, "`static-check` tool"],
   [/`req --files-static-check`/g, "`files-static-check` tool"],
   [/\breq --find\b/g, "search tool"],
   [/\breq --files-find\b/g, "files-search tool"],
-  [/\breq --references\b/g, "references tool"],
   [/\breq --compress\b/g, "compress tool"],
   [/\breq --tokens\b/g, "tokens tool"],
   [/\breq --static-check\b/g, "static-check tool"],