pi-usereq 0.33.0 → 0.34.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -383,11 +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-321**: MUST render `Enable debug commands for tools` in `Debug` after `Debug`, before `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`.
+- **REQ-323**: MUST register `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` only when `DEBUG_TOOL_COMMANDS_ENABLED=enable`.
+- **REQ-324**: MUST make `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` reuse the `compress`, `references`, `static-check`, `summarize`, and `tokens` runner outputs and write `content[0].text` to the editor.
+- **REQ-325**: MUST reject `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, 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.
@@ -461,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`, uses Node.js `24.15.0`, runs npm publication, and creates the GitHub Release from generated changelog text.
+- **TST-039**: MUST verify `.github/workflows/release-npm.yml` parses as YAML when `PyYAML` is available, 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.
 - **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.
@@ -500,10 +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-113**: MUST verify default local configuration persists `DEBUG_TOOL_COMMANDS_ENABLED=disable`, and the `Debug` submenu renders `Enable debug commands for tools` before `Log file`.
 - **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.
+- **TST-115**: MUST verify extension activation registers `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` only when `DEBUG_TOOL_COMMANDS_ENABLED=enable`.
+- **TST-116**: MUST verify `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` write the same `content[0].text` as `compress`, `references`, `static-check`, `summarize`, and `tokens`, and reject execution when disabled.
 
 ## 5. Observed Component Model
 

package/pi-usereq/docs/WORKFLOW.md

@@ -888,7 +888,7 @@
           - `getProjectConfigPath(...)`: resolve config file path [`src/core/config.ts`]
           - `getDefaultConfig(...)`: build default config [`src/core/config.ts`]
             - `normalizeEnabledPiUsereqTools(...)`: canonicalize startup tools [`src/core/pi-usereq-tools.ts`]
-    - `registerDebugToolCommands(...)`: register config-gated debug slash-command wrappers for `compress`, `references`, `static-check`, and `tokens` [`src/index.ts`]
+    - `registerDebugToolCommands(...)`: register config-gated debug slash-command wrappers for `compress`, `references`, `static-check`, `summarize`, and `tokens` [`src/index.ts`]
     - `registerAgentTools(...)`: register structured pi tools whose execute callbacks reuse internal runner families, the status-only references writer, token-optimized payload builders, and compact-plus-expanded custom result renderers [`src/index.ts`]
       - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources for tool executes that need bundled assets [`src/core/resources.ts`]
         - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
@@ -1193,10 +1193,10 @@
       - `buildPiUsereqToolToggleChoices(...)`: serialize per-tool startup-toggle rows plus the value-less terminal reset action [`src/index.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
     - `configureDebugMenu(...)`: interactive debug editor with in-place enable or disable toggles, tool-wrapper command registration, workflow filters, reset confirmation, and per-tool plus per-prompt selectors [`src/index.ts`]
-      - `buildDebugMenuChoices(...)`: serialize global debug controls, 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`]
+      - `buildDebugMenuChoices(...)`: serialize global debug controls with `Enable debug commands for tools` before `Log file`, workflow-event toggles, canonical tool and prompt toggles, and the value-less terminal reset row [`src/index.ts`]
         - `buildDebugMenuChoice(...)`: dim and disable locked debug rows while global debug is off [`src/index.ts`]
         - `getDebugToolToggleNames(...)`: enumerate debuggable tool names in canonical grouped order [`src/index.ts`]
-      - `registerDebugToolCommands(...)`: register debug slash-command wrappers immediately when the tool-wrapper row transitions to `enable` [`src/index.ts`]
+      - `registerDebugToolCommands(...)`: register debug slash-command wrappers including `debug-summarize` immediately when the tool-wrapper row transitions to `enable` [`src/index.ts`]
       - `selectDebugLogOnStatus(...)`: select one explicit workflow-state filter or `any` [`src/index.ts`]
       - `confirmResetChanges(...)`: require explicit approval before applying reset mutations [`src/index.ts`]
       - `resetDebugConfigToDefaults(...)`: restore the debug configuration subtree to documented defaults [`src/index.ts`]

package/src/index.ts

@@ -8,7 +8,7 @@
  * @brief Declares the extension version string.
  * @details The value is exported for external inspection and packaging metadata alignment. Access complexity is O(1).
  */
