pi-usereq 0.6.0 → 0.10.0

package/pi-usereq/docs/WORKFLOW.md

@@ -63,7 +63,7 @@
   - `main(...)`: parse argv, normalize config, dispatch selected runner, serialize result [`src/cli.ts`]
     - `parseArgs(...)`: map argv tokens into a structured command selection [`src/cli.ts`]
       - `takeUntilOption(...)`: collect positional operands until next option token [`src/cli.ts`]
-    - `applyEnableStaticCheckSpecs(...)`: merge repeatable CLI static-check enable specs before command dispatch [`src/cli.ts`]
+    - `applyEnableStaticCheckSpecs(...)`: merge repeatable CLI static-check enable specs, preserve existing checker lists, and force targeted language flags on before command dispatch [`src/cli.ts`]
       - `loadMutableProjectConfig(...)`: load project config without intermediate persistence [`src/cli.ts`]
         - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -108,43 +108,13 @@
           - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
             - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
       - `formatPackSummary(...)`: render aggregate summary [`src/core/token-counter.ts`]
-    - `runFilesReferences(...)`: branch `--files-references`; emit structured explicit-file references JSON [`src/core/tool-runner.ts`]
-      - `buildReferenceToolPayload(...)`: analyze requested files into the agent-oriented references payload [`src/core/reference-payload.ts`]
-        - `canonicalizeReferencePath(...)`: normalize request and file paths against the caller base directory [`src/core/reference-payload.ts`]
-        - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
-          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
-          - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
-            - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
-            - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
-            - `findBlockEnd(...)`: compute construct end line [`src/core/source-analyzer.ts`]
-          - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
-            - `cleanNames(...)`: normalize matched symbol names [`src/core/source-analyzer.ts`]
-            - `extractSignatures(...)`: derive single-line signatures [`src/core/source-analyzer.ts`]
-            - `detectHierarchy(...)`: assign parent-child relationships [`src/core/source-analyzer.ts`]
-            - `extractVisibility(...)`: annotate visibility [`src/core/source-analyzer.ts`]
-              - `parseVisibility(...)`: language-specific visibility classifier [`src/core/source-analyzer.ts`]
-            - `extractInheritance(...)`: annotate inheritance [`src/core/source-analyzer.ts`]
-              - `parseInheritance(...)`: language-specific inheritance parser [`src/core/source-analyzer.ts`]
-            - `extractBodyAnnotations(...)`: capture body comments and exit points [`src/core/source-analyzer.ts`]
-              - `inStringContext(...)`: suppress comment parsing inside strings [`src/core/source-analyzer.ts`]
-              - `findComment(...)`: detect valid single-line comment boundary [`src/core/source-analyzer.ts`]
-              - `cleanCommentLine(...)`: normalize comment payload [`src/core/source-analyzer.ts`]
-            - `extractDoxygenFields(...)`: bind documentation comments to definitions [`src/core/source-analyzer.ts`]
-              - `isPostfixDoxygenComment(...)`: detect postfix documentation markers [`src/core/source-analyzer.ts`]
-              - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
-                - `stripCommentDelimiters(...)`: remove language comment wrappers [`src/core/doxygen-parser.ts`]
-                - `normalizeWhitespace(...)`: canonicalize tag body whitespace [`src/core/doxygen-parser.ts`]
-          - `buildCommentMaps(...)`: associate comments with definitions and file descriptions [`src/core/reference-payload.ts`]
-          - `collectFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/source-analyzer.ts`]
-            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
-          - `collectElementDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/source-analyzer.ts`]
-            - `parseDoxygenComment(...)`: parse Doxygen tag/value map [`src/core/doxygen-parser.ts`]
-          - `structureDoxygenFields(...)`: normalize Doxygen fields into tag-specific JSON arrays and objects [`src/core/doxygen-parser.ts`]
-          - `countDoxygenFieldValues(...)`: derive aggregate Doxygen counts [`src/core/doxygen-parser.ts`]
-          - `resolveParentElement(...)`: link nested symbols to enclosing definitions [`src/core/reference-payload.ts`]
-          - `buildCommentEntry(...)`: serialize normalized comment text and line ranges [`src/core/reference-payload.ts`]
-        - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
-      - `buildReferenceToolExecutionStderr(...)`: serialize skipped and analysis-error entries into stderr text [`src/core/reference-payload.ts`]
+    - `runFilesReferences(...)`: branch `--files-references`; emit monolithic explicit-file references markdown [`src/core/tool-runner.ts`]
+      - `generateMarkdown(...)`: analyze requested files and concatenate Python-compatible reference markdown sections [`src/core/generate-markdown.ts`]
+        - `detectLanguage(...)`: map extension to language key [`src/core/generate-markdown.ts`]
+        - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
+        - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
+        - `formatMarkdown(...)`: render one file as the repository reference-markdown format [`src/core/source-analyzer.ts`]
+          - `normalizeSourceLineForExtraction(...)`: preserve leading tabs in source-derived markdown lines [`src/core/source-analyzer.ts`]
     - `runFilesCompress(...)`: branch `--files-compress`; compress explicit files [`src/core/tool-runner.ts`]
       - `compressFiles(...)`: compress each file into markdown blocks [`src/core/compress-files.ts`]
         - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
@@ -157,11 +127,12 @@
             - `countLogicalLines(...)`: count original source lines [`src/core/compress.ts`]
             - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
             - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
+            - `normalizeRetainedLineIndentation(...)`: preserve full indentation or leading tabs before output normalization [`src/core/compress.ts`]
             - `buildCompressedLineEntry(...)`: normalize one retained line into structured output [`src/core/compress.ts`]
             - `formatCompressedSourceText(...)`: render compressed output text [`src/core/compress.ts`]
         - `formatOutputPath(...)`: normalize emitted file path [`src/core/compress-files.ts`]
-    - `runFilesFind(...)`: branch `--files-find`; extract named constructs from explicit files [`src/core/tool-runner.ts`]
-      - `findConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
+    - `runFilesSearch(...)`: branch `--files-find`; extract named constructs from explicit files [`src/core/tool-runner.ts`]
+      - `searchConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
         - `parseTagFilter(...)`: parse tag filter set [`src/core/find-constructs.ts`]
         - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
         - `languageSupportsTags(...)`: reject unsupported tag/language combinations [`src/core/find-constructs.ts`]
@@ -172,6 +143,7 @@
         - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
           - `cleanNames(...)`: normalize matched symbol names [`src/core/source-analyzer.ts`]
           - `extractSignatures(...)`: derive single-line signatures [`src/core/source-analyzer.ts`]
+            - `normalizeSourceLineForExtraction(...)`: preserve leading tabs in source-derived signature lines [`src/core/source-analyzer.ts`]
           - `detectHierarchy(...)`: assign parent-child relationships [`src/core/source-analyzer.ts`]
           - `extractVisibility(...)`: annotate visibility [`src/core/source-analyzer.ts`]
             - `parseVisibility(...)`: language-specific visibility classifier [`src/core/source-analyzer.ts`]
@@ -217,12 +189,13 @@
         - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
           - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
           - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
-    - `runFilesStaticCheck(...)`: branch `--files-static-check`; run configured checkers for explicit files [`src/core/tool-runner.ts`]
+    - `runFilesStaticCheck(...)`: branch `--files-static-check`; run enabled configured checkers for explicit files [`src/core/tool-runner.ts`]
       - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
       - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
         - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
         - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
           - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+      - `getActiveStaticCheckEntries(...)`: derive the active checker list from per-language enable flags [`src/core/config.ts`]
       - `dispatchStaticCheckForFile(...)`: instantiate checker by configured module [`src/core/static-check.ts`]
         - `formatDispatchStaticCheckModules(...)`: render valid persisted modules for unknown-module failures [`src/core/static-check.ts`]
         - `StaticCheckBase.run(...)`: execute debug dummy checker [`src/core/static-check.ts`]
@@ -235,7 +208,7 @@
           - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
             - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
             - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
-    - `runReferences(...)`: branch `--references`; emit structured project references JSON [`src/core/tool-runner.ts`]
+    - `runReferences(...)`: branch `--references`; emit monolithic project references markdown [`src/core/tool-runner.ts`]
       - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
         - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -244,21 +217,14 @@
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
       - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
         - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
-      - `buildReferenceToolPayload(...)`: analyze configured source files into the agent-oriented references payload [`src/core/reference-payload.ts`]
-        - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
-        - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
-          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
-          - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
-          - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
-          - `buildCommentMaps(...)`: associate comments with definitions and file descriptions [`src/core/reference-payload.ts`]
-          - `collectFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/source-analyzer.ts`]
-          - `collectElementDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/source-analyzer.ts`]
-          - `structureDoxygenFields(...)`: normalize Doxygen fields into tag-specific JSON arrays and objects [`src/core/doxygen-parser.ts`]
-          - `countDoxygenFieldValues(...)`: derive aggregate Doxygen counts [`src/core/doxygen-parser.ts`]
-          - `resolveParentElement(...)`: link nested symbols to enclosing definitions [`src/core/reference-payload.ts`]
-          - `buildCommentEntry(...)`: serialize normalized comment text and line ranges [`src/core/reference-payload.ts`]
-        - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
-      - `buildReferenceToolExecutionStderr(...)`: serialize skipped and analysis-error entries into stderr text [`src/core/reference-payload.ts`]
+      - `formatFilesStructureMarkdown(...)`: render the repository file-structure markdown block [`src/core/tool-runner.ts`]
+        - `buildAsciiTree(...)`: materialize the relative file tree as ASCII text [`src/core/tool-runner.ts`]
+      - `generateMarkdown(...)`: analyze configured source files and concatenate Python-compatible reference markdown sections [`src/core/generate-markdown.ts`]
+        - `detectLanguage(...)`: map extension to language key [`src/core/generate-markdown.ts`]
+        - `SourceAnalyzer.analyze(...)`: parse source elements [`src/core/source-analyzer.ts`]
+        - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
+        - `formatMarkdown(...)`: render one file as the repository reference-markdown format [`src/core/source-analyzer.ts`]
+          - `normalizeSourceLineForExtraction(...)`: preserve leading tabs in source-derived markdown lines [`src/core/source-analyzer.ts`]
     - `runCompress(...)`: branch `--compress`; compress configured source files [`src/core/tool-runner.ts`]
       - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
         - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
