pi-usereq 0.40.0 → 0.42.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,7 +1,7 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.71"
+version: "0.0.74"
 date: "2026-07-10"
 author: "OpenAI Codex"
 scope:
@@ -90,6 +90,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **DES-011**: MUST implement `.github/workflows/release-npm.yml` as a two-job GitHub Actions pipeline where `check-branch` gates `build-release`, preserving changelog-driven GitHub Release creation while adding npm publication.
 - **DES-015**: MUST implement config-gated `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` slash-command wrappers in `src/index.ts` that reuse existing tool-runner execution paths.
 - **DES-016**: MUST deliver rendered bundled-prompt content to the LLM through `sendMessage` as a `display:false` custom message with `triggerTurn:true` and MUST NOT use `sendUserMessage` when `sendMessage` is available.
+- **DES-017**: MUST declare `pyright`, `ruff`, and `eslint` as pinned caret-range npm dependencies and register a `postinstall` script that installs bundled static checkers.
+- **DES-018**: MUST resolve checker executables by probing bundled `node_modules/.bin` paths relative to the installation path before falling back to `PATH` scan.
 
 ### 3.2 Functions
 - **REQ-001**: MUST access bundled prompts, git execution instructions, templates, and guidelines from `<installation-path>/resources` without requiring user-home resource copies before prompt or tool execution.
@@ -162,6 +164,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-335**: MUST display a command invocation summary on screen for every bundled prompt-backed `req-<prompt>` command containing the command name, passed arguments, and active configuration.
 - **REQ-336**: MUST render the command invocation summary with the command name without the `req-` prefix in uppercase and the user request arguments.
 - **REQ-337**: MUST include `docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools` in the command invocation summary.
+- **REQ-338**: MUST render `none` for the command invocation summary `context files`, `static code checks`, and `enabled tools` fields whenever their respective enabled-item list is empty.
 - **REQ-008**: MUST provide a `Language static code checkers` submenu that adds global Command entries by guided language flow, removes configured global checker entries, toggles local per-language enablement, and resets static-check configuration.
 - **REQ-160**: MUST hardcode `Command` as the only user-configurable static-check module and omit module-selection UI from static-check configuration menus.
 - **REQ-161**: MUST hide `Dummy` from user-configurable static-check menus while preserving existing-config parsing and debug-driver support for `Dummy` entries.
@@ -337,7 +340,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-020**: MUST parse user `--enable-static-check` specs in `LANG=Command,CMD[,PARAM...]` format and normalize supported language names plus `Command` case-insensitively.
 - **REQ-021**: MUST reject user `--enable-static-check` specs with missing `=`, missing `Command`, missing `cmd`, unknown language, or any module other than `Command`.
 - **REQ-022**: MUST preserve persisted `Dummy` static-check entries during config loading and execute them only when present in configuration or `--test-static-check dummy` input.
-- **REQ-023**: MUST require `Command`-module executables to exist on `PATH` before static-check execution.
+- **REQ-023**: MUST require `Command`-module executables to resolve via bundled `node_modules/.bin` or `PATH` before static-check execution.
 - **REQ-030**: MUST set static `base-path` from the bootstrap cwd and static `local-config-path` to `<base-path>/.pi-usereq.json`.
 - **REQ-317**: MUST set static `global-config-path` to `~/.config/pi-usereq/config.json`.
 - **REQ-259**: MUST set dynamic `context-path` from the bootstrap cwd and keep it aligned with `ctx.cwd`.
@@ -362,7 +365,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-035**: MUST parse repeatable `--enable-static-check LANG=Command,CMD[,PARAM...]` CLI options before command dispatch and merge resulting entries into persisted global checker lists.
 - **REQ-253**: MUST set `static-check.<language>.enabled=enable` whenever guided or CLI `--enable-static-check` entry creation targets that language.
 - **REQ-036**: MUST preserve existing global `static-check` checker entries, append non-duplicate `--enable-static-check` entries in argument order, and treat canonical language, module, cmd, and params as the duplicate identity.
