pi-usereq 0.5.0 → 0.7.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.35"
-date: "2026-04-19"
+version: "0.0.38"
+date: "2026-04-20"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -103,14 +103,14 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-061**: MUST make `scripts/pi-usereq-debug.sh` expose `inspect`, `session`, `command`, `prompt`, `tool`, `sdk`, `raw`, and `help` subcommands.
 - **REQ-062**: MUST make `scripts/pi-usereq-debug.sh` default to `src/index.ts` plus caller cwd, permit later `--cwd` and `--extension` overrides, auto-prefix bare prompt names with `req-`, and map `session`/`sdk` to `session-start`/`sdk-smoke`.
 - **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 `docs-dir`, `tests-dir`, and `src-dir`, manages static-check and startup-tool submenus, exposes `show-config`, resets defaults, and saves configuration on exit.
-- **REQ-007**: MUST provide a startup-tools submenu with overview, status display, per-tool toggle, enable-all, disable-all, and reset-defaults actions for configurable custom and embedded pi CLI active tools.
+- **REQ-006**: MUST provide a `pi-usereq` menu that edits `Document directory`, `Source-code directories`, and `Unit tests directory`, manages `Language static code checkers`, `Enable tools`, `Notifications`, exposes `Show configuration`, resets defaults, and saves configuration on exit.
+- **REQ-007**: MUST provide an `Enable tools` submenu with `Enable tools`, enable-all, disable-all, and reset-defaults actions for configurable custom and embedded pi CLI active tools.
 - **REQ-063**: MUST derive configurable embedded pi CLI tools from runtime builtin tools named `read`, `bash`, `edit`, `write`, `grep`, and `ls`.
 - **REQ-064**: MUST default all custom tools except `find` and embedded `read`, `bash`, `edit`, and `write` to enabled, and custom `find` plus embedded `grep` and `ls` to disabled.
 - **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 never creates replacement sessions or pre-reset flows.
-- **REQ-008**: MUST provide a static-check submenu that adds Command entries by guided language flow or raw spec, removes language entries, and shows supported languages.
+- **REQ-008**: MUST provide a `Language static code checkers` submenu that adds Command entries by guided language flow, removes configured language entries, 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.
 - **REQ-009**: MUST refresh shared runtime path context, apply configured startup tools, and publish single-line `pi-usereq` status text during `session_start`.
