pi-usereq 0.38.0 → 0.40.0

package/pi-usereq/docs/REQUIREMENTS.md

@@ -1,8 +1,8 @@
 ---
 title: "PI-useReq Requirements"
 description: Software requirements specification
-version: "0.0.68"
-date: "2026-05-29"
+version: "0.0.71"
+date: "2026-07-10"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -89,6 +89,7 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **DES-010**: MUST centralize event-driven context snapshots, run-timing state, prompt-orchestration workflow state, and status-bar rendering through shared extension-status helpers.
 - **DES-011**: MUST implement `.github/workflows/release-npm.yml` as a two-job GitHub Actions pipeline where `check-branch` gates `build-release`, preserving changelog-driven GitHub Release creation while adding npm publication.
 - **DES-015**: MUST implement config-gated `debug-compress`, `debug-references`, `debug-static-check`, and `debug-tokens` slash-command wrappers in `src/index.ts` that reuse existing tool-runner execution paths.
+- **DES-016**: MUST deliver rendered bundled-prompt content to the LLM through `sendMessage` as a `display:false` custom message with `triggerTurn:true` and MUST NOT use `sendUserMessage` when `sendMessage` is available.
 
 ### 3.2 Functions
 - **REQ-001**: MUST access bundled prompts, git execution instructions, templates, and guidelines from `<installation-path>/resources` without requiring user-home resource copies before prompt or tool execution.
@@ -157,6 +158,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-066**: MUST omit `reset-context` and `context-reset` fields from persisted local and global configuration.
 - **REQ-067**: MUST send every bundled prompt-backed `req-<prompt>` payload into the current active session.
 - **REQ-068**: MUST use one prompt-delivery path that sends bundled prompt-backed `req-<prompt>` payloads through the forked execution session by using only the replacement-session context for post-switch session-bound operations.
+- **REQ-334**: MUST NOT display rendered prompt content on screen when delivering bundled prompt-backed `req-<prompt>` commands and MUST deliver the full rendered content only to the LLM agent.
+- **REQ-335**: MUST display a command invocation summary on screen for every bundled prompt-backed `req-<prompt>` command containing the command name, passed arguments, and active configuration.
+- **REQ-336**: MUST render the command invocation summary with the command name without the `req-` prefix in uppercase and the user request arguments.
+- **REQ-337**: MUST include `docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools` in the command invocation summary.
 - **REQ-008**: MUST provide a `Language static code checkers` submenu that adds global Command entries by guided language flow, removes configured global checker entries, toggles local per-language enablement, and resets static-check configuration.
 - **REQ-160**: MUST hardcode `Command` as the only user-configurable static-check module and omit module-selection UI from static-check configuration menus.
 - **REQ-161**: MUST hide `Dummy` from user-configurable static-check menus while preserving existing-config parsing and debug-driver support for `Dummy` entries.
@@ -222,8 +227,8 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **REQ-186**: MUST substitute `%%PROMT%%`, `%%BASE%%`, `%%TIME%%`, `%%ARGS%%`, and `%%RESULT%%` at runtime inside `Pushover title` and `Pushover text`.
 - **REQ-187**: MUST render `%%BASE%%` as static `base-path` relative to user home using `~/...` form and `%%TIME%%` as final elapsed `M:SS`.
 - **REQ-188**: MUST label notification-event rows as `Prompt completed`, `Prompt interrupted`, and `Prompt failed`.
