pi-usereq 0.10.0 → 0.12.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.56"
-date: "2026-04-23"
+version: "0.0.65"
+date: "2026-04-25"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -41,13 +41,14 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 ## 2. Project Requirements
 
 ### 2.1 Project Functions
-- **PRJ-001**: MUST expose prompt commands that render bundled prompt templates with configuration-derived path substitutions and internal tool-reference adaptation.
-- **PRJ-002**: MUST expose CLI and agent-tool interfaces for token counting, references generation, compression, construct search, and static-check execution on explicit files or configured project sources.
+- **PRJ-001**: MUST expose bundled prompt-backed slash commands with configuration-derived path substitutions plus a dedicated `req-references` slash command for direct reference-file regeneration.
+- **PRJ-002**: MUST expose CLI and agent-tool interfaces for token counting, source summarization, compression, construct search, and static-check execution, plus an agent-tool interface for reference-file generation.
 - **PRJ-003**: MUST provide an interactive pi configuration surface for project paths, git automation, static-check entries, active-tool enablement, notifications, and debug logging controls.
-- **PRJ-004**: MUST provide slash-command-owned git validation plus configurable-prefix prompt-command worktree naming, creation, deletion, merge, and cleanup using runtime project and git paths.
+- **PRJ-004**: MUST provide slash-command-owned git validation plus bundled-prompt worktree orchestration and dedicated `req-references` direct reference-file commit orchestration using runtime project and git paths.
 - **PRJ-005**: MUST install bundled prompts, git execution instructions, documentation templates, and guidelines under the extension installation path and expose them through shared runtime path context.
 - **PRJ-006**: MUST expose a standalone debug surface that inventories extension commands and tools, replays handlers offline, captures registration and UI metadata, provides a bash wrapper, and optionally compares the contract against the official pi SDK runtime.
 - **PRJ-007**: MUST intercept pi CLI lifecycle hooks to maintain context telemetry, prompt workflow state, session timing, and selected debug logging for prompt orchestration and tool execution.
+- **PRJ-008**: MUST expose a dedicated `req-reset` slash command for non-agentic prompt-orchestration recovery, base-path session restoration, and force cleanup of generated worktrees plus branches.
 
 ### 2.2 Project Constraints
 - **CTN-001**: MUST persist project configuration only at `<base-path>/.pi-usereq.json` with default `docs-dir=pi-usereq/docs`, `tests-dir=tests`, `src-dir=["src"]`, `AUTO_GIT_COMMIT=enable`, `GIT_WORKTREE_ENABLED=enable`, and `GIT_WORKTREE_PREFIX=PI-useReq-`.
@@ -62,7 +63,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **CTN-010**: MUST execute offline harness flows without requiring pi.dev services or `docs/pi.dev/agent-document-manifest.json`.
 - **CTN-011**: MUST store bundled prompt, instruction, template, and guideline resources under `src/resources/{prompts,instructions,templates,guidelines}` and install them under `<installation-path>/resources/{prompts,instructions,templates,guidelines}`.
 - **CTN-012**: MUST NOT persist derived `base-path`, `git-path`, `parent-path`, `base-dir`, `context-path`, `worktree-dir`, or `worktree-path` in `.pi-usereq.json`.
-- **CTN-013**: MUST default `DEBUG_ENABLED=disable`, `DEBUG_LOG_FILE=debug.json`, `DEBUG_STATUS_CHANGES=disable`, `DEBUG_WORKFLOW_EVENTS=disable`, `DEBUG_LOG_ON_STATUS=running`, `DEBUG_ENABLED_TOOLS=[]`, and `DEBUG_ENABLED_PROMPTS=[]` in persisted project configuration.
+- **CTN-013**: MUST default `DEBUG_ENABLED=disable`, `DEBUG_LOG_FILE=/tmp/PI-useReq.json`, `DEBUG_STATUS_CHANGES=disable`, `DEBUG_WORKFLOW_EVENTS=disable`, `DEBUG_LOG_ON_STATUS=running`, `DEBUG_ENABLED_TOOLS=[]`, and `DEBUG_ENABLED_PROMPTS=[]` in persisted project configuration.
 - **CTN-014**: MUST serialize every configured or derived path without a trailing `/`.
 - **CTN-015**: MUST reserve `*-path` names for absolute paths and `*-dir` names for relative paths.
 - **CTN-016**: MUST NOT modify any path under `docs/` during analysis, implementation, verification, or bug fixing.
@@ -72,11 +73,13 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 
 ### 3.1 Design and Implementation
 - **DES-001**: MUST implement the standalone executable in `src/cli.ts` as flag parsing plus dispatch to `tool-runner.ts` or `runStaticCheck`.
-- **DES-002**: MUST implement extension activation in `src/index.ts` by registering prompt commands with dedicated prompt-runtime orchestration, agent tools, configuration commands, and shared wrappers for supported pi CLI lifecycle hooks.
+- **DES-002**: MUST implement extension activation in `src/index.ts` by registering bundled prompt commands, dedicated `req-references` command orchestration, agent tools, config commands, and shared pi CLI lifecycle-hook wrappers.
 - **DES-003**: MUST represent parsed source constructs as `SourceElement` instances produced by `SourceAnalyzer` and enriched with signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen fields.
-- **DES-012**: MUST implement prompt-command git validation and worktree lifecycle logic in `src/core/prompt-command-runtime.ts` without invoking extension custom-tool executors from `src/core/tool-runner.ts`.
+- **DES-012**: MUST implement bundled prompt-command git validation and worktree lifecycle logic in `src/core/prompt-command-runtime.ts` without invoking extension custom-tool executors from `src/core/tool-runner.ts`.
+- **DES-013**: MUST implement dedicated `req-references` git-validation, reference-write, staging, commit, and clean-repository verification logic in `src/core/req-references-command.ts` without starting an LLM session or creating a worktree.
+- **DES-014**: MUST implement dedicated `req-reset` recovery and cleanup orchestration in `src/core/req-reset-command.ts`, reusing shared base-path restoration helpers without starting an LLM session or creating a worktree.
 - **DES-004**: MUST implement modular static-check execution through debug-capable `StaticCheckBase` and user-facing `StaticCheckCommand`, selected by `dispatchStaticCheckForFile`.
-- **DES-005**: MUST centralize project file collection, token/reference/compress/search operations, and static-check execution in `src/core/tool-runner.ts`.
+- **DES-005**: MUST centralize project file collection, token counting, summary generation, reference-file generation, compression, construct search, and static-check execution in `src/core/tool-runner.ts`.
 - **DES-006**: MUST reuse shared markdown and text renderers for CLI and agent-tool compression plus construct-search outputs, preserving source-leading tabs in emitted excerpts instead of dedicated agent-tool JSON payload builders.
 - **DES-007**: MUST implement the standalone debug surface in `scripts/debug-extension.ts`, `scripts/pi-usereq-debug.sh`, and `scripts/lib/` recording and SDK-probe modules without altering extension runtime control flow.
 - **DES-008**: MUST wrap affected agent-tool executions as one monolithic content text block plus minimal execution-only details instead of mirrored structured JSON payloads.
@@ -89,12 +92,18 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-002**: MUST replace `%%DOC_PATH%%`, `%%GUIDELINES_*%%`, `%%TEMPLATE_PATH%%`, `%%SRC_PATHS%%`, and `%%TEST_PATH%%` when rendering prompts.
 - **REQ-266**: MUST replace `%%PROJECT_BASE%%`, `%%CONTEXT_PATH%%`, `%%INSTALLATION_PATH%%`, `%%CONFIG_PATH%%`, and `%%ARGS%%` when rendering prompts.
 - **REQ-003**: MUST rewrite legacy `req --...` prompt text references to surviving internal tool names and slash-command-owned runtime behaviors.
-- **REQ-004**: MUST register `req-<prompt>` commands for every bundled prompt name using the bundled YAML `description` field as the runtime command description, run prompt preflight/worktree orchestration, and send rendered prompt content as a user message.
+- **REQ-004**: MUST register bundled prompt-backed `req-<prompt>` commands using the first Markdown `# ` heading as description, run prompt preflight/worktree orchestration, and send rendered prompt content as a user message.
+- **REQ-298**: MUST register `req-references` as a dedicated extension command with description `Write a REFERENCES.md using the project's source code` and MUST NOT depend on a bundled prompt Markdown file.
 - **REQ-211**: MUST replace `%%PROMPT%%` with the current prompt name without the `req-` prefix when rendering bundled prompts and bundled commit instructions.
 - **REQ-213**: MUST replace prompt token `%%COMMIT%%` with rendered `<installation-path>/resources/instructions/git_commit.md` when `AUTO_GIT_COMMIT=enable`, and with rendered `<installation-path>/resources/instructions/git_read-only.md` when `AUTO_GIT_COMMIT=disable`.
 - **REQ-214**: MUST preprocess bundled `git_commit.md` and `git_read-only.md` with the same runtime token-replacement rules used for prompts before injecting them through `%%COMMIT%%`.
-- **REQ-005**: MUST expose `files-tokens`, `files-references`, `files-compress`, and `files-search` only through agent-tool registration.
-- **REQ-044**: MUST expose `references`, `compress`, `search`, `tokens`, `files-static-check`, and `static-check` only through agent-tool registration.
+- **REQ-005**: MUST expose `files-tokens`, `files-summarize`, `files-compress`, and `files-search` only through agent-tool registration.
+- **REQ-044**: MUST expose `summarize`, `references`, `compress`, `search`, `tokens`, `files-static-check`, and `static-check` only through agent-tool registration.
+- **REQ-293**: MUST make `references` scan configured `src-dir` files, generate the same file-structure-plus-summary markdown as `summarize`, and overwrite `<base-path>/<docs-dir>/REFERENCES.md`.
+- **REQ-294**: MUST make `references` return `success` through `content[0].text` after `REFERENCES.md` is overwritten and MUST NOT return generated reference markdown to the LLM.
+- **REQ-295**: MUST make `references` return `error: <diagnostic>` through `content[0].text` when source discovery, markdown generation, or `REFERENCES.md` writing fails.
+- **REQ-296**: MUST preserve `references` `details` as `execution` metadata only, with numeric `code` and optional normalized residual diagnostics.
+- **REQ-297**: MUST register `references` with machine-oriented descriptions describing configured `src-dir` plus `docs-dir` scope, overwrite behavior, status-only text contract, and stable failure conditions.
 - **REQ-046**: MUST implement a recording extension API supporting `registerCommand`, `registerTool`, `on`, `getAllTools`, `getActiveTools`, `setActiveTools`, and `sendUserMessage`, and preserve stable registration order in serialized snapshots.
 - **REQ-047**: MUST implement a recording command context UI supporting `select`, `input`, `notify`, `setStatus`, and `setEditorText`, and serialize queued inputs plus emitted UI side effects.
 - **REQ-048**: MUST load the target extension via its default export, invoke it as a black box, and execute offline replays only through registered `session_start`, command, and tool handlers.