@@ -124,35 +124,53 @@ 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: `base`, `context`, `elapsed`, `beep`, `sound`.
-- **REQ-121**: MUST render `context` immediately after `base` with separator ` • ` and a 10-cell bar using `▓` for filled cells.
-- **REQ-122**: MUST compute filled `context` cells by ceiling `usagePercent * 10 / 100`, except 0 percent MUST produce 0 filled cells.
-- **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-120**: MUST render single-line status fields in this order: `base`, `context`, `elapsed`, `sound`.
+- **REQ-121**: MUST render `context` immediately after `base` 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-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` bar cells as theme `warning` `▓` glyphs on a background derived from the active theme `accent` token.
-- **REQ-127**: MUST overlay the literal `◀ CLEAR ▶ ` with the theme `warning` token on an `accent`-derived background when normalized context usage is unavailable or equals 0 percent.
-- **REQ-128**: MUST overlay the centered literal ` ◀ FULL ▶ ` with the active theme `error` token on a theme `warning` background when normalized context usage exceeds 90 percent.
-- **REQ-129**: MUST persist independent terminal-beep flags for successful prompt completion, escape-triggered prompt abortion, and error-terminated prompt completion, defaulting each flag to enabled.
-- **REQ-130**: MUST dispatch enabled terminal-beep events through `notifyWindows`, `notifyOSC99`, `notifyOSC9`, or `notifyOSC777` when the matching prompt lifecycle outcome occurs.
-- **REQ-131**: MUST persist a successful-prompt external sound level with allowed values `none`, `low`, `mid`, and `high`, defaulting to `none`.
-- **REQ-132**: MUST execute the configured successful-prompt external sound command only when the prompt ends without abort or error and the sound level is not `none`.
+- **REQ-126**: MUST render `context` gauge icons with theme `warning`, except the overflow state uses theme `error`.
+- **REQ-127**: MUST render `context` as blinking `▕█▏` 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-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-135**: MUST render `beep` immediately after `et`, showing `none` or the comma-ordered enabled event tokens `end`, `esc`, and `err`.
-- **REQ-136**: MUST render `sound` immediately after `beep`, showing one of `none`, `low`, `mid`, or `high`.
-- **REQ-137**: MUST make the configuration UI expose controls for terminal-beep flags, selected notify command, sound toggle hotkey bind, and per-level notify commands.
-- **REQ-163**: MUST persist successful-prompt Pushover settings `enabled=false`, `user=""`, `token=""`, and `priority=0` in project configuration.
-- **REQ-164**: MUST make the notifications menu expose a `Pushover notifications` submenu immediately after the sound-notification submenu using the existing settings-list layout, navigation, descriptions, and value-column semantics.
-- **REQ-165**: MUST make the Pushover submenu expose controls for successful-prompt enablement, `User Key/Delivery Group Key`, `Token/API Token Key`, and priority toggle `0=Normal` / `1=High Priority`.
-- **REQ-166**: MUST suppress Pushover delivery whenever notification `global disable` is enabled, even when Pushover completion notifications remain enabled.
-- **REQ-167**: MUST deliver successful-completion Pushover notifications through native Node HTTP or HTTPS requests to `https://api.pushover.net/1/messages.json` and MUST NOT invoke shell commands for Pushover delivery.
-- **REQ-168**: MUST send a Pushover message only when the prompt completes successfully, Pushover completion notifications are enabled, and persisted `user` plus `token` values are non-empty.
-- **REQ-169**: MUST send Pushover `title` as `<prompt> @ <base-path> [<time>]`, `message` as the prompt argument text used for `%%ARGS%%`, and `priority` as the persisted `0` or `1` value.
-- **REQ-170**: MUST render single-line status fields in this order: `base`, `context`, `elapsed`, `beep`, `sound`, `pushover`.
-- **REQ-171**: MUST render `pushover` immediately after `sound`, showing `on` or `off` from the Pushover successful-prompt enable setting.
-- **REQ-172**: MUST make the Pushover submenu expose a `global disable` toggle that suppresses all Pushover delivery without mutating the successful-prompt enable setting.
+- **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`.
+- **REQ-165**: MUST order Pushover rows as `Enable pushover`, `Pushover events`, `Pushover priority`, `Pushover title`, `Pushover text`, `Pushover User Key/Delivery Group Key`, and `Pushover Token/API Token Key`.
+- **REQ-166**: MUST deliver Pushover notifications only when global Pushover is enabled and the corresponding prompt-end Pushover event toggle is enabled.
+- **REQ-167**: MUST deliver Pushover notifications through native Node HTTP or HTTPS requests to `https://api.pushover.net/1/messages.json` and MUST NOT invoke shell commands for Pushover delivery.
+- **REQ-168**: MUST send a Pushover message only when persisted `user` plus `token` values are non-empty for the triggered prompt-end outcome.
+- **REQ-169**: MUST substitute `%%INSTALLATION_PATH%%`, `%%PROMT%%`, `%%BASE%%`, `%%TIME%%`, `%%ARGS%%`, and `%%RESULT%%` at runtime inside `PI_NOTIFY_CMD`.
+- **REQ-172**: MUST persist Pushover priority values `Normal=0` and `High=1`, defaulting to `Normal`.
+- **REQ-174**: MUST persist command-notify event toggles in keys `notify-on-completed`, `notify-on-interrupted`, and `notify-on-failed`, defaulting to completed enabled and interrupted plus failed disabled.
+- **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-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-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`.
+- **REQ-187**: MUST render `%%BASE%%` as the runtime base path relative to user home using `~/...` form and `%%TIME%%` as final elapsed `M:SS`.
+- **REQ-188**: MUST label notification-event rows as `Prompt completed`, `Prompt interrupted`, and `Prompt failed`.
+- **REQ-190**: MUST label top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Language static code checkers`, `Enable tools`, `Notifications`, and `Show configuration`.
+- **REQ-191**: MUST order top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Language static code checkers`, `Enable tools`, `Notifications`, `Show configuration`, `Reset defaults`, and `Save and close`.
+- **REQ-192**: MUST preserve the selected settings-menu row after toggling or editing a setting value.
+- **REQ-193**: MUST append `Reset defaults` and `Save and close` as the final two rows of every configuration submenu.
+- **REQ-194**: MUST make top-level `Reset defaults` restore all top-level and submenu settings to defaults.
+- **REQ-195**: MUST make submenu `Reset defaults` restore only settings within that submenu subtree.
+- **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-159**: MUST increase `Σ` by each normally completed prompt duration and MUST NOT change `Σ` on escape-triggered cancellation.
+- **REQ-173**: MUST optimize every agent-tool response for minimum token usage by excluding caller-known, static, duplicated, and registration-described facts from runtime payloads.
 - **REQ-010**: MUST count tokens with `js-tiktoken` `cl100k_base`, count characters and lines, and make `files-tokens` emit agent-oriented JSON containing structured per-file metrics, extracted facts, and aggregate metrics.
 - **REQ-011**: MUST generate explicit-file references by analyzing supported source files and emitting agent-oriented JSON with per-file metadata, imports, symbol records, and optional residual text.
 - **REQ-012**: MUST compress supported source files by removing comments and blank lines, preserving indentation for Python, Haskell, and Elixir, and optionally preserving original line numbers.
@@ -161,40 +179,40 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-015**: MUST make CLI project-scope compression scan configured `src-dir` files and emit one compressed markdown block per supported file.
 - **REQ-016**: MUST make `find` scan configured `src-dir` files using the requested tag filter and regular expression.
 - **REQ-017**: MUST make `tokens` count only existing canonical docs `REQUIREMENTS.md`, `WORKFLOW.md`, and `REFERENCES.md`, reuse the structured `files-tokens` JSON contract, and fail when none exist.
-- **REQ-069**: MUST order `files-tokens` and `tokens` JSON sections as `request`, `summary`, `files`, and `guidance`, and order fields inside each section from canonical identifiers to source facts, metrics, and derived guidance.
+- **REQ-069**: MUST make `files-tokens` and `tokens` runtime payloads expose only `summary`, `files`, and `execution`, omitting request echoes and derived guidance from runtime responses.
 - **REQ-070**: MUST emit counts, sizes, line counts, line ranges, and derived totals as JSON numbers with explicit unit-specific field names, keeping display strings optional and never as the sole carrier of numeric facts.
 - **REQ-071**: MUST normalize `files-tokens` and `tokens` text fields by removing decorative formatting, isolating canonical paths, separating source-derived facts from guidance, and stripping non-semantic presentation artifacts.
-- **REQ-072**: MUST register `files-tokens` and `tokens` with agent-oriented descriptions covering purpose, inputs, output schema, output format, specialized behaviors, configuration options, invocation modes, and failure conditions.
+- **REQ-072**: MUST register `files-tokens` and `tokens` with agent-oriented descriptions carrying static scope, encoding, canonical-doc selection, and failure facts omitted from runtime responses.
 - **REQ-073**: MUST expose file-derived facts needed for direct access, including canonical path, language, existence, line counts, line ranges, and Doxygen-derived metadata, as dedicated JSON fields when available.
 - **REQ-074**: MUST keep monolithic text summaries optional, place them after structured fields, and omit any fact from text-only representation when the same fact can be emitted as dedicated JSON.
-- **REQ-075**: MUST make `files-tokens` and `tokens` guidance fields explicitly distinguish source observations, derived recommendations, and actionable next-step hints.
-- **REQ-076**: MUST order `files-references` and `references` JSON sections from request metadata to repository summary, file records, and optional residual text.
+- **REQ-075**: MUST surface `files-tokens` and `tokens` skip or read-error observations through per-file status fields and execution diagnostics instead of a dedicated guidance section.
+- **REQ-076**: MUST make `files-references` and `references` runtime payloads expose only `summary`, `repository`, `files`, and `execution`, omitting request echoes from runtime responses.
 - **REQ-077**: MUST expose symbol kind, path, declaration lines, counts, and line ranges as dedicated numeric or array fields, never only inside free-form strings.
 - **REQ-078**: MUST expose parsed Doxygen fields as tag-specific JSON objects or arrays, keeping monolithic `text` only for unsplittable residual content.
 - **REQ-079**: MUST normalize `files-references` and `references` text fields by removing decorative markdown artifacts and preserving only parser-relevant residual content.
-- **REQ-080**: MUST register `files-references` and `references` with agent-oriented descriptions covering purpose, inputs, configuration, output schema, specialized behaviors, and failure conditions.
-- **REQ-081**: MUST make agent-tool `files-compress` and `compress` return structured JSON sections ordered as `request`, `summary`, `repository`, `files`, and `execution`.
+- **REQ-080**: MUST register `files-references` and `references` with agent-oriented descriptions carrying static scope, configuration, and failure facts omitted from runtime responses.
+- **REQ-081**: MUST make agent-tool `files-compress` and `compress` return structured JSON sections ordered as `summary`, `repository`, `files`, and `execution`.
 - **REQ-082**: MUST expose canonical paths, absolute paths, language IDs, source line counts, source line ranges, compressed line counts, and removed line counts as dedicated typed compression fields.
 - **REQ-083**: MUST expose compressed excerpts through structured `compressed_lines` arrays and a separate `compressed_source_text` field, never only inside markdown headers, fences, or prefixed display strings.
 - **REQ-084**: MUST expose file-level and symbol-level Doxygen fields as structured tag-specific JSON objects, and emit symbol records with declaration kind, canonical path, signatures, and numeric declaration line ranges.
 - **REQ-085**: MUST keep residual monolithic text optional, place it after structured fields, and omit decorative markdown artifacts from compression JSON field values.
-- **REQ-086**: MUST register `files-compress` and `compress` with agent-oriented descriptions covering scope, parameters, line-number behavior, output schema, project-scope selection rules, output format, and failure conditions.
+- **REQ-086**: MUST register `files-compress` and `compress` with agent-oriented descriptions carrying static scope, line-number behavior, selection rules, and failure facts omitted from runtime responses.
 - **REQ-087**: MUST expose skipped inputs, unsupported extensions, compression failures, and zero-processable requests as structured statuses and stable error reasons, while keeping stderr diagnostics optional.
 - **REQ-088**: MUST mirror the structured compression payload into tool `content[0].text` and tool `details`, with execution metadata nested under the mirrored JSON object.
-- **REQ-089**: MUST make agent-tool `files-find` and `find` return structured JSON sections ordered as `request`, `summary`, `repository`, `files`, and `execution`.
+- **REQ-089**: MUST make agent-tool `files-find` and `find` return structured JSON sections ordered as `summary`, `repository`, `files`, and `execution`.
 - **REQ-090**: MUST expose find request scope facts as dedicated fields, including tag filter, regex pattern, line-number mode, requested paths, configured source directories, and supported tags by language.
 - **REQ-091**: MUST expose per-file and per-match find facts as dedicated fields, including canonical path, language, construct kind, symbol name, signature, declaration order, numeric line ranges, and stripped code lines.
 - **REQ-092**: MUST expose parsed find Doxygen fields as tag-specific JSON objects or arrays for file-level and construct-level metadata, keeping monolithic residual text only when safe splitting is impossible.
 - **REQ-093**: MUST emit find counts, file totals, match totals, line numbers, and line ranges as JSON numbers with explicit unit-specific field names, never only inside display strings.
 - **REQ-094**: MUST normalize `files-find` and `find` text fields by removing markdown headers, fences, bullets, and other presentation-only artifacts from structured JSON values.
-- **REQ-095**: MUST register `files-find` and `find` with agent-oriented descriptions covering purpose, scope, input schema, output schema, `enableLineNumbers`, regex semantics, supported tags by language, and failure conditions.
+- **REQ-095**: MUST register `files-find` and `find` with agent-oriented descriptions carrying static regex semantics, supported tags by language, and failure facts omitted from runtime responses.
 - **REQ-096**: MUST expose structured statuses for skipped files, unsupported languages, invalid tag filters, invalid regex patterns, no-match outcomes, and analysis failures, while keeping stderr diagnostics optional.
 - **REQ-097**: MUST mirror the structured find payload into tool `content[0].text` and tool `details`, with execution metadata nested under the mirrored JSON object.
 - **REQ-098**: MUST keep monolithic find `text` fields optional, place them after structured fields, and omit any fact from text-only representation when a dedicated JSON field can carry it.
-- **REQ-099**: MUST make every agent-tool response expose a JSON-first tree whose specialized fields are directly accessible, while monolithic text remains optional and subordinate to the structured payload.
-- **REQ-100**: MUST encode quantitative facts as JSON numbers in unit-specific fields, keep textual fields free of decorative formatting and textual units, and avoid duplicating facts already exposed by specialized fields.
-- **REQ-101**: MUST register every agent tool with machine-oriented metadata describing purpose, required and optional parameters, configuration and invocation variants, output schema and format, specialized behaviors, and stable error conditions.
-- **REQ-102**: MUST make every structured agent-tool execute result mirror the same JSON object into `content[0].text` and `details`, nesting execution metadata under dedicated `execution` fields.
+- **REQ-099**: MUST make every agent-tool response expose a JSON-first tree whose runtime fields are directly accessible and whose caller-known or registration-described facts are omitted.
+- **REQ-100**: MUST encode quantitative facts as JSON numbers in unit-specific fields, keep textual fields free of decorative formatting, and avoid duplicate or derivable facts in runtime payloads.
+- **REQ-101**: MUST register every agent tool with machine-oriented metadata describing purpose, parameters, static scope facts, omitted response facts, output schema, specialized behaviors, and stable error conditions.
+- **REQ-102**: MUST make every structured agent-tool execute result mirror the same JSON object into `content[0].text` and `details`, nesting only residual execution metadata under dedicated `execution` fields.
 - **REQ-018**: MUST expose the `test-static-check` driver only through standalone CLI `--test-static-check`, dispatching `dummy` or `command` checker subcommands directly.
 - **REQ-019**: MUST resolve each explicit static-check file by extension and run every configured checker for that language while capturing only failing checker output.
 - **REQ-020**: MUST parse user `--enable-static-check` specs in `LANG=Command,CMD[,PARAM...]` format and normalize supported language names plus `Command` case-insensitively.
@@ -213,8 +231,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-105**: MUST make `git-path` print the derived repository root only when it equals `base-path` or is an ancestor of `base-path`.
 - **REQ-106**: MUST make prompt `%%GUIDELINES_FILES%%`, `%%GUIDELINES_PATH%%`, and `%%TEMPLATE_PATH%%` resolve under `<installation-path>/resources`.
 - **REQ-107**: MUST express prompt-visible `installation-path`, `execution-path`, `base-path`, `config-path`, template paths, and guideline paths relative to user home using platform-native home environment variables.
-- **REQ-031**: MUST make the `pi-usereq` menu expose a `show-config` action after `notifications` and before `Reset defaults`, writing the current project configuration JSON to the editor.
-- **REQ-162**: MUST render the `show-config` current value as the user-home-relative extension config path using the settings-list `dim` value style.
+- **REQ-031**: MUST make the `pi-usereq` menu expose a `Show configuration` action after `Notifications` and before `Reset defaults`, writing the current project configuration JSON to the editor.
+- **REQ-162**: MUST render the `show-config` current value as the `~`-relative extension config path using the settings-list `dim` value style.
 - **REQ-032**: MUST inject a pi.dev conformance block into rendered prompts when `docs/pi.dev/agent-document-manifest.json` exists under the project base.
 - **REQ-033**: MUST make that conformance block require manifest-guided document review before implementing or changing extension code that interfaces with pi CLI.
 - **REQ-034**: MUST make that conformance block require manifest-guided document review before validating, analyzing, or fixing extension code that interfaces with pi CLI.
@@ -241,8 +259,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-145**: MUST derive `git-path` only at runtime from the current working directory 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 `base` as the absolute runtime `base-path` with no git-relative shortening.
-- **REQ-149**: MUST label notification settings actions as `Selected notify command`, `Sound toggle hotkey bind`, `Notify command (low vol.)`, `Notify command (mid vol.)`, and `Notify command (high vol.)`.
-- **REQ-150**: MUST omit overview rows and reference-only actions from the main and notification configuration menus.
+- **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-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.
 - **REQ-152**: MUST render a persistent bottom-line description for the currently selected configuration entry.
@@ -254,22 +272,23 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-002**: MUST verify installed bundled prompt, template, and guideline resources remain readable from `installation-path` and prompt rendering replaces all dynamic placeholders with runtime path context.
 - **TST-003**: MUST verify standalone `files-*` CLI outputs match the Python oracle and `--test-static-check` dummy/command outputs match archived fixtures for every fixture file.
 - **TST-004**: MUST verify project `compress`, `find`, `tokens`, `git-check`, `docs-check`, `git-path`, and `get-base-path` outputs match the Python oracle, and verify `files-static-check` plus `static-check` against archived fixtures.
-- **TST-005**: MUST verify the configuration menu persists `docs-dir`, disables startup tools, adds Command static-check entries, and omits prompt-delivery mode controls.
-- **TST-046**: MUST verify static-check menus omit module selection and hide `Dummy`, `Pylance`, and `Ruff` from user-configurable actions.
+- **TST-005**: MUST verify the configuration menu persists `docs-dir`, disables startup tools through `Enable tools`, adds guided Command static-check entries, and omits prompt-delivery mode controls.
+- **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.
 - **TST-006**: MUST verify `session_start` activates configured startup tools and updates the single-line `pi-usereq` status bar.
 - **TST-031**: MUST verify the status bar renders the explicit base path, omits `docs`, `src`, `tests`, `git`, and `tools`, and preserves active-theme `accent`/`warning` field-value token 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 `base`, `context`, `elapsed`, `beep`, and `sound` fields plus the ceiling-based 10-cell context bar.
-- **TST-037**: MUST verify the configuration menu persists terminal-beep flags, selected notify command, sound toggle hotkey bind, and per-level notify commands using the documented menu labels.
+- **TST-033**: MUST verify the status bar renders ordered `base`, `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 actions, and save-close actions.
 - **TST-038**: MUST verify the sound-toggle shortcut cycles persisted sound levels and refreshes the status bar with the updated `sound` field.
