pi-usereq 0.13.0 → 0.33.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.66"
-date: "2026-04-27"
+version: "0.0.68"
+date: "2026-05-29"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -69,6 +69,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **CTN-015**: MUST reserve `*-path` names for absolute paths and `*-dir` names for relative paths.
 - **CTN-016**: MUST NOT modify any path under `docs/` during analysis, implementation, verification, or bug fixing.
 - **CTN-017**: MUST NOT modify any path under `pi.dev-src/` during analysis, implementation, verification, or bug fixing.
+- **CTN-019**: MUST persist local `DEBUG_TOOL_COMMANDS_ENABLED` with allowed values `enable` and `disable`, defaulting to `disable`.
 
 ## 3. Requirements
 
@@ -87,6 +88,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **DES-009**: MUST treat `docs/pi.dev/coding-agent-docs/` and documents referenced by `docs/pi.dev/agent-document-manifest.json` as the authoritative read-only contract for new or modified software that interfaces with the pi.dev CLI.
 - **DES-010**: MUST centralize event-driven context snapshots, run-timing state, prompt-orchestration workflow state, and status-bar rendering through shared extension-status helpers.
 - **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.
 
 ### 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.
@@ -364,7 +366,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-043**: MUST archive repository scenarios for `summarize`, `compress`, `find`, `tokens`, `enable-static-check`, `files-static-check`, and `static-check`.
 - **REQ-138**: MUST make `.github/workflows/release-npm.yml` trigger release automation from pushed tags matched by the existing workflow filter `v[0-9]+.[0-9]+.[0-9]+`.
 - **REQ-139**: MUST skip downstream release work unless `check-branch` confirms the tagged commit is contained in `origin/master`.
-- **REQ-140**: MUST configure Node.js plus npm registry authentication, run `npm ci`, remove manifest `private`, and publish with provenance and public access using `secrets.NPM_TOKEN`.
+- **REQ-140**: MUST configure `.github/workflows/release-npm.yml` to use Node.js `24.15.0`, npm registry authentication, run `npm ci`, remove manifest `private`, and publish with provenance and public access using `secrets.NPM_TOKEN`.
 - **REQ-141**: MUST preserve the existing changelog-builder step and use its output as the non-draft non-prerelease GitHub Release body.
 - **REQ-155**: MUST keep `package.json` `name` equal to `pi-usereq` so npm publication resolves to `https://www.npmjs.com/package/pi-usereq`.
 - **REQ-157**: MUST declare `package.json` `repository.type` as `git` and `repository.url` as `git+https://github.com/Ogekuri/PI-useReq.git`.
@@ -381,6 +383,11 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-152**: MUST render a persistent bottom-line description for the currently selected configuration entry.
 - **REQ-153**: MUST use scrollable configuration menus when entry count exceeds the visible row budget.
 - **REQ-154**: MUST wrap configuration-menu selection from last-to-first and first-to-last entries.
+- **REQ-321**: MUST render `Enable debug commands for tools` in `Debug` after `Log file` and before `Log on status`.
+- **REQ-322**: MUST persist `DEBUG_TOOL_COMMANDS_ENABLED` through the `Debug` submenu with immediate-save, reset, and focus-preserving re-render behavior.
+- **REQ-323**: MUST register `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` only when `DEBUG_TOOL_COMMANDS_ENABLED=enable`.
+- **REQ-324**: MUST make `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` reuse the `compress`, `references`, `static-check`, and `tokens` runner outputs and write `content[0].text` to the editor.
+- **REQ-325**: MUST reject `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` execution when `DEBUG_TOOL_COMMANDS_ENABLED=disable`.
 
 ## 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.
@@ -454,7 +461,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-027**: MUST verify harness inspection surfaces `files-compress` and `compress` descriptions covering parameters, line-number behavior, monolithic markdown output, and failure details.
 - **TST-028**: MUST verify `files-static-check` and `static-check` agent-tool outputs place the monolithic static-check report in `content[0].text` and restrict `details` to execution metadata.
 - **TST-029**: MUST verify harness inspection surfaces `files-static-check` and `static-check` descriptions covering parameters, monolithic output, selection rules, and failure details.