@@ -115,7 +124,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-065**: MUST make `scripts/pi-usereq-debug.sh tool` accept `--args <text>` by forwarding a JSON object through `--params`, while preserving direct `--params <json>` passthrough.
 - **REQ-006**: MUST provide a `pi-usereq` menu that edits project directories, git automation, static-check settings, tools, notifications, and debug settings, exposes `Show configuration`, confirms reset actions, saves every change immediately, and never renders `Save and close`.
 - **REQ-236**: MUST persist `DEBUG_ENABLED` with allowed values `enable` and `disable`, defaulting to `disable`.
-- **REQ-237**: MUST persist `DEBUG_LOG_FILE` as a non-empty string defaulting to `debug.json`, and resolve relative paths against the original project base when writing logs.
+- **REQ-237**: MUST persist `DEBUG_LOG_FILE` as a non-empty string defaulting to `/tmp/PI-useReq.json`, and resolve relative paths against the original project base when writing logs.
 - **REQ-238**: MUST persist `DEBUG_LOG_ON_STATUS` with allowed values `any`, `idle`, `checking`, `running`, `merging`, and `error`, defaulting to `running`.
 - **REQ-239**: MUST persist enabled debug-tool names and enabled debug-prompt names as normalized arrays defaulting to empty.
 - **REQ-254**: MUST persist `DEBUG_STATUS_CHANGES` with allowed values `enable` and `disable`, defaulting to `disable`.
@@ -125,7 +134,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-242**: MUST derive per-tool debug rows from `PI_USEREQ_CUSTOM_TOOL_NAMES` and `PI_USEREQ_EMBEDDED_TOOL_NAMES`.
 - **REQ-243**: MUST derive per-prompt debug rows from `PROMPT_COMMAND_NAMES` as `req-*` names.
 - **REQ-244**: MUST append one JSON entry to `DEBUG_LOG_FILE` for each selected custom or embedded tool execution, including tool name, workflow state, input, result, and error flag.
-- **REQ-245**: MUST append JSON debug entries from selected `req-*` commands for required-doc checks, worktree creation, fast-forward merge, worktree deletion, and workflow events when `DEBUG_WORKFLOW_EVENTS=enable`.
+- **REQ-245**: MUST append JSON debug entries from selected `req-*` commands for required-doc checks, worktree creation, merge finalization, worktree deletion, and workflow events when `DEBUG_WORKFLOW_EVENTS=enable`.
 - **REQ-255**: MUST append `workflow_state` debug entries for every actual prompt-orchestration state transition only when `DEBUG_STATUS_CHANGES=enable`.
 - **REQ-276**: MUST complete orchestrated session closure when pi lifecycle events expose non-command contexts without `switchSession()`, while keeping the client attached to the original `base-path` session.
 - **REQ-278**: MUST preserve the in-memory prompt workflow state plus pending or active prompt request across switch-triggered `session_shutdown` events until the initiating handler or replacement-session lifecycle hooks complete prompt orchestration.
@@ -139,10 +148,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-231**: MUST order non-`files-*` custom-tool toggles alphabetically, append `files-*` custom-tool toggles alphabetically, and place default-disabled custom-tool toggles after default-enabled custom-tool toggles inside each custom subgroup.
 - **REQ-232**: MUST order embedded-tool toggles alphabetically and place default-disabled embedded-tool toggles after default-enabled embedded-tool toggles.
 - **REQ-063**: MUST derive configurable embedded pi CLI tools from runtime builtin tools named `read`, `bash`, `edit`, `write`, `find`, `grep`, and `ls`.
-- **REQ-064**: MUST default `files-tokens`, `files-references`, `files-compress`, `files-search`, `references`, `compress`, `search`, `tokens`, `files-static-check`, `static-check`, plus embedded `read`, `bash`, `edit`, and `write` to enabled.
+- **REQ-064**: MUST default `files-tokens`, `files-summarize`, `files-compress`, `files-search`, `summarize`, `references`, `compress`, `search`, `tokens`, `files-static-check`, `static-check`, plus embedded `read`, `bash`, `edit`, and `write` to enabled.
 - **REQ-066**: MUST omit `reset-context` and `context-reset` fields from persisted project configuration.
-- **REQ-067**: MUST send every rendered `req-<prompt>` payload into the current active session.
-- **REQ-068**: MUST use one prompt-delivery path that sends the rendered prompt through the forked execution session after the worktree switch by using only the replacement-session context for post-switch session-bound operations.
+- **REQ-067**: MUST send every bundled prompt-backed `req-<prompt>` payload into the current active session.
+- **REQ-068**: MUST use one prompt-delivery path that sends bundled prompt-backed `req-<prompt>` payloads through the forked execution session by using only the replacement-session context for post-switch session-bound operations.
 - **REQ-008**: MUST provide a `Language static code checkers` submenu that adds Command entries by guided language flow, removes configured language entries, toggles per-language enablement, and resets the static-check configuration.
 - **REQ-160**: MUST hardcode `Command` as the only user-configurable static-check module and omit module-selection UI from static-check configuration menus.
 - **REQ-161**: MUST hide `Dummy` from user-configurable static-check menus while preserving existing-config parsing and debug-driver support for `Dummy` entries.
@@ -152,9 +161,9 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-251**: MUST default `static-check.Python`, `JavaScript`, and `TypeScript` to `enabled=enable` with their documented Command checker entries.
 - **REQ-252**: MUST default every other supported `static-check.<language>` entry to `enabled=disable` with `checkers=[]`.
 - **REQ-009**: MUST refresh shared runtime path context, apply configured startup tools, reset workflow state to `idle` for `session_start` reasons `startup|new|reload`, and publish single-line `pi-usereq` status text.
-- **REQ-109**: MUST make the single-line status bar render the explicit runtime `current-path` value from `context-path` and omit `base`, `docs`, `src`, and `tests` path fields.
+- **REQ-109**: MUST omit `current-path`, `base`, `docs`, `src`, and `tests` path fields from the single-line status bar.
 - **REQ-111**: MUST omit prompt-delivery mode fields from the single-line status bar.
-- **REQ-112**: MUST render status-bar field names with the active theme `accent` token and non-error field values with the active theme `warning` token.
+- **REQ-112**: MUST render status-bar field names with the active theme `accent` token and non-error field values with the active theme `warning` token unless a field-specific requirement overrides the value token.
 - **REQ-113**: MUST register shared event wrappers for `resources_discover`, `session_start`, `session_before_switch`, `session_before_fork`, `session_before_compact`, `session_compact`, and `session_shutdown`.
 - **REQ-114**: MUST register shared event wrappers for `session_before_tree`, `session_tree`, `context`, `before_provider_request`, `before_agent_start`, `agent_start`, and `agent_end`.
 - **REQ-115**: MUST register shared event wrappers for `turn_start`, `turn_end`, `message_start`, `message_update`, `message_end`, `tool_execution_start`, and `tool_execution_update`.
@@ -162,20 +171,25 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-117**: MUST route every intercepted hook through `updateExtensionStatus` with the originating hook name and event payload, even when no hook-specific side effect exists.
 - **REQ-118**: MUST obtain latest context-usage facts from `ctx.getContextUsage()` or an equivalent runtime API and store them in extension session state.
 - **REQ-119**: MUST refresh stored context-usage facts during `session_start` and after intercepted events before rebuilding the status bar when newer data is available.
-- **REQ-120**: MUST render single-line status fields in this order: `status`, `current-path`, `context`, `elapsed`, `sound`.
-- **REQ-121**: MUST render `context` immediately after `current-path` with separator ` • ` and one fixed-width gauge icon.
-- **REQ-122**: MUST map `context` usage to `▕_▏`, `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` for `0`, `>0-25`, `>25-50`, `>50-90`, and `>90-100` percent bands.
+- **REQ-120**: MUST render single-line status fields in this order: `status`, `branch`, `context`, `elapsed`, `sound`.
+- **REQ-121**: MUST render `branch` immediately after `status` with separator ` • ` and the active git branch name.
+- **REQ-283**: MUST resolve `branch` from the current `context-path` git HEAD during every status-bar rebuild so worktree switches and base-path restoration update immediately.
+- **REQ-284**: MUST render `context` immediately after `branch` with separator ` • ` and one fixed-width gauge icon.
+- **REQ-122**: MUST map `context` usage to `▕_▏`, `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` for `0`, `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75` percent bands.
 - **REQ-123**: MUST render `elapsed` immediately after `context` as `⏱︎ <active> ⚑ <last> ⌛︎<total>`.
 - **REQ-124**: MUST render `⏱︎ --:--` when no prompt is active, and `⚑ --:--` plus `⌛︎--:--` until the corresponding timers receive a normally completed prompt duration.
 - **REQ-125**: MUST render timed `elapsed` segments as `M:SS`, keep minutes unbounded above 59, zero-pad seconds to two digits, and preserve `⚑` plus `⌛︎` when escape-triggered cancellation ends the active run.
-- **REQ-126**: MUST render `context` gauge icons with theme `warning`, except the overflow state uses theme `error`.
-- **REQ-127**: MUST render `context` as blinking theme `warning` `▕█▏` when normalized usage is `>90-100` percent and terminal blink control is supported.
-- **REQ-233**: MUST render `context` as blinking theme `error` `▕█▏` when normalized usage exceeds 100 percent and terminal blink control is supported.
-- **REQ-128**: MUST render `context` as theme `error` `▕█▏` when normalized usage exceeds 100 percent and terminal blink control is unavailable.
-- **REQ-131**: MUST persist a sound level with allowed values `none`, `low`, `mid`, and `high`, defaulting to `none`.
-- **REQ-132**: MUST execute the configured sound command when the corresponding prompt-end sound event toggle is enabled and the sound level is not `none`.
+- **REQ-126**: MUST render `context` gauge icons below 90 percent with the same non-error theme token used by `status`, and theme `error` at 90 percent or above.
+- **REQ-127**: MUST render `context` as non-blinking theme `error` `▕█▏` when normalized usage is `>=90-<100` percent.
+- **REQ-233**: MUST render `context` as blinking theme `error` `▕█▏` when normalized usage is `>=100` percent and terminal blink control is supported.
+- **REQ-128**: MUST render `context` as theme `error` `▕█▏` when normalized usage is `>=100` percent and terminal blink control is unavailable.
+- **REQ-131**: MUST persist a boot sound level with allowed values `none`, `low`, `mid`, and `high`, defaulting to `none`.
+- **REQ-132**: MUST execute the configured sound command when the corresponding prompt-end sound event toggle is enabled and the active runtime sound level is not `none`.
 - **REQ-133**: MUST persist configurable shell-command strings for sound levels `low`, `mid`, and `high`, and MUST substitute `%%INSTALLATION_PATH%%` with the runtime extension installation path before execution.