-- **TST-047**: MUST verify the notifications menu exposes the Pushover submenu after sound settings and persists Pushover enable, user key, token, and priority values.
-- **TST-048**: MUST verify successful prompt completion sends one native Pushover request with the documented endpoint and payload, and suppresses delivery on abort, error, global disable, or missing credentials.
-- **TST-049**: MUST verify the status bar renders ordered `base`, `context`, `elapsed`, `beep`, `sound`, and `pushover` fields and appends `pushover:on|off` using the Pushover enable setting.
-- **TST-050**: MUST verify the Pushover `global disable` toggle suppresses delivery without changing the persisted successful-prompt enable setting.
+- **TST-047**: MUST verify the `Notifications` menu exposes `Pushover events` before direct Pushover settings and persists Pushover enable, event toggles, priority, title, text, user key, and token values.
+- **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 `base`, `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-045**: MUST verify default configuration enables terminal-beep flags `end`, `esc`, and `err` before user customization.
-- **TST-035**: MUST verify unavailable or 0-percent context usage renders the literal `◀ CLEAR ▶ ` with the theme `warning` token on the preserved `accent`-derived context-bar background.
-- **TST-036**: MUST verify context usage above 90 percent renders the literal ` ◀ FULL ▶ ` with the theme `error` token on the preserved theme `warning` background.
+- **TST-045**: MUST verify default configuration disables notify globally, initializes sound to `none`, disables Pushover globally, applies the documented completed/interrupted/failed event 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 above 100 percent renders `▕█▏` with blink control when preserved or with the theme `error` token otherwise.
 - **TST-043**: MUST verify configuration menus reuse the active CLI settings-list theme semantics for labels, values, descriptions, cursor, and hints.
 - **TST-007**: MUST verify `git-path` output ignores stale stored values and resolves only a current repository root that is identical to or an ancestor of `base-path`.
 - **TST-008**: MUST verify `git-wt-create` and `git-wt-delete` create, configure, copy `.pi-usereq`, and remove the named worktree as observable filesystem side effects.
@@ -287,19 +306,21 @@ 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` JSON outputs expose repository, file, symbol, location, and Doxygen facts through dedicated structured fields.
-- **TST-023**: MUST verify harness inspection surfaces agent-oriented `files-references` and `references` tool descriptions with output schema, configuration, specialized behaviors, and failure details.
-- **TST-024**: MUST verify `files-find` and `find` JSON outputs expose request, repository, file, match, location, and Doxygen facts through dedicated structured fields.
+- **TST-022**: MUST verify `files-references` and `references` JSON outputs expose repository, file, symbol, location, and Doxygen facts through dedicated structured fields while omitting request echoes.
+- **TST-023**: MUST verify harness inspection surfaces agent-oriented `files-references` and `references` tool descriptions with output schema, static scope facts, specialized behaviors, and failure details.
+- **TST-024**: MUST verify `files-find` and `find` JSON outputs expose summary, repository, file, match, location, and Doxygen facts through dedicated structured fields while omitting request echoes.
 - **TST-025**: MUST verify harness inspection surfaces agent-oriented `files-find` and `find` tool descriptions with input schema, output schema, line-number behavior, regex semantics, supported tags by language, and failure details.
