pi-usereq 0.37.0 → 0.39.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.70"
+date: "2026-07-09"
 author: "OpenAI Codex"
 scope:
   paths:
@@ -222,8 +222,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 +388,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.
@@ -504,6 +512,10 @@ PI-useReq is a TypeScript pi extension plus companion Node CLI and standalone ex
 - **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,12 @@
           - `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`]
+        - `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`]
         - `deliverPromptCommand(...)`: dispatch prompt replay into the current recorded session [`src/index.ts`]
           - External boundaries: `RecordingExtensionAPI.sendUserMessage(...)` records the delivered prompt payload.
         - `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 +618,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 +845,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 +871,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`]
@@ -1116,7 +1121,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 +1133,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 +1235,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,8 @@
 
 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, type UseReqConfig } from "./config.js";
+import { formatRuntimePathForDisplay, normalizeRelativeDirContract } from "./path-context.js";
 import type {
   PromptCommandExecutionPlan,
   PromptCommandName,
@@ -135,6 +135,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 +316,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 +348,10 @@ 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("");
 }

package/src/index.ts

@@ -27,6 +27,7 @@ import {
 } from "./core/agent-tool-json.js";
 import type { FindToolScope } from "./core/find-payload.js";
 import {
+  DEFAULT_CONTEXT_FILES_FLAG,
   DEFAULT_GIT_WORKTREE_PREFIX,
   DEFAULT_SRC_DIRS,
   createStaticCheckLanguageConfig,
@@ -3949,13 +3950,129 @@ async function configureStaticCheckMenu(
   }
 }
 
+/**
+ * @brief Summarizes the `Context Files` flag state for the top-level menu value column.
+ * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order so the top-level row reflects the current injection configuration. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {string} Compact `Context Files` summary string.
+ * @satisfies REQ-327
+ */
+function formatContextFilesSummary(config: UseReqConfig): string {
+  return `requirements:${config["context-files-requirements"] ? "on" : "off"} \u2022 references:${config["context-files-references"] ? "on" : "off"} \u2022 workflow:${config["context-files-workflow"] ? "on" : "off"}`;
+}
+
+/**
+ * @brief Builds the shared settings-menu choices for the `Context Files` submenu.
+ * @details Exposes one inline on|off toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order plus a value-less subtree-local `Reset defaults` row. Runtime is O(1). No external state is mutated.
+ * @param[in] config {UseReqConfig} Effective project configuration.
+ * @return {PiUsereqSettingsMenuChoice[]} Ordered `Context Files` submenu choices.
+ * @satisfies REQ-327, REQ-328, REQ-333
+ */
+function buildContextFilesMenuChoices(config: UseReqConfig): PiUsereqSettingsMenuChoice[] {
+  return [
+    {
+      id: "context-files-requirements",
+      label: "REQUIREMENTS.md",
+      value: config["context-files-requirements"] ? "on" : "off",
+      values: ["on", "off"],
+      description: "Toggle injection of REQUIREMENTS.md into the prompt context through `%%CONTEXT_FILES%%`.",
+    },
+    {
+      id: "context-files-references",
+      label: "REFERENCES.md",
+      value: config["context-files-references"] ? "on" : "off",
+      values: ["on", "off"],
+      description: "Toggle injection of REFERENCES.md into the prompt context through `%%CONTEXT_FILES%%`.",
+    },
+    {
+      id: "context-files-workflow",
+      label: "WORKFLOW.md",
+      value: config["context-files-workflow"] ? "on" : "off",
+      values: ["on", "off"],
+      description: "Toggle injection of WORKFLOW.md into the prompt context through `%%CONTEXT_FILES%%`.",
+    },
+    ...buildTerminalSettingsMenuChoices({
+      resetDefaultsDescription: "Restore the default Context Files configuration (all three files enabled).",
+    }),
+  ];
+}
+
+/**
+ * @brief Runs the `Context Files` configuration submenu.
+ * @details Loads the shared settings menu with the three context-file toggle rows, persists each inline toggle immediately through the shared change callback, restores all three flags to enabled on approved subtree reset, preserves focus on the toggled row, and returns to the top-level menu on cancel. Runtime depends on user interaction count. Side effects include config writes and UI notifications.
+ * @param[in] ctx {ExtensionCommandContext} Active command context.
+ * @param[in,out] config {UseReqConfig} Mutable effective project configuration.
+ * @param[in] onConfigChange {() => void} Shared persistence-plus-status callback.
+ * @return {Promise<void>} Promise resolved when the submenu closes.
+ * @satisfies REQ-327, REQ-328, REQ-333
+ */
+async function configureContextFilesMenu(
+  ctx: ExtensionCommandContext,
+  config: UseReqConfig,
+  onConfigChange: () => void,
+): Promise<void> {
+  const setFlag = (flagKey: "context-files-requirements" | "context-files-references" | "context-files-workflow", enabled: boolean): void => {
+    config[flagKey] = enabled;
+    onConfigChange();
+    ctx.ui.notify(`${flagKey.replace("context-files-", "").replace("-", " ")} context file ${enabled ? "enabled" : "disabled"}`, "info");
+  };
+  let focusedChoiceId: string | undefined;
+  while (true) {
+    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config), {
+      initialSelectedId: focusedChoiceId,
+      getChoices: () => buildContextFilesMenuChoices(config),
+      onChange: (choiceId, newValue) => {
+        if (choiceId === "context-files-requirements") {
+          setFlag("context-files-requirements", newValue === "on");
+          return;
+        }
+        if (choiceId === "context-files-references") {
+          setFlag("context-files-references", newValue === "on");
+          return;
+        }
+        if (choiceId === "context-files-workflow") {
+          setFlag("context-files-workflow", newValue === "on");
+        }
+      },
+    });
+    if (!choice) {
+      return;
+    }
+    focusedChoiceId = choice;
+    if (choice === "reset-defaults") {
+      const resetPreview: ResetConfirmationChange[] = [
+        { label: "REQUIREMENTS.md", previousValue: config["context-files-requirements"] ? "on" : "off", nextValue: DEFAULT_CONTEXT_FILES_FLAG ? "on" : "off" },
+        { label: "REFERENCES.md", previousValue: config["context-files-references"] ? "on" : "off", nextValue: DEFAULT_CONTEXT_FILES_FLAG ? "on" : "off" },
+        { label: "WORKFLOW.md", previousValue: config["context-files-workflow"] ? "on" : "off", nextValue: DEFAULT_CONTEXT_FILES_FLAG ? "on" : "off" },
+      ].filter((change) => change.previousValue !== change.nextValue);
+      const approved = await confirmResetChanges(
+        ctx,
+        "Confirm Context Files reset",
+        resetPreview,
+        "Approve restoring the default Context Files configuration (all three files enabled).",
+        "Abort the Context Files reset and keep the current values.",
+      );
+      if (!approved) {
+        ctx.ui.notify("Aborted Context Files reset", "info");
+        continue;
+      }
+      config["context-files-requirements"] = DEFAULT_CONTEXT_FILES_FLAG;
+      config["context-files-references"] = DEFAULT_CONTEXT_FILES_FLAG;
+      config["context-files-workflow"] = DEFAULT_CONTEXT_FILES_FLAG;
+      onConfigChange();
+      ctx.ui.notify("Restored default Context Files configuration", "info");
+      continue;
+    }
+  }
+}
+
 /**
  * @brief Builds the shared settings-menu choices for the top-level pi-usereq configuration UI.
- * @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and display-only local plus global config paths. Runtime is O(s) in source-directory count. No external state is mutated.
+ * @details Serializes primary configuration actions into right-valued menu rows consumed by the shared settings-menu renderer, including the `Context Files` injection toggles, automatic git-commit mode, effective prompt-command worktree state, notification summary, debug summary, locked worktree rows when automatic git commit is disabled, and display-only local plus global config paths. Runtime is O(s) in source-directory count. No external state is mutated.
  * @param[in] cwd {string} Current working directory.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered top-level menu choices.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-162, REQ-190, REQ-191, REQ-197, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-314, REQ-318, REQ-319, REQ-320, REQ-326
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
@@ -3985,6 +4102,12 @@ function buildPiUsereqMenuChoices(
       value: config["tests-dir"],
       description: "Edit the repository-relative directory used for project test assets and static-check selection.",
     },
+    {
+      id: "context-files",
+      label: "Context Files",
+      value: formatContextFilesSummary(config),
+      description: "Toggle injection of REQUIREMENTS.md, REFERENCES.md, and WORKFLOW.md into prompt context through `%%CONTEXT_FILES%%`.",
+    },
     {
       id: "auto-git-commit",
       label: "Auto git commit",
@@ -4113,7 +4236,7 @@ function buildSrcDirRemovalChoices(config: UseReqConfig): PiUsereqSettingsMenuCh
  * @param[in] ctx {ExtensionCommandContext} Active command context.
  * @param[in,out] statusController {PiUsereqStatusController} Mutable status controller.
  * @return {Promise<void>} Promise resolved when configuration is saved and the menu closes.
- * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-314, REQ-318, REQ-319, REQ-320
+ * @satisfies REQ-006, REQ-031, REQ-137, REQ-150, REQ-151, REQ-152, REQ-153, REQ-154, REQ-162, REQ-190, REQ-191, REQ-192, REQ-194, REQ-195, REQ-204, REQ-205, REQ-212, REQ-215, REQ-216, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-314, REQ-318, REQ-319, REQ-320, REQ-326, REQ-327, REQ-328, REQ-333
  */
 async function configurePiUsereq(
   pi: ExtensionAPI,
@@ -4193,6 +4316,10 @@ async function configurePiUsereq(
       }
       continue;
     }
+    if (choice === "context-files") {
+      await configureContextFilesMenu(ctx, config, persistConfigChange);
+      continue;
+    }
     if (choice === "auto-git-commit") {
       const nextAutoGitCommit = config.AUTO_GIT_COMMIT === "enable"
         ? "disable"
@@ -4335,6 +4462,7 @@ async function configurePiUsereq(
           { label: "Document directory", previousValue: config["docs-dir"], nextValue: defaultConfig["docs-dir"] },
           { label: "Source-code directories", previousValue: config["src-dir"].join(", "), nextValue: defaultConfig["src-dir"].join(", ") },
           { label: "Unit tests directory", previousValue: config["tests-dir"], nextValue: defaultConfig["tests-dir"] },
+          { label: "Context Files", previousValue: formatContextFilesSummary(config), nextValue: formatContextFilesSummary(defaultConfig) },
           { label: "Auto git commit", previousValue: config.AUTO_GIT_COMMIT, nextValue: defaultConfig.AUTO_GIT_COMMIT },
           { label: "Git worktree", previousValue: config.GIT_WORKTREE_ENABLED, nextValue: defaultConfig.GIT_WORKTREE_ENABLED },
           { label: "Worktree prefix", previousValue: config.GIT_WORKTREE_PREFIX, nextValue: defaultConfig.GIT_WORKTREE_PREFIX },
@@ -4395,7 +4523,7 @@ function registerConfigCommands(
  * @details Validates installation-owned bundled resources, registers the specialized `req-reset` and `req-references` commands plus bundled prompt-backed commands and agent tools, conditionally registers config-gated debug tool wrapper commands when the current project enables them, registers configuration commands, registers the configurable notification-sound shortcut when the runtime supports shortcuts, and installs shared wrappers for all supported pi lifecycle hooks so status telemetry, context usage, prompt timing, cumulative runtime, prompt-specific Pushover metadata, tool-result debug logging, and prompt-orchestration effects remain synchronized with runtime events. Runtime is O(h) in hook count during registration. Side effects include filesystem reads, command/tool/shortcut registration, UI updates, active-tool changes, optional debug-log writes, and timer scheduling.
  * @param[in] pi {ExtensionAPI} Active extension API instance.
  * @return {void} No return value.
- * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325
+ * @satisfies DES-002, DES-015, REQ-004, REQ-005, REQ-009, REQ-044, REQ-067, REQ-068, REQ-109, REQ-111, REQ-112, REQ-113, REQ-114, REQ-115, REQ-116, REQ-117, REQ-118, REQ-119, REQ-120, REQ-121, REQ-122, REQ-123, REQ-124, REQ-125, REQ-126, REQ-127, REQ-128, REQ-131, REQ-132, REQ-133, REQ-134, REQ-137, REQ-159, REQ-163, REQ-164, REQ-165, REQ-166, REQ-167, REQ-168, REQ-169, REQ-172, REQ-174, REQ-179, REQ-180, REQ-184, REQ-188, REQ-190, REQ-191, REQ-192, REQ-193, REQ-194, REQ-195, REQ-196, REQ-197, REQ-236, REQ-237, REQ-238, REQ-239, REQ-240, REQ-241, REQ-242, REQ-243, REQ-244, REQ-245, REQ-246, REQ-247, REQ-298, REQ-299, REQ-300, REQ-301, REQ-302, REQ-303, REQ-304, REQ-305, REQ-306, REQ-312, REQ-313, REQ-323, REQ-324, REQ-325, REQ-326, REQ-327
  */
 export default function piUsereqExtension(pi: ExtensionAPI): void {
   const statusController = createPiUsereqStatusController();