-- **REQ-134**: MUST persist a configurable sound-level toggle shortcut, defaulting to `alt+s`, and MUST cycle sound levels in the order `none`, `low`, `mid`, `high`, `none`.
+- **REQ-134**: MUST persist a configurable sound-level toggle shortcut, defaulting to `alt+s`.
+- **REQ-285**: MUST load the active runtime sound level from persisted `notify-sound` during `session_start`.
+- **REQ-286**: MUST cycle only the active runtime sound level when the configured shortcut fires.
+- **REQ-287**: MUST NOT update `.pi-usereq.json` when the configured shortcut fires.
 - **REQ-137**: MUST make the `Notifications` menu render contiguous command-notify, sound, and Pushover configuration blocks in that order.
 - **REQ-163**: MUST persist a global Pushover enable flag defaulting to disabled.
 - **REQ-164**: MUST expose a `Pushover events` submenu and MUST keep non-event Pushover settings directly in `Notifications`.
@@ -191,10 +205,12 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-175**: MUST persist `PI_NOTIFY_CMD` defaulting to `notify-send -i %%INSTALLATION_PATH%%/resources/images/pi.dev.png -a "PI-useReq" "%%PROMT%% @ %%BASE%% [%%TIME%%]" "%%RESULT%%"`.
 - **REQ-176**: MUST implement command-notify exclusively by executing `PI_NOTIFY_CMD` when command-notify is globally enabled and the corresponding prompt-end notify event toggle is enabled.
 - **REQ-178**: MUST persist sound event toggles in keys `notify-sound-on-completed`, `notify-sound-on-interrupted`, and `notify-sound-on-failed`, defaulting to completed enabled and interrupted plus failed disabled.
-- **REQ-179**: MUST label sound rows as `Enable sound` and `Sound command (low vol.)`, `Sound command (mid vol.)`, and `Sound command (high vol.)`.
-- **REQ-180**: MUST render `sound` immediately after `elapsed`, showing one of `none`, `low`, `mid`, or `high`.
+- **REQ-179**: MUST label sound rows as `Enable sound (boot value)` and `Sound command (low vol.)`, `Sound command (mid vol.)`, and `Sound command (high vol.)`.
+- **REQ-180**: MUST render `sound` immediately after `elapsed`, showing the active runtime sound level as `none`, `low`, `mid`, or `high`.
 - **REQ-181**: MUST make the `Notifications` menu expose `Enable notification`, `Notification events`, and `Notify command` before sound rows.
-- **REQ-183**: MUST make the `Notifications` menu expose `Sound events` immediately after `Enable sound` and before sound hotkey plus command rows.
+- **REQ-183**: MUST make the `Notifications` menu expose `Sound events` immediately after `Enable sound (boot value)` and before sound hotkey plus command rows.
+- **REQ-288**: MUST persist menu-selected `notify-sound` changes to `.pi-usereq.json` without changing the active runtime sound level.
+- **REQ-289**: MUST render configuration-menu sound values from persisted `notify-sound`, even when the active runtime sound level differs.
 - **REQ-184**: MUST persist Pushover event toggles in keys `notify-pushover-on-completed`, `notify-pushover-on-interrupted`, and `notify-pushover-on-failed`, defaulting to completed enabled and interrupted plus failed disabled.
 - **REQ-185**: MUST persist `Pushover title` defaulting to `%%PROMT%% @ %%BASE%% [%%TIME%%]` and `Pushover text` defaulting to `%%RESULT%%\n%%ARGS%%`.
 - **REQ-186**: MUST substitute `%%PROMT%%`, `%%BASE%%`, `%%TIME%%`, `%%ARGS%%`, and `%%RESULT%%` at runtime inside `Pushover title` and `Pushover text`.
@@ -203,36 +219,54 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-190**: MUST label top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, `Debug`, and `Show configuration`.
 - **REQ-191**: MUST order top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, `Debug`, `Show configuration`, and `Reset defaults`.
 - **REQ-192**: MUST preserve the selected settings-menu row after toggling or editing a setting value.
-- **REQ-193**: MUST append `Reset defaults` as the final row of every configuration menu and descendant selector menu, and MUST NOT render `Save and close`.
+- **REQ-193**: MUST append `Reset defaults` as a final row without right-aligned value text in every configuration menu and descendant selector menu, and MUST NOT render `Save and close`.
 - **REQ-194**: MUST make top-level `Reset defaults` show changed values with previous and next values, require explicit confirmation, restore full-tree defaults, and save immediately.
 - **REQ-195**: MUST make non-top-level `Reset defaults` show changed values with previous and next values, require explicit confirmation, restore subtree defaults, and save immediately.
 - **REQ-196**: MUST persist a global command-notify enable flag defaulting to disabled.
 - **REQ-197**: MUST summarize top-level `Notifications` as `notification:<state> • sound:<level> • pushover:<state>`.
 - **REQ-198**: MUST render `Notification events`, `Sound events`, and `Pushover events` as identical submenu lists with right-aligned `on|off` values for `Prompt completed`, `Prompt interrupted`, and `Prompt failed`.
 - **REQ-199**: MUST render `%%RESULT%%` as `successed`, `aborted`, or `failed` for completed, interrupted, and failed prompt-end outcomes.
-- **REQ-200**: MUST run slash-command-owned git validation immediately after the `idle` gate at the start of every `req-<prompt>` command and abort before prompt dispatch on failure.
+- **REQ-200**: MUST run slash-command-owned git validation immediately after the `idle` gate at the start of every `req-*` slash command except `req-reset` and abort before command execution on failure.
 - **REQ-201**: MUST require `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md` before `analyze`, `change`, `check`, `cover`, `fix`, `flowchart`, `new`, `readme`, `recreate`, `refactor`, and `renumber`.
-- **REQ-202**: MUST require `REQUIREMENTS.md` before `implement` and `references`, and MUST skip required-doc prechecks for `create`, `workflow`, and `write`.
-- **REQ-203**: MUST abort a `req-<prompt>` command before worktree creation and prompt dispatch when any prompt-required doc is missing and surface the missing canonical path plus remediation prompt command.
+- **REQ-202**: MUST require `REQUIREMENTS.md` before `implement`, and MUST skip required-doc prechecks for `create`, `references`, `workflow`, and `write`.
+- **REQ-203**: MUST abort a bundled prompt-backed `req-<prompt>` command before worktree creation and prompt dispatch when any prompt-required doc is missing, surfacing the missing canonical path plus remediation prompt command.
 - **REQ-212**: MUST persist `AUTO_GIT_COMMIT` with allowed values `enable` and `disable`, defaulting to `enable`.
 - **REQ-204**: MUST persist `GIT_WORKTREE_ENABLED` with allowed values `enable` and `disable`, defaulting to `enable`.
 - **REQ-205**: MUST persist `GIT_WORKTREE_PREFIX` as the configurable prefix used by `worktree-dir` generation, defaulting to `PI-useReq-`.
 - **REQ-215**: MUST force the effective `GIT_WORKTREE_ENABLED` value to `disable` whenever `AUTO_GIT_COMMIT=disable`.
 - **REQ-216**: MUST render `Git worktree` and `Worktree prefix` as dimmed non-editable rows whenever `AUTO_GIT_COMMIT=disable`.
 - **REQ-206**: MUST derive `worktree-dir` as `<prefix><project>-<sanitized-branch>-<YYYYMMDDHHMMSS>` and `worktree-path` as `<parent-path>/<worktree-dir>/<base-dir>` when worktrees are enabled.
-- **REQ-271**: MUST create one dedicated worktree under `parent-path`, fork the current active session into an execution session file whose header cwd equals `worktree-path`, and switch the active pi CLI session to that file before agent start.
+- **REQ-271**: MUST make bundled prompt-backed `req-<prompt>` commands create one dedicated worktree under `parent-path`, fork the current active session, and switch the active pi CLI session before agent start.
 - **REQ-207**: MUST keep `context-path`, `ctx.cwd`, and `process.cwd()` at `base-path` when worktree creation is disabled.
-- **REQ-208**: MUST restore the original session-backed `base-path`, fast-forward-only merge from `base-path`, and delete the worktree plus branch after successful orchestrated session closure.
+- **REQ-208**: MUST restore the original session-backed `base-path`, merge the successful worktree branch from `base-path`, and delete the worktree plus branch after successful closure.
+- **REQ-290**: MUST preserve the successful worktree execution transcript in the restored client-visible session after successful closure.
+- **REQ-291**: MUST detect staged or unstaged `base-path` changes before successful closure merge and execute `git stash`, merge, and `git stash pop` in that order when changes exist.
+- **REQ-292**: MUST complete successful stash-assisted closure without surfacing an error and MUST emit a warning that the restored `base-path` is not clean after merge.
 - **REQ-209**: MUST restore the original session-backed `base-path`, notify the pi CLI of closure failure, and retain the worktree plus branch when orchestrated session closure is interrupted, failed, aborted, or incomplete.
 - **REQ-221**: MUST maintain one prompt-orchestration state machine with states `idle`, `checking`, `running`, `merging`, and `error`.
-- **REQ-222**: MUST render `status` immediately before `base` as the current prompt-orchestration state and refresh it on every internal or pi CLI state transition.
+- **REQ-222**: MUST render `status` as the first single-line status field and refresh it on every internal or pi CLI state transition.
 - **REQ-223**: MUST render `status:error` with theme `error` plus terminal blink when supported, and other `status` values with the existing non-error status-bar convention.