-- **REQ-037**: MUST reject `--enable-static-check` `Command` entries whose executable is unavailable on `PATH` and MUST NOT modify persisted local or global configuration when validation fails.
+- **REQ-037**: MUST reject `--enable-static-check` `Command` entries whose executable is unresolvable via bundled `node_modules/.bin` or `PATH` and MUST NOT modify persisted local or global configuration when validation fails.
 - **REQ-038**: MUST honor `--verbose` only for `files-summarize`, `files-compress`, `files-find`, `summarize`, `compress`, and `find`, emitting command progress to stderr while leaving stdout payload format unchanged.
 - **REQ-039**: MUST support `--enable-line-numbers` only for `files-compress`, `compress`, `files-find`, and `find`, and MUST leave corresponding outputs unnumbered when the flag is absent.
 - **REQ-040**: MUST store canonical expected CLI result fixtures as UTF-8 text files under `tests/fixtures_attended_results/`, preserving normalized exit code, stdout, and stderr for each archived scenario.
@@ -395,12 +398,18 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-325**: MUST reject `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` execution when `DEBUG_TOOL_COMMANDS_ENABLED=disable`.
 - **REQ-326**: MUST add a top-level `Context Files` row to the `pi-usereq` menu between `Unit tests directory` and `Auto git commit`.
 - **REQ-327**: MUST expose a `Context Files` submenu with separate enable toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` in that order.
-- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to enabled.
+- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to disabled.
 - **REQ-329**: MUST replace the `%%CONTEXT_FILES%%` prompt token with one markdown section per enabled context file in the order `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md`.
 - **REQ-330**: MUST render each `%%CONTEXT_FILES%%` section as the file-name heading, an HTML `<file name="<docs-dir>/<filename>">` reference with `%%DOC_PATH%%` pre-substituted, and the raw file content inside four-backtick `markdown` fences.
 - **REQ-331**: MUST omit the `%%CONTEXT_FILES%%` section for any disabled flag or missing context file without surfacing an error.
 - **REQ-332**: MUST inject `%%CONTEXT_FILES%%` content verbatim after every other prompt replacement so literal `%%...%%` tokens inside context files are not substituted.
-- **REQ-333**: MUST restore all three `Context Files` flags to enabled when the `Context Files` subtree `Reset defaults` is approved.
+- **REQ-333**: MUST restore all three `Context Files` flags to disabled when the `Context Files` subtree `Reset defaults` is approved.
+- **REQ-339**: MUST run `scripts/install-static-checkers.ts` as a best-effort exit-code-0 `postinstall` installer that probes bundled npm checkers, attempts `npm install` on miss, prints platform guidance for native checkers, and never modifies git-tracked files.
+- **REQ-340**: MUST default the `TypeScript` static-check `Command` entry to `cmd: "eslint"` with empty `params`.
+- **REQ-341**: MUST emit one warning notification during `session_start` listing missing enabled static checkers without transitioning workflow state or aborting.
+- **REQ-342**: MUST keep `STATIC_CHECK_MODULES`, `dispatchStaticCheckForFile` signature, and `StaticCheckEntry` shape unchanged when adding bundled executable resolution.
+- **REQ-343**: MUST NOT transition workflow state or abort `session_start` when one or more enabled static checkers are missing.
+- **REQ-344**: MUST place the `session_start` missing-checker helper in `src/core/static-check.ts` so `src/index.ts` remains thin.
 
 ## 4. Test Requirements
 - **TST-001**: MUST verify extension activation registers every documented prompt command, agent tool, and configuration command while omitting tool-name slash commands, `test-static-check`, and the removed standalone config-viewer command.
@@ -522,6 +531,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-118**: MUST verify the `Context Files` submenu persists the three context-file flags in local configuration with immediate-save, reset, and focus-preserving re-render behavior.
 - **TST-119**: MUST verify `%%CONTEXT_FILES%%` replacement emits one section per enabled existing file in the documented order and omits disabled or missing files.
 - **TST-120**: MUST verify `%%CONTEXT_FILES%%` sections use the file-name heading, the pre-substituted HTML file reference, and four-backtick `markdown` fences around raw content.
+- **TST-122**: MUST verify the command invocation summary renders `none` for `context files`, `static code checks`, and `enabled tools` when no items are enabled in each respective category.
+- **TST-123**: MUST verify `resolveCheckerExecutable` probes bundled `node_modules/.bin` paths before `PATH` scan.
+- **TST-124**: MUST verify `scripts/install-static-checkers.ts` always returns exit code `0` regardless of probe or install outcomes.
+- **TST-125**: MUST verify `session_start` emits one warning notification for missing enabled checkers without aborting or transitioning workflow state.
 
 ## 5. Observed Component Model
 

package/pi-usereq/docs/WORKFLOW.md

@@ -49,6 +49,13 @@
     - `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 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`
@@ -83,8 +90,9 @@
       - `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`]
-        - `findExecutable(...)`: resolve executable on PATH or explicit path [`src/core/static-check.ts`]
-          - `isExecutableFile(...)`: verify executable access bits [`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`]
@@ -208,8 +216,9 @@
           - `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`]
-        - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-          - `isExecutableFile(...)`: verify executable access bits [`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`]
@@ -227,8 +236,9 @@
             - `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`]
-          - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-            - `isExecutableFile(...)`: verify executable access bits [`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`]
@@ -366,8 +376,9 @@
               - `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`]
-            - `findExecutable(...)`: resolve executable on `PATH` or explicit path [`src/core/static-check.ts`]
-              - `isExecutableFile(...)`: verify executable access bits [`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`]
@@ -494,6 +505,7 @@
             - `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`]
@@ -575,8 +587,8 @@
             - `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 [`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, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable [`src/index.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`]
@@ -880,8 +892,8 @@
         - `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 [`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, 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`]
+      - `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.
@@ -992,6 +1004,7 @@
             - `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`]
@@ -1280,6 +1293,27 @@
 - 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(...)`: probe each bundled npm checker, attempt best-effort install on miss, print native-checker guidance, and return `0` [`scripts/install-static-checkers.ts`]
+    - `resolveCheckerExecutable(...)`: resolve one checker across bundled `node_modules/.bin` locations and 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`]
+    - `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.
+  - 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.
@@ -1294,4 +1328,4 @@
   - 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:gh-release-check`, and `PROC:gh-release-build` are distinct runtime entry modes; only `PROC:req-debug` directly spawns child processes, while the GitHub Actions units coordinate through workflow job dependencies.
+- 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.

package/scripts/install-static-checkers.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * @file
+ * @brief Implements the best-effort postinstall installer for bundled static checkers.
+ * @details Probes bundled npm-backed static-check executables (`pyright`, `ruff`, `eslint`), attempts a best-effort `npm install --no-save --prefix` on miss, and prints platform-specific guidance for native checkers (`cppcheck`, `clang-format`). Runtime is dominated by child-process probing and optional npm execution. Side effects include stdout/stderr writes, filesystem reads, and best-effort `npm install` subprocess spawning. The script always exits with code `0` and never modifies git-tracked files.
+ */
+
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { resolveCheckerExecutable } from "../src/core/static-check.js";
+import { getInstallationPath } from "../src/core/path-context.js";
+
+/**
+ * @brief Lists the npm-bundled static-check package names that the extension ships as dependencies.
+ * @details Each entry maps to one executable name resolvable through bundled `node_modules/.bin` after `npm install` completes. Access complexity is O(1).
+ */
+export const BUNDLED_NPM_CHECKERS = ["pyright", "ruff", "eslint"] as const;
+
+/**
+ * @brief Lists the native system-package-manager static-check executables that the extension cannot bundle.
+ * @details Each entry maps to one executable name that users must install through their operating system package manager. Access complexity is O(1).
+ */
+export const NATIVE_CHECKERS = ["cppcheck", "clang-format"] as const;
+
+/**
+ * @brief Maps one bundled npm checker name to its pinned caret install range.
+ * @details Returns the caret range matching the package manifest so best-effort installs stay aligned with declared dependencies. Runtime is O(1). No side effects occur.
+ * @param[in] pkg {string} Bundled npm package name.
+ * @return {string} Pinned caret install range.
+ */
+function bundledCheckerRange(pkg: string): string {
+  switch (pkg) {
+    case "pyright":
+      return "^1.1.411";
+    case "ruff":
+      return "^1.5.4";
+    case "eslint":
+      return "^10.2.0";
+    default:
+      return "latest";
+  }
+}
+
+/**
+ * @brief Prints platform-specific install guidance for native checkers.
+ * @details Detects the current platform and emits one consolidated stderr line per native checker describing the recommended system package manager command. Runtime is O(1). Side effect: writes to stderr.
+ * @return {void} No return value.
+ */
+function printNativeCheckerGuidance(): void {
+  const platform = process.platform;
+  let manager: string;
+  let installPrefix: string;
+  if (platform === "linux") {
+    manager = "apt";
+    installPrefix = "sudo apt install";
+  } else if (platform === "darwin") {
+    manager = "brew";
+    installPrefix = "brew install";
+  } else if (platform === "win32") {
+    manager = "choco/scoop";
+    installPrefix = "choco install";
+  } else {
+    manager = "system package manager";
+    installPrefix = "install";
+  }
+  for (const checker of NATIVE_CHECKERS) {
+    process.stderr.write(
+      `Native checker '${checker}' not found. Install via ${manager}: ${installPrefix} ${checker}\n`,
+    );
+  }
+}
+
+/**
+ * @brief Attempts a best-effort `npm install` for one missing bundled checker.
+ * @details Runs `npm install <pkg>@<range> --no-save --prefix <installation-root>` inside the installation parent directory, swallowing all errors so the postinstall flow never fails. Runtime is dominated by npm execution. Side effects include subprocess spawning and optional writes under the installation root.
+ * @param[in] pkg {string} Bundled npm package name.
+ * @return {void} No return value.
+ */
+function attemptBundledInstall(pkg: string): void {
+  const range = bundledCheckerRange(pkg);
+  const installRoot = path.resolve(getInstallationPath(), "..");
+  try {
+    const result = spawnSync(
+      "npm",
+      ["install", `${pkg}@${range}`, "--no-save", "--prefix", installRoot],
+      { encoding: "utf8" },
+    );
+    if (result.error) {
+      process.stderr.write(`Warning: failed to install bundled checker '${pkg}': ${result.error.message}\n`);
+    }
+  } catch (error) {
+    process.stderr.write(
+      `Warning: failed to install bundled checker '${pkg}': ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+  }
+}
+
+/**
+ * @brief Executes the postinstall static-checker installation flow.
+ * @details Probes each bundled npm checker through `resolveCheckerExecutable`, attempts a best-effort install on miss, prints native-checker guidance for unresolvable native checkers, and always returns `0` so `npm install` never fails because of missing optional checkers. Runtime is dominated by PATH probing and optional npm execution. Side effects include stdout/stderr writes and best-effort `npm install` subprocess spawning. The script never modifies git-tracked files.
+ * @param[in] argv {string[]} Raw CLI arguments (unused, retained for CLI convention parity).
+ * @return {number} Always returns `0`.
+ * @satisfies REQ-339, DES-017
+ */
+export function main(argv = process.argv.slice(2)): number {
+  void argv;
+  for (const checker of BUNDLED_NPM_CHECKERS) {
+    if (resolveCheckerExecutable(checker)) {
+      process.stdout.write(`Bundled static checker '${checker}' is available.\n`);
+      continue;
+    }
+    process.stderr.write(`Bundled static checker '${checker}' not found; attempting best-effort install.\n`);
+    attemptBundledInstall(checker);
+  }
+  const missingNative = NATIVE_CHECKERS.filter((checker) => !resolveCheckerExecutable(checker));
+  if (missingNative.length > 0) {
+    printNativeCheckerGuidance();
+  }
+  return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exitCode = main();
+}