-- **TST-039**: MUST verify `.github/workflows/release-npm.yml` keeps the existing tag filter, gates downstream release work on `origin/master`, runs npm publication, and creates the GitHub Release from generated changelog text.
+- **TST-039**: MUST verify `.github/workflows/release-npm.yml` keeps the existing tag filter, gates downstream release work on `origin/master`, uses Node.js `24.15.0`, runs npm publication, and creates the GitHub Release from generated changelog text.
 - **TST-042**: MUST verify `package.json` keeps `name` equal to `pi-usereq` so npm publication resolves to `https://www.npmjs.com/package/pi-usereq`.
 - **TST-044**: MUST verify `package.json` keeps npm provenance metadata aligned to the canonical GitHub repository, issues URL, and README homepage.
 - **TST-040**: MUST verify local and global configuration files omit derived static and dynamic path fields while runtime path context and status rendering still derive them correctly.
@@ -493,6 +500,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-066**: MUST verify `req-<prompt>` commands keep working when extension custom-tool registrations are removed from the runtime inventory.
 - **TST-059**: MUST verify every agent-tool registration defines custom `renderResult` and that compact rendering shows essential invocation parameters while expanded rendering avoids fallback raw-content display.
 - **TST-086**: MUST verify bundled prompt-backed `req-<prompt>` commands abort before prompt dispatch when the persisted execution-session header cwd or `process.cwd()` differs from the expected execution path, and abort before merge when persisted execution-session header metadata or verified worktree artifacts diverge, while stale pre-switch context probes alone do not abort.
+- **TST-113**: MUST verify default local configuration persists `DEBUG_TOOL_COMMANDS_ENABLED=disable`, and the `Debug` submenu renders `Enable debug commands for tools` before `Log on status`.
+- **TST-114**: MUST verify the `Debug` submenu persists `DEBUG_TOOL_COMMANDS_ENABLED` through immediate-save, reset, and focus-preserving re-render flows.
+- **TST-115**: MUST verify extension activation registers `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` only when `DEBUG_TOOL_COMMANDS_ENABLED=enable`.
+- **TST-116**: MUST verify `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` write the same `content[0].text` as `compress`, `references`, `static-check`, and `tokens`, and reject execution when disabled.
 
 ## 5. Observed Component Model
 
@@ -521,7 +532,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 ### 5.3 Packaging and Tooling Surface
 - `package.json` declares `type: "module"`, `pi.extensions: ["./src/index.ts"]`, and the scripts `test`, `test:watch`, `cli`, `debug:ext`, `debug:ext:inspect`, `debug:ext:session`, `debug:ext:command`, `debug:ext:tool`, and `debug:ext:sdk`.
 - `tsconfig.json` declares `target: "ES2022"`, `module: "NodeNext"`, `moduleResolution: "NodeNext"`, `strict: true`, `noEmit: true`, `skipLibCheck: true`, `resolveJsonModule: true`, and `types: ["node"]`.
-- `.github/workflows/release-npm.yml` validates canonical release tags, publishes the package to npm, and creates the matching GitHub Release.
+- `.github/workflows/release-npm.yml` validates canonical release tags, pins Node.js `24.15.0` for release execution, publishes the package to npm, and creates the matching GitHub Release.
 - `package.json` declares version `0.0.0` while `package-lock.json` resolves the top-level package as version `0.1.0`; this manifest metadata is inconsistent in the current revision.
 
 ## 6. Repository Structure
@@ -592,7 +603,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - `tests/prompt-rendering.test.ts` covers home-resource synchronization and placeholder replacement in rendered prompts.
 - `tests/oracle-standalone.test.ts` compares non-tab-sensitive standalone `files-*` outputs against the Python `usereq.cli` oracle, asserts Go-fixture tab preservation, and compares `--test-static-check` dummy/command outputs against archived fixtures.
 - `tests/oracle-project.test.ts` compares non-tab-sensitive project commands against the Python oracle, asserts Go-source tab preservation for project extraction commands, and verifies archived `files-static-check` plus `static-check` outputs.
-- `tests/release-workflow.test.ts` verifies semver-tag gating, npm publication steps, and GitHub release creation directives in `.github/workflows/release-npm.yml`.
+- `tests/release-workflow.test.ts` verifies semver-tag gating, the pinned Node.js `24.15.0` release runtime, npm publication steps, and GitHub release creation directives in `.github/workflows/release-npm.yml`.
 - Test business logic focuses on parity with the Python oracle, persistent config mutation, startup-tool activation, prompt-command worktree lifecycle correctness, and npm release workflow structure.
 
 ## 8. Evidence Matrix
