pi-usereq 0.12.0 → 0.32.0

package/tests/extension-registration.test.ts

@@ -16,6 +16,7 @@ import {
   createStaticCheckLanguageConfig,
   DEFAULT_DOCS_DIR,
   getDefaultConfig,
+  getGlobalConfigPath,
   getProjectConfigPath,
   loadConfig,
 } from "../src/core/config.js";
@@ -23,6 +24,7 @@ import {
   DEBUG_PROMPT_NAMES,
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
+  DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
 } from "../src/core/debug-runtime.js";
 import { PROMPT_COMMAND_NAMES } from "../src/core/prompt-command-catalog.js";
@@ -58,7 +60,13 @@ import {
 } from "../src/core/extension-status.js";
 import { showPiUsereqSettingsMenu } from "../src/core/settings-menu.js";
 import { getSupportedStaticCheckLanguageSupport } from "../src/core/static-check.js";
-import { createTempDir, initFixtureRepo } from "./helpers.js";
+import {
+  createTempDir,
+  initFixtureRepo,
+  readGlobalConfigJson,
+  readProjectConfigJson,
+  saveFixtureConfigs,
+} from "./helpers.js";
 
 /**
  * @brief Describes one fake extension command registration captured during tests.
@@ -91,17 +99,16 @@ type RegisteredTool = {
 type RegisteredShortcut = { description?: string; handler: (ctx: any) => Promise<void> | void };
 
 /**
- * @brief Applies targeted `.pi-usereq.json` overrides inside one test project.
- * @details Loads the persisted config JSON, merges the supplied top-level overrides, and writes the updated payload back with a trailing newline so prompt-command tests can script worktree and notification behavior deterministically. Runtime is O(n) in config size. Side effects include filesystem reads and file overwrite.
+ * @brief Applies targeted effective-config overrides inside one test project.
+ * @details Loads the merged local/global config, merges the supplied top-level overrides, rewrites the split Node config files plus the oracle mirror, and commits the repository-local config artifacts when the fixture is a git repo. Runtime is O(n) in config size. Side effects include filesystem reads, file overwrite, and optional git commits.
  * @param[in] projectBase {string} Fixture project root.
  * @param[in] overrides {Record<string, unknown>} Top-level config overrides.
  * @return {void} No return value.
  */
 function writeProjectConfigOverrides(projectBase: string, overrides: Record<string, unknown>): void {
-  const configPath = getProjectConfigPath(projectBase);
-  const config = JSON.parse(fs.readFileSync(configPath, "utf8")) as Record<string, unknown>;
+  const config = loadConfig(projectBase);
   Object.assign(config, overrides);
-  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  saveFixtureConfigs(projectBase, config);
   if (fs.existsSync(path.join(projectBase, ".git"))) {
     const gitEnv = {
       ...process.env,
@@ -519,13 +526,13 @@ function buildExpectedFakeBasePath(cwd: string): string {
 }
 
 /**
- * @brief Formats one expected home-relative base path for notify-template assertions.
- * @details Resolves the supplied cwd, emits `~` or `~/...` when the path is inside the current user home directory, and otherwise returns the slash-normalized absolute path. Runtime is O(p) in path length. No external state is mutated.
- * @param[in] cwd {string} Runtime working directory.
- * @return {string} Home-relative or absolute base path used by notification templates.
+ * @brief Formats one expected home-relative display path.
+ * @details Resolves the supplied path, emits `~` or `~/...` when the path is inside the current user home directory, and otherwise returns the slash-normalized absolute path. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] targetPath {string} Absolute or relative path candidate.
+ * @return {string} Home-relative or absolute display path.
  */
-function buildExpectedNotifyBasePath(cwd: string): string {
-  const resolvedPath = path.resolve(cwd);
+function buildExpectedDisplayPath(targetPath: string): string {
+  const resolvedPath = path.resolve(targetPath);
   const homePath = path.resolve(process.env.HOME ?? os.homedir());
   if (resolvedPath === homePath) {
     return "~";
@@ -538,15 +545,32 @@ function buildExpectedNotifyBasePath(cwd: string): string {
 }
 
 /**
- * @brief Formats the expected `Show configuration` path value.
- * @details Resolves the current project config path and rewrites a leading home-directory prefix to `~` so top-level menu assertions match the documented display-only substitution without changing stored paths. Runtime is O(p) in path length. No external state is mutated.
+ * @brief Formats one expected home-relative base path for notify-template assertions.
+ * @details Delegates to the generic display-path formatter so notify-template assertions match the runtime `~`-relative path contract. Runtime is O(p) in path length. No external state is mutated.
  * @param[in] cwd {string} Runtime working directory.
- * @return {string} `~`-relative or absolute config-path display string.
+ * @return {string} Home-relative or absolute base path used by notification templates.
+ */
+function buildExpectedNotifyBasePath(cwd: string): string {
+  return buildExpectedDisplayPath(cwd);
+}
+
+/**
+ * @brief Formats the expected `Show local configuration` path value.
+ * @details Resolves the current local project config path and rewrites a leading home-directory prefix to `~` so top-level menu assertions match the documented display-only substitution without changing stored paths. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] cwd {string} Runtime working directory.
+ * @return {string} `~`-relative or absolute local config-path display string.
+ */
+function buildExpectedShowLocalConfigPath(cwd: string): string {
+  return buildExpectedDisplayPath(getProjectConfigPath(cwd));
+}
+
+/**
+ * @brief Formats the expected `Show global configuration` path value.
+ * @details Resolves the current global config path and rewrites a leading home-directory prefix to `~` so top-level menu assertions match the documented display-only substitution without changing stored paths. Runtime is O(p) in path length. No external state is mutated.
+ * @return {string} `~`-relative or absolute global config-path display string.
  */
-function buildExpectedShowConfigPath(cwd: string): string {
-  return buildExpectedNotifyBasePath(path.dirname(getProjectConfigPath(cwd))) === buildExpectedNotifyBasePath(cwd)
-    ? `${buildExpectedNotifyBasePath(cwd)}/.pi-usereq.json`
-    : getProjectConfigPath(cwd).split(path.sep).join("/");
+function buildExpectedShowGlobalConfigPath(): string {
+  return buildExpectedDisplayPath(getGlobalConfigPath());
 }
 
 /**
@@ -815,6 +839,10 @@ test("extension registers prompt and config commands while exposing tool capabil
     "tokens",
     "files-static-check",
     "static-check",
+    "debug-compress",
+    "debug-references",
+    "debug-static-check",
+    "debug-tokens",
     "pi-usereq-show-config",
     "test-static-check",
   ]) {
@@ -839,6 +867,54 @@ test("extension registers prompt and config commands while exposing tool capabil
   }
 });
 
+/**
+ * @brief Verifies debug tool wrapper commands register only when the local debug flag is enabled.
+ * @details Activates the extension once from a default-disabled fixture and once from a fixture whose local config enables debug tool wrapper commands, then asserts the four debug slash commands appear only in the enabled runtime. Runtime is dominated by fixture setup and extension registration. Side effects are limited to temporary filesystem mutation and process cwd changes.
+ * @return {void} No return value.
+ * @throws {AssertionError} Throws when command registration ignores the local debug tool wrapper flag.
+ * @satisfies TST-115
+ */
+test("debug tool commands register only when enabled in local config", () => {
+  const disabledFixture = initFixtureRepo({ fixtures: [] });
+  const enabledFixture = initFixtureRepo({ fixtures: [] });
+  const debugCommandNames = [
+    "debug-compress",
+    "debug-references",
+    "debug-static-check",
+    "debug-tokens",
+  ];
+
+  try {
+    writeProjectConfigOverrides(enabledFixture.projectBase, {
+      DEBUG_TOOL_COMMANDS_ENABLED: "enable",
+    });
+
+    const previousCwd = process.cwd();
+    try {
+      process.chdir(disabledFixture.projectBase);
+      const disabledPi = createFakePi();
+      piUsereqExtension(disabledPi);
+      const disabledCommandNames = [...disabledPi.commands.keys()];
+      for (const commandName of debugCommandNames) {
+        assert.equal(disabledCommandNames.includes(commandName), false, `unexpected command ${commandName}`);
+      }
+
+      process.chdir(enabledFixture.projectBase);
+      const enabledPi = createFakePi();
+      piUsereqExtension(enabledPi);
+      const enabledCommandNames = [...enabledPi.commands.keys()];
+      for (const commandName of debugCommandNames) {
+        assert.ok(enabledCommandNames.includes(commandName), `missing command ${commandName}`);
+      }
+    } finally {
+      process.chdir(previousCwd);
+    }
+  } finally {
+    fs.rmSync(disabledFixture.projectBase, { recursive: true, force: true });
+    fs.rmSync(enabledFixture.projectBase, { recursive: true, force: true });
+  }
+});
+
 /**
  * @brief Verifies `req-references` registration is independent from bundled prompt inventory.
  * @details Confirms `references` is absent from `PROMPT_COMMAND_NAMES` while extension activation still registers `req-references` with the fixed dedicated description. Runtime is O(1). Side effects are limited to extension registration.
@@ -1505,19 +1581,15 @@ test("static-check tools return monolithic text payloads with minimal execution
     assert.equal(staticCheckResult.details?.execution.code, 0);
     assert.deepEqual(staticCheckResult.details?.execution.stderr_lines, undefined);
 
-    fs.writeFileSync(
-      getProjectConfigPath(projectBase),
-      `${JSON.stringify({
-        ...getDefaultConfig(projectBase),
-        "docs-dir": DEFAULT_DOCS_DIR,
-        "tests-dir": "tests",
-        "src-dir": ["src"],
-        "static-check": {
-          TypeScript: createStaticCheckLanguageConfig([{ module: "Dummy" }], "disable"),
-        },
-      }, null, 2)}\n`,
-      "utf8",
-    );
+    saveFixtureConfigs(projectBase, {
+      ...getDefaultConfig(projectBase),
+      "docs-dir": DEFAULT_DOCS_DIR,
+      "tests-dir": "tests",
+      "src-dir": ["src"],
+      "static-check": {
+        TypeScript: createStaticCheckLanguageConfig([{ module: "Dummy" }], "disable"),
+      },
+    });
     const disabledFilesStaticCheckResult = await executeRegisteredTool(pi, "files-static-check", projectBase, {
       files: ["src/check.ts"],
     }) as {
@@ -1532,6 +1604,80 @@ test("static-check tools return monolithic text payloads with minimal execution
   }
 });
 
+/**
+ * @brief Verifies debug tool wrapper commands mirror tool content and reject when disabled.
+ * @details Enables debug tool wrapper commands for one fixture project, compares each debug slash-command editor payload against the matching tool `content[0].text`, then disables the flag and verifies the already-registered wrapper rejects further execution. Runtime is dominated by tool execution plus temporary git fixture setup. Side effects are limited to temporary filesystem mutation, editor-text capture, and process cwd changes.
+ * @return {Promise<void>} Promise resolved when the verification completes.
+ * @throws {AssertionError} Throws when a debug wrapper output diverges from the wrapped tool text or disabled execution is accepted.
+ * @satisfies TST-116
+ */
+test("debug tool wrapper commands mirror tool content and reject when disabled", async () => {
+  const { projectBase } = initFixtureRepo({
+    fixtures: [],
+    staticCheck: {
+      TypeScript: createStaticCheckLanguageConfig([{ module: "Dummy" }], "enable"),
+    },
+  });
+  fs.writeFileSync(path.join(projectBase, "src", "check.ts"), "export const VALUE = 1;\n", "utf8");
+  const add = spawnSync("git", ["add", "."], { cwd: projectBase, encoding: "utf8" });
+  assert.equal(add.status, 0, add.stderr);
+  const commit = spawnSync("git", ["commit", "-m", "add debug tool inputs"], { cwd: projectBase, encoding: "utf8" });
+  assert.equal(commit.status, 0, commit.stderr);
+
+  const previousCwd = process.cwd();
+  try {
+    writeProjectConfigOverrides(projectBase, {
+      DEBUG_TOOL_COMMANDS_ENABLED: "enable",
+    });
+
+    process.chdir(projectBase);
+    const pi = createFakePi();
+    piUsereqExtension(pi);
+
+    const compressToolResult = await executeRegisteredTool(pi, "compress", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+    const referencesToolResult = await executeRegisteredTool(pi, "references", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+    const staticCheckToolResult = await executeRegisteredTool(pi, "static-check", projectBase) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+    const tokensToolResult = await executeRegisteredTool(pi, "tokens", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
+
+    const compressCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-compress")!.handler("", compressCtx);
+    assert.equal(compressCtx.__state.editorText, compressToolResult.content?.[0]?.text ?? "");
+
+    const referencesCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-references")!.handler("", referencesCtx);
+    assert.equal(referencesCtx.__state.editorText, referencesToolResult.content?.[0]?.text ?? "");
+
+    const staticCheckCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-static-check")!.handler("", staticCheckCtx);
+    assert.equal(staticCheckCtx.__state.editorText, staticCheckToolResult.content?.[0]?.text ?? "");
+
+    const tokensCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-tokens")!.handler("", tokensCtx);
+    assert.equal(tokensCtx.__state.editorText, tokensToolResult.content?.[0]?.text ?? "");
+
+    writeProjectConfigOverrides(projectBase, {
+      DEBUG_TOOL_COMMANDS_ENABLED: "disable",
+    });
+    const disabledCtx = createFakeCtx(projectBase);
+    await assert.rejects(
+      async () => pi.commands.get("debug-tokens")!.handler("", disabledCtx),
+      /disabled by Debug > Enable debug commands for tools/u,
+    );
+    assert.equal(disabledCtx.__state.editorText, "");
+  } finally {
+    process.chdir(previousCwd);
+    fs.rmSync(projectBase, { recursive: true, force: true });
+  }
+});
+
 test("configuration menu saves updated docs-dir in project config", async () => {
   const cwd = createTempDir("pi-usereq-menu-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
@@ -1541,7 +1687,7 @@ test("configuration menu saves updated docs-dir in project config", async () =>
   assert.ok(command);
 
   await command!.handler("", createFakeCtx(cwd, { selects: ["docs-dir", "Save and close"], inputs: ["docs/custom"] }));
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readProjectConfigJson(cwd);
   assert.equal(config["docs-dir"], "docs/custom");
 });
 
@@ -1566,7 +1712,7 @@ test("configuration menu persists trailing-slash-free relative directory values"
 
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readProjectConfigJson(cwd);
   assert.equal(config["docs-dir"], "docs/custom");
   assert.equal(config["tests-dir"], "tests/custom");
   assert.deepEqual(config["src-dir"], ["src", "src/custom"]);
@@ -1586,12 +1732,14 @@ test("configuration menu forces worktree rows off and dim when auto git commit i
 
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const localConfig = readProjectConfigJson(cwd);
+  const globalConfig = readGlobalConfigJson();
   const defaultConfig = getDefaultConfig(cwd);
   const renderedLockedMenu = (ctx.__state.customRenderLines[1] ?? []).join("\n");
-  assert.equal(config.AUTO_GIT_COMMIT, "disable");
-  assert.equal(config.GIT_WORKTREE_ENABLED, "disable");
-  assert.equal(config.GIT_WORKTREE_PREFIX, defaultConfig.GIT_WORKTREE_PREFIX);
+  assert.equal(globalConfig.AUTO_GIT_COMMIT, "disable");
+  assert.equal(globalConfig.GIT_WORKTREE_ENABLED, "disable");
+  assert.equal(globalConfig.GIT_WORKTREE_PREFIX, defaultConfig.GIT_WORKTREE_PREFIX);
+  assert.equal(Object.hasOwn(localConfig, "AUTO_GIT_COMMIT"), false);
   assert.match(renderedLockedMenu, /<dim>Git worktree/);
   assert.match(renderedLockedMenu, /<dim>Worktree prefix/);
 });
@@ -1612,7 +1760,7 @@ test("configuration menu omits prompt-delivery controls and persisted config omi
   assert.equal(fs.existsSync(getProjectConfigPath(cwd)), false);
 });
 
-test("configuration menus expose show-config ordering and omit overview or notification-reference rows", async () => {
+test("configuration menus expose local/global config ordering and omit overview or notification-reference rows", async () => {
   const cwd = fs.mkdtempSync(
     path.join(process.env.HOME ?? process.cwd(), "pi-usereq-menu-structure-"),
   );
@@ -1638,10 +1786,18 @@ test("configuration menus expose show-config ordering and omit overview or notif
     "Enable tools",
     "Notifications",
     "Debug",
-    "Show configuration",
+    "Show local configuration",
+    "Show global configuration",
     "Reset defaults",
   ]);
-  assert.ok(renderedMenu.includes(buildExpectedShowConfigPath(cwd)));
+  assert.match(
+    renderedMenu,
+    new RegExp(`<dim>${buildExpectedShowLocalConfigPath(cwd).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}</dim>`),
+  );
+  assert.match(
+    renderedMenu,
+    new RegExp(`<dim>${buildExpectedShowGlobalConfigPath().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}</dim>`),
+  );
   assert.ok(renderedMenu.includes("notification:off • sound:none • pushover:off"));
   assert.ok(renderedMenu.includes("disable"));
   assert.doesNotMatch(renderedMenu, /beep:/);
@@ -1668,15 +1824,15 @@ test("configuration menus expose show-config ordering and omit overview or notif
   ]);
 });
 
-test("show configuration saves pending config, closes the menu, and writes the persisted project config file text into the editor", async () => {
-  const cwd = createTempDir("pi-usereq-menu-show-config-");
+test("show local configuration saves pending config, closes the menu, and writes the persisted local config file text into the editor", async () => {
+  const cwd = createTempDir("pi-usereq-menu-show-local-config-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
   const pi = createFakePi();
   piUsereqExtension(pi);
   const command = pi.commands.get("pi-usereq");
   assert.ok(command);
   const ctx = createFakeCtx(cwd, {
-    selects: ["docs-dir", "show-config"],
+    selects: ["docs-dir", "show-local-config"],
     inputs: ["docs/custom"],
   });
 
@@ -1691,6 +1847,28 @@ test("show configuration saves pending config, closes the menu, and writes the p
   );
 });
 
+test("show global configuration saves pending config, closes the menu, and writes the persisted global config file text into the editor", async () => {
+  const cwd = createTempDir("pi-usereq-menu-show-global-config-");
+  fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
+  const pi = createFakePi();
+  piUsereqExtension(pi);
+  const command = pi.commands.get("pi-usereq");
+  assert.ok(command);
+  const ctx = createFakeCtx(cwd, {
+    selects: ["Auto git commit", "show-global-config"],
+  });
+
+  await command!.handler("", ctx);
+
+  const persistedText = fs.readFileSync(getGlobalConfigPath(), "utf8");
+  assert.equal(ctx.__state.editorText, persistedText);
+  assert.match(ctx.__state.editorText, /"AUTO_GIT_COMMIT": "disable"/);
+  assert.equal(
+    ctx.__state.selectCalls.filter((call) => call.title === "pi-usereq").length,
+    2,
+  );
+});
+
 test("descendant configuration menus end with Reset defaults only", async () => {
   const cwd = createTempDir("pi-usereq-menu-terminal-rows-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
@@ -1770,6 +1948,7 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
       "Debug",
       "Debug",
       "Log file",
+      "Enable debug commands for tools",
       "Log on status",
       "any",
       "Status changes",
@@ -1785,35 +1964,43 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
   await command!.handler("", ctx);
 
   const renderedInitialDebugMenu = (ctx.__state.customRenderLines[1] ?? []).join("\n");
-  const persistedConfig = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const persistedConfig = readProjectConfigJson(cwd);
   const debugCalls = ctx.__state.selectCalls.filter((call) => call.title === "Debug");
   assert.match(renderedInitialDebugMenu, /<dim>Log file/);
+  assert.match(renderedInitialDebugMenu, /<dim>Enable debug commands for tools/);
   assert.match(renderedInitialDebugMenu, /<dim>Log on status/);
   assert.match(renderedInitialDebugMenu, /<dim>Status changes/);
   assert.match(renderedInitialDebugMenu, /<dim>Workflow events/);
   assert.match(renderedInitialDebugMenu, /<dim>compress/);
   assert.equal(persistedConfig.DEBUG_ENABLED, "enable");
   assert.equal(persistedConfig.DEBUG_LOG_FILE, "logs/debug-output.json");
+  assert.equal(persistedConfig.DEBUG_TOOL_COMMANDS_ENABLED, "enable");
   assert.equal(persistedConfig.DEBUG_STATUS_CHANGES, "enable");
   assert.equal(persistedConfig.DEBUG_WORKFLOW_EVENTS, "enable");
   assert.equal(persistedConfig.DEBUG_LOG_ON_STATUS, "any");
+  assert.ok(pi.commands.get("debug-compress"));
+  assert.ok(pi.commands.get("debug-references"));
+  assert.ok(pi.commands.get("debug-static-check"));
+  assert.ok(pi.commands.get("debug-tokens"));
   assert.deepEqual(persistedConfig.DEBUG_ENABLED_TOOLS, ["files-tokens"]);
   assert.deepEqual(persistedConfig.DEBUG_ENABLED_PROMPTS, ["req-analyze"]);
   assert.equal(debugCalls[1]?.selectedChoiceId, "debug-enabled");
   assert.equal(debugCalls[2]?.selectedChoiceId, "debug-log-file");
-  assert.equal(debugCalls[3]?.selectedChoiceId, "debug-log-on-status");
-  assert.equal(debugCalls[4]?.selectedChoiceId, "debug-status-changes");
-  assert.equal(debugCalls[5]?.selectedChoiceId, "debug-workflow-events");
-  assert.equal(debugCalls[6]?.selectedChoiceId, "debug-tool:files-tokens");
-  assert.equal(debugCalls[7]?.selectedChoiceId, "debug-prompt:req-analyze");
+  assert.equal(debugCalls[3]?.selectedChoiceId, "debug-tool-commands-enabled");
+  assert.equal(debugCalls[4]?.selectedChoiceId, "debug-log-on-status");
+  assert.equal(debugCalls[5]?.selectedChoiceId, "debug-status-changes");
+  assert.equal(debugCalls[6]?.selectedChoiceId, "debug-workflow-events");
+  assert.equal(debugCalls[7]?.selectedChoiceId, "debug-tool:files-tokens");
+  assert.equal(debugCalls[8]?.selectedChoiceId, "debug-prompt:req-analyze");
 
   const resetCtx = createFakeCtx(cwd, {
     selects: ["Debug", "Reset defaults", "Approve reset", "Save and close"],
   });
   await command!.handler("", resetCtx);
-  const resetConfig = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const resetConfig = readProjectConfigJson(cwd);
   assert.equal(resetConfig.DEBUG_ENABLED, "disable");
   assert.equal(resetConfig.DEBUG_LOG_FILE, DEFAULT_DEBUG_LOG_FILE);
+  assert.equal(resetConfig.DEBUG_TOOL_COMMANDS_ENABLED, DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED);
   assert.equal(resetConfig.DEBUG_STATUS_CHANGES, "disable");
   assert.equal(resetConfig.DEBUG_WORKFLOW_EVENTS, DEFAULT_DEBUG_WORKFLOW_EVENTS);
   assert.equal(resetConfig.DEBUG_LOG_ON_STATUS, DEFAULT_DEBUG_LOG_ON_STATUS);
@@ -1837,6 +2024,7 @@ test("debug menu rows derive from canonical tool and prompt inventories", async
   assert.deepEqual(ctx.__state.selectCalls[1]?.items ?? [], [
     "Debug",
     "Log file",
+    "Enable debug commands for tools",
     "Log on status",
     "Status changes",
     "Workflow events",
@@ -1856,17 +2044,13 @@ test("debug menu rows derive from canonical tool and prompt inventories", async
 test("tool debug logging honors global enablement and workflow-status filters", async () => {
   const idleBase = createTempDir("pi-usereq-tool-debug-idle-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(idleBase)), { recursive: true });
-  fs.writeFileSync(
-    getProjectConfigPath(idleBase),
-    `${JSON.stringify({
-      ...getDefaultConfig(idleBase),
-      DEBUG_ENABLED: "enable",
-      DEBUG_LOG_FILE: "tool-debug.json",
-      DEBUG_LOG_ON_STATUS: "any",
-      DEBUG_ENABLED_TOOLS: ["bash"],
-    }, null, 2)}\n`,
-    "utf8",
-  );
+  saveFixtureConfigs(idleBase, {
+    ...getDefaultConfig(idleBase),
+    DEBUG_ENABLED: "enable",
+    DEBUG_LOG_FILE: "tool-debug.json",
+    DEBUG_LOG_ON_STATUS: "any",
+    DEBUG_ENABLED_TOOLS: ["bash"],
+  });
   const idlePi = createFakePi();
   piUsereqExtension(idlePi);
   const idleCtx = createFakeCtx(idleBase);
@@ -1927,17 +2111,13 @@ test("tool debug logging honors global enablement and workflow-status filters",
 
   const disabledBase = createTempDir("pi-usereq-tool-debug-disabled-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(disabledBase)), { recursive: true });
-  fs.writeFileSync(
-    getProjectConfigPath(disabledBase),
-    `${JSON.stringify({
-      ...getDefaultConfig(disabledBase),
-      DEBUG_ENABLED: "disable",
-      DEBUG_LOG_FILE: "tool-debug.json",
-      DEBUG_LOG_ON_STATUS: "any",
-      DEBUG_ENABLED_TOOLS: ["bash"],
-    }, null, 2)}\n`,
-    "utf8",
-  );
+  saveFixtureConfigs(disabledBase, {
+    ...getDefaultConfig(disabledBase),
+    DEBUG_ENABLED: "disable",
+    DEBUG_LOG_FILE: "tool-debug.json",
+    DEBUG_LOG_ON_STATUS: "any",
+    DEBUG_ENABLED_TOOLS: ["bash"],
+  });
   const disabledPi = createFakePi();
   piUsereqExtension(disabledPi);
   const disabledCtx = createFakeCtx(disabledBase);
@@ -2181,11 +2361,12 @@ test("notifications reset defaults preserves non-notification settings", async (
 
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
-  assert.equal(config["docs-dir"], "docs/custom");
-  assert.equal(config["notify-enabled"], false);
-  assert.equal(config["notify-sound"], "none");
-  assert.equal(config["notify-pushover-enabled"], false);
+  const localConfig = readProjectConfigJson(cwd);
+  const globalConfig = readGlobalConfigJson();
+  assert.equal(localConfig["docs-dir"], "docs/custom");
+  assert.equal(globalConfig["notify-enabled"], false);
+  assert.equal(globalConfig["notify-sound"], "none");
+  assert.equal(globalConfig["notify-pushover-enabled"], false);
 });
 
 test("top-level reset defaults restores all configuration values", async () => {
@@ -2210,11 +2391,12 @@ test("top-level reset defaults restores all configuration values", async () => {
 
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
-  assert.equal(config["docs-dir"], DEFAULT_DOCS_DIR);
-  assert.deepEqual(config["src-dir"], ["src"]);
-  assert.equal(config["notify-enabled"], false);
-  assert.equal(config["notify-sound"], "none");
+  const localConfig = readProjectConfigJson(cwd);
+  const globalConfig = readGlobalConfigJson();
+  assert.equal(localConfig["docs-dir"], DEFAULT_DOCS_DIR);
+  assert.deepEqual(localConfig["src-dir"], ["src"]);
+  assert.equal(globalConfig["notify-enabled"], false);
+  assert.equal(globalConfig["notify-sound"], "none");
 });
 
 test("configuration menus reuse CLI settings theme semantics", async () => {
@@ -4795,17 +4977,11 @@ test("prompt commands remain functional when custom tool registrations are remov
 test("session_start applies configured pi-usereq startup tools", async () => {
   const cwd = createTempDir("pi-usereq-tools-startup-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
-  fs.writeFileSync(
-    getProjectConfigPath(cwd),
-    `${JSON.stringify({
-      "docs-dir": DEFAULT_DOCS_DIR,
-      "tests-dir": "tests",
-      "src-dir": ["src", "foobar"],
-      "static-check": {},
-      "enabled-tools": ["files-tokens", "static-check"],
-    }, null, 2)}\n`,
-    "utf8",
-  );
+  saveFixtureConfigs(cwd, {
+    ...getDefaultConfig(cwd),
+    "src-dir": ["src", "foobar"],
+    "enabled-tools": ["files-tokens", "static-check"],
+  });
 
   const pi = createFakePi();
   piUsereqExtension(pi);
@@ -4915,7 +5091,7 @@ test("stale replacement contexts do not break workflow-state rendering", () => {
   const cwd = createTempDir("pi-usereq-stale-render-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
   const controller = createPiUsereqStatusController();
-  setPiUsereqStatusConfig(controller, getDefaultConfig());
+  setPiUsereqStatusConfig(controller, getDefaultConfig(cwd));
   const staleCtx = createFakeCtx(cwd);
   Object.defineProperty(staleCtx, "ui", {
     configurable: true,
@@ -5296,7 +5472,9 @@ test("session_start enables default custom tools and default embedded tools only
 });
 
 test("default configuration applies the documented static-check, debug, notify, sound, and pushover defaults", () => {
-  const config = getDefaultConfig(createTempDir("pi-usereq-default-notify-"));
+  const cwd = createTempDir("pi-usereq-default-notify-");
+  const config = getDefaultConfig(cwd);
+  saveFixtureConfigs(cwd, config);
 
   assert.equal(config.AUTO_GIT_COMMIT, "enable");
   assert.deepEqual(Object.keys(config["static-check"]).length, 20);
@@ -5345,6 +5523,7 @@ test("default configuration applies the documented static-check, debug, notify,
   assert.deepEqual(config["static-check"].Ruby, createStaticCheckLanguageConfig([], "disable"));
   assert.equal(config.DEBUG_ENABLED, "disable");
   assert.equal(config.DEBUG_LOG_FILE, DEFAULT_DEBUG_LOG_FILE);
+  assert.equal(config.DEBUG_TOOL_COMMANDS_ENABLED, DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED);
   assert.equal(config.DEBUG_WORKFLOW_EVENTS, DEFAULT_DEBUG_WORKFLOW_EVENTS);
   assert.equal(config.DEBUG_LOG_ON_STATUS, DEFAULT_DEBUG_LOG_ON_STATUS);
   assert.deepEqual(config.DEBUG_ENABLED_TOOLS, []);
@@ -5363,6 +5542,22 @@ test("default configuration applies the documented static-check, debug, notify,
   assert.equal(config["notify-pushover-on-failed"], false);
   assert.equal(config.PI_NOTIFY_CMD, 'notify-send -i %%INSTALLATION_PATH%%/resources/images/pi.dev.png -a "PI-useReq" "%%PROMT%% @ %%BASE%% [%%TIME%%]" "%%RESULT%%"');
   assert.equal(config["notify-pushover-text"], "%%RESULT%%\n%%ARGS%%");
+
+  const localConfig = readProjectConfigJson(cwd);
+  const globalConfig = readGlobalConfigJson();
+  assert.equal((localConfig["static-check"] as Record<string, any>).Python.enabled, "enable");
+  assert.equal((localConfig["static-check"] as Record<string, any>).Ruby.enabled, "disable");
+  assert.equal(localConfig.DEBUG_TOOL_COMMANDS_ENABLED, DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED);
+  assert.deepEqual((globalConfig["static-check"] as Record<string, any>).Python.checkers, [
+    { module: "Command", cmd: "pyright", params: ["--outputjson"] },
+    { module: "Command", cmd: "ruff", params: ["check"] },
+  ]);
+  assert.deepEqual((globalConfig["static-check"] as Record<string, any>).Ruby.checkers, []);
+  assert.equal(globalConfig.AUTO_GIT_COMMIT, "enable");
+  assert.equal(globalConfig.GIT_WORKTREE_ENABLED, "enable");
+  assert.equal(globalConfig["notify-enabled"], false);
+  assert.equal(Object.hasOwn(localConfig, "notify-enabled"), false);
+  assert.equal(Object.hasOwn(localConfig, "enabled-tools"), false);
 });
 
 test("configuration menu orders tool toggles and can enable embedded builtin tools", async () => {
@@ -5378,7 +5573,7 @@ test("configuration menu orders tool toggles and can enable embedded builtin too
 
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readGlobalConfigJson();
   assert.deepEqual(ctx.__state.selectCalls[2]?.items ?? [], [
     "compress",
     "references",
@@ -5419,7 +5614,7 @@ test("configuration menu can disable configurable active tools", async () => {
     }),
   );
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readGlobalConfigJson();
   assert.deepEqual(config["enabled-tools"], []);
   assert.deepEqual(pi.getActiveTools().filter((toolName: string) => PI_USEREQ_STARTUP_TOOL_NAMES.includes(toolName as never)), []);
 });
@@ -5463,7 +5658,7 @@ test("configuration menu can persist notify and boot-sound settings without chan
   await pi.emit("session_start", { reason: "startup" }, ctx);
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readGlobalConfigJson();
   assert.equal(config["notify-enabled"], true);
   assert.equal(config["notify-on-completed"], true);
   assert.equal(config["notify-on-interrupted"], false);
@@ -5524,7 +5719,7 @@ test("configuration menu can persist pushover settings", async () => {
 
   await command!.handler("", ctx);
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readGlobalConfigJson();
   assert.equal(config["notify-pushover-enabled"], true);
   assert.equal(config["notify-pushover-on-completed"], true);
   assert.equal(config["notify-pushover-on-interrupted"], false);
@@ -5551,14 +5746,10 @@ test("configuration menu can persist pushover settings", async () => {
 test("notifications menu escapes pushover text and locks pushover enablement until credentials exist", async () => {
   const cwd = createTempDir("pi-usereq-menu-pushover-display-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
-  fs.writeFileSync(
-    getProjectConfigPath(cwd),
-    `${JSON.stringify({
-      ...getDefaultConfig(cwd),
-      "notify-pushover-text": "first line\nsecond line",
-    }, null, 2)}\n`,
-    "utf8",
-  );
+  saveFixtureConfigs(cwd, {
+    ...getDefaultConfig(cwd),
+    "notify-pushover-text": "first line\nsecond line",
+  });
   const pi = createFakePi();
   piUsereqExtension(pi);
   const command = pi.commands.get("pi-usereq");
@@ -5784,7 +5975,7 @@ test("pushover global enable controls status and suppresses delivery when disabl
   await command!.handler("", ctx);
   writeProjectConfigOverrides(cwd, { GIT_WORKTREE_ENABLED: "disable" });
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
+  const config = readGlobalConfigJson();
   assert.equal(config["notify-pushover-enabled"], false);
   assert.equal(config["notify-pushover-on-completed"], true);
   assert.equal(
@@ -6038,8 +6229,9 @@ test("sound routing honors the selected sound state and per-event toggles", asyn
 test("sound toggle shortcut cycles active runtime pi-notify sound levels without persisting boot config", async () => {
   const cwd = createTempDir("pi-usereq-shortcut-notify-");
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
-  const persistedConfigText = `${JSON.stringify(getDefaultConfig(cwd), null, 2)}\n`;
-  fs.writeFileSync(getProjectConfigPath(cwd), persistedConfigText, "utf8");
+  const persistedConfig = getDefaultConfig(cwd);
+  saveFixtureConfigs(cwd, persistedConfig);
+  const persistedGlobalConfigText = fs.readFileSync(getGlobalConfigPath(), "utf8");
   const previousCwd = process.cwd();
   const pi = createFakePi();
   process.chdir(cwd);
@@ -6056,7 +6248,7 @@ test("sound toggle shortcut cycles active runtime pi-notify sound levels without
 
   for (const expectedSound of ["low", "mid", "high", "none"]) {
     await shortcut!.handler(ctx);
-    assert.equal(fs.readFileSync(getProjectConfigPath(cwd), "utf8"), persistedConfigText);
+    assert.equal(fs.readFileSync(getGlobalConfigPath(), "utf8"), persistedGlobalConfigText);
     assert.equal(
       ctx.__state.statuses.get("pi-usereq"),
       buildExpectedFakeStatusText({
@@ -6077,11 +6269,7 @@ test("session_start loads the active runtime sound from persisted boot config",
   fs.mkdirSync(path.dirname(getProjectConfigPath(cwd)), { recursive: true });
   const persistedConfig = getDefaultConfig(cwd);
   persistedConfig["notify-sound"] = "mid";
-  fs.writeFileSync(
-    getProjectConfigPath(cwd),
-    `${JSON.stringify(persistedConfig, null, 2)}\n`,
-    "utf8",
-  );
+  saveFixtureConfigs(cwd, persistedConfig);
   const previousCwd = process.cwd();
   const pi = createFakePi();
   process.chdir(cwd);
@@ -6180,9 +6368,10 @@ test("configuration menu can toggle per-language static-check enablement", async
     }),
   );
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
-  assert.equal(config["static-check"].Python.enabled, "disable");
-  assert.deepEqual(config["static-check"].Python.checkers, [
+  const localConfig = readProjectConfigJson(cwd);
+  const globalConfig = readGlobalConfigJson();
+  assert.equal((localConfig["static-check"] as Record<string, any>).Python.enabled, "disable");
+  assert.deepEqual((globalConfig["static-check"] as Record<string, any>).Python.checkers, [
     { module: "Command", cmd: "pyright", params: ["--outputjson"] },
     { module: "Command", cmd: "ruff", params: ["check"] },
   ]);
@@ -6210,8 +6399,10 @@ test("configuration menu can add guided static-check entries for explicit suppor
     }),
   );
 
-  const config = JSON.parse(fs.readFileSync(getProjectConfigPath(cwd), "utf8"));
-  assert.deepEqual(config["static-check"].Ruby, createStaticCheckLanguageConfig([
+  const localConfig = readProjectConfigJson(cwd);
+  const globalConfig = readGlobalConfigJson();
+  assert.equal((localConfig["static-check"] as Record<string, any>).Ruby.enabled, "enable");
+  assert.deepEqual((globalConfig["static-check"] as Record<string, any>).Ruby.checkers, [
     { module: "Command", cmd: "true" },
-  ], "enable"));
+  ]);
 });