-- **REQ-190**: MUST label top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, `Debug`, `Show local configuration`, and `Show global configuration`.
-- **REQ-191**: MUST order top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, and `Debug`.
+- **REQ-190**: MUST label top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Context Files`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, `Debug`, `Show local configuration`, and `Show global configuration`.
+- **REQ-191**: MUST order top-level rows as `Document directory`, `Source-code directories`, `Unit tests directory`, `Context Files`, `Auto git commit`, `Git worktree`, `Worktree prefix`, `Language static code checkers`, `Enable tools`, `Notifications`, and `Debug`.
 - **REQ-320**: MUST order `Show local configuration` after `Debug`, `Show global configuration` after `Show local configuration`, and `Reset defaults` last.
 - **REQ-192**: MUST preserve the selected settings-menu row after toggling or editing a setting value.
 - **REQ-193**: MUST append `Reset defaults` as a final row without right-aligned value text in every configuration menu and descendant selector menu, and MUST NOT render `Save and close`.
@@ -388,11 +393,19 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **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`.
+- **REQ-326**: MUST add a top-level `Context Files` row to the `pi-usereq` menu between `Unit tests directory` and `Auto git commit`.
+- **REQ-327**: MUST expose a `Context Files` submenu with separate enable toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` in that order.
+- **REQ-328**: MUST persist `context-files-requirements`, `context-files-references`, and `context-files-workflow` as boolean flags in local configuration, each defaulting to enabled.
+- **REQ-329**: MUST replace the `%%CONTEXT_FILES%%` prompt token with one markdown section per enabled context file in the order `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md`.
+- **REQ-330**: MUST render each `%%CONTEXT_FILES%%` section as the file-name heading, an HTML `<file name="<docs-dir>/<filename>">` reference with `%%DOC_PATH%%` pre-substituted, and the raw file content inside four-backtick `markdown` fences.
+- **REQ-331**: MUST omit the `%%CONTEXT_FILES%%` section for any disabled flag or missing context file without surfacing an error.
+- **REQ-332**: MUST inject `%%CONTEXT_FILES%%` content verbatim after every other prompt replacement so literal `%%...%%` tokens inside context files are not substituted.
+- **REQ-333**: MUST restore all three `Context Files` flags to enabled when the `Context Files` subtree `Reset defaults` is approved.
 
 ## 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.
 - **TST-002**: MUST verify installed bundled prompt, commit-instruction, template, and guideline resources remain readable from `installation-path`.
-- **TST-060**: MUST verify prompt rendering replaces `%%PROMPT%%` and expands `%%COMMIT%%` from rendered `git_commit.md` or `git_read-only.md` according to `AUTO_GIT_COMMIT`.
+- **TST-060**: MUST verify prompt rendering replaces `%%PROMPT%%` and expands `%%COMMIT%%` from rendered `git_commit.md` or `git_read-only.md` according to `AUTO_GIT_COMMIT`, excluding the verbatim `%%CONTEXT_FILES%%` block from placeholder-absence assertions.
 - **TST-003**: MUST verify standalone `files-tokens` outputs match the Python oracle, `--test-static-check` dummy or command outputs match archived fixtures, and `files-summarize`, `files-compress`, plus `files-find` preserve leading source tabs.
 - **TST-004**: MUST verify project `tokens` outputs match the Python oracle, verify `files-static-check` plus `static-check` against archived fixtures, and verify `summarize`, `compress`, plus `find` preserve leading source tabs.
 - **TST-005**: MUST verify the configuration menu saves `docs-dir` locally and `AUTO_GIT_COMMIT`, `GIT_WORKTREE_ENABLED`, plus `GIT_WORKTREE_PREFIX` globally immediately after each change.
@@ -498,12 +511,17 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **TST-065**: MUST verify default startup-tool enablement matches the documented enabled and disabled tool matrix.
 - **TST-110**: MUST verify `Enable tools` toggles, enable-all, disable-all, and reset-defaults persist only in global configuration.
 - **TST-066**: MUST verify `req-<prompt>` commands keep working when extension custom-tool registrations are removed from the runtime inventory.
+- **TST-121**: MUST verify bundled prompt-backed `req-<prompt>` commands deliver the full rendered prompt content through the fallback `sendUserMessage` channel when the runtime does not expose `sendMessage`.
 - **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 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`, `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.
+- **TST-117**: MUST verify the `pi-usereq` menu renders `Context Files` between `Unit tests directory` and `Auto git commit`.
+- **TST-118**: MUST verify the `Context Files` submenu persists the three context-file flags in local configuration with immediate-save, reset, and focus-preserving re-render behavior.
+- **TST-119**: MUST verify `%%CONTEXT_FILES%%` replacement emits one section per enabled existing file in the documented order and omits disabled or missing files.
+- **TST-120**: MUST verify `%%CONTEXT_FILES%%` sections use the file-name heading, the pre-substituted HTML file reference, and four-backtick `markdown` fences around raw content.
 
 ## 5. Observed Component Model
 

package/pi-usereq/docs/WORKFLOW.md

@@ -573,11 +573,13 @@
           - `runCapture(...)`: run git add, commit, and status subprocesses [`src/core/req-references-command.ts`]
           - `listResidualGitStatusLines(...)`: confirm no residual git-status rows remain after commit [`src/core/req-references-command.ts`]
             - `buildIgnoredGitStatusPaths(...)`: ignore extension-owned debug-log artifacts during cleanliness verification [`src/core/req-references-command.ts`]
-        - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion plus conditional pi.dev governance guidance [`src/core/prompts.ts`]
-        - `deliverPromptCommand(...)`: dispatch prompt replay into the current recorded session [`src/index.ts`]
-          - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
+        - `renderPrompt(...)`: render prompt-command payloads with bundled commit-instruction expansion, conditional pi.dev governance guidance, and `%%CONTEXT_FILES%%` context-file injection [`src/core/prompts.ts`]
+          - `buildContextFilesBlock(...)`: build the markdown block injected at `%%CONTEXT_FILES%%` from enabled context files in documented order with pre-substituted `%%DOC_PATH%%` file references and four-backtick fences [`src/core/prompts.ts`]
+        - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name, user request arguments, and active configuration fields [`src/core/prompts.ts`]
+        - `deliverPromptCommand(...)`: dispatch the rendered prompt as a hidden `display:false` custom message plus a `display:true` summary into the current recorded session, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable [`src/index.ts`]
+          - External boundaries: `RecordingExtensionAPI.sendMessage(...)` or fallback `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload plus summary.
         - `configurePiUsereq(...)`: execute the interactive configuration menu [`src/index.ts`]