@@ -685,7 +696,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | REQ-031 | `src/index.ts` :: `registerConfigCommands` :: `pi-usereq-show-config` writes `JSON.stringify(config, null, 2)` into the editor. |
 | REQ-138 | `.github/workflows/release-npm.yml` :: `on.push.tags` plus release-tag validation restrict automation to canonical `v<major>.<minor>.<patch>` tags. |
 | REQ-139 | `.github/workflows/release-npm.yml` :: branch-check job fetches `origin/master` and gates downstream jobs on containment of `github.sha`. |
-| REQ-140 | `.github/workflows/release-npm.yml` :: publish job uses `actions/setup-node`, `npm ci`, `npm pkg delete private`, and `npm publish --provenance` with `NODE_AUTH_TOKEN`. |
+| REQ-140 | `.github/workflows/release-npm.yml` :: `env.NODE_VERSION` is `24.15.0`; publish job uses `actions/setup-node`, `npm ci`, `npm pkg delete private`, and `npm publish --provenance --access public` with `NODE_AUTH_TOKEN`. |
 | REQ-141 | `.github/workflows/release-npm.yml` :: release job uses changelog-builder output as `softprops/action-gh-release` body with non-draft and non-prerelease flags. |
 
 ### 8.4 TST Evidence
@@ -715,7 +726,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 | TST-023 | `tests/extension-registration.test.ts` :: `summary tools register agent-oriented descriptions and schema details`. |
 | TST-024 | `tests/extension-registration.test.ts` :: `source-extraction agent tools preserve leading tabs in emitted content` plus the explicit `files-search` and `search` monolithic-output tests. |
 | TST-026 | `tests/extension-registration.test.ts` :: `source-extraction agent tools preserve leading tabs in emitted content` plus the explicit `files-compress` and `compress` monolithic-output tests. |
-| TST-039 | `tests/release-workflow.test.ts` :: workflow-content assertions cover semver gating, `origin/master` containment, npm publication, and GitHub release generation. |
+| TST-039 | `tests/release-workflow.test.ts` :: workflow-content assertions cover semver gating, `origin/master` containment, Node.js `24.15.0`, npm publication, and GitHub release generation. |
 
 ## 9. Performance Notes
 No explicit performance optimizations identified.

package/pi-usereq/docs/WORKFLOW.md

@@ -44,7 +44,7 @@
   - Threads: no explicit threads detected
 - ID: `PROC:gh-release-build`
   - Type: Process
-  - Role: GitHub Actions release runner that publishes the npm package, builds changelog text, and creates the GitHub Release after branch gating succeeds.
+  - 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
@@ -880,6 +880,15 @@
           - `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`, 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`]
@@ -1183,10 +1192,11 @@
           - `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, workflow filters, reset confirmation, and per-tool plus per-prompt selectors [`src/index.ts`]
-      - `buildDebugMenuChoices(...)`: serialize global debug controls, workflow-event toggles, canonical tool and prompt toggles, and the value-less terminal reset row [`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, the `Enable debug commands for tools` row, 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 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`]
@@ -1227,7 +1237,7 @@
   - 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@v4`, GitHub Actions runner shell, `git` CLI, `grep`, and `$GITHUB_OUTPUT`.
+    - 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.
 
@@ -1240,8 +1250,8 @@
   - 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 for npm, 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@v4`, `actions/setup-node@v4`, 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`.
+  - `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.
 

package/src/core/config.ts

