pi-usereq 0.10.0 → 0.12.0

package/scripts/lib/extension-debug-harness.ts

@@ -211,10 +211,10 @@ const PROMPT_COMMAND_EXAMPLES: Record<string, string> = {
  */
 const TOOL_EXAMPLES: Record<string, string> = {
   "files-tokens": `npm run debug:ext:tool -- --name files-tokens --params '{"files":["pi-usereq/docs/REQUIREMENTS.md","pi-usereq/docs/WORKFLOW.md"]}' --cwd . --format json`,
-  "files-references": `npm run debug:ext:tool -- --name files-references --params '{"files":["src/index.ts","src/core/tool-runner.ts"]}' --cwd . --format pretty`,
+  "files-summarize": `npm run debug:ext:tool -- --name files-summarize --params '{"files":["src/index.ts","src/core/tool-runner.ts"]}' --cwd . --format pretty`,
   "files-compress": `npm run debug:ext:tool -- --name files-compress --params '{"files":["src/index.ts"],"enableLineNumbers":true}' --cwd . --format json`,
   "files-search": `npm run debug:ext:tool -- --name files-search --params '{"tag":"FUNCTION|METHOD","pattern":"^run","files":["src/core/tool-runner.ts"],"enableLineNumbers":true}' --cwd . --format pretty`,
-  references: "npm run debug:ext:tool -- --name references --cwd . --format pretty",
+  summarize: "npm run debug:ext:tool -- --name summarize --cwd . --format pretty",
   compress: `npm run debug:ext:tool -- --name compress --params '{"enableLineNumbers":true}' --cwd . --format json`,
   search: `npm run debug:ext:tool -- --name search --params '{"tag":"FUNCTION","pattern":"^run","enableLineNumbers":true}' --cwd . --format pretty`,
   tokens: "npm run debug:ext:tool -- --name tokens --cwd . --format json",

package/scripts/tool-args-to-params.ts

@@ -97,7 +97,7 @@ function takeBooleanFlag(tokens: string[], flag: string): { tokens: string[]; pr
 export function buildToolParamsFromArgsText(toolName: string, argsText: string): Record<string, unknown> {
   const tokens = shellSplit(argsText);
   switch (toolName) {
-    case "references":
+    case "summarize":
     case "tokens":
     case "static-check":
       if (tokens.length !== 0) {
@@ -105,7 +105,7 @@ export function buildToolParamsFromArgsText(toolName: string, argsText: string):
       }
       return {};
     case "files-tokens":
-    case "files-references":
+    case "files-summarize":
     case "files-static-check":
       return { files: tokens };
     case "files-compress": {

package/src/cli.ts

@@ -20,12 +20,12 @@ import {
   runCompress,
   runFilesCompress,
   runFilesSearch,
-  runFilesReferences,
+  runFilesSummarize,
   runFilesStaticCheck,
   runFilesTokens,
   runSearch,
   runProjectStaticCheck,
-  runReferences,
+  runSummarize,
   runTokens,
 } from "./core/tool-runner.js";
 import {
@@ -46,10 +46,10 @@ interface ParsedArgs {
   enableLineNumbers?: boolean;
   enableStaticCheck?: string[];
   filesTokens?: string[];
-  filesReferences?: string[];
+  filesSummarize?: string[];
   filesCompress?: string[];
   filesSearch?: string[];
-  references?: boolean;
+  summarize?: boolean;
   compress?: boolean;
   search?: [string, string];
   tokens?: boolean;
@@ -106,9 +106,9 @@ function parseArgs(argv: string[]): ParsedArgs {
         index = next;
         break;
       }
-      case "--files-references": {
+      case "--files-summarize": {
         const [values, next] = takeUntilOption(index + 1);
-        parsed.filesReferences = values;
+        parsed.filesSummarize = values;
         index = next;
         break;
       }
@@ -124,8 +124,8 @@ function parseArgs(argv: string[]): ParsedArgs {
         index = next;
         break;
       }
-      case "--references":
-        parsed.references = true;
+      case "--summarize":
+        parsed.summarize = true;
         index += 1;
         break;
       case "--compress":
@@ -256,12 +256,12 @@ export function main(argv = process.argv.slice(2)): number {
     }
     const args = parseArgs(argv);
     const hereOnlyProjectCommand = !!(
-      args.references || args.compress || args.tokens || args.search || args.staticCheck
+      args.summarize || args.compress || args.tokens || args.search || args.staticCheck
     );
     if (hereOnlyProjectCommand) {
       if (args.base) {
         throw new ReqError(
-          "Error: --references, --compress, --tokens, --find, and --static-check do not allow --base; use --here.",
+          "Error: --summarize, --compress, --tokens, --find, and --static-check do not allow --base; use --here.",
           1,
         );
       }
@@ -281,12 +281,12 @@ export function main(argv = process.argv.slice(2)): number {
     }
 
     if (args.filesTokens) return writeResult(runFilesTokens(args.filesTokens));
-    if (args.filesReferences) return writeResult(runFilesReferences(args.filesReferences, process.cwd(), args.verbose));
+    if (args.filesSummarize) return writeResult(runFilesSummarize(args.filesSummarize, process.cwd(), args.verbose));
     if (args.filesCompress) return writeResult(runFilesCompress(args.filesCompress, process.cwd(), args.enableLineNumbers, args.verbose));
     if (args.filesSearch) return writeResult(runFilesSearch(args.filesSearch, args.enableLineNumbers, args.verbose));
     if (args.testStaticCheck) return runStaticCheck(args.testStaticCheck);
     if (args.filesStaticCheck) return writeResult(runFilesStaticCheck(args.filesStaticCheck, projectBase, config));
-    if (args.references) return writeResult(runReferences(projectBase, config, args.verbose));
+    if (args.summarize) return writeResult(runSummarize(projectBase, config, args.verbose));
     if (args.compress) return writeResult(runCompress(projectBase, config, args.enableLineNumbers, args.verbose));
     if (args.search) return writeResult(runSearch(projectBase, args.search[0], args.search[1], config, args.enableLineNumbers, args.verbose));
     if (args.tokens) return writeResult(runTokens(projectBase, config));

package/src/core/debug-runtime.ts

@@ -26,10 +26,10 @@ export const DEFAULT_DEBUG_ENABLED = "disable" as const;
 
 /**
  * @brief Defines the default debug log file value.
- * @details Relative values resolve against the original project base when entries are written. Access complexity is O(1).
+ * @details New configurations write debug JSON entries to `/tmp/PI-useReq.json` unless the user overrides the path. Access complexity is O(1).
  * @satisfies CTN-013, REQ-237
  */
-export const DEFAULT_DEBUG_LOG_FILE = "debug.json";
+export const DEFAULT_DEBUG_LOG_FILE = "/tmp/PI-useReq.json";
 
 /**
  * @brief Defines the default workflow-transition logging mode.

package/src/core/extension-status.ts

@@ -1,10 +1,9 @@
 /**
  * @file
  * @brief Tracks pi-usereq extension status state and renders status-bar telemetry.
- * @details Centralizes hook interception, context-usage snapshots, run timing,
- * and deterministic status-bar formatting for the pi-usereq extension. Runtime
- * is O(1) per event plus O(s) in configured source-path count during status
- * rendering. Side effects are limited to in-memory state mutation and interval
+ * @details Centralizes hook interception, context-usage snapshots, active-branch lookup, run timing, and deterministic status-bar formatting for the pi-usereq extension. Runtime
+ * is O(1) per event plus interval-driven re-renders while a prompt remains
+ * active. Side effects are limited to in-memory state mutation and interval
  * scheduling through exported controller helpers.
  */
 
@@ -15,15 +14,13 @@ 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 {
-  formatRuntimePathForDisplay,
-  getRuntimeContextPath,
-} from "./path-context.js";
 import {
   restorePersistedPromptCommandRuntimeStateForSession,
   writePersistedPromptCommandRuntimeState,
 } from "./prompt-command-state.js";
+import { resolveRuntimeGitBranchName } from "./runtime-project-paths.js";
 
 /**
  * @brief Enumerates the CLI-supported theme tokens consumed by status rendering.
@@ -115,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;
@@ -123,6 +120,7 @@ export interface PiUsereqStatusState {
   runStartTimeMs: number | undefined;
   lastRunDurationMs: number | undefined;
   totalRunDurationMs: number | undefined;
+  runtimeSoundLevel: PiNotifySoundLevel | undefined;
   pendingPromptRequest: PiUsereqPromptRequest | undefined;
   activePromptRequest: PiUsereqPromptRequest | undefined;
 }
@@ -323,6 +321,17 @@ function createStatusThemeAdapter(theme: RawStatusTheme): StatusThemeAdapter {
   };
 }
 
+/**
+ * @brief Resolves the active git branch value rendered in the status bar.
+ * @details Reads the current branch from the active context working directory on every status render so worktree switches and restored base-session renders expose the latest branch immediately. Runtime is dominated by git execution when the working directory belongs to a repository. Side effects include subprocess creation.
+ * @param[in] ctx {ExtensionContext} Active extension context.
+ * @return {string} Active branch name or `unknown` when unavailable.
+ * @satisfies REQ-121, REQ-283
+ */
+function resolveStatusBranchValue(ctx: ExtensionContext): string {
+  return resolveRuntimeGitBranchName(ctx.cwd);
+}
+
 /**
  * @brief Normalizes one raw context-usage snapshot.
  * @details Preserves the runtime token and context-window counts, derives a
@@ -370,12 +379,10 @@ function refreshContextUsage(
 
 /**
  * @brief Resolves the icon text for one normalized context-usage snapshot.
- * @details Maps context usage to one fixed-width icon band so footer rendering
- * remains compact and deterministic. Unavailable usage degrades to the `0%`
- * icon. Runtime is O(1). No external state is mutated.
+ * @details Maps context usage to one fixed-width icon band so footer rendering remains compact and deterministic across the documented `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands. Unavailable usage degrades to the `0%` icon. Runtime is O(1). No external state is mutated.
  * @param[in] contextUsage {ContextUsage | undefined} Normalized context snapshot.
  * @return {string} Fixed-width gauge icon text.
- * @satisfies REQ-121, REQ-122
+ * @satisfies REQ-122, REQ-284
  */
 function resolveContextUsageIconText(
   contextUsage: ContextUsage | undefined,
@@ -384,13 +391,13 @@ function resolveContextUsageIconText(
   if (percent === undefined || percent === null || percent <= 0) {
     return "▕_▏";
   }
-  if (percent <= 25) {
+  if (percent < 25) {
     return "▕▂▏";
   }
-  if (percent <= 50) {
+  if (percent < 50) {
     return "▕▄▏";
   }
-  if (percent <= 90) {
+  if (percent < 75) {
     return "▕▆▏";
   }
   return "▕█▏";
@@ -398,22 +405,22 @@ function resolveContextUsageIconText(
 
 /**
  * @brief Formats one icon-based context-usage gauge.
- * @details Renders the documented `warning`-colored icon bands for `0-90%`, applies terminal blink control to the `warning`-colored `>90-100%` icon, and applies terminal blink control to the `error`-colored overflow icon so unsupported terminals degrade to non-blinking colored text automatically. 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.
- * @satisfies REQ-121, REQ-122, REQ-126, REQ-127, REQ-128, REQ-233
+ * @satisfies REQ-122, REQ-126, REQ-127, REQ-128, REQ-233, REQ-284
  */
 function formatContextUsageBar(
   theme: StatusThemeAdapter,
   contextUsage: ContextUsage | undefined,
 ): string {
   const percent = contextUsage?.percent ?? 0;
-  if (percent > 100) {
+  if (percent >= 100) {
     return theme.colorize("error", "\u001b[5m▕█▏\u001b[25m");
   }
-  if (percent > 90) {
-    return theme.colorize("warning", "\u001b[5m▕█▏\u001b[25m");
+  if (percent >= 90) {
+    return theme.colorize("error", "▕█▏");
   }
   return theme.value(resolveContextUsageIconText(contextUsage));
 }
@@ -543,34 +550,48 @@ 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, current-path, 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.
- * @param[in] cwd {string} Runtime working directory used for context-path derivation.
+ * @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.
+ * @param[in] branchName {string} Active git branch name shown in the footer.
  * @param[in] nowMs {number} Current wall-clock time in milliseconds.
  * @return {string} Single-line status-bar text.
- * @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-148, REQ-156, REQ-159, REQ-180, REQ-222, REQ-223
+ * @satisfies REQ-109, REQ-112, REQ-120, REQ-121, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-156, REQ-159, REQ-180, REQ-222, REQ-223, REQ-233, REQ-283, REQ-284
  */
 function buildPiUsereqStatusText(
-  cwd: string,
   config: UseReqConfig,
   theme: StatusThemeAdapter,
   state: PiUsereqStatusState,
+  branchName: string,
   nowMs: number,
 ): string {
-  const currentPathText = formatRuntimePathForDisplay(getRuntimeContextPath(cwd));
   const elapsedText = formatElapsedStatusValue(state, nowMs);
-  const soundText = config["notify-sound"];
+  const soundText = resolvePiUsereqRuntimeSoundLevel(state, config);
   return [
     formatRenderedStatusField(
       theme,
       "status",
       formatWorkflowStateValue(theme, state.workflowState),
     ),
-    formatStatusField(theme, "current-path", currentPathText),
+    formatStatusField(theme, "branch", branchName),
     formatRenderedStatusField(
       theme,
       "context",
@@ -626,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
  */
@@ -640,6 +661,7 @@ export function createPiUsereqStatusController(): PiUsereqStatusController {
       runStartTimeMs: undefined,
       lastRunDurationMs: undefined,
       totalRunDurationMs: undefined,
+      runtimeSoundLevel: undefined,
       pendingPromptRequest: undefined,
       activePromptRequest: undefined,
     },
@@ -650,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.
@@ -664,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 `.pi-usereq.json`. 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 `.pi-usereq.json`, 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, deriving `current-path` from the active runtime context path aligned to `ctx.cwd` and including the 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(s) in configured source-path count. 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-148, REQ-159, REQ-180, REQ-280
+ * @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,
@@ -681,14 +738,16 @@ export function renderPiUsereqStatus(
     return;
   }
   try {
+    refreshContextUsage(controller.state, ctx);
     const theme = createStatusThemeAdapter(ctx.ui.theme as RawStatusTheme);
+    const branchName = resolveStatusBranchValue(ctx);
     ctx.ui.setStatus(
       "pi-usereq",
       buildPiUsereqStatusText(
-        ctx.cwd,
         controller.config,
         theme,
         controller.state,
+        branchName,
         Date.now(),
       ),
     );
@@ -727,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,
@@ -752,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/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",