pi-usereq 0.48.0 → 0.50.0

package/pi-usereq/docs/WORKFLOW.md

@@ -1,1341 +0,0 @@
-## Execution Units Index
-- ID: `PROC:main`
-  - Type: Process
-  - Role: Standalone `req` CLI dispatcher.
-  - Entrypoints:
-    - `main(...)` [`src/cli.ts`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-- ID: `PROC:req-debug`
-  - Type: Process
-  - Role: Bash wrapper dispatcher for standalone extension-debug inspection, session replay, prompt replay, tool replay, and raw harness passthrough.
-  - Entrypoints:
-    - `main(...)` [`scripts/pi-usereq-debug.sh`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-- ID: `PROC:tool-args-to-params`
-  - Type: Process
-  - Role: Tool-argument normalization helper that converts wrapper `--args` text into debug-harness `--params` JSON.
-  - Entrypoints:
-    - `main(...)` [`scripts/tool-args-to-params.ts`]
-  - Parent Process: `PROC:req-debug`
-  - Threads: no explicit threads detected
-- ID: `PROC:debug-ext`
-  - Type: Process
-  - Role: Standalone extension debug-harness dispatcher for offline registration inspection, handler replay, and SDK parity smoke execution.
-  - Entrypoints:
-    - `main(...)` [`scripts/debug-extension.ts`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-- ID: `PROC:pi-host`
-  - Type: Process
-  - Role: pi extension host callback surface for commands, tools, shortcuts, session initialization, and interactive configuration.
-  - Entrypoints:
-    - `piUsereqExtension(...)` [`src/index.ts`]
-    - `configurePiUsereq(...)` [`src/index.ts`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-- ID: `PROC:gh-release-check`
-  - Type: Process
-  - Role: GitHub Actions release-gate runner that validates the workflow tag trigger ancestry against `origin/master` before downstream release work.
-  - Entrypoints:
-    - `check-branch(...)` [`.github/workflows/release-npm.yml`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-- ID: `PROC:gh-release-build`
-  - Type: Process
-  - Role: GitHub Actions release runner that configures Node.js `24.15.0`, publishes the npm package, builds changelog text, and creates the GitHub Release after branch gating succeeds.
-  - Entrypoints:
-    - `build-release(...)` [`.github/workflows/release-npm.yml`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-- ID: `PROC:install-static-checkers`
-  - Type: Process
-  - Role: Best-effort npm `postinstall` installer that writes consumer-root name-only `allowScripts` approvals, probes bundled static-checker executables, attempts `npm install` on miss, and prints platform guidance for native checkers.
-  - Entrypoints:
-    - `main(...)` [`scripts/install-static-checkers.ts`]
-  - Parent Process: none
-  - Threads: no explicit threads detected
-
-## Execution Units
-### `PROC:main`
-- Entrypoints:
-  - `main(...)`: CLI runtime root [`src/cli.ts`]
-- Lifecycle/trigger:
-  - Start trigger: Node executes `src/cli.ts` as a one-shot command.
-  - Stop trigger: returns numeric exit code after one dispatch path or caught `ReqError`.
-  - Looping model: single-pass argument parse followed by single branch dispatch.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `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 into global checker lists, preserve existing entries, and force targeted local enable flags on before command dispatch [`src/cli.ts`]
-      - `loadMutableProjectConfig(...)`: load effective config without intermediate persistence [`src/cli.ts`]
-        - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-        - `loadConfig(...)`: load merged local/global config or defaults [`src/core/config.ts`]
-          - `loadGlobalConfig(...)`: load global config or defaults [`src/core/config.ts`]
-            - `getGlobalConfigPath(...)`: resolve global config file path [`src/core/config.ts`]
-            - `readConfigPayload(...)`: parse persisted global config JSON when present [`src/core/config.ts`]
-          - `loadLocalConfig(...)`: load local config or defaults using global static-check enable defaults [`src/core/config.ts`]
-            - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
-            - `readConfigPayload(...)`: parse persisted local config JSON when present [`src/core/config.ts`]
-          - `mergeConfigScopes(...)`: combine local and global config into the effective runtime config [`src/core/config.ts`]
-            - `mergeStaticCheckConfig(...)`: combine local enable flags with global checker arrays [`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`]
-      - `buildStaticCheckEntryIdentity(...)`: normalize entry duplicate identity [`src/core/static-check.ts`]
-      - `parseEnableStaticCheck(...)`: parse one static-check enable specification [`src/core/static-check.ts`]
-      - `validateStaticCheckEntry(...)`: validate command-backed entry before config write [`src/core/static-check.ts`]
-        - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or PATH scan [`src/core/static-check.ts`]
-          - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
-            - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
-      - `saveConfig(...)`: persist split local/global config JSON [`src/core/config.ts`]
-        - `saveLocalConfig(...)`: write the local config file [`src/core/config.ts`]
-          - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
-        - `saveGlobalConfig(...)`: write the global config file [`src/core/config.ts`]
-          - `getGlobalConfigPath(...)`: resolve global config file path [`src/core/config.ts`]
-    - `loadAndRepairConfig(...)`: persist normalized config when `--here` or `--base` is active and no CLI static-check mutation is requested [`src/core/tool-runner.ts`]
-      - `resolveProjectBase(...)`: validate project base path [`src/core/tool-runner.ts`]
-      - `loadConfig(...)`: load merged local/global config or defaults [`src/core/config.ts`]
-        - `loadGlobalConfig(...)`: load global config or defaults [`src/core/config.ts`]
-          - `getGlobalConfigPath(...)`: resolve global config file path [`src/core/config.ts`]
-          - `readConfigPayload(...)`: parse persisted global config JSON when present [`src/core/config.ts`]
-        - `loadLocalConfig(...)`: load local config or defaults using global static-check enable defaults [`src/core/config.ts`]
-          - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
-          - `readConfigPayload(...)`: parse persisted local config JSON when present [`src/core/config.ts`]
-        - `mergeConfigScopes(...)`: combine local and global config into the effective runtime config [`src/core/config.ts`]
-          - `mergeStaticCheckConfig(...)`: combine local enable flags with global checker arrays [`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`]
-      - `saveConfig(...)`: persist split local/global config JSON [`src/core/config.ts`]
-        - `saveLocalConfig(...)`: write the local config file [`src/core/config.ts`]
-          - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
-        - `saveGlobalConfig(...)`: write the global config file [`src/core/config.ts`]
-          - `getGlobalConfigPath(...)`: resolve global config file path [`src/core/config.ts`]
-    - `loadConfig(...)`: load effective merged local/global config for dispatch when no CLI static-check mutation is requested [`src/core/config.ts`]
-      - `loadGlobalConfig(...)`: load global config or defaults [`src/core/config.ts`]
-        - `getGlobalConfigPath(...)`: resolve global config file path [`src/core/config.ts`]
-        - `readConfigPayload(...)`: parse persisted global config JSON when present [`src/core/config.ts`]
-      - `loadLocalConfig(...)`: load local config or defaults using global static-check enable defaults [`src/core/config.ts`]
-        - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
-        - `readConfigPayload(...)`: parse persisted local config JSON when present [`src/core/config.ts`]
-      - `mergeConfigScopes(...)`: combine local and global config into the effective runtime config [`src/core/config.ts`]
-        - `mergeStaticCheckConfig(...)`: combine local enable flags with global checker arrays [`src/core/config.ts`]
-        - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-    - `runFilesTokens(...)`: branch `--files-tokens`; count explicit-file token, size, and structure metrics [`src/core/tool-runner.ts`]
-      - `countFilesMetrics(...)`: read 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`]
-      - `formatPackSummary(...)`: render aggregate summary [`src/core/token-counter.ts`]
-    - `runFilesSummarize(...)`: branch `--files-summarize`; emit monolithic explicit-file summary 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`]
-        - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
-          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
-          - `compressSourceDetailed(...)`: strip comments and blank lines into structured line records [`src/core/compress.ts`]
-            - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
-              - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
-                - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
-            - `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`]
-    - `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`]
-        - `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`]
-            - `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`]
-          - `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`]
-        - `constructMatches(...)`: apply tag and regex filter [`src/core/find-constructs.ts`]
-        - `extractFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/find-constructs.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`]
-        - `formatConstruct(...)`: render one construct extract [`src/core/find-constructs.ts`]
-          - `extractConstructDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/find-constructs.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`]
-          - `formatDoxygenFieldsAsMarkdown(...)`: render Doxygen fields as markdown bullets [`src/core/doxygen-parser.ts`]
-          - `stripConstructComments(...)`: compress construct code while preserving strings [`src/core/find-constructs.ts`]
-            - `compressSource(...)`: strip comments and blank lines [`src/core/compress.ts`]
-              - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
-                - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
-                  - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
-              - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
-              - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
-              - `formatResult(...)`: render compressed output [`src/core/compress.ts`]
-        - `formatAvailableTags(...)`: render supported tag index for failure paths [`src/core/find-constructs.ts`]
-    - `runStaticCheck(...)`: branch `--test-static-check`; invoke static-check test driver [`src/core/static-check.ts`]
-      - `StaticCheckBase.run(...)`: iterate resolved files for debug dummy driver [`src/core/static-check.ts`]
-        - `StaticCheckBase.checkFile(...)`: emit success without external checker [`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`]
-      - `StaticCheckCommand.run(...)`: iterate resolved files for external command path [`src/core/static-check.ts`]
-        - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or `PATH` scan [`src/core/static-check.ts`]
-          - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-            - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
-        - `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 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`]
-          - `StaticCheckBase.checkFile(...)`: emit success without external checker [`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`]
-        - `StaticCheckCommand.run(...)`: execute external command checker [`src/core/static-check.ts`]
-          - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or `PATH` scan [`src/core/static-check.ts`]
-            - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-              - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
-          - `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`]
-    - `runSummarize(...)`: branch `--summarize`; emit monolithic project summary 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`]
-          - `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`]
-      - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
-        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.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`]
-        - `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`]
-      - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
-        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
-      - `compressFiles(...)`: compress each file into markdown blocks [`src/core/compress-files.ts`]
-        - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
-        - `compressFileDetailed(...)`: compress one file into structured lines and rendered text [`src/core/compress.ts`]
-          - `detectLanguage(...)`: map extension to language key [`src/core/compress.ts`]
-          - `compressSourceDetailed(...)`: strip comments and blank lines into structured line records [`src/core/compress.ts`]
-            - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
-              - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
-                - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
-            - `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`]
-    - `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`]
-          - `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`]
-      - `collectSourceFiles(...)`: gather tracked and untracked source files under configured roots [`src/core/tool-runner.ts`]
-        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.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`]
-        - `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`]
-            - `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`]
-          - `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`]
-        - `constructMatches(...)`: apply tag and regex filter [`src/core/find-constructs.ts`]
-        - `extractFileLevelDoxygenFields(...)`: extract file-level Doxygen fields [`src/core/find-constructs.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`]
-        - `formatConstruct(...)`: render one construct extract [`src/core/find-constructs.ts`]
-          - `extractConstructDoxygenFields(...)`: merge direct and near-body Doxygen fields [`src/core/find-constructs.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`]
-          - `formatDoxygenFieldsAsMarkdown(...)`: render Doxygen fields as markdown bullets [`src/core/doxygen-parser.ts`]
-          - `stripConstructComments(...)`: compress construct code while preserving strings [`src/core/find-constructs.ts`]
-            - `compressSource(...)`: strip comments and blank lines [`src/core/compress.ts`]
-              - `getSpecs(...)`: memoize parser specs [`src/core/compress.ts`]
-                - `buildLanguageSpecs(...)`: build multi-language parser specs [`src/core/source-analyzer.ts`]
-                  - `re(...)`: compile regex fragments [`src/core/source-analyzer.ts`]
-              - `isInString(...)`: suppress inline comment stripping inside strings [`src/core/compress.ts`]
-              - `removeInlineComment(...)`: remove single-line comment suffixes [`src/core/compress.ts`]
-              - `formatResult(...)`: render compressed output [`src/core/compress.ts`]
-        - `formatAvailableTags(...)`: render supported tag index for failure paths [`src/core/find-constructs.ts`]
-    - `runTokens(...)`: branch `--tokens`; count canonical docs token usage [`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`]
-      - `runFilesTokens(...)`: count explicit-file token, size, and structure metrics [`src/core/tool-runner.ts`]
-        - `countFilesMetrics(...)`: read 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`]
-        - `formatPackSummary(...)`: render aggregate summary [`src/core/token-counter.ts`]
-    - `runProjectStaticCheck(...)`: branch `--static-check`; run configured checkers for source and test roots [`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`]
-      - `collectSourceFiles(...)`: gather tracked and untracked source and test files [`src/core/tool-runner.ts`]
-        - `makeRelativeIfContainsProject(...)`: normalize configured root tokens [`src/core/utils.ts`]
-      - `runFilesStaticCheck(...)`: run 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`]
-        - `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`]
-            - `StaticCheckBase.checkFile(...)`: emit success without external checker [`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`]
-          - `StaticCheckCommand.run(...)`: execute external command checker [`src/core/static-check.ts`]
-            - `resolveCheckerExecutable(...)`: resolve executable via bundled `node_modules/.bin` or `PATH` scan [`src/core/static-check.ts`]
-              - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-                - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
-            - `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`]
-    - `writeResult(...)`: emit selected runner result [`src/cli.ts`]
-      - `writeStdout(...)`: write stdout payload [`src/cli.ts`]
-      - `writeStderr(...)`: write stderr payload [`src/cli.ts`]
-- External Boundaries:
-  - Node process APIs for argv, cwd, environment, stdout, stderr, and exit code.
-  - Filesystem access for config, docs discovery, source reads, and bundled resources.
-  - Git, bash, and arbitrary configured checker subprocesses via child-process execution.
-
-### `PROC:req-debug`
-- Entrypoints:
-  - `main(...)`: bash wrapper runtime root [`scripts/pi-usereq-debug.sh`]
-- Lifecycle/trigger:
-  - Start trigger: Bash executes `scripts/pi-usereq-debug.sh` as a one-shot wrapper.
-  - Stop trigger: returns delegated harness exit status or local validation failure.
-  - Looping model: single-pass subcommand dispatch with no persistent loop.
-  - Threads: no explicit threads detected.
-  - Startup invariant: script body resolves `TSX_BIN` through `resolve_tsx_binary(...)` before invoking `main(...)`.
-- Internal Call-Trace Tree:
-  - `main(...)`: parse wrapper subcommand, normalize prompt and tool convenience aliases, rewrite tool `--args` when requested, and delegate to the TypeScript harness [`scripts/pi-usereq-debug.sh`]
-    - `print_usage(...)`: render wrapper usage text for help and empty invocation [`scripts/pi-usereq-debug.sh`]
-    - `require_value(...)`: validate required command, prompt, tool, or raw operands [`scripts/pi-usereq-debug.sh`]
-    - `contains_exact_option(...)`: detect forwarded `--args` or `--params` tokens for command and prompt replay [`scripts/pi-usereq-debug.sh`]
-    - `contains_long_option(...)`: detect explicit long options before inferring positional payloads [`scripts/pi-usereq-debug.sh`]
-    - `normalize_prompt_name(...)`: map bare prompt aliases to registered `req-*` command names [`scripts/pi-usereq-debug.sh`]
-    - `forward_tool_subcommand(...)`: normalize wrapper tool forwarding and rewrite `--args` into `--params` JSON when present [`scripts/pi-usereq-debug.sh`]
-      - `build_tool_params_json(...)`: spawn the tool-argument converter and capture serialized JSON params [`scripts/pi-usereq-debug.sh`]
-    - `run_debug_extension(...)`: enter repository root, apply default `--cwd` and `--extension`, and spawn the TypeScript harness [`scripts/pi-usereq-debug.sh`]
-- External Boundaries:
-  - Bash shell argument expansion, stdout, and stderr handling.
-  - `git rev-parse`, `ln -s`, and resolved `tsx` executable lookup triggered by `resolve_tsx_binary(...)` during startup.
-  - Child-process execution of `scripts/tool-args-to-params.ts` and `scripts/debug-extension.ts`.
-
-### `PROC:tool-args-to-params`
-- Entrypoints:
-  - `main(...)`: tool-argument conversion runtime root [`scripts/tool-args-to-params.ts`]
-- Lifecycle/trigger:
-  - Start trigger: `PROC:req-debug` executes `scripts/tool-args-to-params.ts` for tool subcommands that pass wrapper `--args`.
-  - Stop trigger: returns numeric exit code after one conversion path or caught `ReqError`.
-  - Looping model: single-pass argument parse followed by one conversion decision.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `main(...)`: parse argv, convert wrapper tool args text into JSON params, and serialize the result [`scripts/tool-args-to-params.ts`]
-    - `parseCliArgs(...)`: map converter CLI options into one normalized request [`scripts/tool-args-to-params.ts`]
-    - `buildToolParamsFromArgsText(...)`: tokenize wrapper args text and map it to one tool-parameter object [`scripts/tool-args-to-params.ts`]
-      - `shellSplit(...)`: split shell-style text into ordered tokens [`src/core/utils.ts`]
-      - `takeBooleanFlag(...)`: remove supported boolean flags while preserving positional order [`scripts/tool-args-to-params.ts`]
-    - `writeStdout(...)`: emit serialized JSON params or usage text [`scripts/tool-args-to-params.ts`]
-    - `writeStderr(...)`: emit conversion diagnostics on error paths [`scripts/tool-args-to-params.ts`]
-- External Boundaries:
-  - Node process APIs for argv, stdout, stderr, and exit code.
-
-### `PROC:debug-ext`
-- Entrypoints:
-  - `main(...)`: debug-harness runtime root [`scripts/debug-extension.ts`]
-- Lifecycle/trigger:
-  - Start trigger: Node executes `scripts/debug-extension.ts` as a one-shot command.
-  - Stop trigger: returns numeric exit code after one harness subcommand or caught `ReqError`.
-  - Looping model: single-pass argument parse followed by single branch dispatch.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `main(...)`: parse argv, dispatch inspect/session-start/command/tool/sdk-smoke, and serialize the selected report [`scripts/debug-extension.ts`]
-    - `parseArgs(...)`: map argv tokens into harness subcommand options [`scripts/debug-extension.ts`]
-    - `parseJsonObject(...)`: parse JSON object options for tool and session replay [`scripts/debug-extension.ts`]
-    - `inspectExtension(...)`: load the extension as a black box, capture registrations, and render the manual [`scripts/lib/extension-debug-harness.ts`]
-      - `registerExtensionOffline(...)`: resolve paths, load the extension default export, and invoke registration under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
-        - `resolveHarnessPaths(...)`: validate working-directory and extension-entry paths [`scripts/lib/extension-debug-harness.ts`]
-        - `loadExtensionFactory(...)`: dynamically import the extension default export [`scripts/lib/extension-debug-harness.ts`]
-        - `withProcessCwd(...)`: execute registration under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
-          - `piUsereqExtension(...)`: register extension commands, tools, shortcuts, and lifecycle hooks [`src/index.ts`]
-            - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources before registration [`src/core/resources.ts`]
-            - `registerReqResetCommand(...)`: register the specialized non-agentic `req-reset` command [`src/index.ts`]
-            - `registerReqReferencesCommand(...)`: register the specialized non-agentic `req-references` command with non-`idle` rejection that transitions workflow state to `error` [`src/index.ts`]
-            - `registerPromptCommands(...)`: register bundled prompt-backed `req-*` commands with non-`idle` rejection that transitions workflow state to `error` [`src/index.ts`]
-            - `registerAgentTools(...)`: register structured agent tools [`src/index.ts`]
-            - `registerConfigCommands(...)`: register configuration commands [`src/index.ts`]
-            - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut and cycle only the active runtime sound level without persisting boot config [`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`]
-                - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-                - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-              - `getPiUsereqRuntimeSoundLevel(...)`: read the active runtime sound level before shortcut cycling [`src/core/extension-status.ts`]
-              - `cyclePiNotifySoundLevel(...)`: compute the next active runtime sound level [`src/core/pi-notify.ts`]
-              - `setPiUsereqRuntimeSoundLevel(...)`: store the cycled runtime sound level and refresh the footer [`src/core/extension-status.ts`]
-                - `renderPiUsereqStatus(...)`: refresh the single-line footer after shortcut-driven runtime sound changes [`src/core/extension-status.ts`]
-      - `buildDebugManual(...)`: render mode and per-command/per-tool examples, including JSON-oriented token-tool examples [`scripts/lib/extension-debug-harness.ts`]
-    - `replaySessionStart(...)`: replay recorded `session_start` handlers and capture resulting UI state [`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`]
-      - `withProcessCwd(...)`: execute `session_start` under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
-        - `loadProjectConfig(...)`: session-start configuration load [`src/index.ts`]
-          - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
-          - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
-          - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-          - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-        - `handleExtensionStatusEvent(...)`: process the replayed `session_start` payload through shared status telemetry helpers [`src/index.ts`]
-          - `loadProjectConfig(...)`: session-start configuration load [`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`]
-            - `isInsideGitRepo(...)`: probe git repository membership [`src/core/tool-runner.ts`]
-            - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
-          - `applyConfiguredPiUsereqTools(...)`: enforce configured active tools against the offline runtime inventory [`src/index.ts`]
-            - `getConfiguredEnabledPiUsereqTools(...)`: canonicalize configured enabled tools [`src/index.ts`]
-              - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
-            - `RecordingExtensionAPI.getAllTools(...)`: expose supported builtin plus extension tool inventory [`scripts/lib/recording-extension-api.ts`]
-              - `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 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`]
-          - `checkDefaultCheckersAvailability(...)`: enumerate missing enabled static-check executables and emit one warning notification without aborting [`src/core/static-check.ts`]
-          - `updateExtensionStatus(...)`: refresh stored context usage, reset or restore elapsed timers, load the active runtime sound level from persisted config during `session_start`, 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(...)`: refresh live context usage and render the extension/status/branch/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`]
-              - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-                - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-                  - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-                    - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-                    - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-              - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-                - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-                  - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 with the non-error status value token below 90 percent and `error` at or above 90 percent [`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`]
-          - `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`]
-            - `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`]
-    - `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`]
-      - `withProcessCwd(...)`: execute the named command under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
-        - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources when invoking bundled prompt-backed `req-*` handlers [`src/core/resources.ts`]
-        - `getProjectBase(...)`: resolve command project base [`src/index.ts`]
-        - `loadProjectConfig(...)`: load command runtime config [`src/index.ts`]
-        - `resolveReqResetPromptRequest(...)`: resolve the recoverable prompt execution plan for `req-reset` from in-memory or persisted prompt state [`src/index.ts`]
-        - `prepareReqResetCommandExecution(...)`: derive base-path recovery and generated cleanup facts for `req-reset` [`src/core/req-reset-command.ts`]
-          - `buildReqResetWorktreeNamePattern(...)`: derive the generated worktree-name matcher from the configured prefix plus repository basename [`src/core/req-reset-command.ts`]
-        - `executeReqResetCommandExecution(...)`: preserve transcript, restore `base-path`, and force-remove matching worktrees plus branches for `req-reset` [`src/core/req-reset-command.ts`]
-          - `preservePromptCommandExecutionTranscript(...)`: copy execution-session records into the original session file when recovery plan data exists [`src/core/prompt-command-runtime.ts`]
-          - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path before cleanup [`src/core/prompt-command-runtime.ts`]
-          - `listReqResetMatchingWorktreeRoots(...)`: enumerate registered and sibling generated worktrees targeted for deletion [`src/core/req-reset-command.ts`]
-            - `listReqResetRegisteredWorktreeRoots(...)`: enumerate registered git worktree roots [`src/core/req-reset-command.ts`]
-            - `listReqResetSiblingWorktreeRoots(...)`: enumerate sibling generated worktree directories [`src/core/req-reset-command.ts`]
-          - `deletePromptWorktree(...)`: force-remove one matching worktree plus its linked branch [`src/core/prompt-command-runtime.ts`]
-          - `listReqResetMatchingBranchNames(...)`: enumerate remaining matching branches after worktree deletion [`src/core/req-reset-command.ts`]
-          - `runCapture(...)`: run `git branch -D` for remaining matching branches [`src/core/req-reset-command.ts`]
-        - `rejectNonIdleReqCommand(...)`: abort non-`idle` replayed `req-references` or bundled prompt commands by transitioning workflow state to `error` [`src/index.ts`]
-        - `prepareReqReferencesCommandExecution(...)`: validate git state and resolve direct-write references execution facts for `req-references` [`src/core/req-references-command.ts`]
-          - `validatePromptGitState(...)`: validate clean runtime repository state while ignoring extension-owned debug-log artifacts [`src/core/prompt-command-runtime.ts`]
-        - `executeReqReferencesCommandExecution(...)`: regenerate `REFERENCES.md`, stage only the target file, create the fixed commit, and verify clean repository state for `req-references` [`src/core/req-references-command.ts`]
-          - `runReferences(...)`: generate summarize-equivalent markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
-          - `getGitAddTargetPath(...)`: resolve the staged path relative to the git root [`src/core/req-references-command.ts`]
-          - `runCapture(...)`: run git add, commit, and status subprocesses [`src/core/req-references-command.ts`]
-          - `listResidualGitStatusLines(...)`: confirm no residual git-status rows remain after commit [`src/core/req-references-command.ts`]
-            - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
-        - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion, conditional pi.dev governance guidance, and `%%CONTEXT_FILES%%` context-file injection [`src/core/prompts.ts`]
-          - `buildContextFilesBlock(...)`: build the markdown block injected at `%%CONTEXT_FILES%%` from enabled context files in documented order with pre-substituted `%%DOC_PATH%%` file references and four-backtick fences [`src/core/prompts.ts`]
-        - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name, user request arguments, and active configuration fields, rendering `none` for empty context-file, static-check-language, and enabled-tool lists [`src/core/prompts.ts`]
-        - `deliverPromptCommand(...)`: dispatch the rendered prompt as a hidden `display:false` custom message plus a `display:true` summary into the current recorded session, awaiting and suppressing summary delivery failures before the hidden prompt turn, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable [`src/index.ts`]
-          - External boundaries: `RecordingExtensionAPI.sendMessage(...)` or fallback `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload plus summary.
-        - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
-          - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including the `Context Files` injection toggle row, effective worktree locking, plus display-only local and global config-path rows [`src/index.ts`]
-            - `formatLocalConfigPathForMenu(...)`: format the current local config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
-            - `formatGlobalConfigPathForMenu(...)`: format the current global 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, keeping inline toggle rows open while rebuilding dependent rows in place [`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, apply optional dim tones, disable non-selectable actions, and expose inline value cycles [`src/core/settings-menu.ts`]
-            - `setSettingsListSelectedIndex(...)`: restore the focused row during in-place menu rebuilds [`src/core/settings-menu.ts`]
-            - `getSettingsListSelectedIndex(...)`: expose the focused row for the offline bridge after inline toggle handling [`src/core/settings-menu.ts`]
-          - `saveProjectConfig(...)`: persist split local/global menu updates [`src/index.ts`]
-          - `setPiUsereqStatusConfig(...)`: cache the saved config for footer rendering [`src/core/extension-status.ts`]
-          - `renderPiUsereqStatus(...)`: refresh live context usage and render the extension/status/branch/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`]
-            - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-              - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-                - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-                  - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-                  - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, consolidated elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-              - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-                - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 icon-based context gauge with the non-error status value token below 90 percent and `error` at or above 90 percent [`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`]
-          - `configureStaticCheckMenu(...)`: interactive editor that adds and removes global Command entries while toggling local per-language enable flags [`src/index.ts`]
-          - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor whose per-tool toggle submenu keeps focus while persisting enablement in global config [`src/index.ts`]
-          - `configurePiNotifyMenu(...)`: interactive notify, sound, and Pushover editor that persists every subtree mutation in global config [`src/index.ts`]
-            - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers, including boot-sound rows sourced from persisted global config [`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 guidance text plus the shared event-submenu launcher [`src/index.ts`]
-            - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor that keeps focus while toggling `on|off` rows for one notification transport [`src/index.ts`]
-              - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus the submenu reset action [`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`]
-          - `configureContextFilesMenu(...)`: interactive `Context Files` editor with inline `on|off` toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` plus subtree reset to all-enabled defaults [`src/index.ts`]
-            - `buildContextFilesMenuChoices(...)`: serialize the three context-file toggle rows plus the subtree reset terminal row [`src/index.ts`]
-            - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for inline context-file toggles and reset confirmation [`src/core/settings-menu.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`]
-      - `withProcessCwd(...)`: execute the named tool under the requested cwd [`scripts/lib/extension-debug-harness.ts`]
-        - `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`]
-        - `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`]
-          - `runFilesSummarize(...)`: execute the monolithic explicit-file summary 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`]
-          - `runSummarize(...)`: execute the monolithic project summary 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`]
-        - `executeStatusTool(...)`: execute one CLI-style runner and wrap one status-only content block plus minimal execution details [`src/index.ts`]
-          - `runReferences(...)`: generate summarize-equivalent references markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
-            - `runSummarize(...)`: execute the project summary markdown runner reused as the reference-file source [`src/core/tool-runner.ts`]
-          - `buildMonolithicToolExecuteResult(...)`: wrap status 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`]
-        - `resolveHarnessPaths(...)`: validate working-directory and extension-entry paths [`scripts/lib/extension-debug-harness.ts`]
-        - `extractSdkApi(...)`: locate the runtime inventory surface [`scripts/lib/sdk-smoke.ts`]
-        - `normalizeCommandRecord(...)`: normalize SDK command metadata [`scripts/lib/sdk-smoke.ts`]
-          - `normalizeSourceInfo(...)`: normalize command provenance fields [`scripts/lib/sdk-smoke.ts`]
-            - `normalizePathValue(...)`: normalize source paths relative to project root [`scripts/lib/sdk-smoke.ts`]
-        - `normalizeToolRecord(...)`: normalize SDK tool metadata [`scripts/lib/sdk-smoke.ts`]
-          - `normalizeSourceInfo(...)`: normalize tool provenance fields [`scripts/lib/sdk-smoke.ts`]
-            - `normalizePathValue(...)`: normalize source paths relative to project root [`scripts/lib/sdk-smoke.ts`]
-      - `buildParityReport(...)`: compare offline and SDK inventories [`scripts/lib/sdk-smoke.ts`]
-        - `compareCommandInventories(...)`: detect command-name, description, and provenance mismatches [`scripts/lib/sdk-smoke.ts`]
-        - `compareToolInventories(...)`: detect tool-name, description, schema-presence, and provenance mismatches [`scripts/lib/sdk-smoke.ts`]
-        - `compareActiveTools(...)`: detect active-tool mismatches after `session_start` [`scripts/lib/sdk-smoke.ts`]
-    - `formatReport(...)`: serialize the selected report as JSON or markdown [`scripts/debug-extension.ts`]
-      - `formatJson(...)`: serialize a machine-readable payload [`scripts/debug-extension.ts`]
-      - `formatInspectReport(...)`: render offline inspection markdown [`scripts/debug-extension.ts`]
-      - `formatSessionStartReport(...)`: render `session_start` replay markdown [`scripts/debug-extension.ts`]
-      - `formatCommandReplayReport(...)`: render command replay markdown [`scripts/debug-extension.ts`]
-      - `formatToolReplayReport(...)`: render tool replay markdown [`scripts/debug-extension.ts`]
-      - `formatSdkSmokeReport(...)`: render parity markdown [`scripts/debug-extension.ts`]
-    - `writeStdout(...)`: emit the final report payload [`scripts/debug-extension.ts`]
-    - `writeStderr(...)`: emit CLI failure diagnostics on error paths [`scripts/debug-extension.ts`]
-- External Boundaries:
-  - Dynamic module loading for the target extension entry and optional `@mariozechner/pi-coding-agent` SDK package.
-  - Filesystem validation for requested cwd and extension paths.
-  - Any filesystem, git, or subprocess side effects triggered indirectly by the registered extension handlers during replay.
-
-### `PROC:pi-host`
-- Entrypoints:
-  - `piUsereqExtension(...)`: extension activation root [`src/index.ts`]
-  - `configurePiUsereq(...)`: named callback body for interactive configuration [`src/index.ts`]
-- Lifecycle/trigger:
-  - Start trigger: pi extension host imports the default export from `src/index.ts` and invokes `piUsereqExtension(...)`.
-  - Runtime trigger: registered commands, registered tools, and lifecycle-hook callbacks are invoked by external pi runtime.
-  - Stop trigger: host lifecycle is external; each callback returns control after completion.
-  - Looping model: event-driven callbacks; menu handlers loop until user selects exit or back.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `piUsereqExtension(...)`: initialize resources, register commands, tools, shortcuts, and lifecycle-hook telemetry wrappers [`src/index.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`]
-    - `registerReqResetCommand(...)`: register the specialized non-agentic `req-reset` command that accepts any workflow state, restores `base-path`, force-removes matching generated worktrees plus branches, clears recoverable prompt state when restoration succeeds, and returns to `idle` without worktree creation or LLM initialization [`src/index.ts`]
-      - `resolveReqResetPromptRequest(...)`: resolve the recoverable prompt execution plan from in-memory or persisted prompt state [`src/index.ts`]
-      - `resolveLiveBootstrapCwd(...)`: recover the live command cwd while preserving a worktree-backed session when it still exists [`src/index.ts`]
-      - `syncContextCwdMirror(...)`: best-effort realign the command-context `cwd` mirror to the recovered live cwd before reset execution [`src/index.ts`]
-      - `bootstrapRuntimePathState(...)`: refresh static runtime path facts from the recovered `base-path` before reset execution [`src/core/path-context.ts`]
-        - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the recovered `base-path` [`src/core/runtime-project-paths.ts`]
-      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for reset execution [`src/index.ts`]
-        - `getProjectBase(...)`: resolve project base from the recovered runtime base path [`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`]
-      - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
-      - `setPiUsereqWorkflowState(...)`: update workflow state directly for running, idle, or error during `req-reset` execution [`src/core/extension-status.ts`]
-        - `renderPiUsereqStatus(...)`: refresh live context usage and render the extension/status/branch/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`]
-          - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-            - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-              - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-                - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-                - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-            - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-              - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 with the non-error status value token below 90 percent and `error` at or above 90 percent [`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`]
-      - `prepareReqResetCommandExecution(...)`: derive the generated cleanup matcher, sibling parent path, and optional recovery plan for `req-reset` [`src/core/req-reset-command.ts`]
-        - `buildReqResetWorktreeNamePattern(...)`: derive the generated worktree-name matcher from the configured prefix plus repository basename [`src/core/req-reset-command.ts`]
-      - `executeReqResetCommandExecution(...)`: preserve transcript, restore `base-path`, and force-remove matching worktrees plus branches [`src/core/req-reset-command.ts`]
-        - `preservePromptCommandExecutionTranscript(...)`: copy execution-session records into the original session file when recovery plan data exists [`src/core/prompt-command-runtime.ts`]
-        - `restorePromptCommandExecution(...)`: switch back to the original session-backed base path before cleanup [`src/core/prompt-command-runtime.ts`]
-        - `listReqResetMatchingWorktreeRoots(...)`: enumerate registered and sibling generated worktrees targeted for deletion [`src/core/req-reset-command.ts`]
-          - `listReqResetRegisteredWorktreeRoots(...)`: enumerate registered git worktree roots [`src/core/req-reset-command.ts`]
-          - `listReqResetSiblingWorktreeRoots(...)`: enumerate sibling generated worktree directories [`src/core/req-reset-command.ts`]
-        - `deletePromptWorktree(...)`: force-remove one matching worktree plus its linked branch [`src/core/prompt-command-runtime.ts`]
-        - `listReqResetMatchingBranchNames(...)`: enumerate remaining matching branches after worktree deletion [`src/core/req-reset-command.ts`]
-        - `runCapture(...)`: run `git branch -D` for remaining matching branches [`src/core/req-reset-command.ts`]
-      - `clearPersistedPromptCommandRuntimeState(...)`: clear persisted prompt workflow and reusable session context after successful recovery [`src/core/prompt-command-state.ts`]
-      - `notifyContextSafely(...)`: emit stale-safe success or error notifications after reset execution [`src/index.ts`]
-    - `registerReqReferencesCommand(...)`: register the specialized non-agentic `req-references` command that rejects non-`idle` invocation by transitioning workflow state to `error`, otherwise validates git state, regenerates `REFERENCES.md`, stages only that file, creates the fixed commit, verifies clean repository state, and returns to `idle` without worktree routing [`src/index.ts`]
-      - `rejectNonIdleReqCommand(...)`: abort non-`idle` `req-references` re-entry by transitioning workflow state to `error` [`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 direct references execution [`src/index.ts`]
-      - `bootstrapRuntimePathState(...)`: refresh static and dynamic runtime path facts for direct references execution [`src/core/path-context.ts`]
-        - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the recovered live cwd [`src/core/runtime-project-paths.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`]
-      - `setPiUsereqStatusConfig(...)`: cache docs/tests/src and pi-notify values for status rendering [`src/core/extension-status.ts`]
-      - `setPiUsereqWorkflowState(...)`: update workflow state directly for checking, running, idle, or error during `req-references` execution [`src/core/extension-status.ts`]
-        - `renderPiUsereqStatus(...)`: refresh live context usage and render the extension/status/branch/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`]
-          - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-            - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-              - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-                - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-                - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-            - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-              - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 with the non-error status value token below 90 percent and `error` at or above 90 percent [`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`]
-      - `prepareReqReferencesCommandExecution(...)`: validate git state and resolve the configured references target before direct execution [`src/core/req-references-command.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 slash-command git-preflight failures [`src/core/prompt-command-runtime.ts`]
-      - `executeReqReferencesCommandExecution(...)`: regenerate `REFERENCES.md`, stage only the target file, create the fixed commit, and verify clean repository state [`src/core/req-references-command.ts`]
-        - `runReferences(...)`: generate summarize-equivalent references markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
-          - `runSummarize(...)`: execute the project summary markdown runner reused as the reference-file source [`src/core/tool-runner.ts`]
-        - `getGitAddTargetPath(...)`: resolve the staged path relative to the git root [`src/core/req-references-command.ts`]
-        - `runCapture(...)`: run git add, commit, and status subprocesses [`src/core/req-references-command.ts`]
-        - `listResidualGitStatusLines(...)`: confirm no residual git-status rows remain after commit [`src/core/req-references-command.ts`]
-          - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
-    - `registerPromptCommands(...)`: register one bundled prompt-backed command per prompt name using runtime prompt level-one heading descriptions, reject non-`idle` re-entry by transitioning workflow state to `error`, recover a live bootstrap cwd when stale command contexts still point at deleted worktrees, otherwise 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`]
-      - `rejectNonIdleReqCommand(...)`: abort non-`idle` bundled prompt re-entry by transitioning workflow state to `error` [`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(...)`: refresh live context usage and render the extension/status/branch/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`]
-          - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-            - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-              - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-                - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-                - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-          - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-            - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-              - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 with the non-error status value token below 90 percent and `error` at or above 90 percent [`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 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`]
-      - `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, conditional pi.dev governance guidance, and `%%CONTEXT_FILES%%` context-file injection [`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`]
-        - `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`]
-        - `buildContextFilesBlock(...)`: build the markdown block injected at `%%CONTEXT_FILES%%` from enabled context files in documented order with pre-substituted `%%DOC_PATH%%` file references and four-backtick fences [`src/core/prompts.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`]
-      - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name without the `req-` prefix in uppercase, user request arguments, and active configuration fields, rendering `none` for empty context-file, static-check-language, and enabled-tool lists [`src/core/prompts.ts`]
-      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt as a hidden `display:false` custom message with `triggerTurn:true` plus a `display:true` command invocation summary into the current active session after execution-session activation is verified, preferring replacement-session `sendMessage(...)` when available, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable, awaiting and suppressing the non-critical summary delivery before the authoritative hidden prompt turn so a rejecting summary never surfaces as an unhandled rejection that could terminate the process before prompt-end closure runs the worktree merge, 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 `sendMessage(...)` [`src/core/extension-status.ts`]
-        - External boundaries: replacement-session `sendMessage(...)` or `pi.sendMessage(...)` delivers the hidden rendered prompt payload plus the displayed summary into the active `AgentSession`; fallback replacement-session `sendUserMessage(...)` or `pi.sendUserMessage(...)` delivers the rendered prompt payload when `sendMessage(...)` is unavailable.
-      - `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`]
-    - `getProcessCwdSafe(...)`: resolve a fallback-safe activation cwd before optional debug command registration [`src/index.ts`]
-    - `shouldRegisterDebugToolCommands(...)`: load local config and decide whether debug tool wrapper commands should register during activation [`src/index.ts`]
-      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for activation-time debug command gating [`src/index.ts`]
-        - `getProjectBase(...)`: resolve project base from the activation 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`]
-    - `registerDebugToolCommands(...)`: register config-gated debug slash-command wrappers for `compress`, `references`, `static-check`, `summarize`, and `tokens` [`src/index.ts`]
-    - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families, the status-only references writer, 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`]
-      - `getProjectBase(...)`: resolve project base from process cwd [`src/index.ts`]
-      - `loadProjectConfig(...)`: load config and normalize persisted directory paths for project-scoped tool executes [`src/index.ts`]
-        - `getProjectBase(...)`: resolve project base from process 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`]
-      - `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`]
-        - `runFilesSummarize(...)`: execute the monolithic explicit-file summary 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`]
-        - `runSummarize(...)`: execute the monolithic project summary 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`]
-      - `executeStatusTool(...)`: execute one CLI-style runner and wrap one status-only content block plus minimal execution details [`src/index.ts`]
-        - `runReferences(...)`: generate summarize-equivalent references markdown, overwrite `REFERENCES.md`, and return the status-only success payload [`src/core/tool-runner.ts`]
-          - `runSummarize(...)`: execute the project summary markdown runner reused as the reference-file source [`src/core/tool-runner.ts`]
-        - `buildMonolithicToolExecuteResult(...)`: wrap status 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`]
-        - `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`]
-    - `registerPiNotifyShortcut(...)`: register the configured sound-level shortcut and cycle only the active runtime sound level without persisting boot config [`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`]
-      - `getPiUsereqRuntimeSoundLevel(...)`: read the active runtime sound level before shortcut cycling [`src/core/extension-status.ts`]
-      - `cyclePiNotifySoundLevel(...)`: compute the next active runtime sound level [`src/core/pi-notify.ts`]
-      - `setPiUsereqRuntimeSoundLevel(...)`: store the cycled runtime sound level and refresh the footer [`src/core/extension-status.ts`]
-        - `renderPiUsereqStatus(...)`: refresh the single-line footer after shortcut-driven runtime sound changes [`src/core/extension-status.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 stash-assisted merge and worktree deletion even after a busy-command rejection moved workflow state to `error`, warning-only closure notifications when restored `base-path` changes are reapplied, stale-safe closure notifications, and matched-failure worktree-execution-session retention plus closure-error notification and workflow `error` parking without resuming `base-path` so the failure stays visible, leaving `base-path` restoration plus worktree and branch cleanup to `req-reset` [`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`]
-        - `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 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`]
-        - `checkDefaultCheckersAvailability(...)`: enumerate missing enabled static-check executables and emit one warning notification without aborting [`src/core/static-check.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`, load the active runtime sound level from persisted config 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(...)`: refresh live context usage and render the extension/status/branch/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`]
-            - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-              - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-                - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-                  - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-                  - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-            - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-              - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-                - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 with the non-error status value token below 90 percent and `error` at or above 90 percent [`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`]
-        - `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`]
-          - `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`]
-        - `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(...)`: refresh live context usage and render the extension/status/branch/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, synchronize the successful execution transcript into the restored base session, restore the original session-backed base path through the persisted replacement-session context when lifecycle hooks omit `switchSession()`, execute the matched successful stash-assisted `base-path` merge sequence, delete the worktree and branch after merge success, and carry a warning-only closure result when restored `base-path` changes are reapplied [`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`]
-          - `preservePromptCommandExecutionTranscript(...)`: append or materialize the restored base-session transcript from the execution-session JSONL before the base-path switch [`src/core/prompt-command-runtime.ts`]
-            - `readPromptSessionJsonLines(...)`: parse execution-session JSONL records and parse original-session JSONL records when a persisted base session already exists [`src/core/prompt-command-runtime.ts`]
-            - `readPromptSessionFileCwd(...)`: verify the restored session header cwd equals `base-path` after transcript synchronization [`src/core/prompt-command-runtime.ts`]
-            - `readPromptSessionJsonLines(...)`: re-read the restored base session and verify copied execution entry identifiers [`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`]
-          - `finalizePromptCommandMerge(...)`: inspect tracked `base-path` changes, run `git stash` plus `git stash pop` around the existing `--ff-only` merge when tracked changes exist, emit a warning-only merge result after reapplying local changes, and append selected merge debug entries [`src/core/prompt-command-runtime.ts`]
-            - `listPromptTrackedBasePathChanges(...)`: parse tracked staged or unstaged `git status --porcelain` rows and ignore untracked or ignored rows before stash-assisted merge selection [`src/core/prompt-command-runtime.ts`]
-          - `deletePromptWorktree(...)`: delete the merged worktree and branch after successful stash-assisted fast-forward merge [`src/core/prompt-command-runtime.ts`]
-        - `restorePromptCommandExecution(...)`: reset runtime path state for non-worktree prompt-end events; worktree-backed interrupted, failed, aborted, or incomplete runs skip restoration, retain the worktree execution session, park workflow state in `error`, and leave `base-path` restoration plus worktree and branch cleanup to `req-reset` [`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, `Context Files` injection toggles, `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`]
-        - `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`]
-    - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
-    - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including the `Context Files` injection toggle row, effective worktree locking, notification and debug summaries, display-only local and global config-path rows, and reset-only terminal rows [`src/index.ts`]
-      - `formatDebugMenuSummary(...)`: summarize global debug mode plus selected tool and prompt counts [`src/index.ts`]
-      - `formatLocalConfigPathForMenu(...)`: format the current local config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
-      - `formatGlobalConfigPathForMenu(...)`: format the current global 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, keeping inline toggle rows open while rebuilding dependent rows in place [`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, apply optional dim tones, disable non-selectable actions, and expose inline value cycles [`src/core/settings-menu.ts`]
-      - `setSettingsListSelectedIndex(...)`: restore the focused row during in-place menu rebuilds [`src/core/settings-menu.ts`]
-      - `getSettingsListSelectedIndex(...)`: expose the focused row for the offline bridge after inline toggle handling [`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 split local/global config JSON [`src/core/config.ts`]
-        - `saveLocalConfig(...)`: write the local config file [`src/core/config.ts`]
-          - `getProjectConfigPath(...)`: resolve local config file path [`src/core/config.ts`]
-        - `saveGlobalConfig(...)`: write the global config file [`src/core/config.ts`]
-          - `getGlobalConfigPath(...)`: resolve global config file path [`src/core/config.ts`]
-    - `writePersistedLocalConfigToEditor(...)`: read the already-persisted local 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 local config path [`src/core/config.ts`]
-    - `writePersistedGlobalConfigToEditor(...)`: read the already-persisted global config file and write its exact text into the editor [`src/index.ts`]
-      - `getGlobalConfigPath(...)`: resolve the persisted global 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(...)`: refresh live context usage and render the extension/status/branch/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`]
-      - `resolveStatusBranchValue(...)`: resolve the active git branch from the current context cwd before footer rendering [`src/core/extension-status.ts`]
-        - `resolveRuntimeGitBranchName(...)`: resolve the active git branch for the current execution path [`src/core/runtime-project-paths.ts`]
-          - `resolveRuntimeGitPath(...)`: resolve the runtime git root for the active execution path [`src/core/runtime-project-paths.ts`]
-            - `isInsideGitRepo(...)`: test git work-tree membership [`src/core/runtime-project-paths.ts`]
-            - `resolveGitRoot(...)`: resolve repository root [`src/core/runtime-project-paths.ts`]
-      - `buildPiUsereqStatusText(...)`: compose the single-line footer payload with runtime extension identity, workflow state, branch, context gauge, elapsed semantics, and the active runtime sound status field [`src/core/extension-status.ts`]
-        - `formatExtensionIdentityStatusField(...)`: render the runtime extension name and version prefix using standard non-error status tokens [`src/core/extension-status.ts`]
-          - `getInstallationPackageMetadata(...)`: resolve cached runtime package name and version [`src/core/path-context.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 with the non-error status value token below 90 percent and `error` at or above 90 percent [`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`]
-    - `configureStaticCheckMenu(...)`: interactive editor that adds, inspects, confirms-before-removes, and resets global Command entries while toggling local per-language enable flags [`src/index.ts`]
-      - `getStaticCheckLanguageConfigForMenu(...)`: resolve a menu-facing per-language static-check object [`src/index.ts`]
-      - `countConfiguredStaticCheckLanguages(...)`: count languages that retain global checker entries [`src/index.ts`]
-      - `countEnabledStaticCheckLanguages(...)`: count languages whose local enable flag is on [`src/index.ts`]
-      - `formatStaticCheckLanguagesSummary(...)`: summarize enabled languages and configured global checker languages [`src/index.ts`]
-      - `buildStaticCheckMenuChoices(...)`: serialize guided add/view/remove/reset actions plus direct per-language local 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`]
-        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-      - `buildSupportedStaticCheckLanguageChoices(...)`: serialize supported languages with enablement, configured counts, and the value-less terminal reset row [`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 the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-      - `buildConfiguredStaticCheckLanguageChoices(...)`: serialize configured languages plus the value-less terminal reset row 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 the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-      - `formatStaticCheckCheckerEntry(...)`: format one checker entry as a shell-like command summary for inspection and confirmation menus [`src/index.ts`]
-      - `formatStaticCheckLanguageCheckerSummary(...)`: summarize configured checkers for one language as a delimited command list [`src/index.ts`]
-      - `buildStaticCheckViewChoices(...)`: serialize configured checkers as read-only disabled inspection rows terminated by a `Close` row [`src/index.ts`]
-      - `buildStaticCheckRemovalConfirmationChoices(...)`: serialize targeted checker preview rows plus approve and abort actions for removal confirmation [`src/index.ts`]
-      - `confirmStaticCheckRemoval(...)`: open one explicit removal-confirmation submenu and return the approval result [`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`]
-    - `configurePiUsereqToolsMenu(...)`: interactive active-tool editor whose per-tool toggle submenu keeps focus while persisting enablement in global config [`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 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 in documented menu order [`src/index.ts`]
-      - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows plus the value-less terminal reset action [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-    - `configureDebugMenu(...)`: interactive debug editor with in-place enable or disable toggles, tool-wrapper command registration, workflow filters, reset confirmation, and per-tool plus per-prompt selectors [`src/index.ts`]
-      - `buildDebugMenuChoices(...)`: serialize global debug controls with `Enable debug commands for tools` before `Log file`, workflow-event toggles, canonical tool and prompt toggles, and the value-less terminal reset row [`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`]
-      - `registerDebugToolCommands(...)`: register debug slash-command wrappers including `debug-summarize` immediately when the tool-wrapper row transitions to `enable` [`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 that persists every subtree mutation in global config while keeping runtime sound edits in memory only [`src/index.ts`]
-      - `buildPiNotifyMenuChoices(...)`: serialize command-notify, sound, and Pushover blocks plus shared-event submenu launchers and the value-less terminal reset row, including boot-sound rows sourced from persisted global config [`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 guidance text plus the shared event-submenu launcher [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row [`src/index.ts`]
-      - `configurePiNotifyEventMenu(...)`: interactive completed/interrupted/failed event editor that keeps focus while toggling `on|off` rows for one notification transport [`src/index.ts`]
-        - `buildPiNotifyEventMenuChoices(...)`: serialize shared event rows plus the submenu reset action [`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 (boot value)` selector while preserving the active runtime sound level [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-      - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector with the subtree-local reset action [`src/index.ts`]
-        - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
-      - `resetPiNotifyConfigToDefaults(...)`: restore notification settings to documented defaults [`src/index.ts`]
-    - `configureContextFilesMenu(...)`: interactive `Context Files` editor with inline `on|off` toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` plus subtree reset to all-enabled defaults [`src/index.ts`]
-      - `buildContextFilesMenuChoices(...)`: serialize the three context-file toggle rows plus the subtree reset terminal row [`src/index.ts`]
-      - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for inline context-file toggles and reset confirmation [`src/core/settings-menu.ts`]
-      - `confirmResetChanges(...)`: require explicit approval before applying the Context Files subtree reset [`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 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.
-  - Git and static-check subprocesses reused through the same tool-runner and static-check functions documented under `PROC:main`.
-
-### `PROC:gh-release-check`
-- Entrypoints:
-  - `check-branch(...)`: GitHub Actions release-gate job root [`.github/workflows/release-npm.yml`]
-- Lifecycle/trigger:
-  - Start trigger: GitHub Actions starts the job for pushed tags matched by the workflow tag filter.
-  - Stop trigger: writes the `is_master` job output after `origin/master` containment evaluation.
-  - Looping model: single-pass job with sequential step execution.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `check-branch(...)`: fetch `origin/master`, evaluate tagged-commit containment, and export the downstream gate flag [`.github/workflows/release-npm.yml`]
-    - External boundaries: `actions/checkout@v5`, GitHub Actions runner shell, `git` CLI, `grep`, and `$GITHUB_OUTPUT`.
-- External Boundaries:
-  - GitHub Actions event routing, hosted-runner lifecycle, checkout action, git subprocesses, and runner output channels.
-
-### `PROC:gh-release-build`
-- Entrypoints:
-  - `build-release(...)`: GitHub Actions npm-and-release job root [`.github/workflows/release-npm.yml`]
-- Lifecycle/trigger:
-  - Start trigger: GitHub Actions starts the job only when `PROC:gh-release-check` exports `is_master=true`.
-  - Stop trigger: returns runner success after npm publication, changelog generation, and GitHub Release creation or runner failure on action errors.
-  - Looping model: single-pass job with sequential step execution.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `build-release(...)`: checkout repository content, configure Node.js `24.15.0` for npm publication, install dependencies, remove manifest `private`, publish the package, build changelog text, and create the GitHub Release [`.github/workflows/release-npm.yml`]
-    - External boundaries: `actions/checkout@v5`, `actions/setup-node@v5`, npm CLI, npm registry, OIDC token issuance, `mikepenz/release-changelog-builder-action@v6`, `softprops/action-gh-release@v2`, `secrets.NPM_TOKEN`, and `secrets.GITHUB_TOKEN`.
-- External Boundaries:
-  - GitHub Actions event routing, hosted-runner lifecycle, checkout action, setup-node action, npm CLI, npm registry, changelog-builder action, GitHub Releases API, and repository secrets.
-
-### `PROC:install-static-checkers`
-- Entrypoints:
-  - `main(...)`: best-effort bundled-checker installer root [`scripts/install-static-checkers.ts`]
-- Lifecycle/trigger:
-  - Start trigger: npm invokes the `postinstall` script declared in `package.json` after dependency installation.
-  - Stop trigger: returns numeric exit code `0` unconditionally after probing, optional best-effort installs, and native-checker guidance output.
-  - Looping model: single-pass probe plus optional install with no persistent loop.
-  - Threads: no explicit threads detected.
-- Internal Call-Trace Tree:
-  - `main(...)`: when invoked as the npm `postinstall` lifecycle, best-effort write consumer-root name-only `allowScripts` approvals, then probe each bundled npm checker, attempt best-effort install on miss, print native-checker guidance, and return `0` [`scripts/install-static-checkers.ts`]
-    - `approvePendingInstallScripts(...)`: best-effort write name-only `allowScripts` approvals into the consumer-root `package.json` for installed packages declaring install lifecycle scripts before probing [`scripts/install-static-checkers.ts`]
-      - `getConsumerInstallRoot(...)`: resolve the consumer install root preferring the npm `npm_config_local_prefix` install root (correct under pi `npm install --prefix <root>` flows) over the `INIT_CWD` caller-cwd fallback [`scripts/install-static-checkers.ts`]
-      - `collectNodeModulesPackages(...)`: scan consumer-root `node_modules` and parse each readable package manifest [`scripts/install-static-checkers.ts`]
-      - `selectInstallScriptPackageNames(...)`: select package names declaring `preinstall`, `install`, or `postinstall` scripts [`scripts/install-static-checkers.ts`]
-      - `mergeAllowScriptsEntries(...)`: merge name-only approvals into the existing `allowScripts` map while preserving prior entries and explicit denials [`scripts/install-static-checkers.ts`]
-    - `resolveCheckerExecutable(...)`: resolve one checker across `%%INSTALLATION_PATH%%` keyword, bundled `node_modules/.bin`, and PATH scan locations [`src/core/static-check.ts`]
-      - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
-        - `isExecutableFile(...)`: verify executable access bits [`src/core/static-check.ts`]
-    - `attemptBundledInstall(...)`: best-effort `npm install <pkg>@<range> --no-save --prefix <install-root>` swallowing all errors [`scripts/install-static-checkers.ts`]
-      - `getInstallationPath(...)`: resolve the installed extension root that owns `scripts/` and `src/` [`src/core/path-context.ts`]
-    - `printNativeCheckerGuidance(...)`: emit platform-specific install guidance for native checkers [`scripts/install-static-checkers.ts`]
-- External Boundaries:
-  - Node process APIs for argv, stdout, stderr, and exit code.
-  - Filesystem access for executable probing under the installation path and best-effort read plus optional write of the consumer-root `package.json` `allowScripts` map during postinstall approval.
-  - npm CLI subprocess spawned best-effort for missing bundled checkers.
-
-## Communication Edges
-- `PROC:req-debug` -> `PROC:tool-args-to-params`
-  - Mechanism: child-process spawn through resolved `tsx` executable.
-  - Endpoint/channel: CLI argv plus captured stdout/stderr.
-  - Payload/data-shape: wrapper tool name plus raw `--args` text, returned as one serialized JSON params object [`scripts/pi-usereq-debug.sh`, `scripts/tool-args-to-params.ts`]
-- `PROC:req-debug` -> `PROC:debug-ext`
-  - Mechanism: child-process spawn through resolved `tsx` executable.
-  - Endpoint/channel: CLI argv plus inherited stdout/stderr.
-  - Payload/data-shape: wrapper-normalized subcommand and forwarded debug-harness options with default `--cwd` and `--extension` values, including rewritten tool `--params` JSON when `--args` was supplied [`scripts/pi-usereq-debug.sh`, `scripts/debug-extension.ts`]
-- `PROC:gh-release-check` -> `PROC:gh-release-build`
-  - Mechanism: GitHub Actions `needs` dependency plus job-output gating.
-  - Endpoint/channel: `is_master` job output and shared tag-run context.
-  - Payload/data-shape: boolean branch-gate flag derived from `origin/master` containment for the tagged commit [`.github/workflows/release-npm.yml`]
-- Internal thread communication edges: none.
-- Relationship note: `PROC:main`, `PROC:req-debug`, `PROC:tool-args-to-params`, `PROC:debug-ext`, `PROC:pi-host`, `PROC:install-static-checkers`, `PROC:gh-release-check`, and `PROC:gh-release-build` are distinct runtime entry modes; only `PROC:req-debug` and `PROC:install-static-checkers` directly spawn child processes, while the GitHub Actions units coordinate through workflow job dependencies.