-- **REQ-224**: MUST reject a `req-<prompt>` command before any operation when workflow state is not `idle`, surfacing the error to pi CLI.
-- **REQ-225**: MUST transition workflow state to `checking` after the `idle` gate and keep it there through required-doc checks, worktree generation, worktree verification, and prompt handoff preparation.
-- **REQ-226**: MUST transition workflow state to `error` when required-doc checks or worktree creation fails during `req-<prompt>` preflight.
-- **REQ-227**: MUST transition workflow state to `running` only after required-doc checks, worktree generation, worktree verification, and prompt-session handoff succeed, and MUST make that transition the last slash-command action except logging.
+- **REQ-224**: MUST reject every `req-*` slash command except `req-reset` before any operation when workflow state is not `idle`, surface the error to pi CLI, and transition workflow state to `error`.
+- **REQ-225**: MUST make bundled prompt-backed `req-<prompt>` commands transition workflow state to `checking` after the `idle` gate and keep it there through required-doc checks, worktree preparation, and prompt handoff preparation.
+- **REQ-226**: MUST transition workflow state to `error` when required-doc checks or worktree creation fails during bundled prompt-backed `req-<prompt>` preflight.
+- **REQ-227**: MUST make bundled prompt-backed `req-<prompt>` commands transition workflow state to `running` only after required-doc checks, worktree preparation, worktree verification, and prompt-session handoff succeed.
+- **REQ-299**: MUST make `req-references`, after passing the shared `idle` gate, transition workflow state to `checking`, validate slash-command-owned git state, and transition directly to `running` without worktree creation, session switching, or LLM-session initialization.
+- **REQ-300**: MUST make `req-references` execute the same reference-generation and overwrite logic as `references`, writing configured-source reference markdown to `<base-path>/<docs-dir>/REFERENCES.md`.
+- **REQ-301**: MUST make `req-references` stage only updated `<docs-dir>/REFERENCES.md` and create one git commit with exact message `docs(references): Update REFERENCES.md document. [useReq]`.
+- **REQ-302**: MUST make successful `req-references` completion verify repository cleanliness, notify pi CLI success, and transition workflow state to `idle` before the command handler returns.
+- **REQ-303**: MUST make failing `req-references` execution notify pi CLI, transition workflow state to `error`, and surface git or reference-generation failures without LLM-session initialization.
+- **REQ-304**: MUST register `req-reset` as a dedicated extension command with description `Reset req workflow state, restore base-path, and remove generated worktrees` and MUST NOT depend on a bundled prompt Markdown file.
+- **REQ-305**: MUST make `req-reset` execute without prompt dispatch, LLM-session initialization, or worktree creation.
+- **REQ-306**: MUST allow `req-reset` invocation from any current workflow state and MUST NOT reject it when workflow state is not `idle`.
+- **REQ-307**: MUST make `req-reset` preserve the visible execution transcript while restoring the original session-backed `base-path`.
+- **REQ-308**: MUST make `req-reset` restore the original session-backed `base-path` when persisted prompt-orchestration state targets a worktree-backed execution session.
+- **REQ-309**: MUST make `req-reset` force-remove every sibling worktree under `parent-path` whose name matches `<prefix><project>-<sanitized-branch>-<YYYYMMDDHHMMSS>`.
+- **REQ-310**: MUST make `req-reset` force-remove every local branch under `git-path` whose name matches `<prefix><project>-<sanitized-branch>-<YYYYMMDDHHMMSS>`.
+- **REQ-311**: MUST derive `req-reset` cleanup matchers from the same prefix, project, and branch-sanitization rules used by prompt-command worktree generation.
+- **REQ-312**: MUST make successful `req-reset` clear persisted prompt-orchestration state, transition workflow state to `idle`, and notify pi success after cleanup completes.
+- **REQ-313**: MUST make failing `req-reset` surface restoration or cleanup failures, transition workflow state to `error`, and preserve already-completed cleanup effects.
 - **REQ-228**: MUST transition workflow state to `merging` immediately before merge and worktree/branch deletion begin during successful orchestrated session closure.
-- **REQ-229**: MUST transition workflow state to `error` and notify the pi CLI when base-path restoration, fast-forward merge, or worktree/branch deletion verification fails during orchestrated session closure.
+- **REQ-229**: MUST transition workflow state to `error` and notify the pi CLI when base-path restoration, merge, or worktree/branch deletion verification fails during orchestrated session closure.
 - **REQ-230**: MUST transition workflow state to `idle` before the orchestrated session-closure handler returns.
 - **REQ-219**: MUST verify created worktree registration via `git worktree list`, branch presence via `git branch` list, and filesystem path existence before changing the prompt execution path or dispatching a prompt message.
 - **REQ-256**: MUST store `base-path`, `context-path`, `git-path`, `parent-path`, `base-dir`, `worktree-dir`, `worktree-path`, branch name, original session file, and execution session file inside prompt-orchestration runtime state.
@@ -245,10 +279,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-217**: MUST reset `⚑` plus `⌛︎` only during `session_start` with reason `startup` or `reload`.
 - **REQ-173**: MUST optimize every affected agent-tool response by reusing Python-compatible monolithic renderer structure, preserving source-leading tabs in source-derived text, and omitting mirrored JSON bodies, duplicate facts, and caller-known request echoes.
 - **REQ-010**: MUST count tokens with `js-tiktoken` `cl100k_base`, count characters and lines, and make `files-tokens` return the Python-compatible pack-summary text through `content[0].text`.
-- **REQ-011**: MUST make `files-references` analyze supported source files and return the Python-compatible references markdown through `content[0].text`.
+- **REQ-011**: MUST make `files-summarize` analyze supported source files and return the Python-compatible summary markdown through `content[0].text`.
 - **REQ-012**: MUST compress supported source files by removing comments and blank lines, preserving full indentation for Python, Haskell, and Elixir, preserving leading-tab indentation for other languages, and optionally preserving original line numbers.
 - **REQ-013**: MUST search explicit files by tag filter and name regex, then return Python-compatible markdown matches with signatures, line ranges, Doxygen bullets, and stripped code excerpts.
-- **REQ-014**: MUST make `references` scan configured `src-dir` files and return the Python-compatible file-structure-plus-references markdown through `content[0].text`.
+- **REQ-014**: MUST make `summarize` scan configured `src-dir` files and return the Python-compatible file-structure-plus-summary markdown through `content[0].text`.
 - **REQ-015**: MUST make CLI project-scope compression scan configured `src-dir` files and emit Python-compatible compressed markdown blocks for every supported file.
 - **REQ-016**: MUST make `find` scan configured `src-dir` files using the requested tag filter and regular expression, then emit Python-compatible markdown matches.
 - **REQ-017**: MUST make `tokens` count only existing canonical docs `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md`, reuse the `files-tokens` pack-summary text contract, and fail when none exist.
@@ -259,11 +293,11 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-073**: MUST omit caller-known request echoes, mirrored file tables, and duplicate metrics from `files-tokens` and `tokens` runtime payloads.
 - **REQ-074**: MUST reserve `files-tokens` and `tokens` `details` for execution metadata and MUST NOT mirror content text or derived guidance there.
 - **REQ-075**: MUST surface `files-tokens` and `tokens` skip or read-error observations through `details.execution` diagnostics instead of structured runtime file entries.
-- **REQ-076**: MUST make `files-references` and `references` pass exactly one monolithic markdown document to the LLM through `content[0].text`.
-- **REQ-077**: MUST keep `files-references` markdown aligned to the Python references renderer in section ordering and non-source formatting while preserving leading tabs in source-derived lines.
-- **REQ-078**: MUST prepend project-scope `references` output with the file-structure markdown block before the per-file references markdown.
-- **REQ-079**: MUST omit mirrored JSON structures and request echoes from `files-references` and `references` runtime payloads.
-- **REQ-080**: MUST register `files-references` and `references` with machine-oriented descriptions describing scope, monolithic markdown contract, and stable failure conditions.
+- **REQ-076**: MUST make `files-summarize` and `summarize` pass exactly one monolithic markdown document to the LLM through `content[0].text`.
+- **REQ-077**: MUST keep `files-summarize` markdown aligned to the Python summary renderer in section ordering and non-source formatting while preserving leading tabs in source-derived lines.
+- **REQ-078**: MUST prepend project-scope `summarize` output with the file-structure markdown block before the per-file summary markdown.
+- **REQ-079**: MUST omit mirrored JSON structures and request echoes from `files-summarize` and `summarize` runtime payloads.
+- **REQ-080**: MUST register `files-summarize` and `summarize` with machine-oriented descriptions describing scope, monolithic markdown contract, and stable failure conditions.
 - **REQ-081**: MUST make `files-compress` and `compress` pass exactly one monolithic markdown document to the LLM through `content[0].text`.
 - **REQ-082**: MUST keep `files-compress` and `compress` content aligned to the Python compression renderer in headers, line-range metadata, code fences, and file ordering while preserving leading tabs in retained source lines.
 - **REQ-083**: MUST make `enableLineNumbers` for `files-compress` and `compress` toggle original source line prefixes inside emitted fenced code blocks without changing header or line-range formatting.
@@ -314,12 +348,12 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-253**: MUST set `static-check.<language>.enabled=enable` whenever guided or CLI `--enable-static-check` entry creation targets that language.
 - **REQ-036**: MUST preserve existing `static-check` entries, append non-duplicate `--enable-static-check` entries in argument order, and treat canonical language, module, cmd, and params as the duplicate identity.
 - **REQ-037**: MUST reject `--enable-static-check` `Command` entries whose executable is unavailable on `PATH` and MUST NOT modify persisted project configuration when validation fails.
-- **REQ-038**: MUST honor `--verbose` only for `files-references`, `files-compress`, `files-find`, `references`, `compress`, and `find`, emitting command progress to stderr while leaving stdout payload format unchanged.
+- **REQ-038**: MUST honor `--verbose` only for `files-summarize`, `files-compress`, `files-find`, `summarize`, `compress`, and `find`, emitting command progress to stderr while leaving stdout payload format unchanged.
 - **REQ-039**: MUST support `--enable-line-numbers` only for `files-compress`, `compress`, `files-find`, and `find`, and MUST leave corresponding outputs unnumbered when the flag is absent.
 - **REQ-040**: MUST store canonical expected CLI result fixtures as UTF-8 text files under `tests/fixtures_attended_results/`, preserving normalized exit code, stdout, and stderr for each archived scenario.
 - **REQ-041**: MUST canonicalize environment-dependent path and timestamp segments in archived and observed CLI results with stable placeholder tokens before exact comparison.
-- **REQ-042**: MUST archive explicit-file scenarios for `files-tokens`, `files-references`, `files-compress`, `files-find`, and `test-static-check` across every file under `tests/fixtures/`.
-- **REQ-043**: MUST archive repository scenarios for `references`, `compress`, `find`, `tokens`, `enable-static-check`, `files-static-check`, and `static-check`.
+- **REQ-042**: MUST archive explicit-file scenarios for `files-tokens`, `files-summarize`, `files-compress`, `files-find`, and `test-static-check` across every file under `tests/fixtures/`.
+- **REQ-043**: MUST archive repository scenarios for `summarize`, `compress`, `find`, `tokens`, `enable-static-check`, `files-static-check`, and `static-check`.
 - **REQ-138**: MUST make `.github/workflows/release-npm.yml` trigger release automation from pushed tags matched by the existing workflow filter `v[0-9]+.[0-9]+.[0-9]+`.
 - **REQ-139**: MUST skip downstream release work unless `check-branch` confirms the tagged commit is contained in `origin/master`.
 - **REQ-140**: MUST configure Node.js plus npm registry authentication, run `npm ci`, remove manifest `private`, and publish with provenance and public access using `secrets.NPM_TOKEN`.
@@ -332,8 +366,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-144**: MUST default `PI_NOTIFY_SOUND_HIGH_CMD` to `paplay --volume=65535 %%INSTALLATION_PATH%%/resources/sounds/Soft-high-tech-notification-sound-effect.mp3`.
 - **REQ-145**: MUST derive static `git-path` during bootstrap from `base-path` and repository ancestry rules, ignoring project-configuration JSON values.
 - **REQ-146**: MUST NOT read or persist `base-path` or `git-path` in project-configuration JSON.
-- **REQ-148**: MUST render status-bar `current-path` as dynamic `context-path`, home-relative with `~` when applicable.
-- **REQ-149**: MUST label notification settings actions as `Notify command`, `Enable sound`, `Sound toggle hotkey bind`, `Sound command (low|mid|high vol.)`, `Pushover User Key/Delivery Group Key`, and `Pushover Token/API Token Key`.
+- **REQ-149**: MUST label notification settings actions as `Notify command`, `Enable sound (boot value)`, `Sound toggle hotkey bind`, `Sound command (low|mid|high vol.)`, `Pushover User Key/Delivery Group Key`, and `Pushover Token/API Token Key`.
 - **REQ-150**: MUST omit overview rows and reference-only actions from the main, notification, startup-tool, and static-check configuration menus.
 - **REQ-151**: MUST render `pi-usereq`, notification, static-check, and startup-tool menus with left-aligned labels and right-aligned current values using the active CLI settings-list theme semantics.
 - **REQ-156**: MUST restrict extension-owned status and settings rendering to CLI-supported theme APIs and documented theme tokens.
@@ -345,8 +378,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-001**: MUST verify extension activation registers every documented prompt command, agent tool, and configuration command while omitting tool-name slash commands, `test-static-check`, and the removed standalone config-viewer command.
 - **TST-002**: MUST verify installed bundled prompt, commit-instruction, template, and guideline resources remain readable from `installation-path`.
 - **TST-060**: MUST verify prompt rendering replaces `%%PROMPT%%` and expands `%%COMMIT%%` from rendered `git_commit.md` or `git_read-only.md` according to `AUTO_GIT_COMMIT`.
-- **TST-003**: MUST verify standalone `files-tokens` outputs match the Python oracle, `--test-static-check` dummy or command outputs match archived fixtures, and `files-references`, `files-compress`, plus `files-find` preserve leading source tabs.
-- **TST-004**: MUST verify project `tokens` outputs match the Python oracle, verify `files-static-check` plus `static-check` against archived fixtures, and verify `references`, `compress`, plus `find` preserve leading source tabs.
+- **TST-003**: MUST verify standalone `files-tokens` outputs match the Python oracle, `--test-static-check` dummy or command outputs match archived fixtures, and `files-summarize`, `files-compress`, plus `files-find` preserve leading source tabs.
+- **TST-004**: MUST verify project `tokens` outputs match the Python oracle, verify `files-static-check` plus `static-check` against archived fixtures, and verify `summarize`, `compress`, plus `find` preserve leading source tabs.
 - **TST-005**: MUST verify the configuration menu saves `docs-dir`, `AUTO_GIT_COMMIT`, `GIT_WORKTREE_ENABLED`, and `GIT_WORKTREE_PREFIX` immediately after each change, preserves toggle ordering, and omits prompt-delivery controls plus `Save and close`.
 - **TST-084**: MUST verify configuration persistence trims trailing `/` and keeps `docs-dir`, `tests-dir`, and `src-dir` relative.
 - **TST-046**: MUST verify `Language static code checkers` omits module selection, raw-spec actions, supported-language reference actions, and hides `Dummy`, `Pylance`, and `Ruff` from user-configurable actions.
@@ -354,23 +387,27 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-078**: MUST verify default configuration persists documented per-language `enabled` flags and checker lists for `C`, `C++`, `Python`, `JavaScript`, and `TypeScript`.
 - **TST-079**: MUST verify `files-static-check` and `static-check` execute zero checkers and expose empty configured-checker lists when the target language `enabled=disable`.
 - **TST-006**: MUST verify `session_start` activates configured startup tools, resets workflow state to `idle` for `startup|new|reload`, and updates the single-line `pi-usereq` status bar.
-- **TST-031**: MUST verify the status bar renders `status` before the home-relative `current-path`, omits `base`, `docs`, `src`, `tests`, `git`, and `tools`, and preserves documented field-value theme separation.
+- **TST-031**: MUST verify the status bar renders `status` before `branch`, omits `current-path`, `base`, `docs`, `src`, `tests`, `git`, and `tools`, and preserves documented field-value theme separation.
 - **TST-032**: MUST verify extension registration installs wrappers for all documented lifecycle hooks and routes replayed hook payloads through `updateExtensionStatus`.
-- **TST-033**: MUST verify the status bar renders ordered `status`, `current-path`, `context`, `elapsed`, and `sound` fields plus the documented icon-based `context` gauge thresholds.
-- **TST-037**: MUST verify the `Notifications` menu persists notification and sound settings through `Notification events` and `Sound events` submenus using the documented labels, order, reset-confirmation flows, immediate-save behavior, and no `Save and close` rows.
-- **TST-038**: MUST verify the sound-toggle shortcut cycles persisted sound levels and refreshes the status bar with the updated `sound` field.
+- **TST-033**: MUST verify the status bar renders ordered `status`, `branch`, `context`, `elapsed`, and `sound` fields plus the documented icon-based `context` gauge thresholds.
+- **TST-037**: MUST verify the `Notifications` menu persists notification and boot-sound settings through `Notification events` and `Sound events` submenus using the documented labels, order, reset-confirmation flows, immediate-save behavior, and no `Save and close` rows.
+- **TST-038**: MUST verify the sound-toggle shortcut cycles only the active runtime sound level, leaves `.pi-usereq.json` unchanged, and refreshes the status bar with the updated `sound` field.
+- **TST-097**: MUST verify `session_start` loads the active runtime sound level from persisted `notify-sound`.
+- **TST-098**: MUST verify menu-selected boot sound changes persist to `.pi-usereq.json` without changing the active runtime sound level.
 - **TST-047**: MUST verify the `Notifications` menu exposes `Pushover events` before direct Pushover settings, keeps `Enable pushover` dimmed and locked until both credential fields are non-empty, and persists Pushover event and credential values.
 - **TST-072**: MUST verify `Pushover text` displays escaped control sequences in menus and decodes the documented escape sequences from input before persistence.
 - **TST-048**: MUST verify native Pushover requests honor global enable, completed/interrupted/failed Pushover toggles, credentials, priority, title, and text placeholder substitution including `%%RESULT%%` for enabled prompt-end outcomes.
-- **TST-049**: MUST verify the status bar renders ordered `status`, `current-path`, `context`, `elapsed`, and `sound` fields and appends `sound:<level>`.
+- **TST-049**: MUST verify the status bar renders ordered `status`, `branch`, `context`, `elapsed`, and `sound` fields and appends `sound:<level>`.
 - **TST-050**: MUST verify `PI_NOTIFY_CMD` placeholder substitution including `%%RESULT%%` and routing honor global notify enable plus completed/interrupted/failed notify toggles.
 - **TST-034**: MUST verify `ctx.getContextUsage()` snapshots refresh status updates and `elapsed` preserves `⚑` plus `⌛︎` across escape-triggered cancellation.
 - **TST-062**: MUST verify `Show configuration` saves pending config, closes the active configuration menu tree, and writes the persisted `.pi-usereq.json` file text into the editor.
 - **TST-063**: MUST verify `⚑` plus `⌛︎` survive `session_start` reason `new` and reset on `session_start` reason `reload`.
-- **TST-045**: MUST verify default configuration enables auto git commit, disables debug, notify, and Pushover globally, initializes sound to `none`, applies the documented debug and notification defaults, and persists the documented notify and Pushover templates.
-- **TST-051**: MUST verify sound routing honors the selected sound state and completed/interrupted/failed sound toggles.
-- **TST-035**: MUST verify unavailable or 0-percent context usage renders `▕_▏` with the theme `warning` token.
-- **TST-036**: MUST verify context usage `>90-100` renders blinking warning `▕█▏`, and `>100` renders blinking error `▕█▏` or non-blinking error `▕█▏` when blink control is unavailable.
+- **TST-045**: MUST verify default configuration enables auto git commit, disables debug, notify, and Pushover globally, initializes sound to `none`, sets `DEBUG_LOG_FILE=/tmp/PI-useReq.json`, and persists the documented notify and Pushover templates.
+- **TST-051**: MUST verify sound routing honors the active runtime sound state and completed/interrupted/failed sound toggles.
+- **TST-035**: MUST verify unavailable or 0-percent context usage renders `▕_▏` with the same non-error theme token used by `status`.
+- **TST-096**: MUST verify context usage `>0-<25`, `>=25-<50`, `>=50-<75`, and `>=75-<90` render `▕▂▏`, `▕▄▏`, `▕▆▏`, and `▕█▏` with the same non-error theme token used by `status`.
+- **TST-036**: MUST verify context usage `>=90-<100` renders non-blinking error `▕█▏`, and `>=100` renders blinking error `▕█▏` or non-blinking error `▕█▏` when blink control is unavailable.
+- **TST-095**: MUST verify status-bar `branch` resolves from current `context-path` git HEAD and refreshes across worktree switches plus base-path restoration.
 - **TST-043**: MUST verify configuration menus reuse the active CLI settings-list theme semantics for labels, values, descriptions, cursor, and hints.
 - **TST-009**: MUST verify `package.json` declares ESM packaging, the single pi extension entry, and the standard `test`, `test:watch`, and `cli` scripts.
 - **TST-010**: MUST verify `tsconfig.json` declares `NodeNext`, `strict`, `noEmit`, and includes both `src/**/*.ts` and `tests/**/*.ts`.
@@ -378,8 +415,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-030**: MUST verify pi.dev-aware prompt rendering injects an explicit interface-contract mandate covering `docs/pi.dev/coding-agent-docs/` and documents referenced by `docs/pi.dev/agent-document-manifest.json`.
 - **TST-087**: MUST verify pi.dev-aware prompt rendering requires `pi.dev-src/pi-mono` validation when manifest or `docs/pi.dev/coding-agent-docs/` guidance is ambiguous for extension-to-pi-client behavior.
 - **TST-088**: MUST verify pi.dev-aware prompt rendering requires `pi.dev-src/pi-mono` validation for bug fixes or problem resolution influenced by extension-to-pi-client interface implementations.