-          - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including effective worktree locking plus display-only local and global config-path rows [`src/index.ts`]
+          - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including the `Context Files` injection toggle row, effective worktree locking, plus display-only local and global config-path rows [`src/index.ts`]
             - `formatLocalConfigPathForMenu(...)`: format the current local config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
             - `formatGlobalConfigPathForMenu(...)`: format the current global config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
           - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for top-level and submenu actions, keeping inline toggle rows open while rebuilding dependent rows in place [`src/core/settings-menu.ts`]
@@ -617,6 +619,9 @@
               - `resolvePiNotifyEventLabel(...)`: map one event-toggle key to the human-readable menu label [`src/index.ts`]
               - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
             - `togglePiNotifyFlag(...)`: toggle one persisted boolean notification setting [`src/index.ts`]
+          - `configureContextFilesMenu(...)`: interactive `Context Files` editor with inline `on|off` toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` plus subtree reset to all-enabled defaults [`src/index.ts`]
+            - `buildContextFilesMenuChoices(...)`: serialize the three context-file toggle rows plus the subtree reset terminal row [`src/index.ts`]
+            - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for inline context-file toggles and reset confirmation [`src/core/settings-menu.ts`]
     - `replayTool(...)`: replay a recorded tool execute handler and capture content/details [`scripts/lib/extension-debug-harness.ts`]
       - `registerExtensionOffline(...)`: rebuild the recorded extension registration surface [`scripts/lib/extension-debug-harness.ts`]
       - `RecordingCommandContext(...)`: initialize the recorded command-context UI adapter and deterministic theme-color encoding [`scripts/lib/recording-extension-api.ts`]
@@ -841,7 +846,7 @@
           - `cleanupPromptWorktreeCreation(...)`: rollback partial prompt-command worktree resources on verification or finalization failure [`src/core/prompt-command-runtime.ts`]
             - `promptWorktreeRegistered(...)`: test whether the sibling worktree remains registered [`src/core/prompt-command-runtime.ts`]
         - `createPromptExecutionSessionFile(...)`: fork the current persisted session into the worktree cwd when the origin session file already exists, or materialize an execution-session snapshot with header cwd=`worktree-path` plus the current in-memory branch when the origin session is not flushed yet [`src/core/prompt-command-runtime.ts`]
-      - `renderPrompt(...)`: render prompt template with project substitutions, bundled commit-instruction expansion, extension-owned runtime guidance, and conditional pi.dev governance guidance [`src/core/prompts.ts`]
+      - `renderPrompt(...)`: render prompt template with project substitutions, bundled commit-instruction expansion, extension-owned runtime guidance, conditional pi.dev governance guidance, and `%%CONTEXT_FILES%%` context-file injection [`src/core/prompts.ts`]
         - `readBundledPrompt(...)`: read bundled prompt template [`src/core/resources.ts`]
           - `ensureBundledResourcesAccessible(...)`: validate installation-owned bundled resources [`src/core/resources.ts`]
             - `getBundledResourceRoot(...)`: resolve installation-owned resource root [`src/core/resources.ts`]
@@ -867,6 +872,7 @@
         - `injectPiDevConformanceBlock(...)`: add conditional pi.dev governance guidance for read-only docs, interface-contract review, and pi client validation [`src/core/prompts.ts`]
           - `buildPiDevConformanceBlock(...)`: resolve manifest-gated pi.dev governance rules for read-only docs, interface contracts, and pi client validation [`src/core/prompts.ts`]
         - `adaptPromptForInternalTools(...)`: rewrite tool names for internal wrappers [`src/core/prompts.ts`]
+        - `buildContextFilesBlock(...)`: build the markdown block injected at `%%CONTEXT_FILES%%` from enabled context files in documented order with pre-substituted `%%DOC_PATH%%` file references and four-backtick fences [`src/core/prompts.ts`]
       - `activatePromptCommandExecution(...)`: switch to the verified execution session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse the persisted replacement-session context when later lifecycle hooks omit `switchSession()`, carry forward the returned replacement-session context for later session-bound work, re-align `process.cwd()` to the execution path, confirm `process.cwd()` plus the persisted execution-session file header cwd when the file is already persisted (treating a not-yet-flushed session file as a non-fatal lazy-persistence state because pi writes session files on first assistant flush), and store the verified runtime path plus reusable command-context state used by later tool execution and prompt-end handling [`src/core/prompt-command-runtime.ts`]
         - `resolvePromptCommandSwitchContext(...)`: prefer the live command context or fall back to the persisted replacement-session context keyed by the execution-session file [`src/core/prompt-command-runtime.ts`]
         - `switchPromptCommandSession(...)`: perform the session switch, tolerate the documented stale-extension-context side effect from invalidating the old closure, and let later verification prove whether the target session actually became active [`src/core/prompt-command-runtime.ts`]
@@ -874,10 +880,11 @@
         - `writePersistedPromptCommandSessionContext(...)`: store the reusable command-capable replacement-session context for later closure handling [`src/core/prompt-command-state.ts`]
         - `clearPersistedPromptCommandSessionContext(...)`: drop reusable command-context persistence when worktree routing is inactive [`src/core/prompt-command-state.ts`]
       - `logPromptWorkflowEvent(...)`: append selected workflow-activation debug entries [`src/index.ts`]
-      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt into the current active session after execution-session activation is verified, preferring replacement-session `sendUserMessage(...)` when available, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
+      - `renderPromptCommandSummary(...)`: render the on-screen command invocation summary with command name without the `req-` prefix in uppercase, user request arguments, and active configuration fields [`src/core/prompts.ts`]
+      - `deliverPromptCommand(...)`: start dispatch of the rendered prompt as a hidden `display:false` custom message with `triggerTurn:true` plus a `display:true` command invocation summary into the current active session after execution-session activation is verified, preferring replacement-session `sendMessage(...)` when available, falling back to `sendUserMessage(...)` when `sendMessage(...)` is unavailable, returning the delivery promise so the final `running` transition is recorded immediately after handoff begins instead of after the full prompt run completes, and suppressing the documented stale post-restore rejection once the prompt was already accepted [`src/index.ts`]
         - `writePersistedPromptCommandRuntimeState(...)`: mirror the prepared prompt execution plan into process-scoped persistence before the worktree session switch returns control [`src/core/prompt-command-state.ts`]
-        - `isStaleExtensionContextError(...)`: classify stale post-restore delivery rejections from replacement-session `sendUserMessage(...)` [`src/core/extension-status.ts`]
-        - External boundaries: replacement-session `sendUserMessage(...)` or fallback `pi.sendUserMessage(...)` delivers the rendered prompt payload into the active `AgentSession`.
+        - `isStaleExtensionContextError(...)`: classify stale post-restore delivery rejections from replacement-session `sendMessage(...)` [`src/core/extension-status.ts`]
+        - External boundaries: replacement-session `sendMessage(...)` or `pi.sendMessage(...)` delivers the hidden rendered prompt payload plus the displayed summary into the active `AgentSession`; fallback replacement-session `sendUserMessage(...)` or `pi.sendUserMessage(...)` delivers the rendered prompt payload when `sendMessage(...)` is unavailable.
       - `abortPromptCommandExecution(...)`: restore the original session-backed base path and delete created worktree resources when command-side preflight or prompt handoff fails [`src/core/prompt-command-runtime.ts`]
         - `restorePromptCommandExecution(...)`: switch back to the original session through replacement-session-aware `ctx.switchSession(sessionPath, { withSession })` handling, reuse the persisted replacement-session context when lifecycle hooks omit `switchSession()`, carry forward the returned replacement-session context for later session-bound work, re-align `process.cwd()` to `base-path`, confirm `process.cwd()` plus the persisted original-session file header cwd when the file is already persisted, append optional workflow-restore debug entries, clear active worktree path facts, and best-effort realign the live `ctx.cwd` mirror when worktree routing was active without failing on stale or getter-only context mirrors [`src/core/prompt-command-runtime.ts`]
           - `resolvePromptCommandSwitchContext(...)`: prefer the live command context or fall back to the persisted replacement-session context keyed by the execution-session file [`src/core/prompt-command-runtime.ts`]
@@ -1116,7 +1123,7 @@
                     - `formatPiNotifyBasePath(...)`: render `%%BASE%%` as `~`-relative when possible [`src/core/pi-notify.ts`]
                     - `formatPiNotifyDuration(...)`: render `%%TIME%%` as `M:SS` [`src/core/pi-notify.ts`]
                     - `formatPiNotifyResult(...)`: map prompt-end outcomes to `successed|aborted|failed` [`src/core/pi-notify.ts`]
-  - `configurePiUsereq(...)`: interactive configuration menu runtime root for directories, `Auto git commit`, locked-or-editable worktree rows, tools, notifications, and debug settings [`src/index.ts`]
+  - `configurePiUsereq(...)`: interactive configuration menu runtime root for directories, `Context Files` injection toggles, `Auto git commit`, locked-or-editable worktree rows, tools, notifications, and debug settings [`src/index.ts`]
     - `loadProjectConfig(...)`: load config and normalize persisted directory paths for command context [`src/index.ts`]
       - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
       - `loadConfig(...)`: load config or defaults [`src/core/config.ts`]
@@ -1128,7 +1135,7 @@
       - `resolveGitRoot(...)`: resolve repository root [`src/core/tool-runner.ts`]
         - `runCapture(...)`: run git subprocess [`src/core/tool-runner.ts`]
     - `getProjectBase(...)`: resolve project base from command context cwd [`src/index.ts`]
-    - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including effective worktree locking, notification and debug summaries, display-only local and global config-path rows, and reset-only terminal rows [`src/index.ts`]
+    - `buildPiUsereqMenuChoices(...)`: serialize top-level settings actions including the `Context Files` injection toggle row, effective worktree locking, notification and debug summaries, display-only local and global config-path rows, and reset-only terminal rows [`src/index.ts`]
       - `formatDebugMenuSummary(...)`: summarize global debug mode plus selected tool and prompt counts [`src/index.ts`]
       - `formatLocalConfigPathForMenu(...)`: format the current local config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
       - `formatGlobalConfigPathForMenu(...)`: format the current global config path with the shared `~`-relative path formatter for menu display [`src/index.ts`]
@@ -1230,6 +1237,10 @@
       - `selectPiNotifyPushoverPriority(...)`: present the `Normal|High` priority selector with the subtree-local reset action [`src/index.ts`]
         - `buildTerminalSettingsMenuChoices(...)`: append the canonical value-less `Reset defaults` row to the selector menu [`src/index.ts`]
       - `resetPiNotifyConfigToDefaults(...)`: restore notification settings to documented defaults [`src/index.ts`]
+    - `configureContextFilesMenu(...)`: interactive `Context Files` editor with inline `on|off` toggles for `REQUIREMENTS.md`, `REFERENCES.md`, and `WORKFLOW.md` plus subtree reset to all-enabled defaults [`src/index.ts`]
+      - `buildContextFilesMenuChoices(...)`: serialize the three context-file toggle rows plus the subtree reset terminal row [`src/index.ts`]
+      - `showPiUsereqSettingsMenu(...)`: render the shared settings-menu UI for inline context-file toggles and reset confirmation [`src/core/settings-menu.ts`]
+      - `confirmResetChanges(...)`: require explicit approval before applying the Context Files subtree reset [`src/index.ts`]
     - `getDefaultConfig(...)`: restore default config on reset and subtree-local selector resets [`src/core/config.ts`]
       - `normalizeEnabledPiUsereqTools(...)`: canonicalize configurable active tools [`src/core/pi-usereq-tools.ts`]
     - `applyConfiguredPiUsereqTools(...)`: re-apply active tools after reset [`src/index.ts`]

package/src/core/config.ts

@@ -84,6 +84,9 @@ export interface UseReqConfig {
   "docs-dir": string;
   "tests-dir": string;
   "src-dir": string[];
+  "context-files-requirements": boolean;
+  "context-files-references": boolean;
+  "context-files-workflow": boolean;
   "static-check": Record<string, StaticCheckLanguageConfig>;
   "enabled-tools": string[];
   AUTO_GIT_COMMIT: "enable" | "disable";
@@ -145,6 +148,9 @@ interface UseReqLocalConfig {
   "docs-dir": string;
   "tests-dir": string;
   "src-dir": string[];
+  "context-files-requirements": boolean;
+  "context-files-references": boolean;
+  "context-files-workflow": boolean;
   "static-check": Record<string, LocalStaticCheckLanguageConfig>;
   DEBUG_ENABLED: "enable" | "disable";
   DEBUG_LOG_FILE: string;
@@ -206,6 +212,23 @@ export const DEFAULT_TESTS_DIR = "tests";
  * @details The array seeds newly created configs and repairs invalid persisted source selections. Access complexity is O(1).
  */
 export const DEFAULT_SRC_DIRS = ["src"];
+/**
+ * @brief Defines the default value for every persisted context-file injection flag.
+ * @details Each `%%CONTEXT_FILES%%` injection toggle defaults to enabled so the bundled canonical documents remain part of the prompt context unless the user explicitly disables one. Lookup complexity is O(1).
+ * @satisfies REQ-328
+ */
+export const DEFAULT_CONTEXT_FILES_FLAG = true;
+
+/**
+ * @brief Normalizes one persisted context-file injection flag.
+ * @details Returns the documented default (`true`) for missing or non-boolean values and preserves only explicit boolean input, so any malformed persisted entry keeps context-file injection enabled. Runtime is O(1). No external state is mutated.
+ * @param[in] value {unknown} Candidate persisted context-file flag.
+ * @return {boolean} Normalized context-file injection flag.
+ * @satisfies REQ-328
+ */
+export function normalizeContextFilesFlag(value: unknown): boolean {
+  return typeof value === "boolean" ? value : DEFAULT_CONTEXT_FILES_FLAG;
+}
 /**
  * @brief Defines the canonical supported static-check language order used by default config serialization.
  * @details The array lists every supported user-configurable language exactly once so default config builders and config serializers can emit deterministic per-language records. Access complexity is O(1).
@@ -555,7 +578,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
+ * @satisfies CTN-019, REQ-328
  */
 function getDefaultLocalConfig(
   globalStaticCheckConfig: Record<string, GlobalStaticCheckLanguageConfig>,
@@ -564,6 +587,9 @@ function getDefaultLocalConfig(
     "docs-dir": DEFAULT_DOCS_DIR,
     "tests-dir": DEFAULT_TESTS_DIR,
     "src-dir": [...DEFAULT_SRC_DIRS],
+    "context-files-requirements": DEFAULT_CONTEXT_FILES_FLAG,
+    "context-files-references": DEFAULT_CONTEXT_FILES_FLAG,
+    "context-files-workflow": DEFAULT_CONTEXT_FILES_FLAG,
     "static-check": getDefaultLocalStaticCheckConfig(globalStaticCheckConfig),
     DEBUG_ENABLED: DEFAULT_DEBUG_ENABLED,
     DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
@@ -619,6 +645,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
  */
 function mergeConfigScopes(
   localConfig: UseReqLocalConfig,
@@ -645,6 +672,9 @@ function mergeConfigScopes(
     "docs-dir": docsDir,
     "tests-dir": testsDir,
     "src-dir": srcDir.length > 0 ? srcDir : [...DEFAULT_SRC_DIRS],
+    "context-files-requirements": localConfig["context-files-requirements"],
+    "context-files-references": localConfig["context-files-references"],
+    "context-files-workflow": localConfig["context-files-workflow"],
     "static-check": mergeStaticCheckConfig(localConfig["static-check"], globalConfig["static-check"]),
     "enabled-tools": normalizeEnabledPiUsereqTools(globalConfig["enabled-tools"]),
     AUTO_GIT_COMMIT: autoGitCommit,
@@ -823,7 +853,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
+ * @satisfies CTN-019, REQ-328
  */
 function loadLocalConfig(
   projectBase: string,
@@ -836,6 +866,9 @@ function loadLocalConfig(
       "docs-dir": DEFAULT_DOCS_DIR,
       "tests-dir": DEFAULT_TESTS_DIR,
       "src-dir": [...DEFAULT_SRC_DIRS],
+      "context-files-requirements": DEFAULT_CONTEXT_FILES_FLAG,
+      "context-files-references": DEFAULT_CONTEXT_FILES_FLAG,
+      "context-files-workflow": DEFAULT_CONTEXT_FILES_FLAG,
       "static-check": normalizeLocalStaticCheckConfig(undefined, defaultStaticCheckConfig),
       DEBUG_ENABLED: DEFAULT_DEBUG_ENABLED,
       DEBUG_LOG_FILE: DEFAULT_DEBUG_LOG_FILE,
@@ -863,6 +896,9 @@ function loadLocalConfig(
     "docs-dir": docsDirCandidate || DEFAULT_DOCS_DIR,
     "tests-dir": testsDirCandidate || DEFAULT_TESTS_DIR,
     "src-dir": srcDirCandidate.length > 0 ? srcDirCandidate : [...DEFAULT_SRC_DIRS],
+    "context-files-requirements": normalizeContextFilesFlag(data["context-files-requirements"]),
+    "context-files-references": normalizeContextFilesFlag(data["context-files-references"]),
+    "context-files-workflow": normalizeContextFilesFlag(data["context-files-workflow"]),
     "static-check": normalizeLocalStaticCheckConfig(data["static-check"], defaultStaticCheckConfig),
     DEBUG_ENABLED: normalizeDebugEnabled(data.DEBUG_ENABLED),
     DEBUG_LOG_FILE: normalizeDebugLogFile(data.DEBUG_LOG_FILE),
@@ -945,7 +981,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
+ * @satisfies CTN-012, CTN-013, CTN-019, REQ-104, REQ-146, REQ-249, REQ-316, REQ-277, REQ-328
  */
 function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
   const normalizedSrcDir = config["src-dir"]
@@ -955,6 +991,9 @@ function buildPersistedLocalConfig(config: UseReqConfig): UseReqLocalConfig {
     "docs-dir": normalizeRelativeDirContract(config["docs-dir"]) || DEFAULT_DOCS_DIR,
     "tests-dir": normalizeRelativeDirContract(config["tests-dir"]) || DEFAULT_TESTS_DIR,
     "src-dir": normalizedSrcDir.length > 0 ? normalizedSrcDir : [...DEFAULT_SRC_DIRS],
+    "context-files-requirements": normalizeContextFilesFlag(config["context-files-requirements"]),
+    "context-files-references": normalizeContextFilesFlag(config["context-files-references"]),
+    "context-files-workflow": normalizeContextFilesFlag(config["context-files-workflow"]),
     "static-check": Object.fromEntries(
       Object.entries(config["static-check"]).map(([language, languageConfig]) => [
         language,

package/src/core/prompts.ts

@@ -6,8 +6,18 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { buildPromptReplacementPaths, type UseReqConfig } from "./config.js";
-import { formatRuntimePathForDisplay } from "./path-context.js";
+import {
+  buildPromptReplacementPaths,
+  DEFAULT_DOCS_DIR,
+  DEFAULT_STATIC_CHECK_LANGUAGES,
+  resolveEffectiveGitWorktreeEnabled,
+  type UseReqConfig,
+} from "./config.js";
+import {
+  comparePiUsereqStartupToolNames,
+  type PiUsereqStartupToolName,
+} from "./pi-usereq-tools.js";
+import { formatRuntimePathForDisplay, normalizeRelativeDirContract } from "./path-context.js";
 import type {
   PromptCommandExecutionPlan,
   PromptCommandName,
@@ -135,6 +145,44 @@ function injectPiDevConformanceBlock(text: string, promptName: string, projectBa
   return text.replace(behaviorHeading, `${behaviorHeading}${block}\n`);
 }
 
+/**
+ * @brief Defines the ordered context-file injection descriptors used by `%%CONTEXT_FILES%%`.
+ * @details Each entry binds the configured flag key to its canonical document file name so the renderer can iterate the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order in one stable vector. Lookup complexity is O(1).
+ * @satisfies REQ-329
+ */
+const CONTEXT_FILE_DESCRIPTORS: ReadonlyArray<{ flagKey: "context-files-requirements" | "context-files-references" | "context-files-workflow"; fileName: string }> = [
+  { flagKey: "context-files-requirements", fileName: "REQUIREMENTS.md" },
+  { flagKey: "context-files-references", fileName: "REFERENCES.md" },
+  { flagKey: "context-files-workflow", fileName: "WORKFLOW.md" },
+];
+
+/**
+ * @brief Builds the markdown block that replaces the `%%CONTEXT_FILES%%` prompt token.
+ * @details Iterates the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order, skips disabled flags and missing files without error, and renders each remaining file as a file-name heading, an HTML `<file name="<docs-dir>/<filename>">` reference with `%%DOC_PATH%%` pre-substituted, and the raw file content inside four-backtick `markdown` fences. Runtime is O(n) in aggregate context-file size. Side effects are limited to filesystem reads.
+ * @param[in] projectBase {string} Absolute project root used to resolve the configured docs directory.
+ * @param[in] config {UseReqConfig} Effective project configuration supplying the docs directory and context-file flags.
+ * @return {string} Rendered markdown block, or the empty string when no enabled context file exists.
+ * @satisfies REQ-329, REQ-330, REQ-331, REQ-332
+ */
+function buildContextFilesBlock(projectBase: string, config: UseReqConfig): string {
+  const normalizedDocsDir = normalizeRelativeDirContract(config["docs-dir"]) || DEFAULT_DOCS_DIR;
+  const sections: string[] = [];
+  for (const { flagKey, fileName } of CONTEXT_FILE_DESCRIPTORS) {
+    if (!config[flagKey]) {
+      continue;
+    }
+    const filePath = path.join(projectBase, normalizedDocsDir, fileName);
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+      continue;
+    }
+    const content = fs.readFileSync(filePath, "utf8");
+    sections.push(
+      `### ${fileName}\n\n<file name="${normalizedDocsDir}/${fileName}">\n\`\`\`\`markdown\n${content}\n\`\`\`\``,
+    );
+  }
+  return sections.join("\n\n");
+}
+
 /**
  * @brief Rewrites bundled prompt tool references from legacy `req --...` syntax to internal tool names.
  * @details Applies deterministic global regex replacements so prompt text matches the extension-registered tool surface instead of the standalone CLI spelling. Time complexity O(p*r) where p is pattern count and r is prompt length.
@@ -278,7 +326,7 @@ function renderBundledCommitInstruction(
  * @param[in] config {UseReqConfig} Effective project configuration used for path substitutions.
  * @param[in] executionPlan {PromptCommandExecutionPlan | undefined} Optional prompt-command execution plan used for injected runtime guidance.
  * @return {string} Fully rendered prompt markdown ready for `pi.sendUserMessage(...)`.
- * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275
+ * @satisfies REQ-002, REQ-003, REQ-032, REQ-033, REQ-034, REQ-108, REQ-200, REQ-201, REQ-202, REQ-206, REQ-207, REQ-208, REQ-209, REQ-211, REQ-213, REQ-214, REQ-273, REQ-274, REQ-275, REQ-329, REQ-330, REQ-331, REQ-332
  */
 export function renderPrompt(
   promptName: string,
@@ -310,5 +358,68 @@ export function renderPrompt(
     promptName,
     projectBase,
   );
-  return adaptPromptForInternalTools(withPiDevConformance);
+  const adapted = adaptPromptForInternalTools(withPiDevConformance);
+  const contextFilesBlock = buildContextFilesBlock(projectBase, config);
+  if (contextFilesBlock) {
+    return adapted.split("%%CONTEXT_FILES%%").join(contextFilesBlock);
+  }
+  return adapted.split("%%CONTEXT_FILES%%").join("");
+}
+
+/**
+ * @brief Defines the custom-message type used for pi-usereq prompt-command screen summaries and hidden LLM prompt delivery.
+ * @details The constant is reused as the `customType` for both the `display:true` command invocation summary and the `display:false` hidden rendered prompt so the TUI renders only the summary while the full prompt reaches the LLM agent through the same custom-message channel. Access complexity is O(1).
+ * @satisfies DES-016, REQ-334
+ */
+export const PROMPT_COMMAND_SUMMARY_CUSTOM_TYPE = "pi-usereq-prompt-command";
+
+/**
+ * @brief Builds the on-screen command invocation summary for one bundled prompt-backed `req-<prompt>` command.
+ * @details Renders the command name without the `req-` prefix in uppercase, the user request arguments, and the active configuration fields (`docs-dir`, `src-dir`, `tests-dir`, enabled context files, `AUTO_GIT_COMMIT`, effective `GIT_WORKTREE_ENABLED`, `GIT_WORKTREE_PREFIX`, enabled static-check languages, and `enabled-tools`) so the TUI shows only a compact summary while the full rendered prompt is delivered hidden to the LLM agent. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @param[in] promptName {string} Bundled prompt name without the `req-` prefix.
+ * @param[in] args {string} User request arguments passed to the slash command.
+ * @param[in] config {UseReqConfig} Effective project configuration supplying directory, git, static-check, and tool fields.
+ * @return {string} Multi-line command invocation summary text.
+ * @satisfies REQ-335, REQ-336, REQ-337
+ */
+export function renderPromptCommandSummary(
+  promptName: string,
+  args: string,
+  config: UseReqConfig,
+): string {
+  const contextFiles = CONTEXT_FILE_DESCRIPTORS
+    .filter((descriptor) => config[descriptor.flagKey])
+    .map((descriptor) => descriptor.fileName.replace(/\.md$/, "").toLowerCase())
+    .join(", ");
+  const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
+    .filter((language) => config["static-check"][language]?.enabled === "enable")
+    .join(", ");
+  const enabledTools = [...config["enabled-tools"]]
+    .sort((left, right) =>
+      comparePiUsereqStartupToolNames(
+        left as PiUsereqStartupToolName,
+        right as PiUsereqStartupToolName,
+      ))
+    .join(", ");
+  const effectiveWorktree = resolveEffectiveGitWorktreeEnabled(
+    config.AUTO_GIT_COMMIT,
+    config.GIT_WORKTREE_ENABLED,
+  );
+  const lines: string[] = [
+    `Command: ${promptName.toUpperCase()}`,
+    "",
+    `User's Request: ${args}`,
+    "",
+    "Configuration:",
+    `- document dir:        ${config["docs-dir"]}`,
+    `- source-code dirs:    ${config["src-dir"].join(", ")}`,
+    `- unit tests dir:      ${config["tests-dir"]}`,
+    `- context files:       ${contextFiles}`,
+    `- auto git commit:     ${config.AUTO_GIT_COMMIT}`,
+    `- git worktree:        ${effectiveWorktree}`,
+    `- worktree prefix:     ${config.GIT_WORKTREE_PREFIX}`,
+    `- static code checks:  ${enabledLanguages}`,
+    `- enabled tools:       ${enabledTools}`,
+  ];
+  return lines.join("\n");
 }