@@ -279,10 +245,11 @@
             - `countLogicalLines(...)`: count original source lines [`src/core/compress.ts`]
             - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
             - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
+            - `normalizeRetainedLineIndentation(...)`: preserve full indentation or leading tabs before output normalization [`src/core/compress.ts`]
             - `buildCompressedLineEntry(...)`: normalize one retained line into structured output [`src/core/compress.ts`]
             - `formatCompressedSourceText(...)`: render compressed output text [`src/core/compress.ts`]
         - `formatOutputPath(...)`: normalize emitted file path [`src/core/compress-files.ts`]
-    - `runFind(...)`: branch `--find`; extract project-wide named constructs [`src/core/tool-runner.ts`]
+    - `runSearch(...)`: branch `--find`; extract project-wide named constructs [`src/core/tool-runner.ts`]
       - `resolveProjectSrcDirs(...)`: load configured source directories [`src/core/tool-runner.ts`]
         - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -291,7 +258,7 @@
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
       - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
         - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
-      - `findConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
+      - `searchConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
         - `parseTagFilter(...)`: parse tag filter set [`src/core/find-constructs.ts`]
         - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
         - `languageSupportsTags(...)`: reject unsupported tag/language combinations [`src/core/find-constructs.ts`]
@@ -302,6 +269,7 @@
         - `SourceAnalyzer.enrich(...)`: derive signatures, hierarchy, visibility, inheritance, body annotations, and Doxygen bindings [`src/core/source-analyzer.ts`]
           - `cleanNames(...)`: normalize matched symbol names [`src/core/source-analyzer.ts`]
           - `extractSignatures(...)`: derive single-line signatures [`src/core/source-analyzer.ts`]
+            - `normalizeSourceLineForExtraction(...)`: preserve leading tabs in source-derived signature lines [`src/core/source-analyzer.ts`]
           - `detectHierarchy(...)`: assign parent-child relationships [`src/core/source-analyzer.ts`]
           - `extractVisibility(...)`: annotate visibility [`src/core/source-analyzer.ts`]
             - `parseVisibility(...)`: language-specific visibility classifier [`src/core/source-analyzer.ts`]
@@ -379,68 +347,6 @@
             - `StaticCheckCommand.checkFile(...)`: run external executable against one file [`src/core/static-check.ts`]
               - `StaticCheckBase.headerLine(...)`: format checker header [`src/core/static-check.ts`]
               - `StaticCheckBase.emitLine(...)`: write checker output [`src/core/static-check.ts`]