-- **TST-026**: MUST verify `files-compress` and `compress` JSON outputs expose structured request, repository, line, symbol, status, and Doxygen facts through dedicated fields.
+- **TST-026**: MUST verify `files-compress` and `compress` JSON outputs expose structured summary, repository, line, symbol, status, and Doxygen facts through dedicated fields while omitting request echoes.
 - **TST-027**: MUST verify harness inspection surfaces agent-oriented `files-compress` and `compress` tool descriptions with parameters, line-number behavior, output schema, specialization triggers, and failure conditions.
-- **TST-028**: MUST verify path, static-check, git, docs, and worktree agent-tool outputs expose structured JSON request, result, status, execution, and derived runtime path facts through dedicated fields.
+- **TST-028**: MUST verify path, static-check, git, docs, and worktree agent-tool outputs expose structured JSON result, summary, file, and execution facts while omitting request echoes and runtime-path duplication.
 - **TST-029**: MUST verify harness inspection surfaces machine-oriented descriptions for path, static-check, git, docs, and worktree tools, including parameters, output schema, specialization triggers, and failure conditions.
 - **TST-039**: MUST verify `.github/workflows/release-npm.yml` keeps the existing tag filter, gates downstream release work on `origin/master`, runs npm publication, and creates the GitHub Release from generated changelog text.
 - **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/config.json` omits `base-path` and `git-path`, while runtime path tools and status rendering still derive both values correctly.
-- **TST-041**: MUST verify the `pi-usereq` menu exposes `show-config` after `notifications` and before `Reset defaults`, shows the home-relative config path in the value column, and omits overview rows plus notification reference-only actions.
+- **TST-041**: MUST verify the `pi-usereq` menu uses the documented labels and order, exposes `Show configuration` after `Notifications`, shows the `~`-relative config path, summarizes `Notifications` without terminal-beep state, and omits configuration reference-only actions.
+- **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 all settings and submenu reset restores only the targeted submenu subtree.
 
 ## 5. Observed Component Model
 
@@ -441,9 +462,9 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | REQ-003 | `src/core/prompts.ts` :: `TOOL_REFERENCE_REPLACEMENTS` and `adaptPromptForInternalTools` :: replaces ``req --find`` style text with `find tool` style text. |
 | REQ-004 | `src/index.ts` :: `registerPromptCommands` :: each handler runs `ensureHomeResources()`, renders the prompt, then executes `pi.sendUserMessage(content)`. |
 | REQ-005 | `src/index.ts` :: `runToolCommand`, `formatResultForEditor`, `showToolResult` :: writes combined output into the editor and notifies `completed` or `failed`. |
-| REQ-006 | `src/index.ts` :: `configurePiUsereq` :: edits docs/tests/src settings, invokes submenus, resets defaults, and persists with `saveProjectConfig`. |
-| REQ-007 | `src/index.ts` :: `configurePiUsereqToolsMenu` :: choices include `Show tool status`, `Toggle tool`, `Enable all`, `Disable all`, `Reset ... defaults`. |
-| REQ-008 | `src/index.ts` :: `configureStaticCheckMenu` :: supports Command-only guided addition, raw-spec addition, language removal, and supported-language display. |
+| REQ-006 | `src/index.ts` :: `configurePiUsereq` :: edits docs/tests/src settings, invokes `Language static code checkers`, resets defaults, and persists with `saveProjectConfig`. |
+| REQ-007 | `src/index.ts` :: `configurePiUsereqToolsMenu` :: choices include `Enable tools`, `Enable all`, `Disable all`, and `Reset defaults`. |
+| REQ-008 | `src/index.ts` :: `configureStaticCheckMenu` :: supports Command-only guided addition, configured-language removal, and reset-only static-check management. |
 | REQ-160 | `src/index.ts` :: `buildStaticCheckMenuChoices` and `configureStaticCheckMenu` :: omit user-facing module selection and hardcode `Command` for guided additions. |
 | 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(...)`. |
@@ -481,7 +502,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | 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 `files-tokens`, `files-compress`, and `files-find`; `tests/attended-results-scenarios.ts` :: archives `test-static-check` dummy and command scenarios only. |
 | TST-004 | `tests/oracle-project.test.ts` :: preserves Python-oracle coverage for `compress`, `find`, `tokens`, `git-check`, `docs-check`, `git-path`, and `get-base-path`; `tests/attended-results-scenarios.ts` :: archives `files-static-check` and `static-check`. |
-| TST-005 | `tests/extension-registration.test.ts` :: `configuration menu saves updated docs-dir`, `configuration menu can disable ... tools`, and both Command-oriented static-check menu addition tests. |
+| 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-006 | `tests/extension-registration.test.ts` :: `session_start applies configured pi-usereq startup tools`. |
 | TST-007 | `tests/extension-registration.test.ts` :: `git-path dependent commands derive the repository root at runtime`. |