pi-usereq 0.69.0 → 0.71.0

package/README.md

@@ -1,4 +1,4 @@
-# PI-useReq/pi-usereq (0.69.0)
+# PI-useReq/pi-usereq (0.71.0)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -290,7 +290,7 @@ The interactive configuration menu exposes every user-facing setting; changes ar
 - **Language static code checkers** — per-language `enable`/`disable` flags and the global `Command`-module checker definitions (view/remove/reset with confirmation).
 - **Enable tools** — the subset of configurable startup tools activated for the project: the `files-*` and project tools plus the embedded pi tools (`read`, `bash`, `edit`, `write` enabled by default; `find`, `grep`, `ls` configurable and disabled by default).
 - **Notifications** — command-notify, sound, and Pushover settings with per-event routing (completed/interrupted/failed).
-- **Debug** — local debug logging: log file, log-on-status filter, status-change/workflow-event toggles, enabled tools/prompts, and `Enable debug commands for tools`.
+- **Debug** — local debug logging: global enablement, prompt-content logging (`Enable debug prompts` plus `Log path for prompts`), log file, log-on-status filter, status-change/workflow-event toggles, enabled tools/prompts, and `Enable debug commands for tools`.
 - **Show local/global configuration** — write the exact config file contents into the editor.
 - **Reset defaults** — restore the default configuration with a confirmation preview.
 - **Models** (not a setting) — the menu exposes no model management: models, custom providers, and authentication are configured at the pi client level and simply shared with pi-usereq commands at runtime.
@@ -320,6 +320,20 @@ The extension renders a status field in the pi status line showing: extension id
 - Config-gated slash commands that run the project tools and write the output into the editor: `debug-compress`, `debug-references`, `debug-static-check`, `debug-summarize`, `debug-tokens`.
 - Standalone debug harness: `scripts/pi-usereq-debug.sh` (bash wrapper) and `scripts/debug-extension.ts` with subcommands `inspect`, `session-start`, `command`, `tool`, and `sdk-smoke`.
 - Debug logging writes to the configured `DEBUG_LOG_FILE`, filtered by prompt/tool name and workflow status.
+- **Prompt content logging** — when both `Debug` and `Enable debug prompts` are enabled (the `Debug > Enable debug prompts` menu entry), the exact rendered prompt delivered to the LLM agent through `sendMessage`/`sendUserMessage` is saved under `Log path for prompts` (`DEBUG_PROMPTS_LOG_PATH`, default `/tmp/PI-useReq`). Each run writes one file named `<timestamp>-<command>` (a `YYYYMMDDHHMMSSmmm` timestamp plus the `/req-*` command used, e.g. `20261009072235123-req-implement`) whose content is byte-identical to what reached the model. Prompt logging is subordinate to the global `Debug` flag and to the `Log on status` workflow filter; nothing is written while `Debug` is disabled. Relative log paths resolve against the project root, and trailing slashes are stripped from the configured path.
+
+  Because the saved file contains exactly what pi-usereq sent, you can replicate the same send from the `pi` CLI, outside pi-usereq and without the extension installed:
+
+  ```bash
+  # Replay the exact saved prompt as a one-shot task argument
+  pi -p "$(cat /tmp/PI-useReq/20261009072235123-req-implement)"
+
+  # Feed extra material on stdin while replaying an analysis request
+  cat errors.log | pi -p "Analyze these errors and suggest how to fix them"
+
+  # Reuse a saved prompt as coding-style guidance through an appended system prompt
+  pi -p "Rewrite this function" --append-system-prompt /tmp/PI-useReq/20261009072235123-req-implement
+  ```
 
 
 ## Note on Git usage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-usereq",
-  "version": "0.69.0",
+  "version": "0.71.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ogekuri/PI-useReq.git"

package/src/core/config.ts