-export const VERSION = "0.33.0";
+export const VERSION = "0.34.0";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -347,8 +347,8 @@ function executeDebugToolCommand(
 }
 
 /**
- * @brief Registers config-gated debug slash-command wrappers for selected built-in analysis tools.
- * @details Registers `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` as extension commands that reuse the same runner paths as the corresponding agent tools and write the resulting monolithic text into the editor instead of the LLM content channel. Re-registering the same commands is idempotent because pi keeps the latest same-extension command definition per name. Runtime is O(1) for registration; handler cost depends on the selected runner. Side effects include command registration.
+ * @brief Registers config-gated debug slash-command wrappers for selected project analysis tools.
+ * @details Registers `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, and `debug-tokens` as extension commands that reuse the same runner paths as the corresponding agent tools and write the resulting monolithic text into the editor instead of the LLM content channel. Re-registering the same commands is idempotent because pi keeps the latest same-extension command definition per name. Runtime is O(1) for registration; handler cost depends on the selected runner. Side effects include command registration.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
  * @satisfies DES-015, REQ-323, REQ-324, REQ-325
@@ -382,6 +382,11 @@ function registerDebugToolCommands(pi: ExtensionAPI): void {
     "Run static-check and write the tool output into the editor",
     (projectBase, config) => executeMonolithicTool(() => runProjectStaticCheck(projectBase, config)),
   );
+  registerDebugToolCommand(
+    "debug-summarize",
+    "Run summarize and write the tool output into the editor",
+    (projectBase, config) => executeMonolithicTool(() => runSummarize(projectBase, config)),
+  );
   registerDebugToolCommand(
     "debug-tokens",
     "Run tokens and write the tool output into the editor",
@@ -1643,20 +1648,20 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
     },
     buildDebugMenuChoice(
       {
-        id: "debug-log-file",
-        label: "Log file",
-        value: config.DEBUG_LOG_FILE,
-        description: "Edit the JSON debug log file path. Relative paths resolve against the original project base.",
+        id: "debug-tool-commands-enabled",
+        label: "Enable debug commands for tools",
+        value: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED),
+        values: ["enable", "disable"],
+        description: "Enable or disable slash-command wrappers for `compress`, `references`, `static-check`, `summarize`, and `tokens`.",
       },
       debugEnabled,
     ),
     buildDebugMenuChoice(
       {
-        id: "debug-tool-commands-enabled",
-        label: "Enable debug commands for tools",
-        value: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED),
-        values: ["enable", "disable"],
-        description: "Enable or disable slash-command wrappers for `compress`, `references`, `static-check`, and `tokens`.",
+        id: "debug-log-file",
+        label: "Log file",
+        value: config.DEBUG_LOG_FILE,
+        description: "Edit the JSON debug log file path. Relative paths resolve against the original project base.",
       },
       debugEnabled,
     ),

package/tests/extension-registration.test.ts

@@ -842,6 +842,7 @@ test("extension registers prompt and config commands while exposing tool capabil
     "debug-compress",
     "debug-references",
     "debug-static-check",
+    "debug-summarize",
     "debug-tokens",
     "pi-usereq-show-config",
     "test-static-check",
@@ -869,7 +870,7 @@ 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.
+ * @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 five 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
@@ -881,6 +882,7 @@ test("debug tool commands register only when enabled in local config", () => {
     "debug-compress",
     "debug-references",
     "debug-static-check",
+    "debug-summarize",
     "debug-tokens",
   ];
 
@@ -1606,7 +1608,7 @@ 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.
+ * @details Enables debug tool wrapper commands for one fixture project, compares the five debug slash-command editor payloads against the matching tool `content[0].text`, then disables the flag and verifies the already-registered wrappers reject 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
@@ -1643,6 +1645,9 @@ test("debug tool wrapper commands mirror tool content and reject when disabled",
     const staticCheckToolResult = await executeRegisteredTool(pi, "static-check", projectBase) as {
       content?: Array<{ type: string; text?: string }>;
     };
+    const summarizeToolResult = await executeRegisteredTool(pi, "summarize", projectBase, {}) as {
+      content?: Array<{ type: string; text?: string }>;
+    };
     const tokensToolResult = await executeRegisteredTool(pi, "tokens", projectBase, {}) as {
       content?: Array<{ type: string; text?: string }>;
     };
@@ -1659,6 +1664,10 @@ test("debug tool wrapper commands mirror tool content and reject when disabled",
     await pi.commands.get("debug-static-check")!.handler("", staticCheckCtx);
     assert.equal(staticCheckCtx.__state.editorText, staticCheckToolResult.content?.[0]?.text ?? "");
 
+    const summarizeCtx = createFakeCtx(projectBase);
+    await pi.commands.get("debug-summarize")!.handler("", summarizeCtx);
+    assert.equal(summarizeCtx.__state.editorText, summarizeToolResult.content?.[0]?.text ?? "");
+
     const tokensCtx = createFakeCtx(projectBase);
     await pi.commands.get("debug-tokens")!.handler("", tokensCtx);
     assert.equal(tokensCtx.__state.editorText, tokensToolResult.content?.[0]?.text ?? "");
@@ -1666,12 +1675,20 @@ test("debug tool wrapper commands mirror tool content and reject when disabled",
     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, "");
+    for (const commandName of [
+      "debug-compress",
+      "debug-references",
+      "debug-static-check",
+      "debug-summarize",
+      "debug-tokens",
+    ]) {
+      const disabledCtx = createFakeCtx(projectBase);
+      await assert.rejects(
+        async () => pi.commands.get(commandName)!.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 });
@@ -1968,6 +1985,10 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
   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.ok(
+    renderedInitialDebugMenu.indexOf("<dim>Enable debug commands for tools")
+      < renderedInitialDebugMenu.indexOf("<dim>Log file"),
+  );
   assert.match(renderedInitialDebugMenu, /<dim>Log on status/);
   assert.match(renderedInitialDebugMenu, /<dim>Status changes/);
   assert.match(renderedInitialDebugMenu, /<dim>Workflow events/);
@@ -1981,6 +2002,7 @@ test("debug menu dims locked rows and persists debug settings with focus-preserv
   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-summarize"));
   assert.ok(pi.commands.get("debug-tokens"));
   assert.deepEqual(persistedConfig.DEBUG_ENABLED_TOOLS, ["files-tokens"]);
   assert.deepEqual(persistedConfig.DEBUG_ENABLED_PROMPTS, ["req-analyze"]);
@@ -2023,8 +2045,8 @@ 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 file",
     "Log on status",
     "Status changes",
     "Workflow events",

package/tests/release-workflow.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import test from "node:test";
@@ -16,6 +17,61 @@ function readReleaseWorkflow(): string {
   );
 }
 
+/**
+ * @brief Verifies the release workflow YAML parses successfully via Python.
+ * @details Resolves a project-local `.venv/bin/python` first, then falls back to `python` and `python3`, executes an inline `yaml.safe_load(...)` check against `.github/workflows/release-npm.yml`, accepts the `PyYAML not available` skip path, and fails on non-zero exit status or `YAML ERROR` output. Runtime is dominated by subprocess probing and one Python execution. Side effects are limited to subprocess creation and filesystem reads performed by the Python snippet.
+ * @return {void} No return value.
+ * @throws {AssertionError} Throws when no usable Python interpreter exists or the workflow YAML fails to parse.
+ * @satisfies TST-039
+ */
+function assertReleaseWorkflowYamlSyntax(): void {
+  const workflowPath = path.join(
+    process.cwd(),
+    ".github",
+    "workflows",
+    "release-npm.yml",
+  );
+  const pythonCandidates = [
+    path.join(process.cwd(), ".venv", "bin", "python"),
+    "python",
+    "python3",
+  ];
+  const pythonCommand = pythonCandidates.find((candidate) => {
+    if (candidate.includes(path.sep) && !fs.existsSync(candidate)) {
+      return false;
+    }
+    const probe = spawnSync(candidate, ["--version"], { encoding: "utf8" });
+    return !probe.error && probe.status === 0;
+  });
+  assert.ok(pythonCommand, "python executable not found for release workflow validation");
+
+  const pythonCode = [
+    "from pathlib import Path",
+    "import sys",
+    `p = Path(${JSON.stringify(workflowPath)})`,
+    "text = p.read_text()",
+    "try:",
+    "    import yaml",
+    "except Exception as error:",
+    "    print(f'PyYAML not available: {error}')",
+    "    sys.exit(0)",
+    "try:",
+    "    yaml.safe_load(text)",
+    "    print('YAML OK')",
+    "except Exception as error:",
+    "    print(f'YAML ERROR: {error}')",
+    "    sys.exit(1)",
+  ].join("\n");
+  const result = spawnSync(pythonCommand, ["-c", pythonCode], {
+    cwd: process.cwd(),
+    encoding: "utf8",
+  });
+  const output = `${result.stdout}${result.stderr}`;
+
+  assert.equal(result.status, 0, output || result.error?.message || "unknown python execution failure");
+  assert.doesNotMatch(output, /YAML ERROR:/u);
+}
+
 /**
  * @brief Describes the package manifest fields asserted by npm release tests.
  * @details Constrains the parsed `package.json` shape to the publication identity and provenance metadata required by the release workflow tests. The interface is compile-time only and introduces no runtime side effects.
@@ -75,6 +131,11 @@ function assertCanonicalPackageProvenanceMetadata(): void {
   assert.equal(manifest.homepage, "https://github.com/Ogekuri/PI-useReq#readme");
 }
 
+test(
+  "release workflow remains valid YAML when parsed by Python",
+  assertReleaseWorkflowYamlSyntax,
+);
+
 test(
   "release workflow keeps the current tag trigger and gates release work on origin/master ancestry",
   () => {