package/src/core/config.ts

@@ -214,14 +214,14 @@ export const DEFAULT_TESTS_DIR = "tests";
 export const DEFAULT_SRC_DIRS = ["src"];
 /**
  * @brief Defines the default value for every persisted context-file injection flag.
- * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to enabled so the bundled canonical documents remain part of the prompt context unless the user explicitly disables one. Lookup complexity is O(1).
+ * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to disabled so the bundled canonical documents are excluded from the prompt context unless the user explicitly enables one. Lookup complexity is O(1).
  * @satisfies REQ-328
  */
-export const DEFAULT_CONTEXT_FILES_FLAG = true;
+export const DEFAULT_CONTEXT_FILES_FLAG = false;
 
 /**
  * @brief Normalizes one persisted context-file injection flag.
- * @details Returns the documented default (`true`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection enabled. Runtime is O(1). No external state is mutated.
+ * @details Returns the documented default (`false`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection disabled. Runtime is O(1). No external state is mutated.
  * @param[in] value {unknown} Candidate persisted context-file flag.
  * @return {boolean} Normalized context-file injection flag.
  * @satisfies REQ-328
@@ -316,8 +316,8 @@ const DEFAULT_STATIC_CHECK_CHECKERS: Record<string, StaticCheckEntry[]> = {
   TypeScript: [
     {
       module: "Command",
-      cmd: "npx",
-      params: ["eslint"],
+      cmd: "eslint",
+      params: [],
     },
   ],
 };

package/src/core/prompt-command-runtime.ts

@@ -6,7 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
 import { classifyPiNotifyOutcome, type PiNotifyOutcome } from "./pi-notify.js";
 import {
@@ -20,6 +20,7 @@ import {
   type DebugWorkflowState,
 } from "./debug-runtime.js";
 import { type PromptCommandName } from "./prompt-command-catalog.js";
+export { type PromptCommandName } from "./prompt-command-catalog.js";
 import {
   isSameOrAncestorPath,
   normalizeRelativeDirContract,
@@ -119,14 +120,13 @@ interface PromptCommandActiveContext extends PromptCommandSessionContext {
 
 /**
  * @brief Describes one serializable session entry copied into a materialized execution-session file.
- * @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. The interface is compile-time only and introduces no runtime cost.
+ * @details Captures the stable tree-entry fields needed to write a JSONL session snapshot for cross-cwd session replacement when the origin session file has not been flushed yet. Mirrors the SDK `SessionEntryBase` shape without an index signature so the SDK `SessionEntry` union remains structurally assignable for passthrough serialization. The interface is compile-time only and introduces no runtime cost.
  */
 interface PromptCommandSessionEntry {
   type: string;
   id: string;
   parentId: string | null;
   timestamp: string;
-  [key: string]: unknown;
 }
 
 /**
@@ -705,7 +705,7 @@ async function switchPromptCommandSession(
     throw new ReqError(`ERROR: Prompt orchestration requires ctx.switchSession() for ${sessionFile}.`, 1);
   }
   let replacementContext: PromptCommandActiveContext | undefined;
-  let switchResult: { cancelled?: boolean } | void;
+  let switchResult: { cancelled?: boolean } | void = undefined;
   try {
     switchResult = await ctx.switchSession(sessionFile, {
       withSession: async (activeContext) => {
@@ -840,9 +840,9 @@ const PROMPT_REQUIRED_DOCS: Record<PromptCommandName, readonly PromptRequiredDoc
  * @details Delegates to `spawnSync`, preserves the supplied working directory, and returns the raw subprocess result used by prompt-command orchestration. Runtime is dominated by external process execution. Side effects include process spawning.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 decoded stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/core/prompts.ts

@@ -375,12 +375,12 @@ export const PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE = "pi-usereq-prompt-command";
 
 /**
  * @brief Builds the on-screen command invocation summary for one bundled prompt-backed `req-<prompt>` command.
- * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
  * @param[in] promptName {string} Bundled prompt name without the `req-` prefix.
  * @param[in] args {string} User request arguments passed to the slash command.
  * @param[in] config {UseReqConfig} Effective project configuration supplying directory, git, static-check, and tool fields.
  * @return {string} Multi-line command invocation summary text.
- * @satisfies REQ-335, REQ-336, REQ-337
+ * @satisfies REQ-335, REQ-336, REQ-337, REQ-338
  */
 export function renderPromptCommandSummary(
   promptName: string,
@@ -390,17 +390,17 @@ export function renderPromptCommandSummary(
   const contextFiles = CONTEXT_FILE_DESCRIPTORS
     .filter((descriptor) => config[descriptor.flagKey])
     .map((descriptor) => descriptor.fileName.replace(/\.md$/, "").toLowerCase())
-    .join(", ");
+    .join(", ") || "none";
   const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
     .filter((language) => config["static-check"][language]?.enabled === "enable")
-    .join(", ");
-  const enabledTools = [...config["enabled-tools"]]
+    .join(", ") || "none";
+  const enabledTools = ([...config["enabled-tools"]]
     .sort((left, right) =>
       comparePiUsereqStartupToolNames(
         left as PiUsereqStartupToolName,
         right as PiUsereqStartupToolName,
       ))
-    .join(", ");
+    .join(", ") || "none");
   const effectiveWorktree = resolveEffectiveGitWorktreeEnabled(
     config.AUTO_GIT_COMMIT,
     config.GIT_WORKTREE_ENABLED,

package/src/core/req-references-command.ts

@@ -4,7 +4,7 @@
  * @details Performs slash-command-owned git validation reuse, reference-file generation, targeted staging, fixed-message commit creation, and post-commit cleanliness verification without creating a worktree or starting an LLM session. Runtime is dominated by git subprocess execution plus source-summary generation and one documentation write. Side effects include filesystem writes and git index/history mutation.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import path from "node:path";
 import type { UseReqConfig } from "./config.js";
 import { ReqError } from "./errors.js";
@@ -39,9 +39,9 @@ export interface ReqReferencesCommandPlan {
  * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/core/req-reset-command.ts

@@ -6,7 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import {
   normalizeGitWorktreePrefix,
   type UseReqConfig,
@@ -63,9 +63,9 @@ type ReqResetCommandContext = Parameters<typeof restorePromptCommandExecution>[1
  * @details Delegates to `spawnSync(...)`, preserves the supplied working directory, and returns the raw result so callers can interpret git exit status plus diagnostics deterministically. Runtime is dominated by external process execution. Side effects include subprocess creation.
  * @param[in] command {string[]} Executable plus argument vector.
  * @param[in] cwd {string} Working directory for the subprocess.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runCapture(command: string[], cwd: string): ReturnType<typeof spawnSync> {
+function runCapture(command: string[], cwd: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",

package/src/core/runtime-project-paths.ts

@@ -5,7 +5,7 @@
  */
 
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawnSync, type SpawnSyncReturns } from "node:child_process";
 import { ReqError } from "./errors.js";
 import { isSameOrAncestorPath } from "./path-context.js";
 
@@ -14,9 +14,9 @@ import { isSameOrAncestorPath } from "./path-context.js";
  * @details Delegates to `spawnSync`, keeps execution synchronous for deterministic command flows, and supports an optional working directory. Runtime is dominated by the spawned git process. Side effects include subprocess creation.
  * @param[in] command {string[]} Git executable plus argument vector.
  * @param[in] cwd {string | undefined} Optional working directory.
- * @return {ReturnType<typeof spawnSync>} Captured subprocess result.
+ * @return {SpawnSyncReturns<string>} Captured subprocess result with UTF-8 stdout and stderr.
  */
-function runGitCapture(command: string[], cwd?: string): ReturnType<typeof spawnSync> {
+function runGitCapture(command: string[], cwd?: string): SpawnSyncReturns<string> {
   return spawnSync(command[0]!, command.slice(1), {
     cwd,
     encoding: "utf8",