pi-usereq 0.11.0 → 0.12.0

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.11.0";
+export const VERSION = "0.12.0";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -91,6 +91,18 @@ import {
   restorePromptCommandExecution,
   type PromptCommandExecutionPlan,
 } from "./core/prompt-command-runtime.js";
+import {
+  REQ_REFERENCES_COMMAND_DESCRIPTION,
+  executeReqReferencesCommandExecution,
+  prepareReqReferencesCommandExecution,
+} from "./core/req-references-command.js";
+import {
+  REQ_RESET_COMMAND_DESCRIPTION,
+  executeReqResetCommandExecution,
+  prepareReqResetCommandExecution,
+  type ReqResetCommandExecutionResult,
+  type ReqResetCommandPlan,
+} from "./core/req-reset-command.js";
 import {
   DEBUG_PROMPT_NAMES,
   DEBUG_WORKFLOW_STATES,
@@ -114,6 +126,7 @@ import {
 import { PROMPT_COMMAND_NAMES } from "./core/prompt-command-catalog.js";
 import { resolveRuntimeGitPath } from "./core/runtime-project-paths.js";
 import {
+  clearPersistedPromptCommandRuntimeState,
   readPersistedPromptCommandRuntimeState,
   writePersistedPromptCommandRuntimeState,
 } from "./core/prompt-command-state.js";
@@ -123,8 +136,10 @@ import {
   PI_USEREQ_STATUS_HOOK_NAMES,
   createPiUsereqStatusController,
   disposePiUsereqStatusController,
+  getPiUsereqRuntimeSoundLevel,
   isStaleExtensionContextError,
   renderPiUsereqStatus,
+  setPiUsereqRuntimeSoundLevel,
   setPiUsereqStatusConfig,
   setPiUsereqWorkflowState,
   shouldPreservePromptCommandStateOnShutdown,
@@ -135,13 +150,14 @@ import {
 import {
   runCompress,
   runFilesCompress,
-  runFilesReferences,
   runFilesSearch,
   runFilesStaticCheck,
+  runFilesSummarize,
   runFilesTokens,
   runProjectStaticCheck,
   runReferences,
   runSearch,
+  runSummarize,
   runTokens,
   type ToolResult,
 } from "./core/tool-runner.js";
@@ -686,6 +702,44 @@ function executeMonolithicTool(operation: () => ToolResult): ReturnType<typeof b
   }
 }
 
+/**
+ * @brief Executes one CLI-style runner for a status-only agent tool.
+ * @details Reuses the standalone tool-runner contract, preserves `content[0].text` as the status-only `success` or `error: <diagnostic>` payload, and strips success-path `stdout_lines` so `details.execution` stays limited to the numeric code plus optional residual stderr diagnostics. Runtime is dominated by the delegated runner. Side effects depend on the selected tool.
+ * @param[in] operation {() => ToolResult} Runner callback.
+ * @return {ReturnType<typeof buildMonolithicToolExecuteResult>} Status-only tool execute result.
+ * @satisfies REQ-294, REQ-295, REQ-296
+ */
+function executeStatusTool(operation: () => ToolResult): ReturnType<typeof buildMonolithicToolExecuteResult> {
+  const normalizeExecution = (
+    payload: ReturnType<typeof buildMonolithicToolExecuteResult>,
+  ): ReturnType<typeof buildMonolithicToolExecuteResult> => {
+    const execution = payload.details.execution;
+    return {
+      content: payload.content,
+      details: {
+        execution: {
+          code: execution.code,
+          ...(Array.isArray(execution.stderr_lines) && execution.stderr_lines.length > 0
+            ? { stderr_lines: execution.stderr_lines }
+            : {}),
+        },
+      },
+    };
+  };
+
+  try {
+    return normalizeExecution(buildMonolithicToolExecuteResult(operation()));
+  } catch (error) {
+    const failure = normalizeToolFailure(error);
+    const diagnostic = failure.stderr.trim().replace(/^(Error|error):\s*/u, "") || "unknown failure";
+    return normalizeExecution(buildMonolithicToolExecuteResult({
+      stdout: "",
+      stderr: `error: ${diagnostic}`,
+      code: failure.code,
+    }));
+  }
+}
+
 /**
  * @brief Starts delivery of one rendered prompt into the current active session.
  * @details Prefers the replacement-session `sendUserMessage(...)` helper exposed by `withSession(...)` callbacks after session replacement so post-switch prompt delivery never reuses stale pre-switch session-bound extension objects. Returns the underlying delivery promise without awaiting it so callers can record the `running` workflow transition as soon as prompt handoff is accepted instead of waiting for the full agent turn to complete on runtimes whose async replacement-session helpers resolve only after `agent_end`. When pi later invalidates that replacement-session context during successful prompt-end restoration, the helper suppresses the documented stale-extension-context rejection because the prompt was already accepted and late rethrow would surface a false orchestration failure. Falls back to `pi.sendUserMessage(...)` only for non-replacement flows or runtimes that do not expose replacement-session helpers. Runtime is O(n) in prompt length. Side effects are limited to user-message delivery.
@@ -838,7 +892,7 @@ function transitionPromptWorkflowState(
 
 /**
  * @brief Resolves the runtime slash-command description for one bundled prompt.
- * @details Reads the bundled prompt front matter, extracts its normalized `description` field, and falls back to the historical generated label when the prompt metadata omits a description. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads.
+ * @details Reads the bundled prompt markdown, extracts the first `# ` heading payload, and falls back to the historical generated label when the prompt omits a level-one heading. Runtime is O(n) in prompt length. Side effects are limited to filesystem reads.
  * @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName} Bundled prompt name.
  * @return {string} Runtime command description.
  */
@@ -889,6 +943,38 @@ function notifyContextSafely(
   }
 }
 
+/**
+ * @brief Rejects one non-`idle` req-command invocation and records the workflow error state.
+ * @details Builds a deterministic busy-state diagnostic from the current workflow state, transitions the shared workflow state to `error`, preserves any pending or active prompt execution metadata for later closure handling, emits an error notification, and throws `ReqError`. Bundled prompt commands reuse `transitionPromptWorkflowState(...)` when cached configuration is available so prompt debug logging captures the actual state transition; specialized non-prompt commands fall back to direct status mutation. Runtime is O(1). Side effects include workflow-state mutation, status-bar rendering, optional debug-log writes, and user notification delivery.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+ * @param[in] ctx {ExtensionContext | ExtensionCommandContext} Active extension context.
+ * @param[in] promptName {import("./core/prompt-command-catalog.js").PromptCommandName | undefined} Optional bundled prompt name used for prompt debug logging.
+ * @return {never} This helper always throws a deterministic `ReqError`.
+ * @throws {ReqError} Always throws because non-`idle` req commands are rejected.
+ * @satisfies REQ-224
+ */
+function rejectNonIdleReqCommand(
+  statusController: PiUsereqStatusController,
+  ctx: ExtensionContext | ExtensionCommandContext,
+  promptName?: import("./core/prompt-command-catalog.js").PromptCommandName,
+): never {
+  const message = `ERROR: Prompt workflow state is ${statusController.state.workflowState}, expected idle.`;
+  if (promptName !== undefined && statusController.config !== undefined) {
+    transitionPromptWorkflowState(
+      statusController,
+      ctx,
+      resolveDebugProjectBase(ctx.cwd, statusController),
+      statusController.config,
+      promptName,
+      "error",
+    );
+  } else {
+    setPiUsereqWorkflowState(statusController, "error", ctx);
+  }
+  notifyContextSafely(ctx, message, "error");
+  throw new ReqError(message, 1);
+}
+
 /**
  * @brief Returns the configurable active-tool inventory visible to the extension.
  * @details Filters runtime tools against the canonical configurable-tool set, keeps only builtin-backed embedded tools, and orders the result by the documented custom/files/embedded/default-disabled grouping. Runtime is O(t log t). No external state is mutated.
@@ -947,14 +1033,14 @@ function applyConfiguredPiUsereqTools(pi: ExtensionAPI, config: UseReqConfig): v
 
 /**
  * @brief Handles one intercepted pi lifecycle hook for pi-usereq status updates.
- * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, merges and deletes the worktree only for matched successful completions, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
+ * @details Applies session-start-specific resource validation, project-config refresh, startup-tool enablement, and selected debug-tool logging before forwarding the originating hook name and payload into the shared `updateExtensionStatus(...)` pipeline. Before `agent_start`, re-verifies any prepared prompt execution session switch. On `agent_end`, dispatches configured command-notify, sound, and prompt-specific Pushover effects, logs dedicated workflow-closure diagnostics, restores the original session-backed `base-path` for every matched worktree-backed completion by reusing persisted replacement-session command contexts when event contexts omit `switchSession()`, executes the stash-assisted merge-and-delete finalization path for every matched successful worktree-backed completion even when a later busy-command rejection already moved workflow state to `error`, emits a warning-only notification when restored `base-path` changes are reapplied after merge, tolerates stale replacement-session notification contexts after session replacement, retains the worktree plus notifies closure failure for interrupted or failed outcomes, logs selected prompt workflow transitions, and transitions workflow state through `merging`, `error`, and `idle` as required. On `session_shutdown`, captures pre-update prompt snapshots so workflow-shutdown diagnostics and same-runtime command continuation preserve the active prompt workflow state across switch-triggered rebinding, then disposes the shared controller. Runtime is dominated by configuration loading during `session_start` and git finalization during matched successful `agent_end` handling; all other hooks are O(1). Side effects include resource checks, active-tool mutation, active-session replacement, status updates, live-ticker disposal on shutdown, optional child-process spawning, outbound HTTPS requests, branch merges, worktree deletion, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @param[in] hookName {PiUsereqStatusHookName} Intercepted hook name.
  * @param[in] event {unknown} Hook payload forwarded by pi.
  * @param[in] ctx {ExtensionContext} Active extension context.
  * @return {Promise<void>} Promise resolved when hook processing completes.
- * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280
+ * @satisfies REQ-117, REQ-118, REQ-119, REQ-131, REQ-132, REQ-133, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-176, REQ-178, REQ-184, REQ-185, REQ-186, REQ-187, REQ-208, REQ-209, REQ-221, REQ-228, REQ-229, REQ-230, REQ-244, REQ-245, REQ-246, REQ-247, REQ-276, REQ-277, REQ-278, REQ-279, REQ-280, REQ-291, REQ-292
  */
 async function handleExtensionStatusEvent(
   pi: ExtensionAPI,
@@ -1025,7 +1111,10 @@ async function handleExtensionStatusEvent(
   if (hookName === "agent_end") {
     if (statusController.config) {
       runPiNotifyEffects(
-        statusController.config,
+        {
+          ...statusController.config,
+          "notify-sound": getPiUsereqRuntimeSoundLevel(statusController),
+        },
         event as { messages: AgentEndEvent["messages"] },
         notifyRequest,
       );
@@ -1041,7 +1130,6 @@ async function handleExtensionStatusEvent(
         ? `ERROR: Prompt closure retained worktree ${activePromptRequest.worktreeDir} after ${outcome} outcome.`
         : undefined;
       const shouldFinalizeMatchedSuccess = outcome === "completed"
-        && statusController.state.workflowState === "running"
         && activePromptRequest.worktreeDir !== undefined;
       if (debugConfig) {
         logPromptWorkflowEvent(
@@ -1080,6 +1168,7 @@ async function handleExtensionStatusEvent(
             mergeSucceeded: boolean;
             cleanupSucceeded: boolean;
             errorMessage?: string;
+            warningMessage?: string;
             activeContext?: unknown;
           }
           | undefined;
@@ -1134,6 +1223,14 @@ async function handleExtensionStatusEvent(
           }
           notifyContextSafely(promptContext, finalization.errorMessage, "error");
         }
+        if (
+          finalization.warningMessage
+          && finalization.cleanupSucceeded
+          && finalization.mergeSucceeded
+          && !finalization.errorMessage
+        ) {
+          notifyContextSafely(promptContext, finalization.warningMessage, "info");
+        }
       } else {
         try {
           promptContext = (await restorePromptCommandExecution(
@@ -1383,6 +1480,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
       id: "debug-enabled",
       label: "Debug",
       value: config.DEBUG_ENABLED,
+      values: ["enable", "disable"],
       description: "Enable or disable all debug logging behavior and unlock the remaining Debug rows.",
     },
     buildDebugMenuChoice(
@@ -1408,6 +1506,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: "debug-status-changes",
         label: "Status changes",
         value: normalizeDebugStatusChanges(config.DEBUG_STATUS_CHANGES),
+        values: ["enable", "disable"],
         description: "Enable or disable `workflow_state` debug entries for prompt-orchestration transitions.",
       },
       debugEnabled,
@@ -1417,6 +1516,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: "debug-workflow-events",
         label: "Workflow events",
         value: normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS),
+        values: ["enable", "disable"],
         description: "Enable or disable dedicated workflow debug entries for activation, restoration, closure, and session-shutdown diagnostics.",
       },
       debugEnabled,
@@ -1426,6 +1526,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: `debug-tool:${toolName}`,
         label: toolName,
         value: enabledTools.has(toolName) ? "enable" : "disable",
+        values: ["enable", "disable"],
         description: PI_USEREQ_CUSTOM_TOOL_NAMES.includes(toolName as never)
           ? `Toggle debug logging for custom tool ${toolName}.`
           : `Toggle debug logging for embedded tool ${toolName}.`,
@@ -1437,6 +1538,7 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
         id: `debug-prompt:${promptName}`,
         label: promptName,
         value: enabledPrompts.has(promptName) ? "enable" : "disable",
+        values: ["enable", "disable"],
         description: `Toggle prompt-orchestration debug logging for /${promptName}.`,
       },
       debugEnabled,
@@ -1464,6 +1566,58 @@ async function configureDebugMenu(
   while (true) {
     const choice = await showPiUsereqSettingsMenu(ctx, "Debug", buildDebugMenuChoices(config), {
       initialSelectedId: focusedChoiceId,
+      getChoices: () => buildDebugMenuChoices(config),
+      onChange: (choiceId, newValue) => {
+        if (choiceId === "debug-enabled") {
+          config.DEBUG_ENABLED = newValue === "enable" ? "enable" : "disable";
+          onConfigChange();
+          ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
+          return;
+        }
+        if (choiceId === "debug-status-changes") {
+          config.DEBUG_STATUS_CHANGES = normalizeDebugStatusChanges(newValue);
+          onConfigChange();
+          ctx.ui.notify(`Debug status-change logging ${config.DEBUG_STATUS_CHANGES}`, "info");
+          return;
+        }
+        if (choiceId === "debug-workflow-events") {
+          config.DEBUG_WORKFLOW_EVENTS = normalizeDebugWorkflowEvents(newValue);
+          onConfigChange();
+          ctx.ui.notify(`Debug workflow-event logging ${config.DEBUG_WORKFLOW_EVENTS}`, "info");
+          return;
+        }
+        if (choiceId.startsWith("debug-tool:")) {
+          const toolName = choiceId.slice("debug-tool:".length) as PiUsereqStartupToolName;
+          const enabledTools = new Set(normalizeDebugEnabledTools(config.DEBUG_ENABLED_TOOLS));
+          if (newValue === "enable") {
+            enabledTools.add(toolName);
+          } else {
+            enabledTools.delete(toolName);
+          }
+          config.DEBUG_ENABLED_TOOLS = getDebugToolToggleNames().filter((name) => enabledTools.has(name));
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "enable" ? "Enabled" : "Disabled"} debug logging for ${toolName}`,
+            "info",
+          );
+          return;
+        }
+        if (choiceId.startsWith("debug-prompt:")) {
+          const promptName = choiceId.slice("debug-prompt:".length) as (typeof DEBUG_PROMPT_NAMES)[number];
+          const enabledPrompts = new Set(normalizeDebugEnabledPrompts(config.DEBUG_ENABLED_PROMPTS));
+          if (newValue === "enable") {
+            enabledPrompts.add(promptName);
+          } else {
+            enabledPrompts.delete(promptName);
+          }
+          config.DEBUG_ENABLED_PROMPTS = DEBUG_PROMPT_NAMES.filter((name) => enabledPrompts.has(name));
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "enable" ? "Enabled" : "Disabled"} debug logging for ${promptName}`,
+            "info",
+          );
+        }
+      },
     });
     if (!choice) {
       return;
@@ -1751,6 +1905,13 @@ const PI_NOTIFY_EVENT_MENU_DEFINITIONS: Record<
   },
 };
 
+/**
+ * @brief Defines the canonical label used for persisted boot-sound menu rows.
+ * @details Reuses one shared string literal across notification menu rows, selectors, reset previews, and tests so the persisted boot-sound terminology remains stable. Access complexity is O(1).
+ * @satisfies REQ-149, REQ-179
+ */
+const PI_NOTIFY_BOOT_SOUND_LABEL = "Enable sound (boot value)";
+
 /**
  * @brief Formats the top-level summary value for one notification event submenu.
  * @details Counts enabled completed/interrupted/failed toggles for the selected transport and renders the result as `n/3 on` for right-aligned menu display. Runtime is O(1). No external state is mutated.
@@ -1806,6 +1967,7 @@ function buildPiNotifyEventMenuChoices(
       id: eventMenu.keys[row.eventId],
       label: row.label,
       value: config[eventMenu.keys[row.eventId]] ? "on" : "off",
+      values: ["on", "off"],
       description: `${eventMenu.systemLabel}: ${row.description}`,
     })),
     ...buildTerminalSettingsMenuChoices({
@@ -1870,7 +2032,23 @@ async function configurePiNotifyEventMenu(
       ctx,
       eventMenu.submenuTitle,
       buildPiNotifyEventMenuChoices(config, eventMenu),
-      { initialSelectedId: focusedChoiceId },
+      {
+        initialSelectedId: focusedChoiceId,
+        getChoices: () => buildPiNotifyEventMenuChoices(config, eventMenu),
+        onChange: (choiceId, newValue) => {
+          const enabled = newValue === "on";
+          config[choiceId as PiNotifyEventBooleanConfigKey] = enabled;
+          onConfigChange();
+          const eventLabel = resolvePiNotifyEventLabel(
+            choiceId as PiNotifyEventBooleanConfigKey,
+            eventMenu,
+          );
+          ctx.ui.notify(
+            `${eventMenu.systemLabel} ${eventLabel} ${enabled ? "enabled" : "disabled"}`,
+            "info",
+          );
+        },
+      },
     );
     if (!choice) {
       return;
@@ -1922,7 +2100,7 @@ async function configurePiNotifyEventMenu(
 
 /**
  * @brief Builds the direct Pushover rows rendered inside `Notifications`.
- * @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows, dims and disables the enable row until both credentials are populated, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. No external state is mutated.
+ * @details Serializes the global enable flag, shared-event submenu launcher, priority, title, text, and credential rows into right-valued menu items appended after the sound-command rows, dims and disables the enable row until both credentials are populated, renders the locked value as `configure user/token keys first`, and escapes control characters for the single-line `Pushover text` value. Runtime is O(n) in the rendered text-template length. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered direct Pushover rows.
  * @satisfies REQ-163, REQ-165, REQ-172, REQ-184, REQ-185, REQ-198, REQ-234, REQ-235
@@ -1934,8 +2112,9 @@ function buildPiNotifyPushoverRows(config: UseReqConfig): PiUsereqSettingsMenuCh
       id: "notify-pushover-enabled",
       label: "Enable pushover",
       labelTone: pushoverCredentialsReady ? undefined : "dim",
-      value: pushoverCredentialsReady ? formatPiNotifyPushoverStatus(config) : "off",
+      value: pushoverCredentialsReady ? formatPiNotifyPushoverStatus(config) : "configure user/token keys first",
       valueTone: pushoverCredentialsReady ? undefined : "dim",
+      values: ["on", "off"],
       disabled: !pushoverCredentialsReady,
       description: pushoverCredentialsReady
         ? "Enable or disable all Pushover delivery globally."
@@ -2018,10 +2197,10 @@ async function selectPiNotifyPushoverPriority(
 
 /**
  * @brief Builds the shared settings-menu choices for notification configuration.
- * @details Serializes command-notify, sound, and Pushover blocks with dedicated shared-event submenu launchers so the settings-menu renderer can expose one unified but modular configuration surface, including locked Pushover enablement and escaped single-line rendering for `Pushover text`. Runtime is O(n) in the longest rendered command or text field. No external state is mutated.
+ * @details Serializes command-notify, sound, and Pushover blocks with dedicated shared-event submenu launchers so the settings-menu renderer can expose one unified but modular configuration surface, including locked Pushover enablement, persisted boot-sound rows that stay decoupled from the active runtime sound level, and escaped single-line rendering for `Pushover text`. Runtime is O(n) in the longest rendered command or text field. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered notification-menu choice vector.
- * @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198, REQ-234, REQ-235
+ * @satisfies REQ-137, REQ-149, REQ-150, REQ-151, REQ-152, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-188, REQ-193, REQ-198, REQ-234, REQ-235, REQ-289
  */
 function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   return [
@@ -2029,6 +2208,7 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
       id: "notify-enabled",
       label: "Enable notification",
       value: formatPiNotifyStatus(config),
+      values: ["on", "off"],
       description: "Enable or disable command-notify delivery globally.",
     },
     buildPiNotifyEventLauncherChoice(
@@ -2043,9 +2223,9 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
     },
     {
       id: "selected-sound-command",
-      label: "Enable sound",
+      label: PI_NOTIFY_BOOT_SOUND_LABEL,
       value: config["notify-sound"],
-      description: "Select which sound command level is currently active.",
+      description: "Edit the persisted boot sound level without changing the active runtime sound level.",
     },
     buildPiNotifyEventLauncherChoice(
       config,
@@ -2055,25 +2235,25 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
       id: "sound-toggle-hotkey-bind",
       label: "Sound toggle hotkey bind",
       value: config["notify-sound-toggle-shortcut"],
-      description: "Edit the keyboard shortcut that cycles the selected sound command.",
+      description: "Edit the keyboard shortcut that cycles the active runtime sound level.",
     },
     {
       id: "sound-command-low",
       label: "Sound command (low vol.)",
       value: config.PI_NOTIFY_SOUND_LOW_CMD,
-      description: "Edit the shell command used when the selected sound command is `low`.",
+      description: "Edit the shell command used when the active runtime sound level is `low`.",
     },
     {
       id: "sound-command-mid",
       label: "Sound command (mid vol.)",
       value: config.PI_NOTIFY_SOUND_MID_CMD,
-      description: "Edit the shell command used when the selected sound command is `mid`.",
+      description: "Edit the shell command used when the active runtime sound level is `mid`.",
     },
     {
       id: "sound-command-high",
       label: "Sound command (high vol.)",
       value: config.PI_NOTIFY_SOUND_HIGH_CMD,
-      description: "Edit the shell command used when the selected sound command is `high`.",
+      description: "Edit the shell command used when the active runtime sound level is `high`.",
     },
     ...buildPiNotifyPushoverRows(config),
     ...buildTerminalSettingsMenuChoices({
@@ -2083,44 +2263,44 @@ function buildPiNotifyMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuCho
 }
 
 /**
- * @brief Opens the shared settings-menu selector for the active sound level.
- * @details Reuses the pi-usereq settings-menu renderer so sound-level selection remains stylistically aligned with the notification menu and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
+ * @brief Opens the shared settings-menu selector for the persisted boot sound level.
+ * @details Reuses the pi-usereq settings-menu renderer so boot-sound selection remains stylistically aligned with the notification menu, keeps the active runtime sound level unchanged, and appends a value-less subtree-local `Reset defaults` row. Runtime depends on user interaction count. Side effects are limited to transient custom-UI rendering.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
- * @param[in] currentLevel {PiNotifySoundLevel} Currently selected sound level.
- * @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected sound level, reset action, or `undefined` when cancelled.
- * @satisfies REQ-131, REQ-179, REQ-192
+ * @param[in] currentLevel {PiNotifySoundLevel} Persisted boot sound level.
+ * @return {Promise<PiNotifySoundLevel | "reset-defaults" | undefined>} Selected boot sound level, reset action, or `undefined` when cancelled.
+ * @satisfies REQ-131, REQ-179, REQ-192, REQ-289
  */
 async function selectPiNotifySoundLevel(
   ctx: ExtensionCommandContext,
   currentLevel: PiNotifySoundLevel,
 ): Promise<PiNotifySoundLevel | "reset-defaults" | undefined> {
-  const choice = await showPiUsereqSettingsMenu(ctx, "Enable sound", [
+  const choice = await showPiUsereqSettingsMenu(ctx, PI_NOTIFY_BOOT_SOUND_LABEL, [
     {
       id: "none",
       label: "none",
       value: currentLevel === "none" ? "selected" : "",
-      description: "Disable sound-command delivery while preserving per-event sound toggles.",
+      description: "Persist `none` as the boot sound level loaded during the next session start.",
     },
     {
       id: "low",
       label: "low",
       value: currentLevel === "low" ? "selected" : "",
-      description: "Use the low-volume sound command when sound delivery is enabled for the current event.",
+      description: "Persist `low` as the boot sound level loaded during the next session start.",
     },
     {
       id: "mid",
       label: "mid",
       value: currentLevel === "mid" ? "selected" : "",
-      description: "Use the mid-volume sound command when sound delivery is enabled for the current event.",
+      description: "Persist `mid` as the boot sound level loaded during the next session start.",
     },
     {
       id: "high",
       label: "high",
       value: currentLevel === "high" ? "selected" : "",
-      description: "Use the high-volume sound command when sound delivery is enabled for the current event.",
+      description: "Persist `high` as the boot sound level loaded during the next session start.",
     },
     ...buildTerminalSettingsMenuChoices({
-      resetDefaultsDescription: "Restore the documented default sound level.",
+      resetDefaultsDescription: "Restore the documented default boot sound level.",
     }),
   ], { initialSelectedId: currentLevel });
   if (!choice) {
@@ -2134,11 +2314,11 @@ async function selectPiNotifySoundLevel(
 
 /**
  * @brief Runs the interactive notification-configuration menu.
- * @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, and preserves row focus across menu re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
+ * @details Exposes command-notify, sound, and Pushover controls through the shared settings-menu renderer, delegates completed/interrupted/failed toggles to dedicated event submenus, persists boot-sound changes without altering the active runtime sound level, keeps `Enable pushover` locked until both credentials are populated, decodes escaped control-sequence input for `Pushover text`, and preserves row focus across menu re-renders. Runtime depends on user interaction count. Side effects include UI updates and config mutation.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<boolean>} `true` when the sound-toggle shortcut changed.
- * @satisfies REQ-131, REQ-133, REQ-134, REQ-137, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-184, REQ-188, REQ-192, REQ-193, REQ-195, REQ-196, REQ-198, REQ-234, REQ-235
+ * @satisfies REQ-131, REQ-133, REQ-134, REQ-137, REQ-163, REQ-164, REQ-165, REQ-172, REQ-179, REQ-181, REQ-183, REQ-184, REQ-188, REQ-192, REQ-193, REQ-195, REQ-196, REQ-198, REQ-234, REQ-235, REQ-288, REQ-289
  */
 async function configurePiNotifyMenu(
   ctx: ExtensionCommandContext,
@@ -2152,7 +2332,27 @@ async function configurePiNotifyMenu(
       ctx,
       "Notifications",
       buildPiNotifyMenuChoices(config),
-      { initialSelectedId: focusedChoiceId },
+      {
+        initialSelectedId: focusedChoiceId,
+        getChoices: () => buildPiNotifyMenuChoices(config),
+        onChange: (choiceId, newValue) => {
+          if (choiceId === "notify-enabled" || choiceId === "notify-pushover-enabled") {
+            if (choiceId === "notify-pushover-enabled" && !hasPiNotifyPushoverCredentials(config)) {
+              config["notify-pushover-enabled"] = false;
+              ctx.ui.notify("Populate both Pushover credential fields before enabling Pushover", "info");
+              return;
+            }
+            const enabled = newValue === "on";
+            config[choiceId as PiNotifyBooleanConfigKey] = enabled;
+            onConfigChange();
+            const labelMap: Record<string, string> = {
+              "notify-enabled": "Notification",
+              "notify-pushover-enabled": "Pushover",
+            };
+            ctx.ui.notify(`${labelMap[choiceId]} ${enabled ? "enabled" : "disabled"}`, "info");
+          }
+        },
+      },
     );
     if (!choice) {
       return config["notify-sound-toggle-shortcut"] !== originalShortcut;
@@ -2216,22 +2416,22 @@ async function configurePiNotifyMenu(
         const approved = await confirmResetChanges(
           ctx,
           "Confirm sound reset",
-          [{ label: "Enable sound", previousValue: config["notify-sound"], nextValue: defaultSoundLevel }]
+          [{ label: PI_NOTIFY_BOOT_SOUND_LABEL, previousValue: config["notify-sound"], nextValue: defaultSoundLevel }]
             .filter((change) => change.previousValue !== change.nextValue),
-          "Approve restoring the documented default sound level.",
-          "Abort the sound reset and keep the current value.",
+          "Approve restoring the documented default boot sound level.",
+          "Abort the boot sound reset and keep the current value.",
         );
         if (!approved) {
-          ctx.ui.notify("Aborted sound reset", "info");
+          ctx.ui.notify("Aborted boot sound reset", "info");
         } else {
           config["notify-sound"] = defaultSoundLevel;
           onConfigChange();
-          ctx.ui.notify("Restored default sound level", "info");
+          ctx.ui.notify("Restored default boot sound level; active runtime sound is unchanged", "info");
         }
       } else if (nextLevel !== undefined) {
         config["notify-sound"] = nextLevel;
         onConfigChange();
-        ctx.ui.notify(`Enable sound set to ${nextLevel}`, "info");
+        ctx.ui.notify(`Stored ${PI_NOTIFY_BOOT_SOUND_LABEL.toLowerCase()} as ${nextLevel}; active runtime sound is unchanged`, "info");
       }
       continue;
     }
@@ -2376,7 +2576,7 @@ async function configurePiNotifyMenu(
       const defaults = getDefaultConfig("");
       const resetPreview: ResetConfirmationChange[] = [
         { label: "Enable notification", previousValue: formatPiNotifyStatus(config), nextValue: formatPiNotifyStatus(defaults) },
-        { label: "Enable sound", previousValue: config["notify-sound"], nextValue: defaults["notify-sound"] },
+        { label: PI_NOTIFY_BOOT_SOUND_LABEL, previousValue: config["notify-sound"], nextValue: defaults["notify-sound"] },
         { label: "Sound toggle hotkey bind", previousValue: config["notify-sound-toggle-shortcut"], nextValue: defaults["notify-sound-toggle-shortcut"] },
         { label: "Notify command", previousValue: config.PI_NOTIFY_CMD, nextValue: defaults.PI_NOTIFY_CMD },
         { label: "Sound command (low vol.)", previousValue: config.PI_NOTIFY_SOUND_LOW_CMD, nextValue: defaults.PI_NOTIFY_SOUND_LOW_CMD },
@@ -2411,15 +2611,15 @@ async function configurePiNotifyMenu(
 /**
  * @brief Registers the configurable notification-sound shortcut when supported.
  * @details Loads the current project config, registers one raw pi shortcut when
- * the runtime exposes `registerShortcut(...)`, cycles persisted sound state on
- * invocation, saves the config, refreshes the status bar, and emits one info
- * notification. Runtime is O(1) for registration plus config I/O per shortcut
- * use. Side effects include shortcut registration, config writes, and status
- * updates.
+ * the runtime exposes `registerShortcut(...)`, cycles only the active runtime
+ * sound level on invocation, leaves `.pi-usereq.json` unchanged, refreshes the
+ * status bar, and emits one info notification. Runtime is O(1) for registration
+ * plus one status update per shortcut use. Side effects include shortcut
+ * registration and status updates.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-131, REQ-134, REQ-180
+ * @satisfies REQ-134, REQ-180, REQ-286, REQ-287
  */
 function registerPiNotifyShortcut(
   pi: ExtensionAPI,
@@ -2433,19 +2633,170 @@ function registerPiNotifyShortcut(
   shortcutRegistrar.registerShortcut(config["notify-sound-toggle-shortcut"], {
     description: "Cycle pi-usereq notification sound level",
     handler: async (ctx) => {
-      const nextConfig = loadProjectConfig(ctx.cwd);
-      nextConfig["notify-sound"] = cyclePiNotifySoundLevel(nextConfig["notify-sound"]);
-      saveProjectConfig(ctx.cwd, nextConfig);
-      setPiUsereqStatusConfig(statusController, nextConfig);
-      renderPiUsereqStatus(statusController, ctx);
-      ctx.ui.notify(`pi-usereq sound:${nextConfig["notify-sound"]}`, "info");
+      const nextRuntimeSoundLevel = cyclePiNotifySoundLevel(
+        getPiUsereqRuntimeSoundLevel(statusController),
+      );
+      setPiUsereqRuntimeSoundLevel(
+        statusController,
+        nextRuntimeSoundLevel,
+        ctx,
+      );
+      ctx.ui.notify(`pi-usereq sound:${nextRuntimeSoundLevel}`, "info");
     },
   });
 }
 
 /**
- * @brief Registers bundled prompt commands with the extension.
- * @details Creates one `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state, transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
+ * @brief Resolves the prompt execution plan targeted by `req-reset` recovery.
+ * @details Prefers the current in-memory active request, then the current in-memory pending request, then the process-scoped persisted prompt runtime state so the dedicated reset command can recover from same-host unclean prompt termination after session replacement. Runtime is O(1). No external state is mutated.
+ * @param[in] statusController {PiUsereqStatusController} Mutable status controller.
+ * @return {PromptCommandExecutionPlan | undefined} Recoverable prompt execution plan when one remains available.
+ */
+function resolveReqResetPromptRequest(
+  statusController: PiUsereqStatusController,
+): PromptCommandExecutionPlan | undefined {
+  const isWorktreeBacked = (request: PromptCommandExecutionPlan | undefined): request is PromptCommandExecutionPlan =>
+    request?.worktreeDir !== undefined
+      && request.worktreeRootPath !== undefined
+      && request.worktreePath !== undefined;
+  const inMemoryActiveRequest = statusController.state.activePromptRequest;
+  if (isWorktreeBacked(inMemoryActiveRequest)) {
+    return inMemoryActiveRequest;
+  }
+  const inMemoryPendingRequest = statusController.state.pendingPromptRequest;
+  if (isWorktreeBacked(inMemoryPendingRequest)) {
+    return inMemoryPendingRequest;
+  }
+  const persistedRuntimeState = readPersistedPromptCommandRuntimeState();
+  if (isWorktreeBacked(persistedRuntimeState.activePromptRequest)) {
+    return persistedRuntimeState.activePromptRequest;
+  }
+  if (isWorktreeBacked(persistedRuntimeState.pendingPromptRequest)) {
+    return persistedRuntimeState.pendingPromptRequest;
+  }
+  return inMemoryActiveRequest
+    ?? inMemoryPendingRequest
+    ?? persistedRuntimeState.activePromptRequest
+    ?? persistedRuntimeState.pendingPromptRequest;
+}
+
+/**
+ * @brief Registers the specialized `req-reset` slash command.
+ * @details Registers the non-agentic prompt-recovery command that accepts any current workflow state, reuses persisted prompt runtime state when available, restores the original session-backed `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by session restoration plus git cleanup. Side effects include command registration, status-controller mutation, active-session replacement, worktree deletion, branch deletion, and user notifications.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+ * @return {void} No return value.
+ * @satisfies REQ-304, REQ-305, REQ-306, REQ-307, REQ-308, REQ-309, REQ-310, REQ-311, REQ-312, REQ-313
+ */
+function registerReqResetCommand(
+  pi: ExtensionAPI,
+  statusController: PiUsereqStatusController,
+): void {
+  pi.registerCommand("req-reset", {
+    description: REQ_RESET_COMMAND_DESCRIPTION,
+    handler: async (_args, ctx) => {
+      const promptRequest = resolveReqResetPromptRequest(statusController);
+      const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
+      syncContextCwdMirror(ctx, commandCwd);
+      const projectBase = path.resolve(promptRequest?.basePath ?? getProjectBase(commandCwd));
+      bootstrapRuntimePathState(projectBase, {
+        gitPath: resolveRuntimeGitPath(projectBase),
+      });
+      const config = loadProjectConfig(projectBase);
+      let executionPlan: ReqResetCommandPlan;
+      let executionResult: ReqResetCommandExecutionResult;
+      let resetContext = ctx;
+
+      setPiUsereqStatusConfig(statusController, config);
+      setPiUsereqWorkflowState(statusController, "running", ctx);
+
+      try {
+        executionPlan = prepareReqResetCommandExecution(projectBase, config, promptRequest);
+        executionResult = await executeReqResetCommandExecution(executionPlan, ctx);
+        resetContext = (executionResult.activeContext ?? resetContext) as typeof ctx;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        setPiUsereqWorkflowState(statusController, "error", resetContext);
+        notifyContextSafely(resetContext, message, "error");
+        throw error;
+      }
+
+      const shouldClearPromptState = executionResult.restoredBasePath
+        || executionPlan.promptRequest === undefined;
+      if (shouldClearPromptState) {
+        statusController.state.pendingPromptRequest = undefined;
+        statusController.state.activePromptRequest = undefined;
+        clearPersistedPromptCommandRuntimeState();
+      }
+
+      if (executionResult.errorMessage) {
+        setPiUsereqWorkflowState(statusController, "error", resetContext);
+        notifyContextSafely(resetContext, executionResult.errorMessage, "error");
+        throw new ReqError(executionResult.errorMessage, 1);
+      }
+
+      setPiUsereqWorkflowState(statusController, "idle", resetContext);
+      const successMessage = executionPlan.promptRequest !== undefined
+        ? `SUCCESS: req-reset restored base-path and removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es).`
+        : `SUCCESS: req-reset removed ${executionResult.removedWorktreeDirs.length} worktree(s) plus ${executionResult.removedBranchNames.length} branch(es) and restored idle state.`;
+      notifyContextSafely(resetContext, successMessage, "info");
+    },
+  });
+}
+
+/**
+ * @brief Registers the specialized `req-references` slash command.
+ * @details Registers the non-agentic references-maintenance command that rejects non-`idle` invocations by transitioning workflow state to `error` before direct execution, otherwise reuses slash-command-owned git validation, transitions workflow state through `checking|running|idle`, regenerates `REFERENCES.md` directly from configured source directories, stages only the generated file, creates the fixed-message git commit, verifies repository cleanliness, and notifies pi without starting an LLM session or creating a worktree. Runtime is dominated by git subprocess execution plus source-summary generation. Side effects include command registration, status-controller mutation, filesystem writes, git index/history mutation, and user notifications.
+ * @param[in] pi {ExtensionAPI} Active extension API instance.
+ * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
+ * @return {void} No return value.
+ * @satisfies REQ-200, REQ-221, REQ-224, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303
+ */
+function registerReqReferencesCommand(
+  pi: ExtensionAPI,
+  statusController: PiUsereqStatusController,
+): void {
+  pi.registerCommand("req-references", {
+    description: REQ_REFERENCES_COMMAND_DESCRIPTION,
+    handler: async (_args, ctx) => {
+      if (statusController.state.workflowState !== "idle") {
+        rejectNonIdleReqCommand(statusController, ctx);
+      }
+      const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
+      syncContextCwdMirror(ctx, commandCwd);
+      bootstrapRuntimePathState(commandCwd, {
+        gitPath: resolveRuntimeGitPath(commandCwd),
+      });
+      const projectBase = getProjectBase(commandCwd);
+      const config = loadProjectConfig(commandCwd);
+      setPiUsereqStatusConfig(statusController, config);
+      statusController.state.pendingPromptRequest = undefined;
+      statusController.state.activePromptRequest = undefined;
+      setPiUsereqWorkflowState(statusController, "checking", ctx);
+      try {
+        const executionPlan = prepareReqReferencesCommandExecution(projectBase, config);
+        setPiUsereqWorkflowState(statusController, "running", ctx);
+        executeReqReferencesCommandExecution(executionPlan, config);
+        setPiUsereqWorkflowState(statusController, "idle", ctx);
+        ctx.ui.notify(
+          `SUCCESS: Updated ${formatRuntimePathForDisplay(executionPlan.referencesPath)} and committed changes.`,
+          "info",
+        );
+      } catch (error) {
+        statusController.state.pendingPromptRequest = undefined;
+        statusController.state.activePromptRequest = undefined;
+        setPiUsereqWorkflowState(statusController, "error", ctx);
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(message, "error");
+        throw error;
+      }
+    },
+  });
+}
+
+/**
+ * @brief Registers bundled prompt-backed commands with the extension.
+ * @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
@@ -2460,9 +2811,7 @@ function registerPromptCommands(
       description: resolvePromptCommandDescription(promptName),
       handler: async (args, ctx) => {
         if (statusController.state.workflowState !== "idle") {
-          const message = `ERROR: Prompt workflow state is ${statusController.state.workflowState}, expected idle.`;
-          ctx.ui.notify(message, "error");
-          throw new ReqError(message, 1);
+          rejectNonIdleReqCommand(statusController, ctx, promptName);
         }
         const commandCwd = resolveLiveBootstrapCwd(ctx.cwd);
         syncContextCwdMirror(ctx, commandCwd);
@@ -2577,10 +2926,10 @@ function registerPromptCommands(
  * @details Defines the tool schemas, prompt metadata, and execution handlers that bridge extension tool calls into tool-runner operations without registering duplicate custom slash commands for the same capabilities. Runtime is O(t) for registration; execution cost depends on the selected tool. Side effects include tool registration.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies REQ-005, REQ-010, REQ-011, REQ-014, REQ-017, REQ-044, REQ-069, REQ-070, REQ-071, REQ-072, REQ-073, REQ-074, REQ-075, REQ-076, REQ-077, REQ-078, REQ-079, REQ-080, REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-095, REQ-096, REQ-097, REQ-098, REQ-099, REQ-100, REQ-101, REQ-102
+ * @satisfies REQ-005, REQ-010, REQ-011, REQ-014, REQ-017, REQ-044, REQ-069, REQ-070, REQ-071, REQ-072, REQ-073, REQ-074, REQ-075, REQ-076, REQ-077, REQ-078, REQ-079, REQ-080, REQ-089, REQ-090, REQ-091, REQ-092, REQ-093, REQ-094, REQ-095, REQ-096, REQ-097, REQ-098, REQ-099, REQ-100, REQ-101, REQ-102, REQ-293, REQ-294, REQ-295, REQ-296, REQ-297
  */
 function registerAgentTools(pi: ExtensionAPI): void {
-  const filesReferencesSchema = Type.Object(
+  const filesSummarizeSchema = Type.Object(
     {
       files: Type.Array(
         Type.String({ description: "Project-relative or absolute source file path resolved from the current working directory when not already absolute" }),
@@ -2632,21 +2981,21 @@ function registerAgentTools(pi: ExtensionAPI): void {
   });
 
   pi.registerTool({
-    name: "files-references",
-    label: "files-references",
-    description: "Scope: explicit source files. Return the monolithic references markdown report in content[0].text and keep only execution metadata in details.execution.",
-    promptSnippet: "Return the monolithic references markdown report for caller-selected source files.",
+    name: "files-summarize",
+    label: "files-summarize",
+    description: "Scope: explicit source files. Return the monolithic summary markdown report in content[0].text and keep only execution metadata in details.execution.",
+    promptSnippet: "Return the monolithic summary markdown report for caller-selected source files.",
     promptGuidelines: [
       "Scope: explicit source files selected by files[]; caller order is preserved; each item may be project-relative or absolute.",
       "Output contract: monolithic markdown in content[0].text; details.execution preserves only exit code and residual diagnostics.",
-      "Formatting contract: content matches the Python reference renderer used by `generate_markdown.py`.",
+      "Formatting contract: content matches the Python summary renderer used by `generate_markdown.py`.",
       "Behavior contract: missing inputs, non-file inputs, unsupported extensions, and analysis failures surface through details.execution diagnostics.",
     ],
-    renderResult: buildStructuredToolRenderResult("files-references"),
-    parameters: filesReferencesSchema,
+    renderResult: buildStructuredToolRenderResult("files-summarize"),
+    parameters: filesSummarizeSchema,
     async execute(_toolCallId, params) {
       const contextPath = getRuntimeContextPath(process.cwd());
-      return executeMonolithicTool(() => runFilesReferences(params.files, contextPath));
+      return executeMonolithicTool(() => runFilesSummarize(params.files, contextPath));
     },
   });
 
@@ -2717,12 +3066,18 @@ function registerAgentTools(pi: ExtensionAPI): void {
     },
   });
 
-  const referencesSchema = Type.Object(
+  const summarizeSchema = Type.Object(
     {},
     {
       description: "Input contract: no params. Scope is the configured src-dir list resolved from the current project configuration. Output contract: monolithic markdown in content[0].text plus details.execution diagnostics.",
     },
   );
+  const referencesSchema = Type.Object(
+    {},
+    {
+      description: "Input contract: no params. Scope is the configured src-dir list plus configured docs-dir resolved from the current project configuration. Output contract: content[0].text returns only `success` or `error: <diagnostic>`; the tool overwrites `<docs-dir>/REFERENCES.md` and keeps details.execution diagnostics.",
+    },
+  );
   const tokensSchema = Type.Object(
     {},
     {
@@ -2731,23 +3086,44 @@ function registerAgentTools(pi: ExtensionAPI): void {
   );
 
   pi.registerTool({
-    name: "references",
-    label: "references",
-    description: "Scope: configured project source directories. Return the monolithic references markdown report in content[0].text and keep only execution metadata in details.execution.",
-    promptSnippet: "Return the monolithic project references markdown report from the configured source directories.",
+    name: "summarize",
+    label: "summarize",
+    description: "Scope: configured project source directories. Return the monolithic summary markdown report in content[0].text and keep only execution metadata in details.execution.",
+    promptSnippet: "Return the monolithic project summary markdown report from the configured source directories.",
     promptGuidelines: [
       "Scope: no params; resolve src-dir from the current project configuration and scan the configured source surface from the current working directory.",
       "Output contract: monolithic markdown in content[0].text; details.execution preserves only exit code and residual diagnostics.",
       "Formatting contract: content prepends the file-structure markdown block before the per-file markdown produced by `generate_markdown.py`.",
       "Configuration contract: output changes with cwd-derived project config and src-dir values; the tool does not accept explicit file overrides.",
     ],
+    renderResult: buildStructuredToolRenderResult("summarize"),
+    parameters: summarizeSchema,
+    async execute() {
+      const contextPath = getRuntimeContextPath(process.cwd());
+      const projectBase = getProjectBase(contextPath);
+      const config = loadProjectConfig(projectBase);
+      return executeMonolithicTool(() => runSummarize(contextPath, config));
+    },
+  });
+
+  pi.registerTool({
+    name: "references",
+    label: "references",
+    description: "Scope: configured project source directories and configured docs-dir. Overwrite REFERENCES.md and return only success or error in content[0].text while keeping execution metadata in details.execution.",
+    promptSnippet: "Generate REFERENCES.md from the configured source directories without returning the generated markdown.",
+    promptGuidelines: [
+      "Scope: no params; resolve src-dir and docs-dir from the current project configuration and current working directory.",
+      "Behavior contract: generate the same file-structure-plus-summary markdown as `summarize` and overwrite `<docs-dir>/REFERENCES.md`.",
+      "Output contract: `content[0].text` is `success` on success or `error: <diagnostic>` on failure; generated markdown is never returned to the LLM.",
+      "Failure contract: source discovery, markdown generation, and file-write errors surface through the status text plus details.execution diagnostics.",
+    ],
     renderResult: buildStructuredToolRenderResult("references"),
     parameters: referencesSchema,
     async execute() {
       const contextPath = getRuntimeContextPath(process.cwd());
       const projectBase = getProjectBase(contextPath);
       const config = loadProjectConfig(projectBase);
-      return executeMonolithicTool(() => runReferences(contextPath, config));
+      return executeStatusTool(() => runReferences(contextPath, config));
     },
   });
 
@@ -2938,6 +3314,7 @@ function buildPiUsereqToolToggleChoices(pi: ExtensionAPI, config: UseReqConfig):
       id: tool.name,
       label: tool.name,
       value: enabledTools.has(tool.name) ? "on" : "off",
+      values: ["on", "off"],
       description: tool.description ?? `Toggle startup activation for ${tool.name}.`,
     })),
     ...buildTerminalSettingsMenuChoices({
@@ -3012,7 +3389,29 @@ async function configurePiUsereqToolsMenu(
     }
 
     if (choice === "enable-tools") {
-      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolToggleChoices(pi, config));
+      const selectedToolName = await showPiUsereqSettingsMenu(ctx, "Enable tools", buildPiUsereqToolToggleChoices(pi, config), {
+        getChoices: () => buildPiUsereqToolToggleChoices(pi, config),
+        onChange: (toolName, newValue) => {
+          const enabledTools = new Set(getConfiguredEnabledPiUsereqTools(config));
+          if (newValue === "on") {
+            enabledTools.add(toolName as PiUsereqStartupToolName);
+          } else {
+            enabledTools.delete(toolName as PiUsereqStartupToolName);
+          }
+          setConfiguredPiUsereqTools(
+            pi,
+            config,
+            getPiUsereqStartupTools(pi)
+              .map((tool) => tool.name)
+              .filter((currentToolName) => enabledTools.has(currentToolName)),
+          );
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "on" ? "Enabled" : "Disabled"} ${toolName}`,
+            "info",
+          );
+        },
+      });
       if (!selectedToolName) {
         continue;
       }
@@ -3138,6 +3537,7 @@ function buildStaticCheckMenuChoices(config: UseReqConfig): PiUsereqSettingsMenu
         id: `toggle-static-check-language:${language}`,
         label: language,
         value: languageConfig.enabled === "enable" ? "on" : "off",
+        values: ["on", "off"],
         description: `Toggle static-check execution for ${language}. Configured ${configuredCount} ${suffix}. Supported extensions: ${extensions.join(", ")}.`,
       };
     }),
@@ -3214,6 +3614,19 @@ async function configureStaticCheckMenu(
   while (true) {
     const staticChoice = await showPiUsereqSettingsMenu(ctx, "Language static code checkers", buildStaticCheckMenuChoices(config), {
       initialSelectedId: focusedChoiceId,
+      getChoices: () => buildStaticCheckMenuChoices(config),
+      onChange: (choiceId, newValue) => {
+        if (choiceId.startsWith("toggle-static-check-language:")) {
+          const language = choiceId.slice("toggle-static-check-language:".length);
+          config["static-check"][language] ??= createStaticCheckLanguageConfig([]);
+          config["static-check"][language]!.enabled = newValue === "on" ? "enable" : "disable";
+          onConfigChange();
+          ctx.ui.notify(
+            `${newValue === "on" ? "Enabled" : "Disabled"} static-check for ${language}`,
+            "info",
+          );
+        }
+      },
     });
 
     if (!staticChoice) {
@@ -3380,6 +3793,7 @@ function buildPiUsereqMenuChoices(
       id: "auto-git-commit",
       label: "Auto git commit",
       value: config.AUTO_GIT_COMMIT,
+      values: ["enable", "disable"],
       description: "Select bundled `git_commit.md` or `git_read-only.md` for `%%COMMIT%%`; disabling also forces prompt-command worktrees off.",
     },
     {
@@ -3388,6 +3802,8 @@ function buildPiUsereqMenuChoices(
       labelTone: autoGitCommitDisabled ? "dim" : undefined,
       value: effectiveGitWorktreeEnabled,
       valueTone: autoGitCommitDisabled ? "dim" : undefined,
+      values: ["enable", "disable"],
+      disabled: autoGitCommitDisabled,
       description: autoGitCommitDisabled
         ? "Forced to `disable` while `Auto git commit` is disabled."
         : "Enable or disable prompt-command worktree orchestration.",
@@ -3520,7 +3936,36 @@ async function configurePiUsereq(
       ctx,
       "pi-usereq",
       buildPiUsereqMenuChoices(ctx.cwd, config),
-      { initialSelectedId: focusedChoiceId },
+      {
+        initialSelectedId: focusedChoiceId,
+        getChoices: () => buildPiUsereqMenuChoices(ctx.cwd, config),
+        onChange: (choiceId, newValue) => {
+          if (choiceId === "auto-git-commit") {
+            config.AUTO_GIT_COMMIT = newValue === "enable" ? "enable" : "disable";
+            if (config.AUTO_GIT_COMMIT === "disable") {
+              config.GIT_WORKTREE_ENABLED = "disable";
+              persistConfigChange();
+              ctx.ui.notify("Auto git commit disabled; Git worktree forced off", "info");
+            } else {
+              persistConfigChange();
+              ctx.ui.notify("Auto git commit enabled", "info");
+            }
+            return;
+          }
+          if (choiceId === "git-worktree-enabled") {
+            if (config.AUTO_GIT_COMMIT === "disable") {
+              ctx.ui.notify("Git worktree is locked while Auto git commit is disabled", "info");
+              return;
+            }
+            config.GIT_WORKTREE_ENABLED = newValue === "enable" ? "enable" : "disable";
+            persistConfigChange();
+            ctx.ui.notify(
+              `Git worktree ${resolveEffectiveGitWorktreeEnabled(config.AUTO_GIT_COMMIT, config.GIT_WORKTREE_ENABLED) === "enable" ? "enabled" : "disabled"}`,
+              "info",
+            );
+          }
+        },
+      },
     );
     if (!choice) {
       if (config["notify-sound-toggle-shortcut"] !== initialShortcut) {
@@ -3740,23 +4185,16 @@ function registerConfigCommands(
 
 /**
  * @brief Registers the complete pi-usereq extension.
- * @details Validates installation-owned bundled resources, registers prompt and
- * configuration commands plus agent tools, registers the configurable
- * notification-sound shortcut when the runtime supports shortcuts, and
- * installs shared wrappers for all supported pi lifecycle hooks so status
- * telemetry, context usage, prompt timing, cumulative runtime, prompt-specific
- * Pushover metadata, tool-result debug logging, and prompt-orchestration debug
- * effects remain synchronized with runtime events. Runtime is O(h) in hook
- * count during registration. Side effects include filesystem reads,
- * command/tool/shortcut registration, UI updates, active-tool changes,
- * optional debug-log writes, and timer scheduling.
+ * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247
+ * @satisfies DES-002, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();
   ensureBundledResourcesAccessible();
+  registerReqResetCommand(pi, statusController);
+  registerReqReferencesCommand(pi, statusController);
   registerPromptCommands(pi, statusController);
   registerAgentTools(pi);
   registerConfigCommands(pi, statusController);