@@ -35,6 +35,8 @@ import {
   DEFAULT_DEBUG_ENABLED,
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
+  DEFAULT_DEBUG_PROMPTS_ENABLED,
+  DEFAULT_DEBUG_PROMPTS_LOG_PATH,
   DEFAULT_DEBUG_STATUS_CHANGES,
   DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
@@ -43,9 +45,12 @@ import {
   normalizeDebugEnabledTools,
   normalizeDebugLogFile,
   normalizeDebugLogOnStatus,
+  normalizeDebugPromptsEnabled,
+  normalizeDebugPromptsLogPath,
   normalizeDebugStatusChanges,
   normalizeDebugToolCommandsEnabled,
   normalizeDebugWorkflowEvents,
+  type DebugPromptsEnabled,
   type DebugToolCommandsEnabled,
 } from "./debug-runtime.js";
 import { normalizeEnabledPiUsereqTools } from "./pi-usereq-tools.js";
@@ -94,6 +99,8 @@ export interface UseReqConfig {
   GIT_WORKTREE_PREFIX: string;
   DEBUG_ENABLED: "enable" | "disable";
   DEBUG_LOG_FILE: string;
+  DEBUG_PROMPTS_ENABLED: DebugPromptsEnabled;
+  DEBUG_PROMPTS_LOG_PATH: string;
   DEBUG_STATUS_CHANGES: "enable" | "disable";
   DEBUG_WORKFLOW_EVENTS: "enable" | "disable";
   DEBUG_TOOL_COMMANDS_ENABLED: DebugToolCommandsEnabled;
@@ -154,6 +161,8 @@ interface UseReqLocalConfig {
   "static-check": Record<string, LocalStaticCheckLanguageConfig>;
   DEBUG_ENABLED: "enable" | "disable";
   DEBUG_LOG_FILE: string;
+  DEBUG_PROMPTS_ENABLED: DebugPromptsEnabled;
+  DEBUG_PROMPTS_LOG_PATH: string;
   DEBUG_STATUS_CHANGES: "enable" | "disable";
   DEBUG_WORKFLOW_EVENTS: "enable" | "disable";
   DEBUG_TOOL_COMMANDS_ENABLED: DebugToolCommandsEnabled;
@@ -214,14 +223,14 @@ export const DEFAULT_TESTS_DIR = "tests";
 export const DEFAULT_SRC_DIRS = ["src"];
 /**
  * @brief Defines the default value for every persisted context-file injection flag.
- * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to disabled so the bundled canonical documents are excluded from the prompt context unless the user explicitly enables one. Lookup complexity is O(1).
+ * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to enabled so the bundled canonical documents enter the prompt context on new projects unless the user explicitly disables one. Lookup complexity is O(1).
  * @satisfies REQ-328
  */
-export const DEFAULT_CONTEXT_FILES_FLAG = false;
+export const DEFAULT_CONTEXT_FILES_FLAG = true;
 
 /**
  * @brief Normalizes one persisted context-file injection flag.
- * @details Returns the documented default (`false`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection disabled. Runtime is O(1). No external state is mutated.
+ * @details Returns the documented default (`true`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection enabled. Runtime is O(1). No external state is mutated.
  * @param[in] value {unknown} Candidate persisted context-file flag.
  * @return {boolean} Normalized context-file injection flag.
  * @satisfies REQ-328
@@ -578,7 +587,7 @@ export function getGlobalConfigPath(): string {
  * @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, REQ-328
+ * @satisfies CTN-019, REQ-328, REQ-413, REQ-414
  */
 function getDefaultLocalConfig(
   globalStaticCheckConfig: Record<string, GlobalStaticCheckLanguageConfig>,
@@ -593,6 +602,8 @@ function getDefaultLocalConfig(
     "static-check": getDefaultLocalStaticCheckConfig(globalStaticCheckConfig),
     DEBUG_ENABLED: DEFAULT_DEBUG_ENABLED,
     DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
+    DEBUG_PROMPTS_ENABLED: DEFAULT_DEBUG_PROMPTS_ENABLED,
+    DEBUG_PROMPTS_LOG_PATH: DEFAULT_DEBUG_PROMPTS_LOG_PATH,
     DEBUG_STATUS_CHANGES: DEFAULT_DEBUG_STATUS_CHANGES,
     DEBUG_WORKFLOW_EVENTS: DEFAULT_DEBUG_WORKFLOW_EVENTS,
     DEBUG_TOOL_COMMANDS_ENABLED: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
@@ -645,7 +656,7 @@ function getDefaultGlobalConfig(): UseReqGlobalConfig {
  * @param[in] localConfig {UseReqLocalConfig} Persisted local configuration.
  * @param[in] globalConfig {UseReqGlobalConfig} Persisted global configuration.
  * @return {UseReqConfig} Effective merged configuration.
- * @satisfies REQ-328
+ * @satisfies REQ-328, REQ-413, REQ-414
  */
 function mergeConfigScopes(
   localConfig: UseReqLocalConfig,
@@ -682,6 +693,8 @@ function mergeConfigScopes(
     GIT_WORKTREE_PREFIX: normalizeGitWorktreePrefix(globalConfig.GIT_WORKTREE_PREFIX),
     DEBUG_ENABLED: normalizeDebugEnabled(localConfig.DEBUG_ENABLED),
     DEBUG_LOG_FILE: normalizeDebugLogFile(localConfig.DEBUG_LOG_FILE),
+    DEBUG_PROMPTS_ENABLED: normalizeDebugPromptsEnabled(localConfig.DEBUG_PROMPTS_ENABLED),
+    DEBUG_PROMPTS_LOG_PATH: normalizeDebugPromptsLogPath(localConfig.DEBUG_PROMPTS_LOG_PATH),
     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),
@@ -724,7 +737,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, 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
+ * @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, REQ-413, REQ-414
  */
 export function getDefaultConfig(_projectBase: string): UseReqConfig {
   const globalConfig = getDefaultGlobalConfig();
@@ -853,7 +866,7 @@ function normalizeGlobalStaticCheckConfig(
  * @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, REQ-328
+ * @satisfies CTN-019, REQ-328, REQ-413, REQ-414
  */
 function loadLocalConfig(
   projectBase: string,
@@ -872,6 +885,8 @@ function loadLocalConfig(
       "static-check": normalizeLocalStaticCheckConfig(undefined, defaultStaticCheckConfig),
       DEBUG_ENABLED: DEFAULT_DEBUG_ENABLED,
       DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
+      DEBUG_PROMPTS_ENABLED: DEFAULT_DEBUG_PROMPTS_ENABLED,
+      DEBUG_PROMPTS_LOG_PATH: DEFAULT_DEBUG_PROMPTS_LOG_PATH,
       DEBUG_STATUS_CHANGES: DEFAULT_DEBUG_STATUS_CHANGES,
       DEBUG_WORKFLOW_EVENTS: DEFAULT_DEBUG_WORKFLOW_EVENTS,
       DEBUG_TOOL_COMMANDS_ENABLED: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
@@ -902,6 +917,8 @@ function loadLocalConfig(
     "static-check": normalizeLocalStaticCheckConfig(data["static-check"], defaultStaticCheckConfig),
     DEBUG_ENABLED: normalizeDebugEnabled(data.DEBUG_ENABLED),
     DEBUG_LOG_FILE: normalizeDebugLogFile(data.DEBUG_LOG_FILE),
+    DEBUG_PROMPTS_ENABLED: normalizeDebugPromptsEnabled(data.DEBUG_PROMPTS_ENABLED),
+    DEBUG_PROMPTS_LOG_PATH: normalizeDebugPromptsLogPath(data.DEBUG_PROMPTS_LOG_PATH),
     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),
@@ -965,7 +982,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, 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
+ * @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, REQ-413, REQ-414
  */
 export function loadConfig(projectBase: string): UseReqConfig {
   const globalConfig = loadGlobalConfig();
@@ -981,7 +998,7 @@ export function loadConfig(projectBase: string): UseReqConfig {
  * @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, CTN-019, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277, REQ-328
+ * @satisfies CTN-012, CTN-013, CTN-019, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277, REQ-328, REQ-413, REQ-414
  */
 function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
   const normalizedSrcDir = config["src-dir"]
@@ -1007,6 +1024,8 @@ function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
     ),
     DEBUG_ENABLED: normalizeDebugEnabled(config.DEBUG_ENABLED),
     DEBUG_LOG_FILE: normalizeDebugLogFile(config.DEBUG_LOG_FILE),
+    DEBUG_PROMPTS_ENABLED: normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED),
+    DEBUG_PROMPTS_LOG_PATH: normalizeDebugPromptsLogPath(config.DEBUG_PROMPTS_LOG_PATH),
     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),

package/src/core/debug-runtime.ts

@@ -52,6 +52,20 @@ export const DEFAULT_DEBUG_WORKFLOW_EVENTS = "disable" as const;
  */
 export const DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED = "disable" as const;
 
+/**
+ * @brief Defines the default debug-prompt content logging mode.
+ * @details New configs do not save dispatched prompt content until the user explicitly enables prompt debug logging from the `Debug` submenu. Access complexity is O(1).
+ * @satisfies CTN-013, REQ-413
+ */
+export const DEFAULT_DEBUG_PROMPTS_ENABLED = "disable" as const;
+
+/**
+ * @brief Defines the default debug prompt log path.
+ * @details New configurations write dispatched prompt content files under `/tmp/PI-useReq` unless the user overrides the path; trailing separators are stripped per CTN-014. Access complexity is O(1).
+ * @satisfies CTN-013, CTN-014, REQ-414
+ */
+export const DEFAULT_DEBUG_PROMPTS_LOG_PATH = "/tmp/PI-useReq";
+
 /**
  * @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).
@@ -111,6 +125,12 @@ export type DebugWorkflowEvents = "enable" | "disable";
  */
 export type DebugToolCommandsEnabled = "enable" | "disable";
 
+/**
+ * @brief Represents one persisted debug-prompt content logging flag.
+ * @details Restricts prompt-content debug file emission to the documented `enable|disable` domain. The alias is compile-time only and introduces no runtime cost.
+ */
+export type DebugPromptsEnabled = "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.
@@ -215,6 +235,32 @@ export function normalizeDebugToolCommandsEnabled(value: unknown): DebugToolComm
   return value === "enable" ? "enable" : DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED;
 }
 
+/**
+ * @brief Normalizes one persisted debug-prompt content logging flag.
+ * @details Accepts only the documented `enable|disable` values and falls back to `DEFAULT_DEBUG_PROMPTS_ENABLED` for all other payloads. Runtime is O(1). No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted prompt-debug enable payload.
+ * @return {DebugPromptsEnabled} Canonical prompt-debug enable value.
+ * @satisfies REQ-413
+ */
+export function normalizeDebugPromptsEnabled(value: unknown): DebugPromptsEnabled {
+  return value === "enable" ? "enable" : DEFAULT_DEBUG_PROMPTS_ENABLED;
+}
+
+/**
+ * @brief Normalizes one persisted debug prompt log path value.
+ * @details Accepts only non-empty strings, trims surrounding whitespace, strips every trailing separator so persisted paths stay trailing-slash-free per CTN-014, and falls back to `DEFAULT_DEBUG_PROMPTS_LOG_PATH` when the candidate is absent or blank. Runtime is O(n) in path length. No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted prompt-log path payload.
+ * @return {string} Canonical trailing-slash-free prompt-log path value.
+ * @satisfies CTN-014, REQ-414
+ */
+export function normalizeDebugPromptsLogPath(value: unknown): string {
+  if (typeof value !== "string") {
+    return DEFAULT_DEBUG_PROMPTS_LOG_PATH;
+  }
+  const trimmedValue = value.trim().replace(/[\\/]+$/g, "");
+  return trimmedValue === "" ? DEFAULT_DEBUG_PROMPTS_LOG_PATH : trimmedValue;
+}
+
 /**
  * @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.
@@ -305,6 +351,21 @@ export function resolveDebugLogPath(projectBase: string, config: UseReqConfig):
     : path.resolve(projectBase, configuredPath);
 }
 
+/**
+ * @brief Resolves the absolute debug prompt log directory for one project base.
+ * @details Preserves absolute configured paths and otherwise resolves relative values against the original project base so prompt-worktree cleanup cannot discard accumulated prompt debug evidence. Runtime is O(p) in path length. No external state is mutated.
+ * @param[in] projectBase {string} Absolute original project base path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {string} Absolute debug prompt log directory path.
+ * @satisfies REQ-414
+ */
+export function resolveDebugPromptsLogPath(projectBase: string, config: UseReqConfig): string {
+  const configuredPath = normalizeDebugPromptsLogPath(config.DEBUG_PROMPTS_LOG_PATH);
+  return path.isAbsolute(configuredPath)
+    ? path.normalize(configuredPath)
+    : path.resolve(projectBase, configuredPath);
+}
+
 /**
  * @brief Tests whether one tool execution should be appended to the debug log.
  * @details Requires global debug enablement, membership in `DEBUG_ENABLED_TOOLS`, and a matching workflow-state filter before any filesystem work occurs. Runtime is O(n) in configured selector count. No external state is mutated.
@@ -379,6 +440,25 @@ export function shouldLogDebugPromptWorkflowEvent(
     && normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS) === "enable";
 }
 
+/**
+ * @brief Tests whether one dispatched prompt content file should be written.
+ * @details Requires global debug enablement, explicit prompt-content debug enablement, and a matching workflow-state filter before any filesystem work occurs; prompt-content logging is therefore fully subordinate to the global `Debug` flag. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] workflowState {DebugWorkflowState} Current workflow state.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @return {boolean} `true` when the prompt content file should be written.
+ * @satisfies REQ-413, REQ-416
+ */
+export function shouldLogDebugPromptContent(
+  config: UseReqConfig,
+  workflowState: DebugWorkflowState,
+  promptName: PromptCommandName,
+): boolean {
+  return normalizeDebugEnabled(config.DEBUG_ENABLED) === "enable"
+    && normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED) === "enable"
+    && matchesDebugWorkflowState(normalizeDebugLogOnStatus(config.DEBUG_LOG_ON_STATUS), workflowState);
+}
+
 /**
  * @brief Serializes arbitrary debug payloads into deterministic JSON-compatible values.
  * @details Converts `Error` instances into structured records, elides functions, stringifies bigint values, and falls back to a best-effort string when JSON serialization fails. Runtime is O(n) in payload size. No external state is mutated.
@@ -564,3 +644,69 @@ export function logDebugPromptWorkflowEvent(
     is_error: isError,
   });
 }
+
+/**
+ * @brief Formats one write-time timestamp as the `YYYYMMDDHHMMSSmmm` prompt debug prefix.
+ * @details Zero-pads calendar fields to their canonical widths, appends three millisecond digits, and joins every segment without separators so generated prompt debug filenames stay lexicographically sortable and collision-resistant within one second. Runtime is O(1). No external state is mutated.
+ * @param[in] date {Date} Write-time timestamp to encode.
+ * @return {string} `YYYYMMDDHHMMSSmmm` timestamp prefix.
+ * @satisfies REQ-417
+ */
+export function formatPromptDebugTimestamp(date: Date): string {
+  const pad = (value: number, length = 2): string => String(value).padStart(length, "0");
+  return [
+    pad(date.getFullYear(), 4),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds()),
+    pad(date.getMilliseconds(), 3),
+  ].join("");
+}
+
+/**
+ * @brief Builds one prompt debug filename for one bundled prompt.
+ * @details Combines the write-time `YYYYMMDDHHMMSSmmm` timestamp with the invokable `req-*` command name so every saved file can be replayed from the pi CLI and attributed to the originating `/req-*` prompt. Runtime is O(1). No external state is mutated.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] date {Date} Write-time timestamp. Defaults to the current wall-clock time.
+ * @return {string} Prompt debug filename in the `<timestamp>-<req-command>` shape.
+ * @satisfies REQ-417
+ */
+export function formatPromptDebugFileName(
+  promptName: PromptCommandName,
+  date = new Date(),
+): string {
+  return `${formatPromptDebugTimestamp(date)}-${getDebugPromptName(promptName)}`;
+}
+
+/**
+ * @brief Writes one dispatched prompt content file when prompt debug logging is enabled.
+ * @details Applies global-debug, prompt-debug, and workflow-state gating before creating the configured prompt log directory and writing the exact delivered prompt content into one `<timestamp>-<req-command>` file so the send can be replayed from the pi CLI without pi-usereq installed. Runtime is dominated by one directory creation plus one file write when enabled and O(1) otherwise. Side effects include directory creation and file creation only for enabled matching entries.
+ * @param[in] projectBase {string} Absolute original project base path.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @param[in] workflowState {DebugWorkflowState} Current workflow state.
+ * @param[in] promptName {PromptCommandName} Bundled prompt name.
+ * @param[in] content {string} Exact rendered prompt content delivered through `sendMessage` or `sendUserMessage`.
+ * @return {boolean} `true` when the prompt content file is written; otherwise `false`.
+ * @satisfies REQ-416, REQ-417, REQ-418
+ */
+export function logDebugPromptContent(
+  projectBase: string,
+  config: UseReqConfig,
+  workflowState: DebugWorkflowState,
+  promptName: PromptCommandName,
+  content: string,
+): boolean {
+  if (!shouldLogDebugPromptContent(config, workflowState, promptName)) {
+    return false;
+  }
+  const logDirectory = resolveDebugPromptsLogPath(projectBase, config);
+  try {
+    fs.mkdirSync(logDirectory, { recursive: true });
+    fs.writeFileSync(path.join(logDirectory, formatPromptDebugFileName(promptName)), content, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -128,9 +128,12 @@ import {
   DEBUG_WORKFLOW_STATES,
   DEFAULT_DEBUG_LOG_FILE,
   DEFAULT_DEBUG_LOG_ON_STATUS,
+  DEFAULT_DEBUG_PROMPTS_ENABLED,
+  DEFAULT_DEBUG_PROMPTS_LOG_PATH,
   DEFAULT_DEBUG_STATUS_CHANGES,
   DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED,
   DEFAULT_DEBUG_WORKFLOW_EVENTS,
+  logDebugPromptContent,
   logDebugPromptEvent,
   logDebugPromptWorkflowEvent,
   logDebugToolExecution,
@@ -138,6 +141,8 @@ import {
   normalizeDebugEnabledTools,
   normalizeDebugLogFile,
   normalizeDebugLogOnStatus,
+  normalizeDebugPromptsEnabled,
+  normalizeDebugPromptsLogPath,
   normalizeDebugStatusChanges,
   normalizeDebugToolCommandsEnabled,
   normalizeDebugWorkflowEvents,
@@ -1778,14 +1783,16 @@ function getDebugToolToggleNames(): PiUsereqStartupToolName[] {
 
 /**
  * @brief Restores the debug configuration subtree to its documented defaults.
- * @details Resets global debug enablement, log path, tool-wrapper command registration, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
+ * @details Resets global debug enablement, log path, prompt-content debug enablement plus prompt log path, tool-wrapper command registration, workflow-state filter, dedicated workflow-event logging, and selected tool plus prompt debug toggles without mutating unrelated settings. Runtime is O(1). Side effect: mutates `config`.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {void} No return value.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-195, REQ-277, REQ-322, REQ-413, REQ-414, REQ-420
  */
 function resetDebugConfigToDefaults(config: UseReqConfig): void {
   config.DEBUG_ENABLED = "disable";
   config.DEBUG_LOG_FILE = DEFAULT_DEBUG_LOG_FILE;
+  config.DEBUG_PROMPTS_ENABLED = DEFAULT_DEBUG_PROMPTS_ENABLED;
+  config.DEBUG_PROMPTS_LOG_PATH = DEFAULT_DEBUG_PROMPTS_LOG_PATH;
   config.DEBUG_STATUS_CHANGES = DEFAULT_DEBUG_STATUS_CHANGES;
   config.DEBUG_WORKFLOW_EVENTS = DEFAULT_DEBUG_WORKFLOW_EVENTS;
   config.DEBUG_TOOL_COMMANDS_ENABLED = DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED;
@@ -1870,10 +1877,10 @@ async function selectDebugLogOnStatus(
 
 /**
  * @brief Builds the shared settings-menu choices for debug logging configuration.
- * @details Serializes global debug controls plus tool-wrapper command registration, workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
+ * @details Serializes global debug controls plus prompt-content debug controls, tool-wrapper command registration, workflow-state, dedicated workflow-event, per-tool, and per-prompt toggles into one submenu, deriving inventories from the canonical tool and prompt lists and dimming locked rows while debug is disabled. Runtime is O(t + p). No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered debug-menu choices.
- * @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277, REQ-321, REQ-322
+ * @satisfies REQ-240, REQ-241, REQ-242, REQ-243, REQ-193, REQ-277, REQ-321, REQ-322, REQ-415
  */
 function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
   const debugEnabled = config.DEBUG_ENABLED === "enable";
@@ -1887,6 +1894,25 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
       values: ["enable", "disable"],
       description: "Enable or disable all debug logging behavior and unlock the remaining Debug rows.",
     },
+    buildDebugMenuChoice(
+      {
+        id: "debug-prompts-enabled",
+        label: "Enable debug prompts",
+        value: normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED),
+        values: ["enable", "disable"],
+        description: "Enable or disable saving the exact dispatched prompt content into the debug prompt log path.",
+      },
+      debugEnabled,
+    ),
+    buildDebugMenuChoice(
+      {
+        id: "debug-prompts-log-path",
+        label: "Log path for prompts",
+        value: config.DEBUG_PROMPTS_LOG_PATH,
+        description: "Edit the directory where dispatched prompt contents are saved as `<timestamp>-<req-command>` files. Relative paths resolve against the original project base.",
+      },
+      debugEnabled,
+    ),
     buildDebugMenuChoice(
       {
         id: "debug-tool-commands-enabled",
@@ -1965,12 +1991,12 @@ function buildDebugMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice
 
 /**
  * @brief Runs the interactive Debug submenu.
- * @details Lets the user toggle global debug enablement, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, and optional debug command registration.
+ * @details Lets the user toggle global debug enablement, prompt-content debug enablement plus prompt log path, tool-wrapper command registration, debug file and workflow filters, dedicated workflow-event logging, per-tool selectors, and per-prompt selectors while preserving row focus across re-renders. Runtime depends on user interaction count. Side effects include UI updates, config mutation, and optional debug command registration.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] config {UseReqConfig} Mutable configuration object.
  * @return {Promise<void>} Promise resolved when the submenu closes.
- * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277, REQ-321, REQ-322, REQ-323
+ * @satisfies REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-192, REQ-193, REQ-195, REQ-277, REQ-321, REQ-322, REQ-323, REQ-413, REQ-414, REQ-415, REQ-420
  */
 async function configureDebugMenu(
   pi: ExtensionAPI,
@@ -1999,6 +2025,12 @@ async function configureDebugMenu(
           ctx.ui.notify(`Debug ${config.DEBUG_ENABLED}`, "info");
           return;
         }
+        if (choiceId === "debug-prompts-enabled") {
+          config.DEBUG_PROMPTS_ENABLED = normalizeDebugPromptsEnabled(newValue);
+          onConfigChange();
+          ctx.ui.notify(`Debug prompts ${config.DEBUG_PROMPTS_ENABLED}`, "info");
+          return;
+        }
         if (choiceId === "debug-tool-commands-enabled") {
           updateDebugToolCommandsEnabled(newValue);
           return;
@@ -2063,6 +2095,8 @@ async function configureDebugMenu(
       const resetPreview: ResetConfirmationChange[] = [
         { label: "Debug", previousValue: config.DEBUG_ENABLED, nextValue: "disable" },
         { label: "Log file", previousValue: config.DEBUG_LOG_FILE, nextValue: DEFAULT_DEBUG_LOG_FILE },
+        { label: "Enable debug prompts", previousValue: normalizeDebugPromptsEnabled(config.DEBUG_PROMPTS_ENABLED), nextValue: DEFAULT_DEBUG_PROMPTS_ENABLED },
+        { label: "Log path for prompts", previousValue: config.DEBUG_PROMPTS_LOG_PATH, nextValue: DEFAULT_DEBUG_PROMPTS_LOG_PATH },
         { label: "Enable debug commands for tools", previousValue: normalizeDebugToolCommandsEnabled(config.DEBUG_TOOL_COMMANDS_ENABLED), nextValue: DEFAULT_DEBUG_TOOL_COMMANDS_ENABLED },
         { label: "Status changes", previousValue: normalizeDebugStatusChanges(config.DEBUG_STATUS_CHANGES), nextValue: DEFAULT_DEBUG_STATUS_CHANGES },
         { label: "Workflow events", previousValue: normalizeDebugWorkflowEvents(config.DEBUG_WORKFLOW_EVENTS), nextValue: DEFAULT_DEBUG_WORKFLOW_EVENTS },
@@ -2090,6 +2124,23 @@ async function configureDebugMenu(
       ctx.ui.notify("Debug rows are locked while Debug is disabled", "info");
       continue;
     }
+    if (choice === "debug-prompts-enabled") {
+      config.DEBUG_PROMPTS_ENABLED = normalizeDebugPromptsEnabled(
+        config.DEBUG_PROMPTS_ENABLED === "enable" ? "disable" : "enable",
+      );
+      onConfigChange();
+      ctx.ui.notify(`Debug prompts ${config.DEBUG_PROMPTS_ENABLED}`, "info");
+      continue;
+    }
+    if (choice === "debug-prompts-log-path") {
+      const value = await ctx.ui.input("Log path for prompts", config.DEBUG_PROMPTS_LOG_PATH);
+      if (value !== undefined) {
+        config.DEBUG_PROMPTS_LOG_PATH = normalizeDebugPromptsLogPath(value);
+        onConfigChange();
+        ctx.ui.notify(`Debug prompt log path set to ${config.DEBUG_PROMPTS_LOG_PATH}`, "info");
+      }
+      continue;
+    }
     if (choice === "debug-log-file") {
       const value = await ctx.ui.input("Log file", config.DEBUG_LOG_FILE);
       if (value !== undefined) {
@@ -3379,11 +3430,11 @@ function registerReqReferencesCommand(
 
 /**
  * @brief Registers bundled prompt-backed commands with the extension.
- * @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, user-message delivery during execution, and optional debug-log writes.
+ * @details Creates one prompt-template-backed `req-<prompt>` command per bundled prompt name. Each handler rejects non-`idle` workflow state by transitioning the shared workflow state to `error` before command-side preflight, otherwise transitions the shared workflow state through `checking`, `error`, and `running`, runs dedicated prompt-command git and required-doc preflight checks, optionally prepares a dedicated worktree execution plan using the active session directory, persists the prompt metadata needed for switch-triggered rebinding, switches the active session to the verified execution cwd before prompt handoff, logs dedicated workflow-activation diagnostics, renders the prompt, starts prompt delivery into the forked active session, records `running` immediately after delivery handoff begins, saves the exact delivered prompt content into the debug prompt log path when prompt debug logging is enabled, and then awaits the wrapped prompt-delivery promise whose stale post-restore rejections are suppressed. Runtime is O(p) for registration; handler cost depends on prompt preflight, worktree preparation, session switching, prompt rendering, prompt dispatch, and optional debug logging. Side effects include command registration, status-controller mutation, worktree creation, active-session replacement, optional worktree rollback, optional prompt-content debug file creation, user-message delivery during execution, and optional debug-log writes.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {void} No return value.
- * @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281, REQ-377
+ * @satisfies REQ-004, REQ-067, REQ-068, REQ-169, REQ-200, REQ-201, REQ-202, REQ-203, REQ-206, REQ-207, REQ-219, REQ-220, REQ-221, REQ-224, REQ-225, REQ-226, REQ-227, REQ-245, REQ-246, REQ-247, REQ-277, REQ-281, REQ-377, REQ-416, REQ-417, REQ-418
  */
 function registerPromptCommands(
   pi: ExtensionAPI,
@@ -3489,6 +3540,13 @@ function registerPromptCommands(
             promptName,
             "running",
           );
+          logDebugPromptContent(
+            projectBase,
+            config,
+            statusController.state.workflowState,
+            promptName,
+            content,
+          );
           await promptDelivery;
         } catch (error) {
           if (shouldIgnoreLatePromptDeliveryFailure(error, statusController.state.workflowState, executionPlan)) {