-    - `runGitCheck(...)`: branch `--git-check`; validate clean git state [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
-        - `isSameOrAncestorPath(...)`: validate git-root ancestry against the base path [`src/core/path-context.ts`]
-        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-      - `runCapture(...)`: verify worktree membership [`src/core/tool-runner.ts`]
-      - `runCapture(...)`: inspect porcelain changes [`src/core/tool-runner.ts`]
-      - `runCapture(...)`: resolve symbolic HEAD [`src/core/tool-runner.ts`]
-      - `runCapture(...)`: resolve detached HEAD fallback [`src/core/tool-runner.ts`]
-    - `runDocsCheck(...)`: branch `--docs-check`; validate canonical docs presence [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-    - `runGitWtName(...)`: branch `--git-wt-name`; generate standardized worktree name [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
-      - `sanitizeBranchName(...)`: canonicalize current branch token [`src/core/tool-runner.ts`]
-    - `runGitWtCreate(...)`: branch `--git-wt-create`; create worktree and copy config [`src/core/tool-runner.ts`]
-      - `validateWtName(...)`: validate requested worktree name [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
-      - `rollbackWorktreeCreate(...)`: remove partial worktree and branch on copy failure [`src/core/tool-runner.ts`]
-    - `runGitWtDelete(...)`: branch `--git-wt-delete`; remove worktree and branch [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
-      - `worktreePathExistsExact(...)`: verify exact registered worktree path [`src/core/tool-runner.ts`]
-        - `runCapture(...)`: run git worktree list subprocess [`src/core/tool-runner.ts`]
-    - `runGitPath(...)`: branch `--git-path`; print configured git root [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-      - `resolveEffectiveGitPath(...)`: derive the effective repository root constrained by `base-path` ancestry [`src/core/tool-runner.ts`]
-      - `formatRuntimePathForDisplay(...)`: serialize the git path for CLI output [`src/core/path-context.ts`]
-    - `runGetBasePath(...)`: branch `--get-base-path`; print configured base path [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `formatRuntimePathForDisplay(...)`: serialize the base path for CLI output [`src/core/path-context.ts`]
-        - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
-        - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
     - `writeResult(...)`: emit selected runner result [`src/cli.ts`]
       - `writeStdout(...)`: write stdout payload [`src/cli.ts`]
       - `writeStderr(...)`: write stderr payload [`src/cli.ts`]
@@ -514,13 +420,14 @@
             - `registerPromptCommands(...)`: register bundled `req-*` prompt commands [`src/index.ts`]
             - `registerAgentTools(...)`: register structured agent tools [`src/index.ts`]
             - `registerConfigCommands(...)`: register configuration commands [`src/index.ts`]
-            - `registerPiNotifyShortcut(...)`: register the configured successful-run sound shortcut when the runtime supports shortcuts [`src/index.ts`]
+            - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut when the runtime supports shortcuts [`src/index.ts`]
               - `loadProjectConfig(...)`: load the current project config for shortcut registration [`src/index.ts`]
                 - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
                 - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
                   - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
                   - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
                     - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+                  - `normalizeGitWorktreePrefix(...)`: canonicalize persisted worktree prefix [`src/core/config.ts`]
                   - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
                   - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
                   - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
@@ -552,42 +459,55 @@
               - `RecordingExtensionAPI.getBuiltinTools(...)`: synthesize supported builtin tool descriptors [`scripts/lib/recording-extension-api.ts`]
                 - `buildBuiltinToolDefinition(...)`: build one builtin tool descriptor [`scripts/lib/recording-extension-api.ts`]
                   - `buildBuiltinSourceInfo(...)`: synthesize builtin provenance metadata [`scripts/lib/recording-extension-api.ts`]
-            - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+            - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
             - `RecordingExtensionAPI.getActiveTools(...)`: expose current active-tool set [`scripts/lib/recording-extension-api.ts`]
             - `RecordingExtensionAPI.setActiveTools(...)`: replace active-tool set with runtime-visible names [`scripts/lib/recording-extension-api.ts`]
               - `RecordingExtensionAPI.getAllTools(...)`: expose supported builtin plus extension tool inventory [`scripts/lib/recording-extension-api.ts`]
           - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
-          - `updateExtensionStatus(...)`: refresh stored context usage, elapsed timers, cumulative runtime, and rendered status text [`src/core/extension-status.ts`]
+          - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore elapsed timers, reset workflow state for startup/new/reload, and render status text [`src/core/extension-status.ts`]
             - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
               - `RecordingCommandContext.getContextUsage(...)`: return the offline context-usage placeholder [`scripts/lib/recording-extension-api.ts`]
+            - `shouldResetElapsedStateOnSessionStart(...)`: detect `startup|reload` elapsed-reset boundaries [`src/core/extension-status.ts`]
+            - `resetElapsedState(...)`: clear in-memory and persisted completed timers [`src/core/extension-status.ts`]
+            - `restorePersistedElapsedState(...)`: restore persisted completed timers for `new|resume|fork` [`src/core/extension-status.ts`]
+            - `shouldResetWorkflowStateOnSessionStart(...)`: detect `startup|new|reload` workflow-reset boundaries [`src/core/extension-status.ts`]
+            - `persistElapsedState(...)`: mirror completed timers into process-scoped persistence [`src/core/extension-status.ts`]
             - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-            - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
               - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics [`src/core/extension-status.ts`]
+              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
                 - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
                 - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-                - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-                  - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
-                  - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+                - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
+                - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+                  - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
                 - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                   - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                   - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-                - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-          - `runPiNotifyEffects(...)`: dispatch configured terminal beeps and successful-run sound hooks on `agent_end` [`src/core/pi-notify.ts`]
-            - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
+          - `runPiNotifyEffects(...)`: dispatch configured command-notify, sound, and optional Pushover hooks on `agent_end` [`src/core/pi-notify.ts`]
+            - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `completed`, `interrupted`, or `failed` [`src/core/pi-notify.ts`]
               - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
-            - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
-            - `buildPiNotifyBody(...)`: build the stable pi-notify body from the classified outcome [`src/core/pi-notify.ts`]
-            - `notifyPiTerminal(...)`: route terminal notifications by runtime environment when the matching beep flag is enabled [`src/core/pi-notify.ts`]
-              - `notifyWindows(...)`: emit Windows toast notifications [`src/core/pi-notify.ts`]
-              - `notifyOSC99(...)`: emit Kitty OSC 99 notifications [`src/core/pi-notify.ts`]
-              - `notifyOSC9(...)`: emit OSC 9 notifications [`src/core/pi-notify.ts`]
-              - `notifyOSC777(...)`: emit OSC 777 notifications [`src/core/pi-notify.ts`]
-            - `runPiNotifySoundCommand(...)`: execute the configured successful-run sound command when sound is enabled [`src/core/pi-notify.ts`]
+            - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
+              - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+            - `runPiNotifyCommand(...)`: execute `PI_NOTIFY_CMD` with runtime placeholder substitution [`src/core/pi-notify.ts`]
+              - `substitutePiNotifyShellTemplate(...)`: replace installation, prompt, base, time, args, and result placeholders inside the shell template [`src/core/pi-notify.ts`]
+                - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                  - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                  - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                  - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+                  - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+                - `escapePiNotifyShellTemplateValue(...)`: escape prompt-scoped values for double-quoted shell insertion [`src/core/pi-notify.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+              - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+            - `shouldRunPiNotifySound(...)`: validate sound level plus the matching event toggle [`src/core/pi-notify.ts`]
+              - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+            - `runPiNotifySoundCommand(...)`: execute the configured sound command when the sound level and matching event toggle permit delivery [`src/core/pi-notify.ts`]
               - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
               - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
                 - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
-                - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+              - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
     - `replayCommand(...)`: replay a recorded command handler and capture prompt/UI side effects [`scripts/lib/extension-debug-harness.ts`]
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
       - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
@@ -595,34 +515,40 @@
         - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources when invoking `req-*` handlers [`src/core/resources.ts`]
         - `getProjectBase(...)`: resolve command project base [`src/index.ts`]
         - `loadProjectConfig(...)`: load command runtime config [`src/index.ts`]
-        - `renderPrompt(...)`: render prompt-command payloads with conditional pi.dev API-contract guidance [`src/core/prompts.ts`]
+        - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion plus conditional pi.dev governance guidance [`src/core/prompts.ts`]
         - `deliverPromptCommand(...)`: dispatch prompt replay into the current recorded session [`src/index.ts`]
           - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
         - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
-          - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions plus the display-only config-path row [`src/index.ts`]
-            - `formatProjectConfigPathForMenu(...)`: format the current config path relative to the user home when possible [`src/index.ts`]
+          - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including effective worktree locking and the display-only config-path row [`src/index.ts`]
+            - `formatProjectConfigPathForMenu(...)`: format the current config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
           - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
             - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
             - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
               - `buildFallbackPiUsereqSettingsListTheme(...)`: mirror CLI settings-list token roles from the callback-local theme [`src/core/settings-menu.ts`]
-            - `buildSettingItems(...)`: map menu choices into settings-list rows and apply optional dim value tones [`src/core/settings-menu.ts`]
+            - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, and disable non-selectable actions [`src/core/settings-menu.ts`]
           - `saveProjectConfig(...)`: persist menu updates on save-and-close [`src/index.ts`]
           - `setPiUsereqStatusConfig(...)`: cache the saved config for footer rendering [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the current-path/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with current-path, consolidated elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-              - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
               - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                 - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                 - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-              - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-          - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
-          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
-          - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
-            - `buildPiNotifyMenuChoices(...)`: serialize notification actions for the shared settings menu [`src/index.ts`]
-            - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
+          - `configureStaticCheckMenu(...)`: interactive guided static-check editor with per-language enable toggles [`src/index.ts`]
+          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor without a status-reference action [`src/index.ts`]
+          - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with dedicated event submenus [`src/index.ts`]
+            - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers [`src/index.ts`]
+              - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
+              - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows plus the shared event-submenu launcher [`src/index.ts`]
+            - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
+              - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus submenu reset/save actions [`src/index.ts`]
+              - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
+              - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
+              - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+            - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
     - `replayTool(...)`: replay a recorded tool execute handler and capture content/details [`scripts/lib/extension-debug-harness.ts`]
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
       - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
@@ -630,62 +556,27 @@
         - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need them [`src/core/resources.ts`]
         - `getProjectBase(...)`: resolve tool project base [`src/index.ts`]
         - `loadProjectConfig(...)`: load tool runtime config [`src/index.ts`]
-        - `buildTokenToolPayload(...)`: construct agent-oriented token JSON with separated source facts, metrics, and guidance [`src/core/token-counter.ts`]
-          - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
-          - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
-            - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
-              - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
-              - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
-              - `countLines(...)`: count logical lines [`src/core/token-counter.ts`]
-              - `inferLanguageName(...)`: infer agent-oriented language labels [`src/core/token-counter.ts`]
-              - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
-              - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
-                - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-        - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
-          - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
-          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
-          - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
-          - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
-          - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
-        - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
-          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
-          - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
-            - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
-            - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
-        - `buildCompressionToolExecuteResult(...)`: wrap compression payloads into tool content and structured details [`src/index.ts`]
-          - `buildCompressToolExecutionStderr(...)`: serialize skipped, error, and symbol-analysis warning entries [`src/core/compress-payload.ts`]
-          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
-        - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
-          - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-        - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
-          - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
-          - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
-          - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
-            - `buildMatchEntry(...)`: structure one matched construct with typed lines and Doxygen fields [`src/core/find-payload.ts`]
-              - `buildStrippedConstructLineEntries(...)`: strip comments into structured code lines [`src/core/find-constructs.ts`]
-        - `buildFindToolExecuteResult(...)`: wrap construct-search payloads into tool content and structured details [`src/index.ts`]
-          - `buildFindToolExecutionStderr(...)`: serialize invalid-request, skipped, no-match, and analysis-error diagnostics [`src/core/find-payload.ts`]
-          - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-        - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
-        - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-        - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
-        - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
-        - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
-        - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-        - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
-        - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-        - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-        - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
-        - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-        - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
-        - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
-        - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-        - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
-        - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
-        - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
+        - `executeMonolithicTool(...)`: execute one CLI-style runner and wrap one monolithic content block plus minimal execution details [`src/index.ts`]
+          - `runFilesTokens(...)`: execute the monolithic token pack-summary runner [`src/core/tool-runner.ts`]
+            - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
+              - `TokenCounter(...)`: lazily resolve `js-tiktoken` only when token counting executes [`src/core/token-counter.ts`]
+                - `loadJsTiktokenModule(...)`: convert missing tokenizer dependencies into deterministic `ReqError` failures [`src/core/token-counter.ts`]
+              - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
+          - `runFilesReferences(...)`: execute the monolithic explicit-file references markdown runner [`src/core/tool-runner.ts`]
+            - `generateMarkdown(...)`: analyze requested files and concatenate Python-compatible reference markdown sections [`src/core/generate-markdown.ts`]
+          - `runFilesCompress(...)`: execute the monolithic explicit-file compression markdown runner [`src/core/tool-runner.ts`]
+            - `compressFiles(...)`: compress each file into markdown blocks [`src/core/compress-files.ts`]
+          - `runFilesSearch(...)`: execute the monolithic explicit-file construct-search markdown runner [`src/core/tool-runner.ts`]
+            - `searchConstructsInFiles(...)`: select constructs by tag and regex [`src/core/find-constructs.ts`]
+          - `runReferences(...)`: execute the monolithic project references markdown runner [`src/core/tool-runner.ts`]
+          - `runCompress(...)`: execute the monolithic project compression markdown runner [`src/core/tool-runner.ts`]
+          - `runSearch(...)`: execute the monolithic project construct-search markdown runner [`src/core/tool-runner.ts`]
+          - `runTokens(...)`: execute the monolithic canonical-doc token runner [`src/core/tool-runner.ts`]
+          - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
+          - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
+          - `buildMonolithicToolExecuteResult(...)`: wrap runner stdout or stderr into tool content plus execution details [`src/core/agent-tool-json.ts`]
+            - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+          - `normalizeToolFailure(...)`: convert runner failures into deterministic execution records [`src/core/agent-tool-json.ts`]
     - `runSdkSmoke(...)`: replay offline `session_start`, probe the official SDK runtime, and compare inventories [`scripts/lib/sdk-smoke.ts`]
       - `replaySessionStart(...)`: capture the offline `session_start` contract [`scripts/lib/extension-debug-harness.ts`]
       - `probeSdkRuntime(...)`: load the official SDK runtime and extract extension-owned inventory [`scripts/lib/sdk-smoke.ts`]
@@ -730,41 +621,106 @@
     - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
       - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
         - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-    - `registerPromptCommands(...)`: register one command per prompt name and cache prompt metadata for later successful-completion notifications [`src/index.ts`]
+    - `registerPromptCommands(...)`: register one command per prompt name using runtime prompt-front-matter descriptions, recover a live bootstrap cwd when stale command contexts still point at deleted worktrees, gate orchestration on `idle`, transition workflow state through `checking|running|error`, prepare a forked execution session with the active session directory, persist prompt metadata for switch-triggered rebinding, switch the active pi CLI session to the verified execution cwd before prompt handoff, append dedicated workflow-activation debug entries, capture the replacement-session context, dispatch the rendered prompt into the forked active session through that context, record `running` immediately after delivery handoff starts, and only then await the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed [`src/index.ts`]
+      - `resolveLiveBootstrapCwd(...)`: recover a live bootstrap cwd from the command context, runtime path state, or process cwd when stale worktree paths no longer exist [`src/index.ts`]
+      - `syncContextCwdMirror(...)`: best-effort realign the command-context `cwd` mirror to the recovered live cwd before prompt preflight [`src/index.ts`]
+      - `transitionPromptWorkflowState(...)`: update workflow state and append gated `workflow_state` debug entries only after the transition completes [`src/index.ts`]
+        - `setPiUsereqWorkflowState(...)`: update workflow state before prompt preflight, prompt handoff, or command-side failure [`src/core/extension-status.ts`]
+        - `logPromptWorkflowStateChange(...)`: append selected prompt workflow-transition debug entries [`src/index.ts`]
+        - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
+          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
+            - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
+            - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
+            - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
+            - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+              - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
+            - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
+              - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
+              - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
       - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources before prompt render [`src/core/resources.ts`]
         - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
           - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-      - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
-      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
-        - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+      - `getProjectBase(...)`: resolve project base from the recovered command-context cwd [`src/index.ts`]
+      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for the recovered command-context cwd [`src/index.ts`]
+        - `getProjectBase(...)`: resolve project base from the recovered command-context cwd [`src/index.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
           - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
           - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-      - `renderPrompt(...)`: render prompt template with project substitutions and conditional pi.dev API-contract guidance [`src/core/prompts.ts`]
+      - `preparePromptCommandExecution(...)`: run prompt preflight, reject stale or off-project origin session files whose persisted header cwd no longer belongs to the active project base, create and verify a dedicated worktree when enabled, reuse the active session directory only when the origin session remains reusable, generate a process-unique timestamp execution identifier for each new worktree name, and plan the execution plus git-state metadata [`src/core/prompt-command-runtime.ts`]
+        - `validatePromptGitState(...)`: validate clean runtime repository state through slash-command-owned git checks while ignoring extension-owned debug-log artifacts [`src/core/prompt-command-runtime.ts`]
+          - `throwPromptGitStatusError(...)`: normalize prompt-command git-preflight failures [`src/core/prompt-command-runtime.ts`]
+        - `isUsablePromptSessionFile(...)`: accept only origin session files whose persisted header cwd still exists inside the active project base [`src/core/prompt-command-runtime.ts`]
+        - `resolvePromptSessionFile(...)`: reuse the current origin session only when reusable, otherwise allocate a fresh persisted session path rooted at the active project base [`src/core/prompt-command-runtime.ts`]
+        - `validatePromptRequiredDocs(...)`: verify the prompt-specific canonical-doc matrix and append selected required-doc debug entries [`src/core/prompt-command-runtime.ts`]
+          - `resolvePromptDocsRoot(...)`: resolve the configured docs root [`src/core/prompt-command-runtime.ts`]
+          - `getPromptRequiredDocs(...)`: map the prompt name to canonical-doc probes [`src/core/prompt-command-runtime.ts`]
+          - `logDebugPromptEvent(...)`: append selected prompt debug entries for required-doc checks [`src/core/debug-runtime.ts`]
+        - `buildPromptWorktreeName(...)`: generate the configured-prefix worktree name when worktrees are enabled [`src/core/prompt-command-runtime.ts`]
+          - `resolveCurrentPromptBranchName(...)`: read the current branch token for worktree naming and runtime state [`src/core/prompt-command-runtime.ts`]
+          - `sanitizePromptWorktreeBranchName(...)`: rewrite the current branch into a filesystem-safe token [`src/core/prompt-command-runtime.ts`]
+          - `getNextPromptWorktreeExecutionId(...)`: derive a process-unique `YYYYMMDDHHMMSS` execution identifier so back-to-back prompt starts never reuse a same-second worktree name [`src/core/prompt-command-runtime.ts`]
+            - `formatPromptWorktreeExecutionId(...)`: serialize one worktree execution timestamp as `YYYYMMDDHHMMSS` [`src/core/prompt-command-runtime.ts`]
+          - `validatePromptWorktreeName(...)`: reject invalid generated worktree names [`src/core/prompt-command-runtime.ts`]
+        - `createPromptWorktree(...)`: create and verify the dedicated worktree and branch when worktrees are enabled and append selected worktree-create debug entries [`src/core/prompt-command-runtime.ts`]
+          - `resolveWorktreePaths(...)`: derive `parent-path`, `base-dir`, worktree root, and `worktree-path` from the original project base and git root [`src/core/prompt-command-runtime.ts`]
+          - `promptWorktreeRegistered(...)`: verify exact worktree registration through `git worktree list --porcelain` [`src/core/prompt-command-runtime.ts`]
+          - `promptWorktreeBranchExists(...)`: verify exact branch presence through `git branch --list --format=%(refname:short)` [`src/core/prompt-command-runtime.ts`]
+          - `logDebugPromptEvent(...)`: append selected prompt debug entries for worktree creation [`src/core/debug-runtime.ts`]
+          - `cleanupPromptWorktreeCreation(...)`: rollback partial prompt-command worktree resources on verification or finalization failure [`src/core/prompt-command-runtime.ts`]
+            - `promptWorktreeRegistered(...)`: test whether the sibling worktree remains registered [`src/core/prompt-command-runtime.ts`]
+        - `createPromptExecutionSessionFile(...)`: fork the current persisted session into the worktree cwd when the origin session file already exists, or materialize an execution-session snapshot with header cwd=`worktree-path` plus the current in-memory branch when the origin session is not flushed yet [`src/core/prompt-command-runtime.ts`]
+      - `renderPrompt(...)`: render prompt template with project substitutions, bundled commit-instruction expansion, extension-owned runtime guidance, and conditional pi.dev governance guidance [`src/core/prompts.ts`]
         - `readBundledPrompt(...)`: read bundled prompt template [`src/core/resources.ts`]
           - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
             - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
               - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-        - `buildPromptReplacementPaths(...)`: build replacement token map including installation-owned template and guideline paths [`src/core/config.ts`]
-          - `buildRuntimePathContext(...)`: derive installation, execution, base, config, docs, tests, source, and git paths [`src/core/path-context.ts`]
-            - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
-            - `getConfigPath(...)`: derive the `.pi-usereq/config.json` path [`src/core/path-context.ts`]
-          - `buildRuntimePathFacts(...)`: convert runtime paths into prompt-visible path strings [`src/core/path-context.ts`]
-            - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with environment variables [`src/core/path-context.ts`]
-          - `formatRuntimePathForDisplay(...)`: serialize guideline file paths for prompt substitution [`src/core/path-context.ts`]
-        - `applyReplacements(...)`: substitute token values [`src/core/prompts.ts`]
-        - `injectPiDevConformanceBlock(...)`: add conditional pi.dev manifest review and API-contract guidance for prompt workflows [`src/core/prompts.ts`]
-          - `buildPiDevConformanceBlock(...)`: resolve manifest-gated pi.dev review and API-compliance rules [`src/core/prompts.ts`]
+        - `buildPromptReplacements(...)`: merge shared path substitutions with `%%ARGS%%` and `%%PROMPT%%` [`src/core/prompts.ts`]
+          - `buildPromptReplacementPaths(...)`: build replacement token map including installation-owned template and guideline paths [`src/core/config.ts`]
+            - `buildRuntimePathContext(...)`: derive `install-path`, `base-path`, `context-path`, `config-path`, docs/tests/source absolute paths, and optional git/worktree facts [`src/core/path-context.ts`]
+              - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+              - `getConfigPath(...)`: derive the `.pi-usereq.json` path [`src/core/path-context.ts`]
+            - `buildRuntimePathFacts(...)`: convert runtime paths into prompt-visible path strings [`src/core/path-context.ts`]
+              - `formatRuntimePathForDisplay(...)`: serialize user-home-relative paths with `~` when applicable [`src/core/path-context.ts`]
+            - `formatRuntimePathForDisplay(...)`: serialize guideline file paths for prompt substitution [`src/core/path-context.ts`]
+        - `renderBundledCommitInstruction(...)`: render `resources/instructions/git_commit.md` or `resources/instructions/git_read-only.md` for `%%COMMIT%%` [`src/core/prompts.ts`]
+          - `readBundledInstruction(...)`: read bundled commit instruction [`src/core/resources.ts`]
+            - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
+              - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
+                - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
+          - `buildPromptReplacements(...)`: merge shared path substitutions with `%%ARGS%%` and `%%PROMPT%%` [`src/core/prompts.ts`]
+        - `applyReplacements(...)`: substitute token values including `%%COMMIT%%` [`src/core/prompts.ts`]
+        - `injectPromptExecutionBlock(...)`: prepend extension-owned runtime instructions for prompt commands [`src/core/prompts.ts`]
+          - `buildPromptExecutionBlock(...)`: serialize git/doc/worktree preflight facts for the prompt [`src/core/prompts.ts`]
+            - `getPromptRequiredDocs(...)`: map the prompt name to canonical-doc probes [`src/core/prompt-command-runtime.ts`]
+        - `injectPiDevConformanceBlock(...)`: add conditional pi.dev governance guidance for read-only docs, interface-contract review, and pi client validation [`src/core/prompts.ts`]
+          - `buildPiDevConformanceBlock(...)`: resolve manifest-gated pi.dev governance rules for read-only docs, interface contracts, and pi client validation [`src/core/prompts.ts`]
         - `adaptPromptForInternalTools(...)`: rewrite tool names for internal wrappers [`src/core/prompts.ts`]
-      - `deliverPromptCommand(...)`: dispatch the rendered prompt into the current active session [`src/index.ts`]
-        - `statusController.state.pendingPromptRequest`: cache the prompt command name and raw `%%ARGS%%` payload for the next successful completion [`src/core/extension-status.ts`]
-        - External boundaries: `pi.sendUserMessage(...)` delivers the rendered prompt payload.
-    - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families and agent-oriented payload builders [`src/index.ts`]
+      - `activatePromptCommandExecution(...)`: switch to the verified execution session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse the persisted replacement-session context when later lifecycle hooks omit `switchSession()`, carry forward the returned replacement-session context for later session-bound work, re-align `process.cwd()` to the execution path, confirm `process.cwd()` plus the persisted execution-session file header cwd when the file is already persisted (treating a not-yet-flushed session file as a non-fatal lazy-persistence state because pi writes session files on first assistant flush), and store the verified runtime path plus reusable command-context state used by later tool execution and prompt-end handling [`src/core/prompt-command-runtime.ts`]
+        - `resolvePromptCommandSwitchContext(...)`: prefer the live command context or fall back to the persisted replacement-session context keyed by the execution-session file [`src/core/prompt-command-runtime.ts`]
+        - `switchPromptCommandSession(...)`: perform the session switch, tolerate the documented stale-extension-context side effect from invalidating the old closure, and let later verification prove whether the target session actually became active [`src/core/prompt-command-runtime.ts`]
+          - `isPromptCommandStaleContextError(...)`: classify stale-extension-context failures raised during prompt-command session switching [`src/core/prompt-command-runtime.ts`]
+        - `writePersistedPromptCommandSessionContext(...)`: store the reusable command-capable replacement-session context for later closure handling [`src/core/prompt-command-state.ts`]
+        - `clearPersistedPromptCommandSessionContext(...)`: drop reusable command-context persistence when worktree routing is inactive [`src/core/prompt-command-state.ts`]
+      - `logPromptWorkflowEvent(...)`: append selected workflow-activation debug entries [`src/index.ts`]
+      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt into the current active session after execution-session activation is verified, preferring replacement-session `sendUserMessage(...)` when available, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
+        - `writePersistedPromptCommandRuntimeState(...)`: mirror the prepared prompt execution plan into process-scoped persistence before the worktree session switch returns control [`src/core/prompt-command-state.ts`]
+        - `isStaleExtensionContextError(...)`: classify stale post-restore delivery rejections from replacement-session `sendUserMessage(...)` [`src/core/extension-status.ts`]
+        - External boundaries: replacement-session `sendUserMessage(...)` or fallback `pi.sendUserMessage(...)` delivers the rendered prompt payload into the active `AgentSession`.
+      - `abortPromptCommandExecution(...)`: restore the original session-backed base path and delete created worktree resources when command-side preflight or prompt handoff fails [`src/core/prompt-command-runtime.ts`]
+        - `restorePromptCommandExecution(...)`: switch back to the original session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse the persisted replacement-session context when lifecycle hooks omit `switchSession()`, carry forward the returned replacement-session context for later session-bound work, re-align `process.cwd()` to `base-path`, confirm `process.cwd()` plus the persisted original-session file header cwd when the file is already persisted, append optional workflow-restore debug entries, clear active worktree path facts, and best-effort realign the live `ctx.cwd` mirror when worktree routing was active without failing on stale or getter-only context mirrors [`src/core/prompt-command-runtime.ts`]
+          - `resolvePromptCommandSwitchContext(...)`: prefer the live command context or fall back to the persisted replacement-session context keyed by the execution-session file [`src/core/prompt-command-runtime.ts`]
+          - `switchPromptCommandSession(...)`: perform the session switch, tolerate the documented stale-extension-context side effect from invalidating the old closure, and let later verification prove whether the target session actually became active [`src/core/prompt-command-runtime.ts`]
+            - `isPromptCommandStaleContextError(...)`: classify stale-extension-context failures raised during prompt-command session switching [`src/core/prompt-command-runtime.ts`]
+          - `logDebugPromptWorkflowEvent(...)`: append selected workflow-restore debug entries [`src/core/debug-runtime.ts`]
+          - `clearPersistedPromptCommandSessionContext(...)`: drop reusable command-context persistence after base-path restoration succeeds [`src/core/prompt-command-state.ts`]
+        - `deletePromptWorktree(...)`: delete the dedicated worktree and branch and append selected worktree-delete debug entries [`src/core/prompt-command-runtime.ts`]
+          - `logDebugPromptEvent(...)`: append selected prompt debug entries for worktree deletion [`src/core/debug-runtime.ts`]
+          - `cleanupPromptWorktreeCreation(...)`: remove registered worktree entries, leftover directories, and matching branches [`src/core/prompt-command-runtime.ts`]
+            - `promptWorktreeRegistered(...)`: test whether the sibling worktree remains registered [`src/core/prompt-command-runtime.ts`]
+            - `promptWorktreeBranchExists(...)`: test whether the matching branch remains present [`src/core/prompt-command-runtime.ts`]
+    - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families, token-optimized payload builders, and compact-plus-expanded custom result renderers [`src/index.ts`]
       - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need bundled assets [`src/core/resources.ts`]
         - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
           - `getInstallationPath(...)`: resolve the installed extension root from the executing module [`src/core/path-context.ts`]
@@ -779,62 +735,24 @@
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-      - `runGitPath(...)`: query the resolved git-path value [`src/core/tool-runner.ts`]
-      - `runGetBasePath(...)`: query the resolved base-path value [`src/core/tool-runner.ts`]
-      - `buildPathQueryToolPayload(...)`: structure token-optimized path-query payloads for `git-path` and `get-base-path` [`src/core/agent-tool-json.ts`]
-      - `buildTokenToolPayload(...)`: construct token-optimized token JSON with direct-access source facts and metrics [`src/core/token-counter.ts`]
-        - `probeRequestedPath(...)`: classify requested paths as readable files, missing inputs, or non-file inputs [`src/core/token-counter.ts`]
-        - `countFilesMetrics(...)`: read readable files and extract token, character, byte, line, heading, and optional Doxygen facts [`src/core/token-counter.ts`]
-          - `buildCountFileMetricsResult(...)`: assemble direct-access per-file metrics and metadata [`src/core/token-counter.ts`]
-            - `TokenCounter.countTokens(...)`: encode content and count tokens [`src/core/token-counter.ts`]
-            - `TokenCounter.countChars(...)`: count characters [`src/core/token-counter.ts`]
-            - `countLines(...)`: count logical lines [`src/core/token-counter.ts`]
-            - `inferLanguageName(...)`: infer agent-oriented language labels [`src/core/token-counter.ts`]
-            - `extractPrimaryHeadingText(...)`: extract the first markdown heading when present [`src/core/token-counter.ts`]
-            - `extractLeadingDoxygenFields(...)`: extract file-level Doxygen fields when present [`src/core/token-counter.ts`]
-              - `parseDoxygenComment(...)`: parse normalized Doxygen fields [`src/core/doxygen-parser.ts`]
-      - `buildTokenToolExecuteResult(...)`: wrap token payloads into tool content and structured details [`src/index.ts`]
-        - `buildTokenToolExecutionStderr(...)`: serialize skipped and error observations into stderr text [`src/index.ts`]
-        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildReferenceToolPayload(...)`: construct token-optimized references JSON with repository structure, symbols, and Doxygen fields [`src/core/reference-payload.ts`]
-        - `canonicalizeReferencePath(...)`: normalize request and file paths against the project base [`src/core/reference-payload.ts`]
-        - `analyzeReferenceFile(...)`: analyze one processable file into structured imports, symbols, and comments [`src/core/reference-payload.ts`]
-        - `buildRepositoryTree(...)`: materialize the repository directory tree as structured JSON [`src/core/reference-payload.ts`]
-      - `buildReferenceToolExecuteResult(...)`: wrap references payloads into tool content and structured details [`src/index.ts`]
-        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildCompressToolPayload(...)`: construct token-optimized compression JSON with structured line facts, symbols, and Doxygen fields [`src/core/compress-payload.ts`]
-        - `analyzeCompressFile(...)`: compress one requested file and attach symbol metadata when available [`src/core/compress-payload.ts`]
-          - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
-          - `analyzeCompressedFileSymbols(...)`: extract symbol and Doxygen records for compressed files [`src/core/compress-payload.ts`]
-      - `buildCompressionToolExecuteResult(...)`: wrap compression payloads into tool content and structured details [`src/index.ts`]
-        - `buildCompressToolExecutionStderr(...)`: serialize skipped, error, and symbol-analysis warning entries [`src/core/compress-payload.ts`]
-        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `buildFindToolSchemaDescription(...)`: synthesize find parameter-schema descriptions [`src/index.ts`]
-      - `buildFindToolPromptGuidelines(...)`: synthesize agent-oriented find guidance strings [`src/index.ts`]
-        - `buildFindToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
-      - `buildFindToolPayload(...)`: construct token-optimized construct-search JSON with structured file statuses, matches, line facts, and Doxygen fields [`src/core/find-payload.ts`]
-        - `validateTagFilter(...)`: normalize requested construct tags [`src/core/find-payload.ts`]
-        - `validateRegexPattern(...)`: compile the construct-name regex [`src/core/find-payload.ts`]
-        - `analyzeFindFile(...)`: analyze one requested file into structured search status and match records [`src/core/find-payload.ts`]
-          - `buildMatchEntry(...)`: structure one matched construct with typed lines and Doxygen fields [`src/core/find-payload.ts`]
-            - `buildStrippedConstructLineEntries(...)`: strip comments into structured code lines [`src/core/find-constructs.ts`]
-      - `buildFindToolExecuteResult(...)`: wrap construct-search payloads into tool content and structured details [`src/index.ts`]
-        - `buildFindToolExecutionStderr(...)`: serialize invalid-request, skipped, no-match, and analysis-error diagnostics [`src/core/find-payload.ts`]
-        - `buildStructuredToolExecuteResult(...)`: mirror the final JSON object into tool content and details [`src/core/agent-tool-json.ts`]
-      - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
-      - `collectProjectStaticCheckSelection(...)`: derive project static-check file selections and fixture exclusions [`src/index.ts`]
-      - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
-      - `buildStaticCheckToolPayload(...)`: structure token-optimized static-check summary, file-selection, and execution facts [`src/core/agent-tool-json.ts`]
-      - `runGitCheck(...)`: validate runtime repository cleanliness [`src/core/tool-runner.ts`]
-      - `buildGitCheckToolPayload(...)`: structure token-optimized git-validation status and execution facts [`src/core/agent-tool-json.ts`]
-      - `buildDocsCheckToolPayload(...)`: structure token-optimized canonical-doc presence and remediation facts [`src/core/agent-tool-json.ts`]
-      - `runGitWtName(...)`: generate the standardized worktree name [`src/core/tool-runner.ts`]
-      - `buildWorktreeNameToolPayload(...)`: structure token-optimized worktree-name generation facts [`src/core/agent-tool-json.ts`]
-      - `runGitWtCreate(...)`: create a dedicated worktree and branch [`src/core/tool-runner.ts`]
-      - `runGitWtDelete(...)`: delete a dedicated worktree and branch [`src/core/tool-runner.ts`]
-      - `buildWorktreeMutationToolPayload(...)`: structure token-optimized worktree create-delete facts [`src/core/agent-tool-json.ts`]
-      - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
-      - `normalizeToolFailure(...)`: convert `ReqError` failures into structured execution records [`src/core/agent-tool-json.ts`]
+      - `buildSearchToolSchemaDescription(...)`: synthesize search parameter-schema descriptions [`src/index.ts`]
+      - `buildSearchToolPromptGuidelines(...)`: synthesize agent-oriented search guidance strings [`src/index.ts`]
+        - `buildSearchToolSupportedTagGuidelines(...)`: emit per-language supported-tag guidance lines [`src/index.ts`]
+      - `buildStructuredToolRenderResult(...)`: attach compact invocation-parameter summaries and expanded monolithic result renderers to every agent tool [`src/index.ts`]
+      - `executeMonolithicTool(...)`: execute one CLI-style runner and wrap one monolithic content block plus minimal execution details [`src/index.ts`]
+        - `runFilesTokens(...)`: execute the monolithic token pack-summary runner [`src/core/tool-runner.ts`]
+        - `runFilesReferences(...)`: execute the monolithic explicit-file references markdown runner [`src/core/tool-runner.ts`]
+        - `runFilesCompress(...)`: execute the monolithic explicit-file compression markdown runner [`src/core/tool-runner.ts`]
+        - `runFilesSearch(...)`: execute the monolithic explicit-file construct-search markdown runner [`src/core/tool-runner.ts`]
+        - `runReferences(...)`: execute the monolithic project references markdown runner [`src/core/tool-runner.ts`]
+        - `runCompress(...)`: execute the monolithic project compression markdown runner [`src/core/tool-runner.ts`]
+        - `runSearch(...)`: execute the monolithic project construct-search markdown runner [`src/core/tool-runner.ts`]
+        - `runTokens(...)`: execute the monolithic canonical-doc token runner [`src/core/tool-runner.ts`]
+        - `runFilesStaticCheck(...)`: execute configured checkers for explicit-file requests [`src/core/tool-runner.ts`]
+        - `runProjectStaticCheck(...)`: execute configured checkers for project source and test selections [`src/core/tool-runner.ts`]
+        - `buildMonolithicToolExecuteResult(...)`: wrap runner stdout or stderr into tool content plus execution details [`src/core/agent-tool-json.ts`]
+          - `buildToolExecutionSection(...)`: normalize residual stdout, stderr, and exit-code metadata [`src/core/agent-tool-json.ts`]
+        - `normalizeToolFailure(...)`: convert runner failures into deterministic execution records [`src/core/agent-tool-json.ts`]
     - `registerConfigCommands(...)`: register interactive configuration commands [`src/index.ts`]
       - `configurePiUsereq(...)`: interactive configuration menu root [`src/index.ts`]
       - `configurePiUsereq(...)`: serve the inline `show-config` action inside the shared settings-menu flow [`src/index.ts`]
@@ -843,6 +761,7 @@
           - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
           - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+          - `normalizeGitWorktreePrefix(...)`: canonicalize persisted worktree prefix [`src/core/config.ts`]
           - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
           - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
           - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
@@ -850,73 +769,152 @@
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
           - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-    - `registerPiNotifyShortcut(...)`: register the configured successful-run sound shortcut when the runtime supports shortcuts [`src/index.ts`]
+    - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut when the runtime supports shortcuts [`src/index.ts`]
+      - `getProcessCwdSafe(...)`: resolve a fallback-safe process cwd for extension-load registration [`src/index.ts`]
       - `loadProjectConfig(...)`: load config for shortcut registration [`src/index.ts`]
         - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
         - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
           - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
           - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
+          - `normalizeGitWorktreePrefix(...)`: canonicalize persisted worktree prefix [`src/core/config.ts`]
           - `normalizePiNotifySoundLevel(...)`: normalize persisted sound level [`src/core/pi-notify.ts`]
           - `normalizePiNotifyShortcut(...)`: normalize persisted shortcut [`src/core/pi-notify.ts`]
           - `normalizePiNotifyCommand(...)`: normalize persisted sound commands [`src/core/pi-notify.ts`]
-        - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-        - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-          - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-    - `registerExtensionStatusHooks(...)`: register shared wrappers for lifecycle telemetry hooks [`src/index.ts`]
-      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers [`src/index.ts`]
-        - `loadProjectConfig(...)`: session-start configuration load [`src/index.ts`]
-          - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+    - `registerExtensionStatusHooks(...)`: register shared wrappers for lifecycle telemetry hooks and suppress the documented stale-extension-context callbacks that can arrive after successful session replacement [`src/index.ts`]
+      - `handleExtensionStatusEvent(...)`: process intercepted hook payloads through shared status helpers, tool-result debug logging, dedicated workflow-closure plus shutdown diagnostics built from pre-shutdown prompt snapshots, workflow-state transitions, recover a live bootstrap cwd during `session_start` when stale context mirrors still point at deleted worktrees, matched-success prompt-command restoration to `base-path` plus merge and worktree deletion, stale-safe closure notifications, and matched-failure base-path restoration plus closure-error notification using persisted replacement-session contexts when event hooks omit `switchSession()` [`src/index.ts`]
+        - `resolveLiveBootstrapCwd(...)`: recover a live bootstrap cwd from the startup context, runtime path state, or process cwd when stale worktree paths no longer exist [`src/index.ts`]
+        - `syncContextCwdMirror(...)`: best-effort realign the startup context `cwd` mirror to the recovered live cwd before startup config loads [`src/index.ts`]
+        - `loadProjectConfig(...)`: session-start configuration load from the recovered live cwd [`src/index.ts`]
+          - `getProjectBase(...)`: resolve project base from the recovered live cwd [`src/index.ts`]
           - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
             - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
             - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
               - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-          - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-            - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
-          - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-            - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
         - `applyConfiguredPiUsereqTools(...)`: enable configured active tools on `session_start` [`src/index.ts`]
           - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-          - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+          - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
         - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for later status renders [`src/core/extension-status.ts`]
-        - `updateExtensionStatus(...)`: refresh stored context usage, elapsed timers, prompt-request state, cumulative runtime, and rendered status text [`src/core/extension-status.ts`]
+        - `activatePromptCommandExecution(...)`: re-verify the prepared execution session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse persisted replacement-session contexts when lifecycle hooks omit `switchSession()`, re-align `process.cwd()` to the execution path, confirm `process.cwd()` plus the persisted execution-session file header cwd when the file is already persisted before agent start, and refresh reusable command-context persistence [`src/core/prompt-command-runtime.ts`]
+        - `resolveDebugProjectBase(...)`: prefer static `base-path` for debug-log writes during worktree-backed prompt runs and recover a live bootstrap cwd when no prompt plan is active [`src/index.ts`]
+        - `notifyContextSafely(...)`: suppress stale replacement-context notification failures after session replacement while preserving closure progress [`src/index.ts`]
+        - `logDebugToolExecution(...)`: append selected tool-result debug entries [`src/core/debug-runtime.ts`]
+        - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore persisted elapsed timers on `session_start`, restore persisted prompt-command state when the active session matches the forked execution session, resynchronize that state on later lifecycle hooks after switch-triggered rebinding, preserve in-memory prompt-command state plus process-scoped persistence across `session_shutdown`, accumulate completed runtime, and render status text while tolerating stale replacement contexts [`src/core/extension-status.ts`]
           - `refreshContextUsage(...)`: sync the latest context-usage snapshot [`src/core/extension-status.ts`]
+          - `shouldResetElapsedStateOnSessionStart(...)`: detect `startup|reload` reset boundaries [`src/core/extension-status.ts`]
+          - `resetElapsedState(...)`: clear in-memory and persisted completed timers [`src/core/extension-status.ts`]
+          - `restorePersistedElapsedState(...)`: restore persisted completed timers for `new|resume|fork` [`src/core/extension-status.ts`]
+          - `restorePersistedPromptCommandState(...)`: restore persisted workflow state plus prompt execution plans when the current session file matches the forked execution session [`src/core/extension-status.ts`]
+          - `getContextSessionFile(...)`: read the active session file from the current extension context for prompt-state resynchronization [`src/core/extension-status.ts`]
+            - `restorePersistedPromptCommandRuntimeStateForSession(...)`: read the process-scoped prompt execution store for the current session file [`src/core/prompt-command-state.ts`]
+          - `shouldResetWorkflowStateOnSessionStart(...)`: detect `startup|new|reload` workflow-reset boundaries [`src/core/extension-status.ts`]
+          - `persistElapsedState(...)`: mirror completed timers into process-scoped persistence [`src/core/extension-status.ts`]
+          - `shouldPreservePromptCommandStateOnShutdown(...)`: detect switch-triggered `session_shutdown` events that must keep in-memory prompt state plus prompt execution persistence intact [`src/core/extension-status.ts`]
+          - `isStaleExtensionContextError(...)`: detect stale replacement-session render failures after session replacement [`src/core/extension-status.ts`]
+          - `persistPromptCommandState(...)`: mirror workflow state plus pending or active prompt execution plans into process-scoped persistence [`src/core/extension-status.ts`]
+            - `writePersistedPromptCommandRuntimeState(...)`: store workflow state plus pending or active prompt execution plans on `globalThis` [`src/core/prompt-command-state.ts`]
           - `syncPiUsereqStatusTicker(...)`: start or stop the live elapsed ticker [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound/pushover footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
             - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics plus the Pushover enable field [`src/core/extension-status.ts`]
+            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
               - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
               - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-              - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-                - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
-                - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+              - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
+              - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+                - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
               - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
                 - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
                 - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-              - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-              - `formatPiNotifyPushoverStatus(...)`: serialize the dedicated Pushover enable flag for the footer [`src/core/pi-notify.ts`]
-        - `runPiNotifyEffects(...)`: dispatch configured terminal beeps, successful-run sound hooks, and optional Pushover API requests on `agent_end` [`src/core/pi-notify.ts`]
-          - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `end`, `esc`, or `err` [`src/core/pi-notify.ts`]
+        - `runPiNotifyEffects(...)`: dispatch configured command-notify, sound, and optional Pushover API requests on `agent_end` [`src/core/pi-notify.ts`]
+          - `classifyPiNotifyOutcome(...)`: map assistant stop reasons to `completed`, `interrupted`, or `failed` [`src/core/pi-notify.ts`]
             - `hasAgentEndStopReason(...)`: scan assistant stop reasons inside the `agent_end` payload [`src/core/pi-notify.ts`]
-          - `buildPiNotifyTitle(...)`: build the stable pi-notify title [`src/core/pi-notify.ts`]
-          - `buildPiNotifyBody(...)`: build the stable pi-notify body from the classified outcome [`src/core/pi-notify.ts`]
-          - `notifyPiTerminal(...)`: route terminal notifications by runtime environment when the matching beep flag is enabled [`src/core/pi-notify.ts`]
-            - `notifyWindows(...)`: emit Windows toast notifications [`src/core/pi-notify.ts`]
-            - `notifyOSC99(...)`: emit Kitty OSC 99 notifications [`src/core/pi-notify.ts`]
-            - `notifyOSC9(...)`: emit OSC 9 notifications [`src/core/pi-notify.ts`]
-            - `notifyOSC777(...)`: emit OSC 777 notifications [`src/core/pi-notify.ts`]
-          - `runPiNotifySoundCommand(...)`: execute the configured successful-run sound command when sound is enabled [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifyCommand(...)`: execute `PI_NOTIFY_CMD` with runtime placeholder substitution [`src/core/pi-notify.ts`]
+            - `substitutePiNotifyShellTemplate(...)`: replace installation, prompt, base, time, args, and result placeholders inside the shell template [`src/core/pi-notify.ts`]
+              - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+              - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+                - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+              - `escapePiNotifyShellTemplateValue(...)`: escape prompt-scoped values for double-quoted shell insertion [`src/core/pi-notify.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+            - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifySound(...)`: validate sound level plus the matching event toggle [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifySoundCommand(...)`: execute the configured sound command when the sound level and matching event toggle permit delivery [`src/core/pi-notify.ts`]
             - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
             - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
               - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
-              - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
-          - `runPiNotifyPushoverRequest(...)`: POST the successful prompt payload to the Pushover Message API when credentials and flags permit delivery [`src/core/pi-notify.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+            - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifyPushover(...)`: validate global Pushover enablement, the matching event toggle, and required credentials [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifyPushoverRequest(...)`: POST the prompt-end payload to the Pushover Message API when credentials and flags permit delivery [`src/core/pi-notify.ts`]
             - `buildPiNotifyPushoverPayload(...)`: serialize token, user, title, priority, and message fields [`src/core/pi-notify.ts`]
-            - `buildPiNotifyPushoverTitle(...)`: compose `<prompt> @ <base-path> [<time>]` for successful completion [`src/core/pi-notify.ts`]
-            - `buildPiNotifyPushoverBody(...)`: reuse the raw prompt argument payload [`src/core/pi-notify.ts`]
-  - `configurePiUsereq(...)`: interactive configuration menu runtime root [`src/index.ts`]
+              - `buildPiNotifyPushoverTitle(...)`: resolve the configured Pushover title template [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyTextTemplate(...)`: replace prompt-scoped placeholders inside the title template [`src/core/pi-notify.ts`]
+                  - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+              - `buildPiNotifyPushoverBody(...)`: resolve the configured Pushover text template [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyTextTemplate(...)`: replace prompt-scoped placeholders inside the text template [`src/core/pi-notify.ts`]
+                  - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+        - `classifyPromptCommandOutcome(...)`: map agent-end payloads to `completed|interrupted|failed` [`src/core/prompt-command-runtime.ts`]
+        - `logPromptWorkflowEvent(...)`: append selected workflow-closure and workflow-session-shutdown debug entries [`src/index.ts`]
+        - `transitionPromptWorkflowState(...)`: transition workflow state for matched-success merge handling and final idle restoration, and append gated workflow-state debug entries immediately after each transition [`src/index.ts`]
+          - `setPiUsereqWorkflowState(...)`: transition workflow state for matched-success merge handling and final idle restoration [`src/core/extension-status.ts`]
+            - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer with CLI-theme token overlays [`src/core/extension-status.ts`]
+          - `logPromptWorkflowStateChange(...)`: append selected prompt workflow-transition debug entries [`src/index.ts`]
+        - `finalizePromptCommandExecution(...)`: verify persisted execution-session header metadata plus live worktree artifacts, restore the original session-backed base path through the persisted replacement-session context when lifecycle hooks omit `switchSession()`, merge the matched successful worktree branch with `--ff-only` from `base-path`, delete the worktree and branch after merge success, and append selected merge plus workflow-restore debug entries [`src/core/prompt-command-runtime.ts`]
+          - `verifyPromptCommandClosureArtifacts(...)`: verify execution-session header cwd, worktree registration, branch presence, and worktree-path existence without requiring worktree-session reactivation after prompt end [`src/core/prompt-command-runtime.ts`]
+          - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path, reuse the persisted replacement-session context keyed by the execution-session file, append optional workflow-restore debug entries, clear active worktree path facts, and realign the live `ctx.cwd` mirror before merge or merge-abort return [`src/core/prompt-command-runtime.ts`]
+          - `deletePromptWorktree(...)`: delete the merged worktree and branch after successful fast-forward merge [`src/core/prompt-command-runtime.ts`]
+        - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path when interrupted, failed, or unmatched prompt-end events skip merge and retain the worktree for manual recovery, reusing the persisted replacement-session context when lifecycle hooks omit `switchSession()` [`src/core/prompt-command-runtime.ts`]
+          - `shouldRunPiNotifyCommand(...)`: validate prompt-scoped command-notify prerequisites [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifyCommand(...)`: execute `PI_NOTIFY_CMD` with runtime placeholder substitution [`src/core/pi-notify.ts`]
+            - `substitutePiNotifyShellTemplate(...)`: replace installation, prompt, base, time, args, and result placeholders inside the shell template [`src/core/pi-notify.ts`]
+              - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+              - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+                - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+              - `escapePiNotifyShellTemplateValue(...)`: escape prompt-scoped values for double-quoted shell insertion [`src/core/pi-notify.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+            - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifySound(...)`: validate sound level plus the matching event toggle [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifySoundCommand(...)`: execute the configured sound command when the sound level and matching event toggle permit delivery [`src/core/pi-notify.ts`]
+            - `resolvePiNotifySoundCommand(...)`: select the configured command for `low`, `mid`, or `high` [`src/core/pi-notify.ts`]
+            - `substitutePiNotifyInstallPath(...)`: replace `%%INSTALLATION_PATH%%` before shell execution [`src/core/pi-notify.ts`]
+              - `quotePiNotifyInstallPath(...)`: quote the installation path for shell reuse [`src/core/pi-notify.ts`]
+            - `getInstallationPath(...)`: resolve the installed extension root [`src/core/path-context.ts`]
+            - `runPiNotifyShellCommand(...)`: spawn one detached shell command [`src/core/pi-notify.ts`]
+          - `shouldRunPiNotifyPushover(...)`: validate global Pushover enablement, the matching event toggle, and required credentials [`src/core/pi-notify.ts`]
+            - `isPiNotifyOutcomeEnabled(...)`: map `completed|interrupted|failed` to the selected toggle set [`src/core/pi-notify.ts`]
+          - `runPiNotifyPushoverRequest(...)`: POST the prompt-end payload to the Pushover Message API when credentials and flags permit delivery [`src/core/pi-notify.ts`]
+            - `buildPiNotifyPushoverPayload(...)`: serialize token, user, title, priority, and message fields [`src/core/pi-notify.ts`]
+              - `buildPiNotifyPushoverTitle(...)`: resolve the configured Pushover title template [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyTextTemplate(...)`: replace prompt-scoped placeholders inside the title template [`src/core/pi-notify.ts`]
+                  - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+              - `buildPiNotifyPushoverBody(...)`: resolve the configured Pushover text template [`src/core/pi-notify.ts`]
+                - `substitutePiNotifyTextTemplate(...)`: replace prompt-scoped placeholders inside the text template [`src/core/pi-notify.ts`]
+                  - `buildPiNotifyRuntimeTemplateValues(...)`: resolve raw prompt-scoped placeholder values [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
+                    - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
+  - `configurePiUsereq(...)`: interactive configuration menu runtime root for directories, `Auto git commit`, locked-or-editable worktree rows, tools, notifications, and debug settings [`src/index.ts`]
     - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -928,72 +926,98 @@
       - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
         - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
     - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
-    - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions plus the display-only config-path row [`src/index.ts`]
-      - `formatProjectConfigPathForMenu(...)`: format the current config path relative to the user home when possible [`src/index.ts`]
+    - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including effective worktree locking, notification and debug summaries, the display-only config-path row, and reset-only terminal rows [`src/index.ts`]
+      - `formatDebugMenuSummary(...)`: summarize global debug mode plus selected tool and prompt counts [`src/index.ts`]
+      - `formatProjectConfigPathForMenu(...)`: format the current config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
+      - `buildTerminalSettingsMenuChoices(...)`: append the canonical `Reset defaults` row without `Save and close` [`src/index.ts`]
     - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions [`src/core/settings-menu.ts`]
       - `formatPiUsereqSettingsMenuTitle(...)`: rebuild the menu title with active-theme semantics [`src/core/settings-menu.ts`]
       - `buildPiUsereqSettingsListTheme(...)`: prefer shared CLI settings-list theming and fall back during offline replay [`src/core/settings-menu.ts`]
         - `buildFallbackPiUsereqSettingsListTheme(...)`: mirror CLI settings-list token roles from the callback-local theme [`src/core/settings-menu.ts`]
-      - `buildSettingItems(...)`: map menu choices into settings-list rows and apply optional dim value tones [`src/core/settings-menu.ts`]
-    - `saveProjectConfig(...)`: persist config on save-and-close [`src/index.ts`]
+      - `buildSettingItems(...)`: map menu choices into settings-list rows, apply optional dim tones, and disable non-selectable actions [`src/core/settings-menu.ts`]
+    - `persistConfigChange(...)`: persist config immediately after every settings mutation and refresh status rendering [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `saveConfig(...)`: persist config JSON [`src/core/config.ts`]
         - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
+    - `writePersistedProjectConfigToEditor(...)`: read the already-persisted config file and write its exact text into the editor [`src/index.ts`]
+      - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
+      - `getProjectConfigPath(...)`: resolve the persisted config path [`src/core/config.ts`]
     - `setPiUsereqStatusConfig(...)`: cache the just-saved docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
-    - `renderPiUsereqStatus(...)`: render the base/context/elapsed/beep/sound/pushover footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
+    - `renderPiUsereqStatus(...)`: render the status/current-path/context/elapsed/sound footer after save-and-close with CLI-theme token overlays [`src/core/extension-status.ts`]
       - `createStatusThemeAdapter(...)`: constrain status rendering to CLI-supported `accent`, `warning`, `dim`, and `error` theme tokens [`src/core/extension-status.ts`]
-      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with consolidated elapsed semantics plus the Pushover enable field [`src/core/extension-status.ts`]
+      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with workflow state, current-path, elapsed semantics, and sound status fields [`src/core/extension-status.ts`]
         - `formatStatusField(...)`: render one colored text field [`src/core/extension-status.ts`]
         - `formatRenderedStatusField(...)`: render one pre-styled field [`src/core/extension-status.ts`]
-        - `formatContextUsageBar(...)`: render the 10-cell context bar or threshold-specific overlay [`src/core/extension-status.ts`]
-          - `resolveContextUsageOverlay(...)`: choose `◀ CLEAR ▶ ` or ` ◀ FULL ▶ ` overlay states with CLI-supported theme tokens [`src/core/extension-status.ts`]
-          - `formatContextUsageOverlay(...)`: paint the fixed-width overlay with preserved bar background [`src/core/extension-status.ts`]
+        - `formatWorkflowStateValue(...)`: render the workflow-state value with error highlighting when required [`src/core/extension-status.ts`]
+        - `formatContextUsageBar(...)`: render the icon-based context gauge [`src/core/extension-status.ts`]
+          - `resolveContextUsageIconText(...)`: map normalized context usage to the fixed-width gauge icon [`src/core/extension-status.ts`]
         - `formatElapsedStatusValue(...)`: compose `⏱︎`, `⚑`, and `⌛︎` timer segments [`src/core/extension-status.ts`]
           - `formatCompletedStatusDuration(...)`: render completed timers or the unset placeholder [`src/core/extension-status.ts`]
           - `formatStatusDuration(...)`: render `M:SS` durations [`src/core/extension-status.ts`]
-        - `formatPiNotifyBeepStatus(...)`: serialize enabled beep flags for the footer [`src/core/pi-notify.ts`]
-    - `configureStaticCheckMenu(...)`: interactive static-check editor [`src/index.ts`]
-      - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
-      - `renderStaticCheckReference(...)`: render static-check reference text [`src/index.ts`]
-        - `formatStaticCheckLanguagesSummary(...)`: summarize configured checker languages [`src/index.ts`]
-        - `formatStaticCheckEntry(...)`: format one configured checker entry [`src/index.ts`]
+    - `configureStaticCheckMenu(...)`: interactive guided static-check editor with per-language enable toggles [`src/index.ts`]
+      - `getStaticCheckLanguageConfigForMenu(...)`: resolve a menu-facing per-language static-check object [`src/index.ts`]
+      - `countConfiguredStaticCheckLanguages(...)`: count languages that retain checker entries [`src/index.ts`]
+      - `countEnabledStaticCheckLanguages(...)`: count languages whose enable flag is on [`src/index.ts`]
+      - `formatStaticCheckLanguagesSummary(...)`: summarize enabled and configured checker languages [`src/index.ts`]
+      - `buildStaticCheckMenuChoices(...)`: serialize guided add/remove actions plus direct per-language toggle rows [`src/index.ts`]
         - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
           - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
-      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with configured counts [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with enablement, configured counts, and terminal rows [`src/index.ts`]
+        - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
+          - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `buildConfiguredStaticCheckLanguageChoices(...)`: serialize configured languages plus terminal rows for removal flows [`src/index.ts`]
+        - `getSupportedStaticCheckLanguageSupport(...)`: enumerate supported languages and extensions [`src/core/static-check.ts`]
+          - `getSupportedStaticCheckLanguages(...)`: enumerate canonical supported languages [`src/core/static-check.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `resetStaticCheckConfig(...)`: restore documented per-language static-check defaults [`src/index.ts`]
+        - `getDefaultStaticCheckConfig(...)`: build documented per-language static-check defaults [`src/core/config.ts`]
+          - `createStaticCheckLanguageConfig(...)`: clone checker entries and derive the enable flag [`src/core/config.ts`]
+      - `createStaticCheckLanguageConfig(...)`: create empty per-language configs for toggle and removal flows [`src/core/config.ts`]
       - `shellSplit(...)`: parse optional parameter input [`src/core/utils.ts`]
-      - `parseEnableStaticCheck(...)`: parse `LANG=Command,CMD[,PARAM...]` specification [`src/core/static-check.ts`]
-        - `splitCsvLikeTokens(...)`: split comma-like spec payload with quoting support [`src/core/static-check.ts`]
-        - `formatStaticCheckModules(...)`: render valid user modules for error paths [`src/core/static-check.ts`]
-    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor [`src/index.ts`]
+    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor without a status-reference action [`src/index.ts`]
       - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
         - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
           - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-        - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
-      - `renderPiUsereqToolsReference(...)`: render configurable active-tool reference text [`src/index.ts`]
-        - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
-        - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
-          - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-        - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
+        - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
       - `setConfiguredPiUsereqTools(...)`: persist selected enabled tools in memory [`src/index.ts`]
         - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
         - `applyConfiguredPiUsereqTools(...)`: enforce configured active-tool set [`src/index.ts`]
           - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-          - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
-      - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows [`src/index.ts`]
-        - `getPiUsereqToolKind(...)`: classify builtin versus extension tools for UI rendering [`src/index.ts`]
-    - `configurePiNotifyMenu(...)`: interactive pi-notify editor [`src/index.ts`]
-      - `buildPiNotifyMenuChoices(...)`: serialize notification actions plus the nested Pushover submenu entry for the shared settings menu [`src/index.ts`]
-      - `togglePiNotifyBeepFlag(...)`: toggle one prompt-end beep flag [`src/index.ts`]
-      - `configurePiNotifyPushoverMenu(...)`: interactive Pushover editor nested under the notifications menu [`src/index.ts`]
-        - `buildPiNotifyPushoverMenuChoices(...)`: serialize Pushover global-disable, enable, credential, and priority actions [`src/index.ts`]
-        - `selectPiNotifyPushoverPriority(...)`: present the `0=Normal` and `1=High Priority` selector [`src/index.ts`]
-    - `getDefaultConfig(...)`: restore default config on reset [`src/core/config.ts`]
+          - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
+      - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows plus terminal reset/save actions [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+    - `configureDebugMenu(...)`: interactive debug editor for global enablement, log path, status-change logging, dedicated workflow-event logging, workflow filters, reset confirmation, and per-tool plus per-prompt toggles [`src/index.ts`]
+      - `buildDebugMenuChoices(...)`: serialize global debug controls, workflow-event toggles, canonical tool and prompt toggles, and terminal rows [`src/index.ts`]
+        - `buildDebugMenuChoice(...)`: dim and disable locked debug rows while global debug is off [`src/index.ts`]
+        - `getDebugToolToggleNames(...)`: enumerate debuggable tool names in canonical grouped order [`src/index.ts`]
+      - `selectDebugLogOnStatus(...)`: select one explicit workflow-state filter or `any` [`src/index.ts`]
+      - `confirmResetChanges(...)`: require explicit approval before applying reset mutations [`src/index.ts`]
+      - `resetDebugConfigToDefaults(...)`: restore the debug configuration subtree to documented defaults [`src/index.ts`]
+    - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor with credential-locked enablement, immediate-save mutations, reset confirmation, and dedicated event submenus [`src/index.ts`]
+      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers and terminal rows [`src/index.ts`]
+        - `buildPiNotifyEventLauncherChoice(...)`: serialize one event-submenu launcher row with a compact enabled-toggle summary [`src/index.ts`]
+        - `buildPiNotifyPushoverRows(...)`: serialize direct Pushover rows with locked enablement plus the shared event-submenu launcher [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows [`src/index.ts`]
+      - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor for one notification transport [`src/index.ts`]
+        - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus submenu reset/save actions [`src/index.ts`]
+        - `resetPiNotifyEventMenuToDefaults(...)`: restore default event toggles for one notification transport [`src/index.ts`]
+        - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
+        - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+      - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+      - `selectPiNotifySoundLevel(...)`: present the `Enable sound` selector with subtree-local reset/save actions [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector with subtree-local reset/save actions [`src/index.ts`]
+        - `buildTerminalSettingsMenuChoices(...)`: append canonical terminal rows to the selector menu [`src/index.ts`]
+      - `resetPiNotifyConfigToDefaults(...)`: restore notification settings to documented defaults [`src/index.ts`]
+    - `getDefaultConfig(...)`: restore default config on reset and subtree-local selector resets [`src/core/config.ts`]
       - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
     - `applyConfiguredPiUsereqTools(...)`: re-apply active tools after reset [`src/index.ts`]
       - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
         - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-      - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory [`src/index.ts`]
+      - `getPiUsereqStartupTools(...)`: enumerate configurable tools from runtime inventory in documented menu order [`src/index.ts`]
 - External Boundaries:
   - pi ExtensionAPI plus command-context APIs for command registration, tool registration, shortcut registration, user-message delivery, session events, active-tool mutation, editor updates, notifications, selections, and text input.
   - Filesystem access for home resource cache, bundled prompt reads, and project config persistence.