@@ -36,6 +36,7 @@ import {
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
   DEFAULT_DEBUG_STATUS_CHANGES,
+  DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
   normalizeDebugEnabled,
   normalizeDebugEnabledPrompts,
@@ -43,7 +44,9 @@ import {
   normalizeDebugLogFile,
   normalizeDebugLogOnStatus,
   normalizeDebugStatusChanges,
+  normalizeDebugToolCommandsEnabled,
   normalizeDebugWorkflowEvents,
+  type DebugToolCommandsEnabled,
 } from "./debug-runtime.js";
 import { normalizeEnabledPiUsereqTools } from "./pi-usereq-tools.js";
 import { makeRelativeIfContainsProject } from "./utils.js";
@@ -90,6 +93,7 @@ export interface UseReqConfig {
   DEBUG_LOG_FILE: string;
   DEBUG_STATUS_CHANGES: "enable" | "disable";
   DEBUG_WORKFLOW_EVENTS: "enable" | "disable";
+  DEBUG_TOOL_COMMANDS_ENABLED: DebugToolCommandsEnabled;
   DEBUG_LOG_ON_STATUS: "any" | "idle" | "checking" | "running" | "merging" | "error";
   DEBUG_ENABLED_TOOLS: string[];
   DEBUG_ENABLED_PROMPTS: string[];
@@ -146,6 +150,7 @@ interface UseReqLocalConfig {
   DEBUG_LOG_FILE: string;
   DEBUG_STATUS_CHANGES: "enable" | "disable";
   DEBUG_WORKFLOW_EVENTS: "enable" | "disable";
+  DEBUG_TOOL_COMMANDS_ENABLED: DebugToolCommandsEnabled;
   DEBUG_LOG_ON_STATUS: "any" | "idle" | "checking" | "running" | "merging" | "error";
   DEBUG_ENABLED_TOOLS: string[];
   DEBUG_ENABLED_PROMPTS: string[];
@@ -547,9 +552,10 @@ export function getGlobalConfigPath(): string {
 
 /**
  * @brief Builds the default persisted local configuration.
- * @details Populates canonical docs/test/source directories, derives local static-check enable defaults from the supplied global checker definitions, and seeds documented debug defaults without any cross-project fields. Runtime is O(l). No filesystem side effects occur.
+ * @details Populates canonical docs/test/source directories, derives local static-check enable defaults from the supplied global checker definitions, and seeds documented debug defaults including tool-wrapper command registration without any cross-project fields. Runtime is O(l). No filesystem side effects occur.
  * @param[in] globalStaticCheckConfig {Record<string, GlobalStaticCheckLanguageConfig>} Global checker definitions used to derive local enable defaults.
  * @return {UseReqLocalConfig} Fresh default local configuration object.
+ * @satisfies CTN-019
  */
 function getDefaultLocalConfig(
   globalStaticCheckConfig: Record<string, GlobalStaticCheckLanguageConfig>,
@@ -563,6 +569,7 @@ function getDefaultLocalConfig(
     DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
     DEBUG_STATUS_CHANGES: DEFAULT_DEBUG_STATUS_CHANGES,
     DEBUG_WORKFLOW_EVENTS: DEFAULT_DEBUG_WORKFLOW_EVENTS,
+    DEBUG_TOOL_COMMANDS_ENABLED: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
     DEBUG_LOG_ON_STATUS: DEFAULT_DEBUG_LOG_ON_STATUS,
     DEBUG_ENABLED_TOOLS: [],
     DEBUG_ENABLED_PROMPTS: [],
@@ -608,7 +615,7 @@ function getDefaultGlobalConfig(): UseReqGlobalConfig {
 
 /**
  * @brief Merges persisted local and global configuration scopes into the effective runtime config.
- * @details Normalizes local directories, combines local static-check enable flags with global checker arrays, resolves effective worktree disablement when automatic git commit is off, normalizes debug and notification fields, and disables Pushover until both credentials are populated. Runtime is O(l + c + p). No external state is mutated.
+ * @details Normalizes local directories, combines local static-check enable flags with global checker arrays, resolves effective worktree disablement when automatic git commit is off, normalizes debug and notification fields including tool-wrapper command registration, and disables Pushover until both credentials are populated. Runtime is O(l + c + p). No external state is mutated.
  * @param[in] localConfig {UseReqLocalConfig} Persisted local configuration.
  * @param[in] globalConfig {UseReqGlobalConfig} Persisted global configuration.
  * @return {UseReqConfig} Effective merged configuration.
@@ -647,6 +654,7 @@ function mergeConfigScopes(
     DEBUG_LOG_FILE: normalizeDebugLogFile(localConfig.DEBUG_LOG_FILE),
     DEBUG_STATUS_CHANGES: normalizeDebugStatusChanges(localConfig.DEBUG_STATUS_CHANGES),
     DEBUG_WORKFLOW_EVENTS: normalizeDebugWorkflowEvents(localConfig.DEBUG_WORKFLOW_EVENTS),
+    DEBUG_TOOL_COMMANDS_ENABLED: normalizeDebugToolCommandsEnabled(localConfig.DEBUG_TOOL_COMMANDS_ENABLED),
     DEBUG_LOG_ON_STATUS: normalizeDebugLogOnStatus(localConfig.DEBUG_LOG_ON_STATUS),
     DEBUG_ENABLED_TOOLS: normalizeDebugEnabledTools(localConfig.DEBUG_ENABLED_TOOLS),
     DEBUG_ENABLED_PROMPTS: normalizeDebugEnabledPrompts(localConfig.DEBUG_ENABLED_PROMPTS),
@@ -686,7 +694,7 @@ function mergeConfigScopes(
  * @details Composes documented local and global defaults, then merges them into the effective runtime config consumed by CLI and extension code. Time complexity is O(l + c). No filesystem side effects occur.
  * @param[in] _projectBase {string} Absolute project root path retained for stable call sites.
  * @return {UseReqConfig} Fresh default effective configuration object.
- * @satisfies CTN-001, CTN-012, CTN-013, CTN-018, REQ-066, REQ-137, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-250, REQ-251, REQ-252, REQ-277, REQ-315, REQ-316
+ * @satisfies CTN-001, CTN-012, CTN-013, CTN-018, CTN-019, REQ-066, REQ-137, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-250, REQ-251, REQ-252, REQ-277, REQ-315, REQ-316
  */
 export function getDefaultConfig(_projectBase: string): UseReqConfig {
   const globalConfig = getDefaultGlobalConfig();
@@ -811,10 +819,11 @@ function normalizeGlobalStaticCheckConfig(
 
 /**
  * @brief Loads and sanitizes the persisted local configuration.
- * @details Returns defaults when `<base-path>/.pi-usereq.json` is absent. Otherwise parses the local JSON payload, normalizes project-scoped directory, debug, and static-check enable fields, and ignores misplaced global keys without migration. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
+ * @details Returns defaults when `<base-path>/.pi-usereq.json` is absent. Otherwise parses the local JSON payload, normalizes project-scoped directory, debug, tool-wrapper command registration, and static-check enable fields, and ignores misplaced global keys without migration. Runtime is O(n) in file size. Side effects are limited to filesystem reads.
  * @param[in] projectBase {string} Absolute project root path.
  * @param[in] defaultStaticCheckConfig {Record<string, LocalStaticCheckLanguageConfig>} Local static-check enable defaults derived from the current global checker map.
  * @return {UseReqLocalConfig} Sanitized local configuration.
+ * @satisfies CTN-019
  */
 function loadLocalConfig(
   projectBase: string,
@@ -832,6 +841,7 @@ function loadLocalConfig(
       DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
       DEBUG_STATUS_CHANGES: DEFAULT_DEBUG_STATUS_CHANGES,
       DEBUG_WORKFLOW_EVENTS: DEFAULT_DEBUG_WORKFLOW_EVENTS,
+      DEBUG_TOOL_COMMANDS_ENABLED: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
       DEBUG_LOG_ON_STATUS: DEFAULT_DEBUG_LOG_ON_STATUS,
       DEBUG_ENABLED_TOOLS: [],
       DEBUG_ENABLED_PROMPTS: [],
@@ -858,6 +868,7 @@ function loadLocalConfig(
     DEBUG_LOG_FILE: normalizeDebugLogFile(data.DEBUG_LOG_FILE),
     DEBUG_STATUS_CHANGES: normalizeDebugStatusChanges(data.DEBUG_STATUS_CHANGES),
     DEBUG_WORKFLOW_EVENTS: normalizeDebugWorkflowEvents(data.DEBUG_WORKFLOW_EVENTS),
+    DEBUG_TOOL_COMMANDS_ENABLED: normalizeDebugToolCommandsEnabled(data.DEBUG_TOOL_COMMANDS_ENABLED),
     DEBUG_LOG_ON_STATUS: normalizeDebugLogOnStatus(data.DEBUG_LOG_ON_STATUS),
     DEBUG_ENABLED_TOOLS: normalizeDebugEnabledTools(data.DEBUG_ENABLED_TOOLS),
     DEBUG_ENABLED_PROMPTS: normalizeDebugEnabledPrompts(data.DEBUG_ENABLED_PROMPTS),
@@ -918,7 +929,7 @@ function loadGlobalConfig(): UseReqGlobalConfig {
  * @param[in] projectBase {string} Absolute project root path.
  * @return {UseReqConfig} Sanitized effective configuration.
  * @throws {ReqError} Throws with exit code `11` when either persisted config file contains invalid JSON or a non-object payload.
- * @satisfies CTN-012, CTN-013, CTN-018, REQ-066, REQ-137, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-215, REQ-234, REQ-235, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-277, REQ-315, REQ-316
+ * @satisfies CTN-012, CTN-013, CTN-018, CTN-019, REQ-066, REQ-137, REQ-146, REQ-163, REQ-174, REQ-178, REQ-184, REQ-185, REQ-196, REQ-204, REQ-205, REQ-212, REQ-215, REQ-234, REQ-235, REQ-236, REQ-237, REQ-238, REQ-239, REQ-249, REQ-277, REQ-315, REQ-316
  */
 export function loadConfig(projectBase: string): UseReqConfig {
   const globalConfig = loadGlobalConfig();
@@ -931,10 +942,10 @@ export function loadConfig(projectBase: string): UseReqConfig {
 
 /**
  * @brief Builds the persisted local configuration payload.
- * @details Copies only project-scoped keys into a fresh object so runtime-derived metadata plus global checker, tool, git, and notification fields never reach `.pi-usereq.json`. Runtime is O(n) in config size. No external state is mutated.
+ * @details Copies only project-scoped keys into a fresh object so runtime-derived metadata plus global checker, tool, git, and notification fields never reach `.pi-usereq.json`, while preserving the debug tool-wrapper command flag beside other local debug settings. Runtime is O(n) in config size. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective configuration object.
  * @return {UseReqLocalConfig} Persistable local configuration payload.
- * @satisfies CTN-012, CTN-013, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277
+ * @satisfies CTN-012, CTN-013, CTN-019, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277
  */
 function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
   const normalizedSrcDir = config["src-dir"]
@@ -959,6 +970,7 @@ function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
     DEBUG_LOG_FILE: normalizeDebugLogFile(config.DEBUG_LOG_FILE),
     DEBUG_STATUS_CHANGES: normalizeDebugStatusChanges(config.DEBUG_STATUS_CHANGES),
     DEBUG_WORKFLOW_EVENTS: normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS),
+    DEBUG_TOOL_COMMANDS_ENABLED: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED),
     DEBUG_LOG_ON_STATUS: normalizeDebugLogOnStatus(config.DEBUG_LOG_ON_STATUS),
     DEBUG_ENABLED_TOOLS: normalizeDebugEnabledTools(config.DEBUG_ENABLED_TOOLS),
     DEBUG_ENABLED_PROMPTS: normalizeDebugEnabledPrompts(config.DEBUG_ENABLED_PROMPTS),

package/src/core/debug-runtime.ts

@@ -45,6 +45,13 @@ export const DEFAULT_DEBUG_STATUS_CHANGES = "disable" as const;
  */
 export const DEFAULT_DEBUG_WORKFLOW_EVENTS = "disable" as const;
 
+/**
+ * @brief Defines the default debug-tool command-wrapper mode.
+ * @details New configs suppress debug slash-command wrappers for selected built-in tools until the user explicitly enables them from the `Debug` submenu. Access complexity is O(1).
+ * @satisfies CTN-019, REQ-322
+ */
+export const DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED = "disable" as const;
+
 /**
  * @brief Defines the default workflow-status filter used by debug logging.
  * @details New configs log only entries whose workflow state equals `running` until the user selects a broader or different workflow-state filter. Access complexity is O(1).
@@ -98,6 +105,12 @@ export type DebugStatusChanges = "enable" | "disable";
  */
 export type DebugWorkflowEvents = "enable" | "disable";
 
+/**
+ * @brief Represents one persisted debug-tool command-wrapper flag.
+ * @details Restricts debug slash-command wrapper registration to the documented `enable|disable` domain. The alias is compile-time only and introduces no runtime cost.
+ */
+export type DebugToolCommandsEnabled = "enable" | "disable";
+
 /**
  * @brief Represents one persisted workflow-status filter value.
  * @details Restricts debug log filtering to `any` or one explicit documented workflow state. The alias is compile-time only and introduces no runtime cost.
@@ -191,6 +204,17 @@ export function normalizeDebugWorkflowEvents(value: unknown): DebugWorkflowEvent
   return value === "enable" ? "enable" : DEFAULT_DEBUG_WORKFLOW_EVENTS;
 }
 
+/**
+ * @brief Normalizes one persisted debug-tool command-wrapper flag.
+ * @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED` for all other payloads. Runtime is O(1). No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted debug-tool command-wrapper payload.
+ * @return {DebugToolCommandsEnabled} Canonical debug-tool command-wrapper flag.
+ * @satisfies CTN-019, REQ-322
+ */
+export function normalizeDebugToolCommandsEnabled(value: unknown): DebugToolCommandsEnabled {
+  return value === "enable" ? "enable" : DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED;
+}
+
 /**
  * @brief Normalizes one persisted debug workflow-status filter.
  * @details Accepts only the documented `any` token or one explicit workflow state and falls back to `DEFAULT_DEBUG_LOG_ON_STATUS` for all other payloads. Runtime is O(1). No external state is mutated.