pi-usereq 0.63.0 → 0.65.0

package/src/core/prompts.ts

@@ -17,7 +17,7 @@ import {
   comparePiUsereqStartupToolNames,
   type PiUsereqStartupToolName,
 } from "./pi-usereq-tools.js";
-import { formatContextFileSize, type ContextFileSizeFacts } from "./context-file-size.js";
+import { computeContextOccupancyFacts, formatContextFileSize, sumEnabledContextFileTokens, type ContextFileSizeFacts } from "./context-file-size.js";
 import { formatRuntimePathForDisplay, normalizeRelativeDirContract } from "./path-context.js";
 import type {
   PromptCommandExecutionPlan,
@@ -387,28 +387,35 @@ 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. When measured context-file size facts are supplied, every enabled existing context file in the `context files` field is rendered as `name(<chars>c/<tokens>t)`; without facts, or for enabled missing files, the plain `name` form is rendered. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Sections are emitted in the order `Command:`, `Configuration:` with its bullet list, then `User's Request:`, each separated by one blank line. Runtime is O(l + t log t) where l is language count and t is enabled-tool count. No external state is mutated.
+ * @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. When measured context-file size facts are supplied, every enabled existing context file in the `context files` field is rendered as `name(<chars>c/<tokens>t)`; when the enabled existing token total contributes tokens, the field additionally appends the `[<percent>% context]` occupancy suffix against the selected model max input context (or `[<percent>%/1.0M* context]` with the documented fallback); without facts, or for enabled missing files, the plain `name` form is rendered. Static-check languages are emitted in canonical `DEFAULT_STATIC_CHECK_LANGUAGES` order; enabled tools are emitted in documented menu order via `comparePiUsereqStartupToolNames`. The `context files`, `static code checks`, and `enabled tools` fields render the literal `none` placeholder whenever their respective enabled-item list is empty so the summary never shows a blank value. Sections are emitted in the order `Command:`, `Configuration:` with its bullet list, then `User's Request:`, each separated by one blank line. 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.
  * @param[in] contextFileSizes {Record<string, ContextFileSizeFacts> | undefined} Optional measured context-file size facts keyed by canonical file name, consumed for `context files` size suffixes.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens consumed by the occupancy suffix; undefined selects the documented 1,000,000-token fallback.
  * @return {string} Multi-line command invocation summary text.
- * @satisfies REQ-335, REQ-336, REQ-337, REQ-338, REQ-353, REQ-377
+ * @satisfies REQ-335, REQ-336, REQ-337, REQ-338, REQ-353, REQ-377, REQ-402, REQ-403, REQ-404, REQ-407
  */
 export function renderPromptCommandSummary(
   promptName: string,
   args: string,
   config: UseReqConfig,
   contextFileSizes?: Record<string, ContextFileSizeFacts>,
+  maxContextTokens?: number | undefined,
 ): string {
-  const contextFiles = CONTEXT_FILE_DESCRIPTORS
+  const contextSegments = CONTEXT_FILE_DESCRIPTORS
     .filter((descriptor) => config[descriptor.flagKey])
     .map((descriptor) => {
       const baseName = descriptor.fileName.replace(/\.md$/, "").toLowerCase();
       const facts = contextFileSizes?.[descriptor.fileName];
       return facts?.exists ? `${baseName}(${formatContextFileSize(facts)})` : baseName;
     })
-    .join(", ") || "none";
+    .join(", ");
+  const totalContextTokens = contextFileSizes ? sumEnabledContextFileTokens(config, contextFileSizes) : 0;
+  const contextFiles = (contextSegments || "none")
+    + (contextSegments && totalContextTokens > 0
+      ? ` ${computeContextOccupancyFacts(totalContextTokens, maxContextTokens).suffix}`
+      : "");
   const enabledLanguages = DEFAULT_STATIC_CHECK_LANGUAGES
     .filter((language) => config["static-check"][language]?.enabled === "enable")
     .join(", ") || "none";

package/src/core/token-counter.ts

@@ -196,14 +196,34 @@ function defaultJsTiktokenModuleLoader(): JsTiktokenModule {
 
 let jsTiktokenModuleLoader: () => JsTiktokenModule = defaultJsTiktokenModuleLoader;
 
+const cachedTokenCounterEncodings = new Map<string, TokenCounterEncoding>();
+
+/**
+ * @brief Resolves one shared tokenizer encoding for a `TokenCounter` construction.
+ * @details Checks the process-scoped per-encoding cache first and constructs the `js-tiktoken` encoding only on the first request per encoding name, so repeated `TokenCounter` construction across the `files-tokens` runner, canonical-doc counting, and context-file measurement reuses one parsed encoder instead of re-parsing the bundled BPE ranks each time. Runtime is O(1) after the first construction for the encoding and dominated by the single deferred `getEncoding` construction otherwise. Side effect: mutates the module-local encoding cache on first resolution per encoding name.
+ * @param[in] encodingName {string} `js-tiktoken` encoding identifier.
+ * @return {TokenCounterEncoding} Cached or newly constructed tokenizer encoding.
+ * @throws {ReqError} Propagates the deterministic unavailable-dependency failure when `js-tiktoken` cannot be loaded.
+ */
+function resolveTokenCounterEncoding(encodingName: string): TokenCounterEncoding {
+  const cachedEncoding = cachedTokenCounterEncodings.get(encodingName);
+  if (cachedEncoding) {
+    return cachedEncoding;
+  }
+  const encoding = loadJsTiktokenModule().getEncoding(encodingName);
+  cachedTokenCounterEncodings.set(encodingName, encoding);
+  return encoding;
+}
+
 /**
  * @brief Overrides the `js-tiktoken` loader for tests.
- * @details Enables deterministic dependency-failure tests without mutating repository dependencies on disk. Runtime is O(1). Side effects are limited to module-local test state.
+ * @details Enables deterministic dependency-failure tests without mutating repository dependencies on disk. Clears the process-scoped encoding cache so every loader swap observes fresh module behavior instead of encoders constructed by the previous loader. Runtime is O(e) in cached encoding count. Side effects are limited to module-local test state and cache reset.
  * @param[in] loader {(() => JsTiktokenModule) | undefined} Replacement loader, or `undefined` to restore the default loader.
  * @return {void} No return value.
  */
 export function setJsTiktokenModuleLoaderForTests(loader?: () => JsTiktokenModule): void {
   jsTiktokenModuleLoader = loader ?? defaultJsTiktokenModuleLoader;
+  cachedTokenCounterEncodings.clear();
 }
 
 /**
@@ -233,23 +253,23 @@ function loadJsTiktokenModule(): JsTiktokenModule {
 
 /**
  * @brief Encapsulates one tokenizer instance for repeated token counting.
- * @details Caches a `js-tiktoken` encoding object so multiple documents can be counted without repeated encoding lookup. Counting cost is O(n) in content length. The class mutates only instance state during construction.
+ * @details Resolves the process-scoped shared encoder for the requested encoding so multiple documents and multiple counter instances are counted without repeated encoding construction; the first construction per encoding name parses the BPE ranks once and every later `TokenCounter` reuses it through the module-local cache. Counting cost is O(n) in content length. The class mutates only instance state during construction.
  */
 export class TokenCounter {
   /**
    * @brief Stores the tokenizer implementation used for subsequent counts.
-   * @details The field holds the encoder returned by `getEncoding`. Access complexity is O(1). The value is initialized once per instance.
+   * @details Holds the cached encoder resolved through the per-encoding process cache. Access complexity is O(1); construction is O(1) after the first resolution for the encoding name.
    */
   private encoding: TokenCounterEncoding;
 
   /**
    * @brief Initializes a token counter for one encoding family.
-   * @details Resolves the named tokenizer once and reuses it across `countTokens` calls. Construction complexity is O(1) relative to caller-controlled input size. Side effects are limited to instance initialization.
+   * @details Resolves the shared cached tokenizer for the encoding name, constructing the underlying `js-tiktoken` encoding at most once per encoding name per process so repeated constructions from token tools and context-file measurement are constant-time cache hits. Side effects are limited to instance initialization plus the optional first-time encoding cache mutation.
    * @param[in] encodingName {string} `js-tiktoken` encoding identifier. Defaults to `cl100k_base`.
    * @return {TokenCounter} New token counter instance.
    */
   constructor(encodingName = TOKEN_COUNTER_ENCODING) {
-    this.encoding = loadJsTiktokenModule().getEncoding(encodingName);
+    this.encoding = resolveTokenCounterEncoding(encodingName);
   }
 
   /**
@@ -427,7 +447,7 @@ function buildCountFileMetricsResult(filePath: string, content: string, counter:
 
 /**
  * @brief Counts tokens, characters, bytes, and lines for one in-memory content string.
- * @details Instantiates a `TokenCounter`, tokenizes the supplied text, and pairs the result with raw character length, UTF-8 byte size, and logical line count. Runtime is O(n). No filesystem I/O occurs.
+ * @details Resolves the process-cached shared `TokenCounter` encoder for the encoding, tokenizes the supplied text once, and pairs the result with raw character length, UTF-8 byte size, and logical line count. Runtime is O(n) after the one-time per-encoding encoder construction. No filesystem I/O occurs.
  * @param[in] content {string} Text payload to measure.
  * @param[in] encodingName {string} Tokenizer identifier. Defaults to `cl100k_base`.
  * @return {{ tokens: number; chars: number; bytes: number; lines: number }} Aggregate metrics for the supplied content.

package/src/index.ts

@@ -84,8 +84,10 @@ import {
   type PiUsereqStartupToolName,
 } from "./core/pi-usereq-tools.js";
 import {
+  computeContextOccupancyFacts,
   formatContextFileSize,
   measureContextFileSizes,
+  sumEnabledContextFileTokens,
   type ContextFileName,
   type ContextFileSizeFacts,
 } from "./core/context-file-size.js";
@@ -160,6 +162,7 @@ import {
   getPiUsereqRuntimeSoundLevel,
   isStaleExtensionContextError,
   renderPiUsereqStatus,
+  resolveModelContextWindowTokens,
   setPiUsereqRuntimeSoundLevel,
   setPiUsereqStatusConfig,
   setPiUsereqWorkflowState,
@@ -3397,6 +3400,7 @@ function registerPromptCommands(
         });
         const projectBase = getProjectBase(commandCwd);
         const config = loadProjectConfig(commandCwd);
+        const maxContextTokens = resolveModelContextWindowTokens(statusController.state.contextUsage);
         transitionPromptWorkflowState(
           statusController,
           ctx,
@@ -3427,6 +3431,7 @@ function registerPromptCommands(
             },
             originalModel,
             originalThinkingLevel,
+            maxContextTokens,
           );
           const content = renderPrompt(
             promptName,
@@ -3470,6 +3475,7 @@ function registerPromptCommands(
             args,
             config,
             measureContextFileSizes(projectBase, config),
+            maxContextTokens,
           );
           const promptDelivery = deliverPromptCommand(pi, content, commandSummary, promptContext);
           transitionPromptWorkflowState(
@@ -4545,44 +4551,56 @@ async function configureStaticCheckMenu(
 }
 
 /**
- * @brief Summarizes the `Context Files` flag state with measured sizes for the top-level menu value column.
- * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order, appending `(<chars>c/<tokens>t)` measured size facts to every enabled segment so the top-level row exposes a runtime estimate of the injected context payload while disabled segments stay plain `name:off`. Runtime is O(1) in segment count. No external state is mutated.
+ * @brief Summarizes the `Context Files` flag state with measured sizes and context occupancy for the top-level menu value column.
+ * @details Renders the three context-file flags as compact `name:on|off` segments in the documented order, appending `(<chars>c/<tokens>t)` measured size facts to every enabled segment, then appends the occupancy suffix computed from the enabled existing token total against the selected model max input context (`[<percent>% context]`, or `[<percent>%/1.0M* context]` with the documented fallback) whenever that total contributes tokens, while disabled segments stay plain `name:off`. Runtime is O(1) in segment count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] sizes {Record<ContextFileName, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
- * @return {string} Compact `Context Files` summary string.
- * @satisfies REQ-327, REQ-376
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens; undefined selects the documented 1,000,000-token fallback.
+ * @return {string} Compact `Context Files` summary string with the occupancy suffix.
+ * @satisfies REQ-327, REQ-376, REQ-402, REQ-403, REQ-404, REQ-405
  */
 function formatContextFilesSummary(
   config: UseReqConfig,
   sizes: Record<ContextFileName, ContextFileSizeFacts>,
+  maxContextTokens?: number | undefined,
 ): string {
   const segments = [
     `requirements:${config["context-files-requirements"] ? `on(${formatContextFileSize(sizes["REQUIREMENTS.md"])})` : "off"}`,
     `references:${config["context-files-references"] ? `on(${formatContextFileSize(sizes["REFERENCES.md"])})` : "off"}`,
     `workflow:${config["context-files-workflow"] ? `on(${formatContextFileSize(sizes["WORKFLOW.md"])})` : "off"}`,
   ];
-  return segments.join(" \u2022 ");
+  const summary = segments.join(" \u2022 ");
+  const totalTokens = sumEnabledContextFileTokens(config, sizes);
+  return totalTokens > 0
+    ? `${summary} ${computeContextOccupancyFacts(totalTokens, maxContextTokens).suffix}`
+    : summary;
 }
 
 /**
  * @brief Builds the shared settings-menu choices for the `Context Files` submenu.
- * @details Exposes one inline toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order whose value renders `on|off • <chars>c/<tokens>t` measured size facts plus a value-less subtree-local `Reset defaults` row. Cycle values embed the same measured facts so inline toggling keeps the size estimate visible while persisting the on|off state. Runtime is O(1) in row count. No external state is mutated.
+ * @details Exposes one inline toggle row per context file in the documented `REQUIREMENTS.md`, `REFERENCES.md`, `WORKFLOW.md` order whose value renders `on|off • <chars>c/<tokens>t` measured size facts plus the context-occupancy suffix computed from the enabled existing token total against the selected model max input context, followed by a value-less subtree-local `Reset defaults` row. Cycle values embed the same measured facts and occupancy suffix so inline toggling keeps the size estimate visible while persisting the on|off state. Runtime is O(1) in row count. No external state is mutated.
  * @param[in] config {UseReqConfig} Effective project configuration.
  * @param[in] sizes {Record<ContextFileName, ContextFileSizeFacts>} Measured context-file size facts keyed by canonical file name.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens; undefined selects the documented 1,000,000-token fallback.
  * @return {PiUsereqSettingsMenuChoice[]} Ordered `Context Files` submenu choices.
- * @satisfies REQ-327, REQ-328, REQ-333, REQ-375
+ * @satisfies REQ-327, REQ-328, REQ-333, REQ-375, REQ-403, REQ-404, REQ-406
  */
 function buildContextFilesMenuChoices(
   config: UseReqConfig,
   sizes: Record<ContextFileName, ContextFileSizeFacts>,
+  maxContextTokens?: number | undefined,
 ): PiUsereqSettingsMenuChoice[] {
+  const totalTokens = sumEnabledContextFileTokens(config, sizes);
+  const occupancySuffix = totalTokens > 0
+    ? ` ${computeContextOccupancyFacts(totalTokens, maxContextTokens).suffix}`
+    : "";
   const buildRow = (
     id: "context-files-requirements" | "context-files-references" | "context-files-workflow",
     fileName: ContextFileName,
     description: string,
   ): PiUsereqSettingsMenuChoice => {
-    const sizedOn = `on \u2022 ${formatContextFileSize(sizes[fileName])}`;
-    const sizedOff = `off \u2022 ${formatContextFileSize(sizes[fileName])}`;
+    const sizedOn = `on \u2022 ${formatContextFileSize(sizes[fileName])}${occupancySuffix}`;
+    const sizedOff = `off \u2022 ${formatContextFileSize(sizes[fileName])}${occupancySuffix}`;
     return {
       id,
       label: fileName,
@@ -4619,13 +4637,15 @@ function buildContextFilesMenuChoices(
  * @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.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens used by the submenu occupancy suffix; undefined selects the documented 1,000,000-token fallback.
  * @return {Promise<void>} Promise resolved when the submenu closes.
- * @satisfies REQ-327, REQ-328, REQ-333
+ * @satisfies REQ-327, REQ-328, REQ-333, REQ-406
  */
 async function configureContextFilesMenu(
   ctx: ExtensionCommandContext,
   config: UseReqConfig,
   onConfigChange: () => void,
+  maxContextTokens?: number | undefined,
 ): Promise<void> {
   const contextFileSizes = measureContextFileSizes(getProjectBase(ctx.cwd), config);
   const setFlag = (flagKey: "context-files-requirements" | "context-files-references" | "context-files-workflow", enabled: boolean): void => {
@@ -4635,9 +4655,9 @@ async function configureContextFilesMenu(
   };
   let focusedChoiceId: string | undefined;
   while (true) {
-    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config, contextFileSizes), {
+    const choice = await showPiUsereqSettingsMenu(ctx, "Context Files", buildContextFilesMenuChoices(config, contextFileSizes, maxContextTokens), {
       initialSelectedId: focusedChoiceId,
-      getChoices: () => buildContextFilesMenuChoices(config, contextFileSizes),
+      getChoices: () => buildContextFilesMenuChoices(config, contextFileSizes, maxContextTokens),
       onChange: (choiceId, newValue) => {
         if (choiceId === "context-files-requirements") {
           setFlag("context-files-requirements", newValue.startsWith("on"));
@@ -4688,12 +4708,14 @@ async function configureContextFilesMenu(
  * @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.
+ * @param[in] maxContextTokens {number | undefined} Selected model max input context tokens used by the `Context Files` occupancy suffix; undefined selects the documented 1,000,000-token fallback.
  * @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, REQ-326, REQ-376
+ * @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, REQ-376, REQ-405
  */
 function buildPiUsereqMenuChoices(
   cwd: string,
   config: UseReqConfig,
+  maxContextTokens?: number | undefined,
 ): PiUsereqSettingsMenuChoice[] {
   const autoGitCommitDisabled = config.AUTO_GIT_COMMIT === "disable";
   const effectiveGitWorktreeEnabled = resolveEffectiveGitWorktreeEnabled(
@@ -4722,7 +4744,7 @@ function buildPiUsereqMenuChoices(
     {
       id: "context-files",
       label: "Context Files",
-      value: formatContextFilesSummary(config, measureContextFileSizes(cwd, config)),
+      value: formatContextFilesSummary(config, measureContextFileSizes(cwd, config), maxContextTokens),
       description: "Toggle injection of REQUIREMENTS.md, REFERENCES.md, and WORKFLOW.md into prompt context through `%%CONTEXT_FILES%%`.",
     },
     {
@@ -4865,6 +4887,7 @@ async function configurePiUsereq(
   });
   let config = loadProjectConfig(ctx.cwd);
   const projectBase = getProjectBase(ctx.cwd);
+  const maxContextTokens = resolveModelContextWindowTokens(statusController.state.contextUsage);
   const initialShortcut = config["notify-sound-toggle-shortcut"];
   const persistConfigChange = () => {
     Object.assign(config, normalizeConfigPaths(projectBase, config));
@@ -4878,10 +4901,10 @@ async function configurePiUsereq(
     const choice = await showPiUsereqSettingsMenu(
       ctx,
       "pi-usereq",
-      buildPiUsereqMenuChoices(ctx.cwd, config),
+      buildPiUsereqMenuChoices(ctx.cwd, config, maxContextTokens),
       {
         initialSelectedId: focusedChoiceId,
-        getChoices: () => buildPiUsereqMenuChoices(ctx.cwd, config),
+        getChoices: () => buildPiUsereqMenuChoices(ctx.cwd, config, maxContextTokens),
         onChange: (choiceId, newValue) => {
           if (choiceId === "auto-git-commit") {
             config.AUTO_GIT_COMMIT = newValue === "enable" ? "enable" : "disable";
@@ -4934,7 +4957,7 @@ async function configurePiUsereq(
       continue;
     }
     if (choice === "context-files") {
-      await configureContextFilesMenu(ctx, config, persistConfigChange);
+      await configureContextFilesMenu(ctx, config, persistConfigChange, maxContextTokens);
       continue;
     }
     if (choice === "auto-git-commit") {
@@ -5079,7 +5102,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, measureContextFileSizes(ctx.cwd, config)), nextValue: formatContextFilesSummary(defaultConfig, measureContextFileSizes(ctx.cwd, defaultConfig)) },
+          { label: "Context Files", previousValue: formatContextFilesSummary(config, measureContextFileSizes(ctx.cwd, config), maxContextTokens), nextValue: formatContextFilesSummary(defaultConfig, measureContextFileSizes(ctx.cwd, defaultConfig), maxContextTokens) },
           { 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 },

package/src/resources/pi-prompts-version.txt

@@ -0,0 +1 @@
+v0.8.0

package/src/resources/prompts/analyze.md

@@ -102,7 +102,7 @@ Use for: string/pattern searches inside code bodies, cross-file references, conf
 ## Execution Protocol (Global vs Local)
 You must manage the execution flow using two distinct methods:
 -  **Global Roadmap** (*check-list*): 
-   - You MUST maintain a *check-list* internally with `2` Steps (one item per Step).
+   - You MUST maintain a *check-list* internally with `3` Steps (one item per Step).
    - **Do NOT** use the *task-list tool* for this high-level roadmap.
 -  **Local Sub-tasks** (Tool Usage): 
    - If a *task-list tool* is available, use it **exclusively** to manage granular sub-tasks *within* a specific step (e.g., in Step X: "1. Edit file A", "2. Edit file B"; or in Step Y: "1. Fix test K", "2. Fix test L").
@@ -123,13 +123,22 @@ During the execution flow you MUST follow these directives:
 
 
 ## Steps
-Create internally a *check-list* for the **Global Roadmap** including all the numbered steps below: `1..2`, and start following the roadmap at the same time, executing the instructions of Step 1. If a tool call is required in Step 1, invoke it immediately; otherwise proceed to Step 1 without additional commentary. Do not add extra intent-adjustment checks unless explicitly listed in the Steps section.
+Create internally a *check-list* for the **Global Roadmap** including all the numbered steps below: `1..3`, and start following the roadmap at the same time, executing the instructions of Step 1. If a tool call is required in Step 1, invoke it immediately; otherwise proceed to Step 1 without additional commentary. Do not add extra intent-adjustment checks unless explicitly listed in the Steps section.
 1. Analyze the [User Request](#users-request)
    - Using [User Request](#users-request) as a unified semantic framework, extract all directly and tangentially related information from `%%DOC_PATH%%/REQUIREMENTS.md`, `%%DOC_PATH%%/WORKFLOW.md` and `%%DOC_PATH%%/REFERENCES.md`, prioritizing high recall to capture every borderline connection across both sources, to identify the most likely related files and functions based on explicit evidence, and treat any uncertain links as candidates without claiming completeness, then analyze the involved source code from %%SRC_PATHS%% to answer the [User Request](#users-request), ensuring compliance with %%GUIDELINES_FILES%% documents if present.
    - Do NOT create or modify tests in this workflow. If you cite tests as evidence, treat them as read-only artifacts.
    - Read %%GUIDELINES_FILES%% files and ensure any suggested follow-up changes would conform to those **guidelines**. Do not check unrelated **guidelines**.
-2. Present results
+2. Generate the follow-up prompt text from the analysis outcome
+   - Using the Step 1 analysis outcome, classify the result against `%%DOC_PATH%%/REQUIREMENTS.md` into exactly one branch:
+      - IF the analysis identified an implementation behavior that conflicts with requirements (the source code must change while `%%DOC_PATH%%/REQUIREMENTS.md` stays unchanged), GENERATE the exact prompt text to pass to the LLM Agent with the `/req-fix` command, including the defect summary, the affected requirement IDs, and concrete evidence (file paths with line numbers).
+      - ELSE IF the analysis identified changes needed to BOTH the source code and `%%DOC_PATH%%/REQUIREMENTS.md`, GENERATE the exact prompt text to pass to the LLM Agent with the `/req-change` command, including the requested change description, the affected requirement IDs, and concrete evidence (file paths with line numbers).
+      - ELSE IF the analysis identified source-code modifications with the intent of improving or adjusting the sources (internals, structure, maintainability, or performance) while `%%DOC_PATH%%/REQUIREMENTS.md` stays unchanged and NO implementation behavior conflicting with requirements was identified, GENERATE the exact prompt text to pass to the LLM Agent with the `/req-refactor` command, including the improvement objective, the affected source paths/symbols, the requirement IDs constraining the behavior to preserve, and concrete evidence (file paths with line numbers).
+      - ELSE (no source-code or requirements modifications are required), do NOT generate any follow-up prompt text.
+   - Each generated follow-up prompt text (`/req-fix`, `/req-change`, or `/req-refactor`) MUST be printed ONLY when the analysis identified its corresponding trigger in the classification above, and MUST NOT be printed in any other case; when generated, carry it into Step 3 for printing under the `## **Next Workflow**` report section.
+   - Do NOT execute the generated follow-up prompt and do NOT apply any fix or repository modification in this workflow; this workflow remains read-only.
+3. Present results
    - PRINT, in the response, the final analysis report for a human reader using clear, easily understandable sentences and readable Markdown formatting that highlight key findings, file paths, and concise evidence. Use the fixed report schema: ## **Outcome**, ## **Requirement Delta**, ## **Design Delta**, ## **Implementation Delta**, ## **Verification Delta**, ## **Evidence**, ## **Assumptions**, ## **Next Workflow**. Final line MUST be exactly: STATUS: OK or STATUS: ERROR.
+   - Include the Step 2 generated follow-up prompt text under `## **Next Workflow**` ONLY when Step 2 generated it; omit the follow-up prompt text entirely in all other cases.
 
 <h2 id="users-request">User's Request</h2>
 %%ARGS%%

package/src/resources/prompts/readme.md

@@ -39,7 +39,7 @@ In scope: static analysis of user-visible behavior from %%SRC_PATHS%% and relate
 - Write root `README.md` in English.
 - Do not perform unrelated edits.
 - Analyze user-visible implementation changes, including new features, CLI parameters/options, GUI interactions, distributed APIs, and configuration-file schema updates when present.
-- Validate whether the current root `README.md` is aligned with implementation evidence; identify exact sections to update first, then update only missing, outdated, or incorrect user-facing content in those sections.
+- Validate the current root `README.md` exhaustively against implementation evidence: enumerate every section, validate each sentence, and record a per-sentence conformance outcome before editing; then update only missing, outdated, or incorrect user-facing content.
 - Parse [User Request](#users-request) (`%%ARGS%%`) as explicit additional-edit directives, using the same anchor-based reference model used by `write.md`, and execute those directives in the same scoped README update pass.
 - Keep non-analysis documentary sections unchanged, including document headers, versioning metadata, context/scope descriptions, personal motivations, related projects, and high-level conceptual or graphical descriptions that do not alter interface usage.
 - Preserve existing README structure and formatting patterns (section order, heading hierarchy, bullet/list style, table style) whenever possible.
@@ -136,9 +136,12 @@ Create internally a *check-list* for the **Global Roadmap** including all the nu
    - Use repository evidence only; for each finding, collect file paths and line ranges.
    - Derive a compact "README coverage list" of user-visible behavior that MUST appear in root `README.md`.
 2. Validate and update root `README.md`
-   - Read the current root `README.md` and compare it with the README coverage list from Step 1.
-   - Identify and list the exact `README.md` sections impacted by the detected user-visible implementation changes and explicit additional edits from [User Request](#users-request) before editing.
+   - Read the current root `README.md` and enumerate ALL its sections and headings in document order to fix the complete validation surface.
+   - Validate `README.md` sentence by sentence, section by section, in document order: for every sentence, verify its content against repository implementation evidence and record exactly one outcome: `CONFORMING`, `OUTDATED`, or `UNSUPPORTED`.
+   - Classify non-analysis documentary sections (headers, versioning, motivations, related projects, high-level graphics) as `NOT-ANALYZED-BY-DESIGN` instead of sentence-level validation; never skip any other part or section.
+   - Identify and list the exact `README.md` sections impacted by the detected user-visible implementation changes, the recorded validation outcomes, and explicit additional edits from [User Request](#users-request) before editing.
    - Update only the identified sections so `README.md` reflects the current externally visible behavior and usage flows.
+   - Completeness gate: do NOT proceed to Step 3 until every enumerated section and every sentence has a recorded outcome and every `OUTDATED` or `UNSUPPORTED` sentence in analysis sections is corrected or removed.
    - Keep all non-analysis documentary sections unchanged (e.g., headers, versioning, context/scope narratives, motivations, related projects, high-level graphics/descriptions not tied to interface behavior).
    - Keep content focused on user interaction, setup, commands, interfaces, and observable outputs.
    - Do NOT add internal implementation details, internal architecture, private symbol names, or algorithm internals.