-- **TST-012**: MUST verify TypeScript CLI parity for standalone command-option regressions covering `--files-tokens`, `--files-references`, `--files-compress`, `--files-find`, `--test-static-check`, `--enable-line-numbers`, `--enable-static-check`, and `--verbose`.
-- **TST-013**: MUST verify TypeScript CLI parity for project-scoped command-option regressions covering `--references`, `--compress`, `--find`, `--tokens`, `--files-static-check`, and `--static-check`.
+- **TST-012**: MUST verify TypeScript CLI parity for standalone command-option regressions covering `--files-tokens`, `--files-summarize`, `--files-compress`, `--files-find`, `--test-static-check`, `--enable-line-numbers`, `--enable-static-check`, and `--verbose`.
+- **TST-013**: MUST verify TypeScript CLI parity for project-scoped command-option regressions covering `--summarize`, `--compress`, `--find`, `--tokens`, `--files-static-check`, and `--static-check`.
 - **TST-014**: MUST maintain an executable mapping from each imported command-option regression case to one TypeScript test case identifier and fail verification when any mapped case is missing.
 - **TST-015**: MUST verify archive-backed standalone CLI scenarios load expected results from `tests/fixtures_attended_results/standalone` and compare exact normalized exit code, stdout, and stderr for every file under `tests/fixtures/`.
 - **TST-016**: MUST verify archive-backed repository CLI scenarios load expected results from `tests/fixtures_attended_results/project` and compare exact normalized exit code, stdout, and stderr for the archived command set.
@@ -388,8 +425,17 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-019**: MUST verify offline harness command and tool replay invoke registered handlers, preserve requested cwd semantics, and capture prompt payloads, tool results, and UI side effects.
 - **TST-020**: MUST verify SDK parity comparison reports aligned inventories as clean, reports requested mismatch categories, and `package.json` declares the `debug:ext*` harness scripts.
 - **TST-021**: MUST verify `scripts/pi-usereq-debug.sh tool` forwards `--params` unchanged and converts `--args` text into the JSON object forwarded through `--params`.
-- **TST-022**: MUST verify `files-references` and `references` agent-tool outputs place monolithic references markdown with preserved leading tabs in `content[0].text` and restrict `details` to execution metadata.
-- **TST-023**: MUST verify harness inspection surfaces `files-references` and `references` descriptions covering scope, monolithic markdown output, and failure details.
+- **TST-022**: MUST verify `files-summarize` and `summarize` agent-tool outputs place monolithic summary markdown with preserved leading tabs in `content[0].text` and restrict `details` to execution metadata.
+- **TST-023**: MUST verify harness inspection surfaces `files-summarize` and `summarize` descriptions covering scope, monolithic markdown output, and failure details.
+- **TST-099**: MUST verify extension activation and tool menus include `references` with the documented agent-tool-only registration and default-enabled ordering.
+- **TST-100**: MUST verify `references` overwrites configured `docs-dir`/`REFERENCES.md`, returns only `success` in `content[0].text`, and restricts `details` to execution metadata.
+- **TST-101**: MUST verify `references` returns `error: <diagnostic>` plus failing execution metadata when source discovery, markdown generation, or `REFERENCES.md` writing fails.
+- **TST-102**: MUST verify `req-references` registers outside the bundled prompt inventory and retains description `Write a REFERENCES.md using the project's source code`.
+- **TST-103**: MUST verify successful `req-references` runs create no worktree or LLM message, overwrite configured `REFERENCES.md`, stage only that file, commit exact message, notify success, and restore workflow state `idle`.
+- **TST-104**: MUST verify failing `req-references` runs transition workflow state to `error`, notify pi CLI, create no worktree or LLM message, and surface git or reference-generation failures.
+- **TST-105**: MUST verify extension activation registers `req-reset` outside the bundled prompt inventory with its dedicated fixed description.
+- **TST-106**: MUST verify successful `req-reset` accepts non-`idle` workflow state, preserves execution transcript, restores `base-path`, removes matching generated worktrees plus branches, and returns workflow state `idle` without LLM messages.
+- **TST-107**: MUST verify failing `req-reset` surfaces restoration or cleanup failures, transitions workflow state to `error`, and starts no worktree or LLM session.
 - **TST-024**: MUST verify `files-search` and `search` agent-tool outputs place monolithic search markdown with preserved leading tabs in `content[0].text` and restrict `details` to execution metadata.
 - **TST-025**: MUST verify harness inspection surfaces `files-search` and `search` descriptions covering parameters, regex semantics, supported tags, monolithic markdown output, and failure details.
 - **TST-026**: MUST verify `files-compress` and `compress` agent-tool outputs place monolithic compression markdown with preserved leading tabs in `content[0].text` and restrict `details` to execution metadata.
@@ -400,13 +446,13 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-042**: MUST verify `package.json` keeps `name` equal to `pi-usereq` so npm publication resolves to `https://www.npmjs.com/package/pi-usereq`.
 - **TST-044**: MUST verify `package.json` keeps npm provenance metadata aligned to the canonical GitHub repository, issues URL, and README homepage.
 - **TST-040**: MUST verify `.pi-usereq.json` omits derived static and dynamic path fields while runtime path context and status rendering still derive them correctly.
-- **TST-041**: MUST verify the `pi-usereq` menu uses the documented labels and order, every configuration menu ends with `Reset defaults` only, dims locked git or debug rows, and preserves the documented summary rows.
+- **TST-041**: MUST verify the `pi-usereq` menu uses the documented labels and order, every configuration menu ends with `Reset defaults` without right-aligned value text, dims locked git or debug rows, and preserves the documented summary rows.
 - **TST-073**: MUST verify the `Debug` submenu persists `DEBUG_ENABLED`, `DEBUG_STATUS_CHANGES`, `DEBUG_WORKFLOW_EVENTS`, `DEBUG_LOG_FILE`, `DEBUG_LOG_ON_STATUS`, and per-item debug toggles through immediate-save, reset-confirmation, and focus-preserving re-render flows.
 - **TST-074**: MUST verify selected custom and embedded tool debug toggles append JSON entries with tool name, workflow state, input, result, and error flag, honoring `DEBUG_ENABLED` plus `DEBUG_LOG_ON_STATUS`.
 - **TST-075**: MUST verify selected `req-*` debug toggles append JSON entries for required-doc checks, worktree creation, fast-forward merge, worktree deletion, `workflow_state`, and `DEBUG_WORKFLOW_EVENTS`-gated workflow events across successful and failing prompt runs.
 - **TST-076**: MUST verify Debug submenu tool and prompt rows derive from `PI_USEREQ_CUSTOM_TOOL_NAMES`, `PI_USEREQ_EMBEDDED_TOOL_NAMES`, and `PROMPT_COMMAND_NAMES`.
 - **TST-085**: MUST verify the `Debug` submenu orders `Log on status` before `Status changes` and preserves the documented immediate-save plus focus-preserving re-render behavior.
-- **TST-080**: MUST verify each `req-*` command description is loaded at runtime from the bundled prompt YAML `description` field.
+- **TST-080**: MUST verify each bundled prompt-backed `req-*` command description is loaded at runtime from the first bundled prompt Markdown `# ` heading with the prefix removed.
 - **TST-081**: MUST verify worktree-backed prompt execution verifies worktree registration and branch presence, switches active-session cwd, `ctx.cwd`, and `process.cwd()` to `worktree-path` before agent start, and restores them to `base-path` before session-closure handling returns.
 - **TST-082**: MUST verify worktree-backed successful runs enter `running` only after prompt handoff succeeds, merge with `--ff-only` from `base-path`, and delete the worktree only after deletion verification passes.
 - **TST-083**: MUST verify worktree merge failures notify the pi CLI, transition through `error`, retain the worktree checkout for manual recovery, and keep `base-path` active after session-closure handling.
@@ -419,32 +465,32 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-052**: MUST verify toggling or editing a settings entry preserves focus on the affected row when the menu re-renders.
 - **TST-053**: MUST verify top-level reset restores the full menu tree and submenu reset restores only the targeted recursive subtree.
 - **TST-054**: MUST verify every `req-<prompt>` command aborts when slash-command-owned git validation fails and dispatches no prompt message.
-- **TST-055**: MUST verify `req-<prompt>` commands enforce the documented required-doc matrix, create no worktree, and dispatch no prompt when a required doc is missing.
+- **TST-055**: MUST verify bundled prompt-backed `req-<prompt>` commands enforce the documented required-doc matrix, create no worktree, and dispatch no prompt when a required doc is missing.
 - **TST-056**: MUST verify worktree-backed `req-<prompt>` commands derive `worktree-dir` from persisted `GIT_WORKTREE_PREFIX` for both default and override values.
 - **TST-057**: MUST verify `req-<prompt>` commands create `worktree-path`, dispatch prompts through the replacement-session context of the switched execution session, and run tool executions against prepared `context-path`.
 - **TST-058**: MUST verify worktree-backed `req-<prompt>` commands skip merge plus worktree/branch deletion, restore `base-path`, and notify pi CLI of closure failure when the matched run ends interrupted, failed, or aborted.
 - **TST-061**: MUST verify `req-<prompt>` commands skip worktree creation when `AUTO_GIT_COMMIT=disable`, even if persisted `GIT_WORKTREE_ENABLED=enable`.
 - **TST-064**: MUST verify worktree-backed `req-<prompt>` commands confirm created worktree directory plus branch existence before prompt dispatch and abort without dispatch when verification fails.
 - **TST-067**: MUST verify `status:error` renders with blinking error styling and non-error `status` values follow the documented status-bar theme convention.
-- **TST-068**: MUST verify every `req-<prompt>` command rejects non-`idle` workflow state before performing checks, worktree operations, or prompt dispatch.
-- **TST-069**: MUST verify `req-<prompt>` commands transition workflow state through `checking`, `error`, and `running` for documented preflight and prompt-handoff paths.
+- **TST-068**: MUST verify every `req-*` slash command except `req-reset` rejects non-`idle` workflow state before checks, worktree operations, or direct references execution, surfaces an error, and transitions workflow state to `error`.
+- **TST-069**: MUST verify bundled prompt-backed `req-<prompt>` commands transition workflow state through `checking`, `error`, and `running` for documented preflight and prompt-handoff paths.
 - **TST-070**: MUST verify prompt-end handling ignores unrelated or non-success completions and performs cleanup only for the matched successful prompt.
 - **TST-071**: MUST verify matched successful cleanup transitions workflow state through `merging` to `idle` and transitions to `error` on merge or deletion failure.
 - **TST-065**: MUST verify default startup-tool enablement matches the documented enabled and disabled tool matrix.
 - **TST-066**: MUST verify `req-<prompt>` commands keep working when extension custom-tool registrations are removed from the runtime inventory.
 - **TST-059**: MUST verify every agent-tool registration defines custom `renderResult` and that compact rendering shows essential invocation parameters while expanded rendering avoids fallback raw-content display.
-- **TST-086**: MUST verify `req-<prompt>` commands abort before prompt dispatch when the persisted execution-session header cwd or `process.cwd()` differs from the expected execution path, and abort before merge when persisted execution-session header metadata or verified worktree artifacts diverge, while stale pre-switch context probes alone do not abort.
+- **TST-086**: MUST verify bundled prompt-backed `req-<prompt>` commands abort before prompt dispatch when the persisted execution-session header cwd or `process.cwd()` differs from the expected execution path, and abort before merge when persisted execution-session header metadata or verified worktree artifacts diverge, while stale pre-switch context probes alone do not abort.
 
 ## 5. Observed Component Model
 
 ### 5.1 Runtime Surfaces
 - `src/cli.ts` parses CLI flags, repairs config for project-scoped commands, and dispatches to `tool-runner.ts` or `runStaticCheck`.
-- `src/index.ts` activates the pi extension, registers commands and agent tools, and manages interactive menu/status behavior through `ctx.ui`.
+- `src/index.ts` activates the pi extension, registers bundled prompt-backed commands plus specialized `req-references` orchestration and agent tools, and manages interactive menu/status behavior through `ctx.ui`.
 - `src/core/tool-runner.ts` orchestrates project file collection, markdown generation, compression, construct search, and static-check execution.
 - `src/core/source-analyzer.ts` defines `SourceElement`, language specs, extraction heuristics, Doxygen attachment, and Markdown rendering support.
 - `src/core/generate-markdown.ts`, `src/core/compress.ts`, and `src/core/find-constructs.ts` share analyzer and compressor logic to produce reusable Markdown outputs.
 - `src/core/static-check.ts` maps languages/extensions, parses Command-only enable specs, preserves debug `Dummy` handling, resolves inputs, and dispatches modular checker classes.
-- `src/core/config.ts`, `src/core/resources.ts`, and `src/core/prompts.ts` provide config persistence, home-resource synchronization, and prompt rendering.
+- `src/core/config.ts`, `src/core/resources.ts`, `src/core/prompts.ts`, and `src/core/req-references-command.ts` provide config persistence, home-resource synchronization, bundled-prompt rendering, and direct `req-references` slash-command orchestration.
 - `src/core/doxygen-parser.ts` normalizes Doxygen tags reused by source references and construct search output.
 - `scripts/debug-extension.ts`, `scripts/pi-usereq-debug.sh`, and `scripts/lib/*.ts` provide the standalone extension debug harness, bash wrapper, recording adapters, offline replay, SDK parity probing, and usage-manual rendering.
 
@@ -457,7 +503,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - `fast-glob` provides wildcard expansion for static-check inputs evidence in `src/core/static-check.ts`, `package.json`, and `package-lock.json`.
 - `tsx` is the manifest-declared TypeScript execution runner for tests and CLI scripts evidenced by `package.json` and `package-lock.json`.
 - `typescript` is the manifest-declared compiler and type-checker evidenced by `package.json`, `package-lock.json`, and `tsconfig.json`.
-- `git` CLI is a runtime dependency for repository discovery, source-file collection, and prompt-command worktree orchestration evidence in `src/core/tool-runner.ts` plus `src/core/prompt-command-runtime.ts`.
+- `git` CLI is a runtime dependency for repository discovery, source-file collection, bundled prompt-command worktree orchestration, and direct `req-references` commit orchestration evidenced in `src/core/tool-runner.ts`, `src/core/prompt-command-runtime.ts`, and `src/core/req-references-command.ts`.
 
 ### 5.3 Packaging and Tooling Surface
 - `package.json` declares `type: "module"`, `pi.extensions: ["./src/index.ts"]`, and the scripts `test`, `test:watch`, `cli`, `debug:ext`, `debug:ext:inspect`, `debug:ext:session`, `debug:ext:command`, `debug:ext:tool`, and `debug:ext:sdk`.
@@ -488,6 +534,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 │   │   ├── generate-markdown.ts
 │   │   ├── pi-usereq-tools.ts
 │   │   ├── prompts.ts
+│   │   ├── req-references-command.ts
 │   │   ├── resources.ts
 │   │   ├── source-analyzer.ts
 │   │   ├── static-check.ts
@@ -497,7 +544,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 │   └── resources/
 │       ├── templates/{Requirements_Template.md,HDT_Test_Authoring_Guide.md,Document_Source_Code_in_Doxygen_Style.md}
 │       ├── guidelines/{Google_Python_Style_Guide.md,Google_C++_Style_Guide.md}
-│       └── prompts/{analyze.md,change.md,check.md,cover.md,create.md,fix.md,flowchart.md,implement.md,new.md,readme.md,recreate.md,refactor.md,references.md,renumber.md,workflow.md,write.md}
+│       └── prompts/{analyze.md,change.md,check.md,cover.md,create.md,fix.md,flowchart.md,implement.md,new.md,readme.md,recreate.md,refactor.md,renumber.md,workflow.md,write.md}
 ├── tests/
 │   ├── extension-registration.test.ts
 │   ├── helpers.ts
@@ -528,7 +575,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 ## 7. Test Evidence Summary
 
 ### 7.1 Covered Behaviors
-- `tests/extension-registration.test.ts` covers extension registration, config-menu persistence, startup-tool enablement, static-check menu mutation flows, and prompt-command worktree orchestration.
+- `tests/extension-registration.test.ts` covers extension registration, config-menu persistence, startup-tool enablement, static-check menu mutation flows, bundled prompt-command worktree orchestration, and specialized `req-references` direct commit orchestration.
 - `tests/prompt-rendering.test.ts` covers home-resource synchronization and placeholder replacement in rendered prompts.
 - `tests/oracle-standalone.test.ts` compares non-tab-sensitive standalone `files-*` outputs against the Python `usereq.cli` oracle, asserts Go-fixture tab preservation, and compares `--test-static-check` dummy/command outputs against archived fixtures.
 - `tests/oracle-project.test.ts` compares non-tab-sensitive project commands against the Python oracle, asserts Go-source tab preservation for project extraction commands, and verifies archived `files-static-check` plus `static-check` outputs.
@@ -540,10 +587,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 ### 8.1 PRJ and CTN Evidence
 | ID | Evidence |
 | --- | --- |
-| PRJ-001 | `src/index.ts` :: `registerPromptCommands` :: `pi.registerCommand(\`req-${promptName}\`, ...)`; `src/core/prompts.ts` :: `renderPrompt` :: `return adaptPromptForInternalTools(applyReplacements(prompt, replacements));` |
-| PRJ-002 | `src/index.ts` :: `registerAgentTools` :: tool names include `files-tokens`, `references`, `compress`, `search`, `files-static-check`, and `static-check`. |
+| PRJ-001 | `src/index.ts` :: `registerPromptCommands` plus `registerReqReferencesCommand` :: registers bundled prompt-backed commands and the dedicated `req-references` command; `src/core/prompts.ts` :: `renderPrompt` :: adapts bundled prompt payloads. |
+| PRJ-002 | `src/index.ts` :: `registerAgentTools` :: tool names include `files-tokens`, `summarize`, `compress`, `search`, `files-static-check`, and `static-check`. |
 | PRJ-003 | `src/index.ts` :: `buildPiUsereqMenuChoices`, `configurePiUsereq`, and `configureDebugMenu` :: expose project paths, git automation, static-check, startup tools, notifications, and debug logging controls. |
-| PRJ-004 | `src/core/prompt-command-runtime.ts` :: `validatePromptGitState`, `buildPromptWorktreeName`, `createPromptWorktree`, and `finalizePromptCommandExecution` :: slash-command-owned git validation plus worktree orchestration remain internal to prompt execution. |
+| PRJ-004 | `src/core/prompt-command-runtime.ts` :: `validatePromptGitState`, `buildPromptWorktreeName`, `createPromptWorktree`, and `finalizePromptCommandExecution`; `src/core/req-references-command.ts` :: `prepareReqReferencesCommandExecution` and `executeReqReferencesCommandExecution` :: keep git orchestration internal to slash-command execution. |
 | PRJ-005 | `src/core/resources.ts` :: `ensureHomeResources` :: copies bundled resources; bundled tree exists under `src/resources/{prompts,templates,guidelines}`. |
 | CTN-001 | `src/core/config.ts` :: `getProjectConfigPath` and `getDefaultConfig` :: returns `.pi/pi-usereq/config.json`, `pi-usereq/docs`, `tests`, and `["src"]`. |
 | CTN-002 | `src/core/tool-runner.ts` :: `collectSourceFiles` :: executes `git -C <projectBase> ls-files --cached --others --exclude-standard` and fails on non-zero status. |
@@ -559,11 +606,12 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 ### 8.2 DES Evidence
 | ID | Evidence |
 | --- | --- |
-| DES-001 | `src/cli.ts` :: `parseArgs` and `main` :: parses flags then dispatches with branches such as `runReferences`, `runCompress`, `runSearch`, `runProjectStaticCheck`, and `runStaticCheck`. |
-| DES-002 | `src/index.ts` :: `piUsereqExtension` :: calls `registerPromptCommands`, `registerToolWrapperCommands`, `registerAgentTools`, `registerConfigCommands`, then installs `pi.on("session_start", ...)`. |
+| DES-001 | `src/cli.ts` :: `parseArgs` and `main` :: parses flags then dispatches with branches such as `runSummarize`, `runCompress`, `runSearch`, `runProjectStaticCheck`, and `runStaticCheck`. |
+| DES-002 | `src/index.ts` :: `piUsereqExtension` :: calls `registerReqReferencesCommand`, `registerPromptCommands`, `registerAgentTools`, `registerConfigCommands`, then installs shared lifecycle hooks. |
 | DES-003 | `src/core/source-analyzer.ts` :: `class SourceElement`; `SourceAnalyzer.enrich` :: invokes `extractSignatures`, `detectHierarchy`, `extractVisibility`, `extractInheritance`, `extractBodyAnnotations`, and `extractDoxygenFields`. |
+| DES-013 | `src/core/req-references-command.ts` :: `prepareReqReferencesCommandExecution` and `executeReqReferencesCommandExecution` :: implement the dedicated no-worktree `req-references` git-write workflow. |
 | DES-004 | `src/core/static-check.ts` :: `StaticCheckBase` and `StaticCheckCommand`; `dispatchStaticCheckForFile` switch selects the modular implementation by module name. |
-| DES-005 | `src/core/tool-runner.ts` :: exports `runFilesTokens`, `runReferences`, `runCompress`, `runSearch`, `runFilesStaticCheck`, and `runProjectStaticCheck`. |
+| DES-005 | `src/core/tool-runner.ts` :: exports `runFilesTokens`, `runFilesSummarize`, `runSummarize`, `runCompress`, `runSearch`, `runFilesStaticCheck`, and `runProjectStaticCheck`. |
 | DES-006 | `src/core/compress.ts` :: `normalizeRetainedLineIndentation`; `src/core/source-analyzer.ts` :: `normalizeSourceLineForExtraction`; `src/core/compress-files.ts` and `src/core/find-constructs.ts` reuse shared markdown emitters with preserved source tabs. |
 | DES-011 | `.github/workflows/release-npm.yml` :: release jobs validate semver tags and `origin/master`, publish with npm authentication, and create the GitHub Release. |
 
@@ -573,7 +621,13 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | REQ-001 | `src/core/resources.ts` :: `copyDirectoryContents` :: skips dotfiles, recurses into directories, and uses `fs.copyFileSync(sourcePath, destinationPath)`. |
 | REQ-002 | `src/core/config.ts` :: `buildPromptReplacementPaths` :: emits `%%TEMPLATE_PATH%%` plus docs/guideline/source/test tokens; `src/core/prompts.ts` :: `renderPrompt` merges them with `"%%ARGS%%": args`. |
 | REQ-003 | `src/core/prompts.ts` :: `TOOL_REFERENCE_REPLACEMENTS` and `adaptPromptForInternalTools` :: replaces ``req --find`` style text with `search tool` style text. |
-| REQ-004 | `src/index.ts` :: `registerPromptCommands` :: each handler runs `ensureHomeResources()`, renders the prompt, then executes `pi.sendUserMessage(content)`. |
+| REQ-004 | `src/index.ts` :: `registerPromptCommands` :: each handler renders the bundled prompt and dispatches it through `deliverPromptCommand(...)`. |
+| REQ-298 | `src/core/prompt-command-catalog.ts` :: `PROMPT_COMMAND_NAMES` omits `references`; `src/index.ts` :: `registerReqReferencesCommand` registers `req-references` with `REQ_REFERENCES_COMMAND_DESCRIPTION`. |
+| REQ-299 | `src/index.ts` :: `registerReqReferencesCommand` :: transitions `checking` then `running`; `src/core/req-references-command.ts` :: `prepareReqReferencesCommandExecution` reuses `validatePromptGitState(...)` without worktree or session switching. |
+| REQ-300 | `src/core/req-references-command.ts` :: `executeReqReferencesCommandExecution` calls `runReferences(...)`; `src/core/tool-runner.ts` :: `runReferences` overwrites configured `REFERENCES.md`. |
+| REQ-301 | `src/core/req-references-command.ts` :: `REQ_REFERENCES_COMMIT_MESSAGE`, `getGitAddTargetPath(...)`, and `executeReqReferencesCommandExecution(...)` :: stage only `REFERENCES.md` and create the fixed commit. |
+| REQ-302 | `src/index.ts` :: `registerReqReferencesCommand` :: restores workflow state `idle` and emits success notification after direct execution; `src/core/req-references-command.ts` :: `listResidualGitStatusLines(...)` verifies clean repository state. |
+| REQ-303 | `src/index.ts` :: `registerReqReferencesCommand` :: transitions to `error` and notifies on failure; `src/core/req-references-command.ts` :: throws deterministic `ReqError` failures for generation, staging, commit, and cleanliness errors. |
 | REQ-005 | `src/index.ts` :: `runToolCommand`, `formatResultForEditor`, `showToolResult` :: writes combined output into the editor and notifies `completed` or `failed`. |
 | REQ-006 | `src/index.ts` :: `buildPiUsereqMenuChoices` and `configurePiUsereq` :: expose directories, git automation, static-check, tools, notifications, debug settings, reset, save, and `Show configuration`. |
 | REQ-236 | `src/core/config.ts` :: `getDefaultConfig`, `loadConfig`, and `buildPersistedConfig` :: persist `DEBUG_ENABLED` with default `disable`. |
@@ -601,10 +655,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | REQ-161 | `src/core/static-check.ts` :: `dispatchStaticCheckForFile` and `runStaticCheck` :: keep `Dummy` only for existing config entries and the debug driver. |
 | REQ-009 | `src/index.ts` :: `pi.on("session_start", ...)` :: calls `ensureHomeResources()`, `applyConfiguredPiUsereqTools`, and `ctx.ui.setStatus(...)`. |
 | REQ-010 | `src/core/token-counter.ts` :: `new TokenCounter("cl100k_base")`; `formatPackSummary`; `src/core/tool-runner.ts` :: `runFilesTokens` validates files and returns summary plus warnings. |
-| REQ-011 | `src/core/tool-runner.ts` :: `runFilesReferences` :: returns `generateMarkdown(...)`; `src/core/source-analyzer.ts` :: `formatMarkdown` renders source-derived lines with preserved leading tabs. |
+| REQ-011 | `src/core/tool-runner.ts` :: `runFilesSummarize` :: returns `generateMarkdown(...)`; `src/core/source-analyzer.ts` :: `formatMarkdown` renders source-derived lines with preserved leading tabs. |
 | REQ-012 | `src/core/compress.ts` :: `INDENT_SIGNIFICANT`, `normalizeRetainedLineIndentation`, and `compressSourceDetailed` :: preserve full indentation for indentation-significant languages and preserve leading tabs for other languages. |
 | REQ-013 | `src/core/find-constructs.ts` :: `searchConstructsInFiles` and `formatConstruct` :: filters by tags/regex and emits signature, lines, Doxygen bullets, and stripped code with preserved leading tabs. |
-| REQ-014 | `src/core/tool-runner.ts` :: `runReferences` :: prepends file structure and returns `generateMarkdown(...)`; `src/core/source-analyzer.ts` :: `formatMarkdown` preserves source-derived leading tabs. |
+| REQ-014 | `src/core/tool-runner.ts` :: `runSummarize` :: prepends file structure and returns `generateMarkdown(...)`; `src/core/source-analyzer.ts` :: `formatMarkdown` preserves source-derived leading tabs. |
 | REQ-015 | `src/core/tool-runner.ts` :: `runCompress` :: collects configured project files then returns `compressFiles(files, enableLineNumbers, verbose, base)`. |
 | REQ-016 | `src/core/tool-runner.ts` :: `runSearch` :: collects configured project files and executes `searchConstructsInFiles(files, tagFilter, pattern, ...)`. |
 | REQ-017 | `src/core/tool-runner.ts` :: `runTokens` :: `canonicalNames = ["REQUIREMENTS.md", "WORKFLOW.md", "REFERENCES.md"]` and fails if no canonical docs exist. |
@@ -626,8 +680,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | --- | --- |
 | TST-001 | `tests/extension-registration.test.ts` :: `extension registers all required prompt commands, tool wrappers, and agent tools` validates command and tool registration sets. |
 | TST-002 | `tests/prompt-rendering.test.ts` :: `embedded resources are copied ...` and `prompt rendering replaces all dynamic placeholders ...`. |
-| TST-003 | `tests/oracle-standalone.test.ts` :: preserves Python-oracle coverage for non-tab-sensitive fixtures, asserts Go-fixture tab preservation for `files-references`, `files-compress`, and `files-find`, and keeps archived `test-static-check` coverage. |
-| TST-004 | `tests/oracle-project.test.ts` :: preserves Python-oracle coverage for non-tab-sensitive project fixtures, asserts Go-source tab preservation for `references`, `compress`, and `find`, and keeps archived static-check coverage. |
+| TST-003 | `tests/oracle-standalone.test.ts` :: preserves Python-oracle coverage for non-tab-sensitive fixtures, asserts Go-fixture tab preservation for `files-summarize`, `files-compress`, and `files-find`, and keeps archived `test-static-check` coverage. |
+| TST-004 | `tests/oracle-project.test.ts` :: preserves Python-oracle coverage for non-tab-sensitive project fixtures, asserts Go-source tab preservation for `summarize`, `compress`, and `find`, and keeps archived static-check coverage. |
 | TST-005 | `tests/extension-registration.test.ts` :: `configuration menu saves updated docs-dir`, `configuration menu can disable ... tools`, and `configuration menu can add guided static-check entries ...`. |
 | TST-046 | `tests/extension-registration.test.ts` :: `configuration menu hides removed static-check modules from user-facing actions`. |
 | TST-073 | `tests/extension-registration.test.ts` :: `debug menu dims locked rows and persists debug settings with focus-preserving re-renders` validates `DEBUG_WORKFLOW_EVENTS` alongside the existing Debug fields. |
@@ -638,11 +692,14 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | TST-092 | `tests/extension-registration.test.ts` :: `stale replacement contexts do not break workflow-state rendering` verifies stale replacement-session render contexts are ignored without throwing. |
 | TST-093 | `tests/extension-registration.test.ts` :: `replacement-session prompt delivery persists running before async sendUserMessage resolves` verifies async prompt-delivery completion does not delay merge-eligible `running` state. |
 | TST-094 | `tests/extension-registration.test.ts` :: `worktree-backed closure merges from base-path when end-of-session timing already moved the persisted context` verifies closure merges successfully without worktree-session reactivation. |
+| TST-102 | `tests/extension-registration.test.ts` :: `req-references registers outside the bundled prompt inventory and keeps its dedicated description` verifies dedicated registration independent from the bundled prompt inventory. |
+| TST-103 | `tests/extension-registration.test.ts` :: `req-references updates REFERENCES.md with a direct commit workflow and no LLM session` verifies overwrite, fixed commit message, clean repo, and idle restoration without worktree or prompt dispatch. |
+| TST-104 | `tests/extension-registration.test.ts` :: `req-references surfaces git-validation and reference-generation failures without session handoff` verifies error reporting without worktree creation, prompt dispatch, or git-history mutation. |
 | TST-006 | `tests/extension-registration.test.ts` :: `session_start applies configured pi-usereq startup tools`. |
 | TST-009 | `package.json` :: `"type": "module"`, `"pi": { "extensions": ["./src/index.ts"] }`, and `"scripts"` entries for `test`, `test:watch`, and `cli`. |
 | TST-010 | `tsconfig.json` :: `"module": "NodeNext"`, `"moduleResolution": "NodeNext"`, `"strict": true`, `"noEmit": true`, and `"include": ["src/**/*.ts", "tests/**/*.ts"]`. |
-| TST-022 | `tests/extension-registration.test.ts` :: `source-extraction agent tools preserve leading tabs in emitted content` plus the explicit `files-references` and `references` monolithic-output tests. |
-| TST-023 | `tests/extension-registration.test.ts` :: `reference tools register agent-oriented descriptions and schema details`. |
+| TST-022 | `tests/extension-registration.test.ts` :: `source-extraction agent tools preserve leading tabs in emitted content` plus the explicit `files-summarize` and `summarize` monolithic-output tests. |
+| TST-023 | `tests/extension-registration.test.ts` :: `summary tools register agent-oriented descriptions and schema details`. |
 | TST-024 | `tests/extension-registration.test.ts` :: `source-extraction agent tools preserve leading tabs in emitted content` plus the explicit `files-search` and `search` monolithic-output tests. |
 | TST-026 | `tests/extension-registration.test.ts` :: `source-extraction agent tools preserve leading tabs in emitted content` plus the explicit `files-compress` and `compress` monolithic-output tests. |
 | TST-039 | `tests/release-workflow.test.ts` :: workflow-content assertions cover semver gating, `origin/master` containment, npm publication, and